@shomra/agent 0.3.13 → 0.3.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shomra/agent",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "Shomra — adversarial assurance for AI agents, as a local-first CLI. Blocks dangerous tool-calls before they run, attacks your own guardrails to prove they hold, and gates AI artifacts in your editor and CI.",
   "type": "module",
   "bin": {

package/shomra.mjs

@@ -175,12 +175,13 @@ async function api(url, key, route, body, opts = {}) {
   const timer = setTimeout(() => ctrl.abort(), timeoutMs);
   let res;
   try {
+    const method = opts.method ?? 'POST';
     res = await fetch(`${url}${route}`, {
-      method: 'POST',
+      method,
       // Connection: close avoids undici keep-alive sockets lingering after the
       // command finishes (which can crash process.exit on Windows).
       headers: { 'Content-Type': 'application/json', 'X-Shomra-Key': key, Connection: 'close' },
-      body: JSON.stringify(body),
+      ...(method === 'GET' ? {} : { body: JSON.stringify(body) }),
       signal: ctrl.signal,
     });
   } catch (e) {
@@ -219,7 +220,7 @@ const BOOLEAN_FLAGS = new Set([
   'apply', 'dry-run', 'global', 'local', 'trailer', 'evolve', 'report', 'init',
   'no-suppress', 'no-baseline', 'no-policy', 'no-index', 'adaptive',
   'fail-on-regression', 'fail-on-blocked', 'write', 'yes', 'stdin', 'quiet', 'help',
-  'check', 'checklist', 'pre-receive', 'uninstall',
+  'check', 'checklist', 'pre-receive', 'uninstall', 'save', 'list',
 ]);
 // Flags that take a value (`--key value` or `--key=value`).
 const VALUE_FLAGS = new Set([
@@ -230,8 +231,25 @@ const VALUE_FLAGS = new Set([
   // `--fail-on <critical|high|medium>` lets CI gate below the default
   // (blocked-only) exit code — e.g. fail the build on a HIGH finding.
   'fail-on',
+  // `shomra design --save --subject KIND:id` — pin the analysis to a subject.
+  'subject', 'title', 'note', 'actor',
+  // `shomra run <playbook> --input key=value` — repeatable, see REPEATABLE_FLAGS.
+  'input',
 ]);
 const KNOWN_FLAGS = new Set([...BOOLEAN_FLAGS, ...VALUE_FLAGS]);
+// ⚠ Flags that ACCUMULATE instead of overwriting. Everything else keeps the
+// last value; a playbook takes several inputs, and silently dropping all but
+// the last one would run it on defaults nobody asked for.
+const REPEATABLE_FLAGS = new Set(['input']);
+
+function setFlag(flags, name, value) {
+  if (!REPEATABLE_FLAGS.has(name)) {
+    flags[name] = value;
+    return;
+  }
+  const prev = flags[name];
+  flags[name] = prev === undefined ? value : [].concat(prev, value);
+}
 
 function parseFlags(argv) {
   const flags = {};
@@ -247,7 +265,7 @@ function parseFlags(argv) {
       if (eq !== -1) {
         const name = body.slice(0, eq);
         if (!KNOWN_FLAGS.has(name)) unknown.push(name);
-        flags[name] = body.slice(eq + 1);
+        setFlag(flags, name, body.slice(eq + 1));
         continue;
       }
       if (!KNOWN_FLAGS.has(body)) {
@@ -261,7 +279,7 @@ function parseFlags(argv) {
       }
       const next = argv[i + 1];
       if (next !== undefined && !next.startsWith('--')) {
-        flags[body] = next;
+        setFlag(flags, body, next);
         i++;
       } else flags[body] = true;
     } else positional.push(a);
@@ -2728,6 +2746,114 @@ async function cmdMemoryScan(flags, positional) {
 // `--min <resilience>` and/or `--fail-on-regression`. Exit: 0 = pass,
 // 2 = below the resilience floor or a regression appeared.
 
+// ── playbooks: the whole assurance loop as ONE command ────────────────────
+//
+// `pre-release` and `agent-release-check` were written to be run by a pipeline
+// and had no client — the backend has carried an API-key controller for exactly
+// this since the engine shipped. Exit code is the product: a failed `gate` step
+// comes back FAILED, and that is the assertion holding, not a broken run.
+
+const STEP_MARK = { SUCCESS: () => green('✓'), FAILED: () => red('✗'), SKIPPED: () => dim('–'), RUNNING: () => cyan('•'), PENDING: () => dim('·') };
+
+async function cmdRun(flags, positional) {
+  const id = positional[0];
+
+  /**
+   * ⚠ USAGE BEFORE ENROLMENT. A malformed `--input` is a typo the caller can
+   * fix without a key, and answering it with "not configured" sends them to
+   * the wrong problem.
+   *
+   * --input k=v, repeatable. Numbers and booleans keep their type, because a
+   * threshold arriving as "80" is not the same argument.
+   */
+  const inputs = {};
+  for (const raw of [].concat(flags.input ?? [])) {
+    const eq = String(raw).indexOf('=');
+    if (eq < 0) {
+      console.error(`  ${red('✗')} --input expects key=value (got ${JSON.stringify(raw)})\n`);
+      process.exit(EXIT_USAGE);
+    }
+    const k = String(raw).slice(0, eq).trim();
+    const v = String(raw).slice(eq + 1);
+    inputs[k] = v === 'true' ? true : v === 'false' ? false : /^-?\d+(\.\d+)?$/.test(v) ? Number(v) : v;
+  }
+
+  const cfg = loadConfig();
+  const { apiKey, url } = resolveSettings(cfg);
+  if (!apiKey) exitNotConfigured();
+
+  if (!id || flags.list) {
+    let catalog;
+    try {
+      catalog = await api(url, apiKey, '/playbooks/agent/catalog', null, { method: 'GET' });
+    } catch (e) {
+      console.error(`  ${red('✗')} ${e.message}\n`);
+      process.exit(1);
+    }
+    if (flags.json) {
+      console.log(JSON.stringify(catalog, null, 2));
+      return;
+    }
+    console.log(`\n  ${bold('Playbooks')} ${dim('— run one end-to-end, exit non-zero when a gate holds')}\n`);
+    for (const p of catalog) {
+      console.log(`  ${cyan(p.id)} ${dim(`v${p.version} · ${p.steps.length} steps`)}`);
+      console.log(`    ${p.name}`);
+      const required = Object.entries(p.inputs || {}).filter(([, d]) => d.required).map(([k]) => k);
+      if (required.length) console.log(`    ${dim('needs')} ${required.map((k) => bold(k)).join(', ')}`);
+      console.log('');
+    }
+    console.log(dim(`  Run one:  ${bold('shomra run <id> --input key=value')}\n`));
+    if (!id) process.exitCode = EXIT_USAGE;
+    return;
+  }
+
+  if (!flags.json) process.stdout.write(dim(`\n  Running ${bold(id)}… `));
+  let run;
+  try {
+    run = await api(url, apiKey, `/playbooks/agent/${encodeURIComponent(id)}/run`, {
+      inputs,
+      ...(flags.project ? { projectId: String(flags.project) } : {}),
+      actor: `${os.hostname()}/${os.userInfo().username}`,
+    });
+  } catch (e) {
+    if (!flags.json) console.log(red('failed'));
+    console.error(`  ${red('✗')} ${e.message}\n`);
+    process.exit(1);
+  }
+  if (!flags.json) console.log(green('done'));
+
+  if (flags.json) {
+    console.log(JSON.stringify(run, null, 2));
+  } else {
+    console.log(`\n  ${bold(run.playbookName)} ${dim(`· ${run.playbookId}`)}\n`);
+    for (const s of run.steps || []) {
+      const mark = (STEP_MARK[s.status] || STEP_MARK.PENDING)();
+      // ⚠ SKIPPED is stated as its own thing. A step whose condition was false
+      // did not run, and printing it as a pass claims work nothing did.
+      const note =
+        s.status === 'SKIPPED'
+          ? dim('skipped — its condition was false')
+          : s.error
+            ? (s.uses === 'gate' ? yellow(s.error) : red(s.error))
+            : '';
+      console.log(`  ${mark} ${s.name}${note ? ' ' + dim('·') + ' ' + note : ''}`);
+    }
+    const failedStep = (run.steps || []).find((s) => s.status === 'FAILED');
+    const gateHeld = run.status === 'FAILED' && failedStep?.uses === 'gate';
+    console.log('');
+    if (run.status === 'FAILED' && gateHeld) {
+      console.log(`  ${yellow('⚠')} ${bold('The gate held.')} ${dim('That is the assertion firing — exiting non-zero.')}\n`);
+    } else if (run.status === 'FAILED') {
+      console.log(`  ${red('✗')} ${bold('A step failed.')} ${dim(run.error || '')}\n`);
+    } else {
+      console.log(`  ${green('✓')} ${bold('Completed.')} ${dim('Every step that was meant to run did.')}\n`);
+    }
+  }
+
+  // The exit code IS the feature: a pipeline gates on this.
+  if (run.status === 'FAILED') process.exitCode = 1;
+}
+
 async function cmdRedteam(flags) {
   const cfg = loadConfig();
   const { apiKey, url } = resolveSettings(cfg);
@@ -5067,7 +5193,7 @@ async function addPackage(flags, positional) {
 
 // ── shomra design: threat-model a system before it exists ───────────────────
 //
-//   shomra design <file|dir|-> [--checklist] [--json] [--strict]
+//   shomra design <file|dir|-> [--save --subject KIND:id] [--checklist] [--json] [--strict]
 //
 // The leftmost surface Shomra has. Everything else needs an artifact; this reads
 // a DESCRIPTION — an RFC, a design doc, a Jira/Linear ticket, a PR body — and
@@ -5136,6 +5262,11 @@ async function cmdDesign(flags, positional) {
     }
   }
 
+  // --save pins the analysis to the live capability manifest server-side, so the
+  // dashboard and the CI gate can tell later that the system has moved past it.
+  // Without it the analysis dies with the terminal it printed to.
+  if (flags.save) await saveDesign(results, flags);
+
   // CRITICAL = untrusted input reaching execution or a destructive action. That
   // is a hard fail even without --strict: it is the one shape where the attacker
   // picks the action, and no amount of care in the implementation recovers it.
@@ -5143,6 +5274,55 @@ async function cmdDesign(flags, positional) {
   else if (open.length && flags.strict) process.exitCode = 2;
 }
 
+// ── shomra design --save --subject KIND:id ──────────────────────────────────
+//
+// ⚠ ONE SUBJECT, ONE DOCUMENT. A directory of RFCs produces one analysis each,
+// and pinning several of them to the same subject would leave the subject
+// described by whichever happened to be written last. The command refuses
+// rather than picking.
+async function saveDesign(results, flags) {
+  const { apiKey, url } = resolveSettings(loadConfig());
+  const subject = String(flags.subject ?? '').trim();
+  const m = /^(AGENT|PROJECT|DESIGN):(.+)$/i.exec(subject);
+  if (!m) {
+    console.error(red('✗') + ' --save needs ' + bold('--subject KIND:id') + dim('  (AGENT | PROJECT | DESIGN)'));
+    console.error(dim('  e.g. ') + 'shomra design docs/rfc.md --save --subject DESIGN:inbox-agent');
+    process.exit(EXIT_USAGE);
+  }
+  if (results.length !== 1) {
+    console.error(red('✗') + ` --save takes one document; ${results.length} were modelled.`);
+    console.error(dim('  Save each against its own subject.'));
+    process.exit(EXIT_USAGE);
+  }
+  if (!apiKey || !url) exitNotConfigured();
+
+  const [, kind, id] = m;
+  const r = results[0];
+  process.stdout.write(dim('  Saving to the platform… '));
+  try {
+    const res = await api(url, apiKey, '/threat-models/agent-author', {
+      subjectKind: kind.toUpperCase(),
+      subjectId: id,
+      title: flags.title ? String(flags.title) : r.name,
+      analysis: r,
+      note: flags.note ? String(flags.note) : `Modelled from ${r.name}.`,
+      actor: flags.actor ? String(flags.actor) : undefined,
+    });
+    const v = res?.version;
+    const c = res?.coverage;
+    console.log(green('saved') + dim(` — v${v?.seq ?? '?'}, ${v?.reviewState ?? 'IN_REVIEW'}`));
+    // ⚠ Saving is not approving. A version nobody else has signed off does not
+    // clear the gate, and saying so here is the difference between a stored
+    // document and a control.
+    console.log(dim('  It is not approved yet — a threat model must be reviewed by someone other than its author.'));
+    if (c?.headline) console.log(dim('  ') + c.headline);
+  } catch (e) {
+    console.log(red('failed'));
+    console.error(dim('  ') + (e?.message || String(e)));
+    process.exitCode = 1;
+  }
+}
+
 const DESIGN_DOC_RE = /\.(md|markdown|txt|rst|adoc)$/i;
 const DESIGN_MAX_DOCS = 50;
 
@@ -6596,6 +6776,9 @@ ${bold('COMMANDS')}
   ${cyan('scan')}          Discover AI tooling on this machine    ${dim('[--report] [--json] [--path <dir>]')}
   ${cyan('report')}        Discover + send inventory to your Shomra org ${dim('(alias: scan --report) [--json]')}
   ${cyan('status')}        Show config, enrollment + firewall health
+  ${cyan('run')}           ${bold('Run a whole assurance playbook')} ${dim('<id> [--input k=v]… [--project <id>] [--json]  ·  --list for the catalog')}
+                ${dim('scan → red-team → harden → compliance → gate, as one command. Exits')}
+                ${dim('non-zero when a gate holds, so a pipeline can block the release.')}
 
   ${dim('Setup — run once per machine / repo')}
   ${cyan('init')}          Configure + enroll this machine       ${dim('--key shm_live_… [--url <backend>]')}
@@ -6606,7 +6789,7 @@ ${bold('COMMANDS')}
   ${cyan('doctor')}        ${bold('Am I safe?')} Posture of this machine's AI setup ${dim('[--json]')}
 
   ${dim('Prevention — get in front of the model, not just behind it')}
-  ${cyan('design')}        ${bold('Threat-model a system before it exists')} ${dim('<file|dir|-> [--checklist] [--strict] [--json]')}
+  ${cyan('design')}        ${bold('Threat-model a system before it exists')} ${dim('<file|dir|-> [--save --subject KIND:id] [--checklist] [--strict] [--json]')}
                 ${dim('Reads an RFC / design doc / ticket and says whether it closes a path from')}
                 ${dim('untrusted input to a consequence, plus what must be true before it ships.')}
                 ${dim('Pipe a ticket straight in: ')}${bold('gh issue view 42 --json body -q .body | shomra design -')}
@@ -6844,6 +7027,7 @@ const COMMANDS = {
   scan: (f) => cmdScan(f),
   report: (f) => cmdScan({ ...f, report: true }),
   gate: (f, p) => cmdGate(f, p),
+  run: (f, p) => cmdRun(f, p),
   check: (f, p) => cmdCheck(f, p),
   pr: (f, p) => cmdPr(f, p),
   baseline: (f, p) => cmdBaseline(f, p),