memarium 0.13.1

package/assets/workflows/memarium-aggregate.yml

@@ -0,0 +1,66 @@
+# Auto-generated by `memarium workflow init`. Edit freely once committed.
+#
+# Purpose: aggregate every device branch's book/ into main. The LLM work
+# (chronicle/topics/cards writing) happens LOCALLY on each device via
+# `memarium sync`. This workflow never calls an LLM — it just does a
+# deterministic merge so `main` shows a unified view across all your devices.
+#
+# Triggers on push to ANY branch except main. The script is bundled in
+# this repo at scripts/merge-books.mjs (written by `memarium workflow init`).
+
+name: memarium aggregate book
+
+on:
+  push:
+    branches-ignore:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write       # push merged book/ to main
+
+concurrency:
+  group: memarium-aggregate
+  cancel-in-progress: false
+
+jobs:
+  aggregate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout main (orphan if missing)
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+        continue-on-error: true
+
+      - name: Ensure main branch exists
+        run: |
+          if ! git rev-parse --verify main >/dev/null 2>&1; then
+            git checkout --orphan main
+            git rm -rf . 2>/dev/null || true
+            git commit --allow-empty -m "memarium: initialize main branch"
+          else
+            git checkout main
+          fi
+
+      - name: Set up Node 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Configure git identity
+        run: |
+          git config user.name  "memarium-bot"
+          git config user.email "memarium-bot@users.noreply.github.com"
+
+      - name: Aggregate device books into main
+        env:
+          # Locale for rendered book pages. Substituted by `memarium workflow init`
+          # from the user's ~/.memarium/config.json `bookLocale` field. Default "en".
+          MEMARIUM_LOCALE: "__MEMARIUM_LOCALE__"
+        run: node scripts/merge-books.mjs
+
+      - name: Push main
+        run: git push origin HEAD:main

package/dist/bin/memarium.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+run(process.argv).catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/dist/src/aggregated-store.js

@@ -0,0 +1,95 @@
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { simpleGit } from "simple-git";
+/** Per-clone read-only mirror of `origin/main` mounted as a separate git
+ *  worktree. Holds the union of every device's raw_sessions/ plus
+ *  `.memarium/index.aggregated.json` (written by CI's merge-books.mjs).
+ *
+ *  P7 (0.8.0): without this, `memarium resume <id>` could only find sessions
+ *  recorded by THIS device — sessions captured on a sibling device were
+ *  unreachable until you manually checked out the other device branch.
+ *
+ *  Layout: `<HOME>/.memarium/aggregated/` — sibling to `session-repo/`.
+ *  Both worktrees share the same `.git` database. */
+export function aggregatedPath() {
+    return join(homedir(), ".memarium", "aggregated");
+}
+/** Path inside aggregated worktree where merge-books.mjs writes the union
+ *  index. Absent when CI hasn't run yet or no device had spool data. */
+export function aggregatedIndexAbs() {
+    return join(aggregatedPath(), ".memarium", "index.aggregated.json");
+}
+/**
+ * Ensure the aggregated worktree exists and points at the latest origin/main.
+ * Best-effort — returns true on success, false otherwise (caller logs and
+ * proceeds; aggregation is opt-in eye candy, not a hard requirement).
+ *
+ * First call: `git worktree add <aggPath> main` from the session-repo.
+ * Subsequent calls: `git -C <aggPath> fetch + reset --hard origin/main`.
+ * (Use reset instead of pull --ff-only because CI rewrites raw_sessions/
+ * with every aggregate commit; a pure ff is the common case but reset
+ * keeps the worktree clean even when the user accidentally edits files
+ * inside it.)
+ */
+export async function refreshAggregatedWorktree(sessionRepoPath) {
+    const aggPath = aggregatedPath();
+    try {
+        if (!existsSync(join(aggPath, ".git"))) {
+            // First-time setup. `git worktree add` from the session repo, pointing
+            // at the local-tracking `main` ref. If `main` doesn't exist locally yet
+            // (very fresh clone), fall back to creating it from origin/main.
+            mkdirSync(dirname(aggPath), { recursive: true });
+            const repoGit = simpleGit(sessionRepoPath);
+            // Make sure we have origin/main locally first.
+            await repoGit.fetch("origin", "main").catch(() => { });
+            // Ensure a local `main` ref tracks origin/main so worktree add can
+            // point at a name (worktrees can't share a HEAD with another worktree,
+            // and the session-repo is usually on a device branch already).
+            const localMain = await repoGit.raw(["branch", "--list", "main"]).catch(() => "");
+            if (!localMain.trim()) {
+                await repoGit.raw(["branch", "main", "origin/main"]).catch(() => { });
+            }
+            await repoGit.raw(["worktree", "add", aggPath, "main"]);
+            return true;
+        }
+        // Refresh path. Worktree exists; fetch + reset --hard to origin/main.
+        const aggGit = simpleGit(aggPath);
+        await aggGit.fetch("origin", "main");
+        await aggGit.raw(["reset", "--hard", "origin/main"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read the aggregated index from the worktree. Returns null when:
+ *   - the worktree doesn't exist (first sync hasn't called refresh)
+ *   - main has never received an aggregate commit (no devices ran sync yet)
+ *   - the file is malformed.
+ * Callers should treat null as "no cross-device sessions known" and proceed
+ * with own-only data. */
+export function loadAggregatedIndex() {
+    const p = aggregatedIndexAbs();
+    if (!existsSync(p))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(p, "utf8"));
+        if (parsed.version !== 1 || !parsed.entries)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve the absolute path of a session's md file. Sessions captured by
+ *  THIS device live under the session-repo working tree; sessions from
+ *  sibling devices (= entries with originDevice set, only present in the
+ *  aggregated index) live under the aggregated worktree. The IndexEntry's
+ *  `relativePath` is the same in both cases — just resolved against a
+ *  different root. */
+export function resolveSessionMdPath(sessionRepoPath, entry, isAggregated) {
+    const root = isAggregated ? aggregatedPath() : sessionRepoPath;
+    return join(root, entry.relativePath);
+}

package/dist/src/cli.js

@@ -0,0 +1,175 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import chalk from "chalk";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+/** Read version straight from the bundled package.json so we can never
+ *  ship a CLI whose --version lies. Two layouts to handle:
+ *    dev: src/cli.ts → ../package.json
+ *    built: dist/src/cli.js → ../../package.json */
+function readPackageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const rel of ["../package.json", "../../package.json", "../../../package.json"]) {
+        try {
+            return JSON.parse(readFileSync(resolve(here, rel), "utf8")).version;
+        }
+        catch { /* try next */ }
+    }
+    return "0.0.0-unknown";
+}
+export async function run(argv) {
+    const program = new Command();
+    program
+        .name("memarium")
+        .description("Vibe coding memory book")
+        // Standard CLI convention: -v + --version. Commander defaults to -V
+        // (uppercase) which most users don't reach for; we override to lowercase.
+        .version(readPackageVersion(), "-v, --version", "print the installed memarium version");
+    program
+        .command("init [repoUrl]")
+        .description("Initialize memarium. Run with no arguments for the interactive wizard, or pass a repoUrl + flags for non-interactive setup.")
+        .option("--local-path <path>", "local checkout path (default ./.memarium/repo)")
+        .option("--no-digest", "skip the digest pipeline (raw push only)")
+        .option("--device <name>", "device branch name (default: sanitized os.hostname())")
+        .action(async (repoUrl, opts) => {
+        const { initCmd } = await import("./commands/init.js");
+        await initCmd({
+            repoUrl,
+            localPath: opts.localPath,
+            digestEnabled: opts.digest !== false,
+            device: opts.device,
+        });
+    });
+    program
+        .command("sync")
+        .description("Extract sessions from local Claude Code + VS Code Copilot Chat, commit + push to your device branch. No LLM call. Run /memarium in Claude Code afterward to digest.")
+        .action(async () => {
+        const { syncCmd } = await import("./commands/sync.js");
+        await syncCmd();
+    });
+    program
+        .command("upgrade")
+        .description("Refresh the npm CLI (`npm install -g memarium@latest`). Skips the npm step if memarium is npm-link'd from a dev checkout. To update the Claude Code plugin, run `/plugin update memarium` in any session.")
+        .option("--no-cli", "skip the `npm install -g` step")
+        .action(async (opts) => {
+        const { upgradeCmd } = await import("./commands/upgrade.js");
+        await upgradeCmd({ noCli: opts.cli === false });
+    });
+    program
+        .command("doctor")
+        .description("Health check: CLI version on PATH, npm latest, Claude plugin manifest + install entry, ~/.memarium/config presence, memex availability. Read-only and offline-tolerant.")
+        .action(async () => {
+        const { doctorCmd } = await import("./commands/doctor.js");
+        await doctorCmd();
+    });
+    program
+        .command("prune")
+        .description("Find raw_sessions/*.md files on disk that are not referenced by .memarium/index.json (orphans from earlier extractor bugs) and optionally delete them. Dry-run by default.")
+        .option("--apply", "actually delete the orphan files (default is dry-run)")
+        .action(async (opts) => {
+        const { pruneCmd } = await import("./commands/prune.js");
+        await pruneCmd({ apply: opts.apply });
+    });
+    program
+        .command("workflow")
+        .description("Manage the GitHub Action that aggregates device branches into main")
+        .addCommand(new Command("init")
+        .description("Write .github/workflows/memarium-aggregate.yml + scripts/merge-books.mjs into the configured memarium repo, then commit + push")
+        .option("--force", "overwrite if files already exist")
+        .option("--no-push", "write the files locally but don't auto commit + push")
+        .action(async (opts) => {
+        const { workflowInitCmd } = await import("./commands/workflow.js");
+        // commander's --no-X sets opts.X=false when flag present, true otherwise.
+        await workflowInitCmd({ force: opts.force, noPush: opts.push === false });
+    }));
+    program
+        .command("list")
+        .description("List synced sessions")
+        .option("--tool <name>", "filter by claude|copilot")
+        .option("--project <name>", "filter by project")
+        .action(async (opts) => {
+        const { listCmd } = await import("./commands/list.js");
+        await listCmd(opts);
+    });
+    program
+        .command("show <ref>")
+        .description("Show a session by sessionId, shortId, slug, or display name")
+        .action(async (ref) => {
+        const { showCmd } = await import("./commands/show.js");
+        await showCmd(ref);
+    });
+    program
+        .command("cat <path>")
+        .description("Print a repo file to stdout. Path is absolute or relative to the configured repoPath. Used by the /memarium skill to read session md.")
+        .action(async (path) => {
+        const { catCmd } = await import("./commands/cat.js");
+        await catCmd(path);
+    });
+    program
+        .command("list-sessions")
+        .description("List sessions in the local spool, filterable for cross-device resume.")
+        .option("--project <slug>", "filter by project slug")
+        .option("--since <window>", "only sessions ended within this window (e.g. 7d, 24h, 4w)")
+        .option("--device <name>", "filter by device branch (placeholder for v0.6)")
+        .action(async (opts) => {
+        const { listSessionsCmd } = await import("./commands/resume/list-sessions.js");
+        const sessions = await listSessionsCmd(opts);
+        if (sessions.length === 0) {
+            console.log("(no sessions match)");
+            return;
+        }
+        const rows = sessions.map((e) => ({
+            SESSION: e.shortId,
+            TOOL: e.tool,
+            PROJECT: e.project,
+            ENDED: e.endedAt.slice(0, 10),
+            TITLE: e.displayName.slice(0, 40),
+        }));
+        console.table(rows);
+    });
+    program
+        .command("resume <id>")
+        .description("Find a session's context.md and spawn a fresh `claude` session with it as the first prompt.")
+        .option("--print", "print the claude invocation instead of spawning it")
+        .option("--cwd <path>", "override the cwd used for project-match validation (default: process.cwd())")
+        .action(async (id, opts) => {
+        const { resumeCmd } = await import("./commands/resume/resume.js");
+        try {
+            await resumeCmd({ idOrPrefix: id, print: opts.print, cwd: opts.cwd });
+        }
+        catch (err) {
+            console.error(chalk.red(String(err.message)));
+            process.exit(1);
+        }
+    });
+    program
+        .command("config")
+        .description("Inspect or modify ~/.memarium/config.json.")
+        .option("--map-path <FROM=TO>", "add a cross-device path mapping (e.g. /Users/yueA=/Users/yueB) for `memarium resume`")
+        .option("--device <name>", "set a stable device branch name (e.g. 'mini2') — overrides the volatile hostname() default")
+        .action(async (opts) => {
+        if (opts.mapPath) {
+            const { setMapPath } = await import("./commands/resume/config-pathmap.js");
+            setMapPath(opts.mapPath);
+            console.log(`Added pathMap entry. Current ~/.memarium/config.json updated.`);
+            return;
+        }
+        if (opts.device) {
+            const { setDeviceBranch } = await import("./commands/resume/config-pathmap.js");
+            const { previous, current } = setDeviceBranch(opts.device);
+            console.log(`Device branch: ${previous} → ${current}`);
+            if (previous && previous !== current) {
+                console.log(`\nNote: your spool repo may still have a local + remote branch named '${previous}'.\n` +
+                    `If you want to clean those up:\n` +
+                    `  cd ~/.memarium/session-repo\n` +
+                    `  git branch -D '${previous}' 2>/dev/null\n` +
+                    `  git push origin --delete '${previous}' 2>/dev/null`);
+            }
+            return;
+        }
+        // No flags: print current config
+        const { readConfig } = await import("./config.js");
+        console.log(JSON.stringify(readConfig(), null, 2));
+    });
+    await program.parseAsync(argv);
+}

package/dist/src/commands/cat.js

@@ -0,0 +1,20 @@
+import { readFileSync, existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { readConfig } from "../config.js";
+/**
+ * Dump a session file (or any repo file) to stdout. Used by the in-session
+ * /memarium skill to read session md.
+ *
+ * Path resolution:
+ *   - absolute path → used as-is
+ *   - relative path → resolved against `cfg.repoPath`
+ */
+export async function catCmd(path) {
+    if (!path)
+        throw new Error("usage: memarium cat <path>");
+    const cfg = readConfig();
+    const abs = isAbsolute(path) ? path : join(cfg.repoPath, path);
+    if (!existsSync(abs))
+        throw new Error(`not found: ${abs}`);
+    process.stdout.write(readFileSync(abs));
+}