@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/unrealPublish.js

@@ -0,0 +1,331 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWorldId = resolveWorldId;
+exports.assertCreateResponseMatchesPlan = assertCreateResponseMatchesPlan;
+exports.assertReceipt = assertReceipt;
+exports.uploadArtifact = uploadArtifact;
+exports.publishUnrealBuild = publishUnrealBuild;
+exports.assertClientDeliveryMatchesPlan = assertClientDeliveryMatchesPlan;
+exports.renderPublishFailure = renderPublishFailure;
+/**
+ * The Unreal publish UPLOAD leg: presign → PUT → finalize → promote.
+ *
+ * Before this existed a creator could cook an Unreal world and had no way to
+ * get it to HELIX. The backend's Shared-Runtime Build API was complete and
+ * deployed but had no caller; the Unreal side produced a candidate and a plan
+ * it never sent. This module is the join.
+ *
+ * The upload is deliberately STREAMED from disk. IoStore containers (.ucas)
+ * routinely run to gigabytes and the per-artifact ceiling is 64 GiB, so reading
+ * a build into memory to hash-and-PUT it would fail on exactly the worlds this
+ * exists to ship.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_stream_1 = require("node:stream");
+const api_1 = require("./api");
+const unrealCandidate_1 = require("./unrealCandidate");
+/** How many artifacts are PUT at once. Matches the bundle publisher. */
+const UPLOAD_CONCURRENCY = 4;
+/** Attempts per artifact. A presigned PUT is idempotent, so retrying is safe. */
+const UPLOAD_ATTEMPTS = 3;
+const SHA256 = /^[a-f0-9]{64}$/;
+/** ES256 in P1363 form, base64url — 64 raw bytes. */
+const P1363_ES256 = /^[A-Za-z0-9_-]{86}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Resolves a world slug to its id. A UUID is passed straight through — the
+ * backend routes on id, and requiring a lookup would make publishing to a
+ * world you own but did not name locally impossible.
+ */
+async function resolveWorldId(api, world) {
+    const value = world.trim();
+    if (UUID.test(value))
+        return value.toLowerCase();
+    const slug = value.toLowerCase();
+    const mine = await api.request('GET', '/api/v1/instant-worlds/me');
+    const match = mine.data.find((candidate) => candidate.slug === slug);
+    if (!match) {
+        throw new unrealCandidate_1.UnrealCandidateError(`You have no world with the slug "${slug}"`, [
+            `You have no world with the slug "${slug}".`,
+            'Create it first: helix world create --title "<Title>" --slug ' + slug,
+            'Or pass the world id directly with --world <uuid>.',
+        ]);
+    }
+    return match.id;
+}
+/**
+ * Checks that the server's presign response binds EVERY artifact we declared,
+ * with the exact content-type, length, and cache-control it signed. A ticket
+ * that disagrees would produce an opaque R2 403 at PUT time; catching it here
+ * says which artifact and why.
+ */
+function assertCreateResponseMatchesPlan(plan, response) {
+    const problems = [];
+    if (!UUID.test(String(response.buildId))) {
+        problems.push(`the server did not return a build id (got ${String(response.buildId)})`);
+    }
+    if (!Number.isInteger(response.buildNumber) || response.buildNumber < 1) {
+        problems.push(`the server returned an invalid build number: ${String(response.buildNumber)}`);
+    }
+    // NUL joins the composite key: neither a role nor an artifact path can
+    // contain one, so `a|b` can never collide with `a` + `|b`. Written as the
+    // \u0000 ESCAPE, not a literal byte — a raw control character makes this file
+    // read as binary, and every repo-wide grep then skips it silently.
+    const expected = new Map(plan.uploads.map((upload) => [`${upload.role}\u0000${upload.path}`, upload]));
+    const uploads = Array.isArray(response.uploads) ? response.uploads : [];
+    const seen = new Set();
+    for (const ticket of uploads) {
+        const key = `${ticket.role}\u0000${ticket.path}`;
+        const intent = expected.get(key);
+        if (!intent) {
+            problems.push(`the server presigned an artifact we did not declare: ${ticket.role} ${ticket.path}`);
+            continue;
+        }
+        if (seen.has(key)) {
+            problems.push(`the server presigned ${ticket.path} twice`);
+            continue;
+        }
+        seen.add(key);
+        if (ticket.contentType !== intent.mediaType) {
+            problems.push(`upload ticket content type does not match the manifest for ${ticket.path}: signed ${ticket.contentType}, declared ${intent.mediaType}`);
+        }
+        if (ticket.contentLength !== intent.sizeBytes) {
+            problems.push(`upload ticket length does not match the manifest for ${ticket.path}: signed ${ticket.contentLength}, declared ${intent.sizeBytes}`);
+        }
+        if (ticket.cacheControl !== unrealCandidate_1.PRIVATE_IMMUTABLE) {
+            problems.push(`upload ticket cache-control is not the immutable build policy for ${ticket.path}`);
+        }
+        if (!isHttpsUrl(ticket.url)) {
+            problems.push(`upload ticket for ${ticket.path} is not an https URL`);
+        }
+    }
+    // An `uploading` build must presign everything. A REPLAYED build (already
+    // uploading-complete, validated, or active) legitimately returns none —
+    // that is the idempotency path, not a failure.
+    if (response.status === 'uploading' && seen.size !== expected.size) {
+        for (const [key, upload] of expected) {
+            if (!seen.has(key))
+                problems.push(`the server did not presign ${upload.path}`);
+        }
+    }
+    if (problems.length) {
+        throw new unrealCandidate_1.UnrealCandidateError(problems[0], problems);
+    }
+}
+/** Fail-closed check of a finalize/promote receipt. */
+function assertReceipt(receipt) {
+    const problems = [];
+    if (!UUID.test(String(receipt.buildId)))
+        problems.push('the receipt has no build id');
+    if (!Number.isInteger(receipt.buildNumber) || receipt.buildNumber < 1) {
+        problems.push('the receipt has no build number');
+    }
+    if (!Number.isInteger(receipt.bundleSizeBytes) || receipt.bundleSizeBytes < 1) {
+        problems.push('the receipt reports an empty bundle');
+    }
+    if (!SHA256.test(String(receipt.manifestDigest))) {
+        problems.push('the receipt has no manifest digest');
+    }
+    // The whole point of finalize is the countersignature. A receipt without a
+    // well-formed ES256 signature means the build is NOT verifiable by a client,
+    // however cheerful the status string is.
+    if (!P1363_ES256.test(String(receipt.manifestSignature))) {
+        problems.push('the receipt is not countersigned by HELIX');
+    }
+    if (!String(receipt.manifestSigningKeyId ?? '').trim()) {
+        problems.push('the receipt does not name a signing key');
+    }
+    if (problems.length)
+        throw new unrealCandidate_1.UnrealCandidateError(problems[0], problems);
+}
+function isHttpsUrl(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && !!url.host && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * PUTs one artifact to its presigned ticket, streaming from disk.
+ *
+ * Content-Type, Cache-Control and Content-Length are all folded into the R2
+ * signature by the backend, so every one of them must be echoed EXACTLY or the
+ * upload comes back as an opaque 403 AccessDenied. Content-Length in
+ * particular has to be set by hand: a streamed body has no length undici can
+ * infer, and without the header the request is chunked and the signature fails.
+ */
+async function uploadArtifact(absolutePath, ticket, attempts = UPLOAD_ATTEMPTS) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            const stream = node_stream_1.Readable.toWeb((0, node_fs_1.createReadStream)(absolutePath));
+            const response = await fetch(ticket.url, {
+                method: 'PUT',
+                body: stream,
+                // Node's fetch requires an explicit half-duplex declaration to accept
+                // a stream body at all.
+                duplex: 'half',
+                headers: {
+                    'content-type': ticket.contentType,
+                    'cache-control': ticket.cacheControl,
+                    'content-length': String(ticket.contentLength),
+                },
+            });
+            if (response.ok)
+                return;
+            const detail = await response.text().catch(() => '');
+            const error = new Error(`upload of ${ticket.path} failed (${response.status})${detail ? `: ${detail.slice(0, 400)}` : ''}`);
+            // 4xx other than 408/429 is a signature or policy problem: the same
+            // bytes will be rejected the same way, so retrying only wastes the
+            // creator's upload budget.
+            if (response.status < 500 && response.status !== 408 && response.status !== 429)
+                throw error;
+            lastError = error;
+        }
+        catch (error) {
+            const wrapped = error instanceof Error ? error : new Error(String(error));
+            if (/failed \(4\d\d\)/.test(wrapped.message))
+                throw wrapped;
+            lastError = wrapped;
+        }
+        if (attempt < attempts) {
+            await new Promise((done) => setTimeout(done, 500 * 2 ** (attempt - 1)));
+        }
+    }
+    throw lastError ?? new Error(`upload of ${ticket.path} failed`);
+}
+/**
+ * Verify a cooked candidate, register the Build, upload every artifact,
+ * finalize, and (by default) promote it to the world's active release.
+ */
+async function publishUnrealBuild(candidateDir, api, options, onProgress = () => undefined) {
+    onProgress('Verifying the cooked build');
+    const candidate = await (0, unrealCandidate_1.verifyUnrealCandidate)(candidateDir, {
+        engineVersion: options.engineVersion,
+    });
+    onProgress(`Verified ${candidate.totalBytes.toLocaleString()} bytes across ${candidate.roles.length} role(s)`);
+    const worldId = await resolveWorldId(api, options.world);
+    const plan = (0, unrealCandidate_1.planSharedRuntimePublish)(candidate, {
+        worldId,
+        idempotencyKey: options.idempotencyKey ?? (0, unrealCandidate_1.defaultIdempotencyKey)(candidate),
+        activityId: options.activityId,
+        maxPlayers: options.maxPlayers,
+    });
+    const base = `/api/v1/worlds/${plan.worldId}/builds`;
+    onProgress(`Registering a ${plan.networkMode} build with ${plan.uploads.length} artifact(s)`);
+    const created = await api.requestItem('POST', `${base}/shared-runtime`, plan.create);
+    assertCreateResponseMatchesPlan(plan, created);
+    const bySource = new Map(plan.uploads.map((upload) => [`${upload.role}\u0000${upload.path}`, upload]));
+    const queue = [...(created.uploads ?? [])];
+    const total = queue.length;
+    const replayed = total === 0;
+    if (replayed) {
+        onProgress(`Build ${created.buildId} already has its artifacts; skipping upload`);
+    }
+    let done = 0;
+    await Promise.all(Array.from({ length: Math.min(UPLOAD_CONCURRENCY, Math.max(total, 1)) }, async () => {
+        for (let ticket = queue.shift(); ticket; ticket = queue.shift()) {
+            const upload = bySource.get(`${ticket.role}\u0000${ticket.path}`);
+            await uploadArtifact((0, node_path_1.join)(candidate.directory, ...upload.source.split('/')), ticket);
+            done += 1;
+            onProgress(`Uploaded ${done}/${total} · ${ticket.path}`);
+        }
+    }));
+    onProgress('Verifying every uploaded byte on the server');
+    const finalized = await api.requestItem('POST', `${base}/${created.buildId}/shared-runtime/finalize`);
+    assertReceipt(finalized);
+    let receipt = finalized;
+    const shouldPromote = options.promote !== false;
+    if (shouldPromote) {
+        onProgress('Promoting the build to the world’s active release');
+        receipt = await api.requestItem('POST', `${base}/${created.buildId}/promote`, options.visibility ? { visibility: options.visibility } : {});
+        assertReceipt(receipt);
+    }
+    let deliveryVerified = false;
+    if (shouldPromote && options.verifyDelivery) {
+        onProgress('Checking what a client would actually receive');
+        const delivery = await api.requestItem('GET', `${base}/${created.buildId}/delivery/client`);
+        assertClientDeliveryMatchesPlan(plan, receipt, delivery);
+        deliveryVerified = true;
+    }
+    return {
+        worldId: plan.worldId,
+        buildId: created.buildId,
+        buildNumber: created.buildNumber,
+        status: receipt.status,
+        networkMode: plan.networkMode,
+        artifactCount: plan.uploads.length,
+        bundleSizeBytes: receipt.bundleSizeBytes,
+        manifestDigest: receipt.manifestDigest,
+        manifestSigningKeyId: receipt.manifestSigningKeyId,
+        uploadedCount: done,
+        replayed,
+        promoted: shouldPromote,
+        deliveryVerified,
+    };
+}
+/** Client-visible roles, per the backend's delivery split. */
+const CLIENT_ROLES = new Set([
+    'windows_client_content',
+    'shared_content',
+    'lua_client',
+    'lua_shared',
+    'webui',
+]);
+/**
+ * Confirms the build a CLIENT would download is the build we uploaded: same
+ * signed digest, and every client-role artifact present with the digest and
+ * size we declared. This is the only check that looks at the delivery path
+ * rather than the publish path.
+ */
+function assertClientDeliveryMatchesPlan(plan, receipt, delivery) {
+    const problems = [];
+    if (delivery.buildId !== receipt.buildId) {
+        problems.push('delivery returned a different build than the one published');
+    }
+    if (delivery.manifestDigest !== receipt.manifestDigest) {
+        problems.push('the delivered manifest digest does not match the signed receipt');
+    }
+    if (delivery.manifestSignature !== receipt.manifestSignature) {
+        problems.push('the delivered signature does not match the signed receipt');
+    }
+    const expected = new Map(plan.uploads
+        .filter((upload) => CLIENT_ROLES.has(upload.role))
+        .map((upload) => [`${upload.role}\u0000${upload.path}`, upload]));
+    const seen = new Set();
+    for (const artifact of delivery.artifacts ?? []) {
+        const key = `${artifact.role}\u0000${artifact.path}`;
+        const intent = expected.get(key);
+        if (!intent) {
+            problems.push(`delivery includes an artifact we never published: ${artifact.path}`);
+            continue;
+        }
+        seen.add(key);
+        if (artifact.digest !== intent.sha256) {
+            problems.push(`delivered ${artifact.path} has a different digest than we uploaded`);
+        }
+        if (artifact.sizeBytes !== intent.sizeBytes) {
+            problems.push(`delivered ${artifact.path} has a different size than we uploaded`);
+        }
+    }
+    for (const [key, upload] of expected) {
+        if (!seen.has(key))
+            problems.push(`delivery is missing ${upload.path}`);
+    }
+    if (problems.length)
+        throw new unrealCandidate_1.UnrealCandidateError(problems[0], problems);
+}
+/** Renders an already-thrown publish failure for a terminal. */
+function renderPublishFailure(error) {
+    if (error instanceof unrealCandidate_1.UnrealCandidateError)
+        return error.render();
+    if (error instanceof api_1.ApiError)
+        return error.render();
+    return `✖ ${error instanceof Error ? error.message : String(error)}`;
+}
+//# sourceMappingURL=unrealPublish.js.map

package/dist/unrealPublish.js.map

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

package/dist/vault.d.ts

@@ -0,0 +1,121 @@
+import type { CliCredentials } from './config';
+/**
+ * DISCOVERING LOOKS AND OTHER SEALED PACKAGES — the Continuum Vault catalog.
+ *
+ * `helix assets search` (and MCP `search_assets`) hits the LEGACY
+ * `/api/v1/vault/assets` table: raw creator resources with no Continuum
+ * Package identity. It has no Looks (Universal Items pinned to a `build`
+ * Continuum Package — see docs/architecture, and
+ * run/open-alpha-audit/builds-explained.md §6 in the workspace root) and
+ * never will, because a Look does not live in that table. The table that DOES
+ * list Looks — `GET /api/v1/vault/catalog`, backing the website's Vault page
+ * (`continuum-vault-catalog.controller.ts`) — had no CLI or MCP door onto it
+ * at all, which is the gap this file closes.
+ *
+ * "Look" is the user-facing name; the API and this filter keep the identifier
+ * `build` (Phase 1, backend PR #1375; Phase 2 product note
+ * run/open-alpha-audit/builds-explained.md). `packageType: 'look'` is accepted
+ * here as a pure client-side alias for `'build'` — the backend 400s on any
+ * `packageType` it does not recognise as a `ContinuumPackageType`, and `look`
+ * is not one, so the alias is resolved before the request ever leaves this
+ * process.
+ */
+export declare const VAULT_CATALOG_PACKAGE_TYPES: readonly ["asset", "material", "character", "vehicle", "weapon", "device", "addon", "animation", "build", "scene", "gameplay", "runtime-module", "unreal-world"];
+export type VaultCatalogPackageType = (typeof VAULT_CATALOG_PACKAGE_TYPES)[number];
+/** Every accepted spelling of the filter, including the user-facing alias. */
+export declare const VAULT_CATALOG_PACKAGE_TYPE_INPUTS: readonly ["asset", "material", "character", "vehicle", "weapon", "device", "addon", "animation", "build", "scene", "gameplay", "runtime-module", "unreal-world", "look"];
+export type VaultCatalogPackageTypeInput = (typeof VAULT_CATALOG_PACKAGE_TYPE_INPUTS)[number];
+/**
+ * Resolve the alias. `look` -> `build`; every real `ContinuumPackageType`
+ * passes through unchanged; anything else is returned as-is so the backend's
+ * own 400 (with its own message) is what the caller sees, rather than this
+ * layer inventing a second error for the same bad input.
+ */
+export declare function resolveVaultCatalogPackageType(value: string): string;
+export interface VaultCatalogSearchInput {
+    q?: string;
+    /** Accepts `look` as an alias for `build`; see resolveVaultCatalogPackageType. */
+    packageType?: string;
+    sort?: 'recent' | 'name';
+    cursor?: string;
+    limit?: number;
+}
+interface BackendPackageRef {
+    packageId?: unknown;
+    version?: unknown;
+    manifestCid?: unknown;
+}
+interface BackendBuildSlot {
+    slot?: unknown;
+    package?: BackendPackageRef | null;
+}
+interface BackendCatalogRow {
+    catalogId?: unknown;
+    listingId?: unknown;
+    title?: unknown;
+    tags?: unknown;
+    visibility?: unknown;
+    packagePin?: BackendPackageRef | null;
+    packageType?: unknown;
+    packageName?: unknown;
+    packageSlug?: unknown;
+    manifest?: {
+        build?: {
+            base?: BackendPackageRef | null;
+            slots?: BackendBuildSlot[] | null;
+            parameters?: Record<string, unknown> | null;
+        } | null;
+    } | null;
+    previewImage?: {
+        url?: unknown;
+    } | null;
+    creatorId?: unknown;
+    createdAt?: unknown;
+    updatedAt?: unknown;
+}
+/** One row, trimmed to what an agent needs to CHOOSE — full row for Looks with get_look. */
+export interface VaultCatalogRow {
+    catalogId: string;
+    title: string;
+    packageType: string;
+    package: {
+        packageId: string;
+        version: string;
+        manifestCid: string;
+    } | null;
+    packageSlug: string | null;
+    tags: string[];
+    visibility: string | null;
+    thumbnailUrl: string | null;
+    creatorId: string | null;
+    updatedAt: string | null;
+    /** Present only for `packageType === 'build'` (a Look): its base and add-on slots. */
+    build: {
+        base: {
+            packageId: string;
+            version: string;
+        } | null;
+        slots: Array<{
+            slot: string;
+            packageId: string | null;
+            version: string | null;
+        }>;
+        parameters: Record<string, unknown> | null;
+    } | null;
+}
+export interface VaultCatalogSearchResult {
+    items: VaultCatalogRow[];
+    nextCursor: string | null;
+    totalItems: number;
+    counts: Record<string, number>;
+    /** Echoed so a caller can see exactly what reached the server (post-alias-resolution). */
+    query: Record<string, string | number>;
+}
+export declare function projectVaultCatalogRow(row: BackendCatalogRow): VaultCatalogRow;
+/**
+ * Search the Continuum Vault catalog — the table that actually lists Looks
+ * (and every other sealed, listed Continuum Package: characters, vehicles,
+ * weapons, devices, add-ons, materials...). Public: no bearer required.
+ */
+export declare function searchVaultCatalog(apiUrl: string, input?: VaultCatalogSearchInput, creds?: CliCredentials): Promise<VaultCatalogSearchResult>;
+export {};

package/dist/vault.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VAULT_CATALOG_PACKAGE_TYPE_INPUTS = exports.VAULT_CATALOG_PACKAGE_TYPES = void 0;
+exports.resolveVaultCatalogPackageType = resolveVaultCatalogPackageType;
+exports.projectVaultCatalogRow = projectVaultCatalogRow;
+exports.searchVaultCatalog = searchVaultCatalog;
+const api_1 = require("./api");
+/**
+ * DISCOVERING LOOKS AND OTHER SEALED PACKAGES — the Continuum Vault catalog.
+ *
+ * `helix assets search` (and MCP `search_assets`) hits the LEGACY
+ * `/api/v1/vault/assets` table: raw creator resources with no Continuum
+ * Package identity. It has no Looks (Universal Items pinned to a `build`
+ * Continuum Package — see docs/architecture, and
+ * run/open-alpha-audit/builds-explained.md §6 in the workspace root) and
+ * never will, because a Look does not live in that table. The table that DOES
+ * list Looks — `GET /api/v1/vault/catalog`, backing the website's Vault page
+ * (`continuum-vault-catalog.controller.ts`) — had no CLI or MCP door onto it
+ * at all, which is the gap this file closes.
+ *
+ * "Look" is the user-facing name; the API and this filter keep the identifier
+ * `build` (Phase 1, backend PR #1375; Phase 2 product note
+ * run/open-alpha-audit/builds-explained.md). `packageType: 'look'` is accepted
+ * here as a pure client-side alias for `'build'` — the backend 400s on any
+ * `packageType` it does not recognise as a `ContinuumPackageType`, and `look`
+ * is not one, so the alias is resolved before the request ever leaves this
+ * process.
+ */
+exports.VAULT_CATALOG_PACKAGE_TYPES = [
+    'asset',
+    'material',
+    'character',
+    'vehicle',
+    'weapon',
+    'device',
+    'addon',
+    'animation',
+    'build',
+    'scene',
+    'gameplay',
+    'runtime-module',
+    'unreal-world',
+];
+/** Every accepted spelling of the filter, including the user-facing alias. */
+exports.VAULT_CATALOG_PACKAGE_TYPE_INPUTS = [
+    ...exports.VAULT_CATALOG_PACKAGE_TYPES,
+    'look',
+];
+/**
+ * Resolve the alias. `look` -> `build`; every real `ContinuumPackageType`
+ * passes through unchanged; anything else is returned as-is so the backend's
+ * own 400 (with its own message) is what the caller sees, rather than this
+ * layer inventing a second error for the same bad input.
+ */
+function resolveVaultCatalogPackageType(value) {
+    return value === 'look' ? 'build' : value;
+}
+function text(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function packageRef(ref) {
+    const packageId = text(ref?.packageId);
+    const version = text(ref?.version);
+    const manifestCid = text(ref?.manifestCid);
+    return packageId && version && manifestCid ? { packageId, version, manifestCid } : null;
+}
+function projectVaultCatalogRow(row) {
+    const build = row.manifest?.build;
+    return {
+        catalogId: String(row.catalogId ?? row.listingId ?? ''),
+        title: String(row.title ?? ''),
+        packageType: String(row.packageType ?? 'unknown'),
+        package: packageRef(row.packagePin),
+        packageSlug: text(row.packageSlug),
+        tags: Array.isArray(row.tags) ? row.tags.filter((t) => typeof t === 'string') : [],
+        visibility: text(row.visibility),
+        thumbnailUrl: text(row.previewImage?.url),
+        creatorId: text(row.creatorId),
+        updatedAt: text(row.updatedAt),
+        build: build
+            ? {
+                base: build.base
+                    ? {
+                        packageId: text(build.base.packageId) ?? '',
+                        version: text(build.base.version) ?? '',
+                    }
+                    : null,
+                slots: (build.slots ?? []).map((slot) => ({
+                    slot: String(slot?.slot ?? ''),
+                    packageId: text(slot?.package?.packageId),
+                    version: text(slot?.package?.version),
+                })),
+                parameters: build.parameters ?? null,
+            }
+            : null,
+    };
+}
+/**
+ * Search the Continuum Vault catalog — the table that actually lists Looks
+ * (and every other sealed, listed Continuum Package: characters, vehicles,
+ * weapons, devices, add-ons, materials...). Public: no bearer required.
+ */
+async function searchVaultCatalog(apiUrl, input = {}, creds) {
+    const api = creds
+        ? api_1.HelixApi.forCredentials(creds)
+        : new api_1.HelixApi(apiUrl);
+    const query = {};
+    if (input.q)
+        query.q = input.q;
+    if (input.packageType)
+        query.packageType = resolveVaultCatalogPackageType(input.packageType);
+    if (input.sort)
+        query.sort = input.sort;
+    if (input.cursor)
+        query.cursor = input.cursor;
+    if (input.limit)
+        query.limit = input.limit;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query))
+        params.set(key, String(value));
+    const suffix = params.size ? `?${params}` : '';
+    const raw = await api.request('GET', `/api/v1/vault/catalog${suffix}`);
+    const counts = {};
+    for (const [key, value] of Object.entries(raw?.counts ?? {})) {
+        if (typeof value === 'number')
+            counts[key] = value;
+    }
+    return {
+        items: (raw?.items ?? []).map(projectVaultCatalogRow),
+        nextCursor: text(raw?.nextCursor),
+        totalItems: typeof raw?.totalItems === 'number' ? raw.totalItems : 0,
+        counts,
+        query,
+    };
+}
+//# sourceMappingURL=vault.js.map

package/dist/vault.js.map

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

package/dist/vehicle/addOnDefinition.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The canonical `helix.vehicle-addon-definition/1` root a vehicle add-on Package seals. Pure and import-light so both
+ * `vehicle addon publish` (which seals these exact bytes) and `vehicle addon check` (which proves the web customizer
+ * will accept them) build the one same object.
+ */
+import type { Json } from './platform';
+export declare const ADDON_DEFINITION_SCHEMA = "helix.vehicle-addon-definition/1";
+/** The canonical addon-definition root. Pure: same inputs, same bytes. */
+export declare function addOnDefinition(spec: {
+    title: string;
+    fits: Json;
+    ops: Json[];
+    provenance?: unknown;
+    definition?: Json;
+}, glb: {
+    sha: string;
+    bytes: number;
+    frame?: unknown;
+} | null): Json;

package/dist/vehicle/addOnDefinition.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADDON_DEFINITION_SCHEMA = void 0;
+exports.addOnDefinition = addOnDefinition;
+exports.ADDON_DEFINITION_SCHEMA = 'helix.vehicle-addon-definition/1';
+/** The canonical addon-definition root. Pure: same inputs, same bytes. */
+function addOnDefinition(spec, glb) {
+    return {
+        schema: exports.ADDON_DEFINITION_SCHEMA,
+        kind: 'vehiclePart',
+        hostKind: 'vehicle',
+        slotType: String(spec.fits.slotType),
+        title: spec.title,
+        fits: spec.fits,
+        ops: spec.ops,
+        mesh: glb ? { glb: 'model.glb', sha256: glb.sha, bytes: glb.bytes, frame: glb.frame ?? null } : null,
+        source: spec.provenance ?? null,
+        ...(spec.definition ?? {}),
+    };
+}
+//# sourceMappingURL=addOnDefinition.js.map

package/dist/vehicle/addOnDefinition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addOnDefinition.js","sourceRoot":"","sources":["../../src/vehicle/addOnDefinition.ts"],"names":[],"mappings":";;;AAUA,0CAaC;AAhBY,QAAA,uBAAuB,GAAG,kCAAkC,CAAC;AAE1E,0EAA0E;AAC1E,SAAgB,eAAe,CAAC,IAAyF,EAAE,GAA2D;IACpL,OAAO;QACL,MAAM,EAAE,+BAAuB;QAC/B,IAAI,EAAE,aAAa;QACnB,QAAQ,EAAE,SAAS;QACnB,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;QACpC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;QACpG,MAAM,EAAE,IAAI,CAAC,UAAU,IAAI,IAAI;QAC/B,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;KAC3B,CAAC;AACJ,CAAC"}