opensquid 0.5.395

package/dist/chat_daemon/client.js

@@ -0,0 +1,122 @@
+/**
+ * The single owner of the chat-daemon client (T-CHAT-FINALIZE-REMOVE-LEGACY CL.1).
+ *
+ * Before this module the one-shot JSON-RPC-over-UNIX-socket dance was copy-pasted into
+ * ~5 call sites (agent_bridge/tools/chat_send, mcp/chat-bridge-server, setup/cli/
+ * chat_actions_test_step, functions/ensure_umbrella_topic) plus the socket-path
+ * derivation in ~5 places — duplication left over from when the chat-daemon client
+ * lived in the now-removed `src.legacy/` tree. This is that shared client (the home the
+ * chat_send.ts comment named). STRICT extraction: the
+ * socket/timeout/decode behavior matches the prior `defaultDaemonSend` byte-for-byte;
+ * `daemonRpc` just generalizes it over the RPC `method` + result type.
+ *
+ * Scope (Simplicity — no method without a present caller): socket-path resolution, one
+ * one-shot `daemonRpc`, and the typed `sendChat` wrapper. No pooling / retry / streaming —
+ * the daemon calls are one-shot, so a one-shot client is the correct shape.
+ *
+ * Imports from: node:net, node:os, ../runtime/paths.js.
+ * Imported by: the chat-daemon call sites (CL.3).
+ */
+import { connect } from 'node:net';
+import { platform as osPlatform } from 'node:os';
+import { chatDaemonSockPath, OPENSQUID_HOME } from '../runtime/paths.js';
+/**
+ * The chat-daemon socket address. Unix: the canonical `chatDaemonSockPath()`
+ * (`<home>/chat-daemon.sock`). Win32: a named pipe whose fingerprint = the last path
+ * segment of the data root (keeps multiple installs isolated — the convention the legacy
+ * `daemonSockAddress` used). This is the ONE place the Win32 branch lives now.
+ */
+export function daemonSocketPath() {
+    if (osPlatform() === 'win32') {
+        const fingerprint = OPENSQUID_HOME().split(/[\\/]/).pop() ?? 'default';
+        return `\\\\.\\pipe\\opensquid-chat-daemon-${fingerprint}`;
+    }
+    return chatDaemonSockPath();
+}
+let rpcCounter = 0;
+/**
+ * One-shot JSON-RPC over the daemon UNIX socket: connect → write a single newline-framed
+ * request → read the first newline-framed response → resolve its `result` (or reject on
+ * RPC error / malformed JSON / connection error / timeout). Never spawns the daemon — a
+ * down daemon surfaces as a connection-error rejection.
+ */
+export function daemonRpc(method, params, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5000;
+    return new Promise((resolveCall, rejectCall) => {
+        const id = `opensquid-client-${++rpcCounter}-${Date.now()}`;
+        const req = JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';
+        let sock = null;
+        let buffer = '';
+        const cleanup = () => {
+            if (sock !== null) {
+                try {
+                    sock.end();
+                }
+                catch {
+                    /* socket already closed */
+                }
+                sock = null;
+            }
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            rejectCall(new Error(`chat-daemon RPC timeout after ${String(timeoutMs)}ms`));
+        }, timeoutMs);
+        sock = connect(daemonSocketPath());
+        sock.once('error', (err) => {
+            clearTimeout(timer);
+            cleanup();
+            rejectCall(new Error(`chat-daemon connection error: ${err.message}`));
+        });
+        sock.once('connect', () => sock?.write(req));
+        sock.on('data', (chunk) => {
+            buffer += chunk.toString('utf8');
+            const nl = buffer.indexOf('\n');
+            if (nl < 0)
+                return;
+            const line = buffer.slice(0, nl);
+            clearTimeout(timer);
+            cleanup();
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed.error) {
+                    rejectCall(new Error(`chat-daemon RPC error ${parsed.error.code}: ${parsed.error.message}`));
+                }
+                else if (parsed.result !== undefined) {
+                    resolveCall(parsed.result);
+                }
+                else {
+                    rejectCall(new Error('chat-daemon RPC: malformed response (no result or error)'));
+                }
+            }
+            catch (e) {
+                rejectCall(new Error(`chat-daemon RPC: invalid JSON response: ${e instanceof Error ? e.message : String(e)}`));
+            }
+        });
+    });
+}
+/** Typed `send` RPC — the one-shot reply path used by the agent-bridge + MCP bridge. */
+export const sendChat = (params) => daemonRpc('send', {
+    channel: params.channel,
+    text: params.text,
+    ...(params.replyTo !== undefined ? { replyTo: params.replyTo } : {}),
+    ...(params.threadId !== undefined ? { threadId: params.threadId } : {}),
+    ...(params.imagePath !== undefined ? { mediaPath: params.imagePath } : {}),
+});
+/** Typed `create_topic` RPC — creates one Telegram forum topic, returns its thread id. */
+export const createTopic = (chatId, name) => daemonRpc('create_topic', {
+    platform: 'telegram',
+    chat_id: chatId,
+    name,
+});
+/** Liveness gate — true iff a chat-daemon answers `ping` on its socket. Any failure ⇒ false. */
+export const pingDaemon = async (timeoutMs = 1500) => {
+    try {
+        const r = await daemonRpc('ping', {}, { timeoutMs });
+        return r.pong === true;
+    }
+    catch {
+        return false;
+    }
+};
+//# sourceMappingURL=client.js.map

package/dist/chat_daemon/client.js.map

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

package/dist/claude-md.d.ts

@@ -0,0 +1,39 @@
+/** Resolved path to the user's global CLAUDE.md. */
+export declare function defaultClaudeMdPath(): string;
+export interface PromotedLessonEntry {
+    /** Engine lesson id (e.g. "les-abc12345"). */
+    id: string;
+    /** One-line description (trigger phrase + concise summary). */
+    description: string;
+    /** ISO timestamp the promotion happened. */
+    promoted_at: string;
+}
+/**
+ * Append a one-line entry for a newly promoted lesson into the
+ * CLAUDE.md rules sub-block. Idempotent — if an entry for `id` already
+ * exists, the line is left untouched. Returns the path written + the
+ * new content of the rules block (without sentinels).
+ *
+ * No-op (silent) when:
+ *   - CLAUDE.md doesn't exist
+ *   - The rules sub-block isn't installed yet (user hasn't run
+ *     `opensquid install` against this CLAUDE.md)
+ *
+ * Failure is intentionally non-fatal: lesson promotion is the
+ * authoritative event; CLAUDE.md is downstream display. We never block
+ * the promote on a CLAUDE.md write failure.
+ */
+export declare function appendPromotedLessonToClaudeMd(entry: PromotedLessonEntry, options?: {
+    target?: string;
+}): Promise<{
+    target: string;
+    appended: boolean;
+} | null>;
+/**
+ * For tests + diagnostics: list the lesson ids currently appearing in
+ * the rules sub-block of a given CLAUDE.md.
+ */
+export declare function listRulesBlockLessonIds(options?: {
+    target?: string;
+}): Promise<string[]>;
+//# sourceMappingURL=claude-md.d.ts.map

package/dist/claude-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-md.d.ts","sourceRoot":"","sources":["../src.legacy/claude-md.ts"],"names":[],"mappings":"AA6BA,oDAAoD;AACpD,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC,CA4BvD;AA4BD;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB"}

package/dist/claude-md.js

@@ -0,0 +1,113 @@
+/**
+ * CLAUDE.md sentinel-block management.
+ *
+ * Two managed blocks live inside `~/.claude/CLAUDE.md`:
+ *
+ *   1. `opensquid-automation:start vX.Y.Z` ... `opensquid-automation:end`
+ *      — the outer behavioral instructions block, written by
+ *      `opensquid install` (src/cli.ts).
+ *
+ *   2. `opensquid-rules:start (auto-managed)` ... `opensquid-rules:end`
+ *      — an inner block nested INSIDE the automation block, holding
+ *      one-line summaries of promoted lessons. Auto-managed at
+ *      runtime: every `lesson.promote` success appends an entry here
+ *      so the agent reads promoted rules at session start with no
+ *      recall lag.
+ *
+ * This module exposes the runtime updater for the inner rules block.
+ * The CLAUDE.md installer / uninstaller (src/cli.ts) owns the outer
+ * block; this module ONLY touches what's between the inner sentinels.
+ */
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+const RULES_START = "<!-- opensquid-rules:start (auto-managed) -->";
+const RULES_END = "<!-- opensquid-rules:end -->";
+const PLACEHOLDER = "(no promoted lessons yet";
+/** Resolved path to the user's global CLAUDE.md. */
+export function defaultClaudeMdPath() {
+    return path.join(os.homedir(), ".claude", "CLAUDE.md");
+}
+/**
+ * Append a one-line entry for a newly promoted lesson into the
+ * CLAUDE.md rules sub-block. Idempotent — if an entry for `id` already
+ * exists, the line is left untouched. Returns the path written + the
+ * new content of the rules block (without sentinels).
+ *
+ * No-op (silent) when:
+ *   - CLAUDE.md doesn't exist
+ *   - The rules sub-block isn't installed yet (user hasn't run
+ *     `opensquid install` against this CLAUDE.md)
+ *
+ * Failure is intentionally non-fatal: lesson promotion is the
+ * authoritative event; CLAUDE.md is downstream display. We never block
+ * the promote on a CLAUDE.md write failure.
+ */
+export async function appendPromotedLessonToClaudeMd(entry, options = {}) {
+    const target = options.target ?? defaultClaudeMdPath();
+    let content;
+    try {
+        content = await fs.readFile(target, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const block = findRulesBlock(content);
+    if (!block)
+        return null;
+    // Idempotency: skip if this lesson id already appears in the block.
+    const idMarker = `(lesson:${entry.id})`;
+    if (block.inner.includes(idMarker)) {
+        return { target, appended: false };
+    }
+    // Strip the placeholder if it's the only thing in the block.
+    const cleaned = block.inner.includes(PLACEHOLDER) ? "" : block.inner.trimEnd();
+    const newLine = `- ${entry.description.trim()} ${idMarker} — promoted ${entry.promoted_at}`;
+    const nextInner = cleaned.length === 0 ? `\n${newLine}\n` : `${cleaned}\n${newLine}\n`;
+    const nextContent = content.slice(0, block.innerStart) + nextInner + content.slice(block.innerEnd);
+    await fs.writeFile(target, nextContent, "utf8");
+    return { target, appended: true };
+}
+function findRulesBlock(content) {
+    const startIdx = content.indexOf(RULES_START);
+    if (startIdx === -1)
+        return null;
+    const endIdx = content.indexOf(RULES_END, startIdx + RULES_START.length);
+    if (endIdx === -1)
+        return null;
+    // inner starts right after the start sentinel (allowing a trailing newline).
+    let innerStart = startIdx + RULES_START.length;
+    if (content[innerStart] === "\n")
+        innerStart++;
+    // inner ends at the start of the end sentinel.
+    const innerEnd = endIdx;
+    return {
+        inner: content.slice(innerStart, innerEnd),
+        innerStart,
+        innerEnd,
+    };
+}
+/**
+ * For tests + diagnostics: list the lesson ids currently appearing in
+ * the rules sub-block of a given CLAUDE.md.
+ */
+export async function listRulesBlockLessonIds(options = {}) {
+    const target = options.target ?? defaultClaudeMdPath();
+    let content;
+    try {
+        content = await fs.readFile(target, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const block = findRulesBlock(content);
+    if (!block)
+        return [];
+    const ids = [];
+    const re = /\(lesson:([a-z0-9-]+)\)/g;
+    for (const m of block.inner.matchAll(re)) {
+        ids.push(m[1]);
+    }
+    return ids;
+}
+//# sourceMappingURL=claude-md.js.map

package/dist/claude-md.js.map

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

package/dist/claude-md.test.js

@@ -0,0 +1,91 @@
+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 { appendPromotedLessonToClaudeMd, listRulesBlockLessonIds } from "./claude-md.js";
+let tmpFile;
+beforeEach(async () => {
+    tmpFile = path.join(os.tmpdir(), `oscli-claude-md-${crypto.randomUUID()}.md`);
+});
+afterEach(async () => {
+    await fs.rm(tmpFile, { force: true });
+});
+const INSTALLED_BLOCK = `<!-- opensquid-automation:start v0.4.0 -->
+## opensquid
+
+Use recall before substantive answers.
+
+### Active lessons (auto-managed — do not edit by hand)
+
+<!-- opensquid-rules:start (auto-managed) -->
+(no promoted lessons yet — this block populates as \`lesson.promote\`
+succeeds for user-endorsed candidates)
+<!-- opensquid-rules:end -->
+<!-- opensquid-automation:end -->
+`;
+describe("appendPromotedLessonToClaudeMd", () => {
+    it("returns null when CLAUDE.md doesn't exist", async () => {
+        const res = await appendPromotedLessonToClaudeMd({ id: "les-x", description: "anything", promoted_at: "2026-05-15T00:00:00Z" }, { target: tmpFile });
+        expect(res).toBeNull();
+    });
+    it("returns null when the rules block isn't installed", async () => {
+        await fs.writeFile(tmpFile, "# Just a regular CLAUDE.md\nNothing fancy.\n", "utf8");
+        const res = await appendPromotedLessonToClaudeMd({ id: "les-x", description: "anything", promoted_at: "now" }, { target: tmpFile });
+        expect(res).toBeNull();
+    });
+    it("replaces the placeholder with the first promoted lesson", async () => {
+        await fs.writeFile(tmpFile, INSTALLED_BLOCK, "utf8");
+        const res = await appendPromotedLessonToClaudeMd({
+            id: "les-abc12345",
+            description: "before any git push or release",
+            promoted_at: "2026-05-15T19:00:00Z",
+        }, { target: tmpFile });
+        expect(res?.appended).toBe(true);
+        const content = await fs.readFile(tmpFile, "utf8");
+        expect(content).not.toContain("(no promoted lessons yet");
+        expect(content).toContain("(lesson:les-abc12345)");
+        expect(content).toContain("before any git push or release");
+        expect(content).toContain("promoted 2026-05-15T19:00:00Z");
+    });
+    it("appends subsequent lessons without removing prior ones", async () => {
+        await fs.writeFile(tmpFile, INSTALLED_BLOCK, "utf8");
+        await appendPromotedLessonToClaudeMd({ id: "les-1", description: "first rule", promoted_at: "2026-05-15T19:00:00Z" }, { target: tmpFile });
+        await appendPromotedLessonToClaudeMd({ id: "les-2", description: "second rule", promoted_at: "2026-05-15T19:01:00Z" }, { target: tmpFile });
+        const content = await fs.readFile(tmpFile, "utf8");
+        expect(content).toContain("(lesson:les-1)");
+        expect(content).toContain("(lesson:les-2)");
+        expect(content).toContain("first rule");
+        expect(content).toContain("second rule");
+    });
+    it("is idempotent — re-promoting the same id is a no-op", async () => {
+        await fs.writeFile(tmpFile, INSTALLED_BLOCK, "utf8");
+        await appendPromotedLessonToClaudeMd({ id: "les-1", description: "rule one", promoted_at: "2026-05-15T19:00:00Z" }, { target: tmpFile });
+        const before = await fs.readFile(tmpFile, "utf8");
+        const res = await appendPromotedLessonToClaudeMd({ id: "les-1", description: "rule one", promoted_at: "2026-05-15T19:30:00Z" }, { target: tmpFile });
+        expect(res?.appended).toBe(false);
+        const after = await fs.readFile(tmpFile, "utf8");
+        expect(after).toBe(before);
+    });
+    it("preserves the outer automation block sentinels", async () => {
+        await fs.writeFile(tmpFile, INSTALLED_BLOCK, "utf8");
+        await appendPromotedLessonToClaudeMd({ id: "les-x", description: "anything", promoted_at: "2026-05-15T00:00:00Z" }, { target: tmpFile });
+        const content = await fs.readFile(tmpFile, "utf8");
+        expect(content).toContain("<!-- opensquid-automation:start v0.4.0 -->");
+        expect(content).toContain("<!-- opensquid-automation:end -->");
+        expect(content).toContain("<!-- opensquid-rules:start (auto-managed) -->");
+        expect(content).toContain("<!-- opensquid-rules:end -->");
+    });
+});
+describe("listRulesBlockLessonIds", () => {
+    it("returns [] when no rules block", async () => {
+        await fs.writeFile(tmpFile, "# plain\n", "utf8");
+        expect(await listRulesBlockLessonIds({ target: tmpFile })).toEqual([]);
+    });
+    it("returns ids in append order", async () => {
+        await fs.writeFile(tmpFile, INSTALLED_BLOCK, "utf8");
+        await appendPromotedLessonToClaudeMd({ id: "les-aaa", description: "a", promoted_at: "t1" }, { target: tmpFile });
+        await appendPromotedLessonToClaudeMd({ id: "les-bbb", description: "b", promoted_at: "t2" }, { target: tmpFile });
+        expect(await listRulesBlockLessonIds({ target: tmpFile })).toEqual(["les-aaa", "les-bbb"]);
+    });
+});

package/dist/cli/pack.d.ts

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+export type ExportMode = 'lessons-only' | 'raw';
+export interface PackCliDeps {
+    /** Test seam — override stdout for assertion. */
+    out?: (line: string) => void;
+    /** Test seam — bypass interactive prompt; treat all confirmations as yes. */
+    forceYes?: boolean;
+}
+export declare function buildInstallCommand(deps?: PackCliDeps): Command;
+export declare function buildListCommand(deps?: PackCliDeps): Command;
+export declare function buildExportCommand(deps?: PackCliDeps): Command;
+export declare function buildRemoveCommand(deps?: PackCliDeps): Command;
+export declare function registerPackCli(program: Command, deps?: PackCliDeps): Command;
+//# sourceMappingURL=pack.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/cli/pack.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,KAAK,CAAC;AAiBhD,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAiCD,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAsDnE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAgChE;AAYD,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAiDlE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAuClE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CASjF"}

package/dist/cli/pack.js

@@ -0,0 +1,232 @@
+/**
+ * LP.4 — `opensquid pack` CLI surface: install / list / export / remove.
+ *
+ * v1 minimum-viable per pragmatic scope:
+ *   - install: local directory only (tarball + URL deferred to v1.5)
+ *   - list: full
+ *   - export: lessons-only + raw (with-evidence deferred to v1.5)
+ *   - remove: --yes + --also-personal-revision flags
+ *
+ * Path-traversal defense via `validatePackId` (LP.3) on every command that
+ * accepts a pack name. `personal_revision/` preserved by default on remove
+ * (no-delete axiom per [[project_memory_architecture_dual_surface_sync]]).
+ *
+ * Imports: commander, node:fs/promises, node:os, node:path, yaml,
+ *   LP.1 personal_revision + LP.2 versioning + LP.3 discovery helpers.
+ */
+import { cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { resolvePackStateDir, validatePackId } from '../packs/discovery.js';
+import { initPersonalRevision, readLessonFiles, readVersionJson, } from '../packs/personal_revision.js';
+import { Manifest } from '../packs/schemas/manifest.js';
+import { runThreeWayMerge } from '../runtime/versioning.js';
+function emit(deps) {
+    return deps.out ?? ((line) => process.stdout.write(line + '\n'));
+}
+async function readAndValidateManifest(packDir) {
+    const raw = await readFile(join(packDir, 'manifest.yaml'), 'utf8');
+    const parsed = parseYaml(raw);
+    const manifest = Manifest.parse(parsed);
+    return { name: manifest.name, version: manifest.version };
+}
+function semverLt(a, b) {
+    const ap = a
+        .split('-')[0]
+        .split('.')
+        .map((n) => Number.parseInt(n, 10));
+    const bp = b
+        .split('-')[0]
+        .split('.')
+        .map((n) => Number.parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const d = (ap[i] ?? 0) - (bp[i] ?? 0);
+        if (d < 0)
+            return true;
+        if (d > 0)
+            return false;
+    }
+    return false;
+}
+export function buildInstallCommand(deps = {}) {
+    const print = emit(deps);
+    return new Command('install')
+        .description('Install a pack from a local directory (tarball + URL deferred to v1.5)')
+        .argument('<source>', 'Path to pack directory containing manifest.yaml')
+        .option('--scope <scope>', 'user | project', 'user')
+        .option('--project-cwd <path>', 'Project root (required for --scope project)')
+        .action(async (source, opts) => {
+        const manifest = await readAndValidateManifest(source);
+        validatePackId(manifest.name);
+        const stateDir = resolvePackStateDir(manifest.name, opts.scope ?? 'user', opts.projectCwd);
+        const existing = await readVersionJson(stateDir);
+        if (existing !== null && existing.base_version !== manifest.version) {
+            if (semverLt(existing.base_version, manifest.version)) {
+                // Upgrade — copy new vanilla to staging + run merge.
+                const stagingDir = join(stateDir, 'base-staging');
+                await rm(stagingDir, { recursive: true, force: true });
+                await cp(source, stagingDir, { recursive: true });
+                const mergeResult = await runThreeWayMerge({
+                    packId: manifest.name,
+                    baseDir: join(stateDir, 'base'),
+                    personalStateDir: stateDir,
+                    vanillaDir: stagingDir,
+                    vanillaVersion: manifest.version,
+                });
+                // Promote staging → base after successful merge.
+                await rm(join(stateDir, 'base'), { recursive: true, force: true });
+                await cp(stagingDir, join(stateDir, 'base'), { recursive: true });
+                await rm(stagingDir, { recursive: true, force: true });
+                print(`[opensquid pack install] Upgraded ${manifest.name} from ${existing.base_version} → ${manifest.version}`);
+                print(`  - dispositions: ${String(mergeResult.dispositions.length)}`);
+                print(`  - conflicts:    ${String(mergeResult.conflictCount)}`);
+                if (mergeResult.conflictCount > 0) {
+                    print(`  Resolve conflicts in ${stateDir}/personal_revision/*.conflict.yaml then rename back to .yaml`);
+                }
+            }
+            else {
+                throw new Error(`Downgrade rejected: existing ${existing.base_version} > new ${manifest.version}. v1 does not support --force.`);
+            }
+        }
+        else {
+            await mkdir(stateDir, { recursive: true });
+            await cp(source, join(stateDir, 'base'), { recursive: true });
+            await initPersonalRevision(stateDir, manifest.version);
+            print(`[opensquid pack install] Installed ${manifest.name}@${manifest.version} → ${stateDir}`);
+        }
+    });
+}
+export function buildListCommand(deps = {}) {
+    const print = emit(deps);
+    return new Command('list')
+        .description('List installed packs')
+        .option('--scope <scope>', 'user | project', 'user')
+        .option('--project-cwd <path>', 'Project root (required for --scope project)')
+        .action(async (opts) => {
+        const baseDir = opts.scope === 'project'
+            ? join(opts.projectCwd ?? process.cwd(), '.opensquid', 'packs')
+            : join(process.env.OPENSQUID_HOME ?? join(homedir(), '.opensquid'), 'packs');
+        let entries;
+        try {
+            entries = await readdir(baseDir);
+        }
+        catch {
+            print(`[opensquid pack list] No packs installed in ${baseDir}`);
+            return;
+        }
+        let listed = 0;
+        for (const name of entries) {
+            const stateDir = join(baseDir, name);
+            const version = await readVersionJson(stateDir).catch(() => null);
+            if (version === null)
+                continue;
+            const lastMerged = version.last_merged_vanilla !== null ? ` lastMerged=${version.last_merged_vanilla}` : '';
+            print(`${name.padEnd(40)} base=${version.base_version} revision=${String(version.personal_revision_id)}${lastMerged}`);
+            listed++;
+        }
+        if (listed === 0)
+            print(`[opensquid pack list] No installed packs in ${baseDir}`);
+    });
+}
+function stripLessonsOnly(lessons) {
+    return lessons.map((lesson) => {
+        const bodyStr = JSON.stringify(lesson.body);
+        const stripped = bodyStr.replace(/<cite\s+id=mem-[a-f0-9-]+>([^<]*)<\/cite>/g, '$1');
+        const parsedBody = JSON.parse(stripped);
+        delete parsedBody.cited_memory_ids;
+        return { ...lesson, body: parsedBody };
+    });
+}
+export function buildExportCommand(deps = {}) {
+    const print = emit(deps);
+    return new Command('export')
+        .description('Export a pack with one of 2 stripping modes (with-evidence is v1.5)')
+        .argument('<name>', 'Pack name')
+        .option('--mode <mode>', 'lessons-only (default) | raw', 'lessons-only')
+        .option('--out <path>', 'Output directory path (default <name>-<mode>-export/)')
+        .option('--scope <scope>', 'user | project', 'user')
+        .option('--project-cwd <path>', 'Project root (required for --scope project)')
+        .action(async (name, opts) => {
+        validatePackId(name);
+        const mode = opts.mode ?? 'lessons-only';
+        if (mode !== 'lessons-only' && mode !== 'raw') {
+            throw new Error(`Invalid --mode: ${String(mode)}. v1 ships: lessons-only | raw. (with-evidence deferred to v1.5)`);
+        }
+        const stateDir = resolvePackStateDir(name, opts.scope ?? 'user', opts.projectCwd);
+        const version = await readVersionJson(stateDir);
+        if (version === null) {
+            throw new Error(`Pack ${name} is not installed (no version.json at ${stateDir})`);
+        }
+        const lessons = await readLessonFiles(stateDir);
+        const exportedLessons = mode === 'raw' ? lessons : stripLessonsOnly(lessons);
+        const outDir = opts.out ?? `${name}-${mode}-export`;
+        await mkdir(outDir, { recursive: true });
+        // Copy manifest + skills tree from base/
+        await cp(join(stateDir, 'base'), join(outDir, 'pack'), { recursive: true }).catch(() => undefined);
+        // Write lessons + version.json (raw only)
+        const lessonsOutDir = join(outDir, 'personal_revision');
+        await mkdir(lessonsOutDir, { recursive: true });
+        for (const lesson of exportedLessons) {
+            const fname = lesson.hasConflict
+                ? `lesson_${String(lesson.id)}.conflict.yaml`
+                : `lesson_${String(lesson.id)}.yaml`;
+            await writeFile(join(lessonsOutDir, fname), stringifyYaml(lesson.body), 'utf8');
+        }
+        if (mode === 'raw') {
+            await writeFile(join(lessonsOutDir, 'version.json'), JSON.stringify(version, null, 2), 'utf8');
+        }
+        print(`[opensquid pack export] Exported ${name} → ${outDir} (mode: ${mode})`);
+        print(`  - lessons:  ${String(exportedLessons.length)}`);
+    });
+}
+export function buildRemoveCommand(deps = {}) {
+    const print = emit(deps);
+    return new Command('remove')
+        .description('Remove an installed pack (preserves personal_revision/ by default)')
+        .argument('<name>', 'Pack name')
+        .option('--yes', 'Skip confirmation prompt', false)
+        .option('--also-personal-revision', 'Also delete personal_revision/ (DESTRUCTIVE)', false)
+        .option('--scope <scope>', 'user | project', 'user')
+        .option('--project-cwd <path>', 'Project root (required for --scope project)')
+        .action(async (name, opts) => {
+        validatePackId(name);
+        const stateDir = resolvePackStateDir(name, opts.scope ?? 'user', opts.projectCwd);
+        const version = await readVersionJson(stateDir).catch(() => null);
+        if (version === null) {
+            print(`[opensquid pack remove] Pack ${name} is not installed`);
+            return;
+        }
+        const skipPrompt = opts.yes === true || deps.forceYes === true;
+        if (!skipPrompt) {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const ans = await rl.question(`Remove pack ${name} (revision=${String(version.personal_revision_id)})? [y/N] `);
+            rl.close();
+            if (ans.trim().toLowerCase() !== 'y') {
+                print('Aborted.');
+                return;
+            }
+        }
+        await rm(join(stateDir, 'base'), { recursive: true, force: true });
+        if (opts.alsoPersonalRevision === true) {
+            await rm(join(stateDir, 'personal_revision'), { recursive: true, force: true });
+            print(`[opensquid pack remove] Removed ${name} (including personal_revision/)`);
+        }
+        else {
+            print(`[opensquid pack remove] Removed ${name} (preserved personal_revision/ — delete manually if desired)`);
+        }
+    });
+}
+export function registerPackCli(program, deps = {}) {
+    const pack = program
+        .command('pack')
+        .description('Manage installed opensquid packs (install / list / export / remove)');
+    pack.addCommand(buildInstallCommand(deps));
+    pack.addCommand(buildListCommand(deps));
+    pack.addCommand(buildExportCommand(deps));
+    pack.addCommand(buildRemoveCommand(deps));
+    return pack;
+}
+//# sourceMappingURL=pack.js.map