@helix3/helix-cli 0.1.18-helix3.312 → 0.1.18-helix3.314

package/README.md

@@ -48,6 +48,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `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. |
+| `helix item visual-qa <item-id> [--submit] [--local-critic] [--storage-state <file>] [--host <id…>]` | Render the item's current package version headless in the real runtime (test-grounds world for vehicles, the customiser for add-ons and wearables on every declared host/base, the item viewer for props), measure it, and with `--submit` record the backend's verdict (numeric asserts + vision critic) against that exact version. **Marketplace/Vault listing, distributions and version moves on a public item require a pass.** See [docs/visual-qa.md](docs/visual-qa.md). |
 | `helix device create <dir> --id <slug> --title <t> --model <mesh.glb> --template standing-desk\|clock\|television` | Scaffold a GLB-backed `helix.device/1` definition, including the interactive TV/media-player template. There is intentionally no website Device editor. |
 | `helix device validate [dir] [--json]` | Validate the definition, GLB bytes and named-node bindings, typed state/controls, capabilities, and Home+World compatibility, including [declarative character hand reach](docs/device-hand-reach.md). |
 | `helix device test [dir] [--mode single\|multiplayer\|both] [--json]` | Exercise every interaction, persistence remount, and deterministic one-/two-client authority convergence. |

package/dist/config.d.ts

@@ -15,6 +15,9 @@ export declare function resolveEnvironment(scope: string, override?: {
     apiUrl: string;
     webUrl: string;
 };
+/** The website that belongs to an API origin, when it is one of ours (visual QA renders on the site that serves the
+ *  API the item lives on, not on this build's default site). */
+export declare function webUrlForApi(apiUrl: string): string | null;
 export declare const HELIX_SCOPE: string;
 export declare const HELIX_ENV: HelixEnvName;
 export declare const DEFAULT_API_URL: string;

package/dist/config.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_WEB_URL = exports.DEFAULT_API_URL = exports.HELIX_ENV = exports.HELIX_SCOPE = exports.CONFIG_DIR = void 0;
 exports.resolveEnvironment = resolveEnvironment;
+exports.webUrlForApi = webUrlForApi;
 exports.apiUrlMatchesEnv = apiUrlMatchesEnv;
 exports.credsEnvMismatchWarning = credsEnvMismatchWarning;
 exports.saveCredentials = saveCredentials;
@@ -68,6 +69,16 @@ const RESOLVED = resolveEnvironment(ownScope(), {
     apiUrl: process.env.HELIX_API_URL,
     webUrl: process.env.HELIX_WEB_URL,
 });
+/** The website that belongs to an API origin, when it is one of ours (visual QA renders on the site that serves the
+ *  API the item lives on, not on this build's default site). */
+function webUrlForApi(apiUrl) {
+    const n = normalizeApiUrlForEnv(apiUrl);
+    for (const env of Object.values(ENVIRONMENTS))
+        if (normalizeApiUrlForEnv(env.apiUrl) === n)
+            return env.webUrl;
+    return null;
+}
+const normalizeApiUrlForEnv = (url) => url.trim().replace(/\/+$/, '').toLowerCase();
 exports.HELIX_SCOPE = RESOLVED.scope;
 exports.HELIX_ENV = RESOLVED.env;
 exports.DEFAULT_API_URL = RESOLVED.apiUrl;

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1686,6 +1686,167 @@ item
 // Distinct from `item distribution disable` below: a distribution is ONE
 // acquisition route (you can have several); delist takes the whole item
 // definition off browse/marketplace regardless of how many routes it has.
+// Visual QA: the publish/listing gate judges an item RENDERED, in the real runtime, not its numbers. This command is
+// the harness: it renders the item's current package version headless (test-grounds world for vehicles, the
+// customiser for add-ons and wearables, the item viewer for props), measures it, and with --submit hands it to the
+// backend, which runs the vision critic, records the verdict against that exact version and serves a contact sheet.
+item
+    .command('visual-qa')
+    .description('Render an item headless in the real HELIX runtime, measure it, and (with --submit) record the visual-QA verdict that Marketplace/Vault listing requires. --hosted asks the platform to render it on a GPU runner instead')
+    .argument('[item-id]', 'universal item UUID (its CURRENT package version is rendered); omit with --hosted-worker')
+    .option('--submit', 'submit frames + measurements to the backend, which judges and records the verdict (needs `helix login`)')
+    .option('--hosted', 'queue a hosted render on the platform GPU runner and wait for the verdict (needs `helix login`; exit 0 pass, 1 fail, 2 error)')
+    .option('--retry', 'with --hosted: re-queue after a failed/errored hosted run of this version')
+    .option('--no-wait', 'with --hosted: queue the render and return without waiting')
+    .option('--timeout <minutes>', 'with --hosted: how long to wait for the verdict', '30')
+    .option('--status', 'read-only: show the hosted visual-QA state and recorded result for the item (no login needed)')
+    .option('--hosted-worker', 'runner mode: claim hosted render jobs, render, submit (HELIX_VQA_BOT_EMAIL / HELIX_VQA_BOT_PASSWORD)')
+    .option('--max-jobs <n>', 'with --hosted-worker: stop after n jobs')
+    .option('--max-minutes <n>', 'with --hosted-worker: stop claiming new jobs after n minutes')
+    .option('--idle-exit-minutes <n>', 'with --hosted-worker: keep polling an empty queue this long before exiting', '0')
+    .option('--poll-seconds <n>', 'with --hosted-worker: queue polling interval', '10')
+    .option('--render-timeout <seconds>', 'with --hosted-worker: hard limit per render', '900')
+    .option('--worker <name>', 'with --hosted-worker: runner identity recorded on the job')
+    .option('--local-critic', 'also run the vision critic locally (needs ANTHROPIC_API_KEY or OPENROUTER_API_KEY)')
+    .option('--out <dir>', 'bundle directory (frames, bundle.json, contact-sheet.jpg)')
+    .option('--storage-state <file>', 'Playwright storageState of a signed-in QA account (Try Now and the customiser need one); default $HELIX_VQA_STORAGE_STATE')
+    .option('--host <id...>', 'only fit onto these host/base item ids (add-ons, wearables)')
+    .option('--chrome <path>', 'Chrome/Chromium executable (default: system Chrome, headless)')
+    .option('--api-url <url>', 'platform API base URL')
+    .option('--web-url <url>', 'website base URL (default: the site that serves --api-url)')
+    .option('--json', 'print the outcome as JSON')
+    .action(async (id, opts) => {
+    try {
+        const creds = opts.submit || opts.hosted ? requireAuth() : (0, config_1.loadCredentials)();
+        const apiBase = opts.apiUrl ?? creds?.apiUrl ?? config_1.DEFAULT_API_URL;
+        const webBase = opts.webUrl ?? process.env.HELIX_WEB_URL ?? (0, config_1.webUrlForApi)(apiBase) ?? config_1.DEFAULT_WEB_URL;
+        if (opts.hostedWorker) {
+            const email = process.env.HELIX_VQA_BOT_EMAIL;
+            const password = process.env.HELIX_VQA_BOT_PASSWORD;
+            if (!email || !password)
+                fail('✖ --hosted-worker needs HELIX_VQA_BOT_EMAIL and HELIX_VQA_BOT_PASSWORD in the environment');
+            const { runHostedWorker } = await Promise.resolve().then(() => __importStar(require('./visualQa/hosted')));
+            const workerApi = opts.apiUrl ?? process.env.HELIX_API_URL ?? config_1.DEFAULT_API_URL; // never a stored login: the runner is its own account
+            const summary = await runHostedWorker({
+                apiBase: workerApi,
+                webBase: opts.webUrl ?? process.env.HELIX_WEB_URL ?? (0, config_1.webUrlForApi)(workerApi) ?? config_1.DEFAULT_WEB_URL,
+                email,
+                password,
+                worker: opts.worker ?? process.env.HELIX_VQA_WORKER,
+                maxJobs: opts.maxJobs ? Number(opts.maxJobs) : undefined,
+                maxMinutes: opts.maxMinutes ? Number(opts.maxMinutes) : undefined,
+                idleExitMinutes: Number(opts.idleExitMinutes ?? 0),
+                pollSeconds: Number(opts.pollSeconds ?? 10),
+                renderTimeoutSeconds: Number(opts.renderTimeout ?? 900),
+                out: opts.out,
+                chrome: opts.chrome,
+                cliVersion: (0, lib_1.cliVersion)(),
+            });
+            if (opts.json)
+                console.log(JSON.stringify(summary, null, 2));
+            else
+                console.log(`hosted worker done (${summary.exit}): ${summary.jobs.length} job(s)${summary.jobs.map((j) => `\n  ${j.jobId} ${j.outcome}${j.verdict ? ` ${j.verdict}` : ''}${j.error ? ` — ${j.error.slice(0, 120)}` : ''}`).join('')}`);
+            return; // a failing item or a reported harness error is the queue's business; the runner itself succeeded
+        }
+        if (!id)
+            fail('✖ visual-qa needs an <item-id> (omit it only with --hosted-worker)');
+        if (opts.status || opts.hosted) {
+            const hosted = await Promise.resolve().then(() => __importStar(require('./visualQa/hosted')));
+            if (opts.status) {
+                const st = await hosted.getItemVisualQaStatus(apiBase, id);
+                const job = st.hostedJob;
+                if (opts.json)
+                    console.log(JSON.stringify(st, null, 2));
+                else {
+                    console.log(`hosted job: ${hosted.describeJob(job)}`);
+                    if (job?.contactSheetUrl)
+                        console.log(`  contact sheet: ${job.contactSheetUrl}`);
+                    for (const r of job?.reasons ?? [])
+                        console.log(`  - ${r}`);
+                    if (job?.error)
+                        console.log(`  error: ${job.error}`);
+                    console.log(`current version: ${st.currentVersion ? (st.currentVersion.passed ? 'PASSED' : 'no passing run') : 'not pinned to a package version'}`);
+                }
+                process.exitCode = job && hosted.isTerminal(job.status) ? hosted.exitCodeForJob(job) : 0;
+                return;
+            }
+            const token = creds?.token;
+            const req = await hosted.requestHostedRun(apiBase, token, id, !!opts.retry);
+            if (!opts.json) {
+                if (req.alreadyPassed)
+                    console.log('✔ this version already has a passing visual-QA run');
+                else if (req.exempt)
+                    console.log('✔ exempt: this item has nothing to render');
+                else if (!req.job)
+                    console.log(`✖ nothing queued${req.skipped ? ` (${req.skipped})` : ''}${req.message ? `: ${req.message}` : ''}`);
+                else
+                    console.log(`hosted render: ${hosted.describeJob(req.job)}`);
+            }
+            let job = req.job;
+            let timedOut = false;
+            if (job && !hosted.isTerminal(job.status) && opts.wait !== false) {
+                const waited = await hosted.waitForHostedJob(apiBase, id, job.id, {
+                    timeoutMs: Number(opts.timeout ?? 30) * 60_000,
+                    onUpdate: (j) => { if (!opts.json)
+                        console.log(`  ${hosted.describeJob(j)}`); },
+                });
+                job = waited.job;
+                timedOut = waited.timedOut;
+            }
+            if (opts.json)
+                console.log(JSON.stringify({ ...req, job, timedOut }, null, 2));
+            else if (job && hosted.isTerminal(job.status)) {
+                console.log(`${job.status === 'passed' ? '✔' : '✖'} visual QA ${job.status.toUpperCase()}`);
+                for (const r of job.reasons)
+                    console.log(`  - ${r}`);
+                if (job.error)
+                    console.log(`  error: ${job.error}`);
+                if (job.contactSheetUrl)
+                    console.log(`  contact sheet: ${job.contactSheetUrl}`);
+            }
+            else if (timedOut)
+                console.log(`… still ${job?.status ?? 'queued'} after ${opts.timeout ?? 30} min; check later with: helix item visual-qa ${id} --status`);
+            else if (job)
+                console.log(`  check later with: helix item visual-qa ${id} --status`);
+            process.exitCode = req.alreadyPassed || req.exempt ? 0 : job && !hosted.isTerminal(job.status) && opts.wait === false ? 0 : hosted.exitCodeForJob(job, timedOut);
+            return;
+        }
+        const { runVisualQa } = await Promise.resolve().then(() => __importStar(require('./visualQa/command')));
+        const outcome = await runVisualQa(id, {
+            apiBase,
+            webBase,
+            token: creds?.token ?? null,
+            out: opts.out,
+            storageState: opts.storageState ?? process.env.HELIX_VQA_STORAGE_STATE,
+            hostIds: opts.host,
+            chrome: opts.chrome,
+            submit: opts.submit,
+            localCritic: opts.localCritic,
+            cliVersion: (0, lib_1.cliVersion)(),
+            quiet: opts.json,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ verdict: outcome.verdict, reasons: outcome.reasons, bundleDir: outcome.bundleDir, contactSheet: outcome.contactSheet, server: outcome.server, critic: outcome.critic, timings: outcome.timings }, null, 2));
+        }
+        else {
+            const mark = outcome.verdict === 'pass' ? '✔' : '✖';
+            console.log(`${mark} visual QA ${outcome.verdict.toUpperCase()} — ${outcome.bundle.item.title} (${outcome.bundle.item.category}, package ${outcome.bundle.item.packageVersion ?? '?'})`);
+            for (const r of outcome.reasons)
+                console.log(`  - ${r}`);
+            if (outcome.contactSheet)
+                console.log(`  contact sheet: ${outcome.contactSheet}`);
+            if (outcome.server?.contactSheetUrl)
+                console.log(`  recorded: ${outcome.server.contactSheetUrl}`);
+            if (!opts.submit)
+                console.log('  (local run only — add --submit to record the verdict the listing gate checks)');
+            console.log(`  ${(outcome.timings.totalMs / 1000).toFixed(1)} s (render ${(outcome.timings.renderMs / 1000).toFixed(1)} s)`);
+        }
+        process.exitCode = outcome.verdict === 'pass' ? 0 : outcome.verdict === 'fail' ? 1 : 2;
+    }
+    catch (error) {
+        fail(error instanceof lib_1.ApiError ? error.render() : String(error?.message ?? error));
+    }
+});
 item
     .command('delist')
     .description('Unlist a published item you own — existing owners keep what they own, nobody new can acquire it. Not a delete (see `helix item publish` for why delete refuses an owned item), and not currently reversible.')