@plainconceptsplatform/workflows 0.5.1 → 0.16.0

package/dist/stack-defaults.js

@@ -0,0 +1,110 @@
+export function generateStackDefaults(inspection) {
+    const hasDotnet = inspection.stackHints.solutionFiles.length > 0;
+    const hasNode = inspection.stackHints.pnpmLockfile;
+    const hasNodeOnly = hasNode && !hasDotnet;
+    let verifyCommands;
+    let repoRulesBase;
+    if (hasDotnet && hasNode) {
+        verifyCommands = ".NET: dotnet restore && dotnet build -c Release && dotnet test | Web: pnpm lint && pnpm test && pnpm build";
+        repoRulesBase = "Full-stack .NET + React/Next.js repository. Follow Clean Architecture layering: API → Application → Domain. Infrastructure implements Application ports. Do not reference EF Core or ASP.NET from Application. Frontend communicates exclusively via HTTP endpoints. Run both .NET and frontend verification.";
+    }
+    else if (hasDotnet) {
+        verifyCommands = "dotnet restore && dotnet build -c Release --no-restore && dotnet test";
+        repoRulesBase = ".NET repository using Clean Architecture. Follow layering: API → Application → Domain. Infrastructure implements Application ports. Do not reference EF Core or ASP.NET from Application.";
+    }
+    else {
+        verifyCommands = "pnpm verify";
+        repoRulesBase = "Node.js repository. Follow existing project conventions and import boundaries.";
+    }
+    return { verifyCommands, repoRulesBase, hasDotnet, hasNodeOnly };
+}
+// Only a worker that prints a verification block declares VERIFY_COMMANDS. Adding the key to
+// the others made byte-identical workers read as changed on every update, so a worker without
+// the key is left without it.
+export function injectStackEnv(content, defaults) {
+    return content.replace(/^  VERIFY_COMMANDS: .*$/m, `  VERIFY_COMMANDS: "${defaults.verifyCommands}"`);
+}
+export function generateOpencodeCi(baseContent, inspection) {
+    let result = baseContent;
+    // Idempotent on purpose: this runs on every install and update, and the shared file already
+    // carries some of these steps. A step is added only when no step of that name exists.
+    if (inspection.stackHints.solutionFiles.length > 0) {
+        const solutionPath = inspection.stackHints.solutionFiles[0].replaceAll("\\", "/");
+        if (!result.includes("name: Cache NuGet packages")) {
+            const nugetCache = `  - name: Cache NuGet packages
+    uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+    with:
+      path: ~/.nuget/packages
+      key: nuget-\${{ runner.os }}-\${{ hashFiles('**/*.slnx', '**/Directory.Packages.props') }}
+      restore-keys: nuget-\${{ runner.os }}-
+
+`;
+            result = insertBeforeMarker(result, nugetCache, "  - name: Install workspace dependencies");
+        }
+        if (!result.includes("name: Restore .NET dependencies")) {
+            const restore = `  - name: Restore .NET dependencies
+    run: dotnet restore ${solutionPath}
+
+`;
+            result = insertBeforeMarker(result, restore, "  - name: Install workspace dependencies");
+        }
+    }
+    if (inspection.stackHints.openSpec && !result.includes("name: Install OpenSpec CLI")) {
+        const openspecStep = `  - name: Install OpenSpec CLI
+    run: |
+      set -euo pipefail
+      npm install -g "@fission-ai/openspec@1.8.0"
+      openspec --version
+
+`;
+        result = insertBeforeMarker(result, openspecStep, "  - name: Install workspace dependencies");
+    }
+    if (inspection.stackHints.packageJson && !result.includes("--legacy-peer-deps")) {
+        result = result.replace(`      if ! npm install --prefix .opencode; then\n        echo "No plugin deps, skipping."\n        exit 0\n      fi`, `      if ! npm install --prefix .opencode; then\n        echo "::warning::Strict npm install failed on a peer conflict. Retrying with --legacy-peer-deps; check .opencode/package.json."\n        npm install --prefix .opencode --legacy-peer-deps\n      fi`);
+    }
+    return result;
+}
+function insertBeforeMarker(content, steps, marker) {
+    if (content.includes(marker)) {
+        return content.replace(marker, steps + marker);
+    }
+    return content + "\n" + steps;
+}
+export function generateOpencodeConfig(baseContent, inspection) {
+    try {
+        const config = JSON.parse(baseContent);
+        const hasDotnet = inspection.stackHints.solutionFiles.length > 0;
+        if (!hasDotnet && config.lsp !== undefined) {
+            delete config.lsp;
+        }
+        else if (hasDotnet && config.lsp === undefined) {
+            config.lsp = {
+                csharp: { disabled: true },
+                fsharp: { disabled: true },
+                razor: { disabled: true },
+            };
+        }
+        const agent = config.agent;
+        if (agent !== undefined) {
+            const agentEntry = agent["ci-workflow-agent"];
+            if (agentEntry !== undefined) {
+                let prompt = agentEntry.prompt ?? "";
+                if (hasDotnet) {
+                    if (!prompt.includes(".NET guardrails")) {
+                        prompt += "\n\n# .NET guardrails\nFollow Clean Architecture layering: API → Application → Domain. Infrastructure implements Application ports. Application must not reference EF Core or ASP.NET. Use Central Package Management (Directory.Packages.props). Build in Release mode for CI.";
+                    }
+                }
+                else {
+                    if (!prompt.includes("Node/React rules")) {
+                        prompt += "\n\n# Node/React rules\nFollow Feature-Sliced Design import boundaries. Use pnpm, never npm or yarn. All user-facing text must be i18n messages. TypeScript strict mode.";
+                    }
+                }
+                agentEntry.prompt = prompt;
+            }
+        }
+        return JSON.stringify(config, null, 2) + "\n";
+    }
+    catch {
+        return baseContent;
+    }
+}

package/dist/tui.d.ts

@@ -0,0 +1,25 @@
+import { type CatalogEntry } from "./catalog-listing.js";
+export type SelectionStatus = "selecting" | "submitting" | "cancelled";
+export interface SelectionState {
+    readonly allItems: readonly CatalogEntry[];
+    readonly visibleItems: readonly CatalogEntry[];
+    readonly selected: ReadonlySet<string>;
+    readonly cursor: number;
+    readonly filter: string;
+    readonly status: SelectionStatus;
+}
+export interface InteractiveOptions {
+    readonly force?: boolean;
+}
+export declare function createSelectionState(entries: readonly CatalogEntry[]): SelectionState;
+export declare function fuzzyMatch(text: string, query: string): boolean;
+export declare function filterItems(items: readonly CatalogEntry[], filter: string): readonly CatalogEntry[];
+export declare function applyFilter(state: SelectionState, filter: string): SelectionState;
+export declare function clearFilter(state: SelectionState): SelectionState;
+export declare function moveCursorUp(state: SelectionState): SelectionState;
+export declare function moveCursorDown(state: SelectionState): SelectionState;
+export declare function toggleSelection(state: SelectionState): SelectionState;
+export declare function submitSelection(state: SelectionState): SelectionState;
+export declare function cancelSelection(state: SelectionState): SelectionState;
+export declare function getItemsToInstall(state: SelectionState, force?: boolean): readonly CatalogEntry[];
+export declare function runInteractive(repositoryPath: string, options?: InteractiveOptions): Promise<number>;

package/dist/tui.js

@@ -0,0 +1,271 @@
+import * as readline from "node:readline";
+import { formatCatalog, listCatalog } from "./catalog-listing.js";
+import { installCatalog, installTemplate, isTemplateName, removeRouteFiles } from "./catalog-installation.js";
+import { inspectRepository } from "./repository-inspection.js";
+import { routeNames } from "./workflow-catalog.js";
+const ANSI = {
+    clear: "\x1b[2J",
+    home: "\x1b[H",
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    cyan: "\x1b[36m",
+    green: "\x1b[32m",
+    grey: "\x1b[90m",
+    white: "\x1b[37m",
+    hideCursor: "\x1b[?25l",
+    showCursor: "\x1b[?25h",
+};
+export function createSelectionState(entries) {
+    const selected = new Set(entries.filter((entry) => entry.installed).map((entry) => entry.name));
+    return {
+        allItems: entries,
+        visibleItems: entries,
+        selected,
+        cursor: 0,
+        filter: "",
+        status: "selecting",
+    };
+}
+export function fuzzyMatch(text, query) {
+    if (query === "")
+        return true;
+    const haystack = text.toLowerCase();
+    const needle = query.toLowerCase();
+    let needleIndex = 0;
+    for (let i = 0; i < haystack.length && needleIndex < needle.length; i++) {
+        if (haystack[i] === needle[needleIndex])
+            needleIndex++;
+    }
+    return needleIndex === needle.length;
+}
+export function filterItems(items, filter) {
+    if (filter === "")
+        return items;
+    return items.filter((entry) => fuzzyMatch(`${entry.name} ${entry.description}`, filter));
+}
+export function applyFilter(state, filter) {
+    const visibleItems = filterItems(state.allItems, filter);
+    const cursor = visibleItems.length === 0 ? 0 : Math.min(state.cursor, visibleItems.length - 1);
+    return { ...state, visibleItems, filter, cursor };
+}
+export function clearFilter(state) {
+    return applyFilter(state, "");
+}
+export function moveCursorUp(state) {
+    if (state.visibleItems.length === 0)
+        return state;
+    const cursor = state.cursor === 0 ? state.visibleItems.length - 1 : state.cursor - 1;
+    return { ...state, cursor };
+}
+export function moveCursorDown(state) {
+    if (state.visibleItems.length === 0)
+        return state;
+    const cursor = state.cursor === state.visibleItems.length - 1 ? 0 : state.cursor + 1;
+    return { ...state, cursor };
+}
+export function toggleSelection(state) {
+    if (state.visibleItems.length === 0)
+        return state;
+    const entry = state.visibleItems[state.cursor];
+    if (entry === undefined)
+        return state;
+    const selected = new Set(state.selected);
+    if (selected.has(entry.name)) {
+        selected.delete(entry.name);
+    }
+    else {
+        selected.add(entry.name);
+    }
+    return { ...state, selected };
+}
+export function submitSelection(state) {
+    return { ...state, status: "submitting" };
+}
+export function cancelSelection(state) {
+    return { ...state, status: "cancelled" };
+}
+export function getItemsToInstall(state, force = false) {
+    return state.allItems.filter((entry) => state.selected.has(entry.name) && (force || !entry.installed));
+}
+function renderEntry(entry, highlighted, checked) {
+    const indicator = highlighted ? `${ANSI.bold}${ANSI.white}>${ANSI.reset}` : " ";
+    if (checked) {
+        const checkbox = `${ANSI.green}[x]${ANSI.reset}`;
+        const name = highlighted ? `${ANSI.white}${ANSI.bold}${entry.name}${ANSI.reset}` : entry.name;
+        const desc = `${ANSI.dim} — ${entry.description}${ANSI.reset}`;
+        return `${indicator} ${checkbox} ${name}${desc}`;
+    }
+    const checkbox = `${ANSI.grey}[ ]${ANSI.reset}`;
+    const name = highlighted ? `${ANSI.white}${ANSI.bold}${entry.name}${ANSI.reset}` : entry.name;
+    const desc = `${ANSI.dim} — ${entry.description}${ANSI.reset}`;
+    return `${indicator} ${checkbox} ${name}${desc}`;
+}
+function render(state) {
+    const lines = [];
+    lines.push(`${ANSI.cyan}${ANSI.bold}Plain Concepts Platform — Agentic Workflows${ANSI.reset}`);
+    lines.push(`${ANSI.dim}Select items to install. Already-installed items are pre-checked.${ANSI.reset}`);
+    lines.push("");
+    if (state.filter) {
+        lines.push(`${ANSI.cyan}Filter:${ANSI.reset} ${state.filter}${ANSI.grey}█${ANSI.reset}`);
+    }
+    else {
+        lines.push(`${ANSI.dim}Type to filter, arrows to navigate, space to toggle, Enter to install${ANSI.reset}`);
+    }
+    lines.push("");
+    const routes = state.visibleItems.filter((entry) => entry.kind === "route");
+    const templates = state.visibleItems.filter((entry) => entry.kind === "template");
+    let index = 0;
+    if (routes.length > 0) {
+        lines.push(`${ANSI.cyan}Workflows${ANSI.reset}`);
+        for (const entry of routes) {
+            lines.push(renderEntry(entry, index === state.cursor, state.selected.has(entry.name)));
+            index++;
+        }
+        if (templates.length > 0)
+            lines.push("");
+    }
+    if (templates.length > 0) {
+        lines.push(`${ANSI.cyan}Templates${ANSI.reset}`);
+        for (const entry of templates) {
+            lines.push(renderEntry(entry, index === state.cursor, state.selected.has(entry.name)));
+            index++;
+        }
+    }
+    if (state.visibleItems.length === 0) {
+        lines.push(`${ANSI.grey}  No items match the filter.${ANSI.reset}`);
+    }
+    lines.push("");
+    lines.push(`${ANSI.grey}↑↓ navigate  space toggle  type to filter  Enter install  Esc clear filter  q quit${ANSI.reset}`);
+    process.stdout.write(`${ANSI.clear}${ANSI.home}${lines.join("\n")}\n`);
+}
+export async function runInteractive(repositoryPath, options = {}) {
+    const force = options.force ?? false;
+    if (process.stdin.isTTY !== true) {
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        console.log(formatCatalog(entries));
+        console.log("");
+        console.log("Run with a TTY for an interactive selection screen, or use: workflows add [--template <name>] [--force]");
+        return 0;
+    }
+    const entries = await listCatalog({ installedPath: repositoryPath });
+    let state = createSelectionState(entries);
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdout.write(ANSI.hideCursor);
+    render(state);
+    return new Promise((resolve) => {
+        const onKeypress = (str, key) => {
+            if (key?.ctrl && key?.name === "c") {
+                cleanup();
+                resolve(0);
+                return;
+            }
+            if (str === "q" && state.filter === "" && !key?.ctrl && !key?.meta && !key?.shift) {
+                cleanup();
+                resolve(0);
+                return;
+            }
+            if (key?.name === "escape") {
+                state = clearFilter(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "up") {
+                state = moveCursorUp(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "down") {
+                state = moveCursorDown(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "space" || str === " ") {
+                state = toggleSelection(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "return" || key?.name === "enter") {
+                cleanup();
+                void installSelected(state, repositoryPath, force).then((exitCode) => resolve(exitCode));
+                return;
+            }
+            if (key?.name === "backspace") {
+                state = applyFilter(state, state.filter.slice(0, -1));
+                render(state);
+                return;
+            }
+            if (str !== undefined &&
+                str.length === 1 &&
+                str >= " " &&
+                str <= "~" &&
+                !key?.ctrl &&
+                !key?.meta) {
+                state = applyFilter(state, state.filter + str);
+                render(state);
+            }
+        };
+        function cleanup() {
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stdout.write(`${ANSI.showCursor}${ANSI.reset}`);
+            process.stdin.removeListener("keypress", onKeypress);
+        }
+        process.stdin.on("keypress", onKeypress);
+    });
+}
+async function installSelected(state, repositoryPath, force) {
+    const items = getItemsToInstall(state, force);
+    const templates = items.filter((entry) => entry.kind === "template");
+    const routeEntries = state.allItems.filter((entry) => entry.kind === "route");
+    const checkedRoutes = routeEntries
+        .filter((entry) => state.selected.has(entry.name))
+        .map((entry) => entry.name)
+        .filter((name) => routeNames.includes(name));
+    const installedRouteNames = routeEntries
+        .filter((entry) => entry.installed)
+        .map((entry) => entry.name)
+        .filter((name) => routeNames.includes(name));
+    const removedRoutes = installedRouteNames.filter((name) => !checkedRoutes.includes(name));
+    const allConflicts = [];
+    const allInstalled = [];
+    const inspection = await inspectRepository(repositoryPath);
+    // Desired state: the checked routes are the target set. Installing it also refreshes every
+    // package-managed file that is already there, so Enter on an unchanged selection is an update.
+    const result = await installCatalog(repositoryPath, { force, selectedRoutes: checkedRoutes, inspection });
+    allInstalled.push(...result.installed);
+    const allRemoved = await removeRouteFiles(repositoryPath, removedRoutes);
+    for (const template of templates) {
+        if (!isTemplateName(template.name))
+            continue;
+        const templateResult = await installTemplate(repositoryPath, template.name, { force, inspection });
+        allConflicts.push(...templateResult.conflicts);
+        allInstalled.push(...templateResult.installed);
+    }
+    if (allConflicts.length > 0 && !force) {
+        console.error(`Template conflicts found. Re-run with --force to overwrite:\n${allConflicts.join("\n")}`);
+        return 1;
+    }
+    const changed = result.changes.filter((change) => change.status === "added" || change.status === "updated" || change.status === "removed");
+    const skipped = result.changes.filter((change) => change.status === "skipped");
+    console.log(`Package ${result.packageVersion}${result.installedVersions.length > 0 ? ` (was ${result.installedVersions.join(", ")})` : ""}`);
+    if (changed.length === 0 && allRemoved.length === 0 && templates.length === 0) {
+        console.log("Everything is up to date.");
+    }
+    for (const change of changed) {
+        const kept = change.keptEnv?.length ? ` (kept env: ${change.keptEnv.join(", ")})` : "";
+        console.log(`  ${change.status.padEnd(8)} ${change.target}${kept}`);
+    }
+    for (const change of skipped) {
+        console.log(`  skipped  ${change.target} (${change.reason ?? "consumer-owned"})`);
+    }
+    for (const file of allRemoved) {
+        console.log(`  removed  ${file}`);
+    }
+    for (const template of templates) {
+        console.log(`  template ${template.name}`);
+    }
+    return 0;
+}

package/dist/worker-env.d.ts

@@ -0,0 +1,46 @@
+export interface EnvEntry {
+    readonly key: string;
+    /** Comment and blank lines that precede the key. They belong to the key they describe. */
+    readonly leading: readonly string[];
+    /** The `  KEY: value` line, followed by any continuation lines of a multi-line value. */
+    readonly lines: readonly string[];
+}
+export interface WorkerEnv {
+    readonly present: boolean;
+    readonly before: readonly string[];
+    readonly entries: readonly EnvEntry[];
+    readonly trailing: readonly string[];
+    readonly after: readonly string[];
+}
+export interface WorkerMergeReport {
+    /** Consumer values kept because they differ from the package (and from the baseline, when known). */
+    readonly keptEnv: readonly string[];
+    /** Package defaults applied because the consumer still had the previous default. */
+    readonly updatedDefaults: readonly string[];
+    /** Keys only the consumer defines, kept at the end of the block. */
+    readonly consumerOnlyEnv: readonly string[];
+    /** Keys the package removed that the consumer still carried at the old default. */
+    readonly droppedEnv: readonly string[];
+}
+/** The `env:` block of a worker, which lives inside the markdown frontmatter. */
+export declare function parseWorkerEnv(content: string): WorkerEnv;
+/** The top-level `env:` block of a plain YAML workflow, such as the router. */
+export declare function parseYamlEnv(content: string): WorkerEnv;
+export declare function serializeWorkerEnv(env: WorkerEnv): string;
+export declare function entryValue(entry: EnvEntry): string;
+export declare function mergeWorkerEnv(packageContent: string, consumerContent: string, baselineContent?: string, parse?: (content: string) => WorkerEnv): {
+    content: string;
+    report: WorkerMergeReport;
+};
+/** Copy the router's own `env:` values into the two literal lines that cannot read them. */
+export declare function mirrorRouterLiterals(router: string): string;
+/** The package's router with the consumer's `env:` values put back and mirrored into place. */
+export declare function mergeRouter(packageContent: string, consumerContent: string, baselineContent?: string): {
+    content: string;
+    report: WorkerMergeReport;
+};
+/** The package's worker with the consumer's customisable values put back. */
+export declare function mergeWorker(packageContent: string, consumerContent: string, baselineContent?: string): {
+    content: string;
+    report: WorkerMergeReport;
+};

package/dist/worker-env.js

@@ -0,0 +1,179 @@
+// The `env:` block at the top of a worker is the only part of it a consumer may customise.
+// Everything else in the file is the package's, so an update takes the package's file and
+// puts the consumer's env values back. This module does that merge.
+//
+// With a baseline (the package version the consumer installed from) the merge is three-way:
+// a value the consumer never touched follows the package when the default changes, and a
+// value the consumer changed is kept. Without one it is two-way: every consumer value is kept.
+const ENTRY = /^  ([A-Za-z_][A-Za-z0-9_.-]*):(.*)$/;
+/** The `env:` block of a worker, which lives inside the markdown frontmatter. */
+export function parseWorkerEnv(content) {
+    const lines = content.split("\n");
+    if (lines[0] !== "---")
+        return absent(lines);
+    const end = lines.findIndex((line, index) => index > 0 && line === "---");
+    if (end === -1)
+        return absent(lines);
+    return parseEnvBlock(lines, lines.findIndex((line, index) => index > 0 && index < end && line === "env:"));
+}
+/** The top-level `env:` block of a plain YAML workflow, such as the router. */
+export function parseYamlEnv(content) {
+    const lines = content.split("\n");
+    return parseEnvBlock(lines, lines.indexOf("env:"));
+}
+function absent(lines) {
+    return { present: false, before: lines, entries: [], trailing: [], after: [] };
+}
+function parseEnvBlock(lines, envIndex) {
+    if (envIndex === -1)
+        return absent(lines);
+    // The block runs to the first line that is neither blank nor indented into it. That is the
+    // closing `---` of a frontmatter and the next top-level key of a plain YAML file alike.
+    let cursor = envIndex + 1;
+    while (cursor < lines.length && (lines[cursor] === "" || lines[cursor].startsWith("  ")))
+        cursor += 1;
+    const entries = [];
+    let leading = [];
+    let current;
+    for (const line of lines.slice(envIndex + 1, cursor)) {
+        const match = ENTRY.exec(line);
+        if (match !== null) {
+            if (current)
+                entries.push(current);
+            current = { key: match[1], leading, lines: [line] };
+            leading = [];
+        }
+        else if (current && leading.length === 0 && /^   +\S/.test(line)) {
+            current.lines.push(line);
+        }
+        else {
+            leading.push(line);
+        }
+    }
+    if (current)
+        entries.push(current);
+    return {
+        present: true,
+        before: lines.slice(0, envIndex + 1),
+        entries,
+        trailing: leading,
+        after: lines.slice(cursor),
+    };
+}
+export function serializeWorkerEnv(env) {
+    if (!env.present)
+        return env.before.join("\n");
+    return [
+        ...env.before,
+        ...env.entries.flatMap((entry) => [...entry.leading, ...entry.lines]),
+        ...env.trailing,
+        ...env.after,
+    ].join("\n");
+}
+export function entryValue(entry) {
+    const first = entry.lines[0].replace(ENTRY, "$2").trim();
+    return [first, ...entry.lines.slice(1).map((line) => line.trim())].join("\n").trim();
+}
+export function mergeWorkerEnv(packageContent, consumerContent, baselineContent, parse = parseWorkerEnv) {
+    const report = { keptEnv: [], updatedDefaults: [], consumerOnlyEnv: [], droppedEnv: [] };
+    const pkg = parse(packageContent);
+    const consumer = parse(consumerContent);
+    if (!pkg.present || !consumer.present)
+        return { content: packageContent, report };
+    const baseline = baselineContent === undefined ? undefined : parse(baselineContent);
+    const consumerByKey = new Map(consumer.entries.map((entry) => [entry.key, entry]));
+    const baselineByKey = new Map((baseline?.entries ?? []).map((entry) => [entry.key, entry]));
+    const packageKeys = new Set(pkg.entries.map((entry) => entry.key));
+    const merged = [];
+    for (const entry of pkg.entries) {
+        const mine = consumerByKey.get(entry.key);
+        if (mine === undefined || entryValue(mine) === entryValue(entry)) {
+            merged.push(entry);
+            continue;
+        }
+        const base = baselineByKey.get(entry.key);
+        if (base !== undefined && entryValue(base) === entryValue(mine)) {
+            // Still the previous default: the package changed it, the consumer never did.
+            merged.push(entry);
+            report.updatedDefaults.push(entry.key);
+            continue;
+        }
+        merged.push({ key: entry.key, leading: entry.leading, lines: mine.lines });
+        report.keptEnv.push(entry.key);
+    }
+    for (const entry of consumer.entries) {
+        if (packageKeys.has(entry.key))
+            continue;
+        const base = baselineByKey.get(entry.key);
+        if (base !== undefined && entryValue(base) === entryValue(entry)) {
+            report.droppedEnv.push(entry.key);
+            continue;
+        }
+        merged.push(entry);
+        report.consumerOnlyEnv.push(entry.key);
+    }
+    return { content: serializeWorkerEnv({ ...pkg, entries: merged }), report };
+}
+// Two more per-repository values live outside `env:` because GitHub gives them no other home:
+// `runs-on` cannot read the env context, and the engine's gateway URL is read by the engine
+// before the workflow's env exists.
+function engineEndpoint(content) {
+    return /^    OPENAI_BASE_URL: (.+)$/m.exec(content)?.[1];
+}
+// Which self-hosted pool a worker's agent jobs run on. gh-aw cannot share runs-on through an
+// import, so every worker names it. ubuntu-latest is excluded, being GitHub's own runner, used
+// by the deterministic jobs everywhere and chosen by nobody.
+function runnerPools(content) {
+    const found = new Set();
+    for (const match of content.matchAll(/^\s*runs-on(?:-slim)?: (\S+)\s*$/gm)) {
+        if (match[1] !== "ubuntu-latest")
+            found.add(match[1]);
+    }
+    return [...found];
+}
+function preserveRunnerPool(packageContent, consumerContent) {
+    const mine = runnerPools(consumerContent);
+    const theirs = runnerPools(packageContent);
+    // Only an unambiguous swap. A consumer naming several pools has drifted rather than
+    // decided, and guessing which it meant is worse than leaving the package's.
+    if (mine.length !== 1 || theirs.length !== 1 || mine[0] === theirs[0])
+        return packageContent;
+    return packageContent.replace(/^(\s*runs-on(?:-slim)?: )(\S+)(\s*)$/gm, (line, prefix, pool, tail) => pool === "ubuntu-latest" ? line : `${prefix}${mine[0]}${tail}`);
+}
+// GitHub evaluates no expression in a `workflow_run.workflows:` list or in a `cron:`, so the two
+// router values that are also needed there cannot be read from `env:` at those two lines. The
+// installer copies them in instead, which is what keeps the pair in step across an update; the
+// route matrix asserts the copies still agree.
+const CI_NAME_TRIGGER = /^(\s*workflows: \[")[^"]*("\]\s*)$/m;
+const AUDIT_CRON_LINE = /^(\s*- cron: ")[^"]*(" # audit slot.*)$/m;
+/** Copy the router's own `env:` values into the two literal lines that cannot read them. */
+export function mirrorRouterLiterals(router) {
+    const values = new Map(parseYamlEnv(router).entries.map((entry) => [entry.key, unquote(entryValue(entry))]));
+    const ciName = values.get("CI_WORKFLOW_NAME");
+    const auditCron = values.get("AUDIT_CRON");
+    let result = router;
+    if (ciName !== undefined)
+        result = result.replace(CI_NAME_TRIGGER, `$1${ciName}$2`);
+    if (auditCron !== undefined)
+        result = result.replace(AUDIT_CRON_LINE, `$1${auditCron}$2`);
+    return result;
+}
+function unquote(value) {
+    const match = /^(["'])([\s\S]*)\1$/.exec(value);
+    return match === null ? value : match[2];
+}
+/** The package's router with the consumer's `env:` values put back and mirrored into place. */
+export function mergeRouter(packageContent, consumerContent, baselineContent) {
+    const { content, report } = mergeWorkerEnv(packageContent, consumerContent, baselineContent, parseYamlEnv);
+    return { content: mirrorRouterLiterals(content), report };
+}
+/** The package's worker with the consumer's customisable values put back. */
+export function mergeWorker(packageContent, consumerContent, baselineContent) {
+    const { content: envMerged, report } = mergeWorkerEnv(packageContent, consumerContent, baselineContent);
+    let result = envMerged;
+    const endpoint = engineEndpoint(consumerContent);
+    if (endpoint !== undefined) {
+        result = result.replace(/^    OPENAI_BASE_URL: .+$/m, `    OPENAI_BASE_URL: ${endpoint}`);
+    }
+    return { content: preserveRunnerPool(result, consumerContent), report };
+}

package/dist/workflow-catalog.d.ts

@@ -0,0 +1,27 @@
+export declare const routeNames: readonly ["refine", "implement", "triage", "apply-review", "merge-gate", "audit", "release"];
+export type RouteName = (typeof routeNames)[number];
+export interface WorkflowRoute {
+    readonly name: RouteName;
+    readonly worker: string;
+    readonly description: string;
+    readonly defaultEnabled: boolean;
+}
+export declare const workflowRoutes: readonly WorkflowRoute[];
+export declare const packageOwnedTargets: readonly [".github/actions", ".github/workflows/agent-*.md", ".github/workflows/shared/platform-defaults.md", ".github/workflows/shared/opencode-ci.md", ".github/workflows/work-router.yml", "scripts/compile-agent-workflows.mjs", "opencode.ci.json"];
+export interface MandatoryFile {
+    readonly source: string;
+    readonly target: string;
+}
+export declare const mandatoryFiles: readonly MandatoryFile[];
+export declare const generatedConsumerTargets: readonly [".github/workflows/agent-*.lock.yml", ".github/aw/actions-lock.json"];
+export declare const templateNames: readonly ["agentics-checks", "agentics-error-report", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "bug-report", "feature-request", "github-release", "opencode.ci.json"];
+export type TemplateName = (typeof templateNames)[number];
+export interface CatalogTemplate {
+    readonly name: TemplateName;
+    readonly file: string;
+    readonly description: string;
+    readonly target?: string;
+    /** Subdirectory of `templates/` holding the file. Defaults to "agentics". */
+    readonly directory?: string;
+}
+export declare const catalogTemplates: readonly CatalogTemplate[];