@bitpub/cli 2.0.3 → 2.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitpub/cli",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "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"
@@ -14,7 +14,7 @@
   ],
   "scripts": {
     "test": "jest --testPathPattern=tests/ --forceExit",
-    "prepack": "mkdir -p static && cp ../backend/static/console.html static/console.html",
+    "prepack": "mkdir -p static/assets && cp ../backend/static/console.html static/console.html && cp ../backend/static/welcome.html static/welcome.html && cp ../backend/static/assets/tollbit-icon.png ../backend/static/assets/BITPUB-dark.png static/assets/",
     "prepublishOnly": "npm test"
   },
   "engines": {

package/src/commands/browser.js

@@ -46,27 +46,29 @@ function decryptSlice(slice, apiKey) {
 }
 
 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.
+  // Resolution order:
   //
-  //   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.
+  //   1. backend/static/console.html — the workspace file, only present
+  //      in a checked-out clone. Preferred when present so iterating on
+  //      the UI doesn't require a `prepack` round-trip between edits.
+  //      Production installs (npm tarball) don't ship the `backend/`
+  //      folder, so this candidate is absent there and the resolver
+  //      falls through.
+  //   2. cli/static/console.html — populated by `prepack` from
+  //      `backend/static/console.html` and shipped inside the CLI
+  //      tarball. This is the canonical location at runtime for
+  //      installed CLIs.
   //   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.
+  //      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(__dirname, '../../static/console.html'),
     path.join(BITPUB_DIR, 'console.html'),
   ];
   for (const p of candidates) {
@@ -75,6 +77,37 @@ function resolveBrowserHtmlPath() {
   return null;
 }
 
+// Mirror of `resolveBrowserHtmlPath` for the bundled asset directory.
+// Both the dev clone and the npm tarball place assets under
+// `static/assets/` next to `console.html`, so we look in the same order:
+// workspace first (so the browser picks up edits to PNGs without a
+// `prepack` round-trip), then the prepacked CLI copy.
+function resolveAssetsDir() {
+  const candidates = [
+    path.join(__dirname, '../../../backend/static/assets'),
+    path.join(__dirname, '../../static/assets'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+// Tiny extension → Content-Type table covering the asset types the
+// console actually uses. Falls back to application/octet-stream so an
+// unknown extension downloads instead of being interpreted.
+const ASSET_MIME = {
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif':  'image/gif',
+  '.webp': 'image/webp',
+  '.svg':  'image/svg+xml',
+  '.ico':  'image/x-icon',
+  '.mp4':  'video/mp4',
+  '.webm': 'video/webm',
+};
+
 function openInBrowser(url) {
   const cmd = process.platform === 'darwin' ? 'open' :
     process.platform === 'win32' ? 'start' : 'xdg-open';
@@ -110,7 +143,21 @@ function startBrowserServer(opts = {}) {
       return reject(err);
     }
 
-    const htmlTemplate = fs.readFileSync(htmlPath, 'utf-8');
+    // Cache the HTML at startup, but if the resolver picked the workspace
+    // copy (developer iterating on the UI), re-read on every request so
+    // edits show up on a simple browser refresh — no server restart
+    // needed. The installed-tarball path stays cached because its file
+    // never changes between sessions.
+    const workspaceHtml = path.join(__dirname, '../../../backend/static/console.html');
+    const isWorkspaceCopy = path.resolve(htmlPath) === path.resolve(workspaceHtml);
+    const cachedHtml = fs.readFileSync(htmlPath, 'utf-8');
+    function loadHtml() {
+      if (!isWorkspaceCopy) return cachedHtml;
+      try { return fs.readFileSync(htmlPath, 'utf-8'); }
+      catch { return cachedHtml; }
+    }
+
+    const assetsDir = resolveAssetsDir();
 
     const server = http.createServer((req, res) => {
       const url = new URL(req.url, `http://localhost:${port}`);
@@ -132,7 +179,34 @@ function startBrowserServer(opts = {}) {
 
       if (url.pathname === '/' || url.pathname === '/index.html') {
         res.setHeader('Content-Type', 'text/html; charset=utf-8');
-        res.end(htmlTemplate);
+        res.end(loadHtml());
+        return;
+      }
+
+      // Static assets: serve files from `static/assets/` for any
+      // `/assets/<name>` request. We resolve+contain inside the assets
+      // dir to defend against `../`-style traversal, fail closed if the
+      // asset dir doesn't exist, and only serve known image/video MIME
+      // types so this can't accidentally double as a generic file
+      // server.
+      if (url.pathname.startsWith('/assets/')) {
+        if (!assetsDir) { res.statusCode = 404; res.end('Not found'); return; }
+        const rel = url.pathname.replace(/^\/assets\//, '');
+        const full = path.resolve(assetsDir, rel);
+        if (!full.startsWith(path.resolve(assetsDir) + path.sep)) {
+          res.statusCode = 403; res.end('Forbidden'); return;
+        }
+        const ext = path.extname(full).toLowerCase();
+        const mime = ASSET_MIME[ext];
+        if (!mime) { res.statusCode = 415; res.end('Unsupported Media Type'); return; }
+        fs.readFile(full, (err, data) => {
+          if (err) { res.statusCode = 404; res.end('Not found'); return; }
+          res.setHeader('Content-Type', mime);
+          // Short cache so iterating on PNGs (which we re-read from
+          // the workspace in dev) doesn't get pinned to a stale copy.
+          res.setHeader('Cache-Control', 'public, max-age=60');
+          res.end(data);
+        });
         return;
       }
 

package/src/commands/load.js

@@ -12,7 +12,23 @@
  *      "did you mean…" search across the user's full private namespace.
  *      With exactly one match, auto-load and print a transparency note to
  *      stderr saying where it actually came from. With multiple, list
- *      them and exit. With zero, print an actionable not-found error.
+ *      them and exit. With zero, fall through.
+ *   4. If still empty, check whether the address is a *folder* — i.e. it
+ *      has descendants under it — and if so, auto-load them in one shot.
+ *      Capped at `--limit` (default 20) so a stray `load` on a deep
+ *      prefix can't blow up output. A stderr breadcrumb tells the caller
+ *      what we did and (if truncated) how to get the rest. This catches
+ *      the common mistake of `load`-ing a prefix like
+ *      `bitpub://group:foo/Agents/x` when the real slices live at
+ *      `.../Agents/x/README`, `.../script`, etc. A single wildcard
+ *      remote pull is attempted on cache miss so this works without a
+ *      separate `sync` step.
+ *   5. Otherwise: actionable not-found error.
+ *
+ * Multi-slice raw output (from explicit wildcards or from the folder
+ * auto-load in step 4) is prefixed with a `=== <address> ===` header
+ * per slice so the caller can tell which content came from which slice.
+ * Single-slice loads keep their clean stdout-only output (no header).
  *
  * The DWIM step exists because agents holding a fully-qualified URL will
  * sometimes (incorrectly) strip it down to a short name before calling
@@ -33,6 +49,11 @@ module.exports = function registerLoad(program) {
     .description('Load a slice by short name (this project) or full bitpub:// address')
     .option('--no-fetch', 'Do not fetch from cloud if missing locally')
     .option('--format <raw|json>', 'Output format', 'raw')
+    .option(
+      '--limit <n>',
+      'Max slices to return when the address resolves to a folder (default 20)',
+      '20'
+    )
     .action(async (name, opts) => {
       const config = requireConfig();
       const wasShortName = !name.startsWith('bitpub://') && !isAliasRef(name);
@@ -84,7 +105,58 @@ module.exports = function registerLoad(program) {
           console.error(`  bitpub load <one-of-the-addresses-above>`);
           process.exit(1);
         }
-        // Zero candidates: fall through to the not-found block below.
+        // Zero candidates: fall through to the folder/not-found block below.
+      }
+
+      // Folder check: the exact address didn't resolve to a slice, but it
+      // may be a *prefix* with children under it (e.g. user typed
+      // `bitpub://group:foo/Agents/x` when the real slices live at
+      // `.../Agents/x/README`, `.../script`, etc). Auto-load up to
+      // --limit children so the caller doesn't have to round-trip.
+      // Skip if the user already passed a wildcard — querySlices already
+      // handles that path and a 0-result wildcard is a real not-found.
+      if (slices.length === 0 && !hcu.includes('*')) {
+        const cleanHcu = hcu.replace(/\/$/, '');
+        const folderPattern = cleanHcu + '/**';
+        // Cap raised slightly above the user-facing default so a folder
+        // with N=21 items doesn't get silently truncated below the cap
+        // the user asked for; we still slice() to `limit` for display.
+        const limit = Math.max(1, parseInt(opts.limit, 10) || 20);
+        let descendants = querySlices(folderPattern);
+
+        if (descendants.length === 0 && opts.fetch !== false) {
+          try {
+            const api = createApiClient(config);
+            const remote = await api.pull(folderPattern, Math.max(limit, 50));
+            decryptSlices(remote, config.api_key);
+            remote.forEach(upsertSlice);
+            descendants = querySlices(folderPattern);
+          } catch {
+            // Non-fatal — if there's nothing remote either, we'll fall
+            // through to the regular not-found message below.
+          }
+        }
+
+        if (descendants.length > 0) {
+          const total = descendants.length;
+          const truncated = total > limit;
+          slices = descendants.slice(0, limit);
+
+          // Transparency breadcrumb → stderr (keeps stdout pure for pipes).
+          // The agent gets a single useful message that tells it (a) what
+          // we did and (b) how to escape the cap if 20 wasn't enough.
+          if (truncated) {
+            console.error(
+              `(loaded ${slices.length} of ${total} descendants of "${cleanHcu}" — ` +
+              `it's a folder, not a slice; pass --limit ${total} for all of them)`
+            );
+          } else {
+            console.error(
+              `(loaded ${slices.length} descendant${slices.length === 1 ? '' : 's'} of ` +
+              `"${cleanHcu}" — it's a folder, not a slice)`
+            );
+          }
+        }
       }
 
       if (slices.length === 0) {
@@ -113,10 +185,15 @@ module.exports = function registerLoad(program) {
         return;
       }
 
+      // Multi-slice raw output (wildcard input or folder auto-load) gets
+      // a `=== <address> ===` header per slice so the caller can attribute
+      // each chunk. Single-slice loads keep their clean header-free output.
       const parts = slices.map(s => {
         const payload = JSON.parse(s.payload);
-        return payload.content ?? '';
+        const content = payload.content ?? '';
+        if (slices.length === 1) return content;
+        return `=== ${s.hcu} ===\n${content}`;
       });
-      console.log(parts.join('\n---\n'));
+      console.log(parts.join(slices.length === 1 ? '' : '\n\n'));
     });
 };

package/src/commands/welcome.js

@@ -8,6 +8,9 @@
  *      address (`bitpub://private:<owner>/Welcome`). This is proof to a
  *      non-technical user that the round trip works: an identity got
  *      provisioned, encryption is set up, and reads/writes hit the cloud.
+ *      The slice payload is an HTML app (a "Pack" entry-point); the
+ *      browser renders it in a sandboxed iframe. The whole welcome
+ *      experience is the slice — no separate panel in the chrome.
  *
  *   2. With `--serve`, start the local browser UI and open a tab to the
  *      welcome slice. This is what install.sh calls so the very first thing
@@ -24,7 +27,9 @@
  * once, the first time the user sets up BitPub on this machine.
  */
 
-const { requireConfig, readConfig, writeConfig, authorIdFor } = require('../config');
+const fs = require('fs');
+const path = require('path');
+const { requireConfig, readConfig, writeConfig, authorIdFor, BITPUB_DIR } = require('../config');
 const { createApiClient } = require('../api');
 const { upsertSlice } = require('../db/cache');
 const { encrypt, decryptSlices } = require('../crypto');
@@ -36,13 +41,60 @@ function welcomeAddressFor(owner) {
   return `bitpub://private:${owner}/${WELCOME_SLICE_NAME}`;
 }
 
+/**
+ * Resolve the welcome.html template path. Mirrors `resolveBrowserHtmlPath`
+ * in commands/browser.js — workspace first (so edits to the template apply
+ * without a `prepack` round-trip), then the prepacked CLI copy, then the
+ * last-resort ~/.bitpub cache. Returns null if no template is on disk
+ * (in which case we fall back to a markdown welcome — see below).
+ */
+function resolveWelcomeTemplatePath() {
+  const candidates = [
+    path.join(__dirname, '../../../backend/static/welcome.html'),
+    path.join(__dirname, '../../static/welcome.html'),
+    path.join(BITPUB_DIR, 'welcome.html'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Build the welcome slice payload. Returns `{ content, format }`.
+ *
+ * Prefers the HTML app template at `backend/static/welcome.html`. That
+ * template contains a single substitution token, `__OWNER__`, which is
+ * replaced with the user's owner ID so the address shown in the page
+ * matches the slice's actual address. The HTML is rendered by the
+ * browser inside a sandboxed iframe (no network, no storage).
+ *
+ * If the template is not on disk (older installs, partial unpacks), falls
+ * back to a short markdown welcome so the round-trip proof still works.
+ */
 function buildWelcomeContent(config) {
   const owner = config.owner || '<your-owner>';
+
+  const templatePath = resolveWelcomeTemplatePath();
+  if (templatePath) {
+    try {
+      const html = fs.readFileSync(templatePath, 'utf-8');
+      // Replace the single substitution token. We use a placeholder rather
+      // than a string template so the template stays a syntactically valid
+      // standalone HTML file you can open directly in a browser for design
+      // iteration.
+      const content = html.replace(/__OWNER__/g, owner);
+      return { content, format: 'text/html' };
+    } catch (_) {
+      // fall through to markdown fallback
+    }
+  }
+
+  // Fallback markdown content. Shorter than the HTML app and not as
+  // visually polished, but works in every renderer and still proves the
+  // round trip.
   const address = welcomeAddressFor(owner);
-  // Plain markdown — the browser UI renders the slice content directly.
-  // Keep it short, friendly, and oriented toward the three workflows we
-  // want non-technical users to discover next: skills, sharing, building.
-  return [
+  const content = [
     '# Welcome to BitPub',
     '',
     'Your install worked. **This page is your first saved memory** — a slice',
@@ -102,6 +154,7 @@ function buildWelcomeContent(config) {
     'own. Close this tab whenever you\'re ready.',
     '',
   ].join('\n');
+  return { content, format: 'text/markdown' };
 }
 
 async function saveWelcomeSlice(config, { force } = {}) {
@@ -111,7 +164,7 @@ async function saveWelcomeSlice(config, { force } = {}) {
   }
 
   const address = welcomeAddressFor(config.owner);
-  const content = buildWelcomeContent(config);
+  const { content, format } = buildWelcomeContent(config);
   const api = createApiClient(config);
 
   const body = {
@@ -122,7 +175,7 @@ async function saveWelcomeSlice(config, { force } = {}) {
       tags: ['welcome', 'onboarding'],
     },
     payload: {
-      format: 'text/markdown',
+      format,
       content: encrypt(content, config.api_key),
     },
   };