opensquid 0.5.395

package/dist/config.js

@@ -0,0 +1,202 @@
+/**
+ * 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

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

package/dist/config.test.js

@@ -0,0 +1,117 @@
+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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,171 @@
+/**
+ * `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

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