@plainconceptsplatform/workflows 0.4.34 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "0.4.34",
+  "version": "0.5.1",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",
@@ -25,13 +25,6 @@
     "loops",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc --project tsconfig.json",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit --project tsconfig.json",
-    "release": "pnpm build && pnpm test && npm publish --access public",
-    "prepack": "node ./scripts/copy-loops.mjs"
-  },
   "engines": {
     "node": ">=20.19"
   },
@@ -40,5 +33,11 @@
     "typescript": "^5.8.0",
     "vitest": "^3.0.0",
     "yaml": "^2.9.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "release": "pnpm build && pnpm test && npm publish --access public"
   }
 }

package/dist/action-validation.test.d.ts

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

package/dist/action-validation.test.js

@@ -1,84 +0,0 @@
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { parse } from "yaml";
-import { catalogSourcePath } from "./catalog-installation.js";
-async function collectActionYmlFiles(actionsDir) {
-    const entries = await readdir(actionsDir, { withFileTypes: true });
-    const results = [];
-    for (const entry of entries) {
-        if (entry.isDirectory()) {
-            for (const sub of await readdir(join(actionsDir, entry.name), { withFileTypes: true })) {
-                if (sub.isFile() && sub.name === "action.yml") {
-                    results.push(join(actionsDir, entry.name, sub.name));
-                }
-            }
-        }
-    }
-    return results;
-}
-async function loadManifests() {
-    const actionsDir = join(catalogSourcePath(), "actions");
-    const files = await collectActionYmlFiles(actionsDir);
-    return Promise.all(files.map(async (file) => {
-        const content = await readFile(file, "utf8");
-        return { file, content, manifest: parse(content) };
-    }));
-}
-describe("action.yml manifest validation", () => {
-    it("finds action.yml files under loops/actions/", async () => {
-        const manifests = await loadManifests();
-        expect(manifests.length).toBeGreaterThanOrEqual(1);
-    });
-    it("every action.yml parses as valid YAML", async () => {
-        for (const { file, content } of await loadManifests()) {
-            expect(() => parse(content), `${file}: failed to parse as YAML`).not.toThrow();
-        }
-    });
-    it("every action.yml has runs.using === composite", async () => {
-        for (const { file, manifest } of await loadManifests()) {
-            expect(manifest.runs?.using, `${file}: runs.using is not "composite"`).toBe("composite");
-        }
-    });
-    it("every action.yml has at least one step in runs.steps", async () => {
-        for (const { file, manifest } of await loadManifests()) {
-            expect(manifest.runs?.steps, `${file}: runs.steps is undefined`).toBeDefined();
-            expect(manifest.runs.steps.length, `${file}: runs.steps is empty — file may be truncated`).toBeGreaterThanOrEqual(1);
-        }
-    });
-    it("every step with shell: also has run:", async () => {
-        for (const { file, manifest } of await loadManifests()) {
-            const steps = manifest.runs?.steps ?? [];
-            for (const [index, step] of steps.entries()) {
-                const label = step.name ?? step.id ?? `step ${index}`;
-                if (step.shell !== undefined) {
-                    expect(step.run, `${file}: step "${label}" has shell: but no run:`).toBeDefined();
-                    expect(typeof step.run, `${file}: step "${label}" run is not a string`).toBe("string");
-                    expect(step.run.trim().length, `${file}: step "${label}" run is empty`).toBeGreaterThan(0);
-                }
-            }
-        }
-    });
-    it("every step with env: also has run: or uses:", async () => {
-        for (const { file, manifest } of await loadManifests()) {
-            const steps = manifest.runs?.steps ?? [];
-            for (const [index, step] of steps.entries()) {
-                const label = step.name ?? step.id ?? `step ${index}`;
-                if (step.env !== undefined) {
-                    expect(step.run !== undefined || step.uses !== undefined, `${file}: step "${label}" has env: but no run: or uses:`).toBe(true);
-                }
-            }
-        }
-    });
-    it("no action.yml is truncated (last step has run: or uses: with non-empty value)", async () => {
-        for (const { file, manifest } of await loadManifests()) {
-            const steps = manifest.runs?.steps ?? [];
-            expect(steps.length, `${file}: no steps found — file may be truncated`).toBeGreaterThanOrEqual(1);
-            const lastStep = steps[steps.length - 1];
-            const hasTerminal = (lastStep.run !== undefined && lastStep.run.trim().length > 0) ||
-                (lastStep.uses !== undefined && lastStep.uses.trim().length > 0) ||
-                (lastStep.with !== undefined);
-            expect(hasTerminal, `${file}: last step appears truncated`).toBe(true);
-        }
-    });
-});

package/dist/catalog-installation.d.ts

@@ -1,30 +0,0 @@
-import { type RouteName, type TemplateName } from "./workflow-catalog.js";
-import type { RepositoryInspection } from "./repository-inspection.js";
-export interface CatalogInstallResult {
-    readonly installed: readonly string[];
-    readonly conflicts: readonly string[];
-}
-export interface CatalogInstallOptions {
-    readonly force?: boolean;
-    readonly sourcePath?: string;
-    readonly selectedRoutes?: readonly RouteName[];
-    readonly inspection?: RepositoryInspection;
-    readonly compile?: (repositoryPath: string) => Promise<void>;
-}
-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 installedRoutes(repositoryPath: string): Promise<RouteName[]>;
-export declare function removeRouteFiles(repositoryPath: string, routes: readonly RouteName[]): Promise<string[]>;
-export declare function isTemplateName(value: string): value is TemplateName;
-export declare function ensurePreCommitHook(repositoryPath: string): Promise<void>;
-export declare function runCompileIfAvailable(repositoryPath: string): Promise<void>;
-export declare function exists(path: string): Promise<boolean>;
-export {};

package/dist/catalog-installation.js

@@ -1,379 +0,0 @@
-import { execFile } from "node:child_process";
-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";
-import { promisify } from "node:util";
-import { parse as parseYaml } from "yaml";
-import { catalogTemplates, mandatoryFiles, routeNames, templateNames, workflowRoutes } from "./workflow-catalog.js";
-import { processRoutes, excludedWorkerFiles } from "./route-processing.js";
-import { generateOpencodeCi, generateOpencodeConfig, generateStackDefaults, injectStackEnv } from "./stack-defaults.js";
-const execFileAsync = promisify(execFile);
-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 selectedRoutes = options.selectedRoutes ?? routeNames;
-    const allFiles = [...await catalogFiles(sourcePath), ...mandatoryFileSpecs(sourcePath)];
-    const deduplicated = allFiles.filter((file, index) => allFiles.findIndex((f) => f.target === file.target) === index).sort((left, right) => left.target.localeCompare(right.target));
-    const excluded = excludedWorkerFiles(selectedRoutes);
-    const filtered = deduplicated.filter((file) => {
-        const fileName = file.target.split("/").pop() ?? "";
-        return !excluded.has(fileName);
-    });
-    const fileContents = new Map();
-    for (const file of filtered) {
-        fileContents.set(file.target, await readFile(file.source, "utf8"));
-    }
-    let processedContents = processRoutes(fileContents, selectedRoutes);
-    if (options.inspection !== undefined) {
-        const defaults = generateStackDefaults(options.inspection);
-        processedContents = injectStackIntoWorkers(processedContents, defaults);
-        processedContents = transformOpencodeFiles(processedContents, options.inspection);
-    }
-    processedContents = await preserveConsumerWorkerEnv(repositoryPath, processedContents);
-    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) {
-    const result = new Map(files);
-    for (const [key, content] of result) {
-        if (key.startsWith(".github/workflows/agent-") && key.endsWith(".md")) {
-            result.set(key, injectStackEnv(content, defaults));
-        }
-    }
-    return result;
-}
-async function preserveConsumerWorkerEnv(repositoryPath, files) {
-    const result = new Map(files);
-    for (const [target, content] of result) {
-        if (!target.startsWith(".github/workflows/agent-") || !target.endsWith(".md"))
-            continue;
-        const existingPath = join(repositoryPath, target);
-        if (!await exists(existingPath))
-            continue;
-        result.set(target, mergeWorkerEnv(content, await readFile(existingPath, "utf8")));
-    }
-    return result;
-}
-function mergeWorkerEnv(packageContent, consumerContent) {
-    const consumerEnv = workerEnvValues(consumerContent);
-    let result = packageContent.replace(/^  ([A-Z][A-Z0-9_]*): .+$/gm, (line, key) => consumerEnv.has(key) ? `  ${key}: ${consumerEnv.get(key)}` : line);
-    const endpoint = engineEndpoint(consumerContent);
-    if (endpoint !== undefined) {
-        result = result.replace(/^    OPENAI_BASE_URL: .+$/m, `    OPENAI_BASE_URL: ${endpoint}`);
-    }
-    return result;
-}
-function workerEnvValues(content) {
-    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/m.exec(content)?.[1];
-    const envBlock = frontmatter === undefined ? undefined : /^env:\r?\n((?:  .*\r?\n?)*)/m.exec(frontmatter)?.[1];
-    const values = new Map();
-    if (envBlock === undefined)
-        return values;
-    for (const line of envBlock.split(/\r?\n/)) {
-        const match = /^  ([A-Z][A-Z0-9_]*): (.+)$/.exec(line);
-        if (match !== null)
-            values.set(match[1], match[2]);
-    }
-    return values;
-}
-function engineEndpoint(content) {
-    return /^    OPENAI_BASE_URL: (.+)$/m.exec(content)?.[1];
-}
-function transformOpencodeFiles(files, inspection) {
-    const result = new Map(files);
-    for (const [key, content] of result) {
-        if (key.endsWith("opencode-ci.md")) {
-            result.set(key, generateOpencodeCi(content, inspection));
-        }
-        else if (key === "opencode.ci.json") {
-            result.set(key, generateOpencodeConfig(content, inspection));
-        }
-    }
-    return result;
-}
-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);
-    if (options.inspection !== undefined && template === "opencode.ci.json") {
-        const baseContent = await readFile(source, "utf8");
-        const transformed = generateOpencodeConfig(baseContent, options.inspection);
-        await writeFile(destination, transformed, "utf8");
-    }
-    try {
-        await runCompileIfAvailable(repositoryPath);
-    }
-    catch {
-        // compile failure is non-fatal
-    }
-    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 };
-    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 async function installedRoutes(repositoryPath) {
-    const found = await Promise.all(workflowRoutes.map(async (route) => (await exists(join(repositoryPath, ".github", "workflows", route.worker))) ? route.name : undefined));
-    return found.filter((name) => name !== undefined);
-}
-export async function removeRouteFiles(repositoryPath, routes) {
-    const workerByRoute = new Map(workflowRoutes.map((route) => [route.name, route.worker]));
-    const removed = [];
-    for (const route of routes) {
-        const worker = workerByRoute.get(route);
-        if (worker === undefined)
-            continue;
-        const lock = worker.replace(/\.md$/, ".lock.yml");
-        for (const file of [worker, lock]) {
-            const destination = join(repositoryPath, ".github", "workflows", file);
-            if (await exists(destination)) {
-                await rm(destination, { force: true });
-                removed.push(`.github/workflows/${file}`);
-            }
-        }
-    }
-    return removed.sort();
-}
-export function isTemplateName(value) {
-    return templateNames.includes(value);
-}
-export async function ensurePreCommitHook(repositoryPath) {
-    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";
-    const stageLine = "git add -- .github/workflows/*.lock.yml";
-    const actionLockLine = "[ ! -f .github/actions/actions-lock.json ] || git add -- .github/actions/actions-lock.json";
-    const managedLines = `if git diff --cached --name-only -- .github | grep -q .; then\n  ${compileLine}\n  ${stageLine}\n  ${actionLockLine}\nfi\n`;
-    if (!await exists(hookPath)) {
-        return { target, content: managedLines };
-    }
-    const content = (await readFile(hookPath, "utf8"))
-        .replace("pnpm exec if git diff --cached --name-only -- .github | grep -q .; then", "if git diff --cached --name-only -- .github | grep -q .; then");
-    if (content.includes("compile-agent-workflows")) {
-        const legacyLines = `${compileLine}\n${stageLine}\n${actionLockLine}\n`;
-        if (content.includes(managedLines))
-            return { target, content };
-        if (content.includes(legacyLines))
-            return { target, content: content.replace(legacyLines, managedLines) };
-        const suffix = content.endsWith("\n") || content === "" ? "" : "\n";
-        return { target, content: `${content}${suffix}${managedLines}` };
-    }
-    return { target, content: content.endsWith("\n") || content === ""
-            ? `${content}${managedLines}`
-            : `${content}\n${managedLines}` };
-}
-export async function runCompileIfAvailable(repositoryPath) {
-    const script = join(repositoryPath, "scripts", "compile-agent-workflows.mjs");
-    if (await exists(script)) {
-        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);
-        await initializeStagingRepository(stagingPath);
-        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 initializeStagingRepository(stagingPath) {
-    await execFileAsync("git", ["init", "--quiet"], { cwd: stagingPath, windowsHide: 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));
-}
-function validateActionManifests(updates) {
-    for (const { target, content } of updates) {
-        if (!target.endsWith("action.yml"))
-            continue;
-        let manifest;
-        try {
-            manifest = parseYaml(content);
-        }
-        catch {
-            throw new Error(`${target}: invalid YAML — failed to parse action manifest`);
-        }
-        if (manifest?.runs?.using !== "composite")
-            continue;
-        const steps = manifest.runs?.steps;
-        if (!Array.isArray(steps) || steps.length === 0) {
-            throw new Error(`${target}: composite action has no steps — file may be truncated`);
-        }
-        for (const [index, step] of steps.entries()) {
-            const label = step.name ?? step.id ?? `step ${index}`;
-            if (step.shell !== undefined && (typeof step.run !== "string" || step.run.trim() === "")) {
-                throw new Error(`${target}: step "${label}" has shell: but no run: — manifest is invalid or truncated`);
-            }
-        }
-    }
-}
-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);
-        validateActionManifests(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" : template === "github-release" ? "release" : template === "visual-evidence" ? "visual-evidence" : template === "bug-report" || template === "feature-request" ? "issues" : "agentics";
-    const isWorkflow = entry.file.endsWith(".yml");
-    const inferredTarget = template === "app-ci-dotnet-next"
-        ? ".github/workflows/app-ci.yml"
-        : isWorkflow ? `.github/workflows/${entry.file}` : entry.file;
-    const target = entry.target ?? inferredTarget;
-    return { directory, file: entry.file, target };
-}
-async function catalogFiles(sourcePath) {
-    const files = [];
-    for (const [sourceDirectory, targetDirectory] of sourceMappings) {
-        for (const file of await filesIn(join(sourcePath, sourceDirectory))) {
-            if (isGeneratedFile(file))
-                continue;
-            files.push({
-                source: join(sourcePath, sourceDirectory, file),
-                target: `${targetDirectory}/${file.replaceAll("\\", "/")}`,
-                managed: true,
-            });
-        }
-    }
-    return files.sort((left, right) => left.target.localeCompare(right.target));
-}
-function isGeneratedFile(file) {
-    const normalized = file.replaceAll("\\", "/");
-    return normalized.endsWith(".lock.yml") || normalized.endsWith("actions-lock.json");
-}
-async function filesIn(path) {
-    const entries = await readdir(path, { recursive: true, withFileTypes: true });
-    return entries
-        .filter((entry) => entry.isFile())
-        .map((entry) => entry.parentPath === undefined ? entry.name : relative(path, join(entry.parentPath, entry.name)));
-}
-async function filesMatch(source, destination) {
-    try {
-        const [sourceContent, destinationContent] = await Promise.all([readFile(source), readFile(destination)]);
-        return sourceContent.equals(destinationContent);
-    }
-    catch {
-        return false;
-    }
-}
-export async function exists(path) {
-    try {
-        await access(path, constants.F_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

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

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