@bitpub/cli 2.0.0

package/src/commands/catchup.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * `bitpub catch-up` — DEPRECATED ALIAS. Use `bitpub list --sync` instead.
+ *
+ * The new `list --sync` does what catch-up did: pull the active workspace
+ * (and any group_link) from the cloud, then surface recent slices with
+ * the workspace anchor, cache freshness, and previews. Hidden from --help.
+ */
+
+const { requireConfig } = require('../config');
+const { createApiClient } = require('../api');
+const { querySlices, upsertSlice } = require('../db/cache');
+const { decryptSlices } = require('../crypto');
+const { activeNamespace } = require('../workspace');
+
+function safeParse(s) {
+  try { return JSON.parse(s); } catch { return null; }
+}
+
+function normalizePattern(hcu) {
+  if (hcu.endsWith('**') || hcu.endsWith('*')) return hcu;
+  return hcu.replace(/\/?$/, '/**');
+}
+
+function normalizeBase(hcu) {
+  return hcu.replace(/\/?$/, '/');
+}
+
+function sortByRecency(rows) {
+  return rows.slice().sort((a, b) => String(b.last_synced).localeCompare(String(a.last_synced)));
+}
+
+async function sync(api, pattern, config) {
+  try {
+    const slices = await api.pull(pattern, 200);
+    decryptSlices(slices, config.api_key);
+    slices.forEach(upsertSlice);
+  } catch (err) {
+    console.error(`(sync ${pattern} failed: ${err.message})`);
+  }
+}
+
+function printSection(title, rows, base, limit) {
+  console.log(title);
+  if (rows.length === 0) {
+    console.log('  (empty)');
+    console.log('');
+    return;
+  }
+  for (const s of rows.slice(0, limit)) {
+    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, 80);
+    const when = String(meta.timestamp || s.last_synced || '').slice(0, 16).replace('T', ' ');
+    console.log(`  [${when}]  ${shortName || '(root)'}`);
+    if (preview) console.log(`              ${preview}`);
+  }
+  if (rows.length > limit) {
+    console.log(`  … ${rows.length - limit} more`);
+  }
+  console.log('');
+}
+
+module.exports = function registerCatchup(program) {
+  program
+    .command('catch-up', { hidden: true })
+    .description('[deprecated] Use `bitpub list --sync` instead')
+    .option('-n, --limit <number>', 'Slices to surface per scope', '10')
+    .option('--no-sync', 'Skip the network sync (cache only)')
+    .action(async (opts) => {
+      console.error('warning: `bitpub catch-up` is deprecated. Use `bitpub list --sync` instead.');
+      const config = requireConfig();
+      const active = activeNamespace(config);
+      if (!active) {
+        console.error('No workspace and no owner configured. Run `bitpub setup` first.');
+        process.exit(1);
+      }
+      const limit = parseInt(opts.limit, 10) || 10;
+      const api = createApiClient(config);
+      const groupLink = active.workspace?.marker.group_link || null;
+      if (opts.sync !== false) {
+        await sync(api, active.namespace + '**', config);
+        if (groupLink) await sync(api, normalizePattern(groupLink), config);
+      }
+      console.log('═══ Catch-up ═══');
+      if (active.workspace) {
+        console.log(`Workspace  : ${active.workspace.marker.label || active.workspace.marker.id}`);
+        console.log(`Root       : ${active.workspace.root}`);
+      } else {
+        console.log('Workspace  : (none — using per-day session default)');
+      }
+      console.log(`Namespace  : ${active.namespace}`);
+      if (groupLink) console.log(`Group link : ${groupLink}`);
+      console.log('');
+      const privateSlices = sortByRecency(querySlices(active.namespace + '**'));
+      printSection('Your recent work (private)', privateSlices, active.namespace, limit);
+      if (groupLink) {
+        const groupSlices = sortByRecency(querySlices(normalizePattern(groupLink)));
+        const groupBase = normalizeBase(groupLink);
+        printSection('Team context (group, read-mostly)', groupSlices, groupBase, limit);
+      }
+      if (privateSlices.length === 0 && !groupLink) {
+        console.log('No prior work here. Save your first slice:');
+        console.log('  bitpub save <name> "..."');
+      }
+    });
+};

package/src/commands/delete.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * `bitpub delete <name-or-address>` — remove a slice.
+ *
+ * Subsumes the previous `drop`, `trash`, and `restore` verbs into one
+ * verb that does the right thing by default, with friendlier flags for
+ * the recovery cases:
+ *
+ *   bitpub delete notes                   soft-delete (recoverable)
+ *   bitpub delete notes --undo            recover from trash / restore on server
+ *   bitpub delete --list                  show what's in the local trash
+ *   bitpub delete --empty-trash           clear the local undo buffer
+ *
+ * Scope-aware cache behavior preserved from `drop`:
+ *   - private:  row leaves local_slices, lands in local_trash (offline undo)
+ *   - group:    row is evicted; recovery goes through the server (--undo)
+ *
+ * Wildcards are rejected — a delete is an exact-address operation. The
+ * input grammar is the same as load/save: a project short name, an
+ * `@alias`, or a full `bitpub://` URL.
+ */
+
+const { requireConfig } = require('../config');
+const { createApiClient } = require('../api');
+const {
+  upsertSlice,
+  evictSlice,
+  trashSlice,
+  getTrashEntry,
+  removeFromTrash,
+  listTrash,
+  emptyTrash: emptyTrashRows,
+  purgeExpiredTrash,
+  TRASH_TTL_DAYS,
+} = require('../db/cache');
+const { decryptSlices, isPrivateHcu } = require('../crypto');
+const { activeNamespace, resolveHcu } = require('../workspace');
+
+function safeParse(s) {
+  try { return JSON.parse(s); } catch { return null; }
+}
+
+async function runDelete(name, opts) {
+  if (!name) {
+    console.error('Provide an address or short name to delete.');
+    process.exit(1);
+  }
+  if (name.includes('*')) {
+    console.error('Wildcards are not permitted. Delete one slice at a time.');
+    process.exit(1);
+  }
+
+  const config = requireConfig();
+  let address;
+  try { ({ hcu: address } = resolveHcu(name, config)); }
+  catch (err) { console.error(err.message); process.exit(1); }
+
+  if (opts.undo) return runUndo(address, config);
+
+  const api = createApiClient(config);
+  try {
+    const result = await api.drop(address, { expectVersion: opts.expectVersion });
+    const slice = result.slice;
+    if (slice) decryptSlices([slice], config.api_key);
+
+    if (isPrivateHcu(address) && slice) {
+      trashSlice(slice, slice.deleted_at);
+      console.log(`✓ Deleted → ${address}  (v${slice.metadata.version})`);
+      console.log(`  Undo with: bitpub delete "${name}" --undo  (within ${TRASH_TTL_DAYS} days)`);
+    } else {
+      evictSlice(address);
+      console.log(`✓ Deleted → ${address}  (v${slice?.metadata?.version ?? '?'})`);
+      console.log(`  Undo with: bitpub delete "${name}" --undo`);
+    }
+  } catch (err) {
+    if (err.response?.status === 409) {
+      const data = err.response.data;
+      console.error(
+        `Version conflict: expected v${data.expected_version} but server has v${data.actual_version}.`
+      );
+    } else if (err.response?.status === 404) {
+      console.error(`Not found: ${address}`);
+    } else {
+      console.error(`Delete failed: ${err.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+async function runUndo(address, config) {
+  const api = createApiClient(config);
+
+  // Private undos use the recorded trash version as a CAS guard so we
+  // don't silently clobber a concurrent restore. Group undos go straight
+  // through the server with no version check (no local trash entry).
+  const entry = getTrashEntry(address);
+
+  try {
+    const result = await api.restore(
+      address,
+      entry ? { expectVersion: entry.version } : {}
+    );
+    const slice = result.slice;
+    if (slice) decryptSlices([slice], config.api_key);
+    if (slice) upsertSlice(slice);
+    if (entry) removeFromTrash(address);
+
+    console.log(`✓ Undone → ${address}  (v${slice?.metadata?.version ?? '?'})`);
+  } catch (err) {
+    const status = err.response?.status;
+    const data = err.response?.data;
+    if (status === 409 && data?.error?.match(/not in deleted state/i)) {
+      console.error(`${address} is already active. Nothing to undo.`);
+      if (entry) removeFromTrash(address);
+    } else if (status === 409 && entry) {
+      console.error(
+        `Version drift: trash entry has v${entry.version} but server is at v${data?.actual_version}.\n` +
+        `Run: bitpub sync ${address}  to see the current state, then decide.`
+      );
+    } else if (status === 404) {
+      console.error(`${address} doesn't exist on the server.`);
+      if (entry) removeFromTrash(address);
+    } else {
+      console.error(`Undo failed: ${err.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+function runListTrash(config, opts) {
+  const purged = purgeExpiredTrash();
+  if (purged > 0) {
+    console.log(`(purged ${purged} entry(ies) past the ${TRASH_TTL_DAYS}-day TTL)`);
+  }
+
+  let prefix = null;
+  if (!opts.all) {
+    const active = activeNamespace(config);
+    if (active) prefix = active.namespace;
+  }
+
+  const rows = listTrash(prefix);
+  if (rows.length === 0) {
+    console.log(prefix ? `(no deleted slices in ${prefix})` : '(nothing in trash)');
+    return;
+  }
+
+  console.log(`Recently deleted (${rows.length}, kept for ${TRASH_TTL_DAYS} days):`);
+  for (const row of rows) {
+    const meta = safeParse(row.metadata) || {};
+    const shortName = prefix ? row.hcu.replace(prefix, '') : row.hcu;
+    const ver = meta.version != null ? `v${meta.version}` : '   ';
+    console.log(`  ${ver.padEnd(5)}  ${row.deleted_at}   ${shortName}`);
+  }
+  console.log('');
+  console.log('Undo with: bitpub delete <name> --undo');
+}
+
+function runEmptyTrash(opts) {
+  const removed = emptyTrashRows(opts.namespace || null);
+  if (removed === 0) {
+    console.log('(nothing to empty)');
+  } else {
+    console.log(`Emptied ${removed} entry${removed === 1 ? '' : 'ies'} from local trash.`);
+    console.log('  (server-side recovery still possible via `bitpub delete <name> --undo`)');
+  }
+}
+
+module.exports = function registerDelete(program) {
+  program
+    .command('delete [name]')
+    .description('Delete a slice (recoverable for 30 days). --undo to recover; --list to see deleted.')
+    .option('--undo', 'Restore a deleted slice from the local trash or the server')
+    .option('--list', 'Show recently deleted slices instead of deleting')
+    .option('--empty-trash', 'Clear the local undo buffer (server-side recovery still possible)')
+    .option('--all', 'With --list: show deleted slices across every namespace')
+    .option('--namespace <prefix>', 'With --empty-trash: restrict to a namespace prefix')
+    .option('--expect-version <number>', 'Reject if current version differs (optimistic concurrency)', parseInt)
+    .action(async (name, opts) => {
+      const config = requireConfig();
+      if (opts.list) return runListTrash(config, opts);
+      if (opts.emptyTrash) return runEmptyTrash(opts);
+      return runDelete(name, opts);
+    });
+};
+
+module.exports.runDelete = runDelete;
+module.exports.runUndo = runUndo;

package/src/commands/drop.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * `bitpub drop` — DEPRECATED ALIAS. Use `bitpub delete` instead.
+ *
+ * Forwards to delete's runDelete with the same semantics (soft-delete,
+ * recoverable). Hidden from --help.
+ */
+
+const { runDelete } = require('./delete');
+
+module.exports = function registerDrop(program) {
+  program
+    .command('drop', { hidden: true })
+    .description('[deprecated] Use `bitpub delete` instead')
+    .requiredOption('--address <string>', 'Exact address to drop')
+    .option('--expect-version <number>', 'Reject if current version differs', parseInt)
+    .action(async ({ address, expectVersion }) => {
+      console.error('warning: `bitpub drop` is deprecated. Use `bitpub delete <name>` instead.');
+      await runDelete(address, { expectVersion });
+    });
+};

package/src/commands/fetch.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * `bitpub fetch` — DEPRECATED ALIAS. Use `bitpub sync` instead.
+ *
+ * Forwards to the new sync implementation with the same semantics
+ * (one-shot pull into the local cache). Hidden from --help.
+ */
+
+const { requireConfig } = require('../config');
+const { runOneShot } = require('./sync');
+
+module.exports = function registerFetch(program) {
+  program
+    .command('fetch', { hidden: true })
+    .description('[deprecated] Use `bitpub sync` instead')
+    .requiredOption('--address <string>', 'Address pattern to sync (supports * and ** wildcards)')
+    .option('--limit <number>', 'Max slices to fetch (server caps at 500 per request)', '500')
+    .action(async ({ address, limit }) => {
+      console.error('warning: `bitpub fetch` is deprecated. Use `bitpub sync` instead.');
+      const config = requireConfig();
+      try {
+        await runOneShot({ pattern: address, label: address, limit, includeDeleted: false }, config);
+      } catch (err) {
+        console.error(`Sync failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+};

package/src/commands/find.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * `bitpub find <term>` — search for slices by name (URL tail) and by
+ * content, in a single command.
+ *
+ * Why both modes in one verb?
+ *
+ *   - Agents calling `find` after a `load` miss don't always know whether
+ *     the user gave them a partial slice name or a fragment of the
+ *     content they want. Showing both kinds of matches makes the
+ *     recovery work without a flag.
+ *
+ *   - For human users, a unified "what's in my memory that mentions X"
+ *     mental model is easier than choosing between two flavors of
+ *     search up front.
+ *
+ * Output is always:
+ *   1. Name matches first (more specific — exact path-tail equals term).
+ *   2. Content matches second (with a few snippet lines per match).
+ *
+ * Defaults to scope = the active project; pass `--scope` for a wider
+ * search across `bitpub://private:<owner>/**` or a group namespace.
+ */
+
+const { requireConfig } = require('../config');
+const { createApiClient } = require('../api');
+const { querySlices, upsertSlice, findSlicesByName } = require('../db/cache');
+const { decryptSlices } = require('../crypto');
+const { activeNamespace } = require('../workspace');
+const { maybeExpand } = require('../aliases');
+
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function safeParse(s) {
+  try { return JSON.parse(s); } catch { return null; }
+}
+
+async function runFind(term, opts) {
+  const config = requireConfig();
+
+  // Resolve the search scope. Default = active project; --scope overrides
+  // (and accepts aliases like @memory). --all widens to the user's full
+  // private namespace, which is the right move for "where did I put X".
+  let scope;
+  let scopeLabel;
+
+  if (opts.all) {
+    if (!config.owner) {
+      console.error('--all requires a private identity. Run `bitpub setup` first.');
+      process.exit(1);
+    }
+    scope = `bitpub://private:${config.owner}/**`;
+    scopeLabel = '(everything in your private memory)';
+  } else if (opts.scope) {
+    let expanded;
+    try { expanded = maybeExpand(opts.scope); }
+    catch (err) { console.error(err.message); process.exit(1); }
+    scope = expanded.endsWith('**') || expanded.endsWith('*')
+      ? expanded
+      : expanded.replace(/\/?$/, '/**');
+    scopeLabel = opts.scope;
+  } else {
+    const active = activeNamespace(config);
+    if (!active) {
+      console.error('No project anchored here and no identity. Run `bitpub setup` or pass --scope <pattern>.');
+      process.exit(1);
+    }
+    scope = active.namespace + '**';
+    scopeLabel = active.workspace?.marker.label || '(today\'s session bucket)';
+  }
+
+  if (opts.sync) {
+    const api = createApiClient(config);
+    try {
+      const slices = await api.pull(scope, 500);
+      decryptSlices(slices, config.api_key);
+      slices.forEach(upsertSlice);
+    } catch (err) {
+      console.error(`(sync failed: ${err.message} — using local cache)`);
+    }
+  }
+
+  const wantName = !opts.contentOnly;
+  const wantContent = !opts.nameOnly;
+
+  // ── Name matches (path-tail equals or matches the term) ────────────
+  let nameHits = [];
+  if (wantName) {
+    nameHits = findSlicesByName(term, scope);
+  }
+  const nameHitSet = new Set(nameHits.map(s => s.hcu));
+
+  // ── Content matches (regex over slice payload contents) ────────────
+  let contentHits = [];
+  if (wantContent) {
+    const flags = opts.ignoreCase ? 'gi' : 'g';
+    const re = new RegExp(escapeRegex(term), flags);
+    const maxPerSlice = parseInt(opts.maxPerSlice, 10) || 3;
+
+    const allSlices = querySlices(scope);
+    for (const s of allSlices) {
+      // Don't double-count: if a slice already matched by name, skip the
+      // content scan to keep the output tidy. The user will see the
+      // address in the name-matches section regardless.
+      if (nameHitSet.has(s.hcu)) continue;
+
+      const payload = safeParse(s.payload) || {};
+      const content = String(payload.content || '');
+      if (!content) continue;
+      const lines = content.split('\n');
+      const matches = lines.filter(l => re.test(l));
+      if (matches.length === 0) continue;
+      contentHits.push({ slice: s, matches, maxPerSlice });
+    }
+  }
+
+  const totalHits = nameHits.length + contentHits.length;
+
+  console.log(`Search : "${term}"`);
+  console.log(`Scope  : ${scopeLabel}`);
+  console.log(`Found  : ${nameHits.length} by name, ${contentHits.length} by content`);
+  console.log('');
+
+  if (totalHits === 0) {
+    console.log(`  (no matches)`);
+    if (!opts.all) {
+      console.log('');
+      console.log('  Try widening the search:');
+      console.log(`    bitpub find "${term}" --all`);
+    }
+    return;
+  }
+
+  if (nameHits.length > 0) {
+    console.log('Matched by name:');
+    for (const s of nameHits) {
+      const meta = safeParse(s.metadata) || {};
+      const ver = meta.version != null ? `v${meta.version}` : '   ';
+      console.log(`  ${s.hcu}  ${ver}`);
+    }
+    console.log('');
+  }
+
+  if (contentHits.length > 0) {
+    console.log('Matched by content:');
+    for (const { slice: s, matches, maxPerSlice } of contentHits) {
+      console.log(`  ${s.hcu}`);
+      for (const line of matches.slice(0, maxPerSlice)) {
+        console.log(`    ${line.trim().slice(0, 120)}`);
+      }
+      if (matches.length > maxPerSlice) {
+        console.log(`    … ${matches.length - maxPerSlice} more match(es)`);
+      }
+    }
+  }
+}
+
+module.exports = function registerFind(program) {
+  program
+    .command('find <term>')
+    .description('Search slices by name and content (use --all for everything you\'ve saved)')
+    .option('--scope <pattern>', 'Override search scope (address pattern, supports ** wildcards)')
+    .option('--all', 'Search across your full private memory (shorthand for --scope bitpub://private:<owner>/**)')
+    .option('-i, --ignore-case', 'Case-insensitive content search')
+    .option('--name-only', 'Skip content search')
+    .option('--content-only', 'Skip name search')
+    .option('--sync', 'Refresh from cloud before searching')
+    .option('-n, --max-per-slice <number>', 'Max matching content lines per slice', '3')
+    .action(runFind);
+};
+
+module.exports.runFind = runFind;

package/src/commands/grep.js

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * `bitpub grep` — DEPRECATED ALIAS. Use `bitpub find` instead.
+ *
+ * Kept working so existing scripts and shell aliases don't break. The
+ * deprecation warning prints once per invocation; the call is forwarded
+ * to `find`'s implementation with `--content-only` so behavior matches
+ * the old grep semantics exactly (content search only, no name search).
+ */
+
+const { runFind } = require('./find');
+
+module.exports = function registerGrep(program) {
+  program
+    .command('grep <term>', { hidden: true })
+    .description('[deprecated] Use `bitpub find` instead — content-only search in the active workspace')
+    .option('--scope <pattern>', 'Override search scope (address pattern, supports ** wildcards)')
+    .option('-i, --ignore-case', 'Case-insensitive')
+    .option('--sync', 'Refresh from cloud before searching')
+    .option('-n, --max-per-slice <number>', 'Max matching lines per slice', '3')
+    .action(async (term, opts) => {
+      console.error('warning: `bitpub grep` is deprecated. Use `bitpub find` instead.');
+      await runFind(term, { ...opts, contentOnly: true });
+    });
+};

package/src/commands/init.js

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * `bitpub init` — DEPRECATED ALIAS. Use `bitpub setup` instead.
+ *
+ * Forwards to setup's ensure* helpers so the behavior is identical to
+ * `bitpub setup` (idempotent identity provision + folder anchor + skill
+ * install). Hidden from --help; prints a one-line stderr warning.
+ *
+ * Save.js auto-runs setup lazily before the first save anyway, so most
+ * users will never need to call this directly under either name.
+ */
+
+const {
+  ensureIdentity,
+  ensureWorkspace,
+  ensureSkill,
+} = require('./setup');
+const { DEFAULT_CLOUD_URL } = require('../config');
+
+module.exports = function registerInit(program) {
+  program
+    .command('init', { hidden: true })
+    .description('[deprecated] Use `bitpub setup` instead')
+    .option('--url <string>', 'Cloud tenant URL', DEFAULT_CLOUD_URL)
+    .option('--local-only', 'Set up the local store only; skip cloud provisioning')
+    .option('--no-workspace', 'Skip creating a .bitpub/workspace.json in the current folder')
+    .option('--workspace-label <string>', 'Override the workspace label (defaults to folder name)')
+    .option('--force', 'Overwrite an existing identity (the old key is unrecoverable)')
+    .option('--import-from <path>', 'Import an existing TollBit config')
+    .option('--no-import', 'Skip auto-import')
+    .action(async (opts) => {
+      console.error('warning: `bitpub init` is deprecated. Use `bitpub setup` instead.');
+      try {
+        const config = await ensureIdentity({
+          url: opts.url,
+          force: !!opts.force,
+          localOnly: !!opts.localOnly,
+        });
+        if (config && opts.workspace !== false) {
+          ensureWorkspace({ owner: config.owner, label: opts.workspaceLabel });
+        }
+        await ensureSkill({});
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+};