@plainconceptsplatform/workflows 0.1.5 → 0.2.1

package/README.md

@@ -2,11 +2,21 @@
 
 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 init
@@ -18,13 +28,14 @@ For a project-local development dependency:
 
 ```bash
 pnpm add -D @plainconceptsplatform/workflows
+pnpm exec workflows              # launch interactive TUI
 pnpm exec workflows init
 pnpm exec workflows add
 ```
 
 `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. It stops when a managed file differs. Use `pnpm exec workflows update --force` only when you intend to replace managed workflow files.
+`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.
 

package/dist/catalog-installation.d.ts

@@ -7,7 +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 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,33 +2,41 @@ 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 { catalogTemplates, templateNames } from "./workflow-catalog.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: files.map((file) => file.target), conflicts };
+    return { installed: deduplicated.map((file) => file.target), conflicts };
 }
 export async function installTemplate(repositoryPath, template, options = {}) {
     const sourcePath = options.sourcePath ?? catalogSourcePath();
@@ -43,6 +51,22 @@ export async function installTemplate(repositoryPath, template, options = {}) {
     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);
 }

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, installTemplate } 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,12 +15,14 @@ describe("catalog installation", () => {
         });
         expect(catalogSourcePath(join(packageDirectory, "dist", "catalog-installation.js"))).toBe(join(packageDirectory, "loops"));
     });
-    it("installs package-owned loops files", 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",
+            "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",
         });
@@ -30,6 +32,8 @@ describe("catalog installation", () => {
                 ".github/actions/check/action.yml",
                 ".github/workflows/agent-check.md",
                 ".github/workflows/shared/defaults.md",
+                "opencode.ci.json",
+                "scripts/compile-agent-workflows.mjs",
                 "scripts/compile.mjs",
             ],
             conflicts: [],
@@ -41,7 +45,8 @@ describe("catalog installation", () => {
         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.mjs": "// Managed by @plainconceptsplatform/workflows. Source: loops/scripts/compile.mjs. Update with `workflows update --force`; consumer edits may be overwritten.\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({});
@@ -54,7 +59,8 @@ describe("catalog installation", () => {
         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: [] });
@@ -63,7 +69,8 @@ describe("catalog installation", () => {
         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/shared/repo-config.md": "legacy consumer config\n",
@@ -72,7 +79,8 @@ describe("catalog installation", () => {
             installed: [
                 ".github/actions/check/action.yml",
                 ".github/workflows/agent-check.md",
-                "scripts/compile.mjs",
+                "opencode.ci.json",
+                "scripts/compile-agent-workflows.mjs",
             ],
             conflicts: [],
         });
@@ -82,26 +90,30 @@ describe("catalog installation", () => {
         const sourcePath = await createDirectory({
             "actions/check/action.yml": "package action\n",
             "workflows/agent-check.md": "package workflow\n",
-            "scripts/compile.mjs": "package script\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",
+            "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");
@@ -110,10 +122,10 @@ describe("catalog installation", () => {
         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",
             "templates/agentics/agentics-checks.yml": "name: Agentics checks\n",
             "templates/ci/app-ci-node-monorepo.yml": "name: Node CI\n",
-            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
         });
         const repositoryPath = await createDirectory({});
         await installCatalog(repositoryPath, { sourcePath });
@@ -127,6 +139,82 @@ describe("catalog installation", () => {
             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",

package/dist/index.js

@@ -2,13 +2,22 @@
 import { inspectRepository, parseVisibility, resolveVisibility } from "./repository-inspection.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.
@@ -29,10 +38,14 @@ Installed workflows are marked [x] when the corresponding .github/workflows/agen
 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) {
+    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));

package/dist/tui.d.ts

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

package/dist/tui.js

@@ -0,0 +1,254 @@
+import * as readline from "node:readline";
+import { formatCatalog, listCatalog } from "./catalog-listing.js";
+import { installCatalog, installMandatoryFiles, installTemplate, isTemplateName } from "./catalog-installation.js";
+const ANSI = {
+    clear: "\x1b[2J",
+    home: "\x1b[H",
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    cyan: "\x1b[36m",
+    green: "\x1b[32m",
+    grey: "\x1b[90m",
+    white: "\x1b[37m",
+    hideCursor: "\x1b[?25l",
+    showCursor: "\x1b[?25h",
+};
+export function createSelectionState(entries) {
+    const selected = new Set(entries.filter((entry) => entry.installed).map((entry) => entry.name));
+    return {
+        allItems: entries,
+        visibleItems: entries,
+        selected,
+        cursor: 0,
+        filter: "",
+        status: "selecting",
+    };
+}
+export function fuzzyMatch(text, query) {
+    if (query === "")
+        return true;
+    const haystack = text.toLowerCase();
+    const needle = query.toLowerCase();
+    let needleIndex = 0;
+    for (let i = 0; i < haystack.length && needleIndex < needle.length; i++) {
+        if (haystack[i] === needle[needleIndex])
+            needleIndex++;
+    }
+    return needleIndex === needle.length;
+}
+export function filterItems(items, filter) {
+    if (filter === "")
+        return items;
+    return items.filter((entry) => fuzzyMatch(`${entry.name} ${entry.description}`, filter));
+}
+export function applyFilter(state, filter) {
+    const visibleItems = filterItems(state.allItems, filter);
+    const cursor = visibleItems.length === 0 ? 0 : Math.min(state.cursor, visibleItems.length - 1);
+    return { ...state, visibleItems, filter, cursor };
+}
+export function clearFilter(state) {
+    return applyFilter(state, "");
+}
+export function moveCursorUp(state) {
+    if (state.visibleItems.length === 0)
+        return state;
+    const cursor = state.cursor === 0 ? state.visibleItems.length - 1 : state.cursor - 1;
+    return { ...state, cursor };
+}
+export function moveCursorDown(state) {
+    if (state.visibleItems.length === 0)
+        return state;
+    const cursor = state.cursor === state.visibleItems.length - 1 ? 0 : state.cursor + 1;
+    return { ...state, cursor };
+}
+export function toggleSelection(state) {
+    if (state.visibleItems.length === 0)
+        return state;
+    const entry = state.visibleItems[state.cursor];
+    if (entry === undefined)
+        return state;
+    const selected = new Set(state.selected);
+    if (selected.has(entry.name)) {
+        selected.delete(entry.name);
+    }
+    else {
+        selected.add(entry.name);
+    }
+    return { ...state, selected };
+}
+export function submitSelection(state) {
+    return { ...state, status: "submitting" };
+}
+export function cancelSelection(state) {
+    return { ...state, status: "cancelled" };
+}
+export function getItemsToInstall(state, force = false) {
+    return state.allItems.filter((entry) => state.selected.has(entry.name) && (force || !entry.installed));
+}
+function renderEntry(entry, highlighted, checked) {
+    const indicator = highlighted ? `${ANSI.bold}${ANSI.white}>${ANSI.reset}` : " ";
+    if (checked) {
+        const checkbox = `${ANSI.green}[x]${ANSI.reset}`;
+        const name = highlighted ? `${ANSI.white}${ANSI.bold}${entry.name}${ANSI.reset}` : entry.name;
+        const desc = `${ANSI.dim} — ${entry.description}${ANSI.reset}`;
+        return `${indicator} ${checkbox} ${name}${desc}`;
+    }
+    const checkbox = `${ANSI.grey}[ ]${ANSI.reset}`;
+    const name = highlighted ? `${ANSI.white}${ANSI.bold}${entry.name}${ANSI.reset}` : entry.name;
+    const desc = `${ANSI.dim} — ${entry.description}${ANSI.reset}`;
+    return `${indicator} ${checkbox} ${name}${desc}`;
+}
+function render(state) {
+    const lines = [];
+    lines.push(`${ANSI.cyan}${ANSI.bold}Plain Concepts Platform — Agentic Workflows${ANSI.reset}`);
+    lines.push(`${ANSI.dim}Select items to install. Already-installed items are pre-checked.${ANSI.reset}`);
+    lines.push("");
+    if (state.filter) {
+        lines.push(`${ANSI.cyan}Filter:${ANSI.reset} ${state.filter}${ANSI.grey}█${ANSI.reset}`);
+    }
+    else {
+        lines.push(`${ANSI.dim}Type to filter, arrows to navigate, space to toggle, Enter to install${ANSI.reset}`);
+    }
+    lines.push("");
+    const routes = state.visibleItems.filter((entry) => entry.kind === "route");
+    const templates = state.visibleItems.filter((entry) => entry.kind === "template");
+    let index = 0;
+    if (routes.length > 0) {
+        lines.push(`${ANSI.cyan}Workflows${ANSI.reset}`);
+        for (const entry of routes) {
+            lines.push(renderEntry(entry, index === state.cursor, state.selected.has(entry.name)));
+            index++;
+        }
+        if (templates.length > 0)
+            lines.push("");
+    }
+    if (templates.length > 0) {
+        lines.push(`${ANSI.cyan}Templates${ANSI.reset}`);
+        for (const entry of templates) {
+            lines.push(renderEntry(entry, index === state.cursor, state.selected.has(entry.name)));
+            index++;
+        }
+    }
+    if (state.visibleItems.length === 0) {
+        lines.push(`${ANSI.grey}  No items match the filter.${ANSI.reset}`);
+    }
+    lines.push("");
+    lines.push(`${ANSI.grey}↑↓ navigate  space toggle  type to filter  Enter install  Esc clear filter  q quit${ANSI.reset}`);
+    process.stdout.write(`${ANSI.clear}${ANSI.home}${lines.join("\n")}\n`);
+}
+export async function runInteractive(repositoryPath, options = {}) {
+    const force = options.force ?? false;
+    if (process.stdin.isTTY !== true) {
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        console.log(formatCatalog(entries));
+        console.log("");
+        console.log("Run with a TTY for an interactive selection screen, or use: workflows add [--template <name>] [--force]");
+        return 0;
+    }
+    const entries = await listCatalog({ installedPath: repositoryPath });
+    let state = createSelectionState(entries);
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdout.write(ANSI.hideCursor);
+    render(state);
+    return new Promise((resolve) => {
+        const onKeypress = (str, key) => {
+            if (key?.ctrl && key?.name === "c") {
+                cleanup();
+                resolve(0);
+                return;
+            }
+            if (str === "q" && state.filter === "" && !key?.ctrl && !key?.meta && !key?.shift) {
+                cleanup();
+                resolve(0);
+                return;
+            }
+            if (key?.name === "escape") {
+                state = clearFilter(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "up") {
+                state = moveCursorUp(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "down") {
+                state = moveCursorDown(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "space" || str === " ") {
+                state = toggleSelection(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "return" || key?.name === "enter") {
+                cleanup();
+                void installSelected(state, repositoryPath, force).then((exitCode) => resolve(exitCode));
+                return;
+            }
+            if (key?.name === "backspace") {
+                state = applyFilter(state, state.filter.slice(0, -1));
+                render(state);
+                return;
+            }
+            if (str !== undefined &&
+                str.length === 1 &&
+                str >= " " &&
+                str <= "~" &&
+                !key?.ctrl &&
+                !key?.meta) {
+                state = applyFilter(state, state.filter + str);
+                render(state);
+            }
+        };
+        function cleanup() {
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stdout.write(`${ANSI.showCursor}${ANSI.reset}`);
+            process.stdin.removeListener("keypress", onKeypress);
+        }
+        process.stdin.on("keypress", onKeypress);
+    });
+}
+async function installSelected(state, repositoryPath, force) {
+    const items = getItemsToInstall(state, force);
+    const routes = items.filter((entry) => entry.kind === "route");
+    const templates = items.filter((entry) => entry.kind === "template");
+    const allConflicts = [];
+    const allInstalled = [];
+    if (routes.length > 0) {
+        const result = await installCatalog(repositoryPath, { force });
+        allConflicts.push(...result.conflicts);
+        allInstalled.push(...result.installed);
+    }
+    else {
+        const result = await installMandatoryFiles(repositoryPath, { force });
+        allConflicts.push(...result.conflicts);
+        allInstalled.push(...result.installed);
+    }
+    for (const template of templates) {
+        if (!isTemplateName(template.name))
+            continue;
+        const result = await installTemplate(repositoryPath, template.name, { force });
+        allConflicts.push(...result.conflicts);
+        allInstalled.push(...result.installed);
+    }
+    if (allConflicts.length > 0 && !force) {
+        console.error(`Conflicts found. Re-run with --force to overwrite:\n${allConflicts.join("\n")}`);
+        return 1;
+    }
+    if (allInstalled.length > 0) {
+        console.log(`Installed ${allInstalled.length} item(s):`);
+        for (const file of allInstalled) {
+            console.log(`  ${file}`);
+        }
+    }
+    else {
+        console.log("All selected items are already installed.");
+    }
+    return 0;
+}

package/dist/tui.test.d.ts

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