Initial Commit
This commit is contained in:
159
openspec/changes/enterprise-gaming-crafting/proposal.md
Normal file
159
openspec/changes/enterprise-gaming-crafting/proposal.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# OpenSpec Change: enterprise-gaming-crafting
|
||||
|
||||
- **Change ID**: enterprise-gaming-crafting
|
||||
- **Package**: `@suaveplan/crafting`
|
||||
- **Category**: gaming/narrative
|
||||
- **Target path**: `gaming/narrative/crafting`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/crafting.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/crafting` on the genesis branch from scratch at enterprise quality. The package provides recipe-based crafting with stations, material requirements, quality tiers, and crafting queues. A `RecipeRegistry` holds typed `RecipeDefinition` objects; `CraftingStation` manages a per-station craft queue with concurrent slot limits and duration timers; `QualityCalculator` computes output quality from input material quality and skill level. Genesis adds Zod recipe schemas, structured errors, OTel craft counter, injectable clock, and 100% coverage.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis yet — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `CraftingError`; `CRAFT.*` codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `Clock`, `IdGenerator` |
|
||||
| `@suaveplan/events` (`workspace:^`) | `craft:started`, `craft:complete`, `craft:failed` events |
|
||||
| `zod` (`catalog:forms`) | `RecipeDefinition` schema |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Craft completion counter |
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
```ts
|
||||
type QualityTier = 'poor' | 'normal' | 'fine' | 'superior' | 'masterwork'
|
||||
|
||||
interface Ingredient {
|
||||
itemId: string
|
||||
quantity: number
|
||||
qualityMin?: QualityTier
|
||||
}
|
||||
|
||||
interface RecipeDefinition {
|
||||
id: string
|
||||
name: string
|
||||
stationType: string
|
||||
ingredients: Ingredient[]
|
||||
outputItemId: string
|
||||
outputQuantity: number
|
||||
craftTime: number // seconds
|
||||
skillRequired?: number // 0–100
|
||||
outputQualityBase?: QualityTier
|
||||
}
|
||||
|
||||
function createRecipeRegistry(): RecipeRegistry
|
||||
interface RecipeRegistry {
|
||||
register(recipe: RecipeDefinition): void
|
||||
get(id: string): RecipeDefinition | undefined
|
||||
listByStation(stationType: string): RecipeDefinition[]
|
||||
}
|
||||
|
||||
function createCraftingStation(options: StationOptions): CraftingStation
|
||||
|
||||
interface StationOptions {
|
||||
type: string
|
||||
maxSlots?: number // concurrent crafts, default 1
|
||||
clock?: Clock
|
||||
registry: RecipeRegistry
|
||||
}
|
||||
|
||||
interface CraftingStation {
|
||||
canCraft(recipeId: string, inventory: Map<string, number>): boolean
|
||||
startCraft(recipeId: string, inventory: Map<string, number>, skill?: number): CraftJob
|
||||
tick(dt: number): CompletedCraft[]
|
||||
getQueue(): CraftJob[]
|
||||
cancelJob(jobId: string): void
|
||||
}
|
||||
|
||||
interface CraftJob {
|
||||
jobId: string
|
||||
recipeId: string
|
||||
startedAt: number
|
||||
duration: number
|
||||
skill: number
|
||||
}
|
||||
|
||||
interface CompletedCraft {
|
||||
jobId: string
|
||||
recipeId: string
|
||||
outputItemId: string
|
||||
quantity: number
|
||||
quality: QualityTier
|
||||
}
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type CraftErrorCode =
|
||||
| 'CRAFT_RECIPE_NOT_FOUND'
|
||||
| 'CRAFT_MISSING_INGREDIENTS'
|
||||
| 'CRAFT_STATION_FULL'
|
||||
| 'CRAFT_SKILL_TOO_LOW'
|
||||
| 'CRAFT_JOB_NOT_FOUND'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **Quality calculator** — output quality = base + skill bonus; `masterwork` requires skill ≥ 90.
|
||||
2. **Concurrent slot queue** — `maxSlots` allows parallel crafting at upgraded stations.
|
||||
3. **Ingredient quality minimum** — recipe can require `qualityMin`; fails if inventory item below tier.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
gaming/narrative/crafting/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/index.ts
|
||||
types/common.ts
|
||||
types/common.md
|
||||
core/
|
||||
recipe-registry/
|
||||
recipe-registry.ts
|
||||
recipe-registry.md
|
||||
recipe-registry.test.ts
|
||||
index.ts
|
||||
crafting-station/
|
||||
crafting-station.ts
|
||||
crafting-station.md
|
||||
crafting-station.types.ts
|
||||
crafting-station.test.ts
|
||||
index.ts
|
||||
utils/
|
||||
quality-calculator.ts
|
||||
quality-calculator.md
|
||||
quality-calculator.test.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: `@suaveplan/react-crafting` displays station queue and recipe list. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`.
|
||||
46
openspec/changes/enterprise-gaming-crafting/tasks.md
Normal file
46
openspec/changes/enterprise-gaming-crafting/tasks.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# Tasks: enterprise-gaming-crafting
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## Phase 1 — Scaffold
|
||||
|
||||
- [ ] Create `gaming/narrative/crafting/` (`@suaveplan/crafting`, `0.1.0`, `sideEffects: false`)
|
||||
- [ ] `tsconfig.json`, `vitest.config.ts`
|
||||
|
||||
## Phase 2 — Error codes & constants
|
||||
|
||||
- [ ] `src/error-codes.ts` + `src/constants/index.ts` — `QUALITY_TIERS` order, `DEFAULT_MAX_SLOTS`
|
||||
|
||||
## Phase 3 — Types
|
||||
|
||||
- [ ] `src/types/common.ts` + `common.md`
|
||||
|
||||
## Phase 4 — Quality calculator
|
||||
|
||||
- [ ] `src/utils/quality-calculator.ts` — base tier + skill bonus → output tier, masterwork threshold
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 5 — Recipe registry
|
||||
|
||||
- [ ] `src/core/recipe-registry/recipe-registry.ts` — register/get/listByStation, Zod validation
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 6 — Crafting station
|
||||
|
||||
- [ ] `src/core/crafting-station/crafting-station.ts` — canCraft/startCraft/tick/getQueue/cancel, slot queue, OTel
|
||||
- [ ] Tests (slot limit, ingredient check, timer advancement)
|
||||
- [ ] Docs
|
||||
|
||||
## Phase 7 — Integration tests
|
||||
|
||||
- [ ] `tests/integration.test.ts` — recipe start → tick to completion → quality output
|
||||
|
||||
## Phase 8 — Pre-publish gate
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/crafting` green
|
||||
- [ ] 100% coverage
|
||||
- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/crafting`
|
||||
Reference in New Issue
Block a user