@bitpub/cli 2.0.0

package/src/commands/setup.js

@@ -0,0 +1,312 @@
+'use strict';
+
+/**
+ * `bitpub setup` — first-time install + identity provision + skill registration.
+ *
+ * One verb, three jobs. Idempotent — re-running is always safe and skips
+ * any step that's already done. Most agents won't call this directly:
+ * the first `bitpub save` from a non-$HOME folder runs setup lazily for
+ * any user that doesn't have an identity yet (see save.js for the
+ * autosetup hook).
+ *
+ * Subcommands for the rare cases where explicit control matters:
+ *
+ *   bitpub setup                  → identity + project anchor + skill install
+ *   bitpub setup team             → join a team (key + domain, today; invite token, later)
+ *   bitpub setup skill install    → register the BitPub skill into Claude/Cursor/Codex
+ *   bitpub setup skill list       → show where the skill is installed
+ *
+ * The original `init`, `auth login`, and `skills install` verbs are kept
+ * as hidden, deprecation-warning aliases so existing scripts keep working.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const axios = require('axios');
+const {
+  readConfig,
+  writeConfig,
+  isConfigured,
+  DEFAULT_CLOUD_URL,
+} = require('../config');
+const { initCache } = require('../db/cache');
+const { createWorkspace, findWorkspace } = require('../workspace');
+const { injectAgentsMd } = require('../agents-md');
+const { installSkills, listSkillStatus } = require('./skills');
+const { createApiClient } = require('../api');
+
+const LEGACY_CONFIG_DIR = path.join(os.homedir(), '.tollbit');
+const LEGACY_CONFIG_FILE = path.join(LEGACY_CONFIG_DIR, 'config.json');
+const LEGACY_ALIASES_FILE = path.join(LEGACY_CONFIG_DIR, 'aliases.json');
+
+/**
+ * Ensure the local store + a private cloud identity exist. Used both by
+ * `bitpub setup` directly and by save.js as a lazy bootstrap. Pass
+ * `quiet: true` from inside another command to suppress the ascii output
+ * (callers will report success themselves).
+ *
+ * Returns the resulting config (after any provisioning), or null if it
+ * couldn't provision and `localOnly` was passed.
+ */
+async function ensureIdentity({ url = DEFAULT_CLOUD_URL, force = false, localOnly = false, quiet = false } = {}) {
+  url = url.replace(/\/$/, '');
+  initCache();
+
+  // Legacy ~/.tollbit/ import — preserves continuity for anyone who
+  // installed before the BitPub rename. Silent on success unless quiet=false.
+  const importedFromLegacy = maybeImportLegacyConfig({ quiet });
+
+  const existing = readConfig();
+  const alreadyHasIdentity = isConfigured(existing) && !force;
+
+  if (alreadyHasIdentity) return existing;
+
+  if (localOnly) {
+    if (!quiet) console.log('(--local-only: skipping cloud provisioning.)');
+    return null;
+  }
+
+  if (!quiet) console.log(`Provisioning identity against ${url}…`);
+
+  let resp;
+  try {
+    resp = await axios.post(
+      `${url}/v1/identity/provision`,
+      {},
+      { timeout: 15_000, headers: { 'content-type': 'application/json' } }
+    );
+  } catch (err) {
+    const status = err.response?.status;
+    const detail = err.response?.data?.error || err.message || err.code || 'unknown error';
+    if (status === 503) {
+      throw new Error(`${url} doesn't support self-service identity. Use: bitpub setup team --key <K> --domain <D>`);
+    } else if (status === 429) {
+      throw new Error(`Rate limit at ${url}. Try again later.`);
+    } else if (!err.response) {
+      throw new Error(`Could not reach ${url} (${err.code || detail}).`);
+    }
+    throw new Error(`Provisioning failed: ${detail}`);
+  }
+
+  const { api_key, owner_id, namespace, tier, storage_cap_bytes, writes_per_day } = resp.data;
+  writeConfig({
+    api_key,
+    owner: owner_id,
+    api_url: url,
+    tier,
+    provisioned_at: new Date().toISOString(),
+  });
+
+  if (!quiet) {
+    const capMb = Math.round((storage_cap_bytes || 0) / (1024 * 1024));
+    console.log('✓ Cloud identity provisioned\n');
+    console.log(`  Owner     : ${owner_id}`);
+    console.log(`  Namespace : ${namespace}`);
+    console.log(`  Tier      : ${tier}`);
+    console.log(`  Storage   : 0 / ${capMb} MB`);
+    if (writes_per_day) console.log(`  Writes    : 0 / ${writes_per_day} per day`);
+    console.log(`  Backend   : ${url}`);
+  }
+
+  return readConfig();
+}
+
+/**
+ * Make sure this folder has a project anchor. Returns the anchor (new
+ * or existing), or null if we're in $HOME (where we refuse to anchor)
+ * or `owner` is missing.
+ *
+ * `quiet: true` is the common case — `bitpub save` calls this with
+ * `quiet: true` so the first save in a new folder is indistinguishable
+ * from the hundredth. `bitpub setup` calls it with `quiet: false` to
+ * report what just happened in human terms.
+ */
+function ensureWorkspace({ owner, cwd = process.cwd(), label, quiet = false } = {}) {
+  if (!owner) return null;
+  const home = path.resolve(os.homedir());
+  if (path.resolve(cwd) === home) {
+    if (!quiet) {
+      console.log('(Skipping project anchor — you\'re in $HOME. Run setup inside a project folder to anchor here.)');
+    }
+    return null;
+  }
+
+  const existing = findWorkspace(cwd);
+  if (existing) {
+    if (!quiet) {
+      console.log(`✓ This folder is already a project: ${existing.marker.label || existing.marker.id}`);
+      console.log(`  Address : ${existing.marker.namespace}`);
+    }
+    injectAgentsMd(cwd, { quiet: true });
+    return existing;
+  }
+
+  try {
+    const ws = createWorkspace(cwd, owner, { label });
+    if (!quiet) {
+      console.log('✓ Anchored this folder as a project');
+      console.log(`  Label   : ${ws.marker.label}`);
+      console.log(`  Address : ${ws.marker.namespace}`);
+    }
+    injectAgentsMd(cwd, { quiet });
+    return ws;
+  } catch (err) {
+    if (!quiet) console.error(`(Could not anchor folder: ${err.message})`);
+    return null;
+  }
+}
+
+async function ensureSkill({ quiet = false } = {}) {
+  try {
+    const { installed } = await installSkills({});
+    if (installed > 0 && !quiet) {
+      console.log('\n✓ BitPub skill installed into agent directories');
+      console.log('  Quit Claude Code and reopen it to pick up the new skill.');
+    }
+  } catch (err) {
+    if (!quiet) console.log(`\n(Skill install skipped: ${err.message} — run 'bitpub setup skill install' to retry)`);
+  }
+}
+
+module.exports = function registerSetup(program) {
+  const setup = program
+    .command('setup')
+    .description('First-time install + identity provision + skill registration. Idempotent.')
+    .option('--url <string>', 'Cloud tenant URL', DEFAULT_CLOUD_URL)
+    .option('--local-only', 'Set up the local store only; skip cloud provisioning')
+    .option('--no-anchor', 'Skip anchoring this folder as a project')
+    .option('--label <string>', 'Override the project label (defaults to folder name)')
+    .option('--force', 'Overwrite an existing identity (the old key is unrecoverable after this)')
+    .option('--import-from <path>', 'Import an existing TollBit config (defaults to ~/.tollbit/config.json if present)')
+    .option('--no-import', 'Skip auto-import even if a legacy ~/.tollbit/ config is present')
+    .action(async (opts) => {
+      try {
+        const config = await ensureIdentity({
+          url: opts.url,
+          force: !!opts.force,
+          localOnly: !!opts.localOnly,
+        });
+        if (config && opts.anchor !== false) {
+          ensureWorkspace({ owner: config.owner, label: opts.label });
+        }
+        await ensureSkill({});
+        console.log('\nTry it:');
+        console.log('  bitpub save notes "first slice"');
+        console.log('  bitpub list                       # see what\'s in this project');
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // ── setup team … ────────────────────────────────────────────────────
+  // Joins (or rejoins) a team namespace. Today: requires --key + --domain
+  // from a team admin. Future: --invite <token> in lieu of those, once
+  // server-side invite generation lands.
+  setup
+    .command('team')
+    .description('Join a team namespace (key + domain from your team admin)')
+    .requiredOption('--key <string>', 'Team API key provided by your team admin')
+    .requiredOption('--domain <string>', 'Your organization domain (e.g. acme.com)')
+    .option('--url <string>', 'Backend URL (defaults to current api_url or https://bitpub.io)')
+    .option('--verify', 'Ping the backend to verify the key before saving')
+    .action(async ({ key, domain, url, verify }) => {
+      const existing = readConfig() || {};
+      const apiUrl = url || existing.api_url || DEFAULT_CLOUD_URL;
+
+      if (verify) {
+        try {
+          const api = createApiClient({ group_key: key, api_url: apiUrl });
+          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);
+        }
+      }
+
+      writeConfig({ ...existing, group_key: key, domain, api_url: apiUrl });
+      initCache();
+
+      console.log(`✓ Joined team ${domain}`);
+      console.log(`  Backend : ${apiUrl}`);
+      if (existing.owner) {
+        console.log(`  Private : agent_${existing.owner} (preserved)`);
+      }
+      console.log('\nNext: bitpub sync "bitpub://group:' + domain + '/**"');
+    });
+
+  // ── setup skill {install|list} ──────────────────────────────────────
+  const skill = setup.command('skill').description('Manage agent skill installation');
+
+  skill
+    .command('install')
+    .description('Install the BitPub skill into every detected agent directory (Claude, Cursor, Codex)')
+    .option('--target <name>', 'Install only into a single named target (claude|cursor|codex|project|agents-md)')
+    .option('--all', 'Install everywhere, creating directories that do not yet exist')
+    .option('--dry-run', 'Print what would be installed without writing files')
+    .option('--no-agents-md', 'Skip AGENTS.md injection in the current project')
+    .action(async (opts) => {
+      const { installed, skipped } = await installSkills(opts);
+      console.log('');
+      console.log(`Done. ${installed} installed/updated, ${skipped} skipped.`);
+      if (installed > 0) {
+        console.log('Quit Claude Code and reopen it to pick up the new skill — starting a new chat is not enough.');
+      }
+    });
+
+  skill
+    .command('list')
+    .description('Show where the BitPub skill is currently installed')
+    .action(listSkillStatus);
+};
+
+// ── Legacy ~/.tollbit/ import (kept verbatim from original init.js) ────
+function maybeImportLegacyConfig({ quiet = false } = {}) {
+  const sourcePath = LEGACY_CONFIG_FILE;
+  if (!fs.existsSync(sourcePath)) return false;
+  if (isConfigured(readConfig())) return false;
+
+  let legacy;
+  try {
+    legacy = JSON.parse(fs.readFileSync(sourcePath, 'utf-8'));
+  } catch (err) {
+    if (!quiet) console.error(`\n(Could not parse ${sourcePath}: ${err.message} — skipping import)`);
+    return false;
+  }
+
+  const migrated = { ...legacy };
+  if (typeof migrated.api_url === 'string') {
+    migrated.api_url = migrated.api_url
+      .replace(/^https?:\/\/tollbit\.org/, 'https://bitpub.io')
+      .replace(/^https?:\/\/tollbit\.com/, 'https://bitpub.io');
+  }
+  migrated.imported_from = sourcePath;
+  migrated.imported_at = new Date().toISOString();
+  writeConfig(migrated);
+
+  try {
+    if (fs.existsSync(LEGACY_ALIASES_FILE)) {
+      const newAliasesPath = path.join(os.homedir(), '.bitpub', 'aliases.json');
+      if (!fs.existsSync(newAliasesPath)) {
+        const raw = fs.readFileSync(LEGACY_ALIASES_FILE, 'utf-8');
+        const rewritten = raw.replace(/tollbit:\/\//g, 'bitpub://');
+        fs.writeFileSync(newAliasesPath, rewritten);
+      }
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  if (!quiet) {
+    console.log(`✓ Imported existing identity from ${sourcePath}`);
+    if (migrated.owner) console.log(`  Owner   : ${migrated.owner}`);
+    if (migrated.domain) console.log(`  Domain  : ${migrated.domain}`);
+  }
+  return true;
+}
+
+module.exports.ensureIdentity = ensureIdentity;
+module.exports.ensureWorkspace = ensureWorkspace;
+module.exports.ensureSkill = ensureSkill;

package/src/commands/skills.js

@@ -0,0 +1,304 @@
+'use strict';
+
+/**
+ * `bitpub skills install` — distribute the BitPub skill into every
+ * place the agent on this machine knows to look.
+ *
+ * Distribution beats hope: most agents won't go discover a skill from a URL
+ * unless someone tells them about it. By dropping the skill into the
+ * well-known agent directories (Claude Code, Cursor, Codex, etc.) plus
+ * AGENTS.md in the current project, we guarantee the agent's first
+ * filesystem reconnaissance finds it.
+ *
+ * Targets (each detected and offered independently):
+ *   1. ~/.claude/skills/bitpub/SKILL.md          (Claude Code, user-level)
+ *   2. ~/.cursor/skills-cursor/bitpub/SKILL.md   (Cursor, user-level)
+ *   3. ~/.codex/skills/bitpub/SKILL.md           (Codex, user-level)
+ *   4. <cwd>/.claude/skills/bitpub/SKILL.md      (Claude Code, project-level — only if the dir already exists)
+ *   5. <cwd>/AGENTS.md                                (cross-agent convention; section appended/updated)
+ *
+ * Skill content is fetched from <api_url>/skill.md when an identity is
+ * configured, falling back to a bundled copy at cli/skills/bitpub/SKILL.md.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const axios = require('axios');
+const { readConfig, DEFAULT_CLOUD_URL } = require('../config');
+const { findWorkspace } = require('../workspace');
+const { injectAgentsMd } = require('../agents-md');
+
+const SKILL_NAME = 'bitpub';
+const SKILL_FILENAME = 'SKILL.md';
+
+module.exports = function registerSkills(program) {
+  // The top-level `bitpub skills …` command tree is now a deprecated
+  // alias — the canonical entry point is `bitpub setup skill …`.
+  // We keep both wired so existing scripts and shell aliases keep
+  // working; the deprecation hint prints when the legacy path is used.
+  const skills = program
+    .command('skills', { hidden: true })
+    .description('[deprecated] Use `bitpub setup skill` instead');
+
+  skills
+    .command('install')
+    .option('--target <name>', 'Install only into a single named target (claude|cursor|codex|project|agents-md)')
+    .option('--all', 'Install everywhere, creating directories that do not yet exist')
+    .option('--dry-run', 'Print what would be installed without writing files')
+    .option('--no-agents-md', 'Skip AGENTS.md injection in the current project')
+    .action(async (opts) => {
+      console.error('warning: `bitpub skills install` is deprecated. Use `bitpub setup skill install` instead.');
+      const { installed, skipped } = await installSkills(opts);
+      console.log('');
+      console.log(`Done. ${installed} installed/updated, ${skipped} skipped.`);
+      if (installed > 0) {
+        console.log('Quit Claude Code and reopen it to pick up the new skill — starting a new chat is not enough.');
+      }
+    });
+
+  skills
+    .command('list')
+    .action(() => {
+      console.error('warning: `bitpub skills list` is deprecated. Use `bitpub setup skill list` instead.');
+      listSkillStatus();
+    });
+};
+
+/**
+ * Print the install status for each known agent skill target. Used by
+ * the legacy `bitpub skills list` command and the new `bitpub setup
+ * skill list`. No arguments — always considers all targets.
+ */
+function listSkillStatus() {
+  const targets = enumerateTargets({ all: true });
+  console.log('BitPub skill installation status:\n');
+  for (const t of targets) {
+    const exists = fs.existsSync(t.targetPath);
+    const flag = exists ? '✓' : ' ';
+    console.log(`  [${flag}] ${t.label.padEnd(28)} ${t.targetPath}`);
+  }
+}
+
+// ── Target enumeration ──────────────────────────────────────────────────────
+
+function enumerateTargets(opts) {
+  const home = os.homedir();
+  const cwd = process.cwd();
+
+  const candidates = [
+    {
+      name: 'claude',
+      label: 'Claude Code (user)',
+      parentDir: path.join(home, '.claude', 'skills'),
+      targetPath: path.join(home, '.claude', 'skills', SKILL_NAME, SKILL_FILENAME),
+      kind: 'skill-file',
+    },
+    {
+      name: 'cursor',
+      label: 'Cursor (user)',
+      parentDir: path.join(home, '.cursor', 'skills-cursor'),
+      targetPath: path.join(home, '.cursor', 'skills-cursor', SKILL_NAME, SKILL_FILENAME),
+      kind: 'skill-file',
+    },
+    {
+      name: 'codex',
+      label: 'Codex (user)',
+      parentDir: path.join(home, '.codex', 'skills'),
+      targetPath: path.join(home, '.codex', 'skills', SKILL_NAME, SKILL_FILENAME),
+      kind: 'skill-file',
+    },
+    {
+      name: 'project',
+      label: 'Project .claude/skills',
+      parentDir: path.join(cwd, '.claude', 'skills'),
+      targetPath: path.join(cwd, '.claude', 'skills', SKILL_NAME, SKILL_FILENAME),
+      kind: 'skill-file',
+      // Only auto-install at project level if the dir already exists.
+      requiresExistingParent: true,
+    },
+  ];
+
+  // AGENTS.md injection — only when we're inside a workspace (or in the cwd
+  // anyway with --all). It's an append-not-overwrite operation, so safer.
+  const ws = findWorkspace(cwd);
+  if (opts.agentsMd !== false && (ws || opts.all)) {
+    candidates.push({
+      name: 'agents-md',
+      label: 'AGENTS.md (project)',
+      parentDir: cwd,
+      targetPath: path.join(cwd, 'AGENTS.md'),
+      kind: 'agents-md-section',
+    });
+  }
+
+  return candidates;
+}
+
+// ── Per-target handling ─────────────────────────────────────────────────────
+
+function handleTarget(target, skillBody, opts) {
+  if (target.kind === 'skill-file') {
+    return handleSkillFile(target, skillBody, opts);
+  }
+  if (target.kind === 'agents-md-section') {
+    return handleAgentsMd(target, opts);
+  }
+  return 'skipped';
+}
+
+function handleSkillFile(target, skillBody, opts) {
+  const parentExists = fs.existsSync(target.parentDir);
+  const shouldCreateParent = opts.all || !target.requiresExistingParent;
+
+  if (!parentExists && !shouldCreateParent) {
+    console.log(`  ⊘ ${target.label} — directory not present (${target.parentDir})`);
+    return 'skipped';
+  }
+
+  const targetDir = path.dirname(target.targetPath);
+
+  if (opts.dryRun) {
+    console.log(`  → would write ${target.targetPath}`);
+    return 'installed';
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  const existed = fs.existsSync(target.targetPath);
+  fs.writeFileSync(target.targetPath, skillBody);
+  console.log(`  ${existed ? '↻' : '✓'} ${target.label.padEnd(28)} ${target.targetPath}`);
+  return existed ? 'updated' : 'installed';
+}
+
+function handleAgentsMd(target, opts) {
+  return injectAgentsMd(target.parentDir, { dryRun: opts.dryRun });
+}
+
+// ── Skill body sourcing ─────────────────────────────────────────────────────
+
+async function loadSkillBody() {
+  const config = readConfig();
+  const apiUrl = (config?.api_url || DEFAULT_CLOUD_URL).replace(/\/$/, '');
+
+  // Try the live canonical copy first so installs always reflect the latest version.
+  try {
+    const res = await axios.get(`${apiUrl}/skill.md`, { timeout: 10_000 });
+    if (typeof res.data === 'string' && res.data.length > 0) {
+      return res.data;
+    }
+  } catch {
+    // fall through to bundled fallback
+  }
+
+  const bundled = path.join(__dirname, '..', '..', 'skills', SKILL_NAME, SKILL_FILENAME);
+  if (fs.existsSync(bundled)) {
+    const raw = fs.readFileSync(bundled, 'utf-8');
+    // The bundled copy is the canonical template. Render the API_BASE_URL
+    // placeholder against the configured URL so offline installs still produce
+    // self-referential URLs.
+    return raw.replace(/\{\{API_BASE_URL\}\}/g, apiUrl);
+  }
+
+  throw new Error(
+    'Could not load skill body from network or bundled copy. ' +
+    `Tried ${apiUrl}/skill.md and ${bundled}.`
+  );
+}
+
+/**
+ * Pull `version: X.Y.Z` out of the skill's YAML front-matter. Returns null if
+ * the body has no front-matter or no version key (older skills, edited files).
+ */
+function parseSkillVersion(body) {
+  if (typeof body !== 'string') return null;
+  const m = body.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const v = m[1].match(/^version:\s*(.+?)\s*$/m);
+  return v ? v[1].trim() : null;
+}
+
+/**
+ * Refresh skill targets that *already exist*, leaving uninstalled targets
+ * alone. Used by `bitpub update` so updating the CLI also updates the skill
+ * copies the user has actually opted into. Creating new installs remains the
+ * explicit job of `bitpub skills install`.
+ *
+ * @param {{ dryRun?: boolean }} opts
+ * @returns {Promise<{ updates: Array<{label,path,status,oldVersion?,newVersion?}>, error: string|null }>}
+ */
+async function refreshExistingSkills(opts = {}) {
+  let skillBody;
+  try {
+    skillBody = await loadSkillBody();
+  } catch (err) {
+    return { updates: [], error: err.message };
+  }
+
+  const newVersion = parseSkillVersion(skillBody);
+  const targets = enumerateTargets({ all: true });
+  const updates = [];
+
+  for (const target of targets) {
+    if (!fs.existsSync(target.targetPath)) continue;
+
+    if (target.kind === 'skill-file') {
+      const oldBody = fs.readFileSync(target.targetPath, 'utf-8');
+      if (oldBody === skillBody) {
+        updates.push({
+          label: target.label,
+          path: target.targetPath,
+          status: 'unchanged',
+          oldVersion: parseSkillVersion(oldBody),
+          newVersion,
+        });
+        continue;
+      }
+      if (!opts.dryRun) {
+        fs.writeFileSync(target.targetPath, skillBody);
+      }
+      updates.push({
+        label: target.label,
+        path: target.targetPath,
+        status: 'updated',
+        oldVersion: parseSkillVersion(oldBody),
+        newVersion,
+      });
+    } else if (target.kind === 'agents-md-section') {
+      if (!opts.dryRun) {
+        injectAgentsMd(target.parentDir, { quiet: true });
+      }
+      updates.push({
+        label: target.label,
+        path: target.targetPath,
+        status: 'updated',
+      });
+    }
+  }
+
+  return { updates, error: null };
+}
+
+async function installSkills(opts = {}) {
+  const skillBody = await loadSkillBody();
+  const targets = enumerateTargets(opts);
+  const filtered = opts.target
+    ? targets.filter(t => t.name === opts.target)
+    : targets;
+
+  let installed = 0;
+  let skipped = 0;
+  for (const target of filtered) {
+    const result = handleTarget(target, skillBody, opts);
+    if (result === 'installed' || result === 'updated') installed += 1;
+    else skipped += 1;
+  }
+  return { installed, skipped };
+}
+
+module.exports.installSkills = installSkills;
+module.exports.loadSkillBody = loadSkillBody;
+module.exports.enumerateTargets = enumerateTargets;
+module.exports.refreshExistingSkills = refreshExistingSkills;
+module.exports.parseSkillVersion = parseSkillVersion;
+module.exports.listSkillStatus = listSkillStatus;
+

package/src/commands/status.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * `bitpub status` — DEPRECATED ALIAS. Use `bitpub list` instead.
+ *
+ * The new `bitpub list` (with no args) shows the same workspace anchor,
+ * cache health, and synced-namespace info, plus the slices saved here.
+ * Hidden from --help; kept for shell scripts.
+ */
+
+const { getSyncedNamespaces, getCacheStats } = require('../db/cache');
+const { readConfig } = require('../config');
+
+function relativeTime(isoString) {
+  const diffMs = Date.now() - new Date(isoString).getTime();
+  const secs = Math.floor(diffMs / 1000);
+  if (secs < 60) return 'just now';
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins} min${mins !== 1 ? 's' : ''} ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours} hour${hours !== 1 ? 's' : ''} ago`;
+  const days = Math.floor(hours / 24);
+  return `${days} day${days !== 1 ? 's' : ''} ago`;
+}
+
+module.exports = function registerStatus(program) {
+  program
+    .command('status', { hidden: true })
+    .description('[deprecated] Use `bitpub list` instead')
+    .action(() => {
+      console.error('warning: `bitpub status` is deprecated. Use `bitpub list` instead.');
+      const config = readConfig();
+      const stats = getCacheStats();
+      const namespaces = getSyncedNamespaces();
+      console.log('BitPub — Local Cache Status');
+      console.log('─'.repeat(40));
+      if (config) {
+        if (config.owner)  console.log(`Owner  : ${config.owner}`);
+        if (config.domain) console.log(`Domain : ${config.domain}`);
+        if (config.tier)   console.log(`Tier   : ${config.tier}`);
+        console.log(`Backend: ${config.api_url || 'http://localhost:8080'}`);
+      } else {
+        console.log('Not configured. Run: bitpub setup');
+      }
+      console.log(`Slices : ${stats?.total_slices ?? 0} cached`);
+      if (stats?.latest_sync) {
+        console.log(`Updated: ${relativeTime(stats.latest_sync)}`);
+      }
+      if (namespaces.length === 0) {
+        console.log('\nNo namespaces synced yet.');
+        console.log('Run: bitpub sync "bitpub://group:YOUR_DOMAIN/**"');
+        return;
+      }
+      console.log('\nSynced Namespaces:');
+      for (const ns of namespaces) {
+        const ago = relativeTime(ns.last_synced);
+        const count = `${ns.slice_count} slice${ns.slice_count !== 1 ? 's' : ''}`;
+        console.log(`  ${ns.pattern}`);
+        console.log(`    Last synced: ${ago}  |  ${count}`);
+      }
+    });
+};