@bitpub/cli 2.0.0

package/src/aliases.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Aliases — short shortcuts for fully-qualified addresses that don't
+ * correspond to a folder on disk. Useful for stable logical addresses an
+ * agent uses across cwd's, sessions, and machines: task queues, inboxes,
+ * long-running memory areas, frequently-read group namespaces, etc.
+ *
+ * Stored as a flat key→address map at ~/.bitpub/aliases.json. Used
+ * everywhere a command accepts a name, scope, or pattern: a leading `@`
+ * triggers expansion.
+ *
+ *   bitpub alias set inbox bitpub://private:agent_xyz/Queues/inbox/
+ *   bitpub save  @inbox/task-001 "review billing parser"
+ *   bitpub list  @inbox
+ *   bitpub watch --address @inbox/**       (after expansion in CLI)
+ *
+ * Aliases compose with workspaces rather than replacing them: a workspace
+ * gives folder-anchored ergonomics for a project; aliases give cross-cwd
+ * shortcuts to fixed addresses.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ALIASES_FILE = path.join(os.homedir(), '.bitpub', 'aliases.json');
+const VALID_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+
+function readAliases() {
+  try {
+    const raw = fs.readFileSync(ALIASES_FILE, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeAliases(map) {
+  const dir = path.dirname(ALIASES_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(ALIASES_FILE, JSON.stringify(map, null, 2), { mode: 0o600 });
+}
+
+function setAlias(name, address) {
+  if (!VALID_NAME.test(name)) {
+    throw new Error(
+      `Invalid alias name "${name}". Use alphanumeric with - or _ (e.g. "inbox", "team-runbooks").`
+    );
+  }
+  if (typeof address !== 'string' || !address.startsWith('bitpub://')) {
+    throw new Error('Alias value must be a fully qualified address (bitpub://...).');
+  }
+  // Normalize to a trailing slash so `@name/x` and `@name` both work cleanly.
+  const normalized = address.endsWith('/') || address.endsWith('*') ? address : address + '/';
+  const map = readAliases();
+  map[name] = normalized;
+  writeAliases(map);
+  return normalized;
+}
+
+function removeAlias(name) {
+  const map = readAliases();
+  if (!(name in map)) return false;
+  delete map[name];
+  writeAliases(map);
+  return true;
+}
+
+function isAliasRef(input) {
+  return typeof input === 'string' && input.length > 1 && input[0] === '@';
+}
+
+/**
+ * Expand `@name` or `@name/<rest>` against the aliases map. Throws if the
+ * named alias is not defined. Caller is responsible for using `isAliasRef`
+ * first if pass-through behavior is desired.
+ */
+function expandAlias(input) {
+  if (!isAliasRef(input)) {
+    throw new Error(`Not an alias reference: ${input}`);
+  }
+  const slash = input.indexOf('/');
+  const name = slash === -1 ? input.slice(1) : input.slice(1, slash);
+  const rest = slash === -1 ? '' : input.slice(slash + 1);
+
+  const map = readAliases();
+  if (!(name in map)) {
+    throw new Error(
+      `Unknown alias "@${name}". Define it with: bitpub alias set ${name} <bitpub://...> ` +
+      '(or list existing aliases: bitpub alias list)'
+    );
+  }
+  return map[name] + rest;
+}
+
+/**
+ * Convenience: pass-through unless the input is an alias reference.
+ * Useful at command entry points where the caller may pass a fully-qualified
+ * HCU, a short name, or an `@alias`.
+ */
+function maybeExpand(input) {
+  return isAliasRef(input) ? expandAlias(input) : input;
+}
+
+module.exports = {
+  ALIASES_FILE,
+  readAliases,
+  writeAliases,
+  setAlias,
+  removeAlias,
+  isAliasRef,
+  expandAlias,
+  maybeExpand,
+};

package/src/api.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const axios = require('axios');
+
+/**
+ * Create an API client bound to a specific config.
+ * All methods throw on non-2xx responses (axios default behavior).
+ */
+/**
+ * Pick the right API key for a given HCU.
+ * Private namespaces use the personal api_key provisioned by `bitpub init`.
+ * Group/public namespaces use group_key set by `bitpub auth login`, falling
+ * back to api_key so single-key setups keep working.
+ */
+function keyForHcu(config, hcu) {
+  if (typeof hcu === 'string' && hcu.startsWith('bitpub://private:')) {
+    return config.api_key;
+  }
+  return config.group_key || config.api_key;
+}
+
+function createApiClient(config) {
+  const baseURL = (config.api_url || 'http://localhost:8080').replace(/\/$/, '');
+
+  const http = axios.create({
+    baseURL,
+    timeout: 30_000,
+  });
+
+  // Surface server-side error messages cleanly, preserving response for callers
+  http.interceptors.response.use(
+    res => res,
+    err => {
+      const msg = err.response?.data?.error || err.message;
+      const status = err.response?.status;
+      const wrapped = new Error(status ? `[${status}] ${msg}` : msg);
+      wrapped.status = status;
+      wrapped.response = err.response;
+      return Promise.reject(wrapped);
+    }
+  );
+
+  return {
+    /**
+     * Pull context slices from the remote ledger.
+     * @param {string} hcu
+     * @param {number} [limit]
+     * @param {object} [opts]
+     * @param {boolean} [opts.includeDeleted]  surface tombstoned slices
+     * @param {boolean} [opts.mine]            filter to slices written by this key
+     * @returns {Promise<Array>} array of slice DTOs
+     */
+    async pull(hcu, limit = 50, opts = {}) {
+      const params = { hcu, limit };
+      if (opts.includeDeleted) params.include_deleted = 'true';
+      if (opts.mine) params.mine = 'true';
+      const res = await http.get('/v1/context/pull', {
+        params,
+        headers: { 'x-api-key': keyForHcu(config, hcu) },
+      });
+      return res.data;
+    },
+
+    /**
+     * Push a context slice to the remote ledger.
+     * @param {object} body  Full ContextSlice payload
+     * @param {object} [opts]
+     * @param {boolean} [opts.append]    append instead of overwrite
+     * @param {number}  [opts.expectVersion]  reject with 409 on version mismatch
+     * @param {boolean} [opts.force]     un-tombstone a deleted slice with new content
+     * @returns {Promise<{success: boolean, slice: object}>}
+     */
+    async push(body, opts = {}) {
+      // Back-compat: older callers passed (body, append, expectVersion) as
+      // positional args. Detect that shape and translate to the opts object.
+      if (typeof opts === 'boolean' || typeof opts === 'number') {
+        opts = { append: !!opts, expectVersion: arguments[2] };
+      }
+      const { append, expectVersion, force } = opts;
+      const params = {};
+      if (append) params.append = 'true';
+      if (force) params.force = 'true';
+      if (expectVersion != null) params.expect_version = String(expectVersion);
+      const res = await http.post('/v1/context/push', body, {
+        params,
+        headers: { 'x-api-key': keyForHcu(config, body?.hcu) },
+      });
+      return res.data;
+    },
+
+    /**
+     * List immediate children of an HCU path.
+     * @param {string} hcu
+     * @param {object} [opts]
+     * @param {boolean} [opts.includeDeleted]  return tombstone provenance
+     * @returns {Promise<{children: string[] | Array<{hcu: string, deleted_at: string|null, deleted_by: string|null}>}>}
+     */
+    async list(hcu, opts = {}) {
+      const params = { hcu };
+      if (opts.includeDeleted) params.include_deleted = 'true';
+      const res = await http.get('/v1/context/list', {
+        params,
+        headers: { 'x-api-key': keyForHcu(config, hcu) },
+      });
+      return res.data;
+    },
+
+    /**
+     * Soft-delete an exact context slice. Bumps version (active(N) →
+     * deleted(N+1)). The server preserves the row's payload so a no-content
+     * restore can undelete it. Re-dropping an already-tombstoned slice is
+     * idempotent.
+     */
+    async drop(hcu, opts = {}) {
+      const params = { hcu };
+      if (opts.expectVersion != null) params.expect_version = String(opts.expectVersion);
+      const res = await http.delete('/v1/context/drop', {
+        params,
+        headers: { 'x-api-key': keyForHcu(config, hcu) },
+      });
+      return res.data;
+    },
+
+    /**
+     * Restore a tombstoned slice in place using the server's preserved
+     * payload. Bumps version (deleted(N) → active(N+1)). Returns 409 if
+     * the slice is already active; 404 if it never existed.
+     */
+    async restore(hcu, opts = {}) {
+      const params = { hcu };
+      if (opts.expectVersion != null) params.expect_version = String(opts.expectVersion);
+      const res = await http.post('/v1/context/restore', null, {
+        params,
+        headers: { 'x-api-key': keyForHcu(config, hcu) },
+      });
+      return res.data;
+    },
+
+    /**
+     * Open an SSE heartbeat stream and invoke onSync(evt) for each sync event.
+     * Each `evt` is a `{ hcu, deleted? }` object — the optional `deleted: true`
+     * hint tells callers the slice was tombstoned (so they can evict from
+     * any local cache without a refetch).
+     *
+     * For backward compatibility with any caller that expected just an HCU
+     * string, the `evt` argument is documented as the new shape and callers
+     * should detect `evt.deleted` to short-circuit refetch.
+     *
+     * Returns a cleanup function that closes the connection.
+     */
+    watch(hcuPattern, onSync, onError) {
+      const EventSource = require('eventsource');
+      const url = `${baseURL}/v1/context/heartbeat?hcu_pattern=${encodeURIComponent(hcuPattern)}`;
+
+      const es = new EventSource(url, {
+        headers: { 'x-api-key': keyForHcu(config, hcuPattern) },
+      });
+
+      es.addEventListener('sync', (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          onSync(data);
+        } catch {
+          // Malformed event — ignore
+        }
+      });
+
+      es.onerror = (err) => {
+        if (onError) onError(err);
+      };
+
+      return () => es.close();
+    },
+  };
+}
+
+module.exports = { createApiClient };

package/src/commands/alias.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * `bitpub alias` — manage shortcuts for fully-qualified addresses.
+ *
+ *   bitpub alias set inbox bitpub://private:agent_xyz/Queues/inbox/
+ *   bitpub alias list
+ *   bitpub alias show inbox
+ *   bitpub alias rm inbox
+ *
+ * Aliases are referenced everywhere a name/scope/pattern is accepted by
+ * prefixing with `@`:
+ *
+ *   bitpub save @inbox/task-001 "..."
+ *   bitpub list @inbox
+ *   bitpub grep "todo" --scope @inbox
+ */
+
+const { readAliases, setAlias, removeAlias, ALIASES_FILE } = require('../aliases');
+
+module.exports = function registerAlias(program) {
+  const alias = program
+    .command('alias')
+    .description('Manage @-aliases for fully-qualified addresses (queues, inboxes, fixed locations)');
+
+  alias
+    .command('set <name> <address>')
+    .description('Create or update an alias (e.g. `alias set inbox bitpub://private:.../Queues/inbox/`)')
+    .action((name, address) => {
+      try {
+        const normalized = setAlias(name, address);
+        console.log(`✓ @${name} → ${normalized}`);
+      } catch (err) {
+        console.error(err.message);
+        process.exit(1);
+      }
+    });
+
+  alias
+    .command('list')
+    .description('List all defined aliases')
+    .action(() => {
+      const map = readAliases();
+      const keys = Object.keys(map).sort();
+      if (keys.length === 0) {
+        console.log('No aliases defined.');
+        console.log('');
+        console.log('Examples:');
+        console.log('  bitpub alias set inbox  bitpub://private:<owner>/Queues/inbox/');
+        console.log('  bitpub alias set memory bitpub://private:<owner>/Memory/');
+        return;
+      }
+      console.log(`File: ${ALIASES_FILE}\n`);
+      const width = Math.max(...keys.map(k => k.length));
+      for (const k of keys) {
+        console.log(`  @${k.padEnd(width)}  ${map[k]}`);
+      }
+    });
+
+  alias
+    .command('show <name>')
+    .description('Print the fully-qualified address that an alias resolves to')
+    .action((name) => {
+      const map = readAliases();
+      if (!(name in map)) {
+        console.error(`Unknown alias: @${name}`);
+        process.exit(1);
+      }
+      console.log(map[name]);
+    });
+
+  alias
+    .command('rm <name>')
+    .description('Remove an alias')
+    .action((name) => {
+      const ok = removeAlias(name);
+      console.log(ok ? `✓ Removed @${name}` : `(@${name} not found)`);
+    });
+};

package/src/commands/auth.js

@@ -0,0 +1,50 @@
+'use strict';
+
+/**
+ * `bitpub auth login` — DEPRECATED ALIAS. Use `bitpub setup team` instead.
+ *
+ * Persists group credentials (key + domain + url) without touching the
+ * private identity. Forwards to the same writeConfig path setup uses;
+ * hidden from --help.
+ */
+
+const { readConfig, writeConfig } = require('../config');
+const { initCache } = require('../db/cache');
+const { createApiClient } = require('../api');
+
+module.exports = function registerAuth(program) {
+  const auth = program
+    .command('auth', { hidden: true })
+    .description('[deprecated] Use `bitpub setup team` instead');
+
+  auth
+    .command('login')
+    .description('[deprecated] Use `bitpub setup team` instead')
+    .requiredOption('--key <string>', 'Group API key provided by your team admin')
+    .requiredOption('--domain <string>', 'Your organization domain (e.g. acme.com)')
+    .option('--url <string>', 'Backend URL', 'http://localhost:8080')
+    .option('--verify', 'Ping the backend to verify the key before saving')
+    .action(async ({ key, domain, url, verify }) => {
+      console.error('warning: `bitpub auth login` is deprecated. Use `bitpub setup team` instead.');
+      if (verify) {
+        try {
+          const api = createApiClient({ group_key: key, api_url: url });
+          await api.pull(`bitpub://group:${domain}/**`, 1);
+          console.log('✓ Key verified against backend');
+        } catch (err) {
+          console.error(`Key verification failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+      const existing = readConfig() || {};
+      writeConfig({ ...existing, group_key: key, domain, api_url: url });
+      initCache();
+      console.log(`Authenticated.`);
+      console.log(`  Domain : ${domain}`);
+      console.log(`  Backend: ${url}`);
+      if (existing.owner) {
+        console.log(`  Private: agent_${existing.owner} (preserved)`);
+      }
+      console.log(`\nNext: bitpub sync "bitpub://group:${domain}/**"`);
+    });
+};

package/src/commands/browser.js

@@ -0,0 +1,196 @@
+'use strict';
+
+/**
+ * `bitpub browser` — open the visual context explorer in your browser.
+ *
+ * Formerly `bitpub console`. The old command name is still registered as a
+ * hidden alias so existing scripts keep working; new docs and prompts use
+ * `browser` because it matches what the user actually sees (a browser tab
+ * with a UI).
+ *
+ * The serve loop is also exported as `startBrowserServer()` so other
+ * commands (notably `bitpub welcome --serve`) can launch the same UI without
+ * duplicating the http plumbing.
+ */
+
+const http = require('http');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { exec } = require('child_process');
+const { readConfig, BITPUB_DIR } = require('../config');
+const { getSyncedNamespaces, initCache } = require('../db/cache');
+const { isPrivateHcu, decrypt, isEncrypted } = require('../crypto');
+
+const Database = require('better-sqlite3');
+const DB_PATH = path.join(os.homedir(), '.bitpub', 'cache.db');
+
+function getAllSlices() {
+  if (!fs.existsSync(DB_PATH)) return [];
+  const db = new Database(DB_PATH);
+  const rows = db.prepare('SELECT * FROM local_slices ORDER BY last_synced DESC').all();
+  db.close();
+  return rows;
+}
+
+function decryptSlice(slice, apiKey) {
+  if (!isPrivateHcu(slice.hcu) || !apiKey) return slice;
+  try {
+    const payload = typeof slice.payload === 'string' ? JSON.parse(slice.payload) : slice.payload;
+    if (isEncrypted(payload.content)) {
+      payload.content = decrypt(payload.content, apiKey);
+      return { ...slice, payload: typeof slice.payload === 'string' ? JSON.stringify(payload) : payload };
+    }
+  } catch { /* decryption failure — return as-is */ }
+  return slice;
+}
+
+function resolveBrowserHtmlPath() {
+  // Order matters. We want production installs to always serve the HTML
+  // that ships with the *current* CLI version, not whatever got cached in
+  // ~/.bitpub/ from a one-time tarball install months ago.
+  //
+  //   1. cli/static/console.html — populated by `prepack` from the
+  //      workspace `backend/static/console.html` and shipped inside the
+  //      CLI tarball. This is the canonical location at runtime.
+  //   2. backend/static/console.html — only resolves when running from a
+  //      checked-out workspace (e.g., `node cli/bin/bitpub.js browser`
+  //      during development). Convenient but not the real install path.
+  //   3. ~/.bitpub/console.html — last-resort cache, mainly for the
+  //      original install instructions that fetched a single file via curl.
+  //      We never write here ourselves; it exists only when a user
+  //      manually populated it.
+  //
+  // Filename is still console.html on disk — keeping the filename stable
+  // avoids churning the prepack step and lets old `~/.bitpub/console.html`
+  // caches keep working. The user-facing command is `browser`.
+  const candidates = [
+    path.join(__dirname, '../../static/console.html'),
+    path.join(__dirname, '../../../backend/static/console.html'),
+    path.join(BITPUB_DIR, 'console.html'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+function openInBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open' :
+    process.platform === 'win32' ? 'start' : 'xdg-open';
+  exec(`${cmd} ${url}`);
+}
+
+/**
+ * Start the browser server and (optionally) open a tab. Returns a Promise
+ * that resolves with `{ server, url }` once listening, or rejects on error.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.port=4141]   Port to bind. Falls back to next free port.
+ * @param {boolean} [opts.open=true]  Whether to launch the OS browser.
+ * @param {string}  [opts.path='/']   Initial path/query (e.g. '/?welcome=1').
+ * @param {boolean} [opts.quiet=false] Suppress the welcome banner on stdout.
+ */
+function startBrowserServer(opts = {}) {
+  const port = parseInt(opts.port, 10) || 4141;
+  const shouldOpen = opts.open !== false;
+  const initialPath = opts.path || '/';
+  const quiet = !!opts.quiet;
+
+  return new Promise((resolve, reject) => {
+    initCache();
+    const cfg = readConfig();
+
+    const htmlPath = resolveBrowserHtmlPath();
+    if (!htmlPath) {
+      const err = new Error(
+        `Browser UI not found. If you installed from a tarball, run:\n` +
+        `  curl -sS "${(cfg && cfg.api_url) || 'https://<your-server>'}/console" -o ~/.bitpub/console.html`
+      );
+      return reject(err);
+    }
+
+    const htmlTemplate = fs.readFileSync(htmlPath, 'utf-8');
+
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost:${port}`);
+
+      if (url.pathname === '/api/data') {
+        res.setHeader('Content-Type', 'application/json');
+        const slices = getAllSlices().map(s => {
+          if (cfg && cfg.api_key) return decryptSlice(s, cfg.api_key);
+          return s;
+        });
+        res.end(JSON.stringify({
+          mode: 'local',
+          domain: (cfg && cfg.domain) || '',
+          slices,
+          synced_namespaces: getSyncedNamespaces(),
+        }));
+        return;
+      }
+
+      if (url.pathname === '/' || url.pathname === '/index.html') {
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.end(htmlTemplate);
+        return;
+      }
+
+      res.statusCode = 404;
+      res.end('Not found');
+    });
+
+    server.listen(port, () => {
+      const baseUrl = `http://localhost:${port}`;
+      const fullUrl = baseUrl + (initialPath.startsWith('/') ? initialPath : '/' + initialPath);
+      if (!quiet) {
+        console.log(`\n  BitPub Browser\n`);
+        console.log(`  Local:  ${baseUrl}`);
+        if (cfg && cfg.domain) console.log(`  Domain: ${cfg.domain}`);
+        console.log(`\n  Press Ctrl+C to stop.\n`);
+      }
+      if (shouldOpen) openInBrowser(fullUrl);
+      resolve({ server, url: fullUrl });
+    });
+
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        err.message = `Port ${port} is in use. Try: bitpub browser --port ${port + 1}`;
+      }
+      reject(err);
+    });
+  });
+}
+
+function registerCommand(program, name, opts = {}) {
+  const cmd = program
+    .command(name)
+    .description(opts.description || 'Open the visual context explorer in your browser')
+    .option('-p, --port <port>', 'Port to serve on', '4141')
+    .option('--no-open', 'Do not auto-open browser')
+    .action(async (cliOpts) => {
+      if (opts.deprecated) {
+        console.error(`(note: 'bitpub ${name}' is deprecated; use 'bitpub browser')`);
+      }
+      try {
+        await startBrowserServer({
+          port: cliOpts.port,
+          open: cliOpts.open !== false,
+        });
+      } catch (err) {
+        console.error(err.message);
+        process.exit(1);
+      }
+    });
+  return cmd;
+}
+
+module.exports = function (program) {
+  registerCommand(program, 'browser');
+  // Backward-compat: the command was previously called `console`. Keep it
+  // working so existing scripts and muscle-memory don't break, but log a
+  // one-line deprecation hint when used.
+  registerCommand(program, 'console', { deprecated: true });
+};
+
+module.exports.startBrowserServer = startBrowserServer;