@plainconceptsplatform/workflows 0.6.1 → 0.16.0

package/dist/tui.js

@@ -1,6 +1,6 @@
 import * as readline from "node:readline";
 import { formatCatalog, listCatalog } from "./catalog-listing.js";
-import { installCatalog, installMandatoryFiles, installTemplate, isTemplateName, removeRouteFiles } from "./catalog-installation.js";
+import { installCatalog, installTemplate, isTemplateName, removeRouteFiles } from "./catalog-installation.js";
 import { inspectRepository } from "./repository-inspection.js";
 import { routeNames } from "./workflow-catalog.js";
 const ANSI = {
@@ -218,7 +218,6 @@ export async function runInteractive(repositoryPath, options = {}) {
 }
 async function installSelected(state, repositoryPath, force) {
     const items = getItemsToInstall(state, force);
-    const newRoutes = items.filter((entry) => entry.kind === "route");
     const templates = items.filter((entry) => entry.kind === "template");
     const routeEntries = state.allItems.filter((entry) => entry.kind === "route");
     const checkedRoutes = routeEntries
@@ -232,56 +231,41 @@ async function installSelected(state, repositoryPath, force) {
     const removedRoutes = installedRouteNames.filter((name) => !checkedRoutes.includes(name));
     const allConflicts = [];
     const allInstalled = [];
-    const allRemoved = [];
     const inspection = await inspectRepository(repositoryPath);
-    if (checkedRoutes.length > 0 && (newRoutes.length > 0 || removedRoutes.length > 0 || force)) {
-        const result = await installCatalog(repositoryPath, { force, selectedRoutes: checkedRoutes, inspection });
-        allConflicts.push(...result.conflicts);
-        allInstalled.push(...result.installed);
-        if (result.conflicts.length === 0 || force) {
-            allRemoved.push(...await removeRouteFiles(repositoryPath, removedRoutes));
-        }
-    }
-    else if (checkedRoutes.length === 0 && removedRoutes.length > 0) {
-        const result = await installCatalog(repositoryPath, { force, selectedRoutes: [], inspection });
-        allConflicts.push(...result.conflicts);
-        allInstalled.push(...result.installed);
-        if (result.conflicts.length === 0 || force) {
-            allRemoved.push(...await removeRouteFiles(repositoryPath, removedRoutes));
-        }
-    }
-    else {
-        const result = await installMandatoryFiles(repositoryPath, { force });
-        allConflicts.push(...result.conflicts);
-        allInstalled.push(...result.installed);
-    }
+    // 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 result = await installTemplate(repositoryPath, template.name, { force, inspection });
-        allConflicts.push(...result.conflicts);
-        allInstalled.push(...result.installed);
+        const templateResult = await installTemplate(repositoryPath, template.name, { force, inspection });
+        allConflicts.push(...templateResult.conflicts);
+        allInstalled.push(...templateResult.installed);
     }
     if (allConflicts.length > 0 && !force) {
-        console.error(`Conflicts found. Re-run with --force to overwrite:\n${allConflicts.join("\n")}`);
+        console.error(`Template conflicts found. Re-run with --force to overwrite:\n${allConflicts.join("\n")}`);
         return 1;
     }
-    if (allInstalled.length > 0 || allRemoved.length > 0) {
-        if (allInstalled.length > 0) {
-            console.log(`Installed ${allInstalled.length} item(s):`);
-            for (const file of allInstalled) {
-                console.log(`  ${file}`);
-            }
-        }
-        if (allRemoved.length > 0) {
-            console.log(`Removed ${allRemoved.length} item(s):`);
-            for (const file of allRemoved) {
-                console.log(`  ${file}`);
-            }
-        }
+    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.");
     }
-    else {
-        console.log("All selected items are already installed.");
+    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

@@ -1,4 +1,4 @@
-export declare const routeNames: readonly ["refine", "implement", "triage", "apply-review", "merge-gate", "audit"];
+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;
@@ -14,12 +14,14 @@ export interface MandatoryFile {
 }
 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-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "bug-report", "feature-request", "github-release", "opencode.ci.json", "visual-evidence"];
+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[];

package/dist/workflow-catalog.js

@@ -5,14 +5,16 @@ export const routeNames = [
     "apply-review",
     "merge-gate",
     "audit",
+    "release",
 ];
 export const workflowRoutes = [
     { name: "refine", worker: "agent-refine.md", description: "Refines an issue into a user story, on a first pass or after the author has answered the bot's questions.", defaultEnabled: true },
     { name: "implement", worker: "agent-implement.md", description: "Implements an issue and opens a pull request. Stops there: the merge decision belongs to the merge gate.", defaultEnabled: true },
-    { name: "triage", worker: "agent-triage.md", description: "Triages issues opened by outside collaborators: runs 10 checks (template, security, size, danger, duplicates, clarity, reproducibility, acceptance, cross-cutting). Loops up to 3 rounds. Passes to refine or blocks.", defaultEnabled: true },
+    { name: "triage", worker: "agent-triage.md", description: "Triages issues opened from outside the organisation: runs 10 checks (template, security, size, danger, duplicates, clarity, reproducibility, acceptance, cross-cutting, product scope). Loops up to 3 rounds. Passes to refine, asks the author for more, parks out-of-scope work open for a maintainer, or closes what is genuinely rejected.", defaultEnabled: true },
     { name: "apply-review", worker: "agent-apply-review.md", description: "Applies reviewer feedback to an open pull request the bot authored, then pushes the fixes to the same branch.", defaultEnabled: true },
     { name: "merge-gate", worker: "agent-merge-gate.md", description: "Decides what happens to a bot-authored pull request once CI has reported: merge, hand to a human, or fix CI.", defaultEnabled: true },
     { name: "audit", worker: "agent-audit.md", description: "Read-only repository audit. Finds 5-7 problems, scores each 1-10, and files a single issue that Refine then sizes and splits.", defaultEnabled: true },
+    { name: "release", worker: "agent-release.md", description: "Writes release notes from the commit log, then a deterministic job bumps the version, tags, and publishes a GitHub Release. Manual dispatch only (operation=release).", defaultEnabled: true },
 ];
 export const packageOwnedTargets = [
     ".github/actions",
@@ -33,6 +35,7 @@ export const generatedConsumerTargets = [
 ];
 export const templateNames = [
     "agentics-checks",
+    "agentics-error-report",
     "agentics-maintenance",
     "app-ci-dotnet-next",
     "app-ci-node-monorepo",
@@ -40,10 +43,10 @@ export const templateNames = [
     "feature-request",
     "github-release",
     "opencode.ci.json",
-    "visual-evidence",
 ];
 export const catalogTemplates = [
     { name: "agentics-checks", file: "agentics-checks.yml", description: "Agentics checks: verifies generated agent lockfiles, actionlint, and compile on PRs touching workflow files." },
+    { name: "agentics-error-report", file: "agentics-error-report.yml", description: "Daily error report: classifies the last day of failures in the workflows this package ships and files them upstream so the package gets fixed. Deterministic, no model; sends only package-owned names, conclusions and counts, and refuses to file anything a leak scanner flags." },
     { name: "agentics-maintenance", file: "agentics-maintenance.yml", description: "Agentic maintenance: scheduled daily maintenance workflow for keeping workflows and actions up to date." },
     { name: "app-ci-dotnet-next", file: "app-ci-dotnet-next.yml", description: "App CI pipeline for a .NET + Next.js monorepo: build, test, and lint on PRs and schedule." },
     { name: "app-ci-node-monorepo", file: "app-ci-node-monorepo.yml", description: "App CI pipeline for a Node monorepo: build, test, and lint on PRs and schedule." },
@@ -51,5 +54,4 @@ export const catalogTemplates = [
     { name: "feature-request", file: "feature_request.yml", description: "Feature request issue template scoped to small, well-scoped improvements (Small/Medium only; large work belongs in a planning issue).", target: ".github/ISSUE_TEMPLATE/feature_request.yml" },
     { name: "github-release", file: "github-release.yml", description: "Publishes or updates a GitHub Release with generated notes whenever a v* tag is pushed." },
     { name: "opencode.ci.json", file: "opencode.ci.json", description: "Standalone OpenCode CI config: plainconcepts provider, GLM model registration, ci-workflow-agent, and LSP defaults for consumer repositories." },
-    { name: "visual-evidence", file: "visual-evidence.yml", description: "Visual evidence: captures screenshots of UI changes on bot-authored PRs by reading the capturePlan left by the agent in evidence.json and executing it on a runner with Docker and Chrome access." },
 ];

package/loops/actions/add-issue-labels/action.yml

@@ -23,6 +23,26 @@ runs:
         github-token: ${{ inputs.token }}
         script: |
           const labels = process.env.LABELS.split(/\r?\n|,/).map((label) => label.trim()).filter(Boolean);
+          if (labels.length === 0) {
+            core.notice('No labels to add.');
+            return;
+          }
+
+          // Create what does not exist yet, so shipping a new label in the package does not
+          // require a person to go and make it in every repository first. Its sibling
+          // remove-issue-labels has swallowed 404 for a long time; this one had no guard at all,
+          // so a label the package introduced would fail the step in every consumer until
+          // somebody created it by hand. 422 is "already exists", which is the happy path on
+          // every run after the first.
+          for (const name of labels) {
+            try {
+              await github.rest.issues.createLabel({ ...context.repo, name, color: 'ededed' });
+              core.notice(`Created the ${name} label.`);
+            } catch (error) {
+              if (error.status !== 422) throw error;
+            }
+          }
+
           await github.rest.issues.addLabels({
             ...context.repo,
             issue_number: Number(process.env.ISSUE_NUMBER),