amsd-pipeline-workflow 0.1.0 → 0.1.1

package/README.md

@@ -5,13 +5,17 @@ own scripts) and is installed by the pipeline's installer.
 
 ## Install
 
+Into an existing AMSD pipeline install (the pipeline itself is not changed):
+
 ```bash
-npx amsd-pipeline@<version> --dest <dir> --ref v<version> --no-docker --workflows
+npx amsd-pipeline@<version> --dest <dir> --ref v<version> --no-docker     # the pipeline, as always
+npx amsd-pipeline-workflow install --into <dir> [--codeline-cache <cache>]
 ```
 
-`--workflows` installs the `amsd-pipeline-workflow` version the pipeline release pins
-(`orchestrations/config/claude-workflows.json`) into `<dir>/claude-workflows/`. `--workflows <file.tgz>` installs a
-local package instead (for testing a build before it is published). `--check` verifies it; `--uninstall` removes it.
+This writes only `<dir>/claude-workflows/` and, with `--codeline-cache`, each codeline's cached roster and prompts
+(`<cache>/orchestrations/projects/<project>/.prompt-cache/<codeline>/` and its `.complete-<codeline>[.brownfield]` marker)
+into the same project, so the pipeline reuses them instead of minting and generating again. The pipeline still decides at
+launch whether each is current. Reinstalling replaces `claude-workflows/`.
 
 Needs: Node 20+, the `claude` CLI, `unshare` (util-linux) and `systemd-run --user` (the memory bound, `bin/bounded`).
 

package/bin/amsd-pipeline-workflow.js

@@ -1,7 +1,13 @@
 #!/usr/bin/env node
 'use strict';
-// amsd-pipeline-workflow — the AMSD pipeline as Claude workflows. Installed by the pipeline's own installer
-// (install.sh --workflows) into <install>/claude-workflows/, which writes install.json there naming the install.
+// amsd-pipeline-workflow — the AMSD pipeline as Claude workflows, installed INTO an existing pipeline install with no
+// change to the pipeline (operator, 2026-10-18).
+//   amsd-pipeline-workflow install --into <pipeline install> [--codeline-cache <dir>]
+//        writes <install>/claude-workflows/ (this package's published files, and install.json naming the install) and,
+//        with --codeline-cache, each codeline's cache entry from <dir>/orchestrations/projects/<p>/.prompt-cache/ — its
+//        <codeline>/ folder (the minted roster and the prompts) and its .complete-<codeline>[.brownfield] marker — into the
+//        same project of the install, so the pipeline's own reuse step restores them instead of minting and generating
+//        again. Nothing else in the install is written.
 //   amsd-pipeline-workflow run <driver/run.js arguments>   — --install defaults to the install this was installed into
 //   amsd-pipeline-workflow version
 const fs = require('fs');
@@ -9,9 +15,51 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 
 const ROOT = path.resolve(__dirname, '..');
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
 const [cmd, ...rest] = process.argv.slice(2);
-if (cmd === 'version') { process.stdout.write(`${require(path.join(ROOT, 'package.json')).version}\n`); process.exit(0); }
-if (cmd !== 'run') { process.stderr.write('usage: amsd-pipeline-workflow run <driver arguments> | version\n'); process.exit(64); }
+const fail = (m) => { process.stderr.write(`amsd-pipeline-workflow: ${m}\n`); process.exit(1); };
+const opt = (name) => { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : undefined; };
+
+if (cmd === 'version') { process.stdout.write(`${PKG.version}\n`); process.exit(0); }
+
+if (cmd === 'install') {
+  const into = opt('--into'); const cacheDir = opt('--codeline-cache');
+  if (!into) fail('install needs --into <pipeline install>');
+  const inst = path.resolve(into);
+  if (!fs.existsSync(path.join(inst, 'orchestrations', 'scripts')) || !fs.existsSync(path.join(inst, 'orchestrations', 'projects'))) fail(`${inst} is not a pipeline install (no orchestrations/scripts and orchestrations/projects)`);
+  if (cacheDir && !fs.existsSync(path.join(path.resolve(cacheDir), 'orchestrations', 'projects'))) fail(`${cacheDir} holds no codeline cache (no orchestrations/projects)`);
+  // the package: exactly its published files (package.json "files"), into a new folder, then swapped in
+  const dest = path.join(inst, 'claude-workflows'); const tmp = `${dest}.new`;
+  fs.rmSync(tmp, { recursive: true, force: true }); fs.mkdirSync(tmp, { recursive: true });
+  for (const f of [...PKG.files, 'package.json']) {
+    const src = path.join(ROOT, f.replace(/\/$/, ''));
+    if (fs.existsSync(src)) fs.cpSync(src, path.join(tmp, f.replace(/\/$/, '')), { recursive: true });
+  }
+  fs.writeFileSync(path.join(tmp, 'install.json'), `${JSON.stringify({ install: inst }, null, 2)}\n`);
+  fs.rmSync(dest, { recursive: true, force: true }); fs.renameSync(tmp, dest);
+  process.stdout.write(`claude workflows ${PKG.version} → ${dest}\n`);
+  if (cacheDir) {
+    const projects = path.join(path.resolve(cacheDir), 'orchestrations', 'projects');
+    let n = 0;
+    for (const p of fs.readdirSync(projects)) {
+      const src = path.join(projects, p, '.prompt-cache'); const proj = path.join(inst, 'orchestrations', 'projects', p);
+      if (!fs.existsSync(src) || !fs.existsSync(proj)) continue;
+      for (const m of fs.readdirSync(src).filter((x) => x.startsWith('.complete-'))) {
+        const cl = m.replace(/^\.complete-/, '').replace(/\.brownfield$/, '');
+        if (!fs.existsSync(path.join(src, cl))) continue;
+        const dst = path.join(proj, '.prompt-cache'); fs.mkdirSync(dst, { recursive: true });
+        fs.rmSync(path.join(dst, cl), { recursive: true, force: true });
+        fs.cpSync(path.join(src, cl), path.join(dst, cl), { recursive: true });
+        fs.copyFileSync(path.join(src, m), path.join(dst, m));
+        process.stdout.write(`codeline cache: ${p} / ${cl}\n`); n += 1;
+      }
+    }
+    if (!n) process.stdout.write(`codeline cache: ${cacheDir} holds none to carry\n`);
+  }
+  process.exit(0);
+}
+
+if (cmd !== 'run') { process.stderr.write('usage: amsd-pipeline-workflow install --into <pipeline install> [--codeline-cache <dir>] | run <driver arguments> | version\n'); process.exit(64); }
 const args = [...rest];
 const linked = path.join(ROOT, 'install.json');
 if (!args.includes('--install') && fs.existsSync(linked)) args.unshift('--install', JSON.parse(fs.readFileSync(linked, 'utf8')).install);

package/driver/run.js

@@ -72,6 +72,10 @@ async function main(a) {
     const ck = path.join(a.install, 'orchestrations', 'projects', a.project, 'runs', a['recorded-run'] || a.run, 'lanes', a['recorded-lane'] || Object.keys(map)[0], 'checkpoint');
     for (const f of ['roster.json', 'agent-profiles.json', 'profiles.json']) if (fs.existsSync(path.join(ck, f))) fs.copyFileSync(path.join(ck, f), path.join(project, f));
   }
+  // the run's profiles: AGENT_PROFILES_FILE defaults to the agents folder's (run-agent-orchestration.sh:404) — the run's
+  // own copy of it when no checkpoint gave one (a fresh install's project holds none); the install's is never written
+  const agentsProfiles = path.join(a.install, 'orchestrations', 'agents', 'profiles.json');
+  if (!fs.existsSync(path.join(project, 'profiles.json')) && fs.existsSync(agentsProfiles)) fs.copyFileSync(agentsProfiles, path.join(project, 'profiles.json'));
   const er = spawnSync('bash', [path.join(__dirname, 'env.sh'), a.install, a.project, a.run, runDir, set], { encoding: 'utf8', env: baseEnv, maxBuffer: 64 * 1024 * 1024 });
   if (er.status !== 0) throw new Error(`the run's environment did not load: ${er.stderr}`);
   let env = { ...JSON.parse(er.stdout), AGENT_PROFILES_FILE: path.join(project, 'profiles.json'), PIPELINE_PROFILES: path.join(project, 'profiles.json'),

package/generator/generate-agents.js

@@ -84,6 +84,29 @@ function hubSi(art, agent, codelineRoot, work, projectEnv) {
   return relativizeLocalPaths(fs.readFileSync(out, 'utf8'), [codelineRoot]);
 }
 
+/** THE ROSTER THE RUN STARTS FROM (lib/mint-and-spec.sh:156–232). When this run's codeline has a completion marker and a
+ *  recorded roster, the pipeline restores that roster before the mint (both of its reuse branches, :170–175 and :183–192)
+ *  and the hub reads each agent's SI from it at call time; the stage's agents are generated from that roster — by the
+ *  pipeline's own restoreMinted, on a scratch copy of the project (the install is never written). Otherwise the project's
+ *  roster as it is. The codeline: EPAM_CODELINE_ID, else the PRD's single output folder (codelineFromPrd, :157–165). */
+function siProjectDir(art, prdFile, projectEnv, work) {
+  const env = { ...process.env, ...projectEnv };
+  if (env.EPAM_REGENERATE_CODELINE_ASSETS === '1') return art.projectDir;
+  const b = require(path.join(art.scripts, 'lib', 'project-prompt-builder.js'));
+  const cl = String(env.EPAM_CODELINE_ID || '').trim() || b.codelineFromPrd(prdFile);
+  if (!cl) return art.projectDir;
+  const marker = path.join(art.projectDir, '.prompt-cache', `.complete-${cl}${env.EPAM_BROWNFIELD === '1' ? '.brownfield' : ''}`);   // prompt-variant.sh:15–21
+  if (!fs.existsSync(marker) || !b.hasMintedSnapshot({ projectConfigDir: art.projectDir, codeline: cl })) return art.projectDir;
+  const dir = path.join(work, 'si-project'); fs.rmSync(dir, { recursive: true, force: true }); fs.mkdirSync(dir, { recursive: true });
+  for (const f of fs.readdirSync(art.projectDir)) {
+    if (f === 'runs' || f === 'prompts') continue;
+    if (f === '.prompt-cache') fs.symlinkSync(path.join(art.projectDir, f), path.join(dir, f));
+    else fs.cpSync(path.join(art.projectDir, f), path.join(dir, f), { recursive: true });
+  }
+  b.restoreMinted({ projectConfigDir: dir, codeline: cl });
+  return dir;
+}
+
 function stepRunner(name, description, hookArgs, firstTier) {
   return { name, pipelineAgent: null, seam: null, ladder: '',
     frontmatter: { name, description, model: firstTier.startModel,
@@ -158,8 +181,9 @@ function main(a) {
   const scratch = path.join(work, 'seam'); fs.mkdirSync(scratch, { recursive: true });
   const defs = []; const agentMap = {}; const si = {}; const noSi = [];
   const projectEnv = pipe.projectEnv(art);
+  const siArt = { ...art, projectDir: siProjectDir(art, seedPrd, projectEnv, work) };
   for (const s of seamNames) {
-    const body = hubSi(art, s, path.resolve(a['codeline-root']), work, projectEnv);
+    const body = hubSi(siArt, s, path.resolve(a['codeline-root']), work, projectEnv);
     // A seam the hub has no SI for is a call the hub itself refuses (llm-handler.sh: "refusing the call"); it gets no
     // agent here either, and is listed.
     if (body == null) { noSi.push(s); continue; }

package/package.json

@@ -1,10 +1,25 @@
 {
   "name": "amsd-pipeline-workflow",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The AMSD pipeline as Claude workflows. Installed by the amsd-pipeline installer: install.sh --workflows",
   "license": "UNLICENSED",
-  "bin": { "amsd-pipeline-workflow": "bin/amsd-pipeline-workflow.js" },
-  "files": ["bin/", "driver/", "generator/", "hooks/", "mcp/", "README.md"],
-  "engines": { "node": ">=20" },
-  "amsdPipeline": { "tested": "2.0.78" }
+  "bin": {
+    "amsd-pipeline-workflow": "bin/amsd-pipeline-workflow.js"
+  },
+  "files": [
+    "bin/",
+    "driver/",
+    "generator/",
+    "hooks/",
+    "mcp/",
+    "test/layer1/harness.js",
+    "test/layer1/hook-harness.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "amsdPipeline": {
+    "tested": "2.0.78"
+  }
 }

package/test/layer1/harness.js

@@ -0,0 +1,57 @@
+'use strict';
+// LAYER 1 HARNESS (docs/TESTING.md) — runs a REAL workflow script's body with the workflow runtime's primitives,
+// agents answered by a generative stand-in. No AI. Matches the runtime rules the docs state:
+//   - `export const meta` must be a plain literal and the first statement;
+//   - Date.now(), Math.random() and a no-argument new Date() THROW inside the script;
+//   - an agent that fails resolves to null; parallel()/pipeline() keep nulls in place;
+//   - an agent given a `schema` returns an object matching it.
+const vm = require('vm');
+
+/** Fill a JSON schema's required fields generatively (the shape a model would return), then apply overrides. */
+function fromSchema(schema, overrides) {
+  const out = {};
+  const props = (schema && schema.properties) || {};
+  for (const k of (schema && schema.required) || Object.keys(props)) {
+    const t = (props[k] || {}).type;
+    out[k] = t === 'boolean' ? false : t === 'number' || t === 'integer' ? 0 : t === 'array' ? [] : t === 'object' ? fromSchema(props[k], {}) : `generated-${k}`;
+  }
+  return { ...out, ...(overrides || {}) };
+}
+
+/**
+ * Run a workflow script.
+ * @param {string} source  the script text (as emitted)
+ * @param {object} args    the `args` global
+ * @param {(call) => object|null} answer  stand-in (may be async): given {n, prompt, opts}, return overrides for a schema answer, a
+ *                                        string for a text answer, or null for an agent that failed
+ */
+async function run(source, args, answer) {
+  const metaMatch = source.match(/^\s*export const meta\s*=\s*(\{[\s\S]*?\n\})\s*\n/);
+  if (!metaMatch) throw new Error('script does not start with `export const meta = {…}`');
+  const meta = vm.runInNewContext(`(${metaMatch[1]})`, {});      // a literal, or this throws
+  const body = source.slice(metaMatch[0].length);
+  const calls = []; const phases = []; const logs = [];
+  const agent = async (prompt, opts = {}) => {
+    const call = { n: calls.length + 1, prompt: String(prompt), opts, phase: phases[phases.length - 1] || null };
+    calls.push(call);
+    const a = await answer(call);
+    if (a === null || a === undefined) return null;
+    if (opts.schema) return fromSchema(opts.schema, typeof a === 'object' ? a : {});
+    return typeof a === 'string' ? a : JSON.stringify(a);
+  };
+  const parallel = async (thunks) => Promise.all(thunks.map((t) => t().catch(() => null)));
+  const pipeline = async (items, ...stages) => Promise.all(items.map(async (it, i) => {
+    let v = it;
+    for (const st of stages) { try { v = await st(v, it, i); } catch { return null; } }
+    return v;
+  }));
+  const BadDate = function (...a) { if (!a.length) throw new Error('new Date() is not allowed in a workflow'); return new Date(...a); };
+  BadDate.now = () => { throw new Error('Date.now() is not allowed in a workflow'); };
+  const BadMath = Object.create(Math); BadMath.random = () => { throw new Error('Math.random() is not allowed in a workflow'); };
+  const ctx = vm.createContext({ agent, parallel, pipeline, phase: (t) => phases.push(t), log: (m) => logs.push(m),
+    args, Date: BadDate, Math: BadMath, JSON, Array, Object, String, Number, Boolean, Set, Map, Promise, Error, RegExp });
+  const result = await vm.runInContext(`(async () => {\n${body}\n})()`, ctx);
+  return { meta, result, calls, phases, logs };
+}
+
+module.exports = { run, fromSchema };

package/test/layer1/hook-harness.js

@@ -0,0 +1,43 @@
+'use strict';
+// THE LAYER-1 HARNESS WITH THE AGENTS' HOOKS (docs/TESTING.md). test/layer1/harness.js runs the real script with a
+// stand-in for every agent; this runs, in addition, each agent definition's own PreToolUse hook on the stand-in's answer
+// — the generated command, from the generated agents file — exactly as Claude Code would when the agent submits its
+// StructuredOutput: the hook's `updatedInput` becomes the answer the script sees. An agent the stand-in fails (null)
+// never answers, so its hook never runs. No AI.
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+const { run } = require('./harness.js');
+
+/**
+ * @param {string} source       the emitted script
+ * @param {object} args         the script's `args`
+ * @param {string} agentsFile   the generated agents JSON (frontmatter hooks per agent name)
+ * @param {(call) => object|null} answer  the stand-in: the raw answer object, or null for an agent that failed
+ */
+async function runWithHooks(source, args, agentsFile, answer) {
+  const defs = JSON.parse(fs.readFileSync(agentsFile, 'utf8'));
+  const hookRuns = [];
+  const r = await run(source, args, (call) => {
+    const a = answer(call);
+    if (a === null || a === undefined) return null;
+    const def = defs[call.opts.agentType];
+    if (!def) throw new Error(`no generated definition for agent type '${call.opts.agentType}'`);
+    const pre = ((def.hooks || {}).PreToolUse || []).filter((h) => new RegExp(`^(${h.matcher})$`).test('StructuredOutput'));
+    let input = a;
+    for (const h of pre) for (const c of h.hooks || []) {
+      const res = spawnSync('bash', ['-c', c.command], { input: JSON.stringify({ hook_event_name: 'PreToolUse', tool_name: 'StructuredOutput', tool_input: input }),
+        encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+      hookRuns.push({ agentType: call.opts.agentType, status: res.status, stderr: (res.stderr || '').slice(-2000) });
+      if (res.status !== 0) throw new Error(`hook of ${call.opts.agentType} exited ${res.status}: ${(res.stderr || '').slice(-1500)}`);
+      const outLine = String(res.stdout || '').trim().split('\n').pop();
+      const o = outLine ? JSON.parse(outLine) : {};
+      const upd = o.hookSpecificOutput && o.hookSpecificOutput.updatedInput;
+      if (upd) input = upd;
+    }
+    call.answered = input;
+    return input;
+  });
+  return { ...r, hookRuns };
+}
+
+module.exports = { runWithHooks };