@bitpub/cli 2.0.0

package/src/workspace.js

@@ -0,0 +1,377 @@
+'use strict';
+
+/**
+ * Folder anchors — the small piece of state that ties a folder on disk
+ * to a stable private address, so the same short name ("notes") always
+ * resolves to the same slice when the user is sitting in that folder.
+ *
+ *   ~/projects/billing-svc   →  bitpub://private:agent_xyz/Projects/billing-svc/
+ *
+ * Anchors live in ~/.bitpub/config.json under `folderAnchors`. This is a
+ * deliberate change from earlier releases, which stored a `.bitpub/workspace.json`
+ * marker inside each project folder:
+ *
+ *   - No clutter inside git checkouts.
+ *   - One file to back up / sync / inspect; the agent already has it.
+ *   - Anchors survive `git clean -fdx`, branch resets, fresh clones.
+ *
+ * Schema (one entry per anchored folder):
+ *
+ *   {
+ *     "folderAnchors": {
+ *       "/Users/alice/projects/q3-launch": {
+ *         "id":         "ws_q3-launch_abc12345",
+ *         "namespace":  "bitpub://private:agent_xyz/Projects/q3-launch/",
+ *         "label":      "q3-launch",
+ *         "created_at": "2026-05-11T...Z",
+ *         "group_link": null
+ *       }
+ *     }
+ *   }
+ *
+ * Resolution rules:
+ *   1. Walk up from cwd. If a key in `folderAnchors` matches, use its
+ *      `namespace`. Stop at $HOME — we never anchor $HOME.
+ *   2. On the same walk, find any legacy `.bitpub/workspace.json` (or
+ *      ancient `.tollbit/workspace.json`) marker, migrate it into
+ *      folderAnchors, delete the marker file, and return.
+ *   3. Otherwise fall back to `bitpub://private:<owner>/Sessions/<YYYY-MM-DD>/`,
+ *      which captures ad-hoc work outside any project folder.
+ *
+ * Group access bypasses all of this: any `bitpub://group:...` URL goes
+ * through unchanged. Anchors only short-circuit *unqualified* names.
+ *
+ * NOTE on the term "workspace" in this file:
+ *   The user-facing word is now "project" everywhere — in CLI output, in
+ *   the browser, in agent docs. Internally we still call it a "workspace"
+ *   because that's what the public function names have been since v1
+ *   and renaming them is a separate, much larger refactor.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const crypto = require('crypto');
+const { isAliasRef, expandAlias } = require('./aliases');
+const { readConfig, writeConfig } = require('./config');
+
+const LEGACY_MARKER_DIRNAME = '.bitpub';
+const LEGACY_TOLLBIT_DIRNAME = '.tollbit';
+const LEGACY_MARKER_FILE = 'workspace.json';
+
+const PROJECTS_PATH_SEGMENT = 'Projects';
+
+function legacyMarkerPath(rootDir) {
+  return path.join(rootDir, LEGACY_MARKER_DIRNAME, LEGACY_MARKER_FILE);
+}
+
+function olderTollbitMarkerPath(rootDir) {
+  return path.join(rootDir, LEGACY_TOLLBIT_DIRNAME, LEGACY_MARKER_FILE);
+}
+
+/**
+ * Canonicalize an absolute path: resolve symlinks via realpathSync so
+ * `/tmp/foo` and `/private/tmp/foo` (the same folder on macOS) compare
+ * equal as anchor keys. Falls back to `path.resolve` for paths that
+ * don't yet exist (e.g. a folder that will be created in this call).
+ *
+ * This matters because `process.cwd()` reports the post-symlink path
+ * while `mkdir`/`mkdtempSync` may have returned the pre-symlink one —
+ * without this normalization the same folder could end up with two
+ * separate anchors in the config.
+ */
+function canonicalPath(p) {
+  const resolved = path.resolve(p);
+  try { return fs.realpathSync(resolved); }
+  catch { return resolved; }
+}
+
+function _normalizeNamespaceString(ns) {
+  if (typeof ns !== 'string') return ns;
+  return ns.replace(/^tollbit:\/\//, 'bitpub://');
+}
+
+function _normalizeMarker(m) {
+  if (!m || typeof m !== 'object') return null;
+  if (typeof m.namespace !== 'string') return null;
+  if (m.namespace.startsWith('tollbit://')) {
+    return { ...m, namespace: _normalizeNamespaceString(m.namespace) };
+  }
+  return m;
+}
+
+// ── folderAnchors map in config.json ────────────────────────────────────────
+
+function readAnchors() {
+  const config = readConfig() || {};
+  return config.folderAnchors && typeof config.folderAnchors === 'object'
+    ? config.folderAnchors
+    : {};
+}
+
+function _writeAnchors(map) {
+  const config = readConfig() || {};
+  config.folderAnchors = map;
+  writeConfig(config);
+}
+
+function setAnchor(rootDir, marker) {
+  const map = readAnchors();
+  map[canonicalPath(rootDir)] = marker;
+  _writeAnchors(map);
+}
+
+function deleteAnchor(rootDir) {
+  const map = readAnchors();
+  const key = canonicalPath(rootDir);
+  if (!(key in map)) return false;
+  delete map[key];
+  _writeAnchors(map);
+  return true;
+}
+
+// ── one-time migration: in-project marker file → folderAnchors map ──────────
+
+function _safeReadMarkerFile(file) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (raw && typeof raw.namespace === 'string') return raw;
+  } catch { /* corrupt — ignore */ }
+  return null;
+}
+
+function _migrateLegacyMarker(rootDir, marker, sourcePath) {
+  const normalized = { ...marker, namespace: _normalizeNamespaceString(marker.namespace) };
+  setAnchor(rootDir, normalized);
+
+  // Best-effort cleanup. If we can't delete the marker file (read-only fs,
+  // permissions, etc.) the worst case is that subsequent runs re-migrate
+  // it — idempotent and harmless.
+  try {
+    fs.unlinkSync(sourcePath);
+    const dir = path.dirname(sourcePath);
+    try {
+      const remaining = fs.readdirSync(dir);
+      if (remaining.length === 0) fs.rmdirSync(dir);
+    } catch { /* dir not empty — leave it */ }
+  } catch { /* couldn't delete — leave the marker, anchor still works */ }
+
+  if (process.env.BITPUB_QUIET !== '1') {
+    const relMarker = path.relative(rootDir, sourcePath) || sourcePath;
+    console.error(
+      `[bitpub] moved folder anchor: ${relMarker} → ~/.bitpub/config.json  (no more in-project clutter)`
+    );
+  }
+
+  return normalized;
+}
+
+// ── walk up from cwd looking for an anchor ──────────────────────────────────
+
+/**
+ * Walk up from `start` looking for either a configured anchor (in
+ * ~/.bitpub/config.json) or a legacy marker file (which gets migrated on
+ * the fly). Returns `{ root, marker, legacy }` or `null`.
+ *
+ * Deliberately bails at $HOME: a top-level home anchor would silently
+ * capture every shell session, which is almost never what the user wants.
+ */
+function findWorkspace(start = process.cwd()) {
+  const home = canonicalPath(os.homedir());
+  const anchors = readAnchors();
+  let dir = canonicalPath(start);
+
+  while (true) {
+    if (Object.prototype.hasOwnProperty.call(anchors, dir)) {
+      const marker = _normalizeMarker(anchors[dir]);
+      if (marker) return { root: dir, marker, legacy: false };
+    }
+
+    const legacy1 = legacyMarkerPath(dir);
+    if (fs.existsSync(legacy1)) {
+      const parsed = _safeReadMarkerFile(legacy1);
+      if (parsed) {
+        const migrated = _migrateLegacyMarker(dir, parsed, legacy1);
+        return { root: dir, marker: migrated, legacy: true };
+      }
+    }
+
+    const legacy2 = olderTollbitMarkerPath(dir);
+    if (fs.existsSync(legacy2)) {
+      const parsed = _safeReadMarkerFile(legacy2);
+      if (parsed) {
+        const migrated = _migrateLegacyMarker(dir, parsed, legacy2);
+        return { root: dir, marker: migrated, legacy: true };
+      }
+    }
+
+    if (dir === home) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// ── creating a new anchor ───────────────────────────────────────────────────
+
+/**
+ * Slugify a folder name into something safe to embed in a URL path:
+ * lowercase, hyphen-separated, ASCII only.
+ */
+function slugify(name) {
+  const slug = String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64);
+  return slug || 'project';
+}
+
+function generateWorkspaceId(slug) {
+  const rand = crypto.randomBytes(4).toString('hex');
+  return `ws_${slug.slice(0, 24)}_${rand}`;
+}
+
+/**
+ * Create or return an anchor for `rootDir`. Idempotent unless `force`
+ * is set: if there's already an anchor for this folder (in
+ * folderAnchors OR a legacy marker we'd auto-migrate), we return it
+ * unchanged.
+ *
+ * The returned shape is intentionally the same as before the move from
+ * marker files: `{ root, marker, created }`. Callers don't need to
+ * know where the anchor is stored.
+ */
+function createWorkspace(rootDir, ownerId, { force = false, label } = {}) {
+  if (!ownerId) throw new Error('createWorkspace: ownerId is required');
+
+  const home = canonicalPath(os.homedir());
+  const resolvedRoot = canonicalPath(rootDir);
+  if (resolvedRoot === home) {
+    throw new Error(
+      'Refusing to anchor $HOME as a project. Pick a project folder instead.'
+    );
+  }
+
+  if (!force) {
+    // findWorkspace will surface either a configured anchor or migrate a
+    // legacy marker at this exact dir, so the caller gets the existing
+    // state without duplicates.
+    const existing = findWorkspace(resolvedRoot);
+    if (existing && existing.root === resolvedRoot) {
+      return { root: resolvedRoot, marker: existing.marker, created: false };
+    }
+  }
+
+  const displayLabel = label || path.basename(resolvedRoot);
+  const slug = slugify(displayLabel);
+  const id = generateWorkspaceId(slug);
+  const namespace = `bitpub://private:${ownerId}/${PROJECTS_PATH_SEGMENT}/${slug}/`;
+
+  const marker = {
+    id,
+    namespace,
+    label: displayLabel,
+    created_at: new Date().toISOString(),
+    group_link: null,
+  };
+
+  setAnchor(resolvedRoot, marker);
+  return { root: resolvedRoot, marker, created: true };
+}
+
+// ── computed namespaces / hcu resolution ───────────────────────────────────
+
+/**
+ * Compute the namespace for short-name resolution given current cwd.
+ * Returns `{ namespace, source, workspace }` where `source` is:
+ *   - 'workspace'        : a project anchor was found (`workspace` set)
+ *   - 'session-default'  : fell back to per-day private session bucket
+ * Returns `null` if no owner is configured and no anchor was found.
+ */
+function activeNamespace(config, cwd = process.cwd()) {
+  const ws = findWorkspace(cwd);
+  if (ws) {
+    return { namespace: ws.marker.namespace, source: 'workspace', workspace: ws };
+  }
+
+  if (!config || !config.owner) return null;
+
+  const today = new Date().toISOString().slice(0, 10);
+  const namespace = `bitpub://private:${config.owner}/Sessions/${today}/`;
+  return { namespace, source: 'session-default', workspace: null };
+}
+
+/**
+ * Turn a short name like "notes" into a fully-qualified address. Resolution
+ * rules, in order:
+ *
+ *   1. `@alias/...`      → expand against ~/.bitpub/aliases.json
+ *   2. `bitpub://...`    → use verbatim (no rewriting, ever)
+ *   3. `/Memory/notes`   → private-root: prefix with bitpub://private:<owner>
+ *                          (this is what `save` suggestions point at, so
+ *                          the agent can paste them back without thinking)
+ *   4. `notes`           → project-relative, resolved through the active anchor
+ *
+ * Rule 3 exists specifically so the suggestions block in `save`'s output
+ * (`/Memory/notes`, `/Inbox/notes`, ...) can be copy-pasted into a follow-up
+ * `bitpub save /Memory/notes` without re-qualifying to a full URL.
+ */
+function resolveHcu(nameOrHcu, config, cwd = process.cwd()) {
+  if (typeof nameOrHcu !== 'string' || nameOrHcu.length === 0) {
+    throw new Error('resolveHcu: name is required');
+  }
+
+  if (isAliasRef(nameOrHcu)) {
+    return { hcu: expandAlias(nameOrHcu), source: 'alias', workspace: null };
+  }
+
+  if (nameOrHcu.startsWith('bitpub://')) {
+    return { hcu: nameOrHcu, source: 'explicit', workspace: null };
+  }
+
+  if (nameOrHcu.startsWith('/')) {
+    if (!config || !config.owner) {
+      throw new Error(
+        'Cannot resolve "' + nameOrHcu + '": absolute paths require a private identity. ' +
+        'Run `bitpub setup` first, or pass a full bitpub:// URL.'
+      );
+    }
+    const trimmed = nameOrHcu.replace(/^\/+/, '');
+    return {
+      hcu: `bitpub://private:${config.owner}/${trimmed}`,
+      source: 'private-root',
+      workspace: null,
+    };
+  }
+
+  const active = activeNamespace(config, cwd);
+  if (!active) {
+    throw new Error(
+      'Cannot resolve "' + nameOrHcu + '": no project anchored here and no identity configured. ' +
+      'Run `bitpub setup` first.'
+    );
+  }
+
+  const trimmed = nameOrHcu.replace(/^\/+/, '');
+  return {
+    hcu: active.namespace + trimmed,
+    source: active.source,
+    workspace: active.workspace,
+  };
+}
+
+module.exports = {
+  // Public API
+  findWorkspace,
+  createWorkspace,
+  activeNamespace,
+  resolveHcu,
+  slugify,
+  canonicalPath,
+  PROJECTS_PATH_SEGMENT,
+  // Anchor map helpers (used by setup, tests, future admin commands)
+  readAnchors,
+  setAnchor,
+  deleteAnchor,
+};