@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/dist/dev/state.d.ts

@@ -0,0 +1,84 @@
+export declare const DEV_DIR = ".helix";
+export declare const DEV_STATE_FILENAME = "dev-state.json";
+export declare const DEV_PRODUCTS_FILENAME = "dev-products.json";
+export declare const DEV_ACHIEVEMENTS_FILENAME = "dev-achievements.json";
+export declare const DEV_STATE_FILE_VERSION = 1;
+/** Opaque to the CLI: the shape is the SDK's DevShellState. Only `userId` is ever read here. */
+export type DevStateBlob = {
+    userId?: string;
+} & Record<string, unknown>;
+/** The simulated player. `dev-user-1` is the SDK's own default, so a first run matches its docs. */
+export type DevIdentity = {
+    id: string;
+    username: string;
+    displayName: string | null;
+};
+export type DevWorldStates = {
+    activeUserId: string;
+    players: Record<string, DevStateBlob>;
+};
+export type DevStateFile = {
+    v: number;
+    worlds: Record<string, DevWorldStates>;
+};
+/** The catalog seed, shaped like the SDK's DevShellProductsSeed (and the future helix.registry.json). */
+export type DevProductsSeed = {
+    products: unknown[];
+    listings?: unknown[];
+};
+export declare function devStatePath(worldDir: string): string;
+export declare function devProductsPath(worldDir: string): string;
+export declare function devAchievementsPath(worldDir: string): string;
+export declare function emptyDevStateFile(): DevStateFile;
+export declare const DEFAULT_DEV_IDENTITY: DevIdentity;
+/** dev-user-1 is the SDK's default identity, so identity 1 must spell exactly what the SDK would. */
+export declare function devIdentity(index: number): DevIdentity;
+/** Never throws: a hand-edited or truncated file starts the run empty rather than killing the command. */
+export declare function readDevStateFile(worldDir: string): DevStateFile;
+export declare function writeDevStateFile(worldDir: string, file: DevStateFile): string;
+export type DevStateSelection = {
+    file: DevStateFile;
+    identity: DevIdentity;
+    /** The state to hand the shell, or null to let it mint an empty player. */
+    state: DevStateBlob | null;
+    /** True when the file changed here (a reset or a new identity) and must be written back before boot. */
+    mutated: boolean;
+};
+/**
+ * Pick which simulated player this run drives. `--reset` drops the whole world's stored state; `--fresh`
+ * mints the next identity and leaves every other player's state alone.
+ */
+export declare function selectDevState(file: DevStateFile, slug: string, options?: {
+    reset?: boolean;
+    fresh?: boolean;
+}): DevStateSelection;
+/** Fold one onStateChange payload back into the file. Last write wins — the shell is the only writer. */
+export declare function recordDevState(file: DevStateFile, slug: string, state: DevStateBlob): DevStateFile;
+export type IgnoreOutcome = 'present' | 'appended' | 'created';
+/**
+ * Keep the simulated player out of version control. Appends with the file's OWN line ending — flipping
+ * a creator's .gitignore to LF would show up as a whole-file diff on their next commit.
+ */
+export declare function ensureDevDirIgnored(worldDir: string): IgnoreOutcome;
+export type DevProductsSeedResult = {
+    path: string;
+    seed: DevProductsSeed;
+    count: number;
+} | null;
+/** Read `.helix/dev-products.json` if the creator wrote one. A bare array is accepted as `{ products }`. */
+export declare function readDevProductsSeed(worldDir: string): DevProductsSeedResult;
+/** One validated seed row, shaped for the SDK's DevShellAchievement (registry side). */
+export type DevAchievementRow = Record<string, unknown>;
+export type DevAchievementsSeedResult = {
+    path: string;
+    achievements: DevAchievementRow[];
+    count: number;
+    criteriaCount: number;
+} | null;
+/**
+ * Read `.helix/dev-achievements.json` — registration-shaped rows, validated with the SAME rules
+ * `helix achievement register` applies (closed criteria vocabulary, key templates, dot-path field,
+ * unlockMode coherence). A seed that passes here is the same JSON that registers for real; a row the
+ * registration would refuse must fail the boot, not silently never unlock.
+ */
+export declare function readDevAchievementsSeed(worldDir: string): DevAchievementsSeedResult;

package/dist/dev/state.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DEV_IDENTITY = exports.DEV_STATE_FILE_VERSION = exports.DEV_ACHIEVEMENTS_FILENAME = exports.DEV_PRODUCTS_FILENAME = exports.DEV_STATE_FILENAME = exports.DEV_DIR = void 0;
+exports.devStatePath = devStatePath;
+exports.devProductsPath = devProductsPath;
+exports.devAchievementsPath = devAchievementsPath;
+exports.emptyDevStateFile = emptyDevStateFile;
+exports.devIdentity = devIdentity;
+exports.readDevStateFile = readDevStateFile;
+exports.writeDevStateFile = writeDevStateFile;
+exports.selectDevState = selectDevState;
+exports.recordDevState = recordDevState;
+exports.ensureDevDirIgnored = ensureDevDirIgnored;
+exports.readDevProductsSeed = readDevProductsSeed;
+exports.readDevAchievementsSeed = readDevAchievementsSeed;
+// On-disk state for `helix dev` — the persistence half of the SDK's dev shell, which does no I/O of its
+// own. One file per world project holds every simulated player's state, keyed by world slug and by
+// simulated userId, so `--fresh` can start an empty player without discarding the one before it.
+// State PERSISTS across reloads on purpose: a save that vanishes on exit cannot be tested at all.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const achievement_1 = require("../achievement");
+exports.DEV_DIR = '.helix';
+exports.DEV_STATE_FILENAME = 'dev-state.json';
+exports.DEV_PRODUCTS_FILENAME = 'dev-products.json';
+exports.DEV_ACHIEVEMENTS_FILENAME = 'dev-achievements.json';
+exports.DEV_STATE_FILE_VERSION = 1;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// Windows editors (and PowerShell 5's utf8) prepend a BOM, which JSON.parse rejects with a baffling
+// "unexpected token" — strip it so a hand-written seed file works however it was saved.
+const readJsonText = (path) => (0, node_fs_1.readFileSync)(path, 'utf8').replace(/^\uFEFF/, '');
+function devStatePath(worldDir) {
+    return (0, node_path_1.join)(worldDir, exports.DEV_DIR, exports.DEV_STATE_FILENAME);
+}
+function devProductsPath(worldDir) {
+    return (0, node_path_1.join)(worldDir, exports.DEV_DIR, exports.DEV_PRODUCTS_FILENAME);
+}
+function devAchievementsPath(worldDir) {
+    return (0, node_path_1.join)(worldDir, exports.DEV_DIR, exports.DEV_ACHIEVEMENTS_FILENAME);
+}
+function emptyDevStateFile() {
+    return { v: exports.DEV_STATE_FILE_VERSION, worlds: {} };
+}
+exports.DEFAULT_DEV_IDENTITY = {
+    id: 'dev-user-1',
+    username: 'dev-player',
+    displayName: 'Dev Player',
+};
+/** dev-user-1 is the SDK's default identity, so identity 1 must spell exactly what the SDK would. */
+function devIdentity(index) {
+    if (index <= 1)
+        return { ...exports.DEFAULT_DEV_IDENTITY };
+    return { id: `dev-user-${index}`, username: `dev-player-${index}`, displayName: `Dev Player ${index}` };
+}
+/** Never throws: a hand-edited or truncated file starts the run empty rather than killing the command. */
+function readDevStateFile(worldDir) {
+    const path = devStatePath(worldDir);
+    if (!(0, node_fs_1.existsSync)(path))
+        return emptyDevStateFile();
+    let parsed;
+    try {
+        parsed = JSON.parse(readJsonText(path));
+    }
+    catch {
+        return emptyDevStateFile();
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.worlds))
+        return emptyDevStateFile();
+    const worlds = {};
+    for (const [slug, entry] of Object.entries(parsed.worlds)) {
+        if (!isRecord(entry) || !isRecord(entry.players))
+            continue;
+        const players = {};
+        for (const [userId, state] of Object.entries(entry.players)) {
+            if (isRecord(state))
+                players[userId] = state;
+        }
+        const activeUserId = typeof entry.activeUserId === 'string' ? entry.activeUserId : exports.DEFAULT_DEV_IDENTITY.id;
+        worlds[slug] = { activeUserId, players };
+    }
+    return { v: exports.DEV_STATE_FILE_VERSION, worlds };
+}
+function writeDevStateFile(worldDir, file) {
+    const path = devStatePath(worldDir);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(worldDir, exports.DEV_DIR), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(file, null, 2)}\n`, 'utf8');
+    return path;
+}
+const IDENTITY_INDEX = /^dev-user-(\d+)$/;
+function nextIdentityIndex(players) {
+    let highest = 0;
+    for (const userId of Object.keys(players)) {
+        const match = IDENTITY_INDEX.exec(userId);
+        if (match)
+            highest = Math.max(highest, Number(match[1]));
+    }
+    return highest + 1;
+}
+/**
+ * Pick which simulated player this run drives. `--reset` drops the whole world's stored state; `--fresh`
+ * mints the next identity and leaves every other player's state alone.
+ */
+function selectDevState(file, slug, options = {}) {
+    const next = { v: exports.DEV_STATE_FILE_VERSION, worlds: { ...file.worlds } };
+    let mutated = false;
+    if (options.reset && next.worlds[slug]) {
+        delete next.worlds[slug];
+        mutated = true;
+    }
+    const world = next.worlds[slug];
+    if (options.fresh) {
+        const identity = devIdentity(nextIdentityIndex(world?.players ?? {}));
+        next.worlds[slug] = { activeUserId: identity.id, players: { ...(world?.players ?? {}) } };
+        return { file: next, identity, state: null, mutated: true };
+    }
+    if (!world)
+        return { file: next, identity: devIdentity(1), state: null, mutated };
+    const stored = world.players[world.activeUserId] ?? null;
+    const index = IDENTITY_INDEX.exec(world.activeUserId);
+    const identity = index
+        ? devIdentity(Number(index[1]))
+        : { id: world.activeUserId, username: world.activeUserId, displayName: world.activeUserId };
+    return { file: next, identity, state: stored, mutated };
+}
+/** Fold one onStateChange payload back into the file. Last write wins — the shell is the only writer. */
+function recordDevState(file, slug, state) {
+    const userId = typeof state.userId === 'string' && state.userId ? state.userId : exports.DEFAULT_DEV_IDENTITY.id;
+    const world = file.worlds[slug] ?? { activeUserId: userId, players: {} };
+    return {
+        v: exports.DEV_STATE_FILE_VERSION,
+        worlds: {
+            ...file.worlds,
+            [slug]: { activeUserId: userId, players: { ...world.players, [userId]: state } },
+        },
+    };
+}
+/**
+ * Keep the simulated player out of version control. Appends with the file's OWN line ending — flipping
+ * a creator's .gitignore to LF would show up as a whole-file diff on their next commit.
+ */
+function ensureDevDirIgnored(worldDir) {
+    const path = (0, node_path_1.join)(worldDir, '.gitignore');
+    const entry = `${exports.DEV_DIR}/`;
+    if (!(0, node_fs_1.existsSync)(path)) {
+        (0, node_fs_1.writeFileSync)(path, `${entry}\n`, 'utf8');
+        return 'created';
+    }
+    const current = (0, node_fs_1.readFileSync)(path, 'utf8');
+    const ignored = current
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .some((line) => line === entry || line === exports.DEV_DIR || line === `/${exports.DEV_DIR}` || line === `/${entry}`);
+    if (ignored)
+        return 'present';
+    const eol = current.includes('\r\n') ? '\r\n' : '\n';
+    const separator = current.length === 0 || current.endsWith('\n') ? '' : eol;
+    (0, node_fs_1.writeFileSync)(path, `${current}${separator}${entry}${eol}`, 'utf8');
+    return 'appended';
+}
+/** Read `.helix/dev-products.json` if the creator wrote one. A bare array is accepted as `{ products }`. */
+function readDevProductsSeed(worldDir) {
+    const path = devProductsPath(worldDir);
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readJsonText(path));
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const products = Array.isArray(parsed)
+        ? parsed
+        : isRecord(parsed) && Array.isArray(parsed.products)
+            ? parsed.products
+            : null;
+    if (!products) {
+        throw new Error(`${path} must be { "products": [...] } (or a bare array of products)`);
+    }
+    const listings = isRecord(parsed) && Array.isArray(parsed.listings) ? parsed.listings : undefined;
+    return { path, seed: listings ? { products, listings } : { products }, count: products.length };
+}
+/**
+ * Read `.helix/dev-achievements.json` — registration-shaped rows, validated with the SAME rules
+ * `helix achievement register` applies (closed criteria vocabulary, key templates, dot-path field,
+ * unlockMode coherence). A seed that passes here is the same JSON that registers for real; a row the
+ * registration would refuse must fail the boot, not silently never unlock.
+ */
+function readDevAchievementsSeed(worldDir) {
+    const path = devAchievementsPath(worldDir);
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readJsonText(path));
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const rows = Array.isArray(parsed)
+        ? parsed
+        : isRecord(parsed) && Array.isArray(parsed.achievements)
+            ? parsed.achievements
+            : null;
+    if (!rows) {
+        throw new Error(`${path} must be { "achievements": [...] } (or a bare array of achievements)`);
+    }
+    const achievements = [];
+    const seen = new Set();
+    rows.forEach((raw, index) => {
+        const at = (message) => new Error(`${path} achievements[${index}]: ${message}`);
+        if (!isRecord(raw))
+            throw at('must be an object');
+        const key = raw.key;
+        if (typeof key !== 'string' || !achievement_1.ACHIEVEMENT_KEY_PATTERN.test(key)) {
+            throw at('"key" must be 2-80 chars of lowercase letters, digits, "_" or "-", starting alphanumeric');
+        }
+        if (seen.has(key))
+            throw at(`duplicate key "${key}"`);
+        seen.add(key);
+        const scoped = (message) => new Error(`${path} achievement "${key}": ${message}`);
+        if (typeof raw.name !== 'string' || !raw.name.trim())
+            throw scoped('"name" is required');
+        if (raw.description !== undefined && typeof raw.description !== 'string')
+            throw scoped('"description" must be a string');
+        if (raw.iconUrl !== undefined && typeof raw.iconUrl !== 'string')
+            throw scoped('"iconUrl" must be a string');
+        if (raw.hidden !== undefined && typeof raw.hidden !== 'boolean')
+            throw scoped('"hidden" must be a boolean');
+        if (raw.points !== undefined && (!Number.isInteger(raw.points) || raw.points < 0 || raw.points > 1000)) {
+            throw scoped('"points" must be an integer between 0 and 1000');
+        }
+        if (raw.unlockMode !== undefined && typeof raw.unlockMode !== 'string')
+            throw scoped('"unlockMode" must be a string');
+        if (raw.criteria !== undefined && raw.criteria !== null && !isRecord(raw.criteria)) {
+            throw scoped('"criteria" must be an object');
+        }
+        const criteriaInput = isRecord(raw.criteria) ? raw.criteria : undefined;
+        const hasCriteria = (0, achievement_1.hasCriteriaInput)(criteriaInput);
+        try {
+            const unlockMode = (0, achievement_1.resolveUnlockMode)(raw.unlockMode, hasCriteria);
+            const criteria = hasCriteria && criteriaInput ? (0, achievement_1.buildAchievementCriteria)(criteriaInput) : undefined;
+            achievements.push({
+                key,
+                name: raw.name,
+                ...(raw.description !== undefined ? { description: raw.description } : {}),
+                ...(raw.points !== undefined ? { points: raw.points } : {}),
+                ...(raw.hidden !== undefined ? { hidden: raw.hidden } : {}),
+                ...(raw.iconUrl !== undefined ? { iconUrl: raw.iconUrl } : {}),
+                unlockMode,
+                ...(criteria ? { criteria } : {}),
+            });
+        }
+        catch (err) {
+            throw scoped(err instanceof Error ? err.message : String(err));
+        }
+    });
+    return {
+        path,
+        achievements,
+        count: achievements.length,
+        criteriaCount: achievements.filter((a) => a.criteria !== undefined).length,
+    };
+}
+//# sourceMappingURL=state.js.map

package/dist/dev/state.js.map

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

package/dist/device.d.ts

@@ -0,0 +1,104 @@
+export { deviceActionAstBudgetError } from './deviceActionValidation';
+export declare const DEVICE_FILENAME = "device.json";
+/**
+ * The closed interaction verb vocabulary the web host enforces.
+ *
+ * Mirrors the `verb` enum on `DeviceInteraction` in the first-party Device
+ * schema (`helixgame.com/lib/devices/validate.ts`). The host REJECTS anything
+ * else when the package loads, so validating it only in the host let a package
+ * pass `helix device validate` offline and then fail in the client —
+ * `continuum-soju` shipped `"verb": "drink"` that way. The list is duplicated
+ * deliberately; add verbs to both.
+ */
+export declare const DEVICE_INTERACTION_VERBS: readonly ["use", "open", "close", "toggle", "play", "sit", "custom"];
+/** The same vocabulary rendered as one readable list for error messages. */
+export declare const DEVICE_INTERACTION_VERB_LIST: string;
+/**
+ * The closed capability vocabulary a package may declare.
+ *
+ * Mirrors `DEVICE_CAPABILITIES` in `helixgame.com/lib/devices/types.ts`. A
+ * capability the client accepts and this list omits is a FALSE REJECTION —
+ * `physics.solid` was exactly that, and it made the shipped
+ * `continuum-garage-door` example (which needs it for its `collision` block)
+ * fail `helix device validate` while the client loaded it happily. Add
+ * capabilities to both lists, never to one.
+ */
+export declare const DEVICE_CAPABILITIES: readonly ["model.glb", "presentation.nodeMotion", "clock.serverTime", "state.typed", "state.durable", "room.authority", "audio.playback", "presentation.light", "presentation.vfx", "character.posture", "character.animate", "character.hand", "signals.local", "screen.render", "screen.input", "app.web.local", "app.web.remote", "app.web.panel", "app.image.remote", "app.image.owner", "app.canvas", "device.ports", "physics.solid"];
+/**
+ * The closed component vocabulary.
+ *
+ * Mirrors the discriminated union on `components` in the client schema
+ * (`validate.ts:423-527`). Branching on an unknown `type` used to fall through
+ * with no check at all, so a component kind this list does not name is rejected
+ * here rather than validated as an empty object.
+ */
+export declare const DEVICE_COMPONENT_TYPES: readonly ["slider", "clockHands", "pointLight", "audioReactiveLight", "characterSpot", "screen"];
+/**
+ * The closed behavior-graph step vocabulary.
+ *
+ * Mirrors the `step` union in the client schema (`validate.ts:133-222`). Every
+ * kind is validated to the client's depth, including the ones the shipped
+ * examples never use (`moveNode`, `setVfx`, `emitSignal`, `sequence`, `delay`,
+ * `repeat`, `stopAudio`) — their absence from the examples is why the gap went
+ * unnoticed for so long.
+ */
+export declare const DEVICE_GRAPH_STEP_KINDS: readonly ["setState", "toggleState", "moveNode", "rotateNode", "playAudio", "stopAudio", "setVfx", "attachCharacter", "playCharacterAnimation", "releaseCharacter", "enterCharacterSpot", "reachCharacterHand", "releaseCharacterHand", "attachItem", "releaseItem", "emitSignal", "branch", "sequence", "delay", "repeat"];
+/**
+ * The closed CHARACTER socket set an `attachItem` step may target.
+ *
+ * These are sockets on the acting character, never the Device's own `sockets`:
+ * the two namespaces are unrelated, and a Device that mounts on a wall has no
+ * hand to put anything in. Mirrors `DEVICE_HAND_SOCKETS` in the first-party
+ * host (`helixgame.com/lib/devices/types.ts`) and in the portable engine. The
+ * CLI validates offline, so the list is duplicated deliberately; add sockets
+ * to both.
+ */
+export declare const DEVICE_HAND_SOCKETS: readonly ["hand_r.grip", "hand_l.grip"];
+/** The same vocabulary rendered as one readable list for error messages. */
+export declare const DEVICE_HAND_SOCKET_LIST: string;
+/** The closed trigger vocabulary (`validate.ts:224-243`). */
+export declare const DEVICE_TRIGGER_KINDS: readonly ["init", "interact", "stateChanged", "signal", "playerNear"];
+/** The closed host vocabulary for `compatibility.hosts` (`validate.ts:555-560`). */
+export declare const DEVICE_HOSTS: readonly ["home", "world"];
+/** The same vocabulary rendered as one readable list for error messages. */
+export declare const DEVICE_HOSTS_LIST: string;
+/** The closed `thumbnail.policy` vocabulary (`validate.ts:563-567`). */
+export declare const DEVICE_THUMBNAIL_POLICIES: readonly ["catalog", "discreteState", "never"];
+/** The host's `inputMode` vocabulary for a text control (`validate.ts:414-419`). */
+export declare const DEVICE_TEXT_INPUT_MODES: readonly ["text", "tel", "url", "email", "numeric", "decimal", "search"];
+type Scalar = number | string | boolean;
+type JsonObject = Record<string, unknown>;
+export interface DeviceValidationReport {
+    ok: boolean;
+    directory: string;
+    definitionPath: string;
+    modelPath: string | null;
+    nodeNames: string[];
+    errors: string[];
+    warnings: string[];
+    definition?: JsonObject;
+}
+export interface DeviceTestReport {
+    ok: boolean;
+    mode: 'single' | 'multiplayer';
+    clients: number;
+    actionsExercised: string[];
+    finalState: Record<string, Scalar>;
+    persistentState: Record<string, Scalar>;
+    errors: string[];
+}
+export declare function readDeviceGlbNodeNames(file: string): string[];
+export declare function validateDeviceProject(input: string): DeviceValidationReport;
+export declare function testDeviceProject(input: string, mode: 'single' | 'multiplayer'): DeviceTestReport;
+export declare function createDeviceProject(input: {
+    directory: string;
+    id: string;
+    title: string;
+    modelPath: string;
+    template: 'clock' | 'standing-desk' | 'television';
+}): {
+    directory: string;
+    definitionPath: string;
+    modelPath: string;
+    nodeNames: string[];
+};