@plainconceptsplatform/workflows 0.1.2 → 0.2.0

package/dist/catalog-listing.test.js

@@ -0,0 +1,137 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { formatCatalog, listCatalog, searchCatalog } from "./catalog-listing.js";
+import { workflowRoutes, catalogTemplates } from "./workflow-catalog.js";
+const temporaryDirectories = [];
+afterEach(async () => {
+    await Promise.all(temporaryDirectories.splice(0).map((directory) => rm(directory, { force: true, recursive: true })));
+});
+describe("catalog listing", () => {
+    it("returns all routes and templates", async () => {
+        const repositoryPath = await createRepository({});
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        expect(entries).toHaveLength(workflowRoutes.length + catalogTemplates.length);
+        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"]);
+    });
+    it("reports all entries as not installed in an empty repository", async () => {
+        const repositoryPath = await createRepository({});
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        expect(entries.every((entry) => entry.installed === false)).toBe(true);
+    });
+    it("marks a route as installed when its worker file exists", async () => {
+        const repositoryPath = await createRepository({
+            ".github/workflows/agent-refine.md": "# Refine",
+        });
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        const refineEntry = entries.find((entry) => entry.name === "refine");
+        expect(refineEntry).toBeDefined();
+        expect(refineEntry.installed).toBe(true);
+    });
+    it("marks a template as installed when its template file exists", async () => {
+        const repositoryPath = await createRepository({
+            ".github/workflows/agentics-checks.yml": "name: Agentics checks",
+        });
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        const checksEntry = entries.find((entry) => entry.name === "agentics-checks");
+        expect(checksEntry).toBeDefined();
+        expect(checksEntry.installed).toBe(true);
+    });
+    it("marks the opencode.ci.json template as installed when the file exists at repository root", async () => {
+        const repositoryPath = await createRepository({
+            "opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }",
+        });
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        const opencodeEntry = entries.find((entry) => entry.name === "opencode.ci.json");
+        expect(opencodeEntry).toBeDefined();
+        expect(opencodeEntry.installed).toBe(true);
+    });
+    it("reports mixed installed and uninstalled entries", async () => {
+        const repositoryPath = await createRepository({
+            ".github/workflows/agent-refine.md": "# Refine",
+            ".github/workflows/agent-audit.md": "# Audit",
+            ".github/workflows/app-ci-dotnet-next.yml": "name: CI",
+            "opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }",
+        });
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        expect(entries.filter((entry) => entry.installed).map((entry) => entry.name))
+            .toEqual(expect.arrayContaining(["refine", "audit", "app-ci-dotnet-next", "opencode.ci.json"]));
+        expect(entries.filter((entry) => !entry.installed)).toHaveLength(workflowRoutes.length + catalogTemplates.length - 4);
+    });
+});
+describe("searchCatalog", () => {
+    const sampleEntries = [
+        { kind: "route", name: "refine", description: "Refines an issue into a user story.", file: "agent-refine.md", installed: false },
+        { kind: "route", name: "audit", description: "Read-only repository audit.", file: "agent-audit.md", installed: true },
+        { kind: "template", name: "app-ci-dotnet-next", description: "App CI pipeline for .NET + Next.js.", file: "app-ci-dotnet-next.yml", installed: false },
+    ];
+    it("filters by name match", () => {
+        const results = searchCatalog(sampleEntries, "audit");
+        expect(results).toHaveLength(1);
+        expect(results[0].name).toBe("audit");
+    });
+    it("filters by description match", () => {
+        const results = searchCatalog(sampleEntries, "user story");
+        expect(results).toHaveLength(1);
+        expect(results[0].name).toBe("refine");
+    });
+    it("is case-insensitive", () => {
+        const results = searchCatalog(sampleEntries, "AUDIT");
+        expect(results).toHaveLength(1);
+        expect(results[0].name).toBe("audit");
+    });
+    it("returns empty array for no matches", () => {
+        const results = searchCatalog(sampleEntries, "nonexistent");
+        expect(results).toHaveLength(0);
+    });
+    it("returns empty array for empty query after trim", () => {
+        expect(searchCatalog(sampleEntries, "  ")).toHaveLength(0);
+    });
+    it("returns both routes and templates when the query matches both kinds", () => {
+        const entries = [
+            { kind: "route", name: "direct", description: "Executes a CI instruction.", file: "agent-direct.md", installed: false },
+            { kind: "template", name: "app-ci-dotnet-next", description: "App CI pipeline.", file: "app-ci-dotnet-next.yml", installed: true },
+        ];
+        const results = searchCatalog(entries, "CI");
+        expect(results).toHaveLength(2);
+    });
+});
+describe("formatCatalog", () => {
+    it("groups routes under Workflows and templates under Templates", () => {
+        const entries = [
+            { kind: "route", name: "refine", description: "Refines a story.", file: "agent-refine.md", installed: true },
+            { kind: "template", name: "app-ci-dotnet-next", description: "CI for .NET.", file: "app-ci-dotnet-next.yml", installed: false },
+        ];
+        const output = formatCatalog(entries);
+        expect(output).toContain("Workflows:");
+        expect(output).toContain("Templates:");
+        expect(output).toContain("[x] refine");
+        expect(output).toContain("[ ] app-ci-dotnet-next");
+    });
+    it("prints a no-match message for an empty result", () => {
+        expect(formatCatalog([])).toBe("No workflows matched the search query.");
+    });
+    it("prints only a Workflows section when no templates match", () => {
+        const entries = [
+            { kind: "route", name: "refine", description: "Refines.", file: "agent-refine.md", installed: false },
+        ];
+        const output = formatCatalog(entries);
+        expect(output).toContain("Workflows:");
+        expect(output).not.toContain("Templates:");
+    });
+});
+async function createRepository(files) {
+    const repositoryPath = await mkdtemp(join(tmpdir(), "workflows-"));
+    temporaryDirectories.push(repositoryPath);
+    await Promise.all(Object.entries(files).map(async ([relativePath, content]) => {
+        const path = join(repositoryPath, relativePath);
+        const { mkdir } = await import("node:fs/promises");
+        await mkdir(join(path, ".."), { recursive: true });
+        await writeFile(path, content, "utf8");
+    }));
+    return repositoryPath;
+}

package/dist/index.js

@@ -1,13 +1,62 @@
 #!/usr/bin/env node
 import { inspectRepository, parseVisibility, resolveVisibility } from "./repository-inspection.js";
-import { installCatalog } from "./catalog-installation.js";
-import { initializeRepository, readManifest, repositoryConfigRelativePath } from "./repository-state.js";
+import { installCatalog, installTemplate, isTemplateName } from "./catalog-installation.js";
+import { formatCatalog, listCatalog, searchCatalog } from "./catalog-listing.js";
+import { runInteractive } from "./tui.js";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+const HELP_TEXT = `Workflows CLI — install and manage Plain Concepts Platform agentic workflows.
+
+Run with no arguments to launch the interactive TUI, the primary way to select and install
+workflows and templates:
+
+  npx @plainconceptsplatform/workflows
+
+Advanced (non-interactive) commands:
+
+Usage: workflows <command> [options]
+
+Commands:
+  (default)                                   Launch the interactive TUI for selecting and installing items.
+  init                                        Inspect the repository and report its stack and visibility.
+  add                                         Install package-owned workflow files into .github/.
+  update                                      Alias for add. Use --force to overwrite managed files.
+  status                                      Print repository inspection as JSON.
+  list                                        List all available workflows and templates with install status.
+  search <query>                              Filter workflows and templates by name or description.
+
+Options:
+  --visibility public|private                 Override repository visibility (init only).
+  --template <name>                           Install a standalone template instead of the catalog.
+                                              Templates: agentics-checks, agentics-maintenance,
+                                              app-ci-dotnet-next, app-ci-node-monorepo,
+                                              opencode.ci.json.
+  --force                                     Overwrite managed files that differ from the package source.
+  -h, --help                                  Show this help text.
+
+Installed workflows are marked [x] when the corresponding .github/workflows/agent-*.md
+file exists relative to the current directory.`;
 export async function run(arguments_, repositoryPath = process.cwd()) {
     const [command, ...options] = arguments_;
-    if (command === "--help" || command === "-h" || command === undefined) {
-        console.log("Usage: platform-workflows <init|add|update|status> [--visibility public|private] [--force]");
+    if (command === "--help" || command === "-h") {
+        console.log(HELP_TEXT);
+        return 0;
+    }
+    if (command === undefined) {
+        const force = options.includes("--force");
+        return runInteractive(repositoryPath, { force });
+    }
+    if (command === "list") {
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        console.log(formatCatalog(entries));
+        return 0;
+    }
+    if (command === "search") {
+        if (options.length === 0 || options.length > 1)
+            return fail("search requires exactly one query argument.");
+        const allEntries = await listCatalog({ installedPath: repositoryPath });
+        const results = searchCatalog(allEntries, options[0]);
+        console.log(formatCatalog(results));
         return 0;
     }
     if (command === "init") {
@@ -16,21 +65,23 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
             return fail("--visibility must be public or private.");
         const inspection = await inspectRepository(repositoryPath);
         const resolvedVisibility = await resolveVisibility(repositoryPath, visibility);
-        const result = await initializeRepository(inspection, resolvedVisibility);
-        console.log(JSON.stringify({ command, ...result }, null, 2));
+        console.log(JSON.stringify({ command, inspection, visibility: resolvedVisibility }, null, 2));
         return 0;
     }
     if (command === "status") {
         const inspection = await inspectRepository(repositoryPath);
-        const manifest = await readManifest(repositoryPath);
-        console.log(JSON.stringify({ command, inspection, manifest, repositoryConfigPath: repositoryConfigRelativePath }, null, 2));
+        console.log(JSON.stringify({ command, inspection }, null, 2));
         return 0;
     }
     if (command === "add" || command === "update") {
-        if (options.some((option) => option !== "--force"))
-            return fail(`${command} accepts only --force.`);
-        const result = await installCatalog(repositoryPath, { force: options.includes("--force") });
-        if (result.conflicts.length > 0 && !options.includes("--force")) {
+        const template = readTemplateOption(options);
+        if (template === "invalid")
+            return fail(`${command} accepts only --force or --template agentics-checks|agentics-maintenance|app-ci-dotnet-next|app-ci-node-monorepo|opencode.ci.json.`);
+        const force = options.includes("--force");
+        const result = template === undefined
+            ? await installCatalog(repositoryPath, { force })
+            : await installTemplate(repositoryPath, template, { force });
+        if (result.conflicts.length > 0 && !force) {
             console.error(`Catalog conflicts found. Re-run with --force to overwrite package-managed files:\n${result.conflicts.join("\n")}`);
             return 1;
         }
@@ -46,6 +97,19 @@ function readVisibilityOption(options) {
         return "invalid";
     return parseVisibility(options[1]) ?? "invalid";
 }
+function readTemplateOption(options) {
+    const templateIndex = options.indexOf("--template");
+    if (templateIndex === -1)
+        return options.every((option) => option === "--force") ? undefined : "invalid";
+    if (templateIndex + 1 >= options.length || options.filter((option) => option === "--template").length !== 1)
+        return "invalid";
+    if (options.some((option, index) => option !== "--force" && index !== templateIndex && index !== templateIndex + 1))
+        return "invalid";
+    return templateNameFromOptions(options[templateIndex + 1]);
+}
+function templateNameFromOptions(value) {
+    return value !== undefined && isTemplateName(value) ? value : "invalid";
+}
 function fail(message) {
     console.error(message);
     return 1;

package/dist/index.test.d.ts

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

package/dist/index.test.js

@@ -0,0 +1,112 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { run } from "./index.js";
+const temporaryDirectories = [];
+afterEach(async () => {
+    await Promise.all(temporaryDirectories.splice(0).map((directory) => rm(directory, { force: true, recursive: true })));
+});
+describe("workflows CLI", () => {
+    it("prints template names in help", async () => {
+        const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+        await expect(run(["--help"])).resolves.toBe(0);
+        expect(log).toHaveBeenCalledWith(expect.stringContaining("agentics-checks"));
+        expect(log).toHaveBeenCalledWith(expect.stringContaining("app-ci-dotnet-next"));
+        expect(log).toHaveBeenCalledWith(expect.stringContaining("opencode.ci.json"));
+        log.mockRestore();
+    });
+    it("rejects an unsupported template", async () => {
+        const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+        await expect(run(["add", "--template", "unknown"])).resolves.toBe(1);
+        expect(error).toHaveBeenCalledWith("add accepts only --force or --template agentics-checks|agentics-maintenance|app-ci-dotnet-next|app-ci-node-monorepo|opencode.ci.json.");
+        error.mockRestore();
+    });
+    it("lists all workflows and templates with install status [ ] when none installed", async () => {
+        const repositoryPath = await createRepository({});
+        const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+        await expect(run(["list"], repositoryPath)).resolves.toBe(0);
+        expect(log).toHaveBeenCalledTimes(1);
+        const output = log.mock.calls[0][0];
+        expect(output).toContain("Workflows:");
+        expect(output).toContain("Templates:");
+        expect(output).toContain("refine");
+        expect(output).toContain("implement");
+        expect(output).toContain("agentics-checks");
+        expect(output).toContain("app-ci-dotnet-next");
+        // None installed: all [ ]
+        const installedCount = (output.match(/\[x\]/g) ?? []).length;
+        expect(installedCount).toBe(0);
+        // 7 routes + 5 templates = 12 entries
+        const uninstalledCount = (output.match(/\[ \]/g) ?? []).length;
+        expect(uninstalledCount).toBe(12);
+        log.mockRestore();
+    });
+    it("marks installed workflows with [x]", async () => {
+        const repositoryPath = await createRepository({
+            ".github/workflows/agent-refine.md": "# Refine",
+            ".github/workflows/agentics-checks.yml": "name: Agentics checks",
+        });
+        const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+        await expect(run(["list"], repositoryPath)).resolves.toBe(0);
+        const output = log.mock.calls[0][0];
+        const installed = output.match(/(\[x\])/g) ?? [];
+        expect(installed.length).toBe(2);
+        // refine and agentics-checks should be [x]
+        const refineLines = output.split("\n").filter((line) => line.includes("refine") || line.includes("agentics-checks"));
+        expect(refineLines.filter((line) => line.includes("[x]"))).toHaveLength(2);
+        log.mockRestore();
+    });
+    it("search filters by name", async () => {
+        const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+        await expect(run(["search", "audit"])).resolves.toBe(0);
+        const output = log.mock.calls[0][0];
+        expect(output).toContain("audit");
+        expect(output).not.toContain("Templates:");
+        // Only the audit route should be returned — no other route name should appear.
+        const visibleRoutes = ["refine", "implement", "direct", "apply-review", "merge-gate", "propose"];
+        for (const route of visibleRoutes) {
+            expect(output).not.toContain(`${route} —`);
+        }
+        log.mockRestore();
+    });
+    it("search filters by description keyword", async () => {
+        const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+        await expect(run(["search", "CI"])).resolves.toBe(0);
+        const output = log.mock.calls[0][0];
+        expect(output).toContain("dotnet-next");
+        expect(output).toContain("node-monorepo");
+        expect(output).not.toContain("refine");
+        log.mockRestore();
+    });
+    it("search with no matches prints a no-match message", async () => {
+        const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+        await expect(run(["search", "nonexistent"])).resolves.toBe(0);
+        const output = log.mock.calls[0][0];
+        expect(output).toBe("No workflows matched the search query.");
+        log.mockRestore();
+    });
+    it("search with no query fails", async () => {
+        const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+        await expect(run(["search"])).resolves.toBe(1);
+        expect(error).toHaveBeenCalledWith("search requires exactly one query argument.");
+        error.mockRestore();
+    });
+    it("search with too many arguments fails", async () => {
+        const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+        await expect(run(["search", "a", "b"])).resolves.toBe(1);
+        expect(error).toHaveBeenCalledWith("search requires exactly one query argument.");
+        error.mockRestore();
+    });
+});
+async function createRepository(files) {
+    const repositoryPath = await mkdtemp(join(tmpdir(), "workflows-"));
+    temporaryDirectories.push(repositoryPath);
+    await Promise.all(Object.entries(files).map(async ([relativePath, content]) => {
+        const path = join(repositoryPath, relativePath);
+        const { mkdir } = await import("node:fs/promises");
+        await mkdir(join(path, ".."), { recursive: true });
+        await writeFile(path, content, "utf8");
+    }));
+    return repositoryPath;
+}

package/dist/repository-inspection.test.d.ts

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

package/dist/repository-inspection.test.js

@@ -0,0 +1,77 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { inspectRepository, resolveVisibility } from "./repository-inspection.js";
+import { run } from "./index.js";
+const temporaryDirectories = [];
+afterEach(async () => {
+    await Promise.all(temporaryDirectories.splice(0).map((directory) => rm(directory, { force: true, recursive: true })));
+});
+describe("repository inspection", () => {
+    it("finds agent workflows and supported stack markers", async () => {
+        const repositoryPath = await createRepository({
+            ".github/workflows/agent-refine.md": "# Refine",
+            ".github/workflows/agent-custom.md": "# Custom",
+            ".github/workflows/other.md": "# Other",
+            "package.json": "{}",
+            "pnpm-lock.yaml": "lockfileVersion: '9.0'",
+            "apps/api/Numa.slnx": "<Solution />",
+            "openspec/changes/.gitkeep": "",
+        });
+        await expect(inspectRepository(repositoryPath)).resolves.toMatchObject({
+            existingAgentWorkflows: ["agent-custom.md", "agent-refine.md"],
+            stackHints: {
+                packageJson: true,
+                pnpmLockfile: true,
+                solutionFiles: [join(repositoryPath, "apps", "api", "Numa.slnx")],
+                openSpec: true,
+            },
+        });
+    });
+    it("uses an explicit visibility before environment or GitHub", async () => {
+        const runner = { run: async () => '{"visibility":"public"}' };
+        await expect(resolveVisibility("repo", "private", { PLATFORM_WORKFLOWS_VISIBILITY: "public" }, runner)).resolves.toEqual({
+            value: "private",
+            source: "argument",
+        });
+    });
+    it("falls back to private when GitHub CLI is unavailable", async () => {
+        const runner = { run: async () => Promise.reject(new Error("missing gh")) };
+        await expect(resolveVisibility("repo", undefined, {}, runner)).resolves.toEqual({ value: "private", source: "fallback" });
+    });
+});
+describe("CLI commands", () => {
+    it("keeps init available without writing configuration", async () => {
+        const repositoryPath = await createRepository({ "package.json": "{}" });
+        const output = captureConsole("log");
+        await expect(run(["init", "--visibility", "public"], repositoryPath)).resolves.toBe(0);
+        expect(output.calls).toHaveLength(1);
+        await expect(import("node:fs/promises").then(({ access }) => access(join(repositoryPath, ".github/workflows/shared/repo-config.md")))).rejects.toThrow();
+        output.restore();
+    });
+    it("accepts update as an add alias", async () => {
+        const repositoryPath = await createRepository({});
+        const error = captureConsole("error");
+        await expect(run(["update", "--invalid"], repositoryPath)).resolves.toBe(1);
+        expect(error.calls).toEqual(["update accepts only --force or --template agentics-checks|agentics-maintenance|app-ci-dotnet-next|app-ci-node-monorepo|opencode.ci.json."]);
+        error.restore();
+    });
+});
+function captureConsole(method) {
+    const original = console[method];
+    const calls = [];
+    console[method] = (message) => calls.push(message);
+    return { calls, restore: () => { console[method] = original; } };
+}
+async function createRepository(files) {
+    const repositoryPath = await mkdtemp(join(tmpdir(), "workflows-"));
+    temporaryDirectories.push(repositoryPath);
+    await Promise.all(Object.entries(files).map(async ([relativePath, content]) => {
+        const path = join(repositoryPath, relativePath);
+        const { mkdir } = await import("node:fs/promises");
+        await mkdir(join(path, ".."), { recursive: true });
+        await writeFile(path, content, "utf8");
+    }));
+    return repositoryPath;
+}

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>;