model-orchestrator 0.1.35 → 1.0.0

package/src/apply-snippets.js

@@ -1,17 +1,30 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { preflight, snippetFor } from './install.js';
+import { preflight, snippetFor, ACTIVATION_JSON_BYTE_CAP } from './install.js';
 
 export const START = '<!-- model-orchestrator:start -->';
 export const END = '<!-- model-orchestrator:end -->';
 const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 const refuse = (message) => Object.assign(new Error(message), { code: 'PREFLIGHT' });
+const CRLF = Buffer.from('\r\n');
+// R2: match the file's own line ending for the block this run inserts or
+// replaces, so a CRLF file stays CRLF instead of picking up a mixed file.
+const eolOf = (original) => (original.indexOf(CRLF) !== -1 ? '\r\n' : '\n');
+// R1: refuse a pre-existing JSON file over the stated cap before it is read,
+// the same way invalid JSON is refused today, without ever loading its bytes.
+function refuseIfOversized(path) {
+  if (existsSync(path) && statSync(path).size > ACTIVATION_JSON_BYTE_CAP) {
+    throw refuse(`${path}: larger than the ${ACTIVATION_JSON_BYTE_CAP} byte (10 MB) cap on a pre-existing settings/MCP JSON file; nothing written`);
+  }
+}
 
 function mergeHooks(settings, incoming, path) {
   if (!object(settings) || (settings.hooks !== undefined && !object(settings.hooks))) {
     throw refuse(`${path}: expected a JSON object with an optional hooks object`);
   }
   const hooks = { ...settings.hooks };
+  const ownership = [];
   for (const [event, groups] of Object.entries(incoming)) {
     const existing = hooks[event] === undefined ? [] : hooks[event];
     if (!Array.isArray(existing) || existing.some((group) => !object(group) || !Array.isArray(group.hooks))) {
@@ -28,20 +41,26 @@ function mergeHooks(settings, incoming, path) {
         seen.add(key(group, hook));
         return true;
       });
-      if (missing.length) added.push({ ...group, hooks: missing });
+      if (missing.length) {
+        added.push({ ...group, hooks: missing });
+        const { hooks: ignored, ...attributes } = group;
+        for (const hook of missing) ownership.push({ event, group: attributes, hook });
+      }
     }
     hooks[event] = [...existing, ...added];
   }
-  return { ...settings, hooks };
+  return { settings: { ...settings, hooks }, ownership };
 }
 
 function markedContent(original, snippet, path) {
   const start = original.indexOf(START);
   const end = original.indexOf(END);
-  const block = Buffer.from(`${START}\n${snippet.trimEnd()}\n${END}`);
+  const nl = eolOf(original);
+  const body = snippet.trimEnd().split('\n').join(nl);
+  const block = Buffer.from(`${START}${nl}${body}${nl}${END}`);
   if (start === -1 && end === -1) {
-    const separator = original.length && original.at(-1) !== 10 ? '\n\n' : original.length ? '\n' : '';
-    return Buffer.concat([original, Buffer.from(separator), block, Buffer.from('\n')]);
+    const separator = original.length && original.at(-1) !== 10 ? nl + nl : original.length ? nl : '';
+    return Buffer.concat([original, Buffer.from(separator), block, Buffer.from(nl)]);
   }
   if (start < 0 || end < start || original.indexOf(START, start + START.length) !== -1 || original.indexOf(END, end + END.length) !== -1) {
     throw refuse(`${path}: expected one matching ${START} / ${END} block`);
@@ -50,32 +69,45 @@ function markedContent(original, snippet, path) {
 }
 
 export function assertSnippetPrimary(primary) {
-  if (primary?.id !== 'claude-code') {
-    throw refuse(`--apply-snippets requires claude-code as primary; paste ${snippetFor(primary) || 'PASTE-INTO-YOUR-AGENT.md'} by hand`);
-  }
+  // Chat apps have no project rules target; their paste step remains manual.
+  return !!primary?.rulesFile;
 }
 
-// Read and validate both user files before the installer writes anything.
-// These entries deliberately stay outside the uninstall manifest.
+// Read and validate every user file before the installer writes anything.
+// Activation ownership records only the inserted block and added hook entries.
 export function planSnippetApplication({ primary, project, files }) {
-  assertSnippetPrimary(primary);
-  const targets = ['CLAUDE.md', join('.claude', 'settings.json')];
+  if (!assertSnippetPrimary(primary)) return [];
+  const targets = [primary.rulesFile];
+  if (primary.id === 'claude-code') targets.push(join('.claude', 'settings.json'));
   const problems = preflight(targets.map((rel) => ({ rel })), project);
   if (problems.length) throw refuse(problems.join('; '));
-  const settingsPath = join(project, targets[1]);
-  const priorSettings = existsSync(settingsPath) ? readFileSync(settingsPath) : null;
-  let settings = {};
-  if (priorSettings) {
-    try { settings = JSON.parse(priorSettings.toString('utf8')); }
-    catch { throw refuse(`${settingsPath}: invalid JSON; nothing written`); }
-  }
-  const incoming = JSON.parse(files.find((f) => f.rel === 'settings.hooks.snippet.json').content);
-  const merged = mergeHooks(settings, incoming.hooks, settingsPath);
   const rulesPath = join(project, targets[0]);
   const priorRules = existsSync(rulesPath) ? readFileSync(rulesPath) : null;
-  const snippet = files.find((f) => f.rel === 'CLAUDE.snippet.md').content;
-  return [
-    { rel: targets[0], original: priorRules, content: markedContent(priorRules || Buffer.alloc(0), snippet, rulesPath) },
-    { rel: targets[1], original: priorSettings, content: priorSettings && JSON.stringify(settings) === JSON.stringify(merged) ? priorSettings : JSON.stringify(merged, null, 2) + '\n' }
-  ].map((file) => ({ ...file, root: 'project', mode: 0o644, applySnippet: true }));
+  const snippet = files.find((f) => f.rel === snippetFor(primary))?.content;
+  if (snippet === undefined) throw refuse(`${rulesPath}: missing generated rules snippet`);
+  const content = markedContent(priorRules || Buffer.alloc(0), snippet, rulesPath);
+  const block = content.subarray(content.indexOf(START), content.indexOf(END) + Buffer.byteLength(END));
+  const appended = !priorRules?.includes(START);
+  const entries = [{ rel: targets[0], original: priorRules, content, activation: {
+    kind: 'rules', blockHash: createHash('sha256').update(block).digest('hex'), created: priorRules === null,
+    addedPrefix: appended && priorRules?.length ? (priorRules.at(-1) === 10 ? '\n' : '\n\n') : '',
+    addedSuffix: appended ? '\n' : ''
+  } }];
+  if (primary.id === 'claude-code') {
+    const settingsPath = join(project, targets[1]);
+    refuseIfOversized(settingsPath);
+    const priorSettings = existsSync(settingsPath) ? readFileSync(settingsPath) : null;
+    let settings = {};
+    if (priorSettings) {
+      try { settings = JSON.parse(priorSettings.toString('utf8')); }
+      catch { throw refuse(`${settingsPath}: invalid JSON; nothing written`); }
+    }
+    const incoming = JSON.parse(files.find((f) => f.rel === 'settings.hooks.snippet.json').content);
+    const merged = mergeHooks(settings, incoming.hooks, settingsPath);
+    entries.push({ rel: targets[1], original: priorSettings,
+      content: priorSettings && JSON.stringify(settings) === JSON.stringify(merged.settings) ? priorSettings : JSON.stringify(merged.settings, null, 2) + '\n',
+      activation: { kind: 'hooks', hooks: merged.ownership, created: priorSettings === null, hadHooks: Object.hasOwn(settings, 'hooks'), originalEvents: Object.keys(settings.hooks || {}) }
+    });
+  }
+  return entries.map((file) => ({ ...file, root: 'project', mode: 0o644, applySnippet: true }));
 }

package/src/aunx.js

@@ -0,0 +1,262 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, writeFileSync } from 'node:fs';
+import { dirname, join, parse, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { windowsSpawnPlan } from '../bin/cli-run.mjs';
+import { byId } from './catalog.js';
+import { ROLE_SPECS } from './roles.js';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const COMMON = join(ROOT, 'templates', 'common');
+const HELP = `aunx: model router tools for AI coding agents
+
+  aunx [installer flags]              Run the model-orchestrator installer
+  aunx cli-run [--dir PATH] <args>     Run a lane; --dir names a project's own runner
+  aunx route-metrics [--summary]      Read the local routing summary
+  aunx brief [PATH]                   Print the task brief template, or scaffold it at PATH
+  aunx brief new [PATH]               Create TASK_BRIEF.md
+  aunx context [new] [PATH]           Create CONTEXT.md
+  aunx checks [new] [PATH]            Create ACCEPTANCE_CHECKS.json
+  aunx checks run [PATH]              Run local checks; exit 1 on any FAIL. checks run executes
+                                       the commands in your checks file, so run it only on files you trust.
+  aunx route [--dir PATH] "<task>"    Suggest a stack role, tier and effort
+
+Route reads MANIFEST.json from --dir, then ./ai-orchestrator, then the current
+directory. It reads regular JSON files of at most 1 MiB and executes no project code.
+
+Scaffolds preserve existing files. Check commands run only with checks run.
+Use aunx install --help for the installer flags (or model-orchestrator --help).
+Use aunx cli-run --help for the lane runner flags.
+`;
+
+function regular(path) {
+  try { return lstatSync(path).isFile(); } catch { return false; }
+}
+
+// Run Node entry points directly, including on Windows. No command shell parses lane prompts.
+export function runNode(path, args) {
+  return new Promise(resolveExit => {
+    const child = spawn(process.execPath, [path, ...args], { stdio: 'inherit' });
+    const handlers = new Map();
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      const handler = () => { try { child.kill(signal); } catch {} };
+      handlers.set(signal, handler);
+      process.on(signal, handler);
+    }
+    const cleanup = () => { for (const [signal, handler] of handlers) process.removeListener(signal, handler); };
+    child.once('error', error => { cleanup(); console.error(`aunx: ${error.message}`); resolveExit(2); });
+    child.once('close', (code, signal) => { cleanup(); resolveExit(code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1)); });
+  });
+}
+
+// dir stays undefined unless --dir is given explicitly: the project runner is
+// opt-in, never a default guessed from the current directory (R1).
+function runnerArgs(args) {
+  const rest = [];
+  let dir;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--') { rest.push(...args.slice(i)); break; }
+    if (args[i] === '--dir' || args[i].startsWith('--dir=')) {
+      if (dir !== undefined) throw new Error('duplicate --dir');
+      dir = args[i] === '--dir' ? args[++i] : args[i].slice(6);
+      if (!dir || dir.startsWith('--')) throw new Error('--dir needs a path');
+    } else rest.push(args[i]);
+  }
+  return { dir: dir === undefined ? undefined : resolve(dir), rest };
+}
+
+export function scaffold(template, target) {
+  const path = resolve(target);
+  const parts = dirname(path).slice(parse(path).root.length).split(sep).filter(Boolean);
+  let parent = parse(path).root;
+  for (const part of parts) {
+    parent = join(parent, part);
+    try {
+      const stat = lstatSync(parent);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`scaffold parent must be a real directory: ${parent}`);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      mkdirSync(parent);
+    }
+  }
+  writeFileSync(path, readFileSync(join(COMMON, template)), { flag: 'wx', mode: 0o600 });
+  console.log(`Created ${path}`);
+  return 0;
+}
+
+function readChecks(path) {
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+  let config;
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error('checks file must be a regular JSON file of at most 1 MiB');
+    config = JSON.parse(readFileSync(fd, 'utf8'));
+  } finally { closeSync(fd); }
+  if (!config || config.version !== 1 || !Array.isArray(config.checks) || !config.checks.length) throw new Error('expected version: 1 and a non-empty checks array');
+  const ids = new Set();
+  for (const check of config.checks) {
+    if (!check || typeof check.id !== 'string' || !/^[A-Za-z0-9_.-]{1,100}$/.test(check.id) || ids.has(check.id)) throw new Error('each check needs a unique id (letters, digits, _, . or -)');
+    ids.add(check.id);
+    if (check.manual !== true && !(typeof check.command === 'string' && check.command.trim()) && !(Array.isArray(check.command) && check.command.length && check.command.every(s => typeof s === 'string' && s.length > 0 && !s.includes('\0')))) throw new Error(`${check.id}: command must be a string or a non-empty argv array`);
+    if (typeof check.command === 'string' && check.command.includes('\0')) throw new Error(`${check.id}: command contains a null byte`);
+    if (check.cwd !== undefined && (typeof check.cwd !== 'string' || !check.cwd)) throw new Error(`${check.id}: cwd must be a path`);
+    if (check.timeoutMs !== undefined && (!Number.isInteger(check.timeoutMs) || check.timeoutMs < 1 || check.timeoutMs > 3600000)) throw new Error(`${check.id}: timeoutMs must be between 1 and 3600000`);
+  }
+  return config.checks;
+}
+
+export function runChecks(file) {
+  const path = resolve(file);
+  // Validate the whole file before the first command can mutate anything.
+  const checks = readChecks(path);
+  let failed = false;
+  for (const check of checks) {
+    if (check.manual === true) {
+      console.log(`FAIL ${check.id}: manual check is UNVERIFIED`);
+      failed = true;
+      continue;
+    }
+    const cwd = resolve(dirname(path), check.cwd || '.');
+    let command, args, options = {};
+    if (typeof check.command === 'string') {
+      command = check.command;
+      args = [];
+      options.shell = true; // Explicit local shell program supplied by the checks file's author.
+    } else {
+      const argv = [...check.command];
+      if (argv[0] === 'node') argv[0] = process.execPath;
+      const plan = windowsSpawnPlan(argv);
+      if (plan.refuse) {
+        console.log(`FAIL ${check.id}: ${plan.refuse}`);
+        failed = true;
+        continue;
+      }
+      ({ command, args, options = {} } = plan);
+    }
+    const result = spawnSync(command, args, { ...options, cwd, stdio: 'inherit', timeout: check.timeoutMs || 30000, killSignal: 'SIGKILL' });
+    const pass = !result.error && result.status === 0;
+    failed ||= !pass;
+    console.log(`${pass ? 'PASS' : 'FAIL'} ${check.id}: ${result.error ? result.error.code : result.signal ? `signal ${result.signal}` : `exit ${result.status}`}`);
+  }
+  return failed ? 1 : 0;
+}
+
+// Unlike a runner lookup, this discovers data only. lstat plus O_NOFOLLOW
+// refuses symlinks; an identity check and bounded read cover replacement/growth.
+export function readManifestRoles({ dir, cwd = process.cwd() } = {}) {
+  const candidates = [
+    ...(dir === undefined ? [] : [join(resolve(cwd, dir), 'MANIFEST.json')]),
+    join(cwd, 'ai-orchestrator', 'MANIFEST.json'),
+    join(cwd, 'MANIFEST.json')
+  ];
+  const maxBytes = 1024 * 1024;
+  const roleIds = new Set(ROLE_SPECS.map(spec => spec.id));
+  for (const path of new Set(candidates)) {
+    let fd;
+    try {
+      const before = lstatSync(path);
+      if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes) continue;
+      fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+      const after = fstatSync(fd);
+      if (!after.isFile() || after.size > maxBytes || after.dev !== before.dev || after.ino !== before.ino) continue;
+      const buffer = Buffer.alloc(maxBytes + 1);
+      let length = 0;
+      while (length < buffer.length) {
+        const count = readSync(fd, buffer, length, buffer.length - length, null);
+        if (!count) break;
+        length += count;
+      }
+      if (length > maxBytes) continue;
+      const manifest = JSON.parse(buffer.toString('utf8', 0, length));
+      const roles = manifest?.roles;
+      if (!roles || typeof roles !== 'object' || Array.isArray(roles) || !Object.keys(roles).length) continue;
+      if (Object.entries(roles).some(([id, role]) => !roleIds.has(id) || !role || typeof role !== 'object' || Array.isArray(role)
+          || (role.ai !== null && (typeof role.ai !== 'string' || !role.ai))
+          || !['main-agent', 'cli-run', 'subagent', 'manual', 'local', 'none'].includes(role.via)
+          || ['agent', 'tier', 'command', 'why', 'reason'].some(key => role[key] !== undefined && typeof role[key] !== 'string'))) continue;
+      return roles;
+    } catch {
+      // Missing, invalid, non-regular or unreadable JSON is an absent manifest.
+    } finally {
+      if (fd !== undefined) closeSync(fd);
+    }
+  }
+  return null;
+}
+
+function stackSuggestion(assignment) {
+  if (!assignment) return 'Your stack: none selected. Re-run the installer to assign this role.';
+  const clean = value => String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ');
+  const reason = assignment.why || assignment.reason;
+  if (!assignment.ai) return `Your stack: none selected${reason ? `. ${clean(reason)}` : '.'}`;
+  const name = clean(byId[assignment.ai]?.name || assignment.ai);
+  let via;
+  if (assignment.command) via = '`' + clean(assignment.command.startsWith('cli-run ') ? `aunx ${assignment.command}` : assignment.command) + '`';
+  else if (assignment.agent) via = '`' + clean(assignment.agent) + '` on your main agent';
+  else via = { 'main-agent': 'your main agent', local: 'your local runtime', manual: 'manual handoff', subagent: 'a subagent', 'cli-run': 'cli-run' }[assignment.via];
+  return `Your stack: ${name}, via ${via || 'your selected tool'}${reason ? ` (${clean(reason)})` : ''}.`;
+}
+
+// Ordered by the action requested. These are suggestions, so the project rules remain authoritative.
+export function suggestRoute(task) {
+  const text = task.toLowerCase();
+  const routes = [
+    [/\b(verify|reproduce|validate|confirm|check)\b.*\b(findings?|reports?|bugs?)\b/, 'finding-verifier', 'working model', 'high', 'Reproduce each claim against the named evidence.', 'verify'],
+    [/\b(definition[- ]of[- ]done|acceptance checks?|completion|finished|done)\b.*\b(check|verify|met|audit)\b|\b(check|verify)\b.*\b(done|complete|completion|acceptance)\b/, 'done-verifier', 'cheap model', 'low', 'Probe the stated definition of done.', 'verify'],
+    [/\b(review|audit)\b/, 'code-reviewer', 'working model', 'high', 'Review the change and reproduce potential defects.', 'review'],
+    [/\b(latest|current|live|news|search|browse|research|look up)\b/, 'live-researcher', 'working model', 'medium', 'Fetch current evidence before drawing a conclusion.', 'research'],
+    [/\b(read(?:ing)?|summari[sz]e|digest|scan)\b.*\b(files|notes|documents|codebase|repo|folder)\b/, 'reader', 'cheap model', 'low', 'Read the requested files and return cited facts.', 'read'],
+    [/\b(design|architect(?:ure)?|ambiguous|tradeoffs?|plan|strategy|unknown cause|find why|debug|diagnose|investigate)\b/, 'deep-planner', 'planning model', 'xhigh', 'Resolve the design and interfaces before building; use equivalent effort where xhigh is unavailable.', 'plan'],
+    [/\b(rename|format|sort|classify|tag|bulk|mechanical|replace|lint)\b/, 'bulk-worker', 'cheap model', 'low', 'Apply a repeatable mechanical change.', 'bulk'],
+    [/\b(build(?:ing)?|implement|code|fix|create|write|add|refactor)\b/, 'builder', 'working model', 'high', 'Build within a task brief and run its acceptance checks.', 'build']
+  ];
+  for (const [pattern, agent, tier, effort, reason, role] of routes) if (pattern.test(text)) return { agent, tier, effort, reason, role };
+  return null;
+}
+
+export async function main(args) {
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) { console.log(HELP); return 0; }
+  const [command, ...rest] = args;
+  if (command === 'install') return runNode(join(ROOT, 'bin', 'cli.js'), rest);
+  if (command === 'cli-run') {
+    const parsed = runnerArgs(rest);
+    // The packaged runner is the default. A project's own runner only runs
+    // when --dir names it explicitly (R1); this is the one place cli-run
+    // dispatch can execute code from outside the package.
+    if (parsed.dir !== undefined) {
+      const local = join(parsed.dir, 'bin', 'cli-run.mjs');
+      if (regular(local)) {
+        console.error(`aunx: using project runner ${local}`);
+        return runNode(local, parsed.rest);
+      }
+    }
+    return runNode(join(ROOT, 'bin', 'cli-run.mjs'), parsed.rest);
+  }
+  if (command === 'route-metrics') {
+    const local = join(process.cwd(), '.claude', 'hooks', 'route-metrics.mjs');
+    return runNode(regular(local) ? local : join(ROOT, 'templates', 'agents', 'snippets', 'route-metrics.mjs'), rest.length ? rest : ['--summary']);
+  }
+  if (command === 'brief' && rest.length === 0) { process.stdout.write(readFileSync(join(COMMON, 'TASK_BRIEF.md'), 'utf8')); return 0; }
+  if (['brief', 'context', 'checks'].includes(command)) {
+    if (rest.length === 1 && ['--help', '-h'].includes(rest[0])) { console.log(HELP); return 0; }
+    if (command === 'checks' && rest[0] === 'run') {
+      if (rest.length > 2) throw new Error('usage: aunx checks run [PATH]');
+      return runChecks(rest[1] || 'ACCEPTANCE_CHECKS.json');
+    }
+    const tail = rest[0] === 'new' ? rest.slice(1) : rest;
+    if (tail.length > 1 || tail[0]?.startsWith('-')) throw new Error(`usage: aunx ${command} [new] [PATH]`);
+    const template = { brief: 'TASK_BRIEF.md', context: 'CONTEXT.md', checks: 'ACCEPTANCE_CHECKS.json' }[command];
+    return scaffold(template, tail[0] || template);
+  }
+  if (command === 'route') {
+    if (rest.length === 1 && ['--help', '-h'].includes(rest[0])) { console.log(HELP); return 0; }
+    const parsed = runnerArgs(rest);
+    if (parsed.rest.length !== 1 || !parsed.rest[0].trim()) throw new Error('usage: aunx route [--dir PATH] "<task>"');
+    const route = suggestRoute(parsed.rest[0]);
+    const roles = readManifestRoles({ dir: parsed.dir });
+    console.log(route ? `Suggestion: ${roles ? route.role : route.agent} | tier: ${route.tier} | effort: ${route.effort}\n${roles ? stackSuggestion(roles[route.role]) + '\n' : ''}${route.reason} Confirm against your ROUTING.md.` : 'Suggestion: unknown task category. Read your ROUTING.md and choose a route for the task.');
+    if (!roles) console.log('No install found; run the installer or pass --dir to see who your stack assigns.');
+    return 0;
+  }
+  return runNode(join(ROOT, 'bin', 'cli.js'), args);
+}