@plainconceptsplatform/workflows 0.4.0 → 0.4.1

package/README.md

@@ -48,7 +48,7 @@ Route names: refine, implement, direct, apply-review, merge-gate, audit, propose
 
 Use `workflows update --force` to force-overwrite managed files that differ from the package source.
 
-Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-maintenance`, `app-ci-dotnet-next`, and `app-ci-node-monorepo`. CI templates are stack-specific copies, not a combined template. Edit their top-level `env:` values for repository paths, package names, and commands.
+Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, and `github-release`. CI templates are stack-specific copies, not a combined template. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
 
 ## List and search
 

package/dist/catalog-installation.d.ts

@@ -9,6 +9,7 @@ export interface CatalogInstallOptions {
     readonly sourcePath?: string;
     readonly selectedRoutes?: readonly RouteName[];
     readonly inspection?: RepositoryInspection;
+    readonly compile?: (repositoryPath: string) => Promise<void>;
 }
 interface CatalogFile {
     readonly source: string;

package/dist/catalog-installation.js

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { access, copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { access, copyFile, cp, mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -33,13 +33,6 @@ export async function installCatalog(repositoryPath, options = {}) {
         const fileName = file.target.split("/").pop() ?? "";
         return !excluded.has(fileName);
     });
-    const managedFiles = filtered.filter((file) => file.managed);
-    const conflicts = (await Promise.all(managedFiles.map(async (file) => {
-        const destination = join(repositoryPath, file.target);
-        return await exists(destination) && !(await filesMatch(file.source, destination)) ? file.target : undefined;
-    }))).filter((file) => file !== undefined);
-    if (conflicts.length > 0 && !options.force)
-        return { installed: [], conflicts };
     const fileContents = new Map();
     for (const file of filtered) {
         fileContents.set(file.target, await readFile(file.source, "utf8"));
@@ -50,21 +43,14 @@ export async function installCatalog(repositoryPath, options = {}) {
         processedContents = injectStackIntoWorkers(processedContents, defaults);
         processedContents = transformOpencodeFiles(processedContents, options.inspection);
     }
-    await Promise.all([...processedContents.entries()].map(async ([target, content]) => {
-        const destination = join(repositoryPath, target);
-        const originalFile = filtered.find((f) => f.target === target);
-        if (originalFile !== undefined && !originalFile.managed && await exists(destination))
-            return;
-        await mkdir(dirname(destination), { recursive: true });
-        await writeFile(destination, content, "utf8");
-    }));
-    await ensurePreCommitHook(repositoryPath);
-    try {
-        await runCompileIfAvailable(repositoryPath);
-    }
-    catch {
-        // compile failure is non-fatal
-    }
+    const updates = [...processedContents.entries()]
+        .filter(([target]) => filtered.find((file) => file.target === target)?.managed ?? true)
+        .map(([target, content]) => ({ target, content }));
+    const conflicts = await conflictingTargets(repositoryPath, updates);
+    if (conflicts.length > 0 && !options.force)
+        return { installed: [], conflicts };
+    const stagedLocks = await validateStagedCatalog(repositoryPath, updates, options.compile);
+    await applyTransaction(repositoryPath, [...updates, ...stagedLocks, await preCommitHookUpdate(repositoryPath)]);
     return { installed: [...processedContents.keys()].sort(), conflicts };
 }
 function injectStackIntoWorkers(files, defaults) {
@@ -121,31 +107,30 @@ export async function installMandatoryFiles(repositoryPath, options = {}) {
     }))).filter((file) => file !== undefined);
     if (conflicts.length > 0 && !options.force)
         return { installed: [], conflicts };
-    await Promise.all(files.map(async (file) => {
-        const destination = join(repositoryPath, file.target);
-        await mkdir(dirname(destination), { recursive: true });
-        await copyFile(file.source, destination);
-    }));
+    const updates = await Promise.all(files.map(async (file) => ({ target: file.target, content: await readFile(file.source, "utf8") })));
+    await applyTransaction(repositoryPath, [...updates, await preCommitHookUpdate(repositoryPath)]);
     return { installed: files.map((file) => file.target), conflicts };
 }
 export function isTemplateName(value) {
     return templateNames.includes(value);
 }
 export async function ensurePreCommitHook(repositoryPath) {
-    const hookPath = join(repositoryPath, ".husky", "pre-commit");
+    const update = await preCommitHookUpdate(repositoryPath);
+    await applyTransaction(repositoryPath, [update]);
+}
+async function preCommitHookUpdate(repositoryPath) {
+    const target = ".husky/pre-commit";
+    const hookPath = join(repositoryPath, target);
     const compileLine = "node scripts/compile-agent-workflows.mjs";
     if (!await exists(hookPath)) {
-        await mkdir(dirname(hookPath), { recursive: true });
-        await writeFile(hookPath, `${compileLine}\n`, "utf8");
-        return;
+        return { target, content: `${compileLine}\n` };
     }
     const content = await readFile(hookPath, "utf8");
     if (content.includes("compile-agent-workflows"))
-        return;
-    const newContent = content.endsWith("\n") || content === ""
-        ? `${content}${compileLine}\n`
-        : `${content}\n${compileLine}\n`;
-    await writeFile(hookPath, newContent, "utf8");
+        return { target, content };
+    return { target, content: content.endsWith("\n") || content === ""
+            ? `${content}${compileLine}\n`
+            : `${content}\n${compileLine}\n` };
 }
 export async function runCompileIfAvailable(repositoryPath) {
     const script = join(repositoryPath, "scripts", "compile-agent-workflows.mjs");
@@ -153,11 +138,93 @@ export async function runCompileIfAvailable(repositoryPath) {
         await execFileAsync("node", [script, "--force"], { cwd: repositoryPath });
     }
 }
+async function conflictingTargets(repositoryPath, updates) {
+    const conflicts = (await Promise.all(updates.map(async ({ target, content }) => {
+        const destination = join(repositoryPath, target);
+        if (!await exists(destination))
+            return undefined;
+        return (await readFile(destination, "utf8")) === content ? undefined : target;
+    }))).filter((target) => target !== undefined);
+    return [...new Set(conflicts)].sort();
+}
+async function validateStagedCatalog(repositoryPath, updates, compileOverride) {
+    const temporaryRoot = join(repositoryPath, ".opencode", ".tmp");
+    await mkdir(temporaryRoot, { recursive: true });
+    const stagingPath = await mkdtemp(join(temporaryRoot, "workflows-"));
+    try {
+        await copyCompilationInputs(repositoryPath, stagingPath);
+        await writeUpdates(stagingPath, updates);
+        const compiler = compileOverride ?? await packageCompiler(stagingPath);
+        if (compiler === undefined)
+            return [];
+        await compiler(stagingPath);
+        return await generatedFiles(stagingPath);
+    }
+    finally {
+        await rm(stagingPath, { force: true, recursive: true });
+    }
+}
+async function copyCompilationInputs(repositoryPath, stagingPath) {
+    const githubPath = join(repositoryPath, ".github");
+    if (await exists(githubPath))
+        await cp(githubPath, join(stagingPath, ".github"), { recursive: true });
+}
+async function packageCompiler(repositoryPath) {
+    const scriptPath = join(repositoryPath, "scripts", "compile-agent-workflows.mjs");
+    if (!await exists(scriptPath))
+        return undefined;
+    const content = await readFile(scriptPath, "utf8");
+    return content.includes("gh aw compile") ? runCompileIfAvailable : undefined;
+}
+async function generatedFiles(repositoryPath) {
+    const workflowPath = join(repositoryPath, ".github", "workflows");
+    const updates = [];
+    if (await exists(workflowPath)) {
+        for (const file of await filesIn(workflowPath)) {
+            if (!file.endsWith(".lock.yml"))
+                continue;
+            updates.push({ target: `.github/workflows/${file.replaceAll("\\", "/")}`, content: await readFile(join(workflowPath, file), "utf8") });
+        }
+    }
+    const actionsLock = join(repositoryPath, ".github", "actions", "actions-lock.json");
+    if (await exists(actionsLock)) {
+        updates.push({ target: ".github/actions/actions-lock.json", content: await readFile(actionsLock, "utf8") });
+    }
+    return updates.sort((left, right) => left.target.localeCompare(right.target));
+}
+async function applyTransaction(repositoryPath, updates) {
+    const uniqueUpdates = [...new Map(updates.map((update) => [update.target, update])).values()];
+    const rollback = await Promise.all(uniqueUpdates.map(async ({ target }) => {
+        const path = join(repositoryPath, target);
+        return { target, existed: await exists(path), content: await exists(path) ? await readFile(path, "utf8") : undefined };
+    }));
+    try {
+        await writeUpdates(repositoryPath, uniqueUpdates);
+    }
+    catch (error) {
+        await Promise.all(rollback.map(async ({ target, existed, content }) => {
+            if (existed && content !== undefined) {
+                await writeUpdates(repositoryPath, [{ target, content }]);
+            }
+            else {
+                await rm(join(repositoryPath, target), { force: true });
+            }
+        }));
+        throw error;
+    }
+}
+async function writeUpdates(repositoryPath, updates) {
+    await Promise.all(updates.map(async ({ target, content }) => {
+        const destination = join(repositoryPath, target);
+        await mkdir(dirname(destination), { recursive: true });
+        await writeFile(destination, content, "utf8");
+    }));
+}
 function catalogTemplateMeta(template) {
     const entry = catalogTemplates.find((item) => item.name === template);
     if (entry === undefined)
         throw new Error(`Unknown template: ${template}`);
-    const directory = template.startsWith("opencode") ? "opencode" : template.startsWith("app-ci-") ? "ci" : "agentics";
+    const directory = template.startsWith("opencode") ? "opencode" : template.startsWith("app-ci-") ? "ci" : template === "github-release" ? "release" : "agentics";
     const isWorkflow = entry.file.endsWith(".yml");
     const target = template === "app-ci-dotnet-next"
         ? ".github/workflows/app-ci.yml"

package/dist/catalog-installation.test.js

@@ -154,6 +154,7 @@ describe("catalog installation", () => {
             "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
             "templates/agentics/agentics-checks.yml": "name: Agentics checks\n",
             "templates/ci/app-ci-node-monorepo.yml": "name: Node CI\n",
+            "templates/release/github-release.yml": "name: Publish GitHub release\n",
         });
         const repositoryPath = await createDirectory({});
         await installCatalog(repositoryPath, { sourcePath });
@@ -166,6 +167,10 @@ describe("catalog installation", () => {
             installed: [".github/workflows/app-ci-node-monorepo.yml"],
             conflicts: [],
         });
+        await expect(installTemplate(repositoryPath, "github-release", { sourcePath })).resolves.toEqual({
+            installed: [".github/workflows/github-release.yml"],
+            conflicts: [],
+        });
     });
     it("installCatalog installs mandatory opencode.ci.json and compile script alongside catalog files", async () => {
         const sourcePath = await createDirectory({
@@ -256,6 +261,47 @@ describe("catalog installation", () => {
         await expect(readFile(join(repositoryPath, ".husky", "pre-commit"), "utf8"))
             .resolves.toBe("pnpm lint\nnode scripts/compile-agent-workflows.mjs\n");
     });
+    it("leaves consumer files untouched when staged workflow compilation fails", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "package action\n",
+            "workflows/agent-check.md": "package workflow\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"package\" }\n",
+        });
+        const repositoryPath = await createDirectory({
+            ".github/actions/check/action.yml": "consumer action\n",
+            ".github/workflows/agent-check.md": "consumer workflow\n",
+            "opencode.ci.json": "{ \"model\": \"consumer\" }\n",
+            "scripts/compile-agent-workflows.mjs": "consumer compiler\n",
+        });
+        await expect(installCatalog(repositoryPath, {
+            force: true,
+            sourcePath,
+            compile: async () => { throw new Error("compile failed"); },
+        })).rejects.toThrow("compile failed");
+        await expect(readFile(join(repositoryPath, ".github/workflows/agent-check.md"), "utf8"))
+            .resolves.toBe("consumer workflow\n");
+        await expect(readFile(join(repositoryPath, "scripts/compile-agent-workflows.mjs"), "utf8"))
+            .resolves.toBe("consumer compiler\n");
+        await expect(readFile(join(repositoryPath, ".husky", "pre-commit"), "utf8")).rejects.toThrow();
+    });
+    it("applies staged generated locks with managed sources", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "package action\n",
+            "workflows/agent-check.md": "package workflow\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"package\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        await installCatalog(repositoryPath, {
+            sourcePath,
+            compile: async (stagingPath) => {
+                await writeFile(join(stagingPath, ".github", "workflows", "agent-check.lock.yml"), "opencode run --log-level ERROR\n", "utf8");
+            },
+        });
+        await expect(readFile(join(repositoryPath, ".github", "workflows", "agent-check.lock.yml"), "utf8"))
+            .resolves.toBe("opencode run --log-level ERROR\n");
+    });
     it("installs the opencode.ci.json template to the repository root", async () => {
         const sourcePath = await createDirectory({
             "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",

package/dist/catalog-listing.test.js

@@ -16,7 +16,7 @@ describe("catalog listing", () => {
         const routeNames = entries.filter((entry) => entry.kind === "route").map((entry) => entry.name);
         const templateNames = entries.filter((entry) => entry.kind === "template").map((entry) => entry.name);
         expect(routeNames).toEqual(["refine", "implement", "direct", "apply-review", "merge-gate", "audit", "propose"]);
-        expect(templateNames).toEqual(["agentics-checks", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "opencode.ci.json"]);
+        expect(templateNames).toEqual(["agentics-checks", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "github-release", "opencode.ci.json"]);
     });
     it("reports all entries as not installed in an empty repository", async () => {
         const repositoryPath = await createRepository({});

package/dist/index.test.js

@@ -61,12 +61,13 @@ describe("workflows CLI", () => {
         expect(output).toContain("implement");
         expect(output).toContain("agentics-checks");
         expect(output).toContain("app-ci-dotnet-next");
+        expect(output).toContain("github-release");
         // None installed: all [ ]
         const installedCount = (output.match(/\[x\]/g) ?? []).length;
         expect(installedCount).toBe(0);
-        // 7 routes + 5 templates = 12 entries
+        // 7 routes + 6 templates = 13 entries
         const uninstalledCount = (output.match(/\[ \]/g) ?? []).length;
-        expect(uninstalledCount).toBe(12);
+        expect(uninstalledCount).toBe(13);
         log.mockRestore();
     });
     it("marks installed workflows with [x]", async () => {

package/dist/workflow-catalog.d.ts

@@ -14,7 +14,7 @@ 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", "opencode.ci.json"];
+export declare const templateNames: readonly ["agentics-checks", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "github-release", "opencode.ci.json"];
 export type TemplateName = (typeof templateNames)[number];
 export interface CatalogTemplate {
     readonly name: TemplateName;

package/dist/workflow-catalog.js

@@ -38,6 +38,7 @@ export const templateNames = [
     "agentics-maintenance",
     "app-ci-dotnet-next",
     "app-ci-node-monorepo",
+    "github-release",
     "opencode.ci.json",
 ];
 export const catalogTemplates = [
@@ -45,5 +46,6 @@ export const catalogTemplates = [
     { 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." },
+    { 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." },
 ];

package/dist/workflow-catalog.test.js

@@ -17,7 +17,7 @@ describe("workflow catalog", () => {
         }
     });
     it("lists supported optional templates", () => {
-        expect(templateNames).toEqual(["agentics-checks", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "opencode.ci.json"]);
+        expect(templateNames).toEqual(["agentics-checks", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "github-release", "opencode.ci.json"]);
     });
     it("gives every catalog template a non-empty description and file", () => {
         expect(catalogTemplates.map((template) => template.name)).toEqual([...templateNames]);

package/loops/templates/release/github-release.yml

@@ -0,0 +1,30 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/templates/release/github-release.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: Publish GitHub release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    name: Publish release
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Create or update GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release edit "$TAG" --title "$TAG" --generate-notes
+          else
+            gh release create "$TAG" --title "$TAG" --generate-notes
+          fi

package/loops/workflows/agent-apply-review.md

@@ -2,7 +2,6 @@
 # Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-apply-review.md. Update with `workflows update --force`; consumer edits may be overwritten.
 env:
   REPO_RULES: "Apply only actionable outstanding reviewer feedback to the selected bot pull request. Make minimal changes that address each comment. Preserve architecture and do not weaken tests. Run full verification after changes."
-  OPENAI_BASE_URL: https://forge.plainconcepts.com/v1
   WORKING_LABEL: bot-working
   REVIEW_LABEL: review
   REVIEW_MARKER: "<!-- agent-apply-review -->"

package/loops/workflows/agent-audit.md

@@ -2,7 +2,6 @@
 # Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-audit.md. Update with `workflows update --force`; consumer edits may be overwritten.
 env:
   REPO_RULES: "Read-only repository audit. Report only reproducible, actionable defects with evidence. Look for: architectural layer violations, missing tests, security gaps, performance issues, and documentation drift. Do not modify files, commit, push, or run write operations."
-  OPENAI_BASE_URL: https://forge.plainconcepts.com/v1
   AUDIT_MARKER: "<!-- agent-audit -->"
   GIT_AUTHOR_NAME: "github-actions[bot]"
   GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"

package/loops/workflows/agent-direct.md

@@ -2,7 +2,6 @@
 # Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-direct.md. Update with `workflows update --force`; consumer edits may be overwritten.
 env:
   REPO_RULES: "Execute the selected issue's latest human instruction exactly as asked. Follow repository documentation and existing patterns. Keep scope to the requested outcome."
-  OPENAI_BASE_URL: https://forge.plainconcepts.com/v1
   WORKING_LABEL: bot-working
   REVIEW_LABEL: review
   DIRECT_LABEL: direct

package/loops/workflows/agent-implement.md

@@ -2,7 +2,6 @@
 # Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-implement.md. Update with `workflows update --force`; consumer edits may be overwritten.
 env:
   REPO_RULES: "Implement only the selected issue. Follow repository documentation and existing conventions. Do not weaken tests, lower coverage thresholds, or bypass checks. Run the project's full verification suite before creating a pull request."
-  OPENAI_BASE_URL: https://forge.plainconcepts.com/v1
   IMPLEMENT_LABEL: implement
   WORKING_LABEL: bot-working
   REVIEW_LABEL: review

package/loops/workflows/agent-merge-gate.md

@@ -2,7 +2,6 @@
 # Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-merge-gate.md. Update with `workflows update --force`; consumer edits may be overwritten.
 env:
   REPO_RULES: "Make a risk-based merge decision for the selected bot pull request. Merge only when CI is green and no risk indicators are present. Flag security, schema, auth, or calculation changes for human review. Do not merge protected file changes."
-  OPENAI_BASE_URL: https://forge.plainconcepts.com/v1
   WORKING_LABEL: bot-working
   IMPLEMENT_LABEL: implement
   REVIEW_LABEL: review

package/loops/workflows/agent-propose.md

@@ -2,7 +2,6 @@
 # Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-propose.md. Update with `workflows update --force`; consumer edits may be overwritten.
 env:
   REPO_RULES: "Propose one focused product candidate from repository evidence and curated feature radar. Respect documented product goals and architecture boundaries. Do not propose features that conflict with the project's stated scope."
-  OPENAI_BASE_URL: https://forge.plainconcepts.com/v1
   PROPOSED_LABEL: proposed
   IMPLEMENT_LABEL: implement
   PROPOSE_MARKER: "<!-- agent-propose -->"

package/loops/workflows/agent-refine.md

@@ -2,7 +2,6 @@
 # Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-refine.md. Update with `workflows update --force`; consumer edits may be overwritten.
 env:
   REPO_RULES: "Refine only the selected issue into a grounded, implementation-ready user story. Read repository documentation for domain context. Write acceptance criteria that match existing patterns. Do not implement code."
-  OPENAI_BASE_URL: https://forge.plainconcepts.com/v1
   REFINE_LABEL: refine
   REFINED_LABEL: refined
   WORKING_LABEL: bot-working

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",