opensquid 0.5.432 → 0.5.447

package/dist/config.js

@@ -1,202 +0,0 @@
-/**
- * Opensquid host-level config at `<data-root>/config.json`.
- *
- * Persists machine-state that's relevant across sessions but doesn't
- * belong in per-project files or in the engine's lesson store. v0.4
- * uses it to remember the engine binary path so moving the loop-engine
- * checkout doesn't silently break opensquid.
- *
- * Resolution order for the engine binary (v0.6c):
- *   1. `OPENSQUID_ENGINE_BIN` env var — explicit override, always wins
- *   2. `<data-root>/config.json` `engine_bin` field — persisted choice
- *   3. Bundled npm optional dep (`opensquid-engine-<platform>-<arch>`) —
- *      shipped with `opensquid` for published installs (v0.6c)
- *   4. Auto-search common dev paths (~/projects/{,*}/{loop/engine,engine}/target/release/loop-engine)
- *   5. `loop-engine` on $PATH (manually-installed binary)
- *   6. `null` — caller surfaces a helpful error
- *
- * The first successful resolution writes itself back to config.json so
- * the next session picks up the same path immediately. Bundled-binary
- * hits are NOT persisted to config because the path is deterministic
- * from the npm install layout — re-resolving is free and stale-safe
- * across opensquid upgrades.
- */
-import { promises as fs } from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { resolveDataRoot } from "./codex/store.js";
-import { resolveBundledEngineBin } from "./engine-binary-resolver.js";
-const DEFAULT_CONFIG = { version: 1 };
-// ---------------------------------------------------------------------
-// Load / save
-// ---------------------------------------------------------------------
-function configPath(dataRoot) {
-    return path.join(resolveDataRoot(dataRoot), "config.json");
-}
-export async function loadConfig(dataRoot) {
-    try {
-        const raw = await fs.readFile(configPath(dataRoot), "utf8");
-        const parsed = JSON.parse(raw);
-        if (parsed && parsed.version === 1)
-            return parsed;
-    }
-    catch {
-        // missing or malformed — return default
-    }
-    return { ...DEFAULT_CONFIG };
-}
-export async function saveConfig(config, dataRoot) {
-    const p = configPath(dataRoot);
-    await fs.mkdir(path.dirname(p), { recursive: true });
-    await fs.writeFile(p, JSON.stringify(config, null, 2) + "\n", "utf8");
-}
-// ---------------------------------------------------------------------
-// Engine binary discovery
-// ---------------------------------------------------------------------
-const ENGINE_BIN_NAME = "loop-engine";
-/**
- * Resolve the engine binary path using the priority chain above.
- * Writes the resolved path back to config when discovered via search
- * so the next session is instant.
- *
- * Returns `null` if no working binary could be located.
- */
-export async function resolveEngineBin(dataRoot) {
-    // 1. Env override always wins. Don't validate — let the spawn fail
-    //    loudly if the user gave a bad path.
-    const fromEnv = process.env.OPENSQUID_ENGINE_BIN?.trim();
-    if (fromEnv)
-        return fromEnv;
-    // 2. Persisted choice.
-    const config = await loadConfig(dataRoot);
-    if (config.engine_bin && (await isExecutable(config.engine_bin))) {
-        return config.engine_bin;
-    }
-    // 3. v0.6c: bundled npm optional dependency. Only present in npm
-    //    installs of `opensquid` once we start publishing the engine
-    //    binary packages. Returns null in local-dev / git-clone setups,
-    //    so the older discovery branches still cover that case. We
-    //    intentionally do NOT persist this to config.json — the path is
-    //    deterministic from the npm layout, and persisting it would
-    //    point at a stale node_modules path after upgrades.
-    const bundled = resolveBundledEngineBin();
-    if (bundled && (await isExecutable(bundled))) {
-        return bundled;
-    }
-    // 4. Auto-search common dev paths.
-    const found = await searchCommonPaths();
-    if (found) {
-        config.engine_bin = found;
-        config.engine_bin_resolved_at = new Date().toISOString();
-        await saveConfig(config, dataRoot);
-        return found;
-    }
-    // 5. $PATH (in case the user installed loop-engine system-wide).
-    const onPath = await whichBinary(ENGINE_BIN_NAME);
-    if (onPath) {
-        config.engine_bin = onPath;
-        config.engine_bin_resolved_at = new Date().toISOString();
-        await saveConfig(config, dataRoot);
-        return onPath;
-    }
-    return null;
-}
-/**
- * Set the engine binary path explicitly and persist. Validates that the
- * path points at an executable file before writing.
- */
-export async function setEngineBin(binPath, dataRoot) {
-    const abs = path.resolve(binPath);
-    if (!(await isExecutable(abs))) {
-        throw new Error(`not an executable file: ${abs}`);
-    }
-    const config = await loadConfig(dataRoot);
-    config.engine_bin = abs;
-    config.engine_bin_resolved_at = new Date().toISOString();
-    await saveConfig(config, dataRoot);
-    return { resolved: abs };
-}
-/**
- * Forget the persisted engine binary path. Forces re-discovery on the
- * next `resolveEngineBin` call.
- */
-export async function forgetEngineBin(dataRoot) {
-    const config = await loadConfig(dataRoot);
-    delete config.engine_bin;
-    delete config.engine_bin_resolved_at;
-    await saveConfig(config, dataRoot);
-}
-// ---------------------------------------------------------------------
-// Internals
-// ---------------------------------------------------------------------
-async function isExecutable(p) {
-    try {
-        const stat = await fs.stat(p);
-        if (!stat.isFile())
-            return false;
-        // Best-effort executable check: mode &  0o111 (any-x bit set).
-        return (stat.mode & 0o111) !== 0;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Walk common dev-machine layouts looking for a release binary.
- * Conservative — only checks paths that look like sibling projects of
- * the user's $HOME. Returns the first hit.
- */
-async function searchCommonPaths() {
-    const home = os.homedir();
-    const candidates = [];
-    // ~/projects/<*>/engine/target/release/loop-engine — checkout of a
-    // workspace named anything; engine/ as the substrate subdir.
-    // ~/projects/<*>/target/release/loop-engine — standalone engine repo.
-    const projectsRoot = path.join(home, "projects");
-    try {
-        const dirs = await fs.readdir(projectsRoot, { withFileTypes: true });
-        for (const entry of dirs) {
-            if (!entry.isDirectory())
-                continue;
-            candidates.push(path.join(projectsRoot, entry.name, "engine", "target", "release", ENGINE_BIN_NAME), path.join(projectsRoot, entry.name, "target", "release", ENGINE_BIN_NAME));
-        }
-    }
-    catch {
-        // ~/projects doesn't exist — skip.
-    }
-    // ~/work/<*>/{engine,}/target/release/loop-engine — alternate
-    // convention.
-    const workRoot = path.join(home, "work");
-    try {
-        const dirs = await fs.readdir(workRoot, { withFileTypes: true });
-        for (const entry of dirs) {
-            if (!entry.isDirectory())
-                continue;
-            candidates.push(path.join(workRoot, entry.name, "engine", "target", "release", ENGINE_BIN_NAME), path.join(workRoot, entry.name, "target", "release", ENGINE_BIN_NAME));
-        }
-    }
-    catch {
-        // ~/work doesn't exist — skip.
-    }
-    for (const cand of candidates) {
-        if (await isExecutable(cand))
-            return cand;
-    }
-    return null;
-}
-/**
- * Cross-platform `which` — search $PATH for an executable named `bin`.
- * Returns absolute path or null.
- */
-async function whichBinary(bin) {
-    const pathEnv = process.env.PATH ?? "";
-    const sep = process.platform === "win32" ? ";" : ":";
-    for (const dir of pathEnv.split(sep)) {
-        if (!dir)
-            continue;
-        const candidate = path.join(dir, bin);
-        if (await isExecutable(candidate))
-            return candidate;
-    }
-    return null;
-}

package/dist/config.js.map

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

package/dist/config.test.js

@@ -1,117 +0,0 @@
-import * as crypto from "node:crypto";
-import { promises as fs } from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { forgetEngineBin, loadConfig, resolveEngineBin, saveConfig, setEngineBin, } from "./config.js";
-let tmpHome;
-let savedEnvBin;
-beforeEach(async () => {
-    tmpHome = path.join(os.tmpdir(), `oscli-config-${crypto.randomUUID()}`);
-    await fs.mkdir(tmpHome, { recursive: true });
-    savedEnvBin = process.env.OPENSQUID_ENGINE_BIN;
-    delete process.env.OPENSQUID_ENGINE_BIN;
-    process.env.OPENSQUID_HOME = tmpHome;
-});
-afterEach(async () => {
-    await fs.rm(tmpHome, { recursive: true, force: true });
-    if (savedEnvBin === undefined)
-        delete process.env.OPENSQUID_ENGINE_BIN;
-    else
-        process.env.OPENSQUID_ENGINE_BIN = savedEnvBin;
-    delete process.env.OPENSQUID_HOME;
-});
-// Helper: write a fake executable at a tmp path.
-async function fakeExecAt(dir, name = "loop-engine") {
-    await fs.mkdir(dir, { recursive: true });
-    const p = path.join(dir, name);
-    await fs.writeFile(p, "#!/bin/sh\necho fake\n", "utf8");
-    await fs.chmod(p, 0o755);
-    return p;
-}
-// ---------------------------------------------------------------------
-// load / save
-// ---------------------------------------------------------------------
-describe("loadConfig + saveConfig", () => {
-    it("returns default config when file is missing", async () => {
-        const c = await loadConfig();
-        expect(c.version).toBe(1);
-        expect(c.engine_bin).toBeUndefined();
-    });
-    it("round-trips a saved config", async () => {
-        await saveConfig({ version: 1, engine_bin: "/x/y", engine_bin_resolved_at: "now" });
-        const c = await loadConfig();
-        expect(c.engine_bin).toBe("/x/y");
-    });
-    it("returns default on malformed config", async () => {
-        await fs.mkdir(tmpHome, { recursive: true });
-        await fs.writeFile(path.join(tmpHome, "config.json"), "{not json", "utf8");
-        const c = await loadConfig();
-        expect(c.version).toBe(1);
-        expect(c.engine_bin).toBeUndefined();
-    });
-});
-// ---------------------------------------------------------------------
-// resolveEngineBin
-// ---------------------------------------------------------------------
-describe("resolveEngineBin priority order", () => {
-    it("env var wins over everything (no validation)", async () => {
-        process.env.OPENSQUID_ENGINE_BIN = "/some/explicit/path";
-        expect(await resolveEngineBin()).toBe("/some/explicit/path");
-    });
-    it("uses persisted config when env is unset and path is executable", async () => {
-        const bin = await fakeExecAt(path.join(tmpHome, "tools"));
-        await saveConfig({ version: 1, engine_bin: bin });
-        expect(await resolveEngineBin()).toBe(bin);
-    });
-    it("ignores persisted config when its path is no longer executable", async () => {
-        // Persist a path that doesn't exist.
-        await saveConfig({ version: 1, engine_bin: "/nonexistent/loop-engine" });
-        // Auto-search and $PATH likely won't hit on this machine either.
-        const result = await resolveEngineBin();
-        // We can't assert null universally (CI runners might have something
-        // matching), but the bad persisted path must not have been returned.
-        expect(result).not.toBe("/nonexistent/loop-engine");
-    });
-});
-// ---------------------------------------------------------------------
-// setEngineBin
-// ---------------------------------------------------------------------
-describe("setEngineBin", () => {
-    it("validates the path is executable", async () => {
-        await expect(setEngineBin("/nonexistent/bin")).rejects.toThrow(/not an executable/);
-    });
-    it("persists the path on success", async () => {
-        const bin = await fakeExecAt(path.join(tmpHome, "tools"));
-        const res = await setEngineBin(bin);
-        expect(res.resolved).toBe(bin);
-        const config = await loadConfig();
-        expect(config.engine_bin).toBe(bin);
-        expect(config.engine_bin_resolved_at).toBeDefined();
-    });
-    it("resolves relative paths to absolute", async () => {
-        const bin = await fakeExecAt(path.join(tmpHome, "tools"));
-        const rel = path.relative(process.cwd(), bin);
-        const res = await setEngineBin(rel);
-        expect(path.isAbsolute(res.resolved)).toBe(true);
-        expect(res.resolved).toBe(bin);
-    });
-});
-// ---------------------------------------------------------------------
-// forgetEngineBin
-// ---------------------------------------------------------------------
-describe("forgetEngineBin", () => {
-    it("clears the persisted engine_bin", async () => {
-        const bin = await fakeExecAt(path.join(tmpHome, "tools"));
-        await setEngineBin(bin);
-        expect((await loadConfig()).engine_bin).toBe(bin);
-        await forgetEngineBin();
-        expect((await loadConfig()).engine_bin).toBeUndefined();
-    });
-    it("is idempotent on missing config", async () => {
-        await forgetEngineBin();
-        await forgetEngineBin();
-        // No throw — config just stays empty.
-        expect((await loadConfig()).engine_bin).toBeUndefined();
-    });
-});

package/dist/engine/cli.d.ts

@@ -1,14 +0,0 @@
-import type { Command } from 'commander';
-export declare class EngineCliError extends Error {
-    readonly hint?: string;
-    constructor(message: string, hint?: string);
-}
-/**
- * Register the `engine` verb group on a commander program/sub-program.
- *
- * Errors thrown by subcommand handlers surface via the root program's
- * `parseAsync().catch` — registered handlers don't call `process.exit`
- * directly. `EngineCliError.hint` is rendered when present.
- */
-export declare function registerEngineCli(program: Command): void;
-//# sourceMappingURL=cli.d.ts.map

package/dist/engine/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/engine/cli.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;gBAClB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAK3C;AAsHD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8BxD"}

package/dist/engine/cli.js

@@ -1,171 +0,0 @@
-/**
- * `opensquid engine <subcommand>` — engine binary management.
- *
- * Subcommands:
- *   doctor             — show the resolved engine binary + how it was
- *                        discovered (env / config / search / PATH).
- *                        Warns when `OPENSQUID_ENGINE_BIN` is set,
- *                        since the env-var bypass would pin a stale
- *                        path forever (re-resolution can't override
- *                        an explicit env override).
- *   set-path <path>    — persist an explicit engine binary path in
- *                        ~/.opensquid/engine-config.json
- *   forget             — clear the persisted path; force re-discovery
- *                        on next start
- *   kill               — read `~/.opensquid/loop-engine.pid` (written
- *                        by `singleton.acquireOrSpawnEngine`), send
- *                        SIGTERM, wait 2s for graceful shutdown, then
- *                        best-effort unlink the socket + pidfile.
- *                        Idempotent — no pidfile + no socket prints a
- *                        friendly "no engine daemon running" + exit 0.
- *
- * Registered into the root `opensquid` Command via `registerEngineCli`
- * — call from `src/cli.ts`.
- */
-import { existsSync } from 'node:fs';
-import { readFile, unlink } from 'node:fs/promises';
-import { forgetEngineBin, loadEngineConfig, resolveEngineBin, setEngineBin } from './config.js';
-import { enginePidPath, engineSocketPath } from './singleton.js';
-export class EngineCliError extends Error {
-    hint;
-    constructor(message, hint) {
-        super(message);
-        this.name = 'EngineCliError';
-        if (hint !== undefined)
-            this.hint = hint;
-    }
-}
-async function cmdDoctor() {
-    process.stdout.write('[opensquid engine doctor]\n');
-    const env = process.env.OPENSQUID_ENGINE_BIN?.trim();
-    process.stdout.write(`  env OPENSQUID_ENGINE_BIN: ${env ?? '(unset)'}\n`);
-    const config = await loadEngineConfig();
-    process.stdout.write(`  config.engine_bin:        ${config.engine_bin ?? '(unset)'}\n`);
-    if (config.engine_bin_resolved_at) {
-        process.stdout.write(`  resolved at:              ${config.engine_bin_resolved_at}\n`);
-    }
-    const resolved = await resolveEngineBin();
-    process.stdout.write(`  resolved binary:          ${resolved ?? '(none — not found)'}\n`);
-    // T.7: the env-var bypass short-circuits stale-path re-resolution,
-    // so a stale `OPENSQUID_ENGINE_BIN` would pin a dead path forever.
-    // Surface the override + remind the user re-resolution is disabled.
-    if (env) {
-        process.stdout.write('  note: env var OPENSQUID_ENGINE_BIN is set — stale-path re-resolution is disabled.\n' +
-            '        unset it to let opensquid recover automatically.\n');
-    }
-    if (!resolved) {
-        process.stdout.write('  hint: run `opensquid engine set-path <path>` to fix.\n');
-    }
-}
-async function cmdSetPath(target) {
-    if (!target) {
-        throw new EngineCliError('usage: opensquid engine set-path <path>', 'pass the path to a loop-engine release binary');
-    }
-    const res = await setEngineBin(target);
-    process.stdout.write(`[opensquid engine set-path] persisted: ${res.resolved}\n`);
-}
-async function cmdForget() {
-    await forgetEngineBin();
-    process.stdout.write('[opensquid engine forget] cleared persisted engine_bin\n');
-}
-/**
- * Grace period after `SIGTERM` before we clean up the socket + pidfile.
- * The engine's own shutdown handler should unlink both as it exits;
- * cleanup here is defense-in-depth for SIGKILL fallbacks / crashes.
- * 2s is comfortably above engine clean-shutdown time (<200ms typical)
- * without making `engine kill` feel slow on a healthy daemon.
- */
-const KILL_GRACE_MS = 2_000;
-async function cmdKill() {
-    const sockPath = engineSocketPath();
-    const pidPath = enginePidPath();
-    const sockExists = existsSync(sockPath);
-    const pidExists = existsSync(pidPath);
-    // Idempotent no-op when nothing is running. Avoids scaring a user
-    // who runs `engine kill` defensively before tearing down a project.
-    if (!sockExists && !pidExists) {
-        process.stdout.write('[opensquid engine kill] no engine daemon running.\n');
-        return;
-    }
-    // Pidfile is the only authoritative pid source — the socket file
-    // alone tells us nothing about who's listening. If the pidfile is
-    // missing or malformed, skip the signal and fall through to cleanup.
-    let pid = null;
-    if (pidExists) {
-        try {
-            const raw = (await readFile(pidPath, 'utf8')).trim();
-            const parsed = Number.parseInt(raw, 10);
-            if (Number.isFinite(parsed) && parsed > 0) {
-                pid = parsed;
-            }
-            else {
-                process.stdout.write(`[opensquid engine kill] warning: pidfile contents not a valid pid (${raw}); skipping SIGTERM.\n`);
-            }
-        }
-        catch (e) {
-            process.stdout.write(`[opensquid engine kill] warning: could not read pidfile: ${String(e)}; skipping SIGTERM.\n`);
-        }
-    }
-    if (pid !== null) {
-        try {
-            process.kill(pid, 'SIGTERM');
-            process.stdout.write(`[opensquid engine kill] sent SIGTERM to pid=${String(pid)}.\n`);
-            // Give the engine its graceful-shutdown window before we step
-            // in for cleanup. The engine SHOULD unlink the socket + pidfile
-            // itself; our unlink calls below are best-effort fallbacks.
-            await new Promise((resolve) => setTimeout(resolve, KILL_GRACE_MS));
-        }
-        catch (e) {
-            // ESRCH (no such pid) is the common case — pidfile is stale
-            // because the engine crashed without cleanup. Log + continue
-            // to the unlink step so we don't leave junk behind.
-            const msg = e instanceof Error ? e.message : String(e);
-            process.stdout.write(`[opensquid engine kill] kill(${String(pid)}, SIGTERM) failed: ${msg}; continuing to cleanup.\n`);
-        }
-    }
-    // Defense-in-depth cleanup. Either the engine already unlinked
-    // these (cleanly handled SIGTERM) or it didn't (crash / SIGKILL).
-    // Swallow errors — best-effort.
-    if (existsSync(sockPath)) {
-        await unlink(sockPath).catch(() => undefined);
-    }
-    if (existsSync(pidPath)) {
-        await unlink(pidPath).catch(() => undefined);
-    }
-    process.stdout.write('[opensquid engine kill] engine daemon stopped.\n');
-}
-/**
- * Register the `engine` verb group on a commander program/sub-program.
- *
- * Errors thrown by subcommand handlers surface via the root program's
- * `parseAsync().catch` — registered handlers don't call `process.exit`
- * directly. `EngineCliError.hint` is rendered when present.
- */
-export function registerEngineCli(program) {
-    const engine = program.command('engine').description('loop-engine binary management');
-    engine
-        .command('doctor')
-        .description('Show resolved engine binary + discovery chain.')
-        .action(async () => {
-        await cmdDoctor();
-    });
-    engine
-        .command('set-path <path>')
-        .description('Persist an explicit engine binary path.')
-        .action(async (target) => {
-        await cmdSetPath(target);
-    });
-    engine
-        .command('forget')
-        .description('Clear the persisted engine binary path; force re-discovery.')
-        .action(async () => {
-        await cmdForget();
-    });
-    engine
-        .command('kill')
-        .description('Stop the loop-engine singleton daemon (SIGTERM via pidfile + cleanup).')
-        .action(async () => {
-        await cmdKill();
-    });
-}
-//# sourceMappingURL=cli.js.map

package/dist/engine/cli.js.map

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