lootforge 0.3.0

package/docs/SERVICE_MODE.md

@@ -0,0 +1,137 @@
+# Service Mode (`lootforge serve`)
+
+`lootforge serve` runs a local HTTP server for command execution without adding auth/credit controls in core.
+
+## Start
+
+```bash
+lootforge serve --host 127.0.0.1 --port 8744
+```
+
+Optional defaults:
+
+- `--out <dir>`: default out directory injected when command payload omits `out`
+- `--max-active-jobs <number>`: max concurrent active tool executions before returning `429 service_busy` (default `2`)
+- `LOOTFORGE_SERVICE_HOST`
+- `LOOTFORGE_SERVICE_PORT`
+- `LOOTFORGE_SERVICE_OUT`
+- `LOOTFORGE_SERVICE_MAX_ACTIVE_JOBS`
+
+## Endpoints (`v1`)
+
+- `GET /v1/health`
+- `GET /v1/tools`
+- `GET /v1/contracts/generation-request`
+- `GET /v1/contracts/provider-capabilities`
+- `GET /v1/providers/capabilities`
+- `POST /v1/tools/:name`
+- `POST /v1/:name` (alias for tools endpoint)
+- `POST /v1/generation/requests` (canonical generation request contract)
+
+Root helper endpoint:
+
+- `GET /`
+
+Provider capabilities query options:
+
+- `provider` (optional): `openai|nano|local`
+- `model` (optional): model override for introspection; requires `provider`
+
+## Request Shape
+
+Tool execution accepts one of:
+
+1. `params` object (recommended stable interface)
+
+```json
+{
+  "requestId": "req-123",
+  "params": {
+    "out": "/abs/path/to/workdir",
+    "strict": true
+  }
+}
+```
+
+2. `args` override (raw CLI flag compatibility)
+
+```json
+{
+  "args": ["--out", "/abs/path/to/workdir", "--strict", "true"]
+}
+```
+
+`ids` and `runtimes` support string arrays in `params` and are converted to CSV flags.
+
+Canonical generation request contract:
+
+```json
+{
+  "requestId": "req-gen-001",
+  "request": {
+    "manifestPath": "/abs/path/to/manifest.json",
+    "outDir": "/abs/path/to/out",
+    "provider": "auto",
+    "targetIds": ["hero", "enemy_01"],
+    "skipLocked": true,
+    "selectionLockPath": "/abs/path/to/locks/selection-lock.json"
+  }
+}
+```
+
+Notes:
+
+- `request.manifest` can be provided inline instead of `manifestPath`; service mode will materialize it before planning.
+- Canonical request execution maps to `plan -> generate` and returns both plan metadata and generation run metadata.
+
+## Response Shape
+
+Success:
+
+```json
+{
+  "ok": true,
+  "apiVersion": "v1",
+  "tool": "validate",
+  "requestId": "req-123",
+  "result": {}
+}
+```
+
+Failure:
+
+```json
+{
+  "ok": false,
+  "apiVersion": "v1",
+  "tool": "validate",
+  "error": {
+    "code": "manifest_validation_failed",
+    "message": "Manifest validation failed with 1 error(s).",
+    "exitCode": 1
+  }
+}
+```
+
+Busy (`429`):
+
+```json
+{
+  "ok": false,
+  "apiVersion": "v1",
+  "tool": "generate",
+  "error": {
+    "code": "service_busy",
+    "message": "Service is busy (2/2 active jobs). Retry later."
+  }
+}
+```
+
+## MCP Wrapper Compatibility Notes
+
+- `GET /v1/tools` exposes stable tool metadata and parameter keys.
+- `POST /v1/tools/:name` gives deterministic JSON envelopes for tool-call wrappers.
+- `POST /v1/generation/requests` provides a canonical mapping layer from service request payloads to manifest planning + generation targets.
+- `GET /v1/providers/capabilities` provides provider/model capability introspection for wrapper-side feature gating (`pixel`, `highRes`, `references`).
+- `GET /v1/contracts/provider-capabilities` exposes a machine-readable contract for the capabilities endpoint.
+- CORS headers are permissive (`*`) for local tool hosts.

package/docs/manifest-schema.md

@@ -0,0 +1,254 @@
+# Manifest Schema (`version: "next"`)
+
+`next` is the only supported manifest contract in this rewrite.
+
+Manifest policy coverage gate:
+
+- `docs/MANIFEST_POLICY_COVERAGE.md` is the machine-checkable index of documented policy fields.
+- `npm run check:manifest-policy` validates coverage status (`implemented|reserved`) and required test evidence, then emits `coverage/manifest-policy-coverage.json`.
+
+## Top-level fields
+
+- `version`: must be `"next"`
+- `pack`: `{ id, version, license?, author? }`
+- `providers`: `{ default, openai?, nano?, local? }`
+  - Provider configs support runtime fields:
+    - `model?`
+    - `endpoint?` (OpenAI generation endpoint, Nano API base)
+    - `timeoutMs?` (request timeout per provider call)
+    - `maxRetries?` (default retries when target policy omits `generationPolicy.maxRetries`)
+    - `minDelayMs?` (provider-level minimum spacing between jobs)
+    - `defaultConcurrency?` (provider-level worker count)
+  - `providers.local` also supports `baseUrl?` (alias for local endpoint)
+- `styleKits[]` (required, at least one)
+  - `id`
+  - `rulesPath`
+  - `palettePath?`
+  - `referenceImages[]`
+  - `styleReferenceImages[]?` (directed style-image scaffold inputs; provider support varies)
+  - `lightingModel`
+  - `negativeRulesPath?`
+  - `loraPath?`
+  - `loraStrength?` (`0..2`, requires `loraPath`)
+  - `visualPolicy?`: `{ lineContrastMin?, shadingBandCountMax?, uiRectilinearityMin? }`
+    - machine-checkable style-bible constraints applied during acceptance/eval
+- `consistencyGroups[]` (optional)
+  - `id`
+  - `description?`
+  - `styleKitId?`
+  - `referenceImages[]`
+- `targetTemplates[]` (optional)
+  - `id`
+  - `dependsOn[]?` (target-id dependency policy)
+  - `styleReferenceFrom[]?` (target-id style-reference chain policy)
+- `evaluationProfiles[]` (required, at least one)
+  - `id`
+  - `hardGates?`: `{ requireAlpha?, maxFileSizeKB?, seamThreshold?, seamStripPx?, paletteComplianceMin?, alphaHaloRiskMax?, alphaStrayNoiseMax?, alphaEdgeSharpnessMin?, mattingHiddenRgbLeakMax?, mattingMaskConsistencyMin?, mattingSemiTransparencyRatioMax?, packTextureBudgetMB?, spritesheetSilhouetteDriftMax?, spritesheetAnchorDriftMax?, spritesheetIdentityDriftMax?, spritesheetPoseDriftMax? }`
+  - `consistencyGroupScoring?`: `{ warningThreshold?, penaltyThreshold?, penaltyWeight? }`
+    - `warningThreshold`: normalized drift score threshold for group-level warning signals
+    - `penaltyThreshold`: normalized drift score threshold where ranking penalties activate
+    - `penaltyWeight`: deterministic multiplier used for final-score penalty (`round(score * weight)`)
+  - `scoreWeights?`: `{ readability?, fileSize?, consistency?, clip?, lpips?, ssim? }`
+- `scoringProfiles[]` (optional)
+  - `id`
+  - `scoreWeights?`: global score-weight overrides for all target kinds
+  - `kindScoreWeights?`: optional per-kind overrides for `sprite|tile|background|effect|spritesheet`
+- `atlas?`: atlas defaults + optional per-group overrides
+- `targets[]` (required)
+
+Style kit palette defaults:
+
+- If a target omits `palette`, LootForge will attempt to load `styleKits[].palettePath` and apply it as an exact palette policy.
+- If `targets[].palette` is provided, it overrides any style-kit palette default.
+
+## Target contract
+
+Required on every target:
+
+- `id`
+- `kind`
+- `out`
+- `styleKitId`
+- `consistencyGroup`
+- `evaluationProfileId`
+- `generationMode` (`text|edit-first`) recommended
+
+Optional quality controls:
+
+- `templateId?`: references `targetTemplates[].id` for reusable orchestration policy
+- `dependsOn?`: target-id dependencies used for deterministic execution staging
+- `styleReferenceFrom?`: target-id style-reference lineage for chaining generated assets
+  - when omitted, style-reference lineage defaults to `dependsOn`
+- `palette`: `{ mode: exact|max-colors, colors?, maxColors?, dither?, strict? }`
+  - `strict` is supported only in `mode: "exact"` and enforces 100% visible-pixel palette compliance.
+- `scoringProfile?`: profile id from `scoringProfiles[]` (falls back to `evaluationProfileId` lookup)
+- `tileable`, `seamThreshold`, `seamStripPx`
+- `seamHeal?`: `{ enabled?, stripPx?, strength? }` (optional edge blending pass for tileable targets)
+- `wrapGrid?`: `{ columns, rows, seamThreshold?, seamStripPx?, topology? }` (per-cell wrap validation gates)
+  - `topology?`: `{ mode, maxMismatchRatio?, colorTolerance? }`
+  - `mode`: `self|one-to-one|many-to-many` adjacency validation, evaluated independently from seam score
+
+Generation + processing:
+
+- `prompt` or `promptSpec` (required for non-`spritesheet` targets)
+- `generationPolicy`
+  - `generationPolicy.highQuality?` (directed-synthesis scaffold flag)
+  - `generationPolicy.hiresFix?`: `{ enabled?, upscale?, denoiseStrength? }`
+  - `generationPolicy.vlmGate?`: `{ threshold?, rubric? }`
+  - `threshold` defaults to `4` (scored on `0..5`) when gate is configured
+  - `generationPolicy.coarseToFine?`: `{ enabled?, promoteTopK?, minDraftScore?, requireDraftAcceptance? }`
+  - `generationPolicy.agenticRetry?`: `{ enabled?, maxRetries? }`
+    - when enabled, failed VLM/edge-boundary candidates can trigger bounded edit-first self-healing retries
+  - optional quality split: `draftQuality` (coarse pass) and `finalQuality` (refinement pass)
+- `postProcess`
+  - `postProcess.operations.smartCrop?`: `{ enabled?, mode?, padding? }`
+    - `mode`: `alpha-bounds|center`
+  - `postProcess.operations.pixelPerfect?`: `{ enabled?, scale? }`
+    - favors nearest-neighbor semantics during resize when enabled
+  - `postProcess.operations.emitVariants?`: `{ raw?, pixel?, styleRef? }`
+    - writes explicit `__raw`, `__pixel`, and `__style_ref` processed artifacts when enabled
+    - layered export toggles: `layerColor?`, `layerMatte?` write `__layer_color` + `__layer_matte` artifacts
+- `acceptance`
+- `runtimeSpec`
+- `provider`, `model`, `edit`, `auxiliaryMaps`
+- `controlImage?` + `controlMode?` (`canny|depth|openpose`) must be provided together
+- `generationMode: "edit-first"` requires an edit-capable provider (`openai`, `local`, or `nano` with an image-edit-capable Gemini model)
+- `edit.inputs[].path` must resolve inside the active `--out` root at runtime
+- `generationPolicy.background: "transparent"` requires a provider that supports transparent outputs (unsupported providers now fail validation)
+- `generationPolicy.vlmGate` requires runtime evaluator transport via `LOOTFORGE_VLM_GATE_CMD` or `LOOTFORGE_VLM_GATE_URL`
+- edge-aware hard gates can be configured in `evaluationProfiles[].hardGates`:
+  - `alphaHaloRiskMax` (`0..1`, lower is stricter)
+  - `alphaStrayNoiseMax` (`0..1`, lower is stricter)
+  - `alphaEdgeSharpnessMin` (`0..1`, higher is stricter)
+- matting-assisted alpha QA hard gates can be configured in `evaluationProfiles[].hardGates`:
+  - `mattingHiddenRgbLeakMax` (`0..1`, lower is stricter)
+  - `mattingMaskConsistencyMin` (`0..1`, higher is stricter)
+  - `mattingSemiTransparencyRatioMax` (`0..1`, lower is stricter)
+- score weighting defaults and overrides:
+  - LootForge applies deterministic built-in score presets by target kind.
+  - If a matching `scoringProfiles[]` entry is found (by `targets[].scoringProfile` or `evaluationProfileId`), profile weights override the built-in kind preset.
+  - If no matching `scoringProfiles[]` entry exists, `evaluationProfiles[].scoreWeights` acts as a compatibility fallback override.
+- pack-level gates can be configured in `evaluationProfiles[].hardGates` and are normalized onto each planned target:
+  - `packTextureBudgetMB` (`>0`, optional profile-level uncompressed texture budget)
+  - `spritesheetSilhouetteDriftMax` (`0..1`, optional max adjacent-frame silhouette drift)
+  - `spritesheetAnchorDriftMax` (`0..1`, optional max adjacent-frame anchor drift)
+  - `spritesheetIdentityDriftMax` (`0..1`, optional max adjacent-frame visual identity drift)
+  - `spritesheetPoseDriftMax` (`0..1`, optional max adjacent-frame pose/orientation drift)
+- consistency-group drift controls can be configured in `evaluationProfiles[].consistencyGroupScoring` and are normalized onto each planned target:
+  - `warningThreshold` (`>0`, optional warning trigger for aggregate group diagnostics)
+  - `penaltyThreshold` (`>0`, optional threshold for deterministic ranking penalty)
+  - `penaltyWeight` (`>=0`, optional multiplier for ranking influence)
+
+Provider runtime precedence for generate/regenerate:
+
+- target-level `generationPolicy` overrides provider defaults for retries/concurrency settings
+- provider runtime fields resolve from manifest and can be overridden by environment variables (`LOOTFORGE_*` / provider-specific env aliases)
+- capability parity is enforced at runtime (`supports(...)` must match provider capability flags)
+
+## Spritesheet targets
+
+For `kind: "spritesheet"`, define:
+
+- `animations`: record keyed by animation name
+  - `count` (required)
+  - `prompt` (required)
+  - `fps?`, `loop?`, `pivot?`
+
+Planner behavior:
+
+- expands each animation frame into internal frame targets under `__frames/...`
+- emits a generation-disabled sheet target that process stage assembles
+
+Pack invariants enforced during acceptance/eval:
+
+- runtime output uniqueness across non-catalog targets (case-insensitive normalized path)
+- spritesheet sheet/frame family and atlas-group integrity checks
+- continuity metrics per animation (`maxSilhouetteDrift`, `maxAnchorDrift`, `maxIdentityDrift`, `maxPoseDrift`) with optional hard-gate thresholds
+- optional profile texture budget gate using estimated uncompressed bytes (`width * height * 4`)
+
+Style-bible visual policy checks (from `styleKits[].visualPolicy`) in acceptance/eval:
+
+- `lineContrastMin`: rejects low-contrast outputs when measured line contrast is below threshold
+- `shadingBandCountMax`: rejects outputs whose visible-pixel luma bands exceed threshold
+- `uiRectilinearityMin`: rejects non-rectilinear silhouettes when bounding-box fill ratio is too low
+
+## Example (minimal sprite)
+
+```json
+{
+  "version": "next",
+  "pack": {
+    "id": "my-pack",
+    "version": "0.1.0"
+  },
+  "providers": {
+    "default": "openai",
+    "openai": { "model": "gpt-image-1" }
+  },
+  "styleKits": [
+    {
+      "id": "fantasy-topdown",
+      "rulesPath": "style/fantasy/style.md",
+      "palettePath": "style/fantasy/palette.txt",
+      "referenceImages": [],
+      "lightingModel": "top-left key with warm fill"
+    }
+  ],
+  "consistencyGroups": [
+    {
+      "id": "player-family",
+      "description": "Shared protagonist style and silhouette constraints.",
+      "styleKitId": "fantasy-topdown",
+      "referenceImages": []
+    }
+  ],
+  "evaluationProfiles": [
+    {
+      "id": "sprite-quality",
+      "hardGates": {
+        "requireAlpha": true,
+        "maxFileSizeKB": 512,
+        "alphaHaloRiskMax": 0.08,
+        "alphaStrayNoiseMax": 0.01,
+        "alphaEdgeSharpnessMin": 0.8,
+        "packTextureBudgetMB": 48,
+        "spritesheetSilhouetteDriftMax": 0.2,
+        "spritesheetAnchorDriftMax": 0.15
+      }
+    }
+  ],
+  "targets": [
+    {
+      "id": "player.hero",
+      "kind": "sprite",
+      "out": "player_hero.png",
+      "styleKitId": "fantasy-topdown",
+      "consistencyGroup": "player-family",
+      "evaluationProfileId": "sprite-quality",
+      "generationMode": "text",
+      "prompt": "Top-down hero sprite with clear readable silhouette.",
+      "generationPolicy": {
+        "size": "1024x1024",
+        "background": "transparent",
+        "outputFormat": "png",
+        "quality": "high",
+        "candidates": 4,
+        "vlmGate": {
+          "threshold": 4,
+          "rubric": "Score silhouette clarity and framing quality from 0 to 5."
+        }
+      },
+      "postProcess": {
+        "resizeTo": "512x512",
+        "algorithm": "lanczos3",
+        "stripMetadata": true
+      },
+      "acceptance": {
+        "size": "512x512",
+        "alpha": true,
+        "maxFileSizeKB": 512
+      }
+    }
+  ]
+}
+```

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "lootforge",
+  "private": false,
+  "version": "0.3.0",
+  "type": "module",
+  "description": "LootForge CLI for manifest-driven game asset packs",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "lootforge": "./bin/lootforge.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/*.md"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "dev": "tsx src/cli/index.ts",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test:coverage:full": "vitest run --coverage --coverage.include=\"src/**/*.ts\" --coverage.reporter=text --coverage.reporter=json-summary",
+    "test:coverage:critical": "npm run test:coverage:full",
+    "lint": "eslint src/ test/",
+    "lint:fix": "eslint src/ test/ --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "check": "npm run typecheck && npm run lint && npm run format:check",
+    "check:manifest-policy": "node scripts/check-manifest-policy-coverage.mjs --report coverage/manifest-policy-coverage.json",
+    "check:release:metadata": "tsx scripts/check-release-metadata.ts --release 0.3.0",
+    "benchmark:coarse-to-fine": "tsx scripts/benchmark-coarse-to-fine.ts",
+    "release:showcase": "tsx scripts/release-showcase.ts",
+    "check:release-showcase": "tsx scripts/check-release-showcase.ts --release 0.3.0",
+    "pack:dry-run": "npm pack --dry-run --cache .npm-cache",
+    "check:release": "npm run check && npm test && npm run test:coverage:full && npm run build && npm run check:manifest-policy && npm run check:release:metadata && npm run check:release-showcase && npm audit --audit-level=high && npm run pack:dry-run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "sharp": "^0.34.5",
+    "yazl": "^3.3.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.3",
+    "@types/node": "^22.13.1",
+    "@types/yauzl": "^2.10.3",
+    "@types/yazl": "^2.4.5",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.3",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import-x": "^4.16.1",
+    "eslint-plugin-n": "^17.24.0",
+    "prettier": "^3.8.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^4.0.18",
+    "yauzl": "^3.2.0"
+  },
+  "overrides": {
+    "minimatch": ">=10.2.1"
+  }
+}