@bitpub/cli 2.1.1 → 2.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitpub/cli",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "BitPub CLI — local-first shared memory for AI agents. Six daily verbs (save/load/list/find/sync/delete), zero-config private namespace, encrypted client-side.",
   "bin": {
     "bitpub": "./bin/bitpub.js"

package/skills/bitpub/SKILL.md

@@ -241,6 +241,90 @@ valid pattern wherever a scope is accepted.
 
 ---
 
+## Publishing apps
+
+BitPub can render HTML apps directly in its browser (`bitpub browser`,
+served at `http://localhost:4141`). An "app" is just three slices saved
+at the same prefix — no CLI release, no plugin install, no extension API.
+Save the slices and the app appears in every member's BitPub Browser the
+moment their next `bitpub sync` lands.
+
+| Slice | What it is | Format |
+|---|---|---|
+| `<prefix>` | The app shell — rendered in a sandboxed iframe | `text/html` |
+| `<prefix>/manifest.json` | Declarative list of functions the app may call | `application/json` |
+| `<prefix>/<orchestrator>` | (Optional) script the app's functions execute | `text/plain` (or `text/x-python`, etc.) |
+
+Inside the iframe an app calls:
+
+```js
+window.bitpub.identity.me()                  // → { owner, domain, private_prefix }
+window.bitpub.namespace.list({ pattern })    // local SQLite read; no network, no LLM
+window.bitpub.run(functionId, args)          // dispatched through the manifest
+window.bitpub.navigate(hcu)                  // open another slice in the browser
+```
+
+`window.bitpub.run` does not execute arbitrary commands. It looks up
+`functionId` in the app's manifest and dispatches to one of two primitives
+the CLI bridge exposes:
+
+- **`script.run`** — `bitpub load <script_hcu>` to a temp file, then run
+  it with the named interpreter (`python3`, `node`, `bash`, `sh`). Reads
+  `env` and `cli_args` from the manifest, with values resolved from the
+  caller's `args`, the running user's `identity`, or literals.
+- **`os.open`** — `open` a URL or local path (Finder reveal, or
+  open-in-app).
+
+A minimal manifest:
+
+```json
+{
+  "id": "team.example",
+  "name": "Example",
+  "version": "0.1.0",
+  "functions": {
+    "ingest": {
+      "primitive": "script.run",
+      "params": {
+        "script_hcu": "bitpub://group:<domain>/Apps/example/orchestrator",
+        "runtime": "python3"
+      },
+      "env": {
+        "BITPUB_OWNER": { "from": "identity", "key": "owner" },
+        "TARGET":       { "from": "args",     "key": "target" }
+      }
+    },
+    "open_docs": {
+      "primitive": "os.open",
+      "params": { "url": "https://example.com/docs" }
+    }
+  }
+}
+```
+
+Two rules of thumb that keep apps portable across teammates:
+
+- **Read user identity at runtime** in both the orchestrator and the
+  manifest (via `{ "from": "identity", "key": "owner" }`). Never hardcode
+  an `agent_xxx` id — it breaks the moment a different teammate runs the
+  app.
+- **Split ingest from read.** Ingest (write to BitPub) is the slow,
+  credentialed step. Once data is local, every read should be a
+  deterministic `namespace.list` / `bitpub load` — no LLM, no API call.
+
+Before writing a new app, read the full publishing guide. It's hosted
+alongside this skill so it's always reachable from a fresh install:
+
+```bash
+curl -fsSL {{API_BASE_URL}}/publishing-apps.md
+```
+
+If the team has shipped its own copy at
+`bitpub://group:<domain>/Docs/how-to-publish-a-bitpub-app`, prefer that
+— it usually links to in-tree example apps you can fork from.
+
+---
+
 ## Writing scripts that use BitPub
 
 Scripts should read `owner` and `domain` from `~/.bitpub/config.json` at

package/src/commands/browser.js

@@ -21,6 +21,7 @@ const { exec, spawn } = require('child_process');
 const { readConfig, BITPUB_DIR } = require('../config');
 const { getSyncedNamespaces, initCache } = require('../db/cache');
 const { isPrivateHcu, decrypt, isEncrypted } = require('../crypto');
+const { runOneShot: runSyncOneShot } = require('./sync');
 
 const Database = require('better-sqlite3');
 const DB_PATH = path.join(os.homedir(), '.bitpub', 'cache.db');
@@ -110,258 +111,126 @@ const ASSET_MIME = {
 
 /* ── Bridge (apps → local CLI) ──────────────────────────────────────
  *
- * Sandboxed app iframes (default-src 'none', no allow-same-origin)
- * cannot fetch, but they CAN postMessage to the parent window. The
- * parent is the BitPub Browser shell; it forwards approved calls to
- * this CLI process, which spawns a child and streams stdout/stderr
- * back over Server-Sent Events.
+ * Sandboxed app iframes can postMessage to the parent BitPub Browser
+ * shell, which forwards approved calls to this CLI process. The CLI
+ * spawns a child and streams stdout/stderr back over SSE.
  *
- * Security floor for v1:
- *   - Only functions listed in FUNCTIONS are runnable. Apps cannot
- *     execute arbitrary shell.
- *   - Arguments are typed and validated per function — no string
- *     interpolation into the shell.
- *   - The HTTP server binds to localhost only (default port 4141),
- *     so the surface is the same trust boundary as the CLI itself:
- *     anyone with shell access already has more power than the bridge.
- *   - The next layer (permission grants per app + audit log) is a
- *     console.html responsibility, not the CLI's.
+ * SUBSTRATE PRIMITIVES (this file):
+ *   - script.run   load a slice as a script + run with an interpreter
+ *   - os.open      open a URL in the default browser, or a path locally
+ *   - identity.me  who is this BitPub install (separate /bridge/identity endpoint)
  *
- * Functions in v1 are hardcoded here. The end state — functions
- * resolved from slices, e.g. bitpub://group:tollbit.com/Functions/<id>
- * — needs the same permission UX and a small sandbox for the script,
- * so we ship the registry shape first and back-fill the resolver.
+ * APP-SPECIFIC FUNCTIONS (live in the namespace as manifest.json slices):
+ *   Apps declare their own named functions in a manifest sibling slice,
+ *   e.g. bitpub://group:tollbit.com/Apps/github/manifest.json. The
+ *   Browser shell (console.html) reads that manifest, resolves each
+ *   function call to a script.run or os.open invocation, and forwards
+ *   to the bridge. This means no CLI release is needed to publish a
+ *   new app — anyone in a group can save HTML + script + manifest and
+ *   ship it.
+ *
+ * Trust model: same as installing an npm package. Anything the script
+ * can do, the orchestrator can do — we don't sandbox the child process.
+ * The browser shell is responsible for the install consent UI; the CLI
+ * only enforces input shape on the primitives.
  */
 const FUNCTIONS = {
-  'granola.ingest': {
-    description: 'Pull new Granola meetings into your private namespace.',
-    build(args) {
-      const limit = clampInt(args && args.limit, 1, 200, 5);
-      const script =
-        'set -e; ' +
-        'bitpub load bitpub://group:tollbit.com/Agents/granola-ingest/script > "$T" && ' +
-        `python3 "$T" --limit ${limit}`;
-      return {
-        cmd: 'bash',
-        args: ['-lc', script],
-        env: { T: path.join(os.tmpdir(), `.bitpub-fn-granola-ingest.py`) },
-      };
-    },
-  },
 
-  // Orchestration script for sales_brief.generate lives as a slice at
-  // bitpub://private:.../Apps/sales-brief-generator/orchestrator so the
-  // logic can be iterated without restarting the CLI. The function below
-  // is the thin entry point that loads + runs it.
-  'sales_brief.generate': {
-    description: 'Synthesize a bespoke sales brief PDF from selected call transcripts.',
+  // ── Substrate primitive 1: load + run a script slice ───────
+  // Everything else (ingest scripts, generators, summarizers) is
+  // implementable on top of this. Args are deliberately flat so a
+  // declarative app manifest can construct them without a build step.
+  'script.run': {
+    description: 'Load a slice as a script and run it with the given interpreter.',
     build(args) {
       const a = args || {};
-      const transcriptHcus = Array.isArray(a.transcript_hcus) ? a.transcript_hcus.slice(0, 25) : [];
-      const template = String(a.template || 'discovery').slice(0, 32).replace(/[^a-z_]/gi, '');
-      const customer = String(a.customer || '').slice(0, 120);
-      const dealStage = String(a.deal_stage || '').slice(0, 80);
-      const extraNotes = String(a.extra_notes || '').slice(0, 2000);
-      const outputDir = path.join(os.homedir(), 'Downloads', 'Briefs');
-
-      if (transcriptHcus.length === 0) {
-        throw new Error('no transcripts selected');
+      const hcu = String(a.script_hcu || a.script || '').trim();
+      const runtime = String(a.runtime || 'python3').trim();
+      const env = (a.env && typeof a.env === 'object') ? a.env : {};
+      const cliArgs = Array.isArray(a.cli_args) ? a.cli_args : [];
+
+      // HCU must be a real bitpub:// address and free of shell metachars.
+      // (We re-embed it into the bash -lc string below, so be paranoid.)
+      if (!/^bitpub:\/\/(private|group|public):[A-Za-z0-9._-]+\/[A-Za-z0-9._\/\-]+$/.test(hcu)) {
+        throw new Error('invalid script_hcu');
       }
+      if (/[\s"'`$;&|<>\\]/.test(hcu)) throw new Error('script_hcu contains unsafe characters');
 
-      const payload = JSON.stringify({
-        transcript_hcus: transcriptHcus,
-        template,
-        customer,
-        deal_stage: dealStage,
-        extra_notes: extraNotes,
-        output_dir: outputDir,
-      });
-
-      const script =
-        'set -e; ' +
-        'bitpub load bitpub://private:agent_ewim9gf01nq3/Apps/sales-brief-generator/orchestrator > "$ORCH" && ' +
-        'python3 "$ORCH"';
-
-      return {
-        cmd: 'bash',
-        args: ['-lc', script],
-        env: {
-          ORCH: path.join(os.tmpdir(), '.bitpub-fn-sales-brief.py'),
-          BRIEF_PAYLOAD: payload,
-        },
-      };
-    },
-  },
+      const ALLOWED_RUNTIMES = ['python3', 'python', 'node', 'bash', 'sh'];
+      if (!ALLOWED_RUNTIMES.includes(runtime)) {
+        throw new Error(`runtime "${runtime}" not allowed (use one of ${ALLOWED_RUNTIMES.join(', ')})`);
+      }
 
-  'sales_brief.open': {
-    description: 'Open a generated PDF in the default viewer.',
-    build(args) {
-      const p = String((args && args.path) || '');
-      if (!p || !p.startsWith('/') || p.includes('"')) throw new Error('invalid path');
-      return { cmd: 'bash', args: ['-lc', `open "${p}"`] };
-    },
-  },
+      // Sanitize env: only POSIX-ish var names, stringify values.
+      const cleanEnv = {};
+      for (const [k, v] of Object.entries(env)) {
+        if (!/^[A-Z_][A-Z0-9_]{0,63}$/i.test(k)) continue;
+        if (v == null) continue;
+        cleanEnv[k] = (typeof v === 'string') ? v : JSON.stringify(v);
+      }
 
-  'sales_brief.reveal': {
-    description: 'Reveal a generated PDF in Finder.',
-    build(args) {
-      const p = String((args && args.path) || '');
-      if (!p || !p.startsWith('/') || p.includes('"')) throw new Error('invalid path');
-      return { cmd: 'bash', args: ['-lc', `open -R "${p}"`] };
-    },
-  },
+      // Sanitize CLI args: stringify, reject anything with shell metachars.
+      const cleanCliArgs = [];
+      for (const x of cliArgs) {
+        const s = String(x);
+        if (s.length > 256) throw new Error('cli arg too long');
+        if (/[`$;&|<>\\\n]/.test(s)) throw new Error('cli arg contains unsafe characters');
+        cleanCliArgs.push(s);
+      }
 
-  // ── GitHub Pack ────────────────────────────────────────────
-  // The orchestrator slice lives at a GROUP address so every teammate
-  // in the group can load the same logic — they don't fork it. Each
-  // entry point injects BITPUB_OWNER from local config so the script
-  // writes to *the running user's* private namespace, not the author's.
-  //
-  // Auth model: orchestrator probes (1) macOS keychain entry from
-  // GitHub Desktop, (2) gh CLI, (3) BitPub-managed token. Tokens are
-  // never passed through args/URLs — child reads them itself so
-  // secrets never traverse the bridge.
-
-  'github.check_auth': {
-    description: 'Detect available GitHub credentials (Desktop keychain, gh CLI, BitPub-managed token).',
-    build() {
-      return {
-        cmd: 'bash',
-        args: ['-lc',
-          'set -e; ' +
-          'bitpub load bitpub://group:tollbit.com/Apps/github/orchestrator > "$T" && ' +
-          'python3 "$T"',
-        ],
-        env: {
-          T: path.join(os.tmpdir(), '.bitpub-fn-github-authcheck.py'),
-          BITPUB_GH_ACTION: 'auth_check',
-          BITPUB_OWNER: (readConfig() || {}).owner || '',
-        },
-      };
+      // Unique temp file per invocation so two concurrent runs of the
+      // same script can't trample each other.
+      const tag = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const T = path.join(os.tmpdir(), `.bitpub-script-${tag}`);
+      cleanEnv.T = T;
+
+      // Re-shell-quote CLI args by passing them as positional args to bash
+      // via the "_" sentinel, then "$@" preserves quoting.
+      const cliPart = cleanCliArgs.length
+        ? ' ' + cleanCliArgs.map(a => `"${a.replace(/"/g, '\\"')}"`).join(' ')
+        : '';
+      const script = `set -e; bitpub load "${hcu}" > "$T" && ${runtime} "$T"${cliPart}`;
+      return { cmd: 'bash', args: ['-lc', script], env: cleanEnv };
     },
   },
 
-  'github.ingest': {
-    description: 'Mirror your GitHub PRs, issues, and recent activity into your namespace.',
+  // ── Substrate primitive 2: open a URL or a local path ──────
+  // Wraps macOS `open` (the only OS-level capability apps reach for
+  // often enough to belong in the substrate). Manifests can declare
+  // url_pattern allowlists for extra hygiene — enforced at resolver
+  // time in the shell, not here.
+  'os.open': {
+    description: 'Open a URL in the default browser, or a path in Finder / a specific app.',
     build(args) {
       const a = args || {};
-      const recipes = Array.isArray(a.recipes) && a.recipes.length
-        ? a.recipes.filter(r => typeof r === 'string' && /^[a-z_]+$/.test(r)).slice(0, 8)
-        : ['prs_review_requested', 'prs_mine', 'prs_org_recent', 'issues_assigned', 'activity_recent'];
-      return {
-        cmd: 'bash',
-        args: ['-lc',
-          'set -e; ' +
-          'bitpub load bitpub://group:tollbit.com/Apps/github/orchestrator > "$T" && ' +
-          'python3 "$T"',
-        ],
-        env: {
-          T: path.join(os.tmpdir(), '.bitpub-fn-github-ingest.py'),
-          BITPUB_GH_RECIPES: recipes.join(','),
-          BITPUB_OWNER: (readConfig() || {}).owner || '',
-        },
-      };
-    },
-  },
-
-  'github.open': {
-    description: 'Open a GitHub URL in the default browser.',
-    build(args) {
-      const url = String((args && args.url) || '');
-      if (!/^https:\/\/github\.com\//.test(url) || url.includes('"')) {
-        throw new Error('invalid github url');
+      const url = a.url ? String(a.url) : null;
+      const filePath = a.path ? String(a.path) : null;
+      const reveal = !!a.reveal;
+      const inApp = a.in ? String(a.in) : null;
+
+      if (url) {
+        if (!/^https?:\/\//.test(url) || /["`$;&|<>\\]/.test(url)) throw new Error('invalid url');
+        return { cmd: 'bash', args: ['-lc', `open "${url}"`] };
       }
-      return { cmd: 'bash', args: ['-lc', `open "${url}"`] };
-    },
-  },
-
-  'github.open_clone': {
-    description: 'Open a repo\'s local clone in Finder (or VS Code if "in" === "vscode").',
-    build(args) {
-      const repo = String((args && args.repo) || '');
-      const where = String((args && args.in) || 'finder');
-      if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(repo)) {
-        throw new Error('invalid repo "owner/name"');
+      if (filePath) {
+        if (!filePath.startsWith('/') || /["`$;&|<>\\]/.test(filePath)) throw new Error('invalid path');
+        let flag = '';
+        if (reveal) flag = '-R ';
+        else if (inApp) {
+          if (!/^[A-Za-z0-9. _-]{1,64}$/.test(inApp)) throw new Error('invalid app name');
+          flag = `-a "${inApp}" `;
+        }
+        return { cmd: 'bash', args: ['-lc', `open ${flag}"${filePath}"`] };
       }
-      const opener = where === 'vscode' ? 'code' :
-                     where === 'iterm'  ? `open -a iTerm` :
-                                          'open';
-      // Search common project roots for a directory whose `git remote -v`
-      // points at this repo. Local-first move: we surface the user's
-      // clone if they have one, instead of dumping them at github.com.
-      const script = `
-set -e
-REPO='${repo}'
-ROOTS=(~/projects ~/code ~/dev ~/src ~/Documents/projects ~/work)
-for root in "\${ROOTS[@]}"; do
-  [ -d "$root" ] || continue
-  while IFS= read -r dir; do
-    if (cd "$dir" && git remote -v 2>/dev/null) | grep -qiE "[:/]\${REPO}(\\.git)?( |\\\$)"; then
-      echo "found clone: $dir"
-      ${opener} "$dir"
-      exit 0
-    fi
-  done < <(find "$root" -mindepth 1 -maxdepth 3 -type d -name .git -prune -exec dirname {} \\; 2>/dev/null)
-done
-echo "no local clone of $REPO found in common roots — opening on github.com instead"
-open "https://github.com/$REPO"
-`;
-      return { cmd: 'bash', args: ['-lc', script] };
+      throw new Error('os.open needs either url or path');
     },
   },
 
-  'github.summarize_pr': {
-    description: 'Summarize a PR with claude (the only LLM-in-the-loop step).',
-    build(args) {
-      const hcu = String((args && args.hcu) || '');
-      // Any private namespace, as long as it's pointed at GitHub/PRs/.
-      // We constrain the shape so an app can't trick the bridge into
-      // pulling arbitrary slices through claude.
-      if (!/^bitpub:\/\/private:[a-z0-9_-]+\/GitHub\/PRs\//i.test(hcu) || hcu.includes('"')) {
-        throw new Error('invalid PR hcu');
-      }
-      // Deterministic read (bitpub load) -> single LLM call (claude -p) ->
-      // structured text back to the UI. No MCP, no network round-trip for
-      // the data — only for the synthesis.
-      const script =
-        'set -e; ' +
-        `bitpub load "${hcu}" > "$T" && ` +
-        'claude -p "$(printf \'%s\\n\\nSummarize this GitHub PR in 3 short bullets: what it does, who it affects, anything risky. Be concrete.\' "$(cat "$T")")" ' +
-        '--output-format text --permission-mode bypassPermissions';
-      return {
-        cmd: 'bash',
-        args: ['-lc', script],
-        env: { T: path.join(os.tmpdir(), `.bitpub-fn-github-summarize.md`) },
-      };
-    },
-  },
+  // ───────────────────────────────────────────────────────────
+  // (Apps now declare their functions in manifest.json slices —
+  // see backend/static/console.html#resolveManifestFunction.)
+  // ───────────────────────────────────────────────────────────
 
-  'github.action.approve': {
-    description: 'Approve a pull request via the GitHub API (uses inherited credentials).',
-    build(args) {
-      const repo   = String((args && args.repo) || '');
-      const number = parseInt((args && args.number), 10);
-      const body   = String((args && args.body) || '');
-      if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(repo)) throw new Error('invalid repo');
-      if (!Number.isFinite(number) || number <= 0) throw new Error('invalid PR number');
-      return {
-        cmd: 'bash',
-        args: ['-lc',
-          'set -e; ' +
-          'bitpub load bitpub://group:tollbit.com/Apps/github/orchestrator > "$T" && ' +
-          'python3 "$T"',
-        ],
-        env: {
-          T: path.join(os.tmpdir(), '.bitpub-fn-github-action.py'),
-          BITPUB_GH_ACTION: 'approve',
-          BITPUB_GH_REPO: repo,
-          BITPUB_GH_PR: String(number),
-          BITPUB_GH_BODY: body,
-          BITPUB_OWNER: (readConfig() || {}).owner || '',
-        },
-      };
-    },
-  },
 };
 
 function clampInt(value, lo, hi, dflt) {
@@ -498,6 +367,128 @@ function handleBridgeRun(req, res, url) {
   });
 }
 
+/**
+ * Resolve the set of namespaces to sync for "sync everything visible
+ * to the current user." This is the same shape an attentive user would
+ * type by hand: their private root + every joined group.
+ *
+ * Returns an array of `{ pattern, label, config }` triples. The per-
+ * scope `config` is the user's primary config with `api_key` swapped
+ * out when a group entry pins its own key (multi-backend memberships).
+ */
+function resolveSyncTargets(baseConfig) {
+  const targets = [];
+  if (baseConfig && baseConfig.owner) {
+    targets.push({
+      pattern: `bitpub://private:${baseConfig.owner}/**`,
+      label: `private:${baseConfig.owner}`,
+      config: baseConfig,
+    });
+  }
+  const groups = Array.isArray(baseConfig && baseConfig.groups) ? baseConfig.groups : [];
+  for (const g of groups) {
+    if (!g || !g.slug) continue;
+    targets.push({
+      pattern: `bitpub://group:${g.slug}/**`,
+      label: `group:${g.slug}`,
+      // Per-group key/URL is only relevant on multi-backend setups; for
+      // the common single-backend case these fields equal the primary
+      // config and the fallback is a no-op.
+      config: {
+        ...baseConfig,
+        api_key: g.key || baseConfig.api_key,
+        api_url: g.api_url || baseConfig.api_url,
+      },
+    });
+  }
+  return targets;
+}
+
+/**
+ * Stream `bitpub sync` across every scope visible to the user as SSE.
+ *
+ * Wire format:
+ *   event: started   data: { targets: [{label, pattern}, ...] }
+ *   event: scope     data: { label, pattern, status: 'syncing' }
+ *   event: scope     data: { label, pattern, status: 'done',  count, hitLimit }
+ *   event: scope     data: { label, pattern, status: 'error', message }
+ *   event: done      data: { total, scopes }     ← terminal; connection closes
+ *
+ * This is browser-chrome plumbing, not an app function — it calls
+ * sync.js#runOneShot directly inside this process rather than spawning
+ * `bitpub sync` as a subprocess via the script.run primitive. Reasons:
+ *   • No shell-out cost, no quoting hazard, no env propagation issues.
+ *   • Per-scope progress is structured (event stream), not parsed stdout.
+ *   • Manifests are for user-published apps; the Sync button is part of
+ *     the browser shell and shouldn't go through that machinery.
+ */
+function handleBridgeSync(req, res) {
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache, no-transform');
+  res.setHeader('Connection', 'keep-alive');
+  res.setHeader('X-Accel-Buffering', 'no');
+
+  function send(event, payload) {
+    if (res.writableEnded) return;
+    res.write(`event: ${event}\n`);
+    res.write(`data: ${JSON.stringify(payload)}\n\n`);
+  }
+
+  const cfg = readConfig();
+  if (!cfg || !cfg.owner) {
+    send('error', { message: 'No bitpub identity configured. Run `bitpub setup` first.' });
+    send('done', { total: 0, scopes: 0 });
+    res.end();
+    return;
+  }
+
+  const targets = resolveSyncTargets(cfg);
+  send('started', { targets: targets.map(t => ({ label: t.label, pattern: t.pattern })) });
+
+  let cancelled = false;
+  req.on('close', () => { cancelled = true; });
+
+  // Sync scopes sequentially so the progress events tell a single story
+  // and we don't slam the same backend with N concurrent pulls.
+  (async () => {
+    let total = 0;
+    let okScopes = 0;
+    for (const t of targets) {
+      if (cancelled) return;
+      send('scope', { label: t.label, pattern: t.pattern, status: 'syncing' });
+      try {
+        const r = await runSyncOneShot(
+          { pattern: t.pattern, label: t.label, limit: 500, includeDeleted: false, quiet: true },
+          t.config
+        );
+        total += r.count;
+        okScopes += 1;
+        send('scope', {
+          label: t.label,
+          pattern: t.pattern,
+          status: 'done',
+          count: r.count,
+          hitLimit: !!r.hitLimit,
+        });
+      } catch (err) {
+        send('scope', {
+          label: t.label,
+          pattern: t.pattern,
+          status: 'error',
+          message: err && err.message ? err.message : String(err),
+        });
+      }
+    }
+    send('done', { total, scopes: okScopes });
+    res.end();
+  })().catch((err) => {
+    send('error', { message: err && err.message ? err.message : String(err) });
+    send('done', { total: 0, scopes: 0 });
+    res.end();
+  });
+}
+
 function openInBrowser(url) {
   const cmd = process.platform === 'darwin' ? 'open' :
     process.platform === 'win32' ? 'start' : 'xdg-open';
@@ -601,6 +592,15 @@ function startBrowserServer(opts = {}) {
         return;
       }
 
+      // Bridge: sync every namespace visible to this user (private +
+      // each joined group) and stream per-scope progress as SSE. This
+      // backs the sidebar "Sync" button — it's browser chrome, not an
+      // app function, and so doesn't go through the manifest system.
+      if (url.pathname === '/bridge/sync') {
+        handleBridgeSync(req, res);
+        return;
+      }
+
       // Bridge: deterministic namespace read. Apps call this to fetch
       // any slices that match an HCU pattern (exact or prefix-with-/*).
       // No LLM, no MCP, no auth in the loop — this is the read path

package/src/commands/sync.js

@@ -60,7 +60,7 @@ function resolveSyncPattern(input, config) {
   return { pattern: active.namespace + resolved, label: input };
 }
 
-async function runOneShot({ pattern, label, limit, includeDeleted }, config) {
+async function runOneShot({ pattern, label, limit, includeDeleted, quiet }, config) {
   const api = createApiClient(config);
   const limitNum = parseInt(limit, 10) || 500;
 
@@ -70,19 +70,24 @@ async function runOneShot({ pattern, label, limit, includeDeleted }, config) {
   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/**'`);
+  const hitLimit = slices.length >= Math.min(limitNum, 500);
+
+  if (!quiet) {
+    console.log(`Synced ${slices.length} slice(s) from ${label}`);
+    // Surface page-cap warning so the user knows to narrow their pattern.
+    if (hitLimit) {
+      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/**'`);
+    }
   }
+
+  return { count: slices.length, hitLimit, pattern, label };
 }
 
 function runWatch({ pattern, label }, config) {

package/static/console.html

@@ -217,9 +217,27 @@ svg { flex-shrink: 0; }
 #main:hover::-webkit-scrollbar-thumb { background: var(--border); background-clip: content-box; }
 
 /* ── Sidebar / Tree ─────────────────────────────────── */
-.sidebar-header { padding: 12px 14px 8px; font-size: 10.5px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; color: var(--text-subtle); display: flex; align-items: center; justify-content: space-between; }
+.sidebar-header { padding: 12px 14px 8px; font-size: 10.5px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; color: var(--text-subtle); display: flex; align-items: center; justify-content: space-between; gap: 8px; }
 .sidebar-header .clear-btn { font-size: 10.5px; color: var(--text-subtle); cursor: pointer; font-weight: 500; letter-spacing: 0; text-transform: none; }
 .sidebar-header .clear-btn:hover { color: var(--accent); }
+
+/* Sync button — icon-only, ghost style, lives in the sidebar header.
+   Spins while a /bridge/sync request is in flight; pulses green for a
+   moment after a successful sync so the user gets feedback even if no
+   new slices landed. */
+.sync-btn { display: inline-flex; align-items: center; gap: 4px; padding: 3px 6px; border: 0; background: transparent; color: var(--text-subtle); cursor: pointer; border-radius: var(--radius-sm); font: inherit; font-size: 10.5px; font-weight: 500; text-transform: none; letter-spacing: 0; }
+.sync-btn:hover:not(:disabled) { background: var(--bg-hover); color: var(--text); }
+.sync-btn:disabled { opacity: .6; cursor: default; }
+.sync-btn svg { width: 12px; height: 12px; transition: transform .2s ease-out; }
+.sync-btn.is-syncing svg { animation: bp-spin 1s linear infinite; }
+.sync-btn.is-done { color: #10b981; }
+@keyframes bp-spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
+.sync-status { padding: 4px 14px 8px; font-size: 11px; color: var(--text-subtle); line-height: 1.4; max-height: 120px; overflow-y: auto; }
+.sync-status.hidden { display: none; }
+.sync-status .row { display: flex; justify-content: space-between; gap: 8px; padding: 2px 0; }
+.sync-status .row .label { color: var(--text); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.sync-status .row .count { color: var(--text-subtle); flex-shrink: 0; font-variant-numeric: tabular-nums; }
+.sync-status .row.error .count { color: var(--scope-group); }
 .tree-wrap { flex: 1; overflow-y: auto; padding: 0 6px 12px; }
 .tree-wrap::-webkit-scrollbar { width: 8px; }
 .tree-wrap::-webkit-scrollbar-thumb { background: transparent; border-radius: 4px; }
@@ -972,8 +990,15 @@ svg { flex-shrink: 0; }
     <aside id="sidebar">
       <div class="sidebar-header">
         <span>Namespaces</span>
-        <span id="clear-filter-btn" class="clear-btn hidden" onclick="clearFilter()">Clear</span>
+        <span style="display:inline-flex; align-items:center; gap:6px;">
+          <span id="clear-filter-btn" class="clear-btn hidden" onclick="clearFilter()">Clear</span>
+          <button id="sync-btn" class="sync-btn" type="button" onclick="runFullSync()" title="Sync all namespaces from the cloud into your local cache">
+            <svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M8 3a5 5 0 0 1 4.546 2.914.5.5 0 0 0 .908-.418A6 6 0 1 0 2 8a.5.5 0 1 0 1 0 5 5 0 0 1 5-5Z"/><path d="M8 13a5 5 0 0 1-4.546-2.914.5.5 0 0 0-.908.418A6 6 0 1 0 14 8a.5.5 0 1 0-1 0 5 5 0 0 1-5 5Z"/><path d="M11.5 1.5a.5.5 0 0 1 .5.5v3a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1 0-1H11V2a.5.5 0 0 1 .5-.5ZM4.5 10.5a.5.5 0 0 1 .5.5v2.5h2.5a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5v-3a.5.5 0 0 1 .5-.5Z"/></svg>
+            <span class="sync-btn-label">Sync</span>
+          </button>
+        </span>
       </div>
+      <div id="sync-status" class="sync-status hidden"></div>
       <div id="tree" class="tree-wrap"></div>
     </aside>
     <main id="main"></main>
@@ -1456,6 +1481,135 @@ function clearFilter() {
   renderAll();
 }
 
+/* ── Sidebar Sync button ────────────────────────────────
+ *
+ * Streams /bridge/sync (SSE) and renders per-scope progress under the
+ * header. On `done`, force a fresh /api/data poll so the tree picks up
+ * any new arrivals immediately (without waiting for the 30s tick).
+ *
+ * The button is browser chrome — not an app function — so it talks
+ * directly to /bridge/sync rather than going through window.bitpub.run
+ * and the manifest dispatcher.
+ *
+ * Reentrancy: a second click while a sync is in flight is a no-op
+ * (we disable the button), so we don't need to track an EventSource
+ * handle for cancellation.
+ */
+async function runFullSync() {
+  const btn = $('sync-btn');
+  const status = $('sync-status');
+  if (!btn || btn.disabled) return;
+
+  btn.disabled = true;
+  btn.classList.add('is-syncing');
+  btn.classList.remove('is-done');
+  status.classList.remove('hidden');
+  status.innerHTML = '';
+
+  // Track rows so 'syncing' → 'done' overwrites in place rather than
+  // appending a second line per scope.
+  const rows = new Map();
+
+  function setRow(label, pattern, statusText, klass) {
+    let row = rows.get(label);
+    if (!row) {
+      row = document.createElement('div');
+      row.className = 'row';
+      const a = document.createElement('span'); a.className = 'label';
+      const b = document.createElement('span'); b.className = 'count';
+      row.append(a, b);
+      status.appendChild(row);
+      rows.set(label, row);
+    }
+    row.className = 'row' + (klass ? ' ' + klass : '');
+    row.title = pattern;
+    row.children[0].textContent = label;
+    row.children[1].textContent = statusText;
+  }
+
+  const base = location.pathname.endsWith('/') ? location.pathname : location.pathname + '/';
+  const es = new EventSource(base + 'bridge/sync');
+
+  function cleanup() {
+    es.close();
+    btn.disabled = false;
+    btn.classList.remove('is-syncing');
+  }
+
+  es.addEventListener('started', (e) => {
+    let payload = {};
+    try { payload = JSON.parse(e.data); } catch {}
+    for (const t of (payload.targets || [])) setRow(t.label, t.pattern, 'queued', '');
+  });
+
+  es.addEventListener('scope', (e) => {
+    let payload = {};
+    try { payload = JSON.parse(e.data); } catch {}
+    if (payload.status === 'syncing') {
+      setRow(payload.label, payload.pattern, 'syncing…', '');
+    } else if (payload.status === 'done') {
+      const cnt = (payload.count ?? 0) + ' slices';
+      const suffix = payload.hitLimit ? ' (capped)' : '';
+      setRow(payload.label, payload.pattern, cnt + suffix, '');
+    } else if (payload.status === 'error') {
+      setRow(payload.label, payload.pattern, 'error', 'error');
+      console.error('[sync]', payload.label, payload.message);
+    }
+  });
+
+  es.addEventListener('error', (e) => {
+    // Server-sent `event: error` (CLI-reported); EventSource also fires
+    // 'error' on connection drops with no payload. Treat both the same.
+    let payload = {};
+    if (e && e.data) { try { payload = JSON.parse(e.data); } catch {} }
+    if (payload.message) {
+      const row = document.createElement('div');
+      row.className = 'row error';
+      row.innerHTML = '<span class="label">sync failed</span><span class="count"></span>';
+      row.children[1].textContent = payload.message.slice(0, 60);
+      status.appendChild(row);
+    }
+    // Don't cleanup here — wait for `done`, or for the connection to
+    // close on its own. Real errors will be followed by `done`.
+  });
+
+  es.addEventListener('done', async (e) => {
+    let payload = {};
+    try { payload = JSON.parse(e.data); } catch {}
+    cleanup();
+    btn.classList.add('is-done');
+    setTimeout(() => btn.classList.remove('is-done'), 2000);
+
+    // Force-refresh the data so any newly-synced slices show up in
+    // the tree immediately instead of on the next 30s poll tick.
+    const data = await fetchData({ silent: true });
+    if (data) {
+      const arrivals = new Set();
+      const oldKey = new Set(S.slices.map(s => s.hcu + '|' + (s.last_synced || '')));
+      const nextSlices = data.slices.map(parseSlice);
+      for (const s of nextSlices) {
+        const k = s.hcu + '|' + (s.last_synced || '');
+        if (!oldKey.has(k)) arrivals.add(s.hcu);
+      }
+      S.slices = nextSlices;
+      S.tree = buildTree(S.slices);
+      S.stats = computeStats(S.slices);
+      S.lastUpdated = maxTs(S.slices);
+      S.newArrivals = arrivals;
+      renderAll();
+      setTimeout(() => { S.newArrivals = new Set(); }, 2500);
+    }
+
+    // Auto-hide the status panel after a beat if everything succeeded.
+    const anyErrors = Array.from(rows.values()).some(r => r.classList.contains('error'));
+    if (!anyErrors) {
+      setTimeout(() => {
+        if (!btn.classList.contains('is-syncing')) status.classList.add('hidden');
+      }, 4000);
+    }
+  });
+}
+
 /* ══════════════════════════════════════════════════════
    Top-level render
    ══════════════════════════════════════════════════════ */
@@ -2490,7 +2644,7 @@ function renderSlice(sl) {
   if (S.raw) {
     html += `<pre class="content-raw">${esc(content)}</pre>`;
   } else if (canRenderAsApp) {
-    html += renderHtmlAppFrame(content);
+    html += renderHtmlAppFrame(content, sl.hcu);
   } else if (kind === 'html') {
     html += `<div class="app-public-note">${ICON.info}
       <div>HTML apps from <code>public:</code> addresses are shown as source until the public sandbox model lands. Apps in <code>private:</code> and <code>group:</code> scopes render inline.</div>
@@ -2555,14 +2709,21 @@ function detectContentKind(sl, content) {
  *   - The iframe never reaches the network itself — only the parent
  *     does. CSP can stay locked down (default-src 'none').
  */
-function renderHtmlAppFrame(html) {
+function renderHtmlAppFrame(html, appHcu) {
   const csp = `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; base-uri 'none'; form-action 'none'">`;
   const baseTag = `<base target="_blank">`;
+  // Inject the app's own HCU into the iframe so the bridge shim can tag
+  // every postMessage. The parent uses this to look up the calling app's
+  // manifest and resolve short-named functions to script.run / os.open
+  // invocations. (Apps could lie about this in v1 — we trust app code
+  // the same way you trust an npm package.)
+  const safeHcu = String(appHcu || '').replace(/['"\\]/g, '');
+  const hcuConst = `<\x73cript>window.__BITPUB_APP_HCU__='${safeHcu}';<\/script>`;
   // The shim tag uses \x73 + escaped slash so the closing pattern can't
   // be detected by the outer HTML parser. The escapes are transparent to
   // the JS parser but defeat the HTML scanner's greedy script-end match.
   const shim = `<\x73cript>${BRIDGE_SHIM_SOURCE}<\/script>`;
-  const headInject = `${csp}${baseTag}${shim}`;
+  const headInject = `${csp}${baseTag}${hcuConst}${shim}`;
 
   let doc;
   if (/<head[\s>]/i.test(html)) {
@@ -2648,6 +2809,7 @@ const BRIDGE_SHIM_SOURCE = String.raw`
         type: 'bitpub.run',
         requestId: requestId,
         functionId: String(functionId),
+        appHcu: window.__BITPUB_APP_HCU__ || '',
         args: args || {}
       }, '*');
       return requestId;
@@ -2784,13 +2946,151 @@ function bridgeForward(source, requestId, event, payload) {
   } catch (_) { /* iframe gone */ }
 }
 
-function handleBridgeRunMessage(source, msg) {
-  const { requestId, functionId, args } = msg;
+/* ── Manifest-driven app function dispatch ─────────────────────────
+ *
+ * Apps declare their callable functions in a sibling slice named
+ * `manifest.json`. The parent browser shell (this file) reads that
+ * manifest the first time the app calls bitpub.run(), then resolves
+ * every subsequent call to a CLI substrate primitive — without the
+ * CLI needing to know anything about the app.
+ *
+ * Manifest shape:
+ *   {
+ *     "id": "tollbit.github",
+ *     "name": "GitHub Pack",
+ *     "version": "0.1.0",
+ *     "functions": {
+ *       "ingest": {
+ *         "primitive": "script.run",
+ *         "params": {
+ *           "script_hcu": "bitpub://group:tollbit.com/Apps/github/orchestrator",
+ *           "runtime": "python3"
+ *         },
+ *         "env": {
+ *           "BITPUB_GH_ACTION": "ingest",
+ *           "BITPUB_GH_RECIPES": { "from": "args", "key": "recipes", "join": "," },
+ *           "BITPUB_OWNER":      { "from": "identity", "key": "owner" }
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * Field values can be:
+ *   - a literal string                                 → used as-is
+ *   - { from: "args",     key: "...", join?: "," }     → arg-derived
+ *   - { from: "identity", key: "..." }                 → from identity.me()
+ */
+
+const MANIFEST_CACHE = new Map();   // appHcu → Promise<manifest|null>
+const PRIMITIVE_IDS = new Set(['script.run', 'os.open']);
+
+async function loadAppManifest(appHcu) {
+  if (!appHcu) return null;
+  if (MANIFEST_CACHE.has(appHcu)) return MANIFEST_CACHE.get(appHcu);
+  const p = (async () => {
+    const manifestHcu = appHcu + '/manifest.json';
+    try {
+      const u = new URL('/bridge/namespace/list', location.origin);
+      u.searchParams.set('pattern', manifestHcu);
+      u.searchParams.set('fields', 'full');
+      u.searchParams.set('limit', '1');
+      const r = await fetch(u.toString());
+      const body = await r.json();
+      const slice = (body.slices || [])[0];
+      if (!slice || !slice.content) return null;
+      return JSON.parse(slice.content);
+    } catch (_) {
+      return null;
+    }
+  })();
+  MANIFEST_CACHE.set(appHcu, p);
+  return p;
+}
+
+let CACHED_IDENTITY = null;
+async function getIdentityCached() {
+  if (CACHED_IDENTITY) return CACHED_IDENTITY;
+  try {
+    const r = await fetch('/bridge/identity');
+    CACHED_IDENTITY = await r.json();
+  } catch (_) {
+    CACHED_IDENTITY = {};
+  }
+  return CACHED_IDENTITY;
+}
+
+function resolveManifestValue(v, ctx) {
+  if (v == null) return null;
+  // Arrays: resolve each element (used for cli_args).
+  if (Array.isArray(v)) return v.map(x => resolveManifestValue(x, ctx)).filter(x => x != null);
+  if (typeof v !== 'object') return v;                // literal string / number
+  const src = v.from === 'args' ? ctx.args : v.from === 'identity' ? ctx.identity : null;
+  if (!src) return null;
+  // Whole-object reference: { from: "args" } with no key → the entire
+  // object. Useful for shipping all caller args as one JSON env var
+  // (e.g. BRIEF_PAYLOAD). The env serializer downstream auto-stringifies
+  // non-string values, so this Just Works.
+  if (!v.key) return src;
+  let val = src[v.key];
+  if (val == null) return v.default != null ? v.default : null;
+  if (v.join && Array.isArray(val)) val = val.join(v.join);
+  return val;
+}
+
+function resolveManifestFunction(manifest, funcName, args, identity) {
+  if (!manifest || !manifest.functions) throw new Error('app has no manifest');
+  const decl = manifest.functions[funcName];
+  if (!decl) throw new Error(`function "${funcName}" not declared in app manifest`);
+  if (!PRIMITIVE_IDS.has(decl.primitive)) throw new Error(`unknown primitive "${decl.primitive}"`);
+
+  const ctx = { args: args || {}, identity: identity || {} };
+  const params = {};
+  for (const [k, v] of Object.entries(decl.params || {})) {
+    const resolved = resolveManifestValue(v, ctx);
+    if (resolved != null) params[k] = resolved;
+  }
+  if (decl.primitive === 'script.run' && decl.env) {
+    params.env = params.env || {};
+    for (const [k, v] of Object.entries(decl.env)) {
+      const resolved = resolveManifestValue(v, ctx);
+      if (resolved != null) params.env[k] = resolved;
+    }
+  }
+  return { functionId: decl.primitive, args: params };
+}
+
+async function handleBridgeRunMessage(source, msg) {
+  const { requestId, functionId, args, appHcu } = msg;
   if (typeof requestId !== 'number' || !functionId) return;
 
+  // Three paths:
+  //   1. Calling a primitive directly       → passthrough (power users + manifests)
+  //   2. Calling a manifest-declared name   → resolve, then call primitive
+  //   3. Calling a legacy hardcoded name    → passthrough (deprecation path)
+  let resolvedFunctionId = String(functionId);
+  let resolvedArgs = args || {};
+
+  if (!PRIMITIVE_IDS.has(resolvedFunctionId)) {
+    const manifest = await loadAppManifest(appHcu);
+    if (manifest && manifest.functions && manifest.functions[resolvedFunctionId]) {
+      try {
+        const identity = await getIdentityCached();
+        const resolved = resolveManifestFunction(manifest, resolvedFunctionId, resolvedArgs, identity);
+        resolvedFunctionId = resolved.functionId;
+        resolvedArgs = resolved.args;
+      } catch (err) {
+        bridgeForward(source, requestId, 'error', { message: 'manifest resolve: ' + err.message });
+        bridgeForward(source, requestId, 'exit',  { code: 2 });
+        return;
+      }
+    }
+    // else: fall through to legacy CLI passthrough (no manifest, name might
+    // still resolve in the CLI's hardcoded FUNCTIONS list).
+  }
+
   const qs = new URLSearchParams({
-    functionId: String(functionId),
-    args: JSON.stringify(args || {}),
+    functionId: resolvedFunctionId,
+    args: JSON.stringify(resolvedArgs),
   });
 
   let es;
@@ -2802,7 +3102,7 @@ function handleBridgeRunMessage(source, msg) {
     return;
   }
 
-  BRIDGE_RUNS.set(requestId, { es, source, functionId });
+  BRIDGE_RUNS.set(requestId, { es, source, functionId: resolvedFunctionId });
   BRIDGE_RUN_COUNT++;
   updateBridgeBadge();