@plainconceptsplatform/workflows 0.5.1 → 0.6.1

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

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

package/dist/action-validation.test.js

@@ -0,0 +1,87 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { parse } from "yaml";
+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() {
+    // catalogSourcePath() resolves against the published package layout, where loops/ ships
+    // next to the compiled module. In this repository loops/ lives at the root, two levels
+    // above this test, so resolve it from the source tree instead.
+    const actionsDir = join(fileURLToPath(new URL("../../loops", import.meta.url)), "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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,422 @@
+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 preserveRunnerPool(result, consumerContent);
+}
+// Which self-hosted pool a worker's agent jobs run on. gh-aw cannot share runs-on through
+// an import, so every worker names it, and it belongs with the env values rather than with
+// the prompt: a forced update that rewrote it would move a repository's agents onto another
+// pool, and one of ours has two machines in it. ubuntu-latest is excluded, being GitHub's
+// own runner, used by the deterministic jobs everywhere and chosen by nobody.
+function runnerPools(content) {
+    const found = new Set();
+    for (const match of content.matchAll(/^\s*runs-on(?:-slim)?: (\S+)\s*$/gm)) {
+        if (match[1] !== "ubuntu-latest")
+            found.add(match[1]);
+    }
+    return [...found];
+}
+function preserveRunnerPool(packageContent, consumerContent) {
+    const mine = runnerPools(consumerContent);
+    const theirs = runnerPools(packageContent);
+    // Only an unambiguous swap. A consumer naming several pools has drifted rather than
+    // decided, and guessing which it meant is worse than leaving the package's.
+    if (mine.length !== 1 || theirs.length !== 1 || mine[0] === theirs[0])
+        return packageContent;
+    return packageContent.replace(/^(\s*runs-on(?:-slim)?: )(\S+)(\s*)$/gm, (line, prefix, pool, tail) => pool === "ubuntu-latest" ? line : `${prefix}${mine[0]}${tail}`);
+}
+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;
+}
+// Templates that need a companion config beside the workflow file. actionlint only
+// knows GitHub-hosted runner labels, so every workflow naming a self-hosted label is an
+// error without this file; it belongs wherever the lint workflow that reads it lives.
+const templateCompanions = {
+    "agentics-checks": [{ source: "templates/agentics/actionlint.yaml", target: ".github/actionlint.yaml" }],
+};
+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 companions = templateCompanions[template] ?? [];
+    const destinations = [
+        { source, target, companion: false },
+        ...companions.map((companion) => ({
+            source: join(sourcePath, companion.source),
+            target: companion.target,
+            companion: true,
+        })),
+    ];
+    const conflicts = (await Promise.all(destinations.map(async (entry) => await exists(join(repositoryPath, entry.target)) && await exists(entry.source) && !(await filesMatch(entry.source, join(repositoryPath, entry.target)))
+        ? entry.target
+        : undefined))).filter((file) => file !== undefined);
+    if (conflicts.length > 0 && !options.force)
+        return { installed: [], conflicts };
+    for (const entry of destinations) {
+        if (!(await exists(entry.source)))
+            continue; // companion files may not exist for every template version
+        const destination = join(repositoryPath, entry.target);
+        await mkdir(dirname(destination), { recursive: true });
+        await copyFile(entry.source, destination);
+    }
+    if (options.inspection !== undefined && template === "opencode.ci.json") {
+        const baseContent = await readFile(source, "utf8");
+        const transformed = generateOpencodeConfig(baseContent, options.inspection);
+        await writeFile(join(repositoryPath, target), transformed, "utf8");
+    }
+    try {
+        await runCompileIfAvailable(repositoryPath);
+    }
+    catch {
+        // compile failure is non-fatal
+    }
+    return { installed: (await Promise.all(destinations.map(async (entry) => await exists(entry.source) ? entry.target : undefined))).filter((file) => file !== undefined), 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

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