@forgeax/engine-pack 0.1.26 → 0.1.28

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@forgeax/engine-pack",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
-  "description": "Disk schema, GUID tools, scanner, and fail-fast error chain for the forgeax engine asset package system. CLI surface is provided by @forgeax/engine-remote (forgeax-engine-remote asset).",
-  "bin": {
-    "forgeax-engine-remote-asset": "./dist/cli-asset.mjs"
-  },
+  "description": "Disk schema, GUID tools, scanner, and fail-fast error chain for the ForgeaX asset package system. The unified ForgeaX asset command owns the public producer entry.",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -131,7 +128,7 @@
     }
   },
   "dependencies": {
-    "@forgeax/engine-types": "0.1.26",
+    "@forgeax/engine-types": "0.1.28",
     "@noble/hashes": "^2.2.0",
     "fast-glob": "^3.3.3",
     "typescript": "^5.8.3",

package/schema/meta.schema.json

@@ -10,7 +10,7 @@
   "properties": {
     "schemaVersion": {
       "oneOf": [{ "type": "string" }, { "type": "integer" }],
-      "description": "Schema version. Strings (e.g. '1.0.0') for hand-authored .meta.json; integers (1, 2, ...) for importer-emitted .meta.json (forgeax-engine-remote-asset import writes schemaVersion: 1 as the wire format SSOT, GltfMetaJson literal type)."
+      "description": "Schema version. Strings (e.g. '1.0.0') for hand-authored .meta.json; integers (1, 2, ...) for importer-emitted .meta.json (forgeax asset import writes schemaVersion: 1 as the wire format SSOT, GltfMetaJson literal type)."
     },
     "kind": {
       "type": "string",

package/src/__tests__/atlas-cli-region-mismatch.test.ts

@@ -1,4 +1,4 @@
-// `forgeax-engine-remote-asset atlas` region-mismatch safety-net test
+// `forgeax asset atlas` region-mismatch safety-net test
 // (feat-20260521-sprite-atlas-animation M5' T-29 / requirements AC-10 (c)).
 //
 // The shelfPack pure function never produces regions whose summed area

package/src/__tests__/cli.unit.test.ts

@@ -266,7 +266,7 @@ async function writeSolidPng(
       await rm(tempDir, { recursive: true, force: true });
     });
 
-    describe('cli-asset (forgeax-engine-remote-asset plugin bin)', () => {
+    describe('cli-asset (forgeax asset plugin bin)', () => {
       describe('subcommand routing (a)', () => {
         it('routes scan as a known subcommand and returns 0 on empty roots', async () => {
           const io = makeIO();

package/src/__tests__/pack.unit.test.ts

@@ -1129,7 +1129,7 @@ const V1_WHITELIST = new Set([
         const err = new PackError({
           code: 'pack-meta-missing',
           expected: 'every source file must have a corresponding .meta.json in strict mode',
-          hint: 'run forgeax-engine-remote-asset scan --roots to list files without .meta.json',
+          hint: 'run forgeax asset list --root <project> --json to list source files without .meta.json',
           detail,
         });
         expect(err.code).toBe('pack-meta-missing' satisfies PackErrorCode);
@@ -1147,7 +1147,7 @@ const V1_WHITELIST = new Set([
         const err = new PackError({
           code: 'pack-guid-collision',
           expected: 'every GUID must be unique across all .pack.json files in the scan roots',
-          hint: 'run forgeax-engine-remote-asset verify to list all GUID collisions',
+          hint: 'run forgeax asset verify --root <project> --json to list all GUID collisions',
           detail,
         });
         expect(err.code).toBe('pack-guid-collision' satisfies PackErrorCode);
@@ -1168,7 +1168,7 @@ const V1_WHITELIST = new Set([
         const err = new PackError({
           code: 'pack-cyclic-reference',
           expected: 'asset reference graph must be acyclic',
-          hint: 'run forgeax-engine-remote-asset verify to list the cycle path',
+          hint: 'run forgeax asset verify --root <project> --json to list the cycle path',
           detail,
         });
         expect(err.code).toBe('pack-cyclic-reference' satisfies PackErrorCode);

package/src/atlas/run-atlas.ts

@@ -1,4 +1,4 @@
-// `forgeax-engine-remote-asset atlas` subcommand backend
+// `forgeax asset atlas` subcommand backend
 // (feat-20260521-sprite-atlas-animation M5' T-32). Replaces the v1 vite-
 // plugin idiom (PR #190 deleted `@forgeax/engine-vite-plugin-image`) with
 // a one-shot Node CLI that reads a glob of PNGs, runs the pure shelf
@@ -7,7 +7,7 @@
 //
 // Why CLI not Vite plugin (PR #190 architectural pivot):
 //   - asset importing is producer-side disk work; v2 routes the producer
-//     through the kubectl-style `forgeax-engine-remote-` plugin bin so the
+//     through the unified `forgeax asset atlas` producer so the
 //     same surface composes with `scan` / `lookup` / `verify` (charter P5
 //     producer/consumer split).
 //   - vite plugins reach for runtime-coupled hooks (buildStart / emitFile);
@@ -327,7 +327,7 @@ export async function runAtlas(rest: string[], ctx: AssetCtx): Promise<number> {
     return emitError(ctx, {
       code: 'atlas-empty-input',
       expected:
-        'forgeax-engine-remote-asset atlas --input <glob> --name <prefix> [--output <dir>] [--max-atlas-size <n>]',
+        'forgeax asset atlas --input <glob> --name <prefix> [--output <dir>] [--max-atlas-size <n>]',
       hint: argsOutcome.message,
       detail: { receivedCount: 0 },
     });

package/src/atlas/shelf-pack.ts

@@ -1,4 +1,4 @@
-// Pure-function shelf packer for the `forgeax-engine-remote-asset atlas`
+// Pure-function shelf packer for the `forgeax asset atlas`
 // subcommand (feat-20260521-sprite-atlas-animation M5' T-31). Maps a list
 // of decoded RGBA sprites to a non-overlapping atlas region map +
 // atlasWidth / atlasHeight envelope.

package/src/atlas/upng-ambient.d.ts

@@ -1,5 +1,5 @@
 // Ambient declaration for `upng-js` (PNG decoder/encoder) used by the
-// `forgeax-engine-remote-asset atlas` subcommand (run-atlas.ts) and by
+// `forgeax asset atlas` subcommand (run-atlas.ts) and by
 // its hermetic CLI integration tests under `__tests__/`. The package
 // ships without bundled `.d.ts`; consumer sites cast through local
 // interfaces to match the subset they use.

package/src/cli-asset.ts

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-// @forgeax/engine-pack/src/cli-asset — `forgeax-engine-remote-asset`
-// plugin bin (feat-20260516-console-dependency-inversion plan-strategy
-// section 2.9). Discovered by the base bin via the kubectl 4th-path
-// `forgeax-engine-remote-` prefix scanner; subcommands scan / lookup /
-// verify operate offline against the pack scanner.
+// @forgeax/engine-pack/src/cli-asset — Pack producer implementation used by
+// DevKit's unified `forgeax asset` command. It is not a package bin.
 //
 // stderr contract (plan-strategy section 2.3 weak-contract): every error
 // path emits a single JSON Lines record carrying `code` / `expected` /
@@ -30,6 +27,10 @@ import { projectScriptablePackMeta } from './pack-authoring.js';
 import { type ScanSourceDeclaration, scanInventory } from './scanner.js';
 import { loadScriptablePack } from './scriptable-pack-node.js';
 
+// The unified DevKit command tree reuses the producer implementation without
+// reviving the historical standalone executable as a second public surface.
+export { runAtlas } from './atlas/run-atlas.js';
+
 export interface PackEntry {
   readonly guid: string;
   readonly kind: string;
@@ -153,16 +154,14 @@ export async function scanEntries(
 
 function helpBody(): string {
   return [
-    'forgeax-engine-remote-asset — offline pack scanner / lookup / verifier / atlas builder',
+    'forgeax asset — offline pack scanner / lookup / verifier / atlas builder',
     '',
     'Usage:',
-    '  forgeax-engine-remote-asset scan [--roots <dir>]',
-    '  forgeax-engine-remote-asset lookup <guid>',
-    '  forgeax-engine-remote-asset verify',
-    '  forgeax-engine-remote-asset meta <source.pack.ts> --json',
-    '  forgeax-engine-remote-asset lookup --guid <guid> --project <dir> --catalog <path> --json',
-    '  forgeax-engine-remote-asset verify --guid <guid> --project <dir> --catalog <path> --json',
-    '  forgeax-engine-remote-asset atlas --input <glob> --name <prefix> [--output <dir>] [--max-atlas-size <n>]',
+    '  forgeax asset list --root <project> --json',
+    '  forgeax asset inspect --subject <guid> --root <project> --json',
+    '  forgeax asset verify --root <project> --json',
+    '  forgeax asset inspect --subject <source.pack.ts> --root <project> --json',
+    '  forgeax asset atlas --input <glob> --name <prefix> --root <project> [--output <dir>]',
     '',
     'AI recovery commands (host execution remains explicit):',
     '  inspect [--guid <guid>]      read subject, execution, lifecycle, authority, and sourceKey evidence',
@@ -205,7 +204,7 @@ export async function runCliAsset(rest: string[], ctx: AssetCtx): Promise<number
       return emitError(ctx, {
         code: 'unknown-subcommand',
         expected: 'subcommand in {scan, lookup, verify, atlas, meta}',
-        hint: "run 'forgeax-engine-remote-asset --help' for usage",
+        hint: "run 'forgeax help asset' for usage",
         detail: { subcommand: sub },
       });
   }
@@ -227,7 +226,7 @@ async function runMeta(rest: string[], ctx: AssetCtx): Promise<number> {
   } catch (error) {
     return emitError(ctx, {
       code: 'cli-parse-error',
-      expected: 'forgeax-engine-remote-asset meta <source.pack.ts> --json',
+      expected: 'forgeax asset inspect --subject <source.pack.ts> --root <project> --json',
       hint: 'pass one trusted ScriptablePack module path',
       detail: { message: error instanceof Error ? error.message : String(error) },
     });
@@ -277,7 +276,7 @@ async function runRecoveryCommand(
     return emitError(ctx, {
       code: 'cli-parse-error',
       expected: `${operation} [--guid <guid>]`,
-      hint: "run 'forgeax-engine-remote-asset --help' for usage",
+      hint: "run 'forgeax help asset' for usage",
       detail: { message: error instanceof Error ? error.message : String(error) },
     });
   }
@@ -297,8 +296,8 @@ async function runScan(rest: string[], ctx: AssetCtx): Promise<number> {
     const message = e instanceof Error ? e.message : String(e);
     return emitError(ctx, {
       code: 'cli-parse-error',
-      expected: 'forgeax-engine-remote-asset scan [--roots <dir>]',
-      hint: "run 'forgeax-engine-remote-asset --help' for usage",
+      expected: 'forgeax asset list --root <project> --json',
+      hint: "run 'forgeax help asset' for usage",
       detail: { message },
     });
   }
@@ -314,7 +313,7 @@ async function runLookup(rest: string[], ctx: AssetCtx): Promise<number> {
   if (typeof guid !== 'string') {
     return emitError(ctx, {
       code: 'cli-parse-error',
-      expected: 'forgeax-engine-remote-asset lookup <36-char-uuid>',
+      expected: 'forgeax asset inspect --subject <guid> --root <project> --json',
       hint: 'pass a 36-char dash-form UUID positional argument',
     });
   }
@@ -356,8 +355,8 @@ async function runVerify(rest: string[], ctx: AssetCtx): Promise<number> {
     const message = e instanceof Error ? e.message : String(e);
     return emitError(ctx, {
       code: 'cli-parse-error',
-      expected: 'forgeax-engine-remote-asset verify',
-      hint: "run 'forgeax-engine-remote-asset --help' for usage",
+      expected: 'forgeax asset verify --root <project> --json',
+      hint: "run 'forgeax help asset' for usage",
       detail: { message },
     });
   }
@@ -397,7 +396,7 @@ function parseEvidenceOptions(rest: string[], ctx: AssetCtx): EvidenceCliOptions
       emitError(ctx, {
         code: 'cli-parse-error',
         expected: '--guid <guid> --project <dir> --catalog <path> --json',
-        hint: "run 'forgeax-engine-remote-asset --help' for usage",
+        hint: "run 'forgeax help asset' for usage",
       });
       return undefined;
     }
@@ -407,7 +406,7 @@ function parseEvidenceOptions(rest: string[], ctx: AssetCtx): EvidenceCliOptions
     emitError(ctx, {
       code: 'cli-parse-error',
       expected: '--guid <guid> --project <dir> --catalog <path> --json',
-      hint: "run 'forgeax-engine-remote-asset --help' for usage",
+      hint: "run 'forgeax help asset' for usage",
       detail: { message },
     });
     return undefined;

package/src/scanner.ts

@@ -184,7 +184,7 @@ interface ScanCapture {
  * Requirements §3.4 + §5 blacklist.
  *
  * Re-exported as `SCANNER_BLACKLIST` for cross-package reuse: the
- * `forgeax-engine-remote-asset import --check` traversal (M4 / w21 +
+ * `forgeax asset import --check` traversal (M4 / w21 +
  * plan-strategy section 2.8 path b) walks the same set of source-orphan
  * candidates as the scanner, so we share the single SSOT here.
  */