@helix3/helix-cli 0.1.13-helix3.79 → 0.1.13-helix3.82

package/README.md

@@ -41,7 +41,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix init <dir>` | Scaffold a minimal Three.js world (`helix.json` + `index.html` + `main.js`). |
 | `helix install [--update]` | Resolve a world's `systems`/`abilities` pins (a v0.2 **or v0.3** manifest) → materialize the modules, the `three` import map, and `helix.runtime.ts`. |
 | `helix validate [dir]` | Validate a bundle locally — the exact rules the server enforces. |
-| `helix publish [dir] [--thumbnail <file>]` | Validate → resolve/create the world → upload files → finalize → set the cover image → print the play URL. |
+| `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 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> [--kind <k>] [--slot <tag>] [--gender <g>] [--price-lix <n> \| --personal] [--thumbnail <f>] [--dry-run]` | Publish a universal item (wearable / avatar / home item) from one `.glb`; the server verifies the mesh inline. |
@@ -71,6 +71,29 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 5. `POST /api/v1/instant-worlds/:id/builds/:buildId/finalize` → byte-exact verify, activate, publish.
 6. `GET /api/v1/instant-worlds/:slug` → the play URL.
 
+### Opt-in source upload
+
+A published world ships only its **built bundle**, so there is nothing on the server to edit later.
+`--upload-source` adds a second, separate upload that fixes that:
+
+7. `POST /api/v1/instant-worlds/:id/source` → a presigned PUT into a **private** bucket (this call
+   also adopts the world into a project, which is the key its future workspace hangs from).
+8. `helix-source.tar.gz` PUT with `cache-control: no-store`.
+9. `POST /api/v1/instant-worlds/:id/source/finalize` → the server verifies the stored byte count
+   equals the declared one, then records the version.
+
+- **Off by default.** Source is never sent unless you pass the flag. Not a prompt — an interactive
+  confirm would break CI and agent-driven publishes.
+- **What goes in**: the project directory, honouring `.gitignore`, always excluding `node_modules`,
+  `.git`, `dist` and `.vite` — the same exclude set the website's own workspace checkpoints use.
+- **Which directory**: `[dir]` is the BUILT bundle, so the source defaults to its parent. Override
+  with `--source-dir <path>`.
+- **Never part of the build.** The bundle's content-type allowlist rejects archives, raw `.ts` is
+  excluded from a bundle by design, the bundle size budget is the playable budget, and every build
+  file lands on a public CDN path with a year-long immutable cache. Source uses its own private
+  channel for exactly that reason.
+- **Limit**: 128 MiB compressed, checked locally before anything is uploaded.
+
 The programmatic surface (`publishWorld`, `checkBundle`, `whoAmI`, …) is exported for other CLI
 modules. Agent integrations should instruct or delegate to the `helix` commands above rather than
 reimplementing operational behavior in a transport package.

package/dist/index.js

@@ -308,6 +308,11 @@ program
     .option('--skip-subpath-check', 'skip the pre-publish sub-path load check (not recommended: it is the only gate that serves the bundle the way production does)')
     .option('--description <text>', `catalog description, max ${lib_1.WORLD_DESCRIPTION_MAX} chars (pass "" to clear). helix.json cannot carry this — the manifest schema forbids unknown fields`)
     .option('--description-file <path>', 'read the catalog description from a file')
+    .option('--upload-source', "Also upload this project's source so you can edit this world from the HELIX website later. " +
+    'Off by default — your source is not sent unless you pass this.')
+    .option('--source-dir <path>', "project directory to archive for --upload-source (default: the bundle directory's parent, " +
+    'since [directory] points at the BUILT bundle). node_modules, .git, dist and .vite are always excluded, ' +
+    'as is anything your .gitignore excludes')
     .action(async (directory, opts) => {
     // Pure input checks first — bad flags should fail before auth, the network, or any upload.
     if (opts.description !== undefined && opts.descriptionFile) {
@@ -325,6 +330,9 @@ program
     if (description !== undefined && description.length > lib_1.WORLD_DESCRIPTION_MAX) {
         fail(`✖ description is ${description.length} chars; the limit is ${lib_1.WORLD_DESCRIPTION_MAX}. Nothing was published.`);
     }
+    if (opts.sourceDir && !opts.uploadSource) {
+        fail('✖ --source-dir only means something with --upload-source. Source is never uploaded unless you ask for it.');
+    }
     const creds = requireAuth();
     const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
     if (mismatch)
@@ -353,6 +361,8 @@ program
         const result = await (0, lib_1.publishWorld)((0, node_path_1.resolve)(directory), creds, (msg) => console.log(msg), {
             thumbnail: opts.thumbnail ? (0, node_path_1.resolve)(opts.thumbnail) : undefined,
             description,
+            uploadSource: opts.uploadSource,
+            sourceDir: opts.sourceDir ? (0, node_path_1.resolve)(opts.sourceDir) : undefined,
         });
         console.log(`✔ Published "${result.title}" build ${result.buildNumber}`);
         if (result.playUrl)
@@ -363,6 +373,10 @@ program
         }
         if (result.thumbnailWarning)
             console.warn(`  • ${result.thumbnailWarning}`);
+        // Spec §9.3: one line about source, every publish, as a FACT — not a
+        // warning and never repeated. It is what tells a creator that editing on
+        // the website is a thing, and that it did not happen behind their back.
+        console.log(`  ${(0, lib_1.sourceOutcomeLine)(result.source, creds.apiUrl)}`);
     }
     catch (err) {
         fail(err instanceof lib_1.ApiError
@@ -774,6 +788,255 @@ achievement
         fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
     }
 });
+// --- helix product ---------------------------------------------------------
+// The registry `Helix.purchase` sells from: a world can only sell what its
+// creator registered here, and registering was API/website-only until these
+// commands. ORDER, the INVERSE of achievements: publish the world FIRST — the
+// creator registry lists Published worlds only, and nobody can buy inside a
+// world they cannot enter. Worlds are named by SLUG, products by their key.
+const product = program
+    .command('product')
+    .description("Register and manage a world's in-world products (what Helix.purchase sells). Publish the world FIRST — unlike achievements, a product only counts once the world is Published");
+function renderProduct(p, indent = '  ') {
+    // An authored-grants product's stored type is server-DERIVED — the effect list is the truth,
+    // so the "your world applies it" hint only fits legacy consumables.
+    const lines = [
+        `${indent}price:    ${p.priceLix} LIX${p.isFree ? ' — free "Claim"' : ''}`,
+        `${indent}type:     ${p.type}${p.type === 'consumable' && !p.grants ? ' — your world applies the effect on a Granted result' : ''}`,
+    ];
+    // The key is how world code names it; without one the uuid is the only handle.
+    lines.push(`${indent}buy as:   ${p.key ? `pkey:${p.key}` : `${p.id} (no key — register with --key next time)`}`);
+    if (p.grants) {
+        const effects = p.grants.map((g) => g.kind === 'item'
+            ? `item ${g.itemId}${(g.quantity ?? 1) > 1 ? ` ×${g.quantity}` : ''}`
+            : g.kind === 'pass'
+                ? `pass ${g.passKey ?? p.key ?? '(product key)'}${g.durationSeconds ? ` for ${g.durationSeconds}s` : ''}`
+                : `currency ${g.code} +${g.amount}`);
+        lines.push(`${indent}grants:   ${effects.length ? effects.join(', ') : 'nothing — a tip jar'}`);
+    }
+    else if (p.itemId) {
+        lines.push(`${indent}grants:   item ${p.itemId}`);
+    }
+    if (p.maxPerUser !== null)
+        lines.push(`${indent}max/user: ${p.maxPerUser}`);
+    if (!p.active)
+        lines.push(`${indent}active:   no — off sale, existing owners keep theirs`);
+    lines.push(`${indent}id:       ${p.id}`);
+    return lines;
+}
+// The effect list arrives as one JSON string. Only "is it an array" is checked
+// here — every shape rule belongs to the vocabulary, which reports them together.
+function parseGrantsFlag(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        fail(`✖ --grants must be a JSON array of effects — that is not valid JSON (${detail})`);
+    }
+    if (!Array.isArray(parsed)) {
+        fail('✖ --grants must be a JSON array of effects, e.g. \'[{"kind":"currency","code":"coin","amount":500}]\' (several = a bundle, [] = a tip jar)');
+    }
+    return parsed;
+}
+product
+    .command('register')
+    .description('Register a purchasable product on one of your PUBLISHED worlds — one round trip, live as soon as it returns')
+    .argument('<world-slug>', 'the world that sells it')
+    .requiredOption('--title <title>', 'name the purchase popup shows the player (max 120 chars)')
+    .requiredOption('--price <lix>', 'price in LIX; 0 registers a free "Claim" (a confirmation, no spend)')
+    .option('--type <type>', `what the purchase does: ${lib_1.WORLD_PRODUCT_TYPES.join(' | ')} — required unless you author --grants`)
+    .option('--grants <json>', `JSON array of what the purchase hands over, instead of --type/--item-id: item | pass | currency, max ${lib_1.MAX_GRANT_EFFECTS} ` +
+    "(e.g. '[{\"kind\":\"currency\",\"code\":\"coin\",\"amount\":500}]'; [] = a tip jar). Fixed at registration")
+    .option('--key <key>', 'stable slug world code buys as `pkey:<key>` (max 64 chars, lowercase a-z0-9_-); it cannot be renamed later')
+    .option('--description <text>', 'what the player is buying')
+    .option('--item-id <uuid>', 'the universal item handed over — REQUIRED for item_grant and non_consumable, refused for consumable')
+    .option('--max-per-user <n>', 'cap on how many one player may own (whole number >= 1)')
+    .option('--dry-run', 'validate everything locally and print what WOULD be sent; no network, works logged out')
+    .option('--json', 'machine-readable output')
+    .action(async (worldSlug, opts) => {
+    const registration = {
+        worldSlug,
+        key: opts.key,
+        title: opts.title,
+        description: opts.description,
+        priceLix: Number(opts.price),
+        type: opts.type,
+        itemId: opts.itemId,
+        grants: opts.grants !== undefined ? parseGrantsFlag(opts.grants) : undefined,
+        maxPerUser: opts.maxPerUser !== undefined ? parseWholeNumber(opts.maxPerUser, '--max-per-user') : undefined,
+    };
+    // Stops before ANY network call, so it works logged out — the point is to
+    // check the vocabulary and the type/item coherence, not the account.
+    if (opts.dryRun) {
+        try {
+            const plan = (0, lib_1.planProductRegistration)(registration);
+            if (opts.json) {
+                console.log(JSON.stringify({ dryRun: true, worldSlug, fields: plan.fields, warnings: plan.warnings }, null, 2));
+                return;
+            }
+            console.log('✔ Dry run — nothing sent.');
+            console.log(`  POST /api/v1/iwp/products (worldId of "${worldSlug}")`);
+            console.log(`  body:   ${JSON.stringify(plan.fields, null, 2).replace(/\n/g, '\n          ')}`);
+            for (const warning of plan.warnings)
+                console.log(`  • ${warning}`);
+            if (!(0, lib_1.authStatus)().loggedIn)
+                console.log('  • not logged in — run `helix login` before the real registration');
+        }
+        catch (err) {
+            fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
+    const creds = requireAuth();
+    const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
+    if (mismatch)
+        fail(`✖ Refusing to register:\n${mismatch}`);
+    try {
+        const { product: created, warnings } = await (0, lib_1.registerProduct)(registration, creds, {
+            onProgress: (msg) => !opts.json && console.log(msg),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ product: created, warnings }, null, 2));
+            return;
+        }
+        console.log(`✔ Registered "${created.title}" on ${worldSlug}`);
+        for (const line of renderProduct(created))
+            console.log(line);
+        for (const warning of warnings)
+            console.log(`  ⚠ ${warning}`);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+product
+    .command('list')
+    .description("List a world's registered products, or — with no slug — every PUBLISHED world of yours and what it sells")
+    .argument('[world-slug]', 'the world that sells them; omit for all your published worlds')
+    .option('--json', 'machine-readable output')
+    .action(async (worldSlug, opts) => {
+    const creds = requireAuth();
+    try {
+        if (!worldSlug) {
+            const worlds = await (0, lib_1.listProductWorlds)(creds);
+            if (opts.json) {
+                console.log(JSON.stringify(worlds, null, 2));
+                return;
+            }
+            if (worlds.length === 0) {
+                console.log('You have no published worlds — `helix publish` one first; a product on a draft world is unbuyable.');
+                return;
+            }
+            for (const world of worlds) {
+                console.log(`\n${world.slug} — "${world.title}" (${world.products.length} product${world.products.length === 1 ? '' : 's'})`);
+                for (const row of world.products) {
+                    console.log(`  ${row.key ?? row.id} — "${row.title}" · ${row.priceLix} LIX · ${row.type}${row.active ? '' : ' [INACTIVE]'}`);
+                }
+            }
+            return;
+        }
+        const rows = await (0, lib_1.listProducts)(worldSlug, creds);
+        if (opts.json) {
+            console.log(JSON.stringify(rows, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log(`No products registered on "${worldSlug}" yet — register one with: helix product register ${worldSlug} --title … --type … --price …`);
+            return;
+        }
+        console.log(`${rows.length} product${rows.length === 1 ? '' : 's'} on ${worldSlug}:`);
+        for (const row of rows) {
+            console.log(`\n  ${row.key ?? row.id} — "${row.title}"${row.active ? '' : ' [INACTIVE]'}`);
+            console.log(`    ${row.priceLix} LIX · ${row.type}${row.itemId ? ` · grants ${row.itemId}` : ''}${row.maxPerUser !== null ? ` · max ${row.maxPerUser}/user` : ''}`);
+        }
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+product
+    .command('update')
+    .description('Patch a registered product. The key and the type are fixed at registration — world code buys the key, and changing what a purchase hands over would re-label every copy already sold')
+    .argument('<world-slug>', 'the world that sells it')
+    .argument('<product>', 'the product key (or its uuid, if you registered it without a key)')
+    .option('--title <title>', 'new title')
+    .option('--description <text>', 'new description')
+    .option('--price <lix>', 'new price in LIX; 0 makes it a free "Claim"')
+    .option('--max-per-user <n>', 'new per-player ownership cap (whole number >= 1)')
+    .option('--active <true|false>', 'false takes it off sale — existing owners keep theirs, nobody new can buy it')
+    .option('--dry-run', 'validate the patch locally and print what WOULD be sent; no network, works logged out')
+    .option('--json', 'machine-readable output')
+    .action(async (worldSlug, ref, opts) => {
+    const patch = {
+        title: opts.title,
+        description: opts.description,
+        priceLix: opts.price !== undefined ? Number(opts.price) : undefined,
+        maxPerUser: opts.maxPerUser !== undefined ? parseWholeNumber(opts.maxPerUser, '--max-per-user') : undefined,
+        active: opts.active !== undefined ? parseBooleanFlag(opts.active, '--active') : undefined,
+    };
+    if (opts.dryRun) {
+        try {
+            const body = (0, lib_1.buildProductUpdate)(patch);
+            if (opts.json) {
+                console.log(JSON.stringify({ dryRun: true, worldSlug, product: ref, patch: body }, null, 2));
+                return;
+            }
+            console.log('✔ Dry run — nothing sent.');
+            console.log(`  PATCH /api/v1/iwp/products/<id of "${ref}" on ${worldSlug}>`);
+            console.log(`  body:  ${JSON.stringify(body, null, 2).replace(/\n/g, '\n         ')}`);
+        }
+        catch (err) {
+            fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
+    const creds = requireAuth();
+    const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
+    if (mismatch)
+        fail(`✖ Refusing to update:\n${mismatch}`);
+    try {
+        const updated = await (0, lib_1.updateProduct)(worldSlug, ref, patch, creds);
+        if (opts.json) {
+            console.log(JSON.stringify(updated, null, 2));
+            return;
+        }
+        console.log(`✔ Updated "${updated.title}" on ${worldSlug}`);
+        for (const line of renderProduct(updated))
+            console.log(line);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+product
+    .command('set-active')
+    .description('Put a product on sale or take it off. The row stays either way, so past purchases and their grants keep resolving')
+    .argument('<world-slug>', 'the world that sells it')
+    .argument('<product>', 'the product key (or its uuid)')
+    .argument('<true|false>', 'true puts it on sale, false takes it off')
+    .option('--json', 'machine-readable output')
+    .action(async (worldSlug, ref, value, opts) => {
+    const active = parseBooleanFlag(value, '<true|false>');
+    const creds = requireAuth();
+    const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
+    if (mismatch)
+        fail(`✖ Refusing to change what a world sells:\n${mismatch}`);
+    try {
+        const updated = await (0, lib_1.setProductActive)(worldSlug, ref, active, creds);
+        if (opts.json) {
+            console.log(JSON.stringify(updated, null, 2));
+            return;
+        }
+        console.log(`✔ "${updated.title}" is ${updated.active ? 'ON SALE' : 'off sale'} on ${worldSlug}`);
+        for (const line of renderProduct(updated))
+            console.log(line);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
 // --- helix assets ----------------------------------------------------------
 // Operational asset work lives here. MCP surfaces may point agents at these
 // commands, but they must not reimplement Vault, Dreamer, download, or receipt