@bitpub/cli 2.0.0

package/src/commands/sync.js

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * `bitpub sync [path]` — pull remote slices into the local cache.
+ *
+ * Two modes:
+ *   - One-shot (default): walk the addresses for the given path, pull
+ *     them, write to cache, exit. Replaces the old `bitpub fetch`.
+ *   - Live (`--watch`):  open the SSE heartbeat stream and keep the
+ *     cache up to date in the background until interrupted. Replaces
+ *     the old `bitpub watch`.
+ *
+ * The `path` argument is optional and accepts the same forms as
+ * everything else: a project short name (rare for sync — it'd be a
+ * single slice), an `@alias`, or a full `bitpub://` address with or
+ * without wildcards. With no argument, syncs the active project.
+ *
+ * Power flags (`--limit`, `--include-deleted`) are kept here for the
+ * minority of users who care; they default to safe values.
+ */
+
+const { requireConfig } = require('../config');
+const { createApiClient } = require('../api');
+const {
+  upsertSlice,
+  evictSlice,
+  recordNamespaceSync,
+} = require('../db/cache');
+const { decryptSlices } = require('../crypto');
+const { activeNamespace } = require('../workspace');
+const { maybeExpand } = require('../aliases');
+
+function resolveSyncPattern(input, config) {
+  // No arg → active project's pattern
+  if (!input) {
+    const active = activeNamespace(config);
+    if (!active) {
+      throw new Error('No project anchored here and no path given. Run `bitpub setup` first or pass a path / address.');
+    }
+    return { pattern: active.namespace + '**', label: active.workspace?.marker.label || '(today\'s session bucket)' };
+  }
+
+  // Alias or fully-qualified URL: normalize to a pattern
+  let resolved;
+  try { resolved = maybeExpand(input); }
+  catch (err) { throw err; }
+
+  if (resolved.startsWith('bitpub://')) {
+    const pattern = resolved.endsWith('**') || resolved.endsWith('*')
+      ? resolved
+      : resolved.replace(/\/?$/, '/**');
+    return { pattern, label: input };
+  }
+
+  // Bare short name: treat as a project-relative single slice address
+  const active = activeNamespace(config);
+  if (!active) {
+    throw new Error(`Cannot resolve "${input}": no project anchored here. Pass a full bitpub:// URL or an alias.`);
+  }
+  return { pattern: active.namespace + resolved, label: input };
+}
+
+async function runOneShot({ pattern, label, limit, includeDeleted }, config) {
+  const api = createApiClient(config);
+  const limitNum = parseInt(limit, 10) || 500;
+
+  const slices = await api.pull(pattern, limitNum, { includeDeleted: !!includeDeleted });
+  decryptSlices(slices, config.api_key);
+
+  for (const slice of slices) upsertSlice(slice);
+  recordNamespaceSync(pattern, slices.length);
+
+  console.log(`Synced ${slices.length} slice(s) from ${label}`);
+
+  // Surface page-cap warning so the user knows to narrow their pattern.
+  if (slices.length >= Math.min(limitNum, 500)) {
+    console.log(
+      `\n  Hit the page limit (${slices.length} rows). Server caps single sync at 500.` +
+      ` If you expect more, sync sub-namespaces individually:`
+    );
+    const base = pattern.replace(/\/\*+$/, '');
+    console.log(`    bitpub sync '${base}/Projects/**'`);
+    console.log(`    bitpub sync '${base}/Memory/**'`);
+    console.log(`    bitpub sync '${base}/Sessions/**'`);
+  }
+}
+
+function runWatch({ pattern, label }, config) {
+  const api = createApiClient(config);
+
+  console.log(`Watching ${label} (Ctrl+C to stop)`);
+
+  const close = api.watch(
+    pattern,
+    async (evt) => {
+      const updatedAddress = typeof evt === 'string' ? evt : evt.hcu;
+      const isDeleted = typeof evt === 'object' && evt.deleted === true;
+
+      if (isDeleted) {
+        evictSlice(updatedAddress);
+        console.log(`[sync] ${updatedAddress} (deleted, evicted from cache)`);
+        return;
+      }
+
+      process.stdout.write(`[sync] ${updatedAddress} … `);
+      try {
+        const slices = await api.pull(updatedAddress);
+        decryptSlices(slices, config.api_key);
+        for (const slice of slices) upsertSlice(slice);
+        recordNamespaceSync(pattern, slices.length);
+        console.log(`${slices.length} slice(s) updated`);
+      } catch (err) {
+        console.log(`fetch failed: ${err.message}`);
+      }
+    },
+    (err) => {
+      console.error(`[sync] Connection error: ${err?.message ?? 'unknown'}. Retrying…`);
+    }
+  );
+
+  process.on('SIGINT', () => {
+    close();
+    console.log('\nSync watcher stopped.');
+    process.exit(0);
+  });
+}
+
+module.exports = function registerSync(program) {
+  program
+    .command('sync [path]')
+    .description('Pull the latest slices from the cloud into your local cache (--watch for live)')
+    .option('--watch', 'Stay open and keep the cache in sync via SSE')
+    .option('--limit <number>', 'Max slices per request (server caps at 500)', '500')
+    .option('--include-deleted', 'Include tombstoned slices in the sync')
+    .action(async (path, opts) => {
+      const config = requireConfig();
+
+      let resolved;
+      try { resolved = resolveSyncPattern(path, config); }
+      catch (err) { console.error(err.message); process.exit(1); }
+
+      if (opts.watch) {
+        return runWatch(resolved, config);
+      }
+
+      try {
+        await runOneShot(
+          { ...resolved, limit: opts.limit, includeDeleted: opts.includeDeleted },
+          config
+        );
+      } catch (err) {
+        console.error(`Sync failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+};
+
+module.exports.runOneShot = runOneShot;
+module.exports.runWatch = runWatch;
+module.exports.resolveSyncPattern = resolveSyncPattern;

package/src/commands/trash.js

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * `bitpub trash …` — DEPRECATED ALIAS. Use `bitpub delete --list` /
+ * `bitpub delete <name> --undo` / `bitpub delete --empty-trash` instead.
+ *
+ * Subcommands kept for backwards compatibility:
+ *
+ *   trash list                 → bitpub delete --list
+ *   trash restore <name>       → bitpub delete <name> --undo
+ *   trash empty                → bitpub delete --empty-trash
+ *
+ * Each prints a one-line stderr deprecation note then forwards to the
+ * new implementation. Hidden from --help.
+ */
+
+const { requireConfig } = require('../config');
+const { runUndo } = require('./delete');
+const {
+  listTrash,
+  emptyTrash: emptyTrashRows,
+  purgeExpiredTrash,
+  TRASH_TTL_DAYS,
+} = require('../db/cache');
+const { activeNamespace, resolveHcu } = require('../workspace');
+
+function safeParse(s) {
+  try { return JSON.parse(s); } catch { return null; }
+}
+
+module.exports = function registerTrash(program) {
+  const trash = program
+    .command('trash', { hidden: true })
+    .description('[deprecated] Use `bitpub delete --list` / `--undo` / `--empty-trash` instead');
+
+  trash
+    .command('list')
+    .option('--all', 'Show every trash entry across all namespaces')
+    .action(({ all }) => {
+      console.error('warning: `bitpub trash list` is deprecated. Use `bitpub delete --list` instead.');
+      const config = requireConfig();
+      const purged = purgeExpiredTrash();
+      if (purged > 0) {
+        console.log(`(purged ${purged} entry(ies) past the ${TRASH_TTL_DAYS}-day TTL)`);
+      }
+      let prefix = null;
+      if (!all) {
+        const active = activeNamespace(config);
+        if (active) prefix = active.namespace;
+      }
+      const rows = listTrash(prefix);
+      if (rows.length === 0) {
+        console.log(prefix ? `(no trashed slices in ${prefix})` : '(trash is empty)');
+        return;
+      }
+      console.log(`Trash (${rows.length} entry(ies), TTL ${TRASH_TTL_DAYS}d):`);
+      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}`);
+      }
+    });
+
+  trash
+    .command('restore <name>')
+    .action(async (name) => {
+      console.error('warning: `bitpub trash restore` is deprecated. Use `bitpub delete <name> --undo` instead.');
+      const config = requireConfig();
+      let address;
+      try { ({ hcu: address } = resolveHcu(name, config)); }
+      catch (err) { console.error(err.message); process.exit(1); }
+      await runUndo(address, config);
+    });
+
+  trash
+    .command('empty')
+    .option('--namespace <prefix>', 'Restrict to entries with this prefix')
+    .action(({ namespace }) => {
+      console.error('warning: `bitpub trash empty` is deprecated. Use `bitpub delete --empty-trash` instead.');
+      const removed = emptyTrashRows(namespace || null);
+      if (removed === 0) {
+        console.log('(nothing to empty)');
+      } else {
+        console.log(`Emptied ${removed} trash entry(ies).`);
+      }
+    });
+};

package/src/commands/update.js

@@ -0,0 +1,155 @@
+'use strict';
+
+/**
+ * `bitpub update` — pull the latest CLI tarball from your tenant and
+ * reinstall globally.
+ *
+ * Resolution order for the tenant URL (first match wins):
+ *   1. --url flag
+ *   2. BITPUB_CLOUD_URL env var
+ *   3. api_url from ~/.bitpub/config.json (set by `bitpub init` / `auth login`)
+ *   4. https://bitpub.io
+ *
+ * The tarball lives at `${url}/cli/latest.tgz` — same path the one-liner
+ * installer uses. We download to a temp file, peek at its package.json
+ * for a version diff, then run `npm install -g <tarball>`.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { spawnSync } = require('child_process');
+const axios = require('axios');
+const { readConfig } = require('../config');
+const { refreshExistingSkills } = require('./skills');
+
+module.exports = function registerUpdate(program) {
+  program
+    .command('update')
+    .description('Update the BitPub CLI (and any installed skill files) to the latest tarball published by your tenant')
+    .option('--url <string>', 'Override the tenant URL to fetch the tarball from')
+    .option('--check', 'Only check the remote version; do not install')
+    .option('--skip-skills', 'Do not refresh installed skill files after the update')
+    .action(async (opts) => {
+      const config = readConfig();
+      const cloudUrl = (
+        opts.url ||
+        process.env.BITPUB_CLOUD_URL ||
+        config?.api_url ||
+        'https://bitpub.io'
+      ).replace(/\/$/, '');
+
+      const tarballUrl = `${cloudUrl}/cli/latest.tgz`;
+      const localVersion = require('../../package.json').version;
+
+      console.log(`Current : v${localVersion}`);
+      console.log(`Tarball : ${tarballUrl}`);
+
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bitpub-update-'));
+      const tarballPath = path.join(tmpDir, 'bitpub-cli.tgz');
+
+      try {
+        const resp = await axios.get(tarballUrl, {
+          responseType: 'arraybuffer',
+          timeout: 30_000,
+          maxRedirects: 5,
+          validateStatus: (s) => s === 200,
+        });
+        fs.writeFileSync(tarballPath, Buffer.from(resp.data));
+      } catch (err) {
+        cleanup(tmpDir);
+        const status = err.response?.status;
+        if (status) {
+          console.error(`\n✗ Failed to download tarball: HTTP ${status} from ${tarballUrl}`);
+          if (status === 404) {
+            console.error('  This tenant does not appear to publish a CLI tarball.');
+            console.error('  Try --url https://bitpub.io for the public tenant.');
+          }
+        } else {
+          console.error(`\n✗ Failed to download tarball: ${err.message}`);
+        }
+        process.exit(1);
+      }
+
+      const remoteVersion = readVersionFromTarball(tarballPath) || 'unknown';
+      console.log(`Remote  : v${remoteVersion}`);
+
+      if (opts.check) {
+        cleanup(tmpDir);
+        if (remoteVersion === localVersion) {
+          console.log('\n✓ Already up to date.');
+        } else {
+          console.log('\nRun `bitpub update` to install v' + remoteVersion + '.');
+        }
+        return;
+      }
+
+      if (remoteVersion === localVersion) {
+        console.log('\nAlready on v' + localVersion + ' — reinstalling anyway to refresh files.');
+      }
+
+      console.log('\nInstalling globally with npm...');
+      const result = spawnSync('npm', ['install', '-g', tarballPath], {
+        stdio: 'inherit',
+      });
+
+      cleanup(tmpDir);
+
+      if (result.status !== 0) {
+        console.error('\n✗ npm install -g failed.');
+        console.error('  Try running the command with sudo, or set npm prefix to a writable dir.');
+        process.exit(result.status || 1);
+      }
+
+      console.log(`\n✓ BitPub CLI updated to v${remoteVersion}.`);
+
+      if (opts.skipSkills) return;
+
+      console.log('\nRefreshing installed skill files...');
+      const { updates, error } = await refreshExistingSkills();
+      if (error) {
+        console.log(`  ⊘ skipped: ${error}`);
+        return;
+      }
+      if (updates.length === 0) {
+        console.log('  (no skill installs found — run `bitpub skills install` to set them up)');
+        return;
+      }
+      for (const u of updates) {
+        const arrow = u.status === 'updated' ? '↻' : '·';
+        let suffix = '';
+        if (u.oldVersion && u.newVersion && u.oldVersion !== u.newVersion) {
+          suffix = `  v${u.oldVersion} → v${u.newVersion}`;
+        } else if (u.newVersion) {
+          suffix = `  v${u.newVersion}`;
+        }
+        console.log(`  ${arrow} ${u.label.padEnd(28)} ${u.path}${suffix}`);
+      }
+    });
+};
+
+function cleanup(tmpDir) {
+  try {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Peek at `package/package.json` inside an npm tarball using the system
+ * `tar`. Both BSD tar (macOS default) and GNU tar (Linux) support
+ * `-xzOf <file> <member>` to extract a single entry to stdout. Returns
+ * null on any error; callers treat that as "version unknown" and proceed.
+ */
+function readVersionFromTarball(tarballPath) {
+  const out = spawnSync('tar', ['-xzOf', tarballPath, 'package/package.json'], {
+    encoding: 'utf-8',
+  });
+  if (out.status !== 0 || !out.stdout) return null;
+  try {
+    return JSON.parse(out.stdout).version || null;
+  } catch {
+    return null;
+  }
+}

package/src/commands/watch.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * `bitpub watch` — DEPRECATED ALIAS. Use `bitpub sync --watch` instead.
+ *
+ * Forwards to sync's runWatch implementation directly. Hidden from --help;
+ * kept for backwards compatibility with shell scripts and existing
+ * automation.
+ */
+
+const { requireConfig } = require('../config');
+const { runWatch } = require('./sync');
+
+module.exports = function registerWatch(program) {
+  program
+    .command('watch', { hidden: true })
+    .description('[deprecated] Use `bitpub sync --watch` instead')
+    .requiredOption('--address <string>', 'Address pattern to watch (supports ** wildcards)')
+    .action(({ address }) => {
+      console.error('warning: `bitpub watch` is deprecated. Use `bitpub sync --watch` instead.');
+      const config = requireConfig();
+      runWatch({ pattern: address, label: address }, config);
+    });
+};

package/src/commands/welcome.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * `bitpub welcome` — first-run UX for non-technical users.
+ *
+ * Two responsibilities:
+ *   1. Save a "Welcome" slice into the user's private namespace at a stable
+ *      address (`bitpub://private:<owner>/Welcome`). This is proof to a
+ *      non-technical user that the round trip works: an identity got
+ *      provisioned, encryption is set up, and reads/writes hit the cloud.
+ *
+ *   2. With `--serve`, start the local browser UI and open a tab to the
+ *      welcome slice. This is what install.sh calls so the very first thing
+ *      a new user sees after `curl ... | bash` is a working browser tab,
+ *      not just a blinking shell prompt.
+ *
+ * Idempotent by default. The welcome slice is saved exactly once per
+ * machine — re-running `bitpub welcome` is a no-op unless `--force` is
+ * passed. This is gated by `welcome_saved_at` in ~/.bitpub/config.json so
+ * users (or install.sh re-runs) don't keep re-stamping the same slice.
+ *
+ * Note: tied to install, not to init. `bitpub init` is idempotent and may
+ * run many times across many folders; the welcome flow should fire exactly
+ * once, the first time the user sets up BitPub on this machine.
+ */
+
+const { requireConfig, readConfig, writeConfig, authorIdFor } = require('../config');
+const { createApiClient } = require('../api');
+const { upsertSlice } = require('../db/cache');
+const { encrypt, decryptSlices } = require('../crypto');
+const { startBrowserServer } = require('./browser');
+
+const WELCOME_SLICE_NAME = 'Welcome';
+
+function welcomeAddressFor(owner) {
+  return `bitpub://private:${owner}/${WELCOME_SLICE_NAME}`;
+}
+
+function buildWelcomeContent(config) {
+  const owner = config.owner || '<your-owner>';
+  const address = welcomeAddressFor(owner);
+  // Plain markdown — the browser UI renders the slice content directly.
+  // Keep it short, friendly, and oriented toward the three workflows we
+  // want non-technical users to discover next: skills, sharing, building.
+  return [
+    '# Welcome to BitPub',
+    '',
+    'Your install worked. **This page is your first saved memory** — a slice',
+    `at \`${address}\` that only you can read (it\'s end-to-end encrypted on`,
+    'your machine before it leaves your laptop).',
+    '',
+    '---',
+    '',
+    '## What just happened',
+    '',
+    '- A **private namespace** was provisioned in the cloud for you',
+    '  (`bitpub://private:' + owner + '/...`).',
+    '- A **local cache** was set up at `~/.bitpub/cache.db` so reads are',
+    '  instant and work offline.',
+    '- This memory was **saved and encrypted, then synced** — proof the round',
+    '  trip works. You\'re looking at it right now in the BitPub Browser.',
+    '',
+    '---',
+    '',
+    '## What to try next',
+    '',
+    'Pick one. Each one takes under a minute.',
+    '',
+    '### 1. Install a skill from the catalog',
+    '',
+    'Skills are reusable instructions for AI agents — like cloning a GitHub',
+    'repo, but one click and no folder structure to figure out. Your agent',
+    'picks up new skills automatically.',
+    '',
+    '> *Catalog UI coming soon. For now, see the README\'s "Packaging agents',
+    '> for your team" section for the manual flow.*',
+    '',
+    '### 2. Share with your team',
+    '',
+    'Generate a link teammates can click to join your group namespace and',
+    'read shared context. No GitHub invites, no repo access, no PRs.',
+    '',
+    '> *One-click sharing coming soon. Today: `bitpub auth login --domain',
+    '> yourcompany.com` joins an existing team namespace.*',
+    '',
+    '### 3. See what you can build',
+    '',
+    'BitPub is a file system for agents. Anything you\'d put in a folder you',
+    'can put here — research notes, prompts, drafts, agent configs, job',
+    'queues. Multiple agents can read and write the same slices.',
+    '',
+    '> Read the [Cookbook](https://github.com/tollbit/shared-memory-protocol/blob/main/COOKBOOK.md)',
+    '> for real patterns teams have built on top of these primitives.',
+    '',
+    '---',
+    '',
+    '## You don\'t need to interact with this UI',
+    '',
+    'The Browser is here so you can *see* what your agents are doing. The',
+    'real interface is your agent itself — Claude Code, Cursor, Codex, or',
+    'any MCP-compatible client. They\'ll read and write to BitPub on their',
+    'own. Close this tab whenever you\'re ready.',
+    '',
+  ].join('\n');
+}
+
+async function saveWelcomeSlice(config, { force } = {}) {
+  const cfg = readConfig() || {};
+  if (cfg.welcome_saved_at && !force) {
+    return { saved: false, address: welcomeAddressFor(config.owner), reason: 'already-saved' };
+  }
+
+  const address = welcomeAddressFor(config.owner);
+  const content = buildWelcomeContent(config);
+  const api = createApiClient(config);
+
+  const body = {
+    hcu: address,
+    metadata: {
+      author_id: authorIdFor(config),
+      timestamp: new Date().toISOString(),
+      tags: ['welcome', 'onboarding'],
+    },
+    payload: {
+      format: 'text/markdown',
+      content: encrypt(content, config.api_key),
+    },
+  };
+
+  const result = await api.push(body, {});
+  decryptSlices([result.slice], config.api_key);
+  upsertSlice(result.slice);
+
+  writeConfig({ ...cfg, welcome_saved_at: new Date().toISOString() });
+
+  return { saved: true, address, version: result.slice.metadata.version };
+}
+
+module.exports = function registerWelcome(program) {
+  program
+    .command('welcome')
+    .description('Save a first welcome memory and (with --serve) open the browser to view it')
+    .option('--serve', 'Start the local browser UI and open a tab to the welcome slice')
+    .option('--force', 'Re-save the welcome slice even if one was already saved on this machine')
+    .option('-p, --port <port>', 'Port to serve on when --serve is passed', '4141')
+    .option('--no-open', 'Do not auto-open the browser tab when --serve is passed')
+    .action(async (opts) => {
+      const config = requireConfig();
+
+      let saveResult;
+      try {
+        saveResult = await saveWelcomeSlice(config, { force: !!opts.force });
+      } catch (err) {
+        // Don't make a save failure fatal to the install — the user still
+        // has a working CLI. Surface it but keep going to --serve so they
+        // at least see the browser is up.
+        console.error(`(welcome: could not save first memory — ${err.message})`);
+        saveResult = { saved: false, address: welcomeAddressFor(config.owner), reason: 'error' };
+      }
+
+      if (saveResult.saved) {
+        console.log(`✓ Saved your first memory → ${saveResult.address}  (v${saveResult.version})`);
+      } else if (saveResult.reason === 'already-saved') {
+        console.log(`✓ Welcome memory already exists → ${saveResult.address}`);
+        console.log('  (Pass --force to overwrite it.)');
+      }
+
+      if (!opts.serve) {
+        console.log('\n  Next: open the browser to see it.');
+        console.log('    bitpub browser');
+        return;
+      }
+
+      try {
+        await startBrowserServer({
+          port: opts.port,
+          open: opts.open !== false,
+          path: '/?welcome=1',
+        });
+      } catch (err) {
+        console.error(err.message);
+        process.exit(1);
+      }
+    });
+};
+
+module.exports.saveWelcomeSlice = saveWelcomeSlice;
+module.exports.welcomeAddressFor = welcomeAddressFor;
+module.exports.buildWelcomeContent = buildWelcomeContent;