@bitpub/cli 2.0.0

package/src/commands/list.js

@@ -0,0 +1,241 @@
+'use strict';
+
+/**
+ * `bitpub list [path]` — see what's saved here, where you are, and how
+ * fresh your local cache is.
+ *
+ * Replaces the previous `list` (alphabetical), `recent` (newest-first),
+ * `status` (cache health), and `catch-up` (session bootstrap) — all four
+ * answered slightly different versions of "what do I have." Folding them
+ * into one verb means the agent doesn't have to choose between them and
+ * the user has one place to look.
+ *
+ * Behavior:
+ *   bitpub list                  → active project, newest first, with
+ *                                  the project label, where it lives,
+ *                                  cache freshness, and any group_link.
+ *   bitpub list <pattern>        → an arbitrary scope (alias or full URL)
+ *   bitpub list --all            → alphabetical (the old `list` view)
+ *   bitpub list --sync           → refresh from the cloud first
+ *   bitpub list --json           → parseable output (agents)
+ *
+ * The unified output is what an agent should run at session start —
+ * `catch-up` is now an alias for `list --sync`. The 80% case (no flags)
+ * is a one-screen answer to "what's here, where is it, when did I last
+ * touch it."
+ */
+
+const { requireConfig } = require('../config');
+const { createApiClient } = require('../api');
+const {
+  querySlices,
+  upsertSlice,
+  getCacheStats,
+  getSyncedNamespaces,
+} = require('../db/cache');
+const { decryptSlices } = require('../crypto');
+const { activeNamespace } = require('../workspace');
+const { maybeExpand } = require('../aliases');
+
+function safeParse(s) {
+  try { return JSON.parse(s); } catch { return null; }
+}
+
+function relativeTime(iso) {
+  if (!iso) return 'never';
+  const ms = Date.now() - new Date(iso).getTime();
+  if (ms < 60_000) return 'just now';
+  const m = Math.floor(ms / 60_000);
+  if (m < 60) return `${m} min${m === 1 ? '' : 's'} ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h} hour${h === 1 ? '' : 's'} ago`;
+  const d = Math.floor(h / 24);
+  return `${d} day${d === 1 ? '' : 's'} ago`;
+}
+
+function safeExpand(input) {
+  try { return maybeExpand(input); }
+  catch (err) { console.error(err.message); process.exit(1); }
+}
+
+module.exports = function registerList(program) {
+  program
+    .command('list [path]')
+    .description('See what\'s saved here, when it last changed, and where it lives')
+    .option('--sync', 'Refresh from the cloud before listing')
+    .option('--all', 'Sort alphabetically instead of newest-first')
+    .option('--json', 'Output parseable JSON (for agents and scripts)')
+    .option('-n, --limit <number>', 'Max slices to show', '20')
+    .option('--include-deleted', 'Show recently deleted slices alongside active ones')
+    .action(async (path, opts) => {
+      const config = requireConfig();
+
+      let queryPattern;
+      let label;
+      let workspaceObj = null;
+      let groupLink = null;
+
+      const expandedPattern = path ? safeExpand(path) : null;
+      if (expandedPattern && expandedPattern.startsWith('bitpub://')) {
+        queryPattern = expandedPattern.endsWith('**') || expandedPattern.endsWith('*')
+          ? expandedPattern
+          : expandedPattern.replace(/\/?$/, '/**');
+        label = path;
+      } else {
+        const active = activeNamespace(config);
+        if (!active) {
+          console.error('No saves here yet. Run `bitpub save <name> "..."` to create your first slice.');
+          process.exit(1);
+        }
+        queryPattern = active.namespace + '**';
+        label = active.workspace?.marker.label || '(no project anchored here — showing today\'s session bucket)';
+        workspaceObj = active.workspace;
+        groupLink = active.workspace?.marker.group_link || null;
+      }
+
+      // ── Audit-mode query (always hits the network; bypasses cache) ───
+      if (opts.includeDeleted) {
+        const api = createApiClient(config);
+        let slices;
+        try {
+          slices = await api.pull(queryPattern, 500, { includeDeleted: true });
+        } catch (err) {
+          console.error(`Audit fetch failed: ${err.message}`);
+          process.exit(1);
+        }
+        decryptSlices(slices, config.api_key);
+        renderAlphabetical(label, queryPattern, slices, { auditMode: true, json: !!opts.json });
+        return;
+      }
+
+      // ── Optional sync first (catch-up parity) ────────────────────────
+      if (opts.sync) {
+        const api = createApiClient(config);
+        try {
+          const slices = await api.pull(queryPattern, 200);
+          decryptSlices(slices, config.api_key);
+          slices.forEach(upsertSlice);
+        } catch (err) {
+          console.error(`(sync failed: ${err.message} — using local cache)`);
+        }
+        // If a group_link is set on the project, also pull team context
+        // so the user sees it alongside their private work.
+        if (groupLink) {
+          try {
+            const groupPattern = groupLink.endsWith('**') || groupLink.endsWith('*')
+              ? groupLink
+              : groupLink.replace(/\/?$/, '/**');
+            const groupSlices = await api.pull(groupPattern, 200);
+            decryptSlices(groupSlices, config.api_key);
+            groupSlices.forEach(upsertSlice);
+          } catch {
+            // Non-fatal
+          }
+        }
+      }
+
+      const slices = querySlices(queryPattern);
+
+      if (opts.json) {
+        const out = {
+          path: label,
+          pattern: queryPattern,
+          project: workspaceObj?.marker || null,
+          group_link: groupLink,
+          slices: slices.map(s => ({
+            address: s.hcu,
+            metadata: safeParse(s.metadata),
+            payload: safeParse(s.payload),
+            last_synced: s.last_synced,
+          })),
+        };
+        console.log(JSON.stringify(out, null, 2));
+        return;
+      }
+
+      // ── Header: where am I, where does this live, how fresh is it ─
+      const stats = getCacheStats();
+      console.log(`Project:     ${label}`);
+      if (workspaceObj) {
+        console.log(`Folder:      ${workspaceObj.root}`);
+      }
+      console.log(`Address:     ${queryPattern.replace(/\/\*\*?$/, '/')}`);
+      if (groupLink) console.log(`Team link:   ${groupLink}`);
+      console.log(`Cache:       ${stats?.total_slices ?? 0} slices total · last refreshed ${relativeTime(stats?.latest_sync)}`);
+      console.log('');
+
+      if (slices.length === 0) {
+        console.log('(nothing saved in this project yet)');
+        console.log('');
+        console.log('Try:  bitpub save <name> "your first note"');
+        return;
+      }
+
+      const limit = parseInt(opts.limit, 10) || 20;
+
+      if (opts.all) {
+        renderAlphabetical(label, queryPattern, slices, { json: false, limit });
+      } else {
+        renderRecent(queryPattern, slices, limit);
+      }
+    });
+};
+
+function renderRecent(pattern, slices, limit) {
+  const base = pattern.replace(/\*\*?$/, '').replace(/\/?$/, '/');
+  const sorted = slices.slice().sort((a, b) =>
+    String(b.last_synced).localeCompare(String(a.last_synced))
+  );
+  const top = sorted.slice(0, limit);
+
+  for (const s of top) {
+    const meta = safeParse(s.metadata) || {};
+    const payload = safeParse(s.payload) || {};
+    const shortName = s.hcu.startsWith(base) ? s.hcu.slice(base.length) : s.hcu;
+    const preview = String(payload.content || '').replace(/\s+/g, ' ').slice(0, 60);
+    const ver = meta.version != null ? `v${meta.version}` : '   ';
+    console.log(`  ${shortName.padEnd(28)}  ${ver.padEnd(5)}  ${preview}`);
+  }
+  if (sorted.length > limit) {
+    console.log(`  … ${sorted.length - limit} more  (--limit ${sorted.length} to show all)`);
+  }
+}
+
+function renderAlphabetical(label, pattern, slices, opts = {}) {
+  const base = pattern.replace(/\*\*?$/, '').replace(/\/?$/, '/');
+  if (opts.json) {
+    console.log(JSON.stringify(slices.map(s => ({
+      address: s.hcu,
+      metadata: safeParse(s.metadata),
+      payload: safeParse(s.payload),
+      deleted_at: s.deleted_at || null,
+    })), null, 2));
+    return;
+  }
+
+  if (opts.auditMode) {
+    console.log(`Scope : ${label}  (audit; includes deleted)`);
+    console.log(`Total : ${slices.length} slice(s)`);
+    console.log('');
+  }
+
+  if (slices.length === 0) {
+    console.log('  (none)');
+    return;
+  }
+
+  const sorted = slices.slice().sort((a, b) => a.hcu.localeCompare(b.hcu));
+  const limit = opts.limit || sorted.length;
+  for (const s of sorted.slice(0, limit)) {
+    const meta = s.metadata && typeof s.metadata === 'object' ? s.metadata : safeParse(s.metadata) || {};
+    const payload = s.payload && typeof s.payload === 'object' ? s.payload : safeParse(s.payload) || {};
+    const shortName = s.hcu.startsWith(base) ? s.hcu.slice(base.length) : s.hcu;
+    const ver = meta.version != null ? `v${meta.version}` : '   ';
+    const sizeStr = `${String(payload.content || '').length}b`;
+    if (s.deleted_at) {
+      console.log(`  [deleted ${s.deleted_at}]  ${ver.padEnd(5)}  ${shortName}`);
+    } else {
+      console.log(`  ${shortName.padEnd(36)}  ${ver.padEnd(5)}  ${sizeStr}`);
+    }
+  }
+}

package/src/commands/load.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * `bitpub load <name>` — read a slice by name or full address.
+ *
+ * Resolution order:
+ *   1. If the input looks like a `bitpub://` URL or `@alias`, treat it as
+ *      explicit and look up the exact address.
+ *   2. Otherwise, resolve through the active project ("notes" →
+ *      `<project>/notes`) and try the cache; if missing, fetch once.
+ *   3. If still empty AND the input was a short name, fall through to a
+ *      "did you mean…" search across the user's full private namespace.
+ *      With exactly one match, auto-load and print a transparency note to
+ *      stderr saying where it actually came from. With multiple, list
+ *      them and exit. With zero, print an actionable not-found error.
+ *
+ * The DWIM step exists because agents holding a fully-qualified URL will
+ * sometimes (incorrectly) strip it down to a short name before calling
+ * `load`. Rather than make that case fail mysteriously, we recover when
+ * we can and surface the recovery to the user.
+ */
+
+const { requireConfig } = require('../config');
+const { createApiClient } = require('../api');
+const { querySlices, upsertSlice, findSlicesByName } = require('../db/cache');
+const { decryptSlices } = require('../crypto');
+const { resolveHcu } = require('../workspace');
+const { isAliasRef } = require('../aliases');
+
+module.exports = function registerLoad(program) {
+  program
+    .command('load <name>')
+    .description('Load a slice by short name (this project) or full bitpub:// address')
+    .option('--no-fetch', 'Do not fetch from cloud if missing locally')
+    .option('--format <raw|json>', 'Output format', 'raw')
+    .action(async (name, opts) => {
+      const config = requireConfig();
+      const wasShortName = !name.startsWith('bitpub://') && !isAliasRef(name);
+
+      let hcu;
+      try {
+        ({ hcu } = resolveHcu(name, config));
+      } catch (err) {
+        console.error(err.message);
+        process.exit(1);
+      }
+
+      let slices = querySlices(hcu);
+
+      if (slices.length === 0 && opts.fetch !== false) {
+        const api = createApiClient(config);
+        try {
+          const remote = await api.pull(hcu, 1);
+          decryptSlices(remote, config.api_key);
+          remote.forEach(upsertSlice);
+          slices = querySlices(hcu);
+        } catch (err) {
+          console.error(`(remote fetch failed: ${err.message})`);
+        }
+      }
+
+      // DWIM recovery: lookup against the active project missed, but
+      // the user gave us a short name. The slice they meant might live
+      // in a sibling namespace under their private scope (/Memory/,
+      // /Inbox/, a different project, /Transcripts/, etc.). Search by
+      // path-tail and recover when the answer is unambiguous.
+      if (slices.length === 0 && wasShortName && config.owner) {
+        const scope = `bitpub://private:${config.owner}/**`;
+        const candidates = findSlicesByName(name, scope);
+
+        if (candidates.length === 1) {
+          const found = candidates[0];
+          // Transparency note → stderr so stdout stays clean for pipes.
+          console.error(`(loaded from ${found.hcu} — not in this project)`);
+          slices = [found];
+        } else if (candidates.length > 1) {
+          console.error(`Found ${candidates.length} slices named "${name}" in your private memory:`);
+          console.error('');
+          for (const c of candidates) {
+            console.error(`  ${c.hcu}`);
+          }
+          console.error('');
+          console.error('Load by full address:');
+          console.error(`  bitpub load <one-of-the-addresses-above>`);
+          process.exit(1);
+        }
+        // Zero candidates: fall through to the not-found block below.
+      }
+
+      if (slices.length === 0) {
+        if (wasShortName) {
+          console.error(`Not found: "${name}" (not in this project, not elsewhere in your private memory)`);
+          console.error('');
+          console.error('Try:');
+          console.error(`  bitpub find "${name}"        # search by content across everything you've saved`);
+          console.error(`  bitpub list                   # see what's in this project`);
+          console.error(`  bitpub sync                   # pull the latest from the cloud, then retry`);
+        } else {
+          console.error(`Not found: ${hcu}`);
+          console.error(`  Run: bitpub sync ${hcu}  to refresh the cache and retry.`);
+        }
+        process.exit(1);
+      }
+
+      if (opts.format === 'json') {
+        const out = slices.map(s => ({
+          hcu: s.hcu,
+          metadata: JSON.parse(s.metadata),
+          payload: JSON.parse(s.payload),
+          last_synced: s.last_synced,
+        }));
+        console.log(JSON.stringify(out, null, 2));
+        return;
+      }
+
+      const parts = slices.map(s => {
+        const payload = JSON.parse(s.payload);
+        return payload.content ?? '';
+      });
+      console.log(parts.join('\n---\n'));
+    });
+};

package/src/commands/push.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * `bitpub push` — DEPRECATED ALIAS. Use `bitpub save` instead.
+ *
+ * `bitpub save` accepts a fully-qualified `bitpub://` URL, so all the
+ * power that lived in `push` is reachable through `save` (with the same
+ * `--append`, `--expect-version`, `--force`, `--file`, and `--tags`
+ * flags). Hidden from --help.
+ */
+
+const fs = require('fs');
+const { requireConfig, authorIdFor } = require('../config');
+const { createApiClient } = require('../api');
+const { upsertSlice } = require('../db/cache');
+const { encrypt, decryptSlices, isPrivateHcu } = require('../crypto');
+
+module.exports = function registerPush(program) {
+  program
+    .command('push', { hidden: true })
+    .description('[deprecated] Use `bitpub save <address> ...` instead')
+    .requiredOption('--address <string>', 'Target address (no wildcards)')
+    .option('--content <string>', 'Content string to push')
+    .option('--file <path>', 'Path to a file whose contents will be pushed')
+    .option('--format <string>', 'Content format', 'text/markdown')
+    .option('--tags <string>', 'Comma-separated tags')
+    .option('--append', 'Append to existing slice instead of overwriting')
+    .option('--expect-version <number>', 'Reject push if current version differs', parseInt)
+    .option('--force', 'Override the default-strict refusal to overwrite a tombstoned slice')
+    .action(async (opts) => {
+      console.error('warning: `bitpub push` is deprecated. Use `bitpub save <address> ...` instead.');
+      const { address, content, file, format, tags, append, expectVersion, force } = opts;
+
+      if (!content && !file) {
+        console.error('Provide --content <string> or --file <path>');
+        process.exit(1);
+      }
+
+      const finalContent = file ? fs.readFileSync(file, 'utf-8') : content;
+      const tagList = tags ? tags.split(',').map(t => t.trim()).filter(Boolean) : [];
+
+      const config = requireConfig();
+      const api = createApiClient(config);
+
+      const payloadContent = isPrivateHcu(address)
+        ? encrypt(finalContent, config.api_key)
+        : finalContent;
+
+      const body = {
+        hcu: address,
+        metadata: {
+          author_id: authorIdFor(config),
+          timestamp: new Date().toISOString(),
+          tags: tagList,
+        },
+        payload: { format, content: payloadContent },
+      };
+
+      try {
+        const result = await api.push(body, { append: !!append, expectVersion, force: !!force });
+        decryptSlices([result.slice], config.api_key);
+        upsertSlice(result.slice);
+        console.log(`Pushed → ${address}  (v${result.slice.metadata.version})`);
+      } catch (err) {
+        if (err.response?.status === 409) {
+          const data = err.response.data;
+          if (data?.deleted_at) {
+            console.error(`Push blocked: ${data.error}`);
+            console.error(`  Tombstoned at: ${data.deleted_at}`);
+            console.error(`  To undelete with the prior content: bitpub delete "${address}" --undo`);
+            console.error(`  To overwrite with new content, retry with --force.`);
+          } else {
+            console.error(
+              `Version conflict: expected v${data.expected_version} but server has v${data.actual_version}. ` +
+              `Fetch the latest version and retry.`
+            );
+          }
+        } else {
+          console.error(`Push failed: ${err.message}`);
+        }
+        process.exit(1);
+      }
+    });
+};

package/src/commands/read.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * `bitpub read` — DEPRECATED ALIAS. Use `bitpub load` instead.
+ *
+ * `bitpub load` accepts a fully-qualified `bitpub://` URL plus the same
+ * `--format` flag, so this is a thin pass-through. Hidden from --help.
+ */
+
+const { querySlices } = require('../db/cache');
+
+module.exports = function registerRead(program) {
+  program
+    .command('read', { hidden: true })
+    .description('[deprecated] Use `bitpub load <address>` instead')
+    .requiredOption('--address <string>', 'Address or pattern to read (supports * and ** wildcards)')
+    .option('--format <raw|json>', 'Output format: raw content or full JSON DTOs', 'raw')
+    .action(({ address, format }) => {
+      console.error('warning: `bitpub read` is deprecated. Use `bitpub load <address>` instead.');
+      const slices = querySlices(address);
+      if (slices.length === 0) {
+        console.error(`No slices found for: ${address}`);
+        console.error(`Run: bitpub sync ${address}  to refresh from the cloud, then retry.`);
+        process.exit(1);
+      }
+      if (format === 'json') {
+        const output = slices.map(s => ({
+          hcu: s.hcu,
+          metadata: JSON.parse(s.metadata),
+          payload: JSON.parse(s.payload),
+          last_synced: s.last_synced,
+        }));
+        console.log(JSON.stringify(output, null, 2));
+        return;
+      }
+      const parts = slices.map(s => {
+        const payload = JSON.parse(s.payload);
+        return payload.content ?? '';
+      });
+      console.log(parts.join('\n---\n'));
+    });
+};

package/src/commands/recent.js

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * `bitpub recent` — DEPRECATED ALIAS. Use `bitpub list` instead.
+ *
+ * `bitpub list` is now newest-first by default and shows the same
+ * preview info `recent` did. This thin alias prints a one-line warning
+ * and delegates. Hidden from --help.
+ */
+
+const { requireConfig } = require('../config');
+const { createApiClient } = require('../api');
+const { querySlices, upsertSlice, getCacheStats } = require('../db/cache');
+const { decryptSlices } = require('../crypto');
+const { activeNamespace } = require('../workspace');
+
+function safeParse(s) {
+  try { return JSON.parse(s); } catch { return null; }
+}
+
+module.exports = function registerRecent(program) {
+  program
+    .command('recent', { hidden: true })
+    .description('[deprecated] Use `bitpub list` instead')
+    .option('-n, --limit <number>', 'Max slices to show', '10')
+    .option('--sync', 'Refresh from cloud before listing')
+    .action(async (opts) => {
+      console.error('warning: `bitpub recent` is deprecated. Use `bitpub list` instead.');
+      const config = requireConfig();
+      const active = activeNamespace(config);
+      if (!active) {
+        console.error('No workspace found and no owner configured. Run `bitpub setup` first.');
+        process.exit(1);
+      }
+      const pattern = active.namespace + '**';
+      if (opts.sync) {
+        const api = createApiClient(config);
+        try {
+          const slices = await api.pull(pattern, 200);
+          decryptSlices(slices, config.api_key);
+          slices.forEach(upsertSlice);
+        } catch (err) {
+          console.error(`(sync failed: ${err.message})`);
+        }
+      }
+      const slices = querySlices(pattern);
+      slices.sort((a, b) => String(b.last_synced).localeCompare(String(a.last_synced)));
+      const limit = parseInt(opts.limit, 10) || 10;
+      const top = slices.slice(0, limit);
+      const label = active.workspace?.marker.label || '(session default)';
+      console.log(`Workspace : ${label}`);
+      console.log(`Namespace : ${active.namespace}`);
+      console.log('');
+      if (top.length === 0) {
+        console.log(`No slices yet. Save one: bitpub save <name> "..."`);
+        return;
+      }
+      for (const s of top) {
+        const meta = safeParse(s.metadata) || {};
+        const payload = safeParse(s.payload) || {};
+        const shortName = s.hcu.replace(active.namespace, '') || '(root)';
+        const preview = String(payload.content || '').replace(/\s+/g, ' ').slice(0, 60);
+        const ver = meta.version != null ? `v${meta.version}` : '   ';
+        console.log(`  ${shortName.padEnd(28)}  ${ver.padEnd(5)}  ${preview}`);
+      }
+    });
+};

package/src/commands/restore.js

@@ -0,0 +1,23 @@
+'use strict';
+
+/**
+ * `bitpub restore` — DEPRECATED ALIAS. Use `bitpub delete <name> --undo` instead.
+ *
+ * Forwards to delete's runUndo. Hidden from --help.
+ */
+
+const { requireConfig } = require('../config');
+const { runUndo } = require('./delete');
+
+module.exports = function registerRestore(program) {
+  program
+    .command('restore', { hidden: true })
+    .description('[deprecated] Use `bitpub delete <name> --undo` instead')
+    .requiredOption('--address <string>', 'Exact address to restore')
+    .option('--expect-version <number>', 'Reject if current version differs', parseInt)
+    .action(async ({ address }) => {
+      console.error('warning: `bitpub restore` is deprecated. Use `bitpub delete <name> --undo` instead.');
+      const config = requireConfig();
+      await runUndo(address, config);
+    });
+};