okstra 0.174.0 → 0.176.0

package/{src → dist}/commands/manager.mjs

@@ -1,6 +1,5 @@
 import { runPythonModule } from "../lib/python-helper.mjs";
 import { resolvePaths } from "../lib/paths.mjs";
-
 const USAGE = `okstra manager — manage cross-project okstra tasks
 
 Usage:
@@ -17,41 +16,35 @@ Usage:
 
   --workspace-root is owned by this command.
 `;
-
 const OWNED_FLAGS = new Set(["--workspace-root"]);
-
 function isOwnedFlag(arg) {
-  if (OWNED_FLAGS.has(arg)) return true;
-  return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
+    if (OWNED_FLAGS.has(arg))
+        return true;
+    return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
 }
-
 export function buildManagerArgs(args, paths) {
-  return ["--workspace-root", paths.workspace, ...args];
+    return ["--workspace-root", paths.workspace, ...args];
 }
-
 export async function run(args) {
-  const forbidden = args.find(isOwnedFlag);
-  if (forbidden) {
-    process.stderr.write(
-      `error: ${forbidden} is set by 'okstra manager' itself — remove it from your args\n`,
-    );
-    return 2;
-  }
-
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  if (args.length === 0) {
-    process.stdout.write(USAGE);
-    return 2;
-  }
-
-  const paths = await resolvePaths();
-  const result = await runPythonModule({
-    module: "okstra_ctl.manager_cli",
-    args: buildManagerArgs(args, paths),
-    stdio: "inherit-stdout",
-  });
-  return result.code;
+    const forbidden = args.find(isOwnedFlag);
+    if (forbidden) {
+        process.stderr.write(`error: ${forbidden} is set by 'okstra manager' itself — remove it from your args\n`);
+        return 2;
+    }
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (args.length === 0) {
+        process.stdout.write(USAGE);
+        return 2;
+    }
+    const paths = await resolvePaths();
+    const result = await runPythonModule({
+        module: "okstra_ctl.manager_cli",
+        args: buildManagerArgs(args, paths),
+        stdio: "inherit-stdout",
+    });
+    return result.code;
 }
+//# sourceMappingURL=manager.mjs.map

package/dist/commands/manager.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.mjs","sourceRoot":"","sources":["../../src/commands/manager.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;CAeb,CAAC;AAEF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAElD,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAa,EAAE,KAAmB;IACjE,OAAO,CAAC,kBAAkB,EAAE,KAAK,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,IAAuB;IAC/C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACzC,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,UAAU,SAAS,iEAAiE,CACrF,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;QACnC,MAAM,EAAE,wBAAwB;QAChC,IAAI,EAAE,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC;QACnC,KAAK,EAAE,gBAAgB;KACxB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/commands/memory/memory.d.mts

@@ -0,0 +1 @@
+export declare function run(args: readonly string[]): Promise<number>;

package/dist/commands/memory/memory.mjs

@@ -0,0 +1,569 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { resolveOkstraHome } from "../../lib/paths.mjs";
+const MEMORY_TYPES = new Set([
+    "context",
+    "decision",
+    "preference",
+    "requirement",
+    "person",
+    "project-hint",
+    "follow-up",
+]);
+function isMemoryType(value) {
+    return MEMORY_TYPES.has(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+// High-confidence secret shapes. The skill instructs the agent to omit secrets,
+// but this is the CLI-side enforcement (declaration → enforcement) so a stray
+// credential cannot be persisted. Patterns are intentionally narrow (known token
+// prefixes / key blocks) to avoid false-positives on prose that merely mentions
+// "password" or "token".
+const SECRET_PATTERNS = [
+    [/-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/, "private key block"],
+    [/\bAKIA[0-9A-Z]{16}\b/, "AWS access key id"],
+    [/\bASIA[0-9A-Z]{16}\b/, "AWS temporary access key id"],
+    [/\bgh[posru]_[A-Za-z0-9]{36,}\b/, "GitHub token"],
+    [/\bgithub_pat_[A-Za-z0-9_]{60,}\b/, "GitHub fine-grained token"],
+    [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/, "Slack token"],
+    [/\bAIza[0-9A-Za-z_-]{35}\b/, "Google API key"],
+    [/\bsk-[A-Za-z0-9]{20,}\b/, "OpenAI-style secret key"],
+    [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/, "JWT"],
+];
+function detectSecrets(content) {
+    const hits = [];
+    for (const [pattern, label] of SECRET_PATTERNS) {
+        if (pattern.test(content))
+            hits.push(label);
+    }
+    return [...new Set(hits)];
+}
+const USAGE = `okstra memory — store and find conversation memory
+
+Memory Book stores global, user-home notes under ~/.okstra/memory-book.
+It is separate from project-local .okstra task artifacts.
+
+Usage:
+  okstra memory add [--content <text> | --file <path>] [options]
+  okstra memory list [--limit <n>] [--tag <tag>] [--type <type>]
+                     [--project-group <name>] [--json]
+  okstra memory search <query> [--limit <n>] [--project-group <name>]
+                       [--include-archived] [--json]
+  okstra memory groups [--include-archived] [--json]
+  okstra memory show <id> [--json]
+  okstra memory archive <id> [--json]
+
+Add options:
+  --title <title>       Entry title. Defaults to the first non-empty line.
+  --type <type>         context|decision|preference|requirement|person|
+                        project-hint|follow-up. Default: context.
+  --project-group <name> Project group label (e.g. acme, private). Default: global.
+  --project <id>        Related project id. Repeatable.
+  --tag <tag>           Tag. Repeatable or comma-separated.
+  --source <source>     Source label. Default: conversation.
+  --yes                 Skip interactive confirmation.
+  --json                Emit JSON.
+`;
+function okstraHome() {
+    return resolveOkstraHome();
+}
+function memoryRoot() {
+    return join(okstraHome(), "memory-book");
+}
+function indexPath() {
+    return join(memoryRoot(), "index.jsonl");
+}
+function parseGlobalFlags(args) {
+    return {
+        json: args.includes("--json"),
+        includeArchived: args.includes("--include-archived"),
+    };
+}
+function takeValue(args, index, flag) {
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+function parseAddArgs(args) {
+    const opts = {
+        content: null,
+        file: null,
+        title: null,
+        type: "context",
+        projectGroup: "global",
+        source: "conversation",
+        tags: [],
+        projects: [],
+        yes: false,
+        json: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const flag = args[i];
+        if (flag === "--content")
+            opts.content = takeValue(args, i++, flag);
+        else if (flag === "--file")
+            opts.file = takeValue(args, i++, flag);
+        else if (flag === "--title")
+            opts.title = takeValue(args, i++, flag);
+        else if (flag === "--type")
+            opts.type = takeValue(args, i++, flag);
+        else if (flag === "--project-group")
+            opts.projectGroup = takeValue(args, i++, flag);
+        else if (flag === "--source")
+            opts.source = takeValue(args, i++, flag);
+        else if (flag === "--project")
+            opts.projects.push(takeValue(args, i++, flag));
+        else if (flag === "--tag")
+            opts.tags.push(...splitCsv(takeValue(args, i++, flag)));
+        else if (flag === "--yes")
+            opts.yes = true;
+        else if (flag === "--json")
+            opts.json = true;
+        else
+            throw new Error(`unknown flag ${flag}`);
+    }
+    if (!isMemoryType(opts.type)) {
+        throw new Error(`invalid --type: ${opts.type}`);
+    }
+    if (opts.content !== null && opts.file !== null) {
+        throw new Error("pass only one of --content or --file");
+    }
+    return { ...opts, type: opts.type };
+}
+function parseListArgs(args) {
+    const opts = { ...parseGlobalFlags(args), limit: 20, tag: null, type: null, projectGroup: null };
+    for (let i = 0; i < args.length; i++) {
+        const flag = args[i];
+        if (flag === undefined)
+            continue;
+        if (flag === "--json" || flag === "--include-archived")
+            continue;
+        if (flag === "--limit")
+            opts.limit = parseLimit(takeValue(args, i++, flag));
+        else if (flag === "--tag")
+            opts.tag = takeValue(args, i++, flag);
+        else if (flag === "--type")
+            opts.type = takeValue(args, i++, flag);
+        else if (flag === "--project-group")
+            opts.projectGroup = takeValue(args, i++, flag);
+        else
+            throw new Error(`unknown flag ${flag}`);
+    }
+    return opts;
+}
+function parseQueryArgs(args) {
+    const opts = { ...parseGlobalFlags(args), limit: 20, query: [], projectGroup: null };
+    for (let i = 0; i < args.length; i++) {
+        const flag = args[i];
+        if (flag === undefined)
+            continue;
+        if (flag === "--json" || flag === "--include-archived")
+            continue;
+        if (flag === "--limit")
+            opts.limit = parseLimit(takeValue(args, i++, flag));
+        else if (flag === "--project-group")
+            opts.projectGroup = takeValue(args, i++, flag);
+        else if (flag.startsWith("--"))
+            throw new Error(`unknown flag ${flag}`);
+        else
+            opts.query.push(flag);
+    }
+    if (opts.query.length === 0)
+        throw new Error("search requires a query");
+    return { ...opts, query: opts.query.join(" ").trim() };
+}
+function parseGroupsArgs(args) {
+    for (const flag of args) {
+        if (flag !== "--json" && flag !== "--include-archived") {
+            throw new Error(`unknown flag ${flag}`);
+        }
+    }
+    return parseGlobalFlags(args);
+}
+function entryGroup(entry) {
+    return entry.projectGroup ?? "global";
+}
+function parseLimit(raw) {
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error("--limit must be a positive integer");
+    }
+    return value;
+}
+function splitCsv(value) {
+    return value
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+async function readInputContent(opts) {
+    if (opts.content !== null)
+        return opts.content;
+    if (opts.file !== null)
+        return fs.readFile(resolve(opts.file), "utf8");
+    if (!process.stdin.isTTY)
+        return readStdin();
+    throw new Error("memory add requires --content, --file, or stdin");
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+function inferTitle(content, explicitTitle, filePath) {
+    if (explicitTitle?.trim())
+        return explicitTitle.trim();
+    const firstLine = content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find(Boolean);
+    if (firstLine)
+        return truncate(firstLine.replace(/^#+\s*/, ""), 80);
+    if (filePath)
+        return basename(filePath);
+    return "Untitled memory";
+}
+function truncate(value, maxLength) {
+    return value.length > maxLength ? `${value.slice(0, maxLength - 3)}...` : value;
+}
+function slugify(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9가-힣]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    return slug || "memory";
+}
+function buildEntry(opts, content, now) {
+    const title = inferTitle(content, opts.title, opts.file);
+    const compact = now.toISOString().replace(/\D/g, "").slice(0, 17);
+    const slug = slugify(title);
+    // Random suffix disambiguates two same-title adds within one millisecond,
+    // which would otherwise collide on both id and on-disk path (silent overwrite).
+    const nonce = randomBytes(3).toString("hex");
+    const id = `mem_${compact}_${slug}_${nonce}`;
+    const relativePath = join("entries", String(now.getUTCFullYear()), String(now.getUTCMonth() + 1).padStart(2, "0"), `${now.toISOString().replace(/[:.]/g, "")}-${slug}-${nonce}.md`);
+    return {
+        id,
+        title,
+        type: opts.type,
+        projectGroup: opts.projectGroup,
+        source: opts.source,
+        tags: [...new Set(opts.tags)],
+        relatedProjects: [...new Set(opts.projects)],
+        status: "active",
+        createdAt: now.toISOString(),
+        archivedAt: null,
+        path: relativePath,
+    };
+}
+function renderMarkdown(entry, content) {
+    return [
+        "---",
+        `id: ${entry.id}`,
+        `createdAt: ${entry.createdAt}`,
+        `source: ${entry.source}`,
+        `project-group: ${entry.projectGroup}`,
+        `type: ${entry.type}`,
+        `status: ${entry.status}`,
+        `relatedProjects: [${entry.relatedProjects.join(", ")}]`,
+        `tags: [${entry.tags.join(", ")}]`,
+        "---",
+        "",
+        `# ${entry.title}`,
+        "",
+        "## Summary",
+        "",
+        content.trim() || "(empty)",
+        "",
+    ].join("\n");
+}
+async function confirmSave(entry, content, opts) {
+    if (opts.yes || opts.json || !process.stdin.isTTY)
+        return true;
+    process.stdout.write(`Memory Book entry:\n`);
+    process.stdout.write(`  title: ${entry.title}\n`);
+    process.stdout.write(`  type:  ${entry.type}\n`);
+    process.stdout.write(`  group: ${entry.projectGroup}\n`);
+    process.stdout.write(`  tags:  ${entry.tags.join(", ") || "(none)"}\n`);
+    process.stdout.write(`  text:  ${truncate(content.trim().replace(/\s+/g, " "), 140)}\n`);
+    const rl = createInterface({ input, output });
+    const answer = await rl.question("Save to ~/.okstra/memory-book? [y/N] ");
+    rl.close();
+    return /^y(es)?$/i.test(answer.trim());
+}
+async function appendIndex(entry) {
+    await fs.mkdir(dirname(indexPath()), { recursive: true });
+    await fs.appendFile(indexPath(), JSON.stringify(entry) + "\n", "utf8");
+}
+function isMemoryEntry(value) {
+    if (!isRecord(value))
+        return false;
+    const record = value;
+    return (typeof record.id === "string" &&
+        typeof record.title === "string" &&
+        typeof record.type === "string" &&
+        isMemoryType(record.type) &&
+        typeof record.projectGroup === "string" &&
+        typeof record.source === "string" &&
+        Array.isArray(record.tags) &&
+        record.tags.every((tag) => typeof tag === "string") &&
+        Array.isArray(record.relatedProjects) &&
+        record.relatedProjects.every((project) => typeof project === "string") &&
+        (record.status === "active" || record.status === "archived") &&
+        typeof record.createdAt === "string" &&
+        (record.archivedAt === null || typeof record.archivedAt === "string") &&
+        typeof record.path === "string");
+}
+async function readIndex() {
+    let text;
+    try {
+        text = await fs.readFile(indexPath(), "utf8");
+    }
+    catch (err) {
+        if (isRecord(err) && err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    // Skip lines that fail to parse so one truncated row (e.g. an interrupted
+    // appendIndex) cannot make the whole Memory Book unreadable; other JSONL
+    // readers in okstra tolerate corruption the same way.
+    const entries = [];
+    for (const line of text.split(/\r?\n/)) {
+        if (!line)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isMemoryEntry(parsed))
+                entries.push(parsed);
+        }
+        catch {
+            // Drop the unparseable row; intact entries remain visible.
+        }
+    }
+    return entries;
+}
+async function writeIndex(entries) {
+    await fs.mkdir(dirname(indexPath()), { recursive: true });
+    const data = entries.map((entry) => JSON.stringify(entry)).join("\n");
+    await fs.writeFile(indexPath(), data ? `${data}\n` : "", "utf8");
+}
+function visibleEntries(entries, opts) {
+    return entries.filter((entry) => opts.includeArchived || entry.status !== "archived");
+}
+function formatEntryLine(entry) {
+    const tags = entry.tags.length > 0 ? ` #${entry.tags.join(" #")}` : "";
+    return `${entry.id}  ${entry.createdAt.slice(0, 10)}  ${entry.type}  ${entry.title}${tags}`;
+}
+function emitJson(payload) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+async function opAdd(args) {
+    const opts = parseAddArgs(args);
+    const content = await readInputContent(opts);
+    const secrets = detectSecrets(content);
+    if (secrets.length > 0) {
+        throw new Error(`refusing to store likely secret(s): ${secrets.join(", ")}. ` +
+            "Memory Book must not hold credentials — redact the secret and store a note instead.");
+    }
+    const entry = buildEntry(opts, content, new Date());
+    if (!(await confirmSave(entry, content, opts))) {
+        process.stdout.write("cancelled\n");
+        return 0;
+    }
+    const absolutePath = join(memoryRoot(), entry.path);
+    await fs.mkdir(dirname(absolutePath), { recursive: true });
+    await fs.writeFile(absolutePath, renderMarkdown(entry, content), "utf8");
+    try {
+        await appendIndex(entry);
+    }
+    catch (err) {
+        // Index append failed after the file was written — remove the orphan so
+        // `add` stays all-or-nothing (an entry with no index row is invisible to
+        // list/search anyway).
+        await fs.rm(absolutePath, { force: true });
+        throw err;
+    }
+    if (opts.json)
+        emitJson({ ok: true, entry, path: absolutePath });
+    else
+        process.stdout.write(`saved ${entry.id}\n${absolutePath}\n`);
+    return 0;
+}
+async function opList(args) {
+    const opts = parseListArgs(args);
+    const entries = visibleEntries(await readIndex(), opts)
+        .filter((entry) => !opts.tag || entry.tags.includes(opts.tag))
+        .filter((entry) => !opts.type || entry.type === opts.type)
+        .filter((entry) => !opts.projectGroup || entryGroup(entry) === opts.projectGroup)
+        .slice(0, opts.limit);
+    if (opts.json)
+        emitJson(entries);
+    else
+        process.stdout.write(entries.map(formatEntryLine).join("\n") + (entries.length ? "\n" : ""));
+    return 0;
+}
+async function opSearch(args) {
+    const opts = parseQueryArgs(args);
+    const needle = opts.query.toLowerCase();
+    const entries = visibleEntries(await readIndex(), opts).filter((entry) => !opts.projectGroup || entryGroup(entry) === opts.projectGroup);
+    const matches = [];
+    for (const entry of entries) {
+        if (await entryMatches(entry, needle))
+            matches.push(entry);
+        if (matches.length >= opts.limit)
+            break;
+    }
+    if (opts.json)
+        emitJson(matches);
+    else
+        process.stdout.write(matches.map(formatEntryLine).join("\n") + (matches.length ? "\n" : ""));
+    return 0;
+}
+async function opGroups(args) {
+    const opts = parseGroupsArgs(args);
+    const counts = new Map();
+    for (const entry of visibleEntries(await readIndex(), opts)) {
+        const group = entryGroup(entry);
+        counts.set(group, (counts.get(group) ?? 0) + 1);
+    }
+    const groups = [...counts.entries()]
+        .map(([name, count]) => ({ name, count }))
+        .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+    if (opts.json)
+        emitJson(groups);
+    else
+        process.stdout.write(groups.map((g) => `${g.name}  (${g.count})`).join("\n") + (groups.length ? "\n" : ""));
+    return 0;
+}
+async function entryMatches(entry, needle) {
+    const haystack = [
+        entry.id,
+        entry.title,
+        entry.type,
+        entryGroup(entry),
+        entry.source,
+        ...entry.tags,
+        ...entry.relatedProjects,
+    ]
+        .join(" ")
+        .toLowerCase();
+    if (haystack.includes(needle))
+        return true;
+    try {
+        const body = await fs.readFile(join(memoryRoot(), entry.path), "utf8");
+        return body.toLowerCase().includes(needle);
+    }
+    catch {
+        return false;
+    }
+}
+async function findEntry(id) {
+    const entries = await readIndex();
+    const entry = entries.find((candidate) => candidate.id === id);
+    if (!entry)
+        throw new Error(`memory entry not found: ${id}`);
+    return { entry, entries };
+}
+async function opShow(args) {
+    const json = args.includes("--json");
+    const ids = args.filter((arg) => arg !== "--json");
+    if (ids.length !== 1)
+        throw new Error("show requires exactly one id");
+    const id = ids[0];
+    if (id === undefined)
+        throw new Error("show requires exactly one id");
+    const { entry } = await findEntry(id);
+    const absolutePath = join(memoryRoot(), entry.path);
+    const body = await fs.readFile(absolutePath, "utf8");
+    if (json)
+        emitJson({ entry, path: absolutePath, body });
+    else
+        process.stdout.write(body);
+    return 0;
+}
+async function opArchive(args) {
+    const json = args.includes("--json");
+    const ids = args.filter((arg) => arg !== "--json");
+    if (ids.length !== 1)
+        throw new Error("archive requires exactly one id");
+    const id = ids[0];
+    if (id === undefined)
+        throw new Error("archive requires exactly one id");
+    const { entry, entries } = await findEntry(id);
+    const archivedEntry = await moveToArchive(entry);
+    const updated = entries.map((candidate) => candidate.id === entry.id ? archivedEntry : candidate);
+    try {
+        await writeIndex(updated);
+    }
+    catch (err) {
+        // Index rewrite failed after the file was already moved — move it back so
+        // the index keeps pointing at the file's real location (mirrors opAdd).
+        if (archivedEntry.path !== entry.path) {
+            await fs.rename(join(memoryRoot(), archivedEntry.path), join(memoryRoot(), entry.path));
+        }
+        throw err;
+    }
+    if (json)
+        emitJson({ ok: true, entry: archivedEntry });
+    else
+        process.stdout.write(`archived ${entry.id}\n`);
+    return 0;
+}
+async function moveToArchive(entry) {
+    if (entry.status === "archived")
+        return entry;
+    const sourcePath = join(memoryRoot(), entry.path);
+    const archiveDir = join("archive", entry.createdAt.slice(0, 4));
+    const nextPath = join(archiveDir, basename(entry.path));
+    const targetPath = join(memoryRoot(), nextPath);
+    await fs.mkdir(dirname(targetPath), { recursive: true });
+    await fs.rename(sourcePath, targetPath);
+    return {
+        ...entry,
+        status: "archived",
+        archivedAt: new Date().toISOString(),
+        path: relative(memoryRoot(), targetPath),
+    };
+}
+export async function run(args) {
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(USAGE);
+        return args.length === 0 ? 2 : 0;
+    }
+    const op = args[0];
+    const rest = args.slice(1);
+    try {
+        switch (op) {
+            case "add":
+                return await opAdd(rest);
+            case "list":
+                return await opList(rest);
+            case "search":
+                return await opSearch(rest);
+            case "groups":
+                return await opGroups(rest);
+            case "show":
+                return await opShow(rest);
+            case "archive":
+                return await opArchive(rest);
+            default:
+                process.stderr.write(`unknown memory subcommand: ${op}\n\n${USAGE}`);
+                return 2;
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`error: ${message}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=memory.mjs.map