total-recall-brain 3.40.0 → 3.40.2

package/scaffold/.agent/skills/total-recall/plugins/composable-cli/src/registry.mjs

@@ -0,0 +1,192 @@
+/**
+ * Command Registry — cli_command SSSS documents, history, rollback
+ *
+ * Each registered command has a sibling <name>.md SSSS document beside its
+ * <name>.mjs file. History is kept in <scope dir>/commands/.history/<name>/<version>.mjs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+import { EXIT_CODES } from './contract.mjs';
+import { validateRisk } from './risk.mjs';
+import { writeCommandDocument, parseDocument } from './ssss-documents.mjs';
+
+
+/**
+ * Write the cli_command SSSS document for a command.
+ *
+ * @param {object} options
+ * @param {string} options.name - Command name
+ * @param {string} options.commandsDir - Directory containing the command
+ * @param {'project'|'group'|'global'} [options.scope]
+ * @param {string} [options.ownerProject]
+ * @param {string} [options.group]
+ * @param {string} [options.risk]
+ * @param {number} [options.version]
+ * @param {string} [options.author]
+ * @param {string} [options.description]
+ * @param {boolean} [options.background]
+ * @param {string} [options.source]
+ * @returns {object} The written registry document
+ */
+export function writeRegistry(options = {}) {
+  const {
+    name,
+    commandsDir,
+    scope = 'project',
+    ownerProject,
+    group,
+    risk = 'write',
+    version = 1,
+    author = process.env.AGENT_ID || 'unknown',
+    description = '',
+    background = false,
+    source = 'inline',
+  } = options;
+
+  const cmdFile = path.join(commandsDir, `${name}.mjs`);
+  if (!fs.existsSync(cmdFile)) {
+    const err = new Error(`Command '${name}' does not exist in ${commandsDir}.`);
+    err.exitCode = EXIT_CODES.ERROR;
+    throw err;
+  }
+
+  validateRisk(risk);
+
+  const now = new Date().toISOString();
+  const previous = readRegistry(name, commandsDir);
+  const code = fs.readFileSync(cmdFile, 'utf8');
+  const sha = crypto.createHash('sha256').update(code).digest('hex');
+
+  const doc = {
+    ...previous,
+    type: 'cli_command',
+    id: previous?.id || randomUUID(),
+    name,
+    scope,
+    risk,
+    version,
+    author,
+    created: previous?.created || now,
+    updated: now,
+    description,
+    background_allowed: background,
+    code_sha256: sha,
+    source,
+  };
+
+  // Optional fields
+  if (ownerProject) doc.owner_project = ownerProject;
+  if (group) doc.group = group;
+
+  const docPath = path.join(commandsDir, `${name}.md`);
+  fs.mkdirSync(commandsDir, { recursive: true });
+  const prose = fs.existsSync(docPath) ? parseDocument(fs.readFileSync(docPath, 'utf8')).body : `# Command: ${name}\n\n${description}\n`;
+  writeCommandDocument(docPath, doc, prose);
+  return doc;
+}
+
+/**
+ * Read the cli_command document for a command, if present.
+ *
+ * @param {string} name
+ * @param {string} commandsDir
+ * @returns {object | null}
+ */
+export function readRegistry(name, commandsDir) {
+  const docPath = path.join(commandsDir, `${name}.md`);
+  if (!fs.existsSync(docPath)) return null;
+  const content = fs.readFileSync(docPath, 'utf8');
+  const doc = parseDocument(content).data;
+  // Only return if it's a cli_command
+  if (doc.type !== 'cli_command') return null;
+  delete doc.description_if_present;
+  return doc;
+}
+
+/**
+ * Snapshot the currently registered version of a command before an update.
+ *
+ * @param {string} name
+ * @param {string} commandsDir
+ * @returns {number|null} The version number that was snapshotted, or null if none
+ */
+export function snapshotForHistory(name, commandsDir) {
+  const cmdFile = path.join(commandsDir, `${name}.mjs`);
+  if (!fs.existsSync(cmdFile)) return null;
+
+  const doc = readRegistry(name, commandsDir);
+  const version = doc?.version || 1;
+
+  const historyDir = path.join(commandsDir, '.history', name);
+  fs.mkdirSync(historyDir, { recursive: true });
+
+  const snapFile = path.join(historyDir, `v${version}.mjs`);
+  if (!fs.existsSync(snapFile)) {
+    fs.copyFileSync(cmdFile, snapFile);
+  }
+  return version;
+}
+
+/**
+ * List history versions for a command.
+ *
+ * @param {string} name
+ * @param {string} commandsDir
+ * @returns {number[]} Sorted list of version numbers
+ */
+export function listHistory(name, commandsDir) {
+  const histDir = path.join(commandsDir, '.history', name);
+  if (!fs.existsSync(histDir)) return [];
+  return fs.readdirSync(histDir)
+    .filter((f) => /^v\d+\.mjs$/.test(f))
+    .map((f) => parseInt(f.replace(/\.mjs$/, '').replace('v', ''), 10))
+    .sort((a, b) => a - b);
+}
+
+/**
+ * Roll back a command to a previous version.
+ *
+ * @param {string} name
+ * @param {number} version - Target version to restore
+ * @param {string} commandsDir
+ * @returns {number} The restored version
+ */
+export function rollback(name, version, commandsDir) {
+  const snapFile = path.join(commandsDir, '.history', name, `v${version}.mjs`);
+  if (!fs.existsSync(snapFile)) {
+    const err = new Error(`Version ${version} of '${name}' does not exist in history.`);
+    err.exitCode = EXIT_CODES.ERROR;
+    throw err;
+  }
+
+  const cmdFile = path.join(commandsDir, `${name}.mjs`);
+  if (!fs.existsSync(cmdFile)) {
+    const err = new Error(`Command '${name}' does not exist.`);
+    err.exitCode = EXIT_CODES.ERROR;
+    throw err;
+  }
+
+  // Snapshot current before rollback
+  snapshotForHistory(name, commandsDir);
+
+  // Restore the target version
+  fs.copyFileSync(snapFile, cmdFile);
+
+  // Bump the registry version to reflect the rollback
+  const doc = readRegistry(name, commandsDir);
+  if (doc) {
+    const newVersion = (doc.version || 0) + 1;
+    fm(path.join(commandsDir, `${name}.md`), { ...doc, version: newVersion, updated: new Date().toISOString() });
+  }
+
+  return version;
+}
+
+/** Internal: rewrite a registry doc file with updated fields. */
+function fm(docPath, doc) {
+  const body = parseDocument(fs.readFileSync(docPath, 'utf8')).body;
+  const code = fs.readFileSync(docPath.replace(/\.md$/, '.mjs'), 'utf8');
+  writeCommandDocument(docPath, { ...doc, code_sha256: crypto.createHash('sha256').update(code).digest('hex') }, body);
+}

package/scaffold/.agent/skills/total-recall/plugins/composable-cli/src/resolve.mjs

@@ -0,0 +1,221 @@
+/**
+ * Command Resolution — scope search, shadow detection, group scope
+ *
+ * Resolution order for `total-recall <verb>`:
+ * 1. Built-in (provided by the total-recall core)
+ * 2. Project custom commands (<repo>/.agent/commands/)
+ * 3. Group commands (resolved through project_group membership, nearest first)
+ * 4. Global custom commands (~/.agent/commands/)
+ * 5. VFS integration (<agentDir>/skills/total-recall/integrations/)
+ * 6. Plugin manifests whose cli.command matches
+ *
+ * This module provides:
+ * - Shadow detection: refuse built-in names, warn on scope shadowing
+ * - Group scope search through project_group membership
+ * - Full resolution with provenance
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { builtinCommandNames } from './command.mjs';
+import { EXIT_CODES } from './contract.mjs';
+
+/**
+ * Find all commands directories for scoped resolution.
+ * Returns an ordered array of { scope, dir } objects.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Current working directory (default: process.cwd())
+ * @param {string[]} [options.groupDirs] - Optional group command directories
+ * @returns {{ scope: string, dir: string }[]}
+ */
+export function getCommandTargets(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const targets = [];
+
+  // Project scope
+  const projectDir = path.join(cwd, '.agent', 'commands');
+  if (fs.existsSync(projectDir)) {
+    targets.push({ scope: 'project', dir: projectDir });
+  }
+
+  // Group scope (resolved from project_group documents)
+  const groupDirs = options.groupDirs || resolveGroupDirs(cwd);
+  for (const gd of groupDirs) {
+    if (fs.existsSync(gd)) {
+      targets.push({ scope: 'group', dir: gd });
+    }
+  }
+
+  // Global scope
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  if (homeDir) {
+    const globalDir = path.join(homeDir, '.agent', 'commands');
+    if (fs.existsSync(globalDir)) {
+      targets.push({ scope: 'global', dir: globalDir });
+    }
+  }
+
+  return targets;
+}
+
+/**
+ * Resolve group command directories from project_group documents.
+ * Reads groups from ~/.agent/skills/total-recall/groups/
+ * and finds groups that contain this project.
+ *
+ * @param {string} cwd - Current working directory
+ * @returns {string[]} Array of group command directory paths
+ */
+export function resolveGroupDirs(cwd) {
+  const dirs = [];
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  if (!homeDir) return dirs;
+
+  const groupsDir = path.join(homeDir, '.agent', 'skills', 'total-recall', 'groups');
+  if (!fs.existsSync(groupsDir)) return dirs;
+
+  try {
+    const projectBrainPath = path.join(cwd, '.agent', 'skills', 'total-recall', 'config', 'brain.json');
+    let projectId = null;
+    if (fs.existsSync(projectBrainPath)) {
+      try {
+        const brain = JSON.parse(fs.readFileSync(projectBrainPath, 'utf8'));
+        projectId = brain.project_id;
+      } catch { /* ignore */ }
+    }
+
+    const groupFiles = fs.readdirSync(groupsDir).filter((f) => f.endsWith('.md'));
+    for (const gf of groupFiles) {
+      try {
+        const content = fs.readFileSync(path.join(groupsDir, gf), 'utf8');
+        const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!frontmatter) continue;
+        const yaml = frontmatter[1];
+        // Simple YAML-like parsing for members
+        const membersMatch = yaml.match(/members:\s*\[([^\]]*)\]/);
+        if (!membersMatch) continue;
+
+        const membersStr = membersMatch[1];
+        // Check if this project is a member
+        const isMember = projectId && membersStr.includes(projectId);
+
+        if (isMember) {
+          const groupCommandsDir = path.join(homeDir, '.agent', 'commands',
+            'groups', gf.replace(/\.md$/, ''));
+          dirs.push(groupCommandsDir);
+        }
+      } catch { /* ignore */ }
+    }
+  } catch { /* ignore */ }
+
+  return dirs;
+}
+
+/**
+ * Detect whether a name shadows another command in the resolution chain.
+ *
+ * @param {string} name - Command name to check
+ * @param {object} [options]
+ * @param {boolean} [options.throwOnBuiltin=true] - Throw if name is a built-in
+ * @returns {{ shadows: string|null, level: string|null }}
+ *   shadows: the scope whose command of the same name would be shadowed (or null)
+ *   level: 'builtin' | 'project' | 'group' | 'global' | null
+ */
+export function detectShadow(name, options = {}) {
+  const { throwOnBuiltin = true } = options;
+  const builtins = builtinCommandNames();
+
+  // Check built-in (absolute refusal)
+  if (builtins.has(name)) {
+    if (throwOnBuiltin) {
+      const err = new Error(`'${name}' is a built-in Total Recall command; a custom command with that name could never run.`);
+      err.exitCode = EXIT_CODES.USAGE;
+      throw err;
+    }
+    return { shadows: name, level: 'builtin' };
+  }
+
+  // Check project over group/global
+  const targets = getCommandTargets();
+  for (let i = 0; i < targets.length; i++) {
+    const cmdPath = path.join(targets[i].dir, `${name}.mjs`);
+    if (fs.existsSync(cmdPath)) {
+      // This scope already has the command; if we're creating at a higher
+      // priority scope, it shadows the lower one
+      if (i > 0) {
+        return { shadows: name, level: targets[i].scope };
+      }
+      // Same scope — already exists error, not shadowing
+      return { shadows: null, level: null };
+    }
+  }
+
+  return { shadows: null, level: null };
+}
+
+/**
+ * Check whether a name would shadow and return a warning if appropriate.
+ * Does not throw for built-ins (use detectShadow for that).
+ *
+ * @param {string} name - Command name to check
+ * @returns {string|null} Warning message or null
+ */
+export function shadowWarning(name) {
+  // Refuse built-in names with a clear error
+  const builtins = builtinCommandNames();
+  if (builtins.has(name)) {
+    return `'${name}' is a built-in Total Recall command; a custom command with that name could never run.`;
+  }
+
+  const targets = getCommandTargets();
+  let found = false;
+  for (const t of targets) {
+    const cmdPath = path.join(t.dir, `${name}.mjs`);
+    if (fs.existsSync(cmdPath)) {
+      if (!found) {
+        found = true; // First one wins — no warning
+      } else {
+        return `Warning: '${name}' exists in scope '${t.scope}' but will be shadowed by a higher-priority scope.`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve a verb through the full scope chain and return its path and source.
+ *
+ * @param {string} verb - Command name
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ * @returns {{ path: string|null, scope: string|null }}
+ */
+export function resolveCommand(verb, options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  // 1. Project
+  const projectPath = path.join(cwd, '.agent', 'commands', `${verb}.mjs`);
+  if (fs.existsSync(projectPath)) {
+    return { path: projectPath, scope: 'project' };
+  }
+
+  // 2. Group (through membership)
+  const groupDirs = resolveGroupDirs(cwd);
+  for (const gd of groupDirs) {
+    const groupPath = path.join(gd, `${verb}.mjs`);
+    if (fs.existsSync(groupPath)) {
+      return { path: groupPath, scope: 'group' };
+    }
+  }
+
+  // 3. Global
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  if (homeDir) {
+    const globalPath = path.join(homeDir, '.agent', 'commands', `${verb}.mjs`);
+    if (fs.existsSync(globalPath)) {
+      return { path: globalPath, scope: 'global' };
+    }
+  }
+
+  return { path: null, scope: null };
+}

package/scaffold/.agent/skills/total-recall/plugins/composable-cli/src/risk.mjs

@@ -0,0 +1,126 @@
+/**
+ * Risk Gate Module
+ *
+ * Risk classes and the dry-run / --yes gate for composable CLI commands.
+ *
+ * Risk classes:
+ * - read:      No side effects. Runs by default.
+ * - write:     Mutates local files only. Runs by default.
+ * - money:     Affects financial state. Requires --yes to run.
+ * - dns-cert:  Changes DNS records or TLS certificates. Requires --yes.
+ * - production-deploy: Deploys to production. Requires --yes.
+ * - secret-revoke:     Rotates/revokes credentials. Requires --yes.
+ *
+ * Flow:
+ * 1. A command declares its risk class in export const meta = { risk: '...' }
+ * 2. tr() checks hasRiskGate(risk) before calling the handler
+ * 3. If gated and no --yes, calls dryRunResult() to get the plan, returns exit 3
+ * 4. With --yes, the handler runs as normal
+ * 5. Nested tr() calls inherit dryRun; a gated nested call without --yes
+ *    fails the parent with exit 3
+ */
+import { EXIT_CODES } from './contract.mjs';
+
+/** Risk classes that require --yes to execute */
+export const GATED_RISKS = new Set([
+  'money',
+  'dns-cert',
+  'production-deploy',
+  'secret-revoke',
+]);
+
+/** All valid risk classes */
+export const ALL_RISKS = new Set([
+  'read',
+  'write',
+  ...GATED_RISKS,
+]);
+
+/**
+ * Check whether a risk class requires the --yes gate.
+ *
+ * @param {string} risk
+ * @returns {boolean}
+ */
+export function hasRiskGate(risk) {
+  return GATED_RISKS.has(risk);
+}
+
+/**
+ * Validate that a risk class is recognized.
+ *
+ * @param {string} risk
+ * @throws {Error} If the risk class is not recognized
+ */
+export function validateRisk(risk) {
+  if (!ALL_RISKS.has(risk)) {
+    const err = new Error(`Unknown risk class "${risk}". Valid: ${[...ALL_RISKS].join(', ')}`);
+    err.exitCode = EXIT_CODES.USAGE;
+    throw err;
+  }
+  return risk;
+}
+
+/**
+ * Run a handler in dry-run mode to obtain a plan.
+ * The handler receives { dryRun: true } in its context and should
+ * return a description of what it would change.
+ *
+ * @param {Function} handler - The v2 command handler
+ * @param {string[]} args - Arguments
+ * @param {object} context - Execution context { verb, json, dryRun, log }
+ * @returns {Promise<object>} Plan data
+ */
+export async function dryRunResult(handler, args, context = {}) {
+  const { verb, json, dryRun: _, log } = context;
+
+  // Call the handler with dryRun: true
+  const plan = await handler(args, { ...context, dryRun: true });
+
+  const planOutput = {
+    risk: 'gated',
+    command: verb,
+    args: args.filter((a) => a !== '--yes'),
+    plan: plan?.data ?? plan ?? 'No plan returned by command',
+    note: 'Run with --yes to execute',
+  };
+
+  if (json) {
+    console.log(JSON.stringify({ ok: false, exit_code: EXIT_CODES.ABSTAIN, result: planOutput }));
+  } else {
+    console.log(`  ${verb} would make the following changes:`);
+    console.log(JSON.stringify(planOutput.plan, null, 2));
+    console.log(`\nPass --yes to execute.`);
+  }
+
+  process.exitCode = EXIT_CODES.ABSTAIN;
+  return planOutput;
+}
+
+/**
+ * Create an argv parser that looks for --yes and strips it.
+ * Also removes --dry-run when dryRun is handled by the context.
+ *
+ * @param {string[]} args
+ * @param {object} [options]
+ * @param {boolean} [options.stripYes=true]
+ * @param {boolean} [options.stripDryRun=true]
+ * @returns {{ cleanArgs: string[], hasYes: boolean }}
+ */
+export function parseRiskArgs(args, { stripYes = true, stripDryRun = true } = {}) {
+  let hasYes = false;
+  let cleanArgs = args;
+  if (stripYes) {
+    cleanArgs = cleanArgs.filter((a) => {
+      if (a === '--yes' || a === '-y') {
+        hasYes = true;
+        return false;
+      }
+      return true;
+    });
+  }
+  if (stripDryRun) {
+    cleanArgs = cleanArgs.filter((a) => a !== '--dry-run');
+  }
+  return { cleanArgs, hasYes };
+}

package/scaffold/.agent/skills/total-recall/plugins/composable-cli/src/ssss-documents.mjs

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+const require = createRequire(import.meta.url);
+let source;
+if (process.env.TR_PACKAGE_ROOT) {
+  const root = path.resolve(process.env.TR_PACKAGE_ROOT);
+  if (JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name !== 'total-recall-brain') throw new Error('Invalid native Total Recall host');
+  source = path.join(root, 'src/core/plugin-document-store.mjs');
+} else source = require.resolve('total-recall-brain/src/core/plugin-document-store.mjs');
+export const { pluginDocumentOperation, parseDocument, serializeDocument } = await import(pathToFileURL(source).href);
+export const extension = { registry: 'composable-cli', extends: 'ssss', version: '1.0.0', document_primitives: {
+  cli_command: { family: 'capability', append_only: false, portability: 'tenant_private',
+    required_fields: ['type', 'id', 'name', 'scope', 'risk', 'version', 'code_sha256'], immutable_fields: ['id'],
+    patterns: { name: '^[a-z][a-z0-9-]{0,63}$', code_sha256: '^[a-f0-9]{64}$' },
+    enums: { scope: ['project', 'group', 'global'], risk: ['read', 'write', 'money', 'dns-cert', 'production-deploy', 'secret-revoke'] } },
+} };
+export function writeCommandDocument(file, metadata, body) {
+  const now = new Date().toISOString();
+  return pluginDocumentOperation({ type: 'operation', path: path.basename(file),
+    content: serializeDocument({ ...metadata, title: metadata.title || `Command ${metadata.name}`,
+      description: metadata.description || `CLI command ${metadata.name}`, timestamp: now }, body) },
+  { plugin: 'composable-cli', vaultRoot: path.dirname(path.resolve(file)), extension });
+}
+export function deleteCommandDocument(file) {
+  return pluginDocumentOperation({ type: 'delete', path: path.basename(file) },
+    { plugin: 'composable-cli', vaultRoot: path.dirname(path.resolve(file)), extension });
+}

package/scaffold/.agent/skills/total-recall/plugins/composable-cli/ui/DESIGN.md

@@ -0,0 +1,18 @@
+# DESIGN.md — Pipe Dream
+
+```yaml
+tokens:
+  brand-name: "Pipe Dream"
+  wordmark: "[PIPE//DREAM]"
+  color-primary: "#a855f7"
+  color-background: "#09090b"
+  color-accent: "#22c55e"
+  badge: "CLI Pipelines"
+  font-mono: "'JetBrains Mono', 'Fira Code', monospace"
+  border-radius: "8px"
+```
+
+## Brand & Typographic Wordmark
+- **Name**: Pipe Dream
+- **Wordmark Logo**: `[PIPE//DREAM]` (custom typographic badge, no generic icons)
+- **Palette**: Primary `#a855f7`, Surface `#09090b`, Accent `#22c55e`.