@bitpub/cli 2.0.2 → 2.0.4

package/src/commands/group.js

@@ -0,0 +1,333 @@
+'use strict';
+
+/**
+ * `bitpub group` — manage groups (shared namespaces).
+ *
+ *   bitpub group create "Acme Engineering"   create a group, print invite link
+ *   bitpub group list                        show groups I'm in
+ *   bitpub group invite <slug>               rotate the share link (or --show to peek)
+ *   bitpub group leave <slug>                leave a group
+ *
+ * Plus the top-level shortcut for the joiner persona — see `bitpub join`,
+ * which is registered as its own top-level command in this file.
+ *
+ * Encryption: group content is plaintext on whatever server hosts the
+ * group (only `private:` slices are client-side encrypted). This is by
+ * design — full-text search, ltree queries, and BYOC audit all need the
+ * server to be able to read group content.
+ */
+
+const axios = require('axios');
+const {
+  readConfig,
+  requireConfig,
+  upsertGroupEntry,
+  removeGroupEntry,
+  groupEntryFor,
+  DEFAULT_CLOUD_URL,
+} = require('../config');
+
+function trimSlash(s) {
+  return String(s || '').replace(/\/+$/, '');
+}
+
+function primaryApiUrl(config) {
+  return trimSlash(config.api_url || DEFAULT_CLOUD_URL);
+}
+
+/**
+ * Parse a join input that may be either a raw invite token or a full
+ * invite URL (e.g. https://bitpub.io/j/9k3lp2-...). Returns:
+ *   { token, baseUrl|null }
+ * where baseUrl is the backend the invite lives on (so cross-backend
+ * joins talk to the right host without any local config tweak).
+ */
+function parseJoinInput(input) {
+  if (!input || typeof input !== 'string') {
+    throw new Error('join: token or invite URL is required');
+  }
+  const trimmed = input.trim();
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    const u = new URL(trimmed);
+    const parts = u.pathname.split('/').filter(Boolean);
+    // Accept both /join/<token> (canonical) and the legacy /j/<token> form
+    // so older invite links keep working during the rename.
+    if ((parts[0] !== 'join' && parts[0] !== 'j') || !parts[1]) {
+      throw new Error(`join: not a recognized invite URL: ${trimmed}`);
+    }
+    return { token: parts[1], baseUrl: `${u.protocol}//${u.host}` };
+  }
+  return { token: trimmed, baseUrl: null };
+}
+
+async function httpJson(method, url, { headers, body } = {}) {
+  try {
+    const res = await axios.request({
+      method,
+      url,
+      timeout: 30_000,
+      headers: { 'content-type': 'application/json', ...(headers || {}) },
+      data: body,
+    });
+    return res.data;
+  } catch (err) {
+    const status = err.response?.status;
+    const msg = err.response?.data?.error || err.message;
+    const wrapped = new Error(status ? `[${status}] ${msg}` : msg);
+    wrapped.status = status;
+    throw wrapped;
+  }
+}
+
+// ── group create ───────────────────────────────────────────────────────────
+
+async function createGroup(display) {
+  const config = requireConfig();
+  if (!config.api_key) {
+    throw new Error('Group creation requires a personal identity. Run `bitpub setup` first.');
+  }
+  const baseUrl = primaryApiUrl(config);
+
+  const data = await httpJson('POST', `${baseUrl}/v1/groups`, {
+    headers: { 'x-api-key': config.api_key },
+    body: { display },
+  });
+
+  // Creators are auto-added to memberships server-side. Mirror the entry
+  // locally so subsequent `bitpub save bitpub://group:.../...` calls hit
+  // the right backend with the same personal key (creator stays on
+  // their own key; the per-group-key mint happens at *accept* time, not
+  // create time, since the creator already has a key on this backend).
+  upsertGroupEntry({
+    slug: data.slug,
+    display: data.display,
+    api_url: baseUrl,
+    key: config.api_key,
+    owner: config.owner || null,
+    role: 'owner',
+    joined_at: new Date().toISOString(),
+  });
+
+  return { ...data, invite_url: data.invite_url, base_url: baseUrl };
+}
+
+// ── group list ─────────────────────────────────────────────────────────────
+
+async function listGroupsLocal() {
+  const config = readConfig() || {};
+  return Array.isArray(config.groups) ? config.groups : [];
+}
+
+// ── group invite (rotate / show) ───────────────────────────────────────────
+
+async function rotateInvite(slug, { show } = {}) {
+  const config = requireConfig();
+  const entry = groupEntryFor(config, slug);
+  if (!entry) {
+    throw new Error(`Not a member of group "${slug}". Run \`bitpub group list\` to see your groups.`);
+  }
+  if (show) {
+    throw new Error('--show is not yet implemented (server does not expose the current token to non-creators by design). Use `bitpub group invite <slug>` to rotate and get a fresh URL.');
+  }
+  const baseUrl = trimSlash(entry.api_url) || primaryApiUrl(config);
+  const data = await httpJson('POST', `${baseUrl}/v1/groups/${encodeURIComponent(slug)}/invites`, {
+    headers: { 'x-api-key': entry.key },
+  });
+  return data;
+}
+
+// ── group leave ────────────────────────────────────────────────────────────
+
+async function leaveGroup(slug) {
+  const config = requireConfig();
+  const entry = groupEntryFor(config, slug);
+  if (!entry) {
+    // Already not in this group locally. Treat as a no-op (idempotent).
+    return { slug, left: false, reason: 'not-in-local-config' };
+  }
+  const baseUrl = trimSlash(entry.api_url) || primaryApiUrl(config);
+  try {
+    await httpJson('DELETE', `${baseUrl}/v1/groups/${encodeURIComponent(slug)}/members/me`, {
+      headers: { 'x-api-key': entry.key },
+    });
+  } catch (err) {
+    // 404 = server already considers us gone; proceed to clean up locally.
+    if (err.status !== 404) throw err;
+  }
+  removeGroupEntry(slug);
+  return { slug, left: true };
+}
+
+// ── bitpub join <token-or-url> ─────────────────────────────────────────────
+//
+// The recipient-side verb. Public, doesn't require a pre-existing identity
+// on the host backend — the invite token is the capability. After accept,
+// stores a new entry in config.groups[] with the fresh per-group key
+// minted by the backend.
+
+async function joinFromInvite(input) {
+  const { token, baseUrl: baseFromUrl } = parseJoinInput(input);
+  const config = readConfig() || {};
+  const baseUrl = baseFromUrl
+    ? trimSlash(baseFromUrl)
+    : primaryApiUrl(config);
+
+  // Optionally include the existing personal key — this lets same-backend
+  // joins inherit the existing owner_id so the user looks like one person
+  // across all their groups on that backend.
+  const headers = {};
+  if (config.api_key && (!baseFromUrl || trimSlash(baseFromUrl) === primaryApiUrl(config))) {
+    headers['x-api-key'] = config.api_key;
+  }
+
+  const data = await httpJson('POST', `${baseUrl}/v1/groups/invites/${encodeURIComponent(token)}/accept`, {
+    headers,
+  });
+
+  upsertGroupEntry({
+    slug: data.group.slug,
+    display: data.group.display,
+    api_url: baseUrl,
+    key: data.api_key,
+    owner: data.owner_id,
+    role: 'member',
+    joined_at: new Date().toISOString(),
+  });
+
+  return { ...data, base_url: baseUrl };
+}
+
+// ── command registration ──────────────────────────────────────────────────
+
+module.exports = function registerGroup(program) {
+  const group = program
+    .command('group')
+    .description('Create, manage, and leave shared groups');
+
+  group
+    .command('create <name...>')
+    .description('Create a new group; prints a shareable invite link')
+    .action(async (nameParts) => {
+      const display = nameParts.join(' ').trim();
+      if (!display) {
+        console.error('Usage: bitpub group create "Acme Engineering"');
+        process.exit(1);
+      }
+      try {
+        const out = await createGroup(display);
+        console.log(`\n✓ Created group: ${out.display}`);
+        console.log(`  Slug      : ${out.slug}`);
+        console.log(`  Hosted on : ${out.hosted_on}`);
+        console.log(`  Address   : bitpub://group:${out.slug}/`);
+        console.log(`\n  Share this link with teammates:`);
+        console.log(`    ${out.invite_url}`);
+        console.log(`\n  Anyone who clicks it lands on a friendly install + join page —`);
+        console.log(`  technical or not, they're ready to collaborate in a minute.`);
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  group
+    .command('list')
+    .description('Show the groups you are a member of (local view)')
+    .action(async () => {
+      try {
+        const entries = await listGroupsLocal();
+        if (entries.length === 0) {
+          console.log('You are not in any groups yet.');
+          console.log('\n  Create one:  bitpub group create "My Team"');
+          console.log('  Join one:    bitpub join <invite-link>');
+          return;
+        }
+        for (const e of entries) {
+          const label = e.display || e.slug;
+          const tag = e.legacy ? '  [legacy]' : '';
+          console.log(`  ${label}${tag}`);
+          console.log(`    slug    : ${e.slug}`);
+          console.log(`    address : bitpub://group:${e.slug}/`);
+          console.log(`    backend : ${e.api_url || '(default)'}`);
+          if (e.role) console.log(`    role    : ${e.role}`);
+        }
+      } catch (err) {
+        console.error(`✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  group
+    .command('invite <slug>')
+    .description('Rotate the shareable invite link for a group')
+    .option('--show', '[not yet implemented] Show the current link without rotating it')
+    .action(async (slug, opts) => {
+      try {
+        const out = await rotateInvite(slug, opts);
+        console.log(`\n✓ Rotated invite for ${out.display || out.slug}`);
+        console.log(`\n  New share link:`);
+        console.log(`    ${out.invite_url}`);
+        console.log(`\n  Old links (if any) are now invalid.`);
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  group
+    .command('leave <slug>')
+    .description('Leave a group (revokes your per-group key on the host)')
+    .action(async (slug) => {
+      try {
+        const out = await leaveGroup(slug);
+        if (out.left) console.log(`✓ Left group: ${slug}`);
+        else console.log(`(Not in group "${slug}" locally — nothing to do.)`);
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // ── group join — longhand alias of top-level `bitpub join` ─────────────
+  group
+    .command('join <tokenOrUrl>')
+    .description('Accept an invite (longhand for `bitpub join`)')
+    .action(async (tokenOrUrl) => {
+      try {
+        const out = await joinFromInvite(tokenOrUrl);
+        console.log(`\n✓ Joined group: ${out.group.display}`);
+        console.log(`  Address : bitpub://group:${out.group.slug}/`);
+        console.log(`  Backend : ${out.base_url}`);
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // ── top-level `bitpub join` — the joiner one-liner ─────────────────────
+  program
+    .command('join <tokenOrUrl>')
+    .description('Accept a group invite link (or token) and start collaborating')
+    .action(async (tokenOrUrl) => {
+      try {
+        const out = await joinFromInvite(tokenOrUrl);
+        console.log(`\n✓ Joined group: ${out.group.display}`);
+        console.log(`  Address : bitpub://group:${out.group.slug}/`);
+        console.log(`  Backend : ${out.base_url}`);
+        console.log(`\nTry it:`);
+        console.log(`  bitpub save bitpub://group:${out.group.slug}/hello "first message"`);
+        console.log(`  bitpub list bitpub://group:${out.group.slug}/`);
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+};
+
+module.exports._internals = {
+  parseJoinInput,
+  createGroup,
+  joinFromInvite,
+  rotateInvite,
+  leaveGroup,
+};

package/src/commands/setup.js

@@ -271,23 +271,36 @@ module.exports = function registerSetup(program) {
     });
 
   // ── 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.
+  // Legacy: join a tenant by pre-shared key + domain. Kept working for
+  // existing enterprise / BYOC deployments. New users use `bitpub join
+  // <invite-link>` instead — that flow mints a fresh per-user key
+  // instead of sharing one.
   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)')
+    .description('[legacy] Join a group by shared key + domain — prefer `bitpub join <invite-link>`')
+    .requiredOption('--key <string>', 'Group API key provided by your group admin')
+    .requiredOption('--domain <string>', 'Group domain (e.g. acme.com) — used as the group slug')
     .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;
 
+      // Build a temporary config the API client will see, with this group
+      // already mirrored into config.groups[] so the verify-pull picks the
+      // right per-group key+url.
+      const probeConfig = {
+        ...existing,
+        api_url: apiUrl,
+        groups: [
+          ...(Array.isArray(existing.groups) ? existing.groups : []).filter((g) => g.slug !== domain),
+          { slug: domain, display: domain, api_url: apiUrl, key, legacy: true },
+        ],
+      };
+
       if (verify) {
         try {
-          const api = createApiClient({ group_key: key, api_url: apiUrl });
+          const api = createApiClient(probeConfig);
           await api.pull(`bitpub://group:${domain}/**`, 1);
           console.log('✓ Key verified against backend');
         } catch (err) {
@@ -296,14 +309,25 @@ module.exports = function registerSetup(program) {
         }
       }
 
-      writeConfig({ ...existing, group_key: key, domain, api_url: apiUrl });
+      // Persist into the new groups[] shape as well as the legacy top-level
+      // fields. Keeping the top-level fields around for one release means
+      // any external script that reads config.group_key keeps working; the
+      // next release can drop them.
+      writeConfig({
+        ...existing,
+        group_key: key,
+        domain,
+        api_url: apiUrl,
+        groups: probeConfig.groups,
+      });
       initCache();
 
-      console.log(`✓ Joined team ${domain}`);
+      console.log(`✓ Joined group ${domain}`);
       console.log(`  Backend : ${apiUrl}`);
       if (existing.owner) {
         console.log(`  Private : agent_${existing.owner} (preserved)`);
       }
+      console.error('warning: `bitpub setup team` is the legacy flow. New invites use `bitpub join <link>` instead.');
       console.log('\nNext: bitpub sync "bitpub://group:' + domain + '/**"');
     });
 

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),
     },
   };

package/src/config.js

@@ -21,11 +21,51 @@ function ensureDir() {
 }
 
 function readConfig() {
+  let parsed;
   try {
-    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+    parsed = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
   } catch {
     return null;
   }
+  return _migrateLegacyGroupFieldsInPlace(parsed);
+}
+
+/**
+ * Lazy one-shot migration of the pre-v2 top-level `group_key` + `domain`
+ * fields into a single entry in the new `groups` array. We keep the
+ * top-level fields for one release as a safety net so any caller that
+ * still reads them keeps working — they'll be dropped in a follow-up.
+ *
+ * Idempotent: if a matching entry already exists in `groups`, we do
+ * nothing. Only persists back to disk when an actual change was made.
+ */
+function _migrateLegacyGroupFieldsInPlace(config) {
+  if (!config || typeof config !== 'object') return config;
+  if (!Array.isArray(config.groups)) config.groups = [];
+
+  const hasLegacyTopLevel = config.group_key && config.domain;
+  if (!hasLegacyTopLevel) return config;
+
+  const alreadyMigrated = config.groups.some((g) => g && g.slug === config.domain);
+  if (alreadyMigrated) return config;
+
+  config.groups.push({
+    slug: config.domain,
+    display: config.domain,
+    api_url: config.api_url,
+    key: config.group_key,
+    owner: config.owner || null,
+    joined_at: new Date().toISOString(),
+    legacy: true,
+  });
+
+  try {
+    ensureDir();
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+  } catch {
+    // Non-fatal: in-memory copy is still correct for this process.
+  }
+  return config;
 }
 
 function writeConfig(config) {
@@ -35,16 +75,55 @@ function writeConfig(config) {
 
 /**
  * Identity is valid if api_url is present and at least one of these is true:
- *   - private identity: api_key + owner  (provisioned by `bitpub init`)
- *   - group identity:   group_key + domain  (set by `bitpub auth login`)
- *   - legacy single-key: api_key + domain  (old config shape, still supported)
+ *   - private identity:  api_key + owner    (provisioned by `bitpub setup`)
+ *   - group membership:  any entry in groups[]  (added by `bitpub join`)
+ *   - legacy group key:  group_key + domain  (pre-v2 top-level fields)
+ *   - legacy single-key: api_key + domain    (oldest single-tenant shape)
  */
 function isConfigured(config) {
   if (!config || !config.api_url) return false;
   const hasPrivate = Boolean(config.api_key && config.owner);
-  const hasGroup   = Boolean(config.group_key && config.domain);
-  const hasLegacy  = Boolean(config.api_key && config.domain);
-  return hasPrivate || hasGroup || hasLegacy;
+  const hasGroup   = Array.isArray(config.groups) && config.groups.length > 0;
+  const hasLegacyG = Boolean(config.group_key && config.domain);
+  const hasLegacyS = Boolean(config.api_key && config.domain);
+  return hasPrivate || hasGroup || hasLegacyG || hasLegacyS;
+}
+
+/**
+ * Look up the local config entry for a given group slug. Returns null if
+ * the user isn't a member. Used by the API client to route writes to the
+ * correct backend with the correct per-group key.
+ */
+function groupEntryFor(config, slug) {
+  if (!config || !Array.isArray(config.groups)) return null;
+  return config.groups.find((g) => g && g.slug === slug) || null;
+}
+
+/**
+ * Add (or replace) a group entry in the config. Idempotent — re-joining
+ * an existing group overwrites the prior entry (which is what happens
+ * server-side too: accept-invite mints a fresh key, the old one is left
+ * orphaned but still works).
+ */
+function upsertGroupEntry(entry) {
+  if (!entry || !entry.slug) throw new Error('upsertGroupEntry: slug is required');
+  const config = readConfig() || {};
+  if (!Array.isArray(config.groups)) config.groups = [];
+  const idx = config.groups.findIndex((g) => g && g.slug === entry.slug);
+  if (idx === -1) config.groups.push(entry);
+  else config.groups[idx] = { ...config.groups[idx], ...entry };
+  writeConfig(config);
+  return config;
+}
+
+function removeGroupEntry(slug) {
+  const config = readConfig() || {};
+  if (!Array.isArray(config.groups)) return false;
+  const idx = config.groups.findIndex((g) => g && g.slug === slug);
+  if (idx === -1) return false;
+  config.groups.splice(idx, 1);
+  writeConfig(config);
+  return true;
 }
 
 /**
@@ -79,6 +158,9 @@ module.exports = {
   requireConfig,
   isConfigured,
   authorIdFor,
+  groupEntryFor,
+  upsertGroupEntry,
+  removeGroupEntry,
   BITPUB_DIR,
   CONFIG_FILE,
   DEFAULT_CLOUD_URL,