@helix3/helix-cli 0.1.18-helix3.255 → 0.1.18-helix3.256

package/dist/index.js

@@ -47,6 +47,8 @@ const scenePerformance_1 = require("./scenePerformance");
 const lib_1 = require("./lib");
 const itemQuote_1 = require("./itemQuote");
 const itemSearch_1 = require("./itemSearch");
+const vault_1 = require("./vault");
+const looks_1 = require("./looks");
 const tables_1 = require("./itemDef/tables");
 const emoteRules_1 = require("./itemDef/emoteRules");
 const scaffold_1 = require("./itemDef/scaffold");
@@ -1210,14 +1212,14 @@ item
 // list it is always read with. `--gender`'s own help carries the same values.
 item
     .command('search')
-    .description('Search the published MARKETPLACE catalogue — including builds, the presets someone already assembled')
+    .description("Search the published MARKETPLACE catalogue — including Looks (user-facing name for a `build`: a free, never-owned preset), the dressed presets someone already assembled. A Look is never owned itself; its parts are acquired individually from their own listings")
     .argument('[query]', 'free text over title, slug and tags')
     .option('--kind <kind>', 'universal item kind (avatar, wearable, vehicle, weapon, add_on, home_item, emote, prop)')
     .option('--category <category>', 'marketplace category')
     .option('--sub-category <subCategory>', 'form factor beneath the category, e.g. car / rifle / art')
     .option('--tag <tag>', 'exact tag')
     .option('--host-kind <hostKind>', 'host class, e.g. vehicle / character / weapon')
-    .option('--builds <mode>', `builds in the results: ${itemSearch_1.BUILD_FILTER_MODES.join(' | ')} (default include — a build is filed under its base's own category, so it comes back alongside bases unless you narrow)`)
+    .option('--builds <mode>', `Looks (API identifier: builds) in the results: ${itemSearch_1.BUILD_FILTER_MODES.join(' | ')} (default include — a Look is filed under its base's own category, so it comes back alongside bases unless you narrow)`)
     .option('--limit <n>', 'rows to return (1-100, default 20)')
     .option('--json', 'machine-readable output')
     .action(async (query, opts) => {
@@ -1243,11 +1245,12 @@ item
             return;
         }
         for (const row of result.items) {
-            // The BUILD mark leads the line. A build is filed under its base's
+            // The Look mark leads the line (`buildKind` is the field's API name;
+            // "Look" is what a human reads). A Look is filed under its base's
             // own kind, so without it these rows are indistinguishable from the
-            // bases they were assembled from — which is the whole reason builds
+            // bases they were assembled from — which is the whole reason Looks
             // do not get a category of their own.
-            const mark = row.buildKind ? `[build:${row.buildKind}] ` : '';
+            const mark = row.buildKind ? `[look:${row.buildKind}] ` : '';
             const price = row.priceLix === null ? 'unlisted' : `Ⱡ${row.priceLix}`;
             console.log(`${mark}${row.title}  (${row.kind}, ${price})`);
             console.log(`  ${row.id}${row.creator ? `  by ${row.creator}` : ''}`);
@@ -1262,7 +1265,7 @@ item
 });
 item
     .command('build')
-    .description("What is in a published build: its base, its parts, what you own, and what the parts cost together")
+    .description("What is in a published Look (API identifier: build): its base, its add-on parts, what you own, and what the parts cost together. A Look is never owned itself — only its parts are, each bought or held from its own listing")
     .argument('<itemId>', 'universal item id of the build')
     .option('--json', 'machine-readable output')
     .action(async (itemId, opts) => {
@@ -2161,6 +2164,113 @@ product
         fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
     }
 });
+// --- helix vault -------------------------------------------------------------
+// The Continuum Vault catalog (`GET /api/v1/vault/catalog`) — the table that
+// backs the website's Vault page and actually lists Looks (build Packages),
+// characters, vehicles, weapons, devices, and every other sealed Continuum
+// Package. Distinct from `helix assets search`, which hits the LEGACY
+// `/api/v1/vault/assets` table and has no Looks and never will.
+const vault = program
+    .command('vault')
+    .description('Discover sealed Continuum Packages — including Looks — through the public Vault catalog');
+vault
+    .command('search')
+    .description('Search the Continuum Vault catalog. Finds Looks (pass --package-type look) and every other sealed, listed Continuum Package. Public — no login required')
+    .argument('[query]', 'free-text search over title and tags')
+    .option('--package-type <type>', `filter by Continuum Package type. "look" is accepted as an alias for "build" (${vault_1.VAULT_CATALOG_PACKAGE_TYPE_INPUTS.join(', ')})`)
+    .option('--sort <mode>', 'recent or name')
+    .option('--cursor <token>', 'pagination cursor from a previous nextCursor')
+    .option('--limit <n>', 'page size (1-100)')
+    .action(async (query, opts) => {
+    const creds = (0, config_1.loadCredentials)();
+    const apiUrl = creds?.apiUrl ?? config_1.DEFAULT_API_URL;
+    if (opts.sort && !['recent', 'name'].includes(opts.sort)) {
+        fail('✖ --sort must be recent or name');
+    }
+    try {
+        printJson(await (0, vault_1.searchVaultCatalog)(apiUrl, {
+            q: query,
+            packageType: opts.packageType,
+            sort: opts.sort,
+            cursor: opts.cursor,
+            limit: optionalNumber(opts.limit, '--limit'),
+        }, creds ?? undefined));
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// --- helix look --------------------------------------------------------------
+// A Look is a Universal Item pinned to a Continuum Package of type `build`: a
+// free, never-owned preset — a base plus the exact add-ons installed on it.
+// Its parts are still owned and acquired individually from their own listings;
+// applying a Look never grants, buys, or moves anything the caller does not
+// already own. Contract: run/open-alpha-qa/looks/phase2-contract.txt (items 4
+// and 6) in the workspace root.
+const look = program
+    .command('look')
+    .description('Read and save Looks — dressed-character presets (API identifier: build)');
+look
+    .command('get')
+    .description('The dressed character behind one Look in a single public call: base model plus every add-on, with pinned Packages, model URLs/CIDs, and fit data — enough to render it')
+    .argument('<ref>', 'Look item id, or packageId@version (an @ splits packageId from an explicit version; without one, the value is read as an item id)')
+    .option('--json', 'machine-readable output')
+    .action(async (ref, opts) => {
+    const creds = (0, config_1.loadCredentials)();
+    const apiUrl = creds?.apiUrl ?? config_1.DEFAULT_API_URL;
+    const api = creds ? lib_1.HelixApi.forCredentials(creds) : new lib_1.HelixApi(apiUrl);
+    try {
+        const result = await (0, looks_1.resolveLook)(api, (0, looks_1.parseLookRef)(ref));
+        if (opts.json)
+            return printJson(result);
+        console.log(`${result.look.title ?? result.look.packageId} (${result.look.kind})`);
+        console.log(`  base: ${result.base.item?.title ?? result.base.package.packageId}`);
+        if (result.base.model)
+            console.log(`        ${result.base.model.url}`);
+        for (const addOn of result.addOns) {
+            console.log(`  + [${addOn.slot}] ${addOn.item?.title ?? addOn.package.packageId}`);
+            if (addOn.model)
+                console.log(`        ${addOn.model.url}`);
+        }
+        console.log(result.merged
+            ? `\nmerged Runtime Artifact: ${result.merged.url}`
+            : '\nno merged Runtime Artifact yet — assemble base + add-ons at runtime');
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+look
+    .command('save')
+    .description("Freeze an inventory instance's current composition into a Look. Never charges a publish fee, never grants a copy of any part, never creates a distribution — it publishes the recipe, not the parts")
+    .argument('<inventory-item-id>', 'inventory instance to freeze')
+    .requiredOption('--title <title>', 'Look title (1-80 chars)')
+    .option('--description <text>', 'Look description (<=500 chars)')
+    .option('--public', 'publish publicly (sealed public Package + Vault + Marketplace listings); default is private')
+    .option('--look <lookItemId>', 'an existing Look you created — advances it to a new version instead of creating a new one')
+    .option('--json', 'machine-readable output')
+    .action(async (inventoryItemId, opts) => {
+    const creds = requireAuth();
+    try {
+        const result = await (0, looks_1.saveLook)(lib_1.HelixApi.forCredentials(creds), inventoryItemId, {
+            title: opts.title,
+            description: opts.description,
+            visibility: opts.public ? 'public' : 'private',
+            lookItemId: opts.look,
+        });
+        if (opts.json)
+            return printJson(result);
+        console.log(`✔ ${result.created ? 'Saved' : 'Updated'} Look ${result.lookItemId} (${result.visibility})`);
+        console.log(`  package: ${result.package.packageId}@${result.package.version}`);
+        if (result.vaultListingId)
+            console.log(`  vault listing: ${result.vaultListingId}`);
+        if (result.marketplaceListingId)
+            console.log(`  marketplace listing: ${result.marketplaceListingId}`);
+    }
+    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