@plainconceptsplatform/workflows 0.1.2 → 0.2.0

package/README.md

@@ -1,30 +1,59 @@
-# Platform workflows
+# Workflows CLI
 
 Install and update shared GitHub Agentic Workflows for Plain Concepts Platform repositories.
 
+## Quick start
+
+The primary entrypoint is the interactive TUI. Run it with no arguments:
+
+```bash
+npx @plainconceptsplatform/workflows
+```
+
+The TUI lists all routes and templates with install status. Arrow keys navigate, space toggles, Enter installs. Selecting any route installs the full managed catalog plus mandatory `opencode.ci.json` and `scripts/compile-agent-workflows.mjs`. Selecting only templates still installs those mandatory files.
+
 ## Install
 
 Before installing workflows, install and configure [`PlainConceptsPlatform/opencode-onboard`](https://github.com/PlainConceptsPlatform/opencode-onboard) in the consumer repository. Loop workers invoke the skills and commands it provides. Verify the required skills and commands are available before compiling workflows.
 
-For one-off use, prefer:
+For non-interactive use (advanced):
 
 ```bash
-npx @plainconceptsplatform/workflows@latest platform-workflows init
-npx @plainconceptsplatform/workflows@latest platform-workflows add
-npx @plainconceptsplatform/workflows@latest platform-workflows update
+npx @plainconceptsplatform/workflows@latest init
+npx @plainconceptsplatform/workflows@latest add
+npx @plainconceptsplatform/workflows@latest update
 ```
 
 For a project-local development dependency:
 
 ```bash
 pnpm add -D @plainconceptsplatform/workflows
-pnpm exec platform-workflows init
-pnpm exec platform-workflows add
+pnpm exec workflows              # launch interactive TUI
+pnpm exec workflows init
+pnpm exec workflows add
 ```
 
-`init` detects the repository stack and visibility, creates `.github/workflows/shared/repo-config.md` when absent, and records managed workflow state. Complete the consumer configuration before compiling workflows.
+`init` inspects the repository and reports its stack and visibility. It does not create or manage repository configuration or a manifest.
+
+`add` installs package-owned files including the mandatory `opencode.ci.json` and `scripts/compile-agent-workflows.mjs`. It stops when a managed file differs. Use `pnpm exec workflows update --force` only when you intend to replace managed workflow files.
+
+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.
+
+## List and search
 
-`add` installs missing package-owned files. It stops when a managed file differs. Use `pnpm exec platform-workflows update --force` only when you intend to replace managed workflow files. It never overwrites `repo-config.md`.
+List all available workflows, routes, and templates with install status:
+
+```bash
+npx --yes --package @plainconceptsplatform/workflows@latest workflows list
+```
+
+Each entry is marked `[x]` when the corresponding `.github/workflows/agent-*.md` file already exists in the current directory, or `[ ]` when it is not yet installed.
+
+Search by name or description:
+
+```bash
+npx --yes --package @plainconceptsplatform/workflows@latest workflows search "ci"
+```
 
 ## Manual installation
 
@@ -32,10 +61,10 @@ The package includes `loops/`, a copyable equivalent of `.github/`:
 
 - `loops/actions/` maps to `.github/actions/`
 - `loops/workflows/` maps to `.github/workflows/`
-- `loops/aw/repo-config.md` maps to `.github/workflows/shared/repo-config.md`
 - `loops/scripts/` maps to `scripts/`
 
-Copy these files manually if you do not use the CLI. Keep `repo-config.md` consumer-owned.
+Copy these files manually if you do not use the CLI. Each worker is self-contained. Edit its
+top-level `env:` defaults directly for consumer-specific endpoint, model, labels, paths, and checks.
 
 ## Compile
 

package/dist/catalog-installation.d.ts

@@ -1,4 +1,4 @@
-import { repositoryConfigRelativePath } from "./repository-state.js";
+import { type TemplateName } from "./workflow-catalog.js";
 export interface CatalogInstallResult {
     readonly installed: readonly string[];
     readonly conflicts: readonly string[];
@@ -7,6 +7,15 @@ export interface CatalogInstallOptions {
     readonly force?: boolean;
     readonly sourcePath?: string;
 }
+interface CatalogFile {
+    readonly source: string;
+    readonly target: string;
+    readonly managed: boolean;
+}
+export declare function mandatoryFileSpecs(sourcePath: string): CatalogFile[];
 export declare function catalogSourcePath(modulePath?: string): string;
 export declare function installCatalog(repositoryPath: string, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
-export { repositoryConfigRelativePath };
+export declare function installTemplate(repositoryPath: string, template: TemplateName, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
+export declare function installMandatoryFiles(repositoryPath: string, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
+export declare function isTemplateName(value: string): value is TemplateName;
+export {};

package/dist/catalog-installation.js

@@ -2,34 +2,83 @@ import { access, copyFile, mkdir, readFile, readdir } from "node:fs/promises";
 import { constants } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { repositoryConfigRelativePath } from "./repository-state.js";
+import { catalogTemplates, mandatoryFiles, templateNames } from "./workflow-catalog.js";
 const sourceMappings = [
     ["actions", ".github/actions"],
     ["workflows", ".github/workflows"],
     ["scripts", "scripts"],
 ];
+export function mandatoryFileSpecs(sourcePath) {
+    return mandatoryFiles.map((spec) => ({
+        source: join(sourcePath, spec.source),
+        target: spec.target,
+        managed: true,
+    }));
+}
 export function catalogSourcePath(modulePath = fileURLToPath(import.meta.url)) {
     return resolve(dirname(modulePath), "..", "loops");
 }
 export async function installCatalog(repositoryPath, options = {}) {
     const sourcePath = options.sourcePath ?? catalogSourcePath();
-    const files = await catalogFiles(sourcePath);
-    const managedFiles = files.filter((file) => file.managed);
+    const files = [...await catalogFiles(sourcePath), ...mandatoryFileSpecs(sourcePath)];
+    const deduplicated = files.filter((file, index) => files.findIndex((f) => f.target === file.target) === index).sort((left, right) => left.target.localeCompare(right.target));
+    const managedFiles = deduplicated.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 };
-    await Promise.all(files.map(async (file) => {
+    await Promise.all(deduplicated.map(async (file) => {
         const destination = join(repositoryPath, file.target);
         if (!file.managed && await exists(destination))
             return;
         await mkdir(dirname(destination), { recursive: true });
         await copyFile(file.source, destination);
     }));
+    return { installed: deduplicated.map((file) => file.target), conflicts };
+}
+export async function installTemplate(repositoryPath, template, options = {}) {
+    const sourcePath = options.sourcePath ?? catalogSourcePath();
+    const meta = catalogTemplateMeta(template);
+    const source = join(sourcePath, "templates", meta.directory, meta.file);
+    const target = meta.target;
+    const destination = join(repositoryPath, target);
+    const conflicts = await exists(destination) && !(await filesMatch(source, destination)) ? [target] : [];
+    if (conflicts.length > 0 && !options.force)
+        return { installed: [], conflicts };
+    await mkdir(dirname(destination), { recursive: true });
+    await copyFile(source, destination);
+    return { installed: [target], conflicts };
+}
+export async function installMandatoryFiles(repositoryPath, options = {}) {
+    const sourcePath = options.sourcePath ?? catalogSourcePath();
+    const files = mandatoryFileSpecs(sourcePath).sort((left, right) => left.target.localeCompare(right.target));
+    const conflicts = (await Promise.all(files.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 };
+    await Promise.all(files.map(async (file) => {
+        const destination = join(repositoryPath, file.target);
+        await mkdir(dirname(destination), { recursive: true });
+        await copyFile(file.source, destination);
+    }));
     return { installed: files.map((file) => file.target), conflicts };
 }
+export function isTemplateName(value) {
+    return templateNames.includes(value);
+}
+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 isWorkflow = entry.file.endsWith(".yml");
+    const target = isWorkflow ? `.github/workflows/${entry.file}` : entry.file;
+    return { directory, file: entry.file, target };
+}
 async function catalogFiles(sourcePath) {
     const files = [];
     for (const [sourceDirectory, targetDirectory] of sourceMappings) {
@@ -43,10 +92,6 @@ async function catalogFiles(sourcePath) {
             });
         }
     }
-    const repositoryConfigSource = join(sourcePath, "aw", "repo-config.md");
-    if (await exists(repositoryConfigSource)) {
-        files.push({ source: repositoryConfigSource, target: repositoryConfigRelativePath, managed: false });
-    }
     return files.sort((left, right) => left.target.localeCompare(right.target));
 }
 function isGeneratedFile(file) {
@@ -77,4 +122,3 @@ async function exists(path) {
         return false;
     }
 }
-export { repositoryConfigRelativePath };

package/dist/catalog-installation.test.js

@@ -2,7 +2,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { catalogSourcePath, installCatalog, repositoryConfigRelativePath } from "./catalog-installation.js";
+import { catalogSourcePath, installCatalog, installMandatoryFiles, installTemplate } from "./catalog-installation.js";
 const temporaryDirectories = [];
 afterEach(async () => {
     await Promise.all(temporaryDirectories.splice(0).map((directory) => rm(directory, { force: true, recursive: true })));
@@ -15,13 +15,14 @@ describe("catalog installation", () => {
         });
         expect(catalogSourcePath(join(packageDirectory, "dist", "catalog-installation.js"))).toBe(join(packageDirectory, "loops"));
     });
-    it("installs package-owned loops files and initializes repository config", async () => {
+    it("installs package-owned loops files including mandatory opencode.ci.json and compile script", async () => {
         const sourcePath = await createDirectory({
             "actions/check/action.yml": "name: Check\n",
             "workflows/agent-check.md": "# Check\n",
             "workflows/shared/defaults.md": "defaults\n",
-            "scripts/compile.mjs": "console.log('compile');\n",
-            "aw/repo-config.md": "# Repository configuration\n",
+            "scripts/compile-agent-workflows.mjs": "console.log('compile');\n",
+            "scripts/compile.mjs": "console.log('old compile');\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
             "workflows/agent-check.lock.yml": "generated\n",
             "actions/actions-lock.json": "generated\n",
         });
@@ -31,56 +32,234 @@ describe("catalog installation", () => {
                 ".github/actions/check/action.yml",
                 ".github/workflows/agent-check.md",
                 ".github/workflows/shared/defaults.md",
-                repositoryConfigRelativePath,
+                "opencode.ci.json",
+                "scripts/compile-agent-workflows.mjs",
                 "scripts/compile.mjs",
             ],
             conflicts: [],
         });
-        await expect(readFile(join(repositoryPath, repositoryConfigRelativePath), "utf8")).resolves.toBe("# Repository configuration\n");
+    });
+    it("copies ownership headers for base workflows and selected templates", async () => {
+        const header = "# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-check.md. Update with `workflows update --force`; consumer edits may be overwritten.\n";
+        const templateHeader = "# Managed by @plainconceptsplatform/workflows. Source: loops/templates/agentics/agentics-checks.yml. Update with `workflows update --force`; consumer edits may be overwritten.\n";
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "# Managed by @plainconceptsplatform/workflows. Source: loops/actions/check/action.yml. Update with `workflows update --force`; consumer edits may be overwritten.\nname: Check\n",
+            "workflows/agent-check.md": `---\n${header}# Check\n`,
+            "scripts/compile-agent-workflows.mjs": "// Managed by @plainconceptsplatform/workflows. Source: loops/scripts/compile-agent-workflows.mjs. Update with `workflows update --force`; consumer edits may be overwritten.\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+            "templates/agentics/agentics-checks.yml": `${templateHeader}name: Agentics checks\n`,
+        });
+        const repositoryPath = await createDirectory({});
+        await installCatalog(repositoryPath, { sourcePath });
+        await installTemplate(repositoryPath, "agentics-checks", { sourcePath });
+        await expect(readFile(join(repositoryPath, ".github/workflows/agent-check.md"), "utf8")).resolves.toMatch(new RegExp(`^---\\n${escapeRegularExpression(header)}`));
+        await expect(readFile(join(repositoryPath, ".github/workflows/agentics-checks.yml"), "utf8")).resolves.toMatch(new RegExp(`^${escapeRegularExpression(templateHeader)}`));
     });
     it("does not report identical managed files as conflicts", async () => {
         const sourcePath = await createDirectory({
             "actions/check/action.yml": "name: Check\n",
             "workflows/agent-check.md": "# Check\n",
-            "scripts/compile.mjs": "compile\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
         });
         const repositoryPath = await createDirectory({ ".github/workflows/agent-check.md": "# Check\n" });
         await expect(installCatalog(repositoryPath, { sourcePath })).resolves.toMatchObject({ conflicts: [] });
     });
-    it("requires force for different managed files and preserves repository config", async () => {
+    it("does not manage legacy repository configuration files", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "name: Check\n",
+            "workflows/agent-check.md": "# Check\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({
+            ".github/workflows/shared/repo-config.md": "legacy consumer config\n",
+        });
+        await expect(installCatalog(repositoryPath, { sourcePath })).resolves.toMatchObject({
+            installed: [
+                ".github/actions/check/action.yml",
+                ".github/workflows/agent-check.md",
+                "opencode.ci.json",
+                "scripts/compile-agent-workflows.mjs",
+            ],
+            conflicts: [],
+        });
+        await expect(readFile(join(repositoryPath, ".github/workflows/shared/repo-config.md"), "utf8")).resolves.toBe("legacy consumer config\n");
+    });
+    it("requires force for different managed files", async () => {
         const sourcePath = await createDirectory({
             "actions/check/action.yml": "package action\n",
             "workflows/agent-check.md": "package workflow\n",
-            "scripts/compile.mjs": "package script\n",
-            "aw/repo-config.md": "package config\n",
+            "scripts/compile-agent-workflows.mjs": "package script\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
         });
         const repositoryPath = await createDirectory({
             ".github/actions/check/action.yml": "consumer action\n",
             ".github/workflows/agent-check.md": "consumer workflow\n",
-            "scripts/compile.mjs": "consumer script\n",
-            [repositoryConfigRelativePath]: "consumer config\n",
+            "scripts/compile-agent-workflows.mjs": "consumer script\n",
+            "opencode.ci.json": "{ \"model\": \"consumer-model\" }\n",
         });
         await expect(installCatalog(repositoryPath, { sourcePath })).resolves.toEqual({
             installed: [],
             conflicts: [
                 ".github/actions/check/action.yml",
                 ".github/workflows/agent-check.md",
-                "scripts/compile.mjs",
+                "opencode.ci.json",
+                "scripts/compile-agent-workflows.mjs",
             ],
         });
         await expect(installCatalog(repositoryPath, { force: true, sourcePath })).resolves.toMatchObject({
             conflicts: [
                 ".github/actions/check/action.yml",
                 ".github/workflows/agent-check.md",
-                "scripts/compile.mjs",
+                "opencode.ci.json",
+                "scripts/compile-agent-workflows.mjs",
             ],
         });
         await expect(readFile(join(repositoryPath, ".github/actions/check/action.yml"), "utf8")).resolves.toBe("package action\n");
-        await expect(readFile(join(repositoryPath, repositoryConfigRelativePath), "utf8")).resolves.toBe("consumer config\n");
+    });
+    it("installs templates only when explicitly selected", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "name: Check\n",
+            "workflows/agent-check.md": "# Check\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "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",
+        });
+        const repositoryPath = await createDirectory({});
+        await installCatalog(repositoryPath, { sourcePath });
+        await expect(readFile(join(repositoryPath, ".github/workflows/agentics-checks.yml"), "utf8")).rejects.toThrow();
+        await expect(installTemplate(repositoryPath, "agentics-checks", { sourcePath })).resolves.toEqual({
+            installed: [".github/workflows/agentics-checks.yml"],
+            conflicts: [],
+        });
+        await expect(installTemplate(repositoryPath, "app-ci-node-monorepo", { sourcePath })).resolves.toEqual({
+            installed: [".github/workflows/app-ci-node-monorepo.yml"],
+            conflicts: [],
+        });
+    });
+    it("installCatalog installs mandatory opencode.ci.json and compile script alongside catalog files", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "name: Check\n",
+            "workflows/agent-check.md": "# Check\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        const result = await installCatalog(repositoryPath, { sourcePath });
+        expect(result.installed).toContain("opencode.ci.json");
+        expect(result.installed).toContain("scripts/compile-agent-workflows.mjs");
+        await expect(readFile(join(repositoryPath, "opencode.ci.json"), "utf8")).resolves.toBe("{ \"model\": \"plainconcepts/glm-5-2\" }\n");
+        await expect(readFile(join(repositoryPath, "scripts/compile-agent-workflows.mjs"), "utf8")).resolves.toBe("compile\n");
+    });
+    it("installMandatoryFiles installs opencode.ci.json and compile script without catalog files", async () => {
+        const sourcePath = await createDirectory({
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        const result = await installMandatoryFiles(repositoryPath, { sourcePath });
+        expect(result.installed).toEqual(["opencode.ci.json", "scripts/compile-agent-workflows.mjs"]);
+        await expect(readFile(join(repositoryPath, "opencode.ci.json"), "utf8")).resolves.toBe("{ \"model\": \"plainconcepts/glm-5-2\" }\n");
+        await expect(readFile(join(repositoryPath, "scripts/compile-agent-workflows.mjs"), "utf8")).resolves.toBe("compile\n");
+    });
+    it("installMandatoryFiles reports conflicts on differing files", async () => {
+        const sourcePath = await createDirectory({
+            "scripts/compile-agent-workflows.mjs": "package script\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({
+            "opencode.ci.json": "{ \"model\": \"consumer\" }\n",
+            "scripts/compile-agent-workflows.mjs": "consumer script\n",
+        });
+        await expect(installMandatoryFiles(repositoryPath, { sourcePath })).resolves.toEqual({
+            installed: [],
+            conflicts: ["opencode.ci.json", "scripts/compile-agent-workflows.mjs"],
+        });
+    });
+    it("installMandatoryFiles overwrites with force", async () => {
+        const sourcePath = await createDirectory({
+            "scripts/compile-agent-workflows.mjs": "package script\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({
+            "opencode.ci.json": "{ \"model\": \"consumer\" }\n",
+            "scripts/compile-agent-workflows.mjs": "consumer script\n",
+        });
+        await expect(installMandatoryFiles(repositoryPath, { force: true, sourcePath })).resolves.toMatchObject({
+            installed: ["opencode.ci.json", "scripts/compile-agent-workflows.mjs"],
+        });
+        await expect(readFile(join(repositoryPath, "opencode.ci.json"), "utf8")).resolves.toBe("{ \"model\": \"plainconcepts/glm-5-2\" }\n");
+    });
+    it("installMandatoryFiles does not install catalog workflow files", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "name: Check\n",
+            "workflows/agent-check.md": "# Check\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        await installMandatoryFiles(repositoryPath, { sourcePath });
+        await expect(readFile(join(repositoryPath, ".github/workflows/agent-check.md"), "utf8")).rejects.toThrow();
+    });
+    it("installCatalog deduplicates compile script in both scripts/ and mandatory files", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "name: Check\n",
+            "workflows/agent-check.md": "# Check\n",
+            "scripts/compile-agent-workflows.mjs": "same compile script\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        const result = await installCatalog(repositoryPath, { sourcePath });
+        const compileEntries = result.installed.filter((path) => path === "scripts/compile-agent-workflows.mjs");
+        expect(compileEntries).toHaveLength(1);
+    });
+    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",
+        });
+        const repositoryPath = await createDirectory({});
+        await expect(installTemplate(repositoryPath, "opencode.ci.json", { sourcePath })).resolves.toEqual({
+            installed: ["opencode.ci.json"],
+            conflicts: [],
+        });
+        await expect(readFile(join(repositoryPath, "opencode.ci.json"), "utf8")).resolves.toBe("{ \"model\": \"plainconcepts/glm-5-2\" }\n");
+    });
+    it("requires force to replace the opencode.ci.json template", async () => {
+        const sourcePath = await createDirectory({
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({
+            "opencode.ci.json": "{ \"model\": \"consumer-model\" }\n",
+        });
+        await expect(installTemplate(repositoryPath, "opencode.ci.json", { sourcePath })).resolves.toEqual({
+            installed: [],
+            conflicts: ["opencode.ci.json"],
+        });
+        await expect(installTemplate(repositoryPath, "opencode.ci.json", { force: true, sourcePath })).resolves.toMatchObject({
+            installed: ["opencode.ci.json"],
+        });
+        await expect(readFile(join(repositoryPath, "opencode.ci.json"), "utf8")).resolves.toBe("{ \"model\": \"plainconcepts/glm-5-2\" }\n");
+    });
+    it("requires force to replace a selected template", async () => {
+        const sourcePath = await createDirectory({
+            "templates/agentics/agentics-checks.yml": "package template\n",
+        });
+        const repositoryPath = await createDirectory({
+            ".github/workflows/agentics-checks.yml": "consumer template\n",
+        });
+        await expect(installTemplate(repositoryPath, "agentics-checks", { sourcePath })).resolves.toEqual({
+            installed: [],
+            conflicts: [".github/workflows/agentics-checks.yml"],
+        });
+        await expect(installTemplate(repositoryPath, "agentics-checks", { force: true, sourcePath })).resolves.toMatchObject({
+            installed: [".github/workflows/agentics-checks.yml"],
+        });
     });
 });
 async function createDirectory(files) {
-    const directory = await mkdtemp(join(tmpdir(), "platform-workflows-"));
+    const directory = await mkdtemp(join(tmpdir(), "workflows-"));
     temporaryDirectories.push(directory);
     await Promise.all(Object.entries(files).map(async ([relativePath, content]) => {
         const path = join(directory, relativePath);
@@ -90,3 +269,6 @@ async function createDirectory(files) {
     }));
     return directory;
 }
+function escapeRegularExpression(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/catalog-listing.d.ts

@@ -0,0 +1,13 @@
+export interface CatalogEntry {
+    readonly kind: "route" | "template";
+    readonly name: string;
+    readonly description: string;
+    readonly file: string;
+    readonly installed: boolean;
+}
+export interface ListOptions {
+    readonly installedPath?: string;
+}
+export declare function listCatalog(options?: ListOptions): Promise<readonly CatalogEntry[]>;
+export declare function searchCatalog(entries: readonly CatalogEntry[], query: string): readonly CatalogEntry[];
+export declare function formatCatalog(entries: readonly CatalogEntry[]): string;

package/dist/catalog-listing.js

@@ -0,0 +1,68 @@
+import { access, constants } from "node:fs/promises";
+import { join } from "node:path";
+import { catalogTemplates, workflowRoutes } from "./workflow-catalog.js";
+export async function listCatalog(options = {}) {
+    const basePath = options.installedPath ?? process.cwd();
+    const routes = await Promise.all(workflowRoutes.map(async (route) => ({
+        kind: "route",
+        name: route.name,
+        description: route.description,
+        file: route.worker,
+        installed: await isFileInstalled(basePath, route.worker),
+    })));
+    const templates = await Promise.all(catalogTemplates.map(async (template) => ({
+        kind: "template",
+        name: template.name,
+        description: template.description,
+        file: template.file,
+        installed: await isFileInstalled(basePath, template.file),
+    })));
+    return [...routes, ...templates];
+}
+export function searchCatalog(entries, query) {
+    const normalized = query.toLowerCase().trim();
+    if (normalized === "")
+        return [];
+    return entries.filter((entry) => entry.name.toLowerCase().includes(normalized) ||
+        entry.description.toLowerCase().includes(normalized));
+}
+export function formatCatalog(entries) {
+    if (entries.length === 0)
+        return "No workflows matched the search query.";
+    const routes = entries.filter((entry) => entry.kind === "route");
+    const templates = entries.filter((entry) => entry.kind === "template");
+    const lines = [];
+    if (routes.length > 0) {
+        lines.push("Workflows:");
+        for (const entry of routes) {
+            lines.push(formatEntry(entry));
+        }
+    }
+    if (templates.length > 0) {
+        if (lines.length > 0)
+            lines.push("");
+        lines.push("Templates:");
+        for (const entry of templates) {
+            lines.push(formatEntry(entry));
+        }
+    }
+    return lines.join("\n");
+}
+function formatEntry(entry) {
+    const mark = entry.installed ? "[x]" : "[ ]";
+    return `  ${mark} ${entry.name} — ${entry.description}`;
+}
+async function isFileInstalled(basePath, workerOrTemplateFile) {
+    const installedPath = templateInstallPath(basePath, workerOrTemplateFile);
+    try {
+        await access(installedPath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function templateInstallPath(basePath, file) {
+    const isRootTemplate = file.endsWith(".json");
+    return isRootTemplate ? join(basePath, file) : join(basePath, ".github", "workflows", file);
+}

package/dist/catalog-listing.test.d.ts

@@ -0,0 +1 @@
+export {};