@helix3/helix-cli 0.1.18-helix3.353 → 0.1.18-helix3.355

package/README.md

@@ -46,6 +46,10 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix publish [dir] [--thumbnail <file>] [--upload-source] [--source-dir <path>]` | Validate → resolve/create the world → upload files → finalize → set the cover image → print the play URL. `--upload-source` additionally sends the project's source through a separate private channel so the world can be edited on the website later — **off by default**. |
 | `helix list` | List your worlds. |
 | `helix vehicle validate <vehicle-package.json> [--glb <model.glb>] [--json]` | One-second local gate for a hand-authored Universal Vehicle, run before `item publish`. Checks the package against the engine's own validator (vendored, pinned to an engine commit), the engine publish gate, the backend pin requirements, `groundToBodyOrigin` vs `wheelRadius + staticRideHeight`, and the `componentBuild` digest; with `--glb` also resolves the four wheel nodes, checks each wheel node's origin is at its hub (`WHEEL_PIVOT_NOT_AT_HUB`), the +X-left / +Z-forward frame, the vehicle publish budgets and the articulation nodes. Exit `0` no errors, `1` errors, `2` unreadable input. See [Vehicle validate](#vehicle-validate). |
+| `helix vehicle publish <dir> [--dry-run] [--item <id> --package-version <v> --reason <text>] [--json]` | One command from a vehicle package directory to a sealed, pinned, read-back-verified vehicle item: validate → upload each local WAV and write its verified public URL → mint → seal + pin the `vehicle` Package → read back. Resumable (ledger in `<dir>/.helix-publish`). See [Vehicle publish](#vehicle-publish). |
+| `helix vehicle audio-check <dir\|package.json\|item-id> [--json]` | Proves every sound the runtime will select resolves, is PCM WAV and is audible (pre-publish on local files, or read-back on a published item). |
+| `helix vehicle addon check <dir> [--grant] [--json]` / `helix vehicle addon publish <dir> [--no-grant] [--dry-run]` | Add-on fit gate (contract, `helixMeshFrame` anchoring, host hubs, hide targets + grants, the backend's `validate-fit` dry run) and the end-to-end add-on publish (grant → upload → seal + pin the `addon` Package → read back). |
+| `helix vehicle grant-hides <host-id> --hide <slot=glob,...>` | Read-modify-write of the host board's `hostGrantExtensions` (`PUT /universal-items/:id/slots`), so add-ons may hide its real nodes (`rim_*`, `exhaust`). |
 | `helix item list-slots [--json]` | Print the Character-Creator vocabulary a wearable declares: the cosmetic slot tags, and the genders. |
 | `helix item publish <mesh.glb> --title <t> [--collectible-supply <n>] [initial distribution flags] [--dry-run\|--quote]` | Publish a Standard item by default, or one fixed-supply Collectible. The item definition is separate from acquisition routes. |
 | `helix item distribution create\|list\|update\|disable …` | Manage Marketplace/World Claim or Buy routes without republishing the item or paying another publish fee. |
@@ -567,6 +571,25 @@ The model frame is glTF: +X is the vehicle's left, +Y up, +Z forward, metres. Wh
 the engine's own resolver (`wheel_lf` / `wheel_rf` / `wheel_lr` / `wheel_rr` and the usual aliases); all four must
 resolve. The engine validator is vendored by `scripts/vendor-vehicle-package-v2.mjs` (see `vendor/README.md`).
 
+## Vehicle publish
+
+`helix vehicle publish <dir>` takes a directory holding `vehicle-package.json`, one `.glb` (`model.glb` when there
+are several), an optional `thumbnail.{png,jpg,webp}`, WAVs beside the package or under `audio/`, and an optional
+`publish.json` (`title`, `description`, `tags`, `slug`, `version`, `provenance`). Audio rows are authored as
+`{ name, file }`; the command uploads each file as a public Continuum object, waits until its content URL serves the
+exact bytes, and writes `url` / `checksumSha256` / `bytes` / `cid` before the mint (a public object is readable at
+its content URL before any seal, so this is one pass). It then mints the item, seals the `vehicle` Package (root =
+the item's canonical package bytes, the item's web GLB adopted, every WAV) with `universalItemPin`, and reads back
+the pin, the package identity and every audio URL. `--item <id> --package-version <v> --reason <text>` seals a
+staged version of an existing car and moves it (a listed car's move waits for a passing candidate visual QA; the
+command says so). Exit `0` published and verified, `1` refused or read-back failed, `2` unreadable input.
+`helix vehicle validate` judges local-WAV audio rows as if uploaded, so it passes on the same directory.
+
+`helix vehicle addon publish <dir>` does the same for an add-on directory (`addon.json` { `title`, `fits`, `ops`, … }
++ `model.glb`): `addon check` first (opening missing hide grants on hosts you created), then publish with no
+Marketplace route, seal + pin the `addon` Package (vehicle add-ons are not auto-sealed), and read back that every
+host lists it as a fit.
+
 ## Item publish flow
 
 `helix item publish` creates an item definition. It defaults to **Standard**: unlimited issuance,

package/dist/index.js

@@ -588,8 +588,14 @@ vehicleCommand
         }
     }
     let result;
+    let provisional = 0;
     try {
-        result = await (0, validate_1.validateVehicle)(pkg, glb);
+        // Audio rows backed by a WAV beside the package get their public url from `helix vehicle publish`; judge the
+        // rest of the package as if that had happened (the engine validator requires a complete runtime closure).
+        const { provisionalAudio } = await Promise.resolve().then(() => __importStar(require('./vehicle/audio')));
+        const prepared = provisionalAudio(pkg, (0, node_path_1.resolve)(packageFile, '..'));
+        provisional = prepared.filled;
+        result = await (0, validate_1.validateVehicle)(prepared.pkg, glb);
     }
     catch (error) {
         process.stderr.write(`✖ cannot validate ${opts.glb ?? packageFile}: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -602,12 +608,252 @@ vehicleCommand
     else {
         if (result.issues.length > 0)
             console.log((0, validate_1.formatVehicleIssues)(result.issues));
+        if (provisional > 0)
+            console.log(`  ${provisional} audio row${provisional === 1 ? '' : 's'} backed by a local WAV: \`helix vehicle publish\` uploads ${provisional === 1 ? 'it' : 'them'} and writes the url; \`helix vehicle audio-check\` proves ${provisional === 1 ? 'it plays' : 'they play'}`);
         console.log(`${result.ok ? '✔' : '✖'} ${result.ok ? 'Valid' : 'Invalid'} vehicle package: ${result.errors} error${result.errors === 1 ? '' : 's'}, ${result.warnings} warning${result.warnings === 1 ? '' : 's'}`
             + `${glb ? ' (package + GLB)' : ' (package only — add --glb <model.glb> to check wheels, pivots and budgets)'}  [engine ${result.engineCommit.slice(0, 8)}]`);
     }
     if (!result.ok)
         process.exitCode = 1;
 });
+// ── vehicle publish / audio / add-on tooling (src/vehicle/{publish,audio,addon}.ts) ───────────────────────────────
+function vehicleContinuumDeps() {
+    const creds = requireAuth();
+    const api = lib_1.HelixApi.forCredentials(creds);
+    return Promise.resolve().then(() => __importStar(require('./continuum'))).then(({ ContinuumPublisher, HelixContinuumApi }) => {
+        const continuumApi = new HelixContinuumApi(api);
+        const publisher = new ContinuumPublisher(continuumApi);
+        return {
+            creds,
+            api: api,
+            objects: continuumApi,
+            publishPackage: async (intent) => (await publisher.publish(intent)),
+        };
+    });
+}
+function printVehicleJsonOr(json, value, human) {
+    if (json)
+        console.log(JSON.stringify(value, (_k, v) => (v === Number.NEGATIVE_INFINITY ? '-Infinity' : v), 2));
+    else
+        human();
+}
+vehicleCommand
+    .command('publish')
+    .description('Publish a vehicle package directory end to end: validate (package, GLB, every audio sample decoded and audible) → upload each WAV and write its '
+    + 'public URL into the package → mint the vehicle item → seal and pin its `vehicle` Continuum Package (root, adopted web GLB, WAVs) → read it back '
+    + '(pin, package identity, every audio URL fetched and decoded). Resumable: re-run the same command after any failure. '
+    + 'Directory: vehicle-package.json, one .glb (model.glb), optional thumbnail.png, WAVs beside it or in audio/, optional publish.json. '
+    + 'Exit 0 = published and verified, 1 = refused or read-back failed, 2 = unreadable input')
+    .argument('<dir>', 'the vehicle package directory')
+    .option('--glb <file>', 'the drawn model, when the directory holds more than one .glb')
+    .option('--thumbnail <file>', 'thumbnail image (png/jpg/webp); rendered by the server when omitted')
+    .option('--title <title>', 'display title (default: publish.json title, then the package displayName)')
+    .option('--description <text>', 'item description')
+    .option('--tags <a,b,c>', 'comma-separated search keywords')
+    .option('--slug <slug>', 'url slug')
+    .option('--package-version <v>', 'Package Version to seal (default 1.0.0; required with --item)')
+    .option('--item <item-id>', 'publish a NEW VERSION of this existing vehicle item (staged seal + version move) instead of minting')
+    .option('--reason <text>', 'with --item: why the version moves (1–500 chars)')
+    .option('--allow-oversize', 'relax the mesh size ceiling (the server has the final say)')
+    .option('--out <dir>', 'ledger / finished package / descriptor / receipt directory (default <dir>/.helix-publish)')
+    .option('--dry-run', 'validate and check audio only; no upload, no fee')
+    .option('--json', 'print the machine-readable result')
+    .action(async (dir, opts) => {
+    try {
+        const { publishVehicle } = await Promise.resolve().then(() => __importStar(require('./vehicle/publish')));
+        const { formatAudioReport } = await Promise.resolve().then(() => __importStar(require('./vehicle/audio')));
+        const say = (m) => { if (!opts.json)
+            console.log(`· ${m}`); };
+        const base = opts.dryRun ? null : await vehicleContinuumDeps();
+        const creds = base?.creds ?? (0, config_1.loadCredentials)() ?? { apiUrl: '', token: '', expiresAt: '', username: '' };
+        const result = await publishVehicle({
+            dir, glb: opts.glb, thumbnail: opts.thumbnail, title: opts.title, description: opts.description,
+            tags: opts.tags ? (0, lib_1.parseTags)(opts.tags) : undefined, slug: opts.slug, version: opts.packageVersion, itemId: opts.item,
+            reason: opts.reason, allowOversize: opts.allowOversize, out: opts.out, dryRun: opts.dryRun,
+        }, creds, {
+            api: base?.api ?? { request: async () => { throw new Error('dry run makes no requests'); } },
+            objects: base?.objects ?? { putObjectFromFile: async () => { throw new Error('dry run uploads nothing'); } },
+            publishPackage: base?.publishPackage ?? (async () => { throw new Error('dry run seals nothing'); }),
+            mintItem: async (input) => {
+                const r = await (0, lib_1.publishItem)({ kind: 'vehicle', title: input.title, mesh: input.mesh, thumbnail: input.thumbnail, vehiclePackage: input.vehiclePackage, description: input.description, tags: input.tags, slug: input.slug, allowOversize: input.allowOversize }, base.creds, { onProgress: say });
+                return { id: r.id, slug: r.slug };
+            },
+            setVersion: async (itemId, input) => (0, itemSetVersion_1.setItemVersion)(itemId, { packageVersion: input.packageVersion, reason: input.reason, vehiclePackage: input.vehiclePackage }, base.creds),
+            onProgress: say,
+        });
+        printVehicleJsonOr(opts.json, result, () => {
+            if (result.validation.issues.length)
+                console.log((0, validate_1.formatVehicleIssues)(result.validation.issues));
+            console.log(formatAudioReport(result.audio));
+            if (result.itemId)
+                console.log(`  item:    ${result.itemId}${result.slug ? ` (${result.slug})` : ''}`);
+            if (result.packagePin)
+                console.log(`  package: ${result.packagePin.packageId}@${result.packagePin.version} ${result.packagePin.manifestCid}`);
+            if (result.readBack) {
+                console.log(`  read-back: pin ${result.readBack.pinMatches ? 'matches' : 'MISMATCH'}, package identity ${result.readBack.packageIdentityMatches ? 'matches' : 'MISMATCH'}, status ${result.readBack.status}`);
+                console.log(formatAudioReport(result.readBack.audio));
+            }
+            console.log(`  files:   ${Object.values(result.files).join('  ')}`);
+            for (const step of result.next)
+                console.log(`  next: ${step}`);
+            console.log(`${result.ok ? '✔' : '✖'} ${result.dryRun ? 'dry run' : result.versionMove ?? 'publish'}${result.ok ? '' : ' failed'}`);
+        });
+        if (!result.ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof lib_1.ApiError ? error.render() : `✖ ${error instanceof Error ? error.message : String(error)}`}\n`);
+        process.exitCode = 2;
+    }
+});
+vehicleCommand
+    .command('audio-check')
+    .description('Prove every sound a vehicle declares will actually play: each engine-ladder rung and slot sample the runtime selects must resolve (a local WAV '
+    + 'beside the package before publish, or HTTP 200 with the exact declared bytes and sha256 after), be PCM WAV, and be audible (not silence). '
+    + 'Pass a package directory / package JSON for the pre-seal check, or a published vehicle item id for the read-back check. Exit 0 = every sample plays')
+    .argument('<dir|package.json|item-id>', 'package directory or file (pre-seal), or a published vehicle item UUID (read-back)')
+    .option('--json', 'print the machine-readable report')
+    .action(async (target, opts) => {
+    try {
+        const audio = await Promise.resolve().then(() => __importStar(require('./vehicle/audio')));
+        let report;
+        if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(target)) {
+            const creds = (0, config_1.loadCredentials)();
+            const apiUrl = creds?.apiUrl ?? process.env.HELIX_API_URL ?? 'https://helix-backend-api-helix3.up.railway.app';
+            const res = await fetch(`${apiUrl.replace(/\/$/, '')}/api/v1/universal-items/${target}`, { headers: { accept: 'application/json' } });
+            if (!res.ok)
+                throw new Error(`item ${target}: HTTP ${res.status}`);
+            const body = await res.json();
+            const pkg = (body.item ?? body).properties?.vehiclePackage;
+            if (!pkg)
+                throw new Error(`item ${target} carries no properties.vehiclePackage (is it a vehicle?)`);
+            report = await audio.checkAudioReadBack(pkg);
+        }
+        else {
+            const path = (0, node_path_1.resolve)(target);
+            const { statSync } = await Promise.resolve().then(() => __importStar(require('node:fs')));
+            const isDir = statSync(path).isDirectory();
+            const { readVehicleDir } = await Promise.resolve().then(() => __importStar(require('./vehicle/publish')));
+            const pkg = isDir ? readVehicleDir(path).pkg : (0, validate_1.readJsonFile)(path);
+            report = await audio.checkAudioLocal(pkg, isDir ? path : (0, node_path_1.resolve)(path, '..'));
+        }
+        printVehicleJsonOr(opts.json, report, () => console.log(audio.formatAudioReport(report)));
+        if (!report.ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        process.stderr.write(`✖ ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 2;
+    }
+});
+vehicleCommand
+    .command('grant-hides')
+    .description('Let add-ons hide your vehicle\'s real nodes: add hostGrantExtensions to the host\'s slot board (PUT /universal-items/:id/slots, read-modify-write, '
+    + 'existing grants kept). The standard board only grants `*_stock_*` globs, so a wheel add-on that hides `rim_*` fits zero hosts until this runs. '
+    + 'You must be the host item\'s creator. Each glob must match at least one host node')
+    .argument('<host-item-id>', 'your vehicle item')
+    .requiredOption('--hide <slot=glob,...>', 'board slot id = node glob pairs, e.g. whl.wheel=rim_*,pwr.exhaust=exhaust')
+    .option('--json', 'print the board grants before and after')
+    .action(async (hostId, opts) => {
+    try {
+        const add = {};
+        for (const pair of opts.hide.split(',').map((p) => p.trim()).filter(Boolean)) {
+            const eq = pair.indexOf('=');
+            if (eq <= 0 || eq === pair.length - 1)
+                throw new Error(`--hide entry "${pair}" must be <slot id>=<glob>, e.g. whl.wheel=rim_*`);
+            (add[pair.slice(0, eq)] ??= []).push(pair.slice(eq + 1));
+        }
+        const { grantHostHides } = await Promise.resolve().then(() => __importStar(require('./vehicle/addon')));
+        const creds = requireAuth();
+        const result = await grantHostHides(lib_1.HelixApi.forCredentials(creds), hostId, add);
+        printVehicleJsonOr(opts.json, { before: result.before, after: result.after }, () => {
+            console.log(`  before: ${JSON.stringify(result.before)}`);
+            console.log(`  after:  ${JSON.stringify(result.after)}`);
+            console.log(`✔ host ${hostId} grants updated`);
+        });
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof lib_1.ApiError ? error.render() : `✖ ${error instanceof Error ? error.message : String(error)}`}\n`);
+        process.exitCode = 1;
+    }
+});
+const vehicleAddOnCommand = vehicleCommand
+    .command('addon')
+    .description('Check and publish vehicle add-ons (wheels, kits, exhausts, tune parts)');
+vehicleAddOnCommand
+    .command('check')
+    .description('Prove an add-on will fit and land where it should BEFORE paying for it: the local fits/ops contract, the model\'s helixMeshFrame anchoring '
+    + '(a socket-frame part centred on its mount), per host — a vehicle, wheel origins at the hubs, hide targets present, hide grants on the board — '
+    + 'and the backend\'s own fit dry run (POST /universal-items/validate-fit: how many hosts it actually fits). '
+    + 'Directory: addon.json { title, fits, ops, ... } + model.glb. Exit 0 = fits every named host')
+    .argument('<dir>', 'the add-on directory')
+    .option('--glb <file>', 'the add-on model, when the directory holds more than one .glb')
+    .option('--grant', 'also open missing hide grants on hosts you own (helix vehicle grant-hides), then re-check')
+    .option('--json', 'print the machine-readable report')
+    .action(async (dir, opts) => {
+    try {
+        const addon = await Promise.resolve().then(() => __importStar(require('./vehicle/addon')));
+        const creds = requireAuth();
+        const report = await addon.checkAddOn(addon.readAddOnDir(dir, { glb: opts.glb }), creds, {
+            api: lib_1.HelixApi.forCredentials(creds), grant: opts.grant,
+            onProgress: (m) => { if (!opts.json)
+                console.log(`· ${m}`); },
+        });
+        printVehicleJsonOr(opts.json, report, () => console.log(addon.formatAddOnReport(report)));
+        if (!report.ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof lib_1.ApiError ? error.render() : `✖ ${error instanceof Error ? error.message : String(error)}`}\n`);
+        process.exitCode = 2;
+    }
+});
+vehicleAddOnCommand
+    .command('publish')
+    .description('Publish a vehicle add-on end to end: `vehicle addon check` (opening missing hide grants on hosts you own) → upload it → seal and pin its `addon` '
+    + 'Continuum Package (vehicle add-ons are not auto-sealed) → read back (pinned, the backend lists each host as a fit). Resumable. Published with no '
+    + 'Marketplace route: sell it with a distribution once visual QA passes. Exit 0 = published, pinned and fitting every host')
+    .argument('<dir>', 'the add-on directory (addon.json + model.glb)')
+    .option('--glb <file>', 'the add-on model, when the directory holds more than one .glb')
+    .option('--no-grant', 'never touch host boards; refuse instead when a hide grant is missing')
+    .option('--out <dir>', 'ledger / descriptor / receipt directory (default <dir>/.helix-publish)')
+    .option('--dry-run', 'run the check only; nothing is written')
+    .option('--json', 'print the machine-readable result')
+    .action(async (dir, opts) => {
+    try {
+        const addon = await Promise.resolve().then(() => __importStar(require('./vehicle/addon')));
+        const base = await vehicleContinuumDeps();
+        const say = (m) => { if (!opts.json)
+            console.log(`· ${m}`); };
+        const result = await addon.publishAddOn({ dir, glb: opts.glb, out: opts.out, noGrant: opts.grant === false, dryRun: opts.dryRun }, base.creds, {
+            api: base.api,
+            publishPackage: base.publishPackage,
+            mintItem: async (input) => {
+                const r = await (0, lib_1.publishItem)({ kind: 'add_on', title: input.title, mesh: input.mesh, thumbnail: input.thumbnail, fits: input.fits, ops: input.ops, description: input.description, tags: input.tags, slug: input.slug, noMarketplace: true }, base.creds, { onProgress: say });
+                return { id: r.id, slug: r.slug };
+            },
+            onProgress: say,
+        });
+        printVehicleJsonOr(opts.json, result, () => {
+            console.log(addon.formatAddOnReport(result.check));
+            if (result.itemId)
+                console.log(`  item:    ${result.itemId}`);
+            if (result.packagePin)
+                console.log(`  package: ${result.packagePin.packageId}@${result.packagePin.version} ${result.packagePin.manifestCid}`);
+            if (result.readBack)
+                console.log(`  read-back: pinned ${result.readBack.pinned}, fits ${JSON.stringify(result.readBack.fitsHosts)}, on host rails ${JSON.stringify(result.readBack.listedOnHosts)}`);
+            for (const step of result.next)
+                console.log(`  next: ${step}`);
+            console.log(`${result.ok ? '✔' : '✖'} add-on ${opts.dryRun ? 'check' : 'publish'}${result.ok ? '' : ' failed'}`);
+        });
+        if (!result.ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof lib_1.ApiError ? error.render() : `✖ ${error instanceof Error ? error.message : String(error)}`}\n`);
+        process.exitCode = 2;
+    }
+});
 // Validate a token against the API, then persist it. Shared by the browser
 // flow and the --token (CI/headless) path.
 async function finishLogin(apiUrl, token) {