gnosys 5.7.0 → 5.7.1

package/README.md

@@ -80,7 +80,7 @@ gnosys recall "database selection"
 
 > **Postinstall hook:** After `npm install -g gnosys`, a postinstall script automatically runs `gnosys setup` if no configuration is detected, so first-time users are guided through provider and IDE setup immediately.
 
-> **Multi-machine?** Set `GNOSYS_GLOBAL` to a cloud-synced folder (iCloud Drive, Dropbox, OneDrive) and both machines share the same brain. After updating, run `gnosys upgrade` — it re-syncs all projects, regenerates agent rules, and warns other machines to upgrade too. See the [User Guide — Installation & Setup](https://gnosys.ai/guide.html#guide-installation) for the full walkthrough, memory scopes, and multi-machine setup.
+> **Multi-machine?** Set `GNOSYS_GLOBAL` to a cloud-synced folder (iCloud Drive, Dropbox, OneDrive) and both machines share the same brain. To update: run `gnosys upgrade` — it installs the latest gnosys, signals any running MCP servers to restart cleanly, and prompts to run `gnosys setup sync-projects` afterwards (re-syncs all projects, regenerates agent rules, warns other machines to upgrade). See the [User Guide — Installation & Setup](https://gnosys.ai/guide.html#guide-installation) for the full walkthrough, memory scopes, and multi-machine setup.
 
 ### Agent / Helper Library
 
@@ -331,7 +331,7 @@ Dream Mode is the idle-time consolidation engine — confidence decay, summary g
 - Run `gnosys setup dream` on the machine you want to host dream cycles.
 - The wizard validates your provider/model with a live API probe before saving.
 - Other machines stay quiet — they see the designation in the central DB and skip the scheduler.
-- `gnosys dream log` shows recent runs; `gnosys dashboard` has a `DREAM HEALTH` section with last-run timestamp, designated machine, and consecutive-failure counter.
+- `gnosys dream log` shows recent runs; `gnosys status --system` has a `DREAM HEALTH` section with last-run timestamp, designated machine, and consecutive-failure counter.
 - If the designated machine's LLM provider becomes unreachable, you'll see warnings at three layers: in audit log entries (`dream_provider_unreachable`), as stderr at MCP startup, and as a desktop notification after 3 consecutive failures.
 
 ### Removed in v5.4.2
@@ -345,6 +345,19 @@ The following commands were removed in favor of the canonical `gnosys setup <thi
 
 `gnosys remote push|pull|sync|status` remain unchanged — only `configure` moved.
 
+### Removed / renamed in v5.7.1
+
+| Removed / renamed | Use instead |
+|---|---|
+| `gnosys dashboard` | `gnosys status --system` |
+| `gnosys portfolio` | `gnosys status --projects` (or `--web` for HTML) |
+| `gnosys upgrade` (old behaviour) | `gnosys setup sync-projects` |
+| `gnosys status --global` | `gnosys status --projects` (alias kept) |
+
+`gnosys upgrade` is now `npm install -g gnosys@latest` + a marker that
+tells running MCP servers to exit-and-respawn against the new global
+binary. Run it on each machine.
+
 ---
 
 ### Manual config (if you prefer)

package/dist/cli.js

@@ -225,6 +225,7 @@ program
     .option("--federated", "Use federated discovery with tier boosting (project > user > global)")
     .option("--scope <scope>", "Filter by scope: project, user, global (comma-separated for multiple)")
     .option("-d, --directory <dir>", "Project directory for context")
+    .option("--id-format <format>", "ID display format: short | long | raw (default: short)", "short")
     .action(async (query, opts) => {
     // Federated discover path
     if (opts.federated || opts.scope) {
@@ -279,11 +280,16 @@ program
             });
             return;
         }
+        const { formatMemoryId, buildProjectNameLookup, parseIdFormat } = await import("./lib/idFormat.js");
+        const idFormat = parseIdFormat(opts.idFormat);
+        const projectNames = buildProjectNameLookup(centralDb);
         outputResult(!!opts.json, { query, count: results.length, results }, () => {
             console.log(`Found ${results.length} relevant memories for "${query}":\n`);
             for (const r of results) {
+                const projectName = r.project_id ? projectNames.get(r.project_id) || null : null;
+                const displayId = formatMemoryId(r.id, projectName, idFormat);
                 console.log(`  ${r.title}`);
-                console.log(`    id: ${r.id}`);
+                console.log(`    id: ${displayId}`);
                 if (r.relevance)
                     console.log(`    Relevance: ${r.relevance}`);
                 console.log();
@@ -391,6 +397,7 @@ program
     .option("-t, --tag <tag>", "Filter by tag")
     .option("-s, --store <store>", "Filter by store layer (project|user|global)")
     .option("--json", "Output as JSON")
+    .option("--id-format <format>", "ID display format: short | long | raw (default: short)", "short")
     .action(async (opts) => {
     let centralDb = null;
     try {
@@ -424,6 +431,9 @@ program
                 }
             });
         }
+        const { formatMemoryId, buildProjectNameLookup, parseIdFormat } = await import("./lib/idFormat.js");
+        const idFormat = parseIdFormat(opts.idFormat);
+        const projectNames = buildProjectNameLookup(centralDb);
         outputResult(!!opts.json, {
             count: memories.length,
             memories: memories.map((m) => ({
@@ -433,12 +443,15 @@ program
                 status: m.status,
                 scope: m.scope,
                 confidence: m.confidence,
+                project: m.project_id ? projectNames.get(m.project_id) || null : null,
             })),
         }, () => {
             console.log(`${memories.length} memories:\n`);
             for (const m of memories) {
+                const projectName = m.project_id ? projectNames.get(m.project_id) || null : null;
+                const displayId = formatMemoryId(m.id, projectName, idFormat);
                 console.log(`  [${m.scope}] [${m.status}] ${m.title}`);
-                console.log(`    id: ${m.id} | category: ${m.category} | confidence: ${m.confidence}`);
+                console.log(`    id: ${displayId} | category: ${m.category} | confidence: ${m.confidence}`);
                 console.log();
             }
         });
@@ -654,8 +667,9 @@ setupRemoteCmd
             return;
         }
         const { RemoteSync, formatStatus } = await import("./lib/remote.js");
+        const { withHeartbeat } = await import("./lib/heartbeat.js");
         const sync = new RemoteSync(centralDb, remotePath);
-        const status = await sync.getStatus();
+        const status = await withHeartbeat("Checking remote sync status", () => sync.getStatus());
         sync.closeRemote();
         if (opts.json) {
             console.log(JSON.stringify(status, null, 2));
@@ -685,6 +699,7 @@ setupRemoteCmd
     .command("push")
     .description("Push local changes to remote")
     .option("--newer-wins", "Auto-resolve conflicts by taking the newer version")
+    .option("--verbose", "Stream per-memory progress to stderr")
     .action(async (opts) => {
     let centralDb = null;
     try {
@@ -699,8 +714,18 @@ setupRemoteCmd
             process.exit(1);
         }
         const { RemoteSync } = await import("./lib/remote.js");
+        const { withHeartbeat } = await import("./lib/heartbeat.js");
+        const { createProgress } = await import("./lib/progress.js");
+        const progress = createProgress(!!opts.verbose);
         const sync = new RemoteSync(centralDb, remotePath);
-        const result = await sync.push({ strategy: opts.newerWins ? "newer-wins" : "skip-and-flag" });
+        // Suppress heartbeat when verbose is on (progress already streams).
+        const runPush = () => sync.push({
+            strategy: opts.newerWins ? "newer-wins" : "skip-and-flag",
+            onProgress: progress.noop ? undefined : progress.emit.bind(progress),
+        });
+        const result = opts.verbose
+            ? await runPush()
+            : await withHeartbeat("Pushing to remote", runPush);
         sync.closeRemote();
         const projParts = (result.projectsPushed || 0) > 0 ? ` | Projects pushed: ${result.projectsPushed}` : "";
         const auditParts = (result.auditPushed || 0) > 0 ? ` | Audit pushed: ${result.auditPushed}` : "";
@@ -728,6 +753,7 @@ setupRemoteCmd
     .command("pull")
     .description("Pull remote changes to local")
     .option("--newer-wins", "Auto-resolve conflicts by taking the newer version")
+    .option("--verbose", "Stream per-memory progress to stderr")
     .action(async (opts) => {
     let centralDb = null;
     try {
@@ -742,8 +768,17 @@ setupRemoteCmd
             process.exit(1);
         }
         const { RemoteSync } = await import("./lib/remote.js");
+        const { withHeartbeat } = await import("./lib/heartbeat.js");
+        const { createProgress } = await import("./lib/progress.js");
+        const progress = createProgress(!!opts.verbose);
         const sync = new RemoteSync(centralDb, remotePath);
-        const result = await sync.pull({ strategy: opts.newerWins ? "newer-wins" : "skip-and-flag" });
+        const runPull = () => sync.pull({
+            strategy: opts.newerWins ? "newer-wins" : "skip-and-flag",
+            onProgress: progress.noop ? undefined : progress.emit.bind(progress),
+        });
+        const result = opts.verbose
+            ? await runPull()
+            : await withHeartbeat("Pulling from remote", runPull);
         sync.closeRemote();
         const projParts = (result.projectsPulled || 0) > 0 ? ` | Projects pulled: ${result.projectsPulled}` : "";
         const auditParts = (result.auditPulled || 0) > 0 ? ` | Audit pulled: ${result.auditPulled}` : "";
@@ -767,6 +802,7 @@ setupRemoteCmd
     .description("Two-way sync: push local changes then pull remote changes")
     .option("--auto", "Run silently for cron/LaunchAgent (skip-and-flag for conflicts)")
     .option("--newer-wins", "Auto-resolve conflicts by taking the newer version")
+    .option("--verbose", "Stream per-memory progress to stderr")
     .action(async (opts) => {
     let centralDb = null;
     try {
@@ -783,11 +819,20 @@ setupRemoteCmd
             process.exit(opts.auto ? 0 : 1);
         }
         const { RemoteSync } = await import("./lib/remote.js");
+        const { withHeartbeat } = await import("./lib/heartbeat.js");
+        const { createProgress } = await import("./lib/progress.js");
+        const progress = createProgress(!!opts.verbose);
         const sync = new RemoteSync(centralDb, remotePath);
-        const result = await sync.sync({
+        const runSync = () => sync.sync({
             auto: opts.auto,
             strategy: opts.newerWins ? "newer-wins" : "skip-and-flag",
+            onProgress: progress.noop ? undefined : progress.emit.bind(progress),
         });
+        // Auto mode + verbose mode both bypass the heartbeat. Auto mode is
+        // for non-interactive runs (no spinner). Verbose streams its own output.
+        const result = opts.auto || opts.verbose
+            ? await runSync()
+            : await withHeartbeat("Syncing with remote", runSync);
         sync.closeRemote();
         if (!opts.auto || result.conflicts.length > 0 || result.errors.length > 0) {
             const pp = result.projectsPushed || 0;
@@ -3007,41 +3052,9 @@ program
     console.log("");
     console.log(formatGraphStats(stats));
 });
-// ─── gnosys dashboard ───────────────────────────────────────────────────
-// v5.7.0: kept as a thin alias of `gnosys status --system`. Will be removed
-// in a future release; use `gnosys status` instead.
-program
-    .command("dashboard")
-    .description("(alias) Show system health — equivalent to 'gnosys status --system'")
-    .option("--json", "Output as JSON instead of pretty table")
-    .action(async (opts) => {
-    const { collectDashboardData, formatDashboard, formatDashboardJSON } = await import("./lib/dashboard.js");
-    const resolver = await getResolver();
-    const stores = resolver.getStores();
-    if (stores.length === 0) {
-        console.error("No Gnosys stores found. Run gnosys init first.");
-        process.exit(1);
-    }
-    const cfg = await loadConfig(stores[0].path);
-    // v5.1: Use central DB for dashboard stats
-    let dashDb;
-    try {
-        const db = GnosysDB.openCentral();
-        if (db.isAvailable() && db.isMigrated()) {
-            dashDb = db;
-        }
-    }
-    catch {
-        // Central DB not available — legacy dashboard only
-    }
-    const data = await collectDashboardData(resolver, cfg, pkg.version, dashDb);
-    if (opts.json) {
-        console.log(formatDashboardJSON(data));
-    }
-    else {
-        console.log(formatDashboard(data));
-    }
-});
+// `gnosys dashboard` was removed in v5.7.1.
+// Use `gnosys status --system` instead. Hard removal — commander will emit
+// the standard "unknown command" error.
 // ─── gnosys maintain ─────────────────────────────────────────────────────
 program
     .command("maintain")
@@ -3125,12 +3138,19 @@ program
     }
 });
 // NOTE: gnosys migrate is defined below (near the end) with --to-central support
-// ─── gnosys upgrade ─────────────────────────────────────────────────────
-program
-    .command("upgrade")
-    .description("Re-initialize all registered projects after a Gnosys version upgrade. Updates agent rules, project registry, stamps the central DB, and regenerates the portfolio dashboard.")
-    .option("--skip-dashboard", "Skip regenerating the portfolio dashboard")
-    .action(async (opts) => {
+// ─── gnosys upgrade  +  gnosys setup sync-projects ──────────────────────
+//
+// v5.7.1 (#15) split this command:
+//
+//   gnosys upgrade            — upgrade the gnosys CLI/MCP itself
+//                               (npm install + restart signal to MCPs)
+//   gnosys setup sync-projects — what the old `gnosys upgrade` used to do
+//                               (re-init project identities, agent rules,
+//                                central DB stamp, portfolio dashboard)
+//
+// The body of the legacy command is preserved verbatim below as
+// `syncProjectsAction`, called from the new `setup sync-projects` command.
+async function syncProjectsAction(opts) {
     const currentVersion = pkg.version;
     console.log(`Gnosys v${currentVersion} — upgrading registered projects...\n`);
     // 1. Read registered projects from file registry AND central DB
@@ -3349,6 +3369,76 @@ program
             console.log(`\n  Could not regenerate portfolio dashboard`);
         }
     }
+}
+// `gnosys setup sync-projects` — re-init project identities + agent rules.
+// (This is what `gnosys upgrade` used to do; renamed in v5.7.1.)
+setupCmd
+    .command("sync-projects")
+    .description("Re-initialize all registered projects after upgrading gnosys: refresh agent rules, project registry, central DB stamp, and portfolio dashboard.")
+    .option("--skip-dashboard", "Skip regenerating the portfolio dashboard")
+    .action(syncProjectsAction);
+// `gnosys upgrade` — upgrade the gnosys CLI/MCP itself, then prompt the
+// user to run sync-projects. Writes ~/.gnosys/last-upgrade-at so running
+// MCP servers exit cleanly and the host respawns them against the new
+// global binary (see src/lib/upgrade.ts).
+program
+    .command("upgrade")
+    .description("Upgrade gnosys itself (npm install -g gnosys@latest) and signal running MCP servers to restart. After upgrading, suggests running 'gnosys setup sync-projects'.")
+    .option("--yes", "Skip the post-upgrade sync-projects prompt and exit")
+    .option("--no-sync", "Don't suggest running sync-projects afterward")
+    .action(async (opts) => {
+    const currentVersion = pkg.version;
+    console.log(`Gnosys CLI: currently v${currentVersion}`);
+    console.log(`Running: npm install -g gnosys@latest ...`);
+    const { execSync } = await import("child_process");
+    try {
+        execSync("npm install -g gnosys@latest", { stdio: "inherit" });
+    }
+    catch (err) {
+        console.error(`\nUpgrade failed: ${err instanceof Error ? err.message : err}`);
+        console.error(`Try running 'npm install -g gnosys@latest' manually.`);
+        process.exit(1);
+    }
+    // Read the newly-installed version (best-effort — we may still be the
+    // old binary in-process; this is purely informational).
+    let newVersion = "(see npm output)";
+    try {
+        const out = execSync("npm ls -g gnosys --depth=0 --json", { encoding: "utf8" });
+        const parsed = JSON.parse(out);
+        newVersion = parsed?.dependencies?.gnosys?.version || newVersion;
+    }
+    catch {
+        // Best-effort lookup only.
+    }
+    // Write the marker so any running MCP servers exit and respawn.
+    const { writeUpgradeMarker } = await import("./lib/upgrade.js");
+    try {
+        writeUpgradeMarker(typeof newVersion === "string" && newVersion !== "(see npm output)"
+            ? newVersion
+            : currentVersion);
+        console.log(`\n✓ Upgrade marker written: ~/.gnosys/last-upgrade-at`);
+        console.log(`  Any running MCP servers will detect this within 10s and restart cleanly.`);
+        console.log(`  (Your MCP client — Claude Code, Cursor, VS Code — will auto-respawn.)`);
+    }
+    catch (err) {
+        console.error(`\nCould not write upgrade marker: ${err instanceof Error ? err.message : err}`);
+        console.error(`Running MCP servers will need to be restarted manually.`);
+    }
+    if (opts.sync === false || opts.yes) {
+        console.log(`\nDone. Run 'gnosys setup sync-projects' when you're ready to refresh registered projects.`);
+        return;
+    }
+    // Prompt for sync-projects.
+    const readline = await import("readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(`\nRun 'gnosys setup sync-projects' now to refresh registered projects? [Y/n] `, resolve));
+    rl.close();
+    if (answer.trim().toLowerCase() === "n" || answer.trim().toLowerCase() === "no") {
+        console.log(`Done. You can run 'gnosys setup sync-projects' later.`);
+        return;
+    }
+    console.log(``);
+    await syncProjectsAction({});
 });
 // ─── gnosys doctor ──────────────────────────────────────────────────────
 program
@@ -4858,80 +4948,70 @@ program
         centralDb?.close();
     }
 });
-// ─── gnosys portfolio ───────────────────────────────────────────────────
+// `gnosys portfolio` was removed in v5.7.1.
+// Use `gnosys status --projects` (formerly --global) for the projects
+// overview, or `gnosys status --web` for the HTML dashboard, or
+// `gnosys status --projects --output file.html` to write to disk.
+// ─── gnosys status ──────────────────────────────────────────────────────
+// v5.7.1 (#11): the catch-all status command. Section flags select what to
+// show; output flags control format. Default (no flag) is the current
+// project. `dashboard` and `portfolio` were removed in v5.7.1 — their
+// content lives under `--system` and `--projects` respectively.
 program
-    .command("portfolio")
-    .description("Portfolio dashboard — all projects with status, roadmap, and recent activity")
-    .option("-o, --output <file>", "Write dashboard to a file (auto-detects format from extension)")
-    .option("--html", "Output as HTML dashboard")
+    .command("status")
+    .description("Show status. Sections: --projects (all projects) · --remote (sync) · --system (memory/LLM health) · default: current project. Output: --web · --json. Note: 'gnosys dashboard' and 'gnosys portfolio' were removed in v5.7.1 — use 'gnosys status --system' and 'gnosys status --projects' instead.")
+    .option("-d, --directory <dir>", "Project directory (auto-detects if omitted)")
+    .option("-p, --project <id>", "Project ID")
+    .option("-g, --global", "(deprecated alias for --projects)")
+    .option("--projects", "Show all projects portfolio (replaces the old 'gnosys portfolio')")
+    .option("-r, --remote", "Show remote sync status (alias for 'gnosys setup remote status')")
+    .option("-w, --web", "Open the HTML dashboard in the browser")
+    .option("-s, --system", "Show system health (memory count, LLM connectivity, embeddings, archive)")
     .option("--json", "Output as JSON")
     .action(async (opts) => {
-    let centralDb = null;
-    try {
-        centralDb = GnosysDB.openCentral();
-        if (!centralDb.isAvailable()) {
-            console.error("Central DB not available.");
-            process.exit(1);
-        }
-        const { generatePortfolio, formatPortfolioMarkdown } = await import("./lib/portfolio.js");
-        const report = generatePortfolio(centralDb);
-        // Detect format from output extension if not explicitly set
-        const useHtml = opts.html || (opts.output?.endsWith(".html") ?? false);
-        const useJson = opts.json || (opts.output?.endsWith(".json") ?? false);
-        if (useJson) {
-            const json = JSON.stringify(report, null, 2);
-            if (opts.output) {
-                const { writeFileSync } = await import("fs");
-                writeFileSync(opts.output, json, "utf-8");
-                console.log(`Portfolio written to ${opts.output}`);
+    // v5.7.1: --projects supersedes --global (kept as alias).
+    if (opts.projects)
+        opts.global = true;
+    // v5.7.1: --remote — dispatch to RemoteSync.getStatus()
+    if (opts.remote) {
+        let remoteCentralDb = null;
+        try {
+            remoteCentralDb = GnosysDB.openLocal();
+            if (!remoteCentralDb.isAvailable()) {
+                console.error("Central DB not available.");
+                process.exit(1);
             }
-            else {
-                console.log(json);
+            const remotePath = remoteCentralDb.getMeta("remote_path");
+            if (!remotePath) {
+                if (opts.json) {
+                    console.log(JSON.stringify({ configured: false, message: "Remote not configured. Run 'gnosys setup remote'." }, null, 2));
+                }
+                else {
+                    console.log("Remote sync: not configured. Run 'gnosys setup remote' to set up multi-machine sync.");
+                }
+                return;
             }
-            return;
-        }
-        if (useHtml) {
-            const { generatePortfolioHtml } = await import("./lib/portfolioHtml.js");
-            const html = generatePortfolioHtml(report, opts.output);
-            if (opts.output) {
-                const { writeFileSync } = await import("fs");
-                writeFileSync(opts.output, html, "utf-8");
-                console.log(`Portfolio dashboard written to ${opts.output}`);
+            const { RemoteSync, formatStatus } = await import("./lib/remote.js");
+            const { withHeartbeat } = await import("./lib/heartbeat.js");
+            const sync = new RemoteSync(remoteCentralDb, remotePath);
+            const status = await withHeartbeat("Checking remote sync status", () => sync.getStatus());
+            sync.closeRemote();
+            if (opts.json) {
+                console.log(JSON.stringify(status, null, 2));
             }
             else {
-                console.log(html);
+                console.log(formatStatus(status));
             }
             return;
         }
-        const markdown = formatPortfolioMarkdown(report);
-        if (opts.output) {
-            const { writeFileSync } = await import("fs");
-            writeFileSync(opts.output, markdown, "utf-8");
-            console.log(`Portfolio dashboard written to ${opts.output}`);
+        catch (err) {
+            console.error(`Error: ${err instanceof Error ? err.message : err}`);
+            process.exit(1);
         }
-        else {
-            console.log(markdown);
+        finally {
+            remoteCentralDb?.close();
         }
     }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
-        process.exit(1);
-    }
-    finally {
-        centralDb?.close();
-    }
-});
-// ─── gnosys status ──────────────────────────────────────────────────────
-program
-    .command("status")
-    .description("Show project status (--global: all projects, --web: HTML dashboard, --system: memory/LLM health)")
-    .option("-d, --directory <dir>", "Project directory (auto-detects if omitted)")
-    .option("-p, --project <id>", "Project ID")
-    .option("-g, --global", "Show all projects")
-    .option("-w, --web", "Open the HTML dashboard in the browser")
-    .option("-s, --system", "Show system health (memory count, LLM connectivity, embeddings, archive)")
-    .option("--json", "Output as JSON")
-    .action(async (opts) => {
     // --system delegates to the dashboard formatter (formerly `gnosys dashboard`).
     if (opts.system) {
         const { collectDashboardData, formatDashboard, formatDashboardJSON } = await import("./lib/dashboard.js");