total-recall-brain 3.31.2 → 3.32.0

package/src/cli/skill-config.mjs

@@ -0,0 +1,211 @@
+/**
+ * CLI for a layered skill's repo-layer config. Shared by
+ * `total-recall skill config <id> …` and the per-skill command generated by
+ * `total-recall command create <name> --config-for-skill <id>`.
+ *
+ * Exit codes: 0 ok · 1 runtime failure (missing skill/contract, I/O) ·
+ * 2 usage or validation error.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import {
+  SkillConfigError,
+  resolveSkillDir,
+  loadConfigSchema,
+  validateSkillConfig,
+  readSkillConfig,
+  readSkillConfigState,
+  projectSkillConfig,
+  recordPath,
+  writeSkillConfig,
+  getConfigValue,
+  setConfigValue,
+  parseCliValue,
+  listCollections,
+  parseCollectionItem,
+  addCollectionItem,
+  removeCollectionItem,
+  detectSkillConfig,
+  missingRequired,
+  checkSkillLayerContract,
+} from '../core/skill-config.mjs';
+
+function usage(prefix, collections) {
+  const nouns = Object.entries(collections)
+    .map(([noun, c]) => `    ${prefix} ${noun} list|add|remove        Manage '${c.property}' (key: ${c.key})`)
+    .join('\n');
+  return `Usage:
+    ${prefix} config get [path]               Print the repo config or one value
+    ${prefix} config set <path> <value>       Set a value (JSON or plain string), validated
+    ${prefix} config unset <path>             Remove a value, validated
+    ${prefix} config validate                 Check the record against the contract and config.json for drift
+    ${prefix} config rebuild                  Regenerate config.json from the SSSS record
+    ${prefix} config import                   Record an existing config.json (adoption)
+    ${prefix} config check                    Contract checks: record, validity, drift, gate commands
+    ${prefix} config schema                   Print core/config.schema.json
+${nouns ? `${nouns}\n` : ''}    ${prefix} detect [--apply] [--force]       Propose a config from the repo (core/detect.mjs)
+    ${prefix} init [--yes] [--force]           Create config.json from defaults, detection and prompts
+
+  Options: --json (structured output) · --repo <path> (with 'skill config')`;
+}
+
+function topLevelDefaults(schema) {
+  const defaults = {};
+  for (const [key, definition] of Object.entries(schema.properties || {})) {
+    if (definition && Object.hasOwn(definition, 'default')) defaults[key] = structuredClone(definition.default);
+  }
+  return defaults;
+}
+
+async function promptMissing(schema, config, keys) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    let next = config;
+    for (const key of keys) {
+      const definition = schema.properties?.[key] || {};
+      const hint = definition.enum ? ` (${definition.enum.join('|')})` : definition.type ? ` (${definition.type})` : '';
+      const label = definition.description ? `${key} — ${definition.description}` : key;
+      const answer = (await rl.question(`${label}${hint}: `)).trim();
+      if (!answer) throw new SkillConfigError(`'${key}' is required`);
+      next = setConfigValue(next, key, parseCliValue(answer));
+    }
+    return next;
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * @param {string} skillId
+ * @param {string[]} args   verb and arguments, e.g. ['config', 'set', 'tier', 'fast']
+ * @param {{ repoRoot: string, prefix?: string }} opts
+ */
+export async function runSkillConfig(skillId, args, { repoRoot, prefix = `total-recall skill config ${skillId}` } = {}) {
+  const json = args.includes('--json');
+  const flags = new Set(args.filter((arg) => arg.startsWith('--')));
+  const positional = args.filter((arg) => !arg.startsWith('--'));
+  const out = (payload, text) => {
+    if (json) console.log(JSON.stringify({ ok: true, ...payload }));
+    else if (text !== undefined) console.log(text);
+    return { ok: true, ...payload };
+  };
+
+  try {
+    const skillDir = resolveSkillDir(repoRoot, skillId);
+    const contract = loadConfigSchema(skillDir);
+    const collections = listCollections(contract.schema);
+    const [verb, action, ...rest] = positional;
+
+    if (!verb || verb === 'help' || flags.has('--help')) {
+      console.log(usage(prefix, collections));
+      return { ok: true };
+    }
+
+    if (verb === 'config') {
+      const state = readSkillConfigState(skillDir);
+      const current = state.config;
+      if (action === 'schema') return out({ schema: contract.schema }, JSON.stringify(contract.schema, null, 2));
+      if (action === 'validate') {
+        if (current === null) throw new SkillConfigError('No config yet; run init or detect --apply', { exitCode: 1 });
+        const result = validateSkillConfig(contract, current);
+        if (!result.valid) throw new SkillConfigError(`${state.source === 'record' ? recordPath(skillId) : 'config.json'} is invalid:\n  ${result.errors.join('\n  ')}`, { issues: result.errors });
+        if (state.source !== 'record') throw new SkillConfigError(`config.json is valid but not recorded in SSSS; run '${prefix} config import'`, { exitCode: 1 });
+        if (!state.inSync) throw new SkillConfigError(`config.json has drifted from ${recordPath(skillId)}; run '${prefix} config rebuild'`, { exitCode: 1 });
+        return out({ valid: true, in_sync: true }, `${recordPath(skillId)} satisfies core/config.schema.json and config.json matches it`);
+      }
+      if (action === 'check') {
+        const report = checkSkillLayerContract(skillDir);
+        const text = report.checks.map((c) => `${c.ok ? '✔' : c.level === 'warn' ? '⚠' : '✖'} ${c.message}`).join('\n');
+        if (json) console.log(JSON.stringify({ ok: report.ok, exit_code: report.ok ? 0 : 1, ...report }));
+        else console.log(text);
+        process.exitCode = report.ok ? 0 : 1;
+        return report;
+      }
+      if (action === 'rebuild') {
+        if (state.source !== 'record') throw new SkillConfigError(`No ${recordPath(skillId)} record to rebuild from`, { exitCode: 1 });
+        projectSkillConfig(skillDir, state.record.config);
+        return out({ config: state.record.config }, '✔ Rebuilt config.json from the SSSS record');
+      }
+      if (action === 'import') {
+        if (state.source === 'record') return out({ config: current, imported: false }, `Already recorded at ${recordPath(skillId)}`);
+        if (state.projection === null) throw new SkillConfigError('No config.json to import', { exitCode: 1 });
+        const written = await writeSkillConfig(skillDir, contract, state.projection);
+        return out({ config: written, imported: true }, `✔ Recorded config.json at ${recordPath(skillId)}`);
+      }
+      if (action === 'get') {
+        const value = rest[0] ? getConfigValue(current ?? {}, rest[0]) : current;
+        if (rest[0] && value === undefined) throw new SkillConfigError(`No value at '${rest[0]}'`, { exitCode: 1 });
+        return out({ value: value ?? null }, typeof value === 'string' ? value : JSON.stringify(value ?? null, null, 2));
+      }
+      if (action === 'set' || action === 'unset') {
+        if (!rest[0] || (action === 'set' && rest.length < 2)) throw new SkillConfigError(`Usage: ${prefix} config ${action} <path>${action === 'set' ? ' <value>' : ''}`);
+        if (current === null) throw new SkillConfigError('No config.json yet; run init or detect --apply first', { exitCode: 1 });
+        const value = action === 'set' ? parseCliValue(rest.slice(1).join(' ')) : undefined;
+        const written = await writeSkillConfig(skillDir, contract, setConfigValue(current, rest[0], value));
+        return out({ config: written }, `✔ ${action === 'set' ? 'Set' : 'Removed'} ${rest[0]}`);
+      }
+      throw new SkillConfigError(`Unknown config action '${action ?? ''}'\n${usage(prefix, collections)}`);
+    }
+
+    if (Object.hasOwn(collections, verb)) {
+      const collection = collections[verb];
+      const current = readSkillConfig(skillDir);
+      if (action === 'list') {
+        const items = getConfigValue(current ?? {}, collection.property) ?? [];
+        return out({ items }, items.length ? items.map((item) => `- ${item?.[collection.key]}: ${JSON.stringify(item)}`).join('\n') : `No ${collection.property}.`);
+      }
+      if (current === null) throw new SkillConfigError('No config.json yet; run init or detect --apply first', { exitCode: 1 });
+      if (action === 'add') {
+        const item = parseCollectionItem(rest);
+        const written = await writeSkillConfig(skillDir, contract, addCollectionItem(current, collection, item));
+        return out({ config: written }, `✔ Added ${verb} '${item[collection.key]}'`);
+      }
+      if (action === 'remove') {
+        if (!rest[0]) throw new SkillConfigError(`Usage: ${prefix} ${verb} remove <${collection.key}>`);
+        const written = await writeSkillConfig(skillDir, contract, removeCollectionItem(current, collection, rest[0]));
+        return out({ config: written }, `✔ Removed ${verb} '${rest[0]}'`);
+      }
+      throw new SkillConfigError(`Usage: ${prefix} ${verb} list|add|remove`);
+    }
+
+    if (verb === 'detect') {
+      const proposal = await detectSkillConfig(skillDir, repoRoot);
+      const checked = validateSkillConfig(contract, proposal);
+      if (!flags.has('--apply')) {
+        return out({ proposal, valid: checked.valid, errors: checked.errors },
+          `${JSON.stringify(proposal, null, 2)}\n${checked.valid ? 'Valid. Re-run with --apply to write config.json.' : `Invalid:\n  ${checked.errors.join('\n  ')}`}`);
+      }
+      if (readSkillConfig(skillDir) !== null && !flags.has('--force')) {
+        throw new SkillConfigError('A config already exists; use --force to replace it with the detected config', { exitCode: 1 });
+      }
+      const written = await writeSkillConfig(skillDir, contract, proposal);
+      return out({ config: written }, '✔ Recorded the detected config and wrote config.json');
+    }
+
+    if (verb === 'init') {
+      if (readSkillConfig(skillDir) !== null && !flags.has('--force')) {
+        throw new SkillConfigError(`A config already exists; change it with '${prefix} config set' or pass --force`, { exitCode: 1 });
+      }
+      let config = topLevelDefaults(contract.schema);
+      if (fs.existsSync(path.join(skillDir, 'core', 'detect.mjs'))) config = { ...config, ...(await detectSkillConfig(skillDir, repoRoot)) };
+      const missing = missingRequired(contract.schema, config);
+      if (missing.length) {
+        if (flags.has('--yes') || json || !process.stdin.isTTY) {
+          throw new SkillConfigError(`Missing required fields: ${missing.join(', ')}. Run interactively or set them after 'detect --apply'.`);
+        }
+        config = await promptMissing(contract.schema, config, missing);
+      }
+      const written = await writeSkillConfig(skillDir, contract, config);
+      return out({ config: written }, `✔ Initialized ${path.relative(process.cwd(), path.join(skillDir, 'config.json')) || 'config.json'}`);
+    }
+
+    throw new SkillConfigError(`Unknown subcommand '${verb}'\n${usage(prefix, collections)}`);
+  } catch (error) {
+    const exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+    if (json) console.log(JSON.stringify({ ok: false, exit_code: exitCode, error: error.message, ...(error.issues?.length ? { issues: error.issues } : {}) }));
+    else console.error(`Error: ${error.message}`);
+    process.exitCode = exitCode;
+    return { ok: false, exit_code: exitCode, error: error.message };
+  }
+}

package/src/cli/skill.mjs

@@ -68,6 +68,8 @@ function printHelp() {
     registry              List catalog entries in skills-registry/index.yaml
     deploy <id>           Copy skill into a repo (.agent/skills/<id>/) and record install map
     status [id]           Registry + install map + drift (omit id = summary)
+    config <id> …         Repo-layer config from core/config.schema.json (get|set|unset|rebuild|import|check|
+                          validate|schema, <collection> list|add|remove, detect, init)
     sync-registry         Register all local brain skills into the catalog
     unregister <id>       Remove catalog entry (does not delete repo copies)
     track <path>          Track any repo (full project brain + registry) for skill sync
@@ -131,6 +133,24 @@ function parseFlagValue(args, flag) {
 
 export default async function skillCli(args) {
   const { layer, remainingArgs } = parseLayerFlag(args);
+  if (remainingArgs[0] === 'config') {
+    // Repo-layer config is per repository; it needs no brain resolution.
+    const repoAt = remainingArgs.indexOf('--repo');
+    const repoRoot = repoAt === -1 ? process.cwd() : remainingArgs[repoAt + 1];
+    const rest = repoAt === -1 ? remainingArgs : remainingArgs.filter((_, i) => i !== repoAt && i !== repoAt + 1);
+    const skillId = rest[1];
+    if (!skillId || !repoRoot) {
+      console.error('❌ Usage: total-recall skill config <id> <config|detect|init|collection> … [--repo <path>] [--json]');
+      process.exitCode = 2;
+      return;
+    }
+    const { runSkillConfig } = await import('./skill-config.mjs');
+    const verbArgs = rest.slice(2);
+    // `skill config <id> get x` reads as the config verb; `skill config <id> detect` stays a verb.
+    const normalized = ['get', 'set', 'unset', 'validate', 'schema', 'rebuild', 'import', 'check'].includes(verbArgs[0]) ? ['config', ...verbArgs] : verbArgs;
+    await runSkillConfig(skillId, normalized, { repoRoot });
+    return;
+  }
   if (remainingArgs.length === 0 || remainingArgs.includes('--help') || remainingArgs.includes('-h')) {
     printHelp();
     return;
@@ -486,6 +506,9 @@ Provide a high-level explanation of the skill's capabilities and context.
       console.log(`\n  ✅ Deployed: ${result.skillId}`);
       console.log(`     → ${result.destDir}`);
       console.log(`     hash=${result.install.content_hash} adapted=${result.adapt.adapted}`);
+      if (result.install.layered) {
+        console.log(`     core=${result.install.core_hash} repo=${result.install.repo_hash}`);
+      }
       console.log(`     Install map updated in ${resolveRegistryPath(brainDir)}\n`);
     } catch (err) {
       console.error(`❌ Deploy failed: ${err.message}`);
@@ -518,13 +541,25 @@ Provide a high-level explanation of the skill's capabilities and context.
         console.log(`  Version: ${st.entry.version}  hash=${st.entry.content_hash}`);
         console.log(`  Source: ${st.entry.source_path || st.entry.source}`);
       }
-      console.log(`  Installs: ${st.install_count}  drift=${st.any_drift ? 'YES' : 'no'}`);
+      console.log(`  Installs: ${st.install_count}  drift=${st.any_drift ? 'YES' : 'no'}${st.any_contract_failure ? '  contract=FAILED' : ''}`);
       for (const inst of st.installs) {
         console.log(
-          `    • ${inst.path}\n      exists=${inst.exists} live=${inst.live_hash || '-'} drift=${inst.drift}`,
+          `    • ${inst.path}\n      exists=${inst.exists} live=${inst.live_hash || '-'} drift=${inst.drift}` +
+          (inst.adopted === false ? '  (legacy copy, not adopted: deploy to adopt)' : '') +
+          (inst.error ? `\n      error=${inst.error}` : ''),
         );
+        if (inst.layered) {
+          console.log(`      core=${inst.core_hash || '-'} repo=${inst.repo_hash || '-'} repo_changed=${inst.repo_changed}`);
+        }
+        if (inst.contract) {
+          console.log(`      contract=${inst.contract.ok ? 'ok' : 'FAILED'}`);
+          for (const c of inst.contract.checks.filter((check) => !check.ok)) {
+            console.log(`        ${c.level === 'warn' ? '⚠' : '✖'} ${c.message}`);
+          }
+        }
       }
       console.log('');
+      if (st.any_contract_failure) process.exitCode = 1;
     } catch (err) {
       console.error(`❌ ${err.message}`);
       process.exit(1);

package/src/core/app-deploy/adapter-contract.mjs

@@ -0,0 +1,176 @@
+/**
+ * Shared conformance boundary for app deployment adapters.
+ *
+ * An adapter owns the target runtime, but every adapter must prove the same
+ * lifecycle against an isolated app. This runner intentionally uses the SSSS
+ * package's canonical operation fixture rather than a Total Recall-only record.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const ADAPTER_CONTRACT_VERSION = '1.0.0';
+export const ADAPTER_METHODS = Object.freeze([
+  'detect',
+  'generate',
+  'executeSsss',
+  'rebuildProjection',
+  'start',
+  'cleanup'
+]);
+
+export function assertAdapterContract(adapter) {
+  if (!adapter || typeof adapter !== 'object' || !/^[a-z][a-z0-9-]*$/.test(adapter.id || '')) {
+    throw new TypeError('Adapter must have a safe, lowercase id');
+  }
+  for (const method of ADAPTER_METHODS) {
+    if (typeof adapter[method] !== 'function') {
+      throw new TypeError(`Adapter '${adapter.id}' must implement ${method}()`);
+    }
+  }
+  return adapter;
+}
+
+function fail(stage, message) {
+  throw new Error(`Adapter contract ${stage}: ${message}`);
+}
+
+function digest(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function inside(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+function snapshot(dir) {
+  const entries = [];
+  function walk(current, prefix = '') {
+    for (const item of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const relative = path.posix.join(prefix, item.name);
+      const absolute = path.join(current, item.name);
+      const stat = fs.lstatSync(absolute);
+      if (stat.isSymbolicLink()) fail('generation', `symlink '${relative}' is not portable`);
+      if (stat.isDirectory()) walk(absolute, relative);
+      else if (stat.isFile()) entries.push([relative, digest(absolute)]);
+      else fail('generation', `unsupported file '${relative}'`);
+    }
+  }
+  walk(dir);
+  return entries;
+}
+
+/**
+ * Run the same lifecycle proof for each declared adapter. The caller supplies
+ * a canonical SSSS operation fixture with request and expected_response.
+ * Adapter methods receive an isolated target and never the operator's vault.
+ */
+export async function runAdapterContractFixtures(adapter, operationFixture) {
+  assertAdapterContract(adapter);
+  if (!operationFixture?.request || operationFixture.expected_response?.success !== true) {
+    throw new TypeError('A successful canonical SSSS operation fixture is required');
+  }
+
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'tr-adapter-contract-'));
+  const target = path.join(root, 'app');
+  const first = path.join(root, 'generated-a');
+  const second = path.join(root, 'generated-b');
+  const vault = path.join(target, 'vault');
+  const privateFile = path.join(vault, 'tenant-private.txt');
+  let runtime;
+  try {
+    fs.mkdirSync(vault, { recursive: true });
+    fs.mkdirSync(first);
+    fs.mkdirSync(second);
+    fs.writeFileSync(privateFile, 'private user data\n');
+    fs.writeFileSync(path.join(target, 'package.json'), JSON.stringify({
+      name: 'adapter-contract-app',
+      version: '0.0.0',
+      type: 'module',
+      ssss: { adapter: adapter.id }
+    }));
+
+    const targetBefore = snapshot(target);
+    const detection = await adapter.detect(target);
+    if (detection?.supported !== true || detection.adapter !== adapter.id) {
+      fail('detection', `expected a compatible '${adapter.id}' target`);
+    }
+    if (JSON.stringify(snapshot(target)) !== JSON.stringify(targetBefore)) {
+      fail('detection', 'target detection changed the app');
+    }
+
+    await adapter.generate({ target, output: first });
+    await adapter.generate({ target, output: second });
+    const generated = snapshot(first);
+    if (generated.length === 0 || JSON.stringify(generated) !== JSON.stringify(snapshot(second))) {
+      fail('generation', 'source output must be nonempty and deterministic');
+    }
+    if (JSON.stringify(snapshot(target)) !== JSON.stringify(targetBefore)) {
+      fail('generation', 'planning/generation changed the target app');
+    }
+
+    const request = structuredClone(operationFixture.request);
+    const denied = await adapter.executeSsss(request, { target, principal: null });
+    if (denied?.success !== false) fail('kernel bridge', 'missing verified principal was accepted');
+
+    const accepted = await adapter.executeSsss(request, {
+      target,
+      principal: { id: 'fixture-admin', role: 'system', verified: true }
+    });
+    if (accepted?.success !== true || accepted?.validation?.valid !== true) {
+      fail('kernel bridge', `canonical operation failed: ${JSON.stringify(accepted?.validation?.errors || [])}`);
+    }
+    const document = path.join(vault, request.path);
+    if (!fs.existsSync(document)) fail('kernel bridge', 'canonical document was not committed to the app vault');
+    const canonicalHash = digest(document);
+    const replay = await adapter.executeSsss(request, {
+      target,
+      principal: { id: 'fixture-admin', role: 'system', verified: true }
+    });
+    if (replay?.success !== true || replay?.replay !== true || digest(document) !== canonicalHash) {
+      fail('kernel bridge', 'same operation did not replay idempotently');
+    }
+    const escape = { ...request, idempotency_key: `${request.idempotency_key}-escape`, path: '../outside.md' };
+    const escaped = await adapter.executeSsss(escape, {
+      target,
+      principal: { id: 'fixture-admin', role: 'system', verified: true }
+    });
+    if (escaped?.success !== false || fs.existsSync(path.join(target, 'outside.md'))) {
+      fail('kernel bridge', 'path escape was accepted');
+    }
+
+    const projection = await adapter.rebuildProjection({ target });
+    const projectionPath = projection?.path && path.resolve(projection.path);
+    if (!projectionPath || !inside(target, projectionPath) || inside(vault, projectionPath)
+        || !fs.existsSync(projectionPath) || !fs.lstatSync(projectionPath).isFile()
+        || !inside(fs.realpathSync(target), fs.realpathSync(projectionPath))) {
+      fail('projection', 'rebuild must produce a regular file inside the app and outside its vault');
+    }
+    const projectionHash = digest(projectionPath);
+    fs.unlinkSync(projectionPath);
+    await adapter.rebuildProjection({ target });
+    if (!fs.existsSync(projectionPath) || digest(projectionPath) !== projectionHash || digest(document) !== canonicalHash) {
+      fail('projection', 'rebuild is nondeterministic or changed canonical state');
+    }
+
+    runtime = await adapter.start({ target });
+    if (!runtime || typeof runtime.health !== 'function' || typeof runtime.stop !== 'function') {
+      fail('runtime', 'start must return health() and stop()');
+    }
+    const health = await runtime.health();
+    if (health?.status !== 'healthy') fail('runtime', 'health check did not report healthy');
+    await runtime.stop();
+    runtime = null;
+
+    await adapter.cleanup({ target, generated: [first, second] });
+    if (fs.readFileSync(privateFile, 'utf8') !== 'private user data\n' || digest(document) !== canonicalHash) {
+      fail('cleanup', 'tenant-private or canonical app data changed');
+    }
+    return { valid: true, adapter: adapter.id, contract_version: ADAPTER_CONTRACT_VERSION };
+  } finally {
+    if (runtime?.stop) await runtime.stop();
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}