total-recall-brain 3.28.2 → 3.30.0

package/src/core/app-deploy/plan.mjs

@@ -0,0 +1,249 @@
+/**
+ * Capability Deployment — Deployment Planner
+ *
+ * Implements Phase 2 of CAPABILITY_DEPLOYMENT_PLUGINS:
+ * - Deterministic, read-only plan computation
+ * - File diffing (create, modify, identical, conflict)
+ * - SSSS dry-run event envelopes
+ * - Access grant and resource declaration aggregation
+ * - Deterministic SHA-256 plan hash
+ * - Formatted JSON output for CLI (`app plan --json`)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { resolveCapabilitySource } from './source.mjs';
+import { resolveCapabilityGraph } from './resolve.mjs';
+
+export const PROTECTED_APP_FILES = new Set([
+  'package.json',
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  'tsconfig.json',
+  'README.md',
+  '.gitignore',
+  '.env',
+  '.env.local',
+  '.env.production'
+]);
+
+/**
+ * Computes deterministic SHA-256 hash of any JSON-serializable object.
+ */
+export function computeDeterministicHash(obj) {
+  const canonical = JSON.stringify(obj, Object.keys(obj).sort());
+  return crypto.createHash('sha256').update(canonical).digest('hex');
+}
+
+/**
+ * Generates SSSS dry-run lifecycle event envelopes for capability installation.
+ */
+export function generateSsssEnvelopes(orderedPlugins, targetApp) {
+  const envelopes = [];
+  const timestamp = new Date().toISOString();
+
+  for (const plugin of orderedPlugins) {
+    // 1. Install start envelope
+    envelopes.push({
+      type: 'event',
+      domain: 'ssss.capability',
+      action: 'install_started',
+      timestamp,
+      actor: 'total-recall/app-deploy',
+      target: targetApp.dir,
+      payload: {
+        capability_id: plugin.id,
+        version: plugin.version,
+        source_sha256: plugin.sha256
+      }
+    });
+
+    // 2. Schema registration envelopes if categories are present
+    const categories = plugin.manifest.ssss_schemas?.categories || [];
+    if (categories.length > 0) {
+      envelopes.push({
+        type: 'event',
+        domain: 'ssss.schema',
+        action: 'categories_registered',
+        timestamp,
+        actor: 'total-recall/app-deploy',
+        target: targetApp.dir,
+        payload: {
+          capability_id: plugin.id,
+          categories: categories.map((c) => ({
+            name: c.name,
+            description: c.description || '',
+            node_type: c.node_type || 'memory'
+          }))
+        }
+      });
+    }
+
+    // 3. Capability installed envelope
+    envelopes.push({
+      type: 'event',
+      domain: 'ssss.capability',
+      action: 'installed',
+      timestamp,
+      actor: 'total-recall/app-deploy',
+      target: targetApp.dir,
+      payload: {
+        capability_id: plugin.id,
+        version: plugin.version,
+        status: 'ready'
+      }
+    });
+  }
+
+  return envelopes;
+}
+
+/**
+ * Diffs files provided by capability plugins against the target application tree.
+ */
+export function computeFileDiffs(orderedPlugins, targetAppDir) {
+  const fileOperations = [];
+
+  for (const plugin of orderedPlugins) {
+    for (const file of plugin.files || []) {
+      if (file.path === 'plugin.json') continue; // Manifest stays with capability record
+
+      const targetPath = path.join(targetAppDir, file.path);
+      let action = 'create';
+      let existingHash = null;
+
+      if (fs.existsSync(targetPath)) {
+        try {
+          const targetBytes = fs.readFileSync(targetPath);
+          existingHash = crypto.createHash('sha256').update(targetBytes).digest('hex');
+
+          if (existingHash === file.sha256) {
+            action = 'identical';
+          } else if (PROTECTED_APP_FILES.has(file.path) || PROTECTED_APP_FILES.has(path.basename(file.path))) {
+            action = 'conflict';
+          } else {
+            action = 'modify';
+          }
+        } catch {
+          action = 'modify';
+        }
+      }
+
+      fileOperations.push({
+        action,
+        path: file.path,
+        plugin_id: plugin.id,
+        size: file.size,
+        source_sha256: file.sha256,
+        target_sha256: existingHash
+      });
+    }
+  }
+
+  fileOperations.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return fileOperations;
+}
+
+/**
+ * Generates a full, deterministic capability deployment plan.
+ *
+ * @param {string|object} source - Capability source (URI, path, or bundle)
+ * @param {object} [options]
+ * @param {string} [options.target] - Target app directory path
+ * @param {string} [options.adapter] - Target adapter (ssss-app, nextjs, react, flask)
+ * @param {string} [options.expectedHash] - Pinned hash for source
+ * @param {Function} [options.pluginResolver] - Resolver for transitive dependencies
+ * @returns {Promise<{
+ *   plan_version: string,
+ *   plan_hash: string,
+ *   valid: boolean,
+ *   target_app: object,
+ *   adapter: string,
+ *   capabilities: Array<object>,
+ *   file_operations: Array<object>,
+ *   ssss_envelopes: Array<object>,
+ *   access_grants: Array<string>,
+ *   resources: object,
+ *   conflicts: Array<object>,
+ *   cleanup: () => void
+ * }>}
+ */
+export async function createDeploymentPlan(source, options = {}) {
+  const targetDir = path.resolve(options.target || process.cwd());
+  const adapter = options.adapter || 'ssss-app';
+
+  // 1. Resolve and verify root source
+  const rootSource = await resolveCapabilitySource(source, {
+    expectedHash: options.expectedHash,
+    projectRoot: targetDir
+  });
+
+  try {
+    // 2. Resolve dependency graph and check compatibility
+    const resolvedGraph = await resolveCapabilityGraph(rootSource, {
+      adapter,
+      targetApp: {
+        dir: targetDir,
+        framework: adapter,
+        ssssVersion: '0.9.6'
+      },
+      pluginResolver: options.pluginResolver
+    });
+
+    // 3. Compute file diffs against target directory
+    const fileOperations = computeFileDiffs(resolvedGraph.orderedPlugins, targetDir);
+
+    // 4. Generate SSSS dry-run envelopes
+    const ssssEnvelopes = generateSsssEnvelopes(resolvedGraph.orderedPlugins, resolvedGraph.targetApp);
+
+    // 5. Detect any file conflicts
+    const conflicts = fileOperations.filter((op) => op.action === 'conflict');
+
+    const capabilitiesSummary = resolvedGraph.orderedPlugins.map((p) => ({
+      id: p.id,
+      version: p.version,
+      source_sha256: p.sha256,
+      skills: (p.manifest.skills || []).map((s) => s.id),
+      commands: (p.manifest.commands || []).map((c) => c.name),
+      ui: p.manifest.ui ? Object.keys(p.manifest.ui) : []
+    }));
+
+    const planBody = {
+      plan_version: '1.0.0',
+      valid: conflicts.length === 0,
+      target_app: {
+        dir: targetDir,
+        framework: adapter,
+        ssss_version: resolvedGraph.targetApp.ssssVersion
+      },
+      adapter,
+      capabilities: capabilitiesSummary,
+      file_operations: fileOperations,
+      ssss_envelopes: ssssEnvelopes,
+      access_grants: resolvedGraph.totalGrants,
+      resources: resolvedGraph.totalResources,
+      conflicts
+    };
+
+    const planHash = computeDeterministicHash(planBody);
+
+    const stagedSources = {};
+    for (const p of resolvedGraph.orderedPlugins) {
+      if (p.stagedDir) {
+        stagedSources[p.id] = p.stagedDir;
+      }
+    }
+
+    return {
+      ...planBody,
+      plan_hash: planHash,
+      _stagedSources: stagedSources,
+      cleanup: rootSource.cleanup
+    };
+  } catch (err) {
+    rootSource.cleanup();
+    throw err;
+  }
+}

package/src/core/app-deploy/resolve.mjs

@@ -0,0 +1,295 @@
+/**
+ * Capability Deployment — Dependency DAG, Version Constraints & Collision Resolver
+ *
+ * Implements Phase 2 of CAPABILITY_DEPLOYMENT_PLUGINS:
+ * - Target and adapter compatibility checks
+ * - SSSS specification version constraints
+ * - Dependency DAG construction and topological ordering
+ * - Cycle detection and rejection
+ * - File path, command, and SSSS category ownership collision detection
+ * - Access grant and resource requirement aggregation
+ */
+
+import path from 'node:path';
+
+/**
+ * Custom error types for capability resolution
+ */
+export class IncompatibleAdapterError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'IncompatibleAdapterError';
+  }
+}
+
+export class IncompatibleSsssVersionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'IncompatibleSsssVersionError';
+  }
+}
+
+export class DependencyCycleError extends Error {
+  constructor(message, cycle = []) {
+    super(message);
+    this.name = 'DependencyCycleError';
+    this.cycle = cycle;
+  }
+}
+
+export class OwnershipCollisionError extends Error {
+  constructor(message, collisionDetails = {}) {
+    super(message);
+    this.name = 'OwnershipCollisionError';
+    this.details = collisionDetails;
+  }
+}
+
+/**
+ * Lightweight semver comparator to evaluate version constraints.
+ * Supports basic operators: >=, <=, >, <, ^, ~, or exact versions.
+ */
+export function satisfiesVersionConstraint(version, range) {
+  if (!range || range === '*' || range === 'latest') return true;
+  if (!version) return false;
+
+  const cleanV = version.replace(/^v/, '').trim();
+  const vParts = cleanV.split('.').map(Number);
+  const major = vParts[0] || 0;
+  const minor = vParts[1] || 0;
+  const patch = vParts[2] || 0;
+
+  const cleanRange = range.trim();
+
+  // Range with >= operator: e.g. ">=0.9.3"
+  if (cleanRange.startsWith('>=')) {
+    const target = cleanRange.slice(2).trim().split('.').map(Number);
+    if (major > (target[0] || 0)) return true;
+    if (major < (target[0] || 0)) return false;
+    if (minor > (target[1] || 0)) return true;
+    if (minor < (target[1] || 0)) return false;
+    return patch >= (target[2] || 0);
+  }
+
+  // Caret range: e.g. "^0.9.0"
+  if (cleanRange.startsWith('^')) {
+    const target = cleanRange.slice(1).trim().split('.').map(Number);
+    if (major !== (target[0] || 0)) return false;
+    if (minor < (target[1] || 0)) return false;
+    if (minor === (target[1] || 0)) return patch >= (target[2] || 0);
+    return true;
+  }
+
+  // Exact match: e.g. "0.9.6"
+  return cleanV === cleanRange.replace(/^v/, '');
+}
+
+/**
+ * Validates adapter compatibility between capability plugin and target app.
+ */
+export function checkAdapterCompatibility(manifest, adapter) {
+  if (!adapter) return;
+  const targets = manifest.deploy?.targets;
+  if (!targets || !Array.isArray(targets) || targets.length === 0) {
+    // If no targets specified, defaults to universal capability
+    return;
+  }
+
+  const isCompatible = targets.some((t) => t.toLowerCase() === adapter.toLowerCase() || t === '*');
+  if (!isCompatible) {
+    throw new IncompatibleAdapterError(
+      `Plugin '${manifest.id}' is not compatible with target adapter '${adapter}'. Supported targets: ${targets.join(', ')}`
+    );
+  }
+}
+
+/**
+ * Validates SSSS version requirement against target app's SSSS version.
+ */
+export function checkSsssVersionCompatibility(manifest, targetSsssVersion) {
+  const req = manifest.deploy?.required_ssss_version;
+  if (!req) return;
+
+  const currentVersion = targetSsssVersion || '0.9.6';
+  if (!satisfiesVersionConstraint(currentVersion, req)) {
+    throw new IncompatibleSsssVersionError(
+      `Plugin '${manifest.id}' requires SSSS version ${req}, but target app environment provides ${currentVersion}`
+    );
+  }
+}
+
+/**
+ * Resolves full dependency DAG, detects cycles, and sorts topologically.
+ *
+ * @param {object} rootDescriptor - Root capability source descriptor from resolveCapabilitySource
+ * @param {object} [options]
+ * @param {string} [options.adapter] - Target adapter (e.g. ssss-app, nextjs, react, flask)
+ * @param {object} [options.targetApp] - Target app info { dir, framework, ssssVersion }
+ * @param {Function} [options.pluginResolver] - Async resolver for transitive dependencies: (id) => Promise<descriptor>
+ * @returns {Promise<{
+ *   adapter: string,
+ *   targetApp: object,
+ *   orderedPlugins: Array<object>,
+ *   totalGrants: Array<string>,
+ *   totalResources: object,
+ *   fileOwners: Map<string, string>,
+ *   categoryOwners: Map<string, string>
+ * }>}
+ */
+export async function resolveCapabilityGraph(rootDescriptor, options = {}) {
+  const adapter = options.adapter || options.targetApp?.framework || 'ssss-app';
+  const targetSsssVersion = options.targetApp?.ssssVersion || '0.9.6';
+  const pluginResolver = options.pluginResolver || (async () => null);
+
+  const graph = new Map(); // id -> descriptor
+  const visited = new Map(); // id -> 'unvisited' | 'visiting' | 'visited'
+  const ordered = []; // Topological order (dependencies first)
+
+  // 1. Traverse and discover all transitive dependencies
+  async function traverse(currentDescriptor, pathTrace = []) {
+    const id = currentDescriptor.id;
+
+    if (pathTrace.includes(id)) {
+      const cycle = [...pathTrace, id];
+      throw new DependencyCycleError(`Dependency cycle detected: ${cycle.join(' -> ')}`, cycle);
+    }
+
+    if (graph.has(id)) return;
+    graph.set(id, currentDescriptor);
+
+    // Validate adapter and SSSS constraints for each plugin in the graph
+    checkAdapterCompatibility(currentDescriptor.manifest, adapter);
+    checkSsssVersionCompatibility(currentDescriptor.manifest, targetSsssVersion);
+
+    const depsObj = currentDescriptor.manifest.dependencies || {};
+    const depIds = Array.isArray(depsObj) ? depsObj : Object.keys(depsObj);
+
+    for (const depId of depIds) {
+      const depDescriptor = await pluginResolver(depId);
+      if (!depDescriptor) {
+        throw new Error(`Unresolvable dependency '${depId}' required by plugin '${id}'`);
+      }
+
+      const versionReq = typeof depsObj === 'object' && !Array.isArray(depsObj) ? depsObj[depId] : null;
+      if (versionReq && !satisfiesVersionConstraint(depDescriptor.version, versionReq)) {
+        throw new Error(
+          `Version mismatch for dependency '${depId}': '${id}' requires ${versionReq}, but resolved ${depDescriptor.version}`
+        );
+      }
+
+      await traverse(depDescriptor, [...pathTrace, id]);
+    }
+  }
+
+  await traverse(rootDescriptor);
+
+  // 2. Topological sort using DFS
+  for (const id of graph.keys()) {
+    visited.set(id, 'unvisited');
+  }
+
+  function dfsTopological(id, trace = []) {
+    const state = visited.get(id);
+    if (state === 'visiting') {
+      const cycle = [...trace, id];
+      throw new DependencyCycleError(`Dependency cycle detected: ${cycle.join(' -> ')}`, cycle);
+    }
+    if (state === 'visited') return;
+
+    visited.set(id, 'visiting');
+    const desc = graph.get(id);
+    const depsObj = desc.manifest.dependencies || {};
+    const depIds = Array.isArray(depsObj) ? depsObj : Object.keys(depsObj);
+
+    for (const depId of depIds) {
+      if (graph.has(depId)) {
+        dfsTopological(depId, [...trace, id]);
+      }
+    }
+
+    visited.set(id, 'visited');
+    ordered.push(desc);
+  }
+
+  for (const id of graph.keys()) {
+    if (visited.get(id) === 'unvisited') {
+      dfsTopological(id);
+    }
+  }
+
+  // 3. Collision Detection across the resolved graph
+  const fileOwners = new Map(); // relPath -> pluginId
+  const categoryOwners = new Map(); // categoryName -> pluginId
+  const commandOwners = new Map(); // commandName -> pluginId
+  const grantsSet = new Set();
+  const aggregatedResources = {};
+
+  for (const plugin of ordered) {
+    const id = plugin.id;
+    const manifest = plugin.manifest;
+
+    // Check files
+    for (const file of plugin.files || []) {
+      if (file.path === 'plugin.json') continue; // plugin.json is per-plugin
+      if (fileOwners.has(file.path)) {
+        const priorOwner = fileOwners.get(file.path);
+        throw new OwnershipCollisionError(
+          `File collision detected: '${file.path}' is owned by both '${priorOwner}' and '${id}'`,
+          { type: 'file', path: file.path, owners: [priorOwner, id] }
+        );
+      }
+      fileOwners.set(file.path, id);
+    }
+
+    // Check SSSS categories
+    const categories = manifest.ssss_schemas?.categories || [];
+    for (const cat of categories) {
+      const catName = cat.name;
+      if (categoryOwners.has(catName)) {
+        const priorOwner = categoryOwners.get(catName);
+        throw new OwnershipCollisionError(
+          `SSSS schema category collision: category '${catName}' is declared by both '${priorOwner}' and '${id}'`,
+          { type: 'category', category: catName, owners: [priorOwner, id] }
+        );
+      }
+      categoryOwners.set(catName, id);
+    }
+
+    // Check CLI commands
+    const cliCmd = manifest.cli?.command;
+    if (cliCmd) {
+      if (commandOwners.has(cliCmd)) {
+        const priorOwner = commandOwners.get(cliCmd);
+        throw new OwnershipCollisionError(
+          `CLI command collision: command '${cliCmd}' is claimed by both '${priorOwner}' and '${id}'`,
+          { type: 'command', command: cliCmd, owners: [priorOwner, id] }
+        );
+      }
+      commandOwners.set(cliCmd, id);
+    }
+
+    // Accumulate access grants
+    for (const grant of (manifest.deploy?.access_grants || manifest.deploy?.grants || [])) {
+      grantsSet.add(grant);
+    }
+
+    // Merge resources
+    if (manifest.deploy?.resources) {
+      Object.assign(aggregatedResources, manifest.deploy.resources);
+    }
+  }
+
+  return {
+    adapter,
+    targetApp: {
+      dir: options.targetApp?.dir || process.cwd(),
+      framework: adapter,
+      ssssVersion: targetSsssVersion
+    },
+    orderedPlugins: ordered,
+    totalGrants: Array.from(grantsSet).sort(),
+    totalResources: aggregatedResources,
+    fileOwners,
+    categoryOwners
+  };
+}