@opengroundplan/core 0.1.1

package/dist/adapters.d.ts

@@ -0,0 +1,43 @@
+import { AGENTS_FILE } from './agentkit.js';
+import type { GroundplanConfig } from './config.js';
+import type { Adapter, RegistryItem } from './schema.js';
+import type { Vars } from './tokens.js';
+export interface AdapterFile {
+    path: string;
+    content: string;
+    adapter: string;
+    /** The registry item this file was rendered for, when it is one of many. */
+    item?: string;
+}
+export interface AdapterRequest {
+    adapters: Adapter[];
+    registry: RegistryItem[];
+    /** Project-scope variables: agentsMdPath, the toolchain commands, the solution name. */
+    vars: Vars;
+    config: GroundplanConfig;
+}
+/**
+ * Templates are named after the file they produce, plus `.tmpl`.
+ *
+ * A per-item output is the exception: `.claude/rules/__ruleId__.md` is rendered once per item,
+ * so its template is named for the kind — `rule.md.tmpl` — not for any one item's filename.
+ * `__skillId__/SKILL.md` needs no exception because its basename is already the kind.
+ */
+export declare function templatePaths(config: GroundplanConfig, adapterId: string, output: {
+    path: string;
+    template?: string;
+}): string[];
+/**
+ * Renders every file the selected adapters produce.
+ *
+ * Skips nothing silently: an output whose template is missing, or whose template needs a
+ * variable the caller did not supply, is returned in `skipped` with the reason. `doctor`
+ * fails on the first case, so it cannot reach a user.
+ */
+export declare function renderAdapterFiles(request: AdapterRequest): Promise<{
+    files: AdapterFile[];
+    skipped: string[];
+}>;
+/** Writes what `renderAdapterFiles` produced, creating directories as needed. */
+export declare function writeAdapterFiles(target: string, files: AdapterFile[]): Promise<void>;
+export { AGENTS_FILE };

package/dist/adapters.js

@@ -0,0 +1,181 @@
+/**
+ * Compiles the agent instructions outward, one file per tool.
+ *
+ * This is the layer ADR 0002 exists for: AGENTS.md is written once, and every other tool's
+ * file is a wrapper that imports it or a delta that adds only what that tool uniquely needs.
+ * Nothing here restates canonical content — `checkGoverningRule` fails the catalog if an
+ * adapter tries.
+ *
+ * It emitted nothing at all until this module existed. The templates were on disk, the
+ * adapters declared their outputs, and no code path rendered either.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { AGENTS_FILE } from './agentkit.js';
+import { test } from './condition.js';
+import { collectTokens, renderContent, renderPath } from './tokens.js';
+/**
+ * Templates are named after the file they produce, plus `.tmpl`.
+ *
+ * A per-item output is the exception: `.claude/rules/__ruleId__.md` is rendered once per item,
+ * so its template is named for the kind — `rule.md.tmpl` — not for any one item's filename.
+ * `__skillId__/SKILL.md` needs no exception because its basename is already the kind.
+ */
+export function templatePaths(config, adapterId, output) {
+    const dir = path.join(config.paths.adapters, adapterId, 'templates');
+    const names = output.template
+        ? [output.template.endsWith('.tmpl') ? output.template : `${output.template}.tmpl`]
+        : [`${path.basename(output.path)}.tmpl`];
+    return names.map((name) => path.join(dir, name));
+}
+/** A path carrying a `__token__` is rendered once per matching registry item. */
+function isPerItem(outputPath) {
+    return /__[A-Za-z]/.test(outputPath);
+}
+/** `.claude/rules/__ruleId__.md` → `ruleId`. */
+function itemTokenOf(outputPath) {
+    return /__([A-Za-z][A-Za-z0-9]*)__/.exec(outputPath)?.[1];
+}
+/**
+ * Which registry kind an output is for, taken from the token the author wrote. The token names
+ * the thing — `__skillId__` is a skill — so the mapping is the author's own vocabulary rather
+ * than a second list to keep in sync.
+ */
+const KIND_FOR_TOKEN = {
+    ruleId: 'skill',
+    skillId: 'skill',
+    commandId: 'command',
+    agentId: 'agent',
+};
+/** Per-item variables. Pre-rendered because the engine substitutes, it does not loop. */
+function itemVars(item) {
+    const globs = item.tags.filter((tag) => tag.includes('*') || tag.includes('/'));
+    return {
+        itemId: item.id,
+        itemName: item.name,
+        itemDescription: item.description,
+        itemBody: item.body,
+        itemGlobsCsv: globs.join(','),
+        itemGlobsYamlList: globs.length ? globs.map((g) => `  - "${g}"`).join('\n') : '  []',
+        itemTools: '',
+        itemArgumentHint: '',
+    };
+}
+/** A JSON array laid out the way a formatter would leave it, at the nesting the template uses. */
+function denyList(paths) {
+    if (paths.length === 0)
+        return '[]';
+    const entries = paths.map((p) => `      ${JSON.stringify(`Edit(${p})`)}`).join(',\n');
+    return ['[', entries, '    ]'].join('\n');
+}
+/** True when the item asked for this adapter, by id or through a universal target. */
+function targets(item, adapter) {
+    return item.targets.includes(adapter.id) || item.targets.includes('agents-md');
+}
+/**
+ * Renders every file the selected adapters produce.
+ *
+ * Skips nothing silently: an output whose template is missing, or whose template needs a
+ * variable the caller did not supply, is returned in `skipped` with the reason. `doctor`
+ * fails on the first case, so it cannot reach a user.
+ */
+export async function renderAdapterFiles(request) {
+    const files = [];
+    const skipped = [];
+    // Gating flags the adapters' `when:` clauses read. Derived from what the registry actually
+    // holds, so a tool gets a rules directory only when there are rules to put in it.
+    const vars = {
+        ...request.vars,
+        hasSkills: request.registry.some((i) => i.kind === 'skill'),
+        hasGlobRules: request.registry.some((i) => i.kind === 'skill'),
+        hasCommands: request.registry.some((i) => i.kind === 'command'),
+        hasAgents: request.registry.some((i) => i.kind === 'agent'),
+        // Pre-indented to match the settings file's own style. A one-line array renders valid
+        // JSON that the generated repo's own formatter then rejects, so `pnpm lint` fails on a
+        // file the generator wrote.
+        protectedPathsDenyJson: denyList(request.config.protectedPaths),
+    };
+    for (const adapter of request.adapters) {
+        for (const output of adapter.outputs) {
+            // A native reader gets no wrapper. A duplicate of AGENTS.md is exactly what drifts.
+            if (adapter.readsAgentsMd && output.mode === 'wrapper')
+                continue;
+            if (!test(output.when, vars))
+                continue;
+            const candidates = templatePaths(request.config, adapter.id, output);
+            let template = null;
+            let source = null;
+            for (const candidate of candidates) {
+                const content = await fs.readFile(candidate, 'utf8').catch(() => null);
+                if (content !== null) {
+                    template = candidate;
+                    source = content;
+                    break;
+                }
+            }
+            if (source === null || template === null) {
+                const tried = candidates.map((c) => path.relative(request.config.groundplanHome, c)).join(' or ');
+                skipped.push(`${adapter.id}: ${output.path} — no template at ${tried}`);
+                continue;
+            }
+            if (isPerItem(output.path)) {
+                files.push(...renderPerItem(adapter, output, source, template, request, vars, skipped));
+                continue;
+            }
+            const missing = collectTokens(source).filter((token) => !(token in vars));
+            if (missing.length > 0) {
+                skipped.push(`${adapter.id}: ${output.path} — needs ${missing.join(', ')}`);
+                continue;
+            }
+            files.push({
+                path: output.path,
+                content: renderContent(source, vars, template),
+                adapter: adapter.id,
+            });
+        }
+    }
+    return { files, skipped };
+}
+function renderPerItem(adapter, output, source, template, request, projectVars, skipped) {
+    const token = itemTokenOf(output.path);
+    const kind = token === undefined ? undefined : KIND_FOR_TOKEN[token];
+    if (token === undefined || kind === undefined) {
+        skipped.push(`${adapter.id}: ${output.path} — no registry kind for token "${token}"`);
+        return [];
+    }
+    const rendered = [];
+    for (const item of request.registry) {
+        if (item.kind !== kind || !targets(item, adapter))
+            continue;
+        if (!test(item.when, projectVars))
+            continue;
+        // The tool must be able to express the item; a rules-only tool gets no subagent file.
+        const unsupported = item.requiresCapability.filter((c) => !adapter.capabilities.includes(c));
+        if (unsupported.length > 0)
+            continue;
+        const vars = { ...projectVars, ...itemVars(item) };
+        vars[token] = item.id;
+        const missing = collectTokens(source).filter((name) => !(name in vars));
+        if (missing.length > 0) {
+            skipped.push(`${adapter.id}: ${output.path} (${item.id}) — needs ${missing.join(', ')}`);
+            continue;
+        }
+        rendered.push({
+            path: renderPath(output.path, vars, template),
+            content: renderContent(source, vars, template),
+            adapter: adapter.id,
+            item: item.id,
+        });
+    }
+    return rendered;
+}
+/** Writes what `renderAdapterFiles` produced, creating directories as needed. */
+export async function writeAdapterFiles(target, files) {
+    for (const file of files) {
+        const destination = path.join(target, file.path);
+        await fs.mkdir(path.dirname(destination), { recursive: true });
+        await fs.writeFile(destination, file.content, 'utf8');
+    }
+}
+export { AGENTS_FILE };
+//# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"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"}

package/dist/agentkit.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent-kit wiring: the variables adapter templates render against, and the doctor checks
+ * that keep adapters honest.
+ *
+ * The engine does flat substitution only, so anything list-shaped must be pre-rendered
+ * here rather than looped over in a template. That constraint is deliberate: templates stay
+ * data, and data cannot execute.
+ */
+import type { Adapter, Blueprint, RegistryItem } from './schema.js';
+import type { GroundplanConfig } from './config.js';
+import type { Vars } from './tokens.js';
+/** Every adapter points at this one file; none of them restates its content. */
+export declare const AGENTS_FILE = "AGENTS.md";
+export interface GlobalsInput {
+    solutionName: string;
+    /** The base blueprint's id. Lets a layer condition on which skeleton it is layering over. */
+    base: string;
+    stack: string;
+    teamSize: number;
+    architecture?: string;
+    adapters: string[];
+    today: string;
+    /** Pre-rendered invoke specs. Defaults to none so a caller without a catalog still works. */
+    delegationTools?: string;
+}
+/**
+ * The variables every template may use without declaring them. Defined once so the CLI and
+ * the test suite cannot drift — a global that exists in one and not the other is a template
+ * that passes tests and fails for a user.
+ */
+export declare function engineGlobals(input: GlobalsInput): Vars;
+/**
+ * Toolchain commands for the generated repo, resolved from the base blueprint that declared
+ * them and falling back to the stack's defaults. Derived rather than asked: a user who just
+ * picked "Next.js" should not then be interrogated about their build command.
+ */
+export declare function commandVars(blueprints: Iterable<Blueprint>, stack: string, config: GroundplanConfig): Vars;
+/**
+ * Headless invocation specs for the tools the repo was wired for, pre-rendered as JSON.
+ * `.agent/delegate.mjs` reads this to actually run another agent, so delegation is an
+ * executed command rather than a routing table nobody acts on.
+ *
+ * Only adapters with a verified `invoke` block appear — a guessed flag produces a
+ * delegation that silently does nothing.
+ */
+export declare function delegationToolsJson(adapters: Iterable<Adapter>): string;
+/**
+ * ADR 0007, enforced rather than documented. A standard that lives only in prose decays into
+ * prose; these are the parts a machine can check.
+ */
+export declare function checkDelegationCompliance(adapters: Iterable<Adapter>): string[];
+/**
+ * The governing rule, enforced mechanically: a tool that reads AGENTS.md natively must not
+ * be handed a second instruction file, because two sources of truth drift apart.
+ */
+export declare function checkGoverningRule(adapters: Iterable<Adapter>): string[];
+/**
+ * A declared capability with nothing behind it is a promise the adapter does not keep.
+ *
+ * "Behind it" means either a static output in the adapter, or registry items of that kind
+ * targeting it — commands, hooks, skills, and subagents are supplied by the registry, not
+ * enumerated per adapter. And `instructions` is satisfied by AGENTS.md itself for a native
+ * reader, where emitting a file would violate the governing rule.
+ */
+export declare function checkCapabilityCoverage(adapters: Iterable<Adapter>, registry?: Iterable<RegistryItem>): string[];

package/dist/agentkit.js

@@ -0,0 +1,183 @@
+/** Every adapter points at this one file; none of them restates its content. */
+export const AGENTS_FILE = 'AGENTS.md';
+/**
+ * The variables every template may use without declaring them. Defined once so the CLI and
+ * the test suite cannot drift — a global that exists in one and not the other is a template
+ * that passes tests and fails for a user.
+ */
+export function engineGlobals(input) {
+    return {
+        solutionName: input.solutionName,
+        base: input.base,
+        stack: input.stack,
+        teamSize: input.teamSize,
+        architecture: input.architecture ?? 'unspecified',
+        adapters: input.adapters,
+        today: input.today,
+        agentsMdPath: AGENTS_FILE,
+        delegationToolsJson: input.delegationTools ?? '{}',
+    };
+}
+/**
+ * Toolchain commands for the generated repo, resolved from the base blueprint that declared
+ * them and falling back to the stack's defaults. Derived rather than asked: a user who just
+ * picked "Next.js" should not then be interrogated about their build command.
+ */
+export function commandVars(blueprints, stack, config) {
+    const declared = [...blueprints].find((b) => b.commands)?.commands;
+    const fallback = config.stackCommands[stack];
+    const commands = declared ?? fallback;
+    if (!commands)
+        throw new Error(`No commands declared for stack "${stack}" and no fallback exists.`);
+    return {
+        buildCommand: commands.build,
+        testCommand: commands.test,
+        lintCommand: commands.lint,
+        typecheckCommand: commands.typecheck ?? '',
+        devCommand: commands.dev ?? '',
+    };
+}
+/**
+ * Headless invocation specs for the tools the repo was wired for, pre-rendered as JSON.
+ * `.agent/delegate.mjs` reads this to actually run another agent, so delegation is an
+ * executed command rather than a routing table nobody acts on.
+ *
+ * Only adapters with a verified `invoke` block appear — a guessed flag produces a
+ * delegation that silently does nothing.
+ */
+export function delegationToolsJson(adapters) {
+    const tools = {};
+    for (const adapter of adapters) {
+        if (!adapter.invoke)
+            continue;
+        tools[adapter.id] = {
+            id: adapter.id,
+            binary: adapter.invoke.binary,
+            args: adapter.invoke.args,
+            promptVia: adapter.invoke.promptVia,
+            autoApprove: adapter.invoke.autoApprove,
+            modelFlag: adapter.invoke.modelFlag,
+            detect: adapter.invoke.detect,
+            install: adapter.invoke.install ?? null,
+            verified: adapter.invoke.verified,
+        };
+    }
+    return JSON.stringify(tools, null, 2);
+}
+/**
+ * Characters a shell would act on. The line breaks matter as much as the operators: a newline
+ * splits one command into two, which is the shape an injected argument usually takes.
+ */
+const SHELL_METACHARACTER = /[;&|`$(){}<>\n\r]/;
+/**
+ * ADR 0007, enforced rather than documented. A standard that lives only in prose decays into
+ * prose; these are the parts a machine can check.
+ */
+export function checkDelegationCompliance(adapters) {
+    const problems = [];
+    const known = new Set();
+    for (const adapter of adapters)
+        known.add(adapter.id);
+    for (const adapter of adapters) {
+        const invoke = adapter.invoke;
+        if (!invoke)
+            continue;
+        const at = `${adapter.id}.invoke`;
+        // §3 — the prompt has to reach the tool somehow.
+        const carriesPrompt = invoke.args.some((arg) => arg.includes('{prompt}'));
+        if (invoke.promptVia === 'arg' && !carriesPrompt) {
+            problems.push(`${at}: promptVia "arg" but no argument contains {prompt}`);
+        }
+        if (invoke.promptVia === 'stdin' && carriesPrompt) {
+            problems.push(`${at}: promptVia "stdin" but an argument also contains {prompt}`);
+        }
+        // §4 — a placeholder URL is worse than none; it looks verified.
+        if (!/^https?:\/\/[^\s]+\.[^\s]+/.test(invoke.verified)) {
+            problems.push(`${at}: verified must be a real vendor documentation URL`);
+        }
+        if (invoke.modelFlag.length > 0 && !invoke.modelFlag.some((arg) => arg.includes('{model}'))) {
+            problems.push(`${at}: modelFlag is set but no argument contains {model}`);
+        }
+        // §7 — the dispatcher passes argv, so a flag carrying a shell metacharacter is either a
+        // mistake or an injection attempt.
+        for (const arg of [...invoke.args, ...invoke.autoApprove, ...invoke.modelFlag]) {
+            if (SHELL_METACHARACTER.test(arg.replace(/\{prompt\}|\{model\}/g, ''))) {
+                problems.push(`${at}: argument "${arg}" contains a shell metacharacter`);
+            }
+        }
+        // The binary was never checked, only the flags. `execFile` with shell:false would treat
+        // `probe; rm -rf /` as one absurd filename rather than running it, so this is not a live
+        // injection — but it is invalid data, and the one field whose value becomes a process is
+        // the last one that should go unvalidated.
+        if (SHELL_METACHARACTER.test(invoke.binary) || /\s/.test(invoke.binary)) {
+            problems.push(`${at}: binary "${invoke.binary}" is not a plain command name. ` +
+                `It is resolved on PATH and spawned without a shell, so it must be one executable.`);
+        }
+        // §9 — a successor must exist, or the deprecation note points nowhere.
+        const successor = invoke.deprecated?.successor;
+        if (successor && !known.has(successor)) {
+            problems.push(`${at}: deprecated.successor "${successor}" is not an adapter`);
+        }
+    }
+    return problems;
+}
+/**
+ * The governing rule, enforced mechanically: a tool that reads AGENTS.md natively must not
+ * be handed a second instruction file, because two sources of truth drift apart.
+ */
+export function checkGoverningRule(adapters) {
+    const violations = [];
+    for (const adapter of adapters) {
+        if (!adapter.readsAgentsMd)
+            continue;
+        for (const output of adapter.outputs) {
+            if (output.kind === 'instructions' || output.mode === 'wrapper') {
+                violations.push(`${adapter.id}: reads AGENTS.md natively but emits "${output.path}" ` +
+                    `(kind=${output.kind}, mode=${output.mode}) — that duplicates the source of truth`);
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * A declared capability with nothing behind it is a promise the adapter does not keep.
+ *
+ * "Behind it" means either a static output in the adapter, or registry items of that kind
+ * targeting it — commands, hooks, skills, and subagents are supplied by the registry, not
+ * enumerated per adapter. And `instructions` is satisfied by AGENTS.md itself for a native
+ * reader, where emitting a file would violate the governing rule.
+ */
+export function checkCapabilityCoverage(adapters, registry = []) {
+    const kindForCapability = {
+        'slash-commands': 'command',
+        subagents: 'agent',
+        hooks: 'hook',
+        skills: 'skill',
+    };
+    const items = [...registry];
+    const gaps = [];
+    for (const adapter of adapters) {
+        for (const capability of adapter.capabilities) {
+            // Three valid ways to honour "instructions": read AGENTS.md natively, emit a wrapper
+            // file, or ship config that points the tool at AGENTS.md (aider's `read:`).
+            if (capability === 'instructions') {
+                const honoured = adapter.readsAgentsMd ||
+                    adapter.outputs.some((o) => o.kind === 'instructions' || o.kind === 'settings');
+                if (!honoured) {
+                    gaps.push(`${adapter.id}: claims "instructions" but nothing points the tool at AGENTS.md`);
+                }
+                continue;
+            }
+            const kind = kindForCapability[capability];
+            if (!kind)
+                continue;
+            const hasStatic = adapter.outputs.some((o) => o.kind === kind);
+            const hasRegistry = items.some((i) => i.kind === kind && i.targets.includes(adapter.id));
+            if (!hasStatic && !hasRegistry) {
+                gaps.push(`${adapter.id}: claims "${capability}" but no ${kind} targets it`);
+            }
+        }
+    }
+    return gaps;
+}
+//# sourceMappingURL=agentkit.js.map

package/dist/agentkit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentkit.js","sourceRoot":"","sources":["../src/agentkit.ts"],"names":[],"mappings":"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"}

package/dist/apply.d.ts

@@ -0,0 +1,21 @@
+import type { GroundplanConfig } from './config.js';
+import type { Plan } from './schema.js';
+export interface ApplyOptions {
+    /** Render and stage but do not move into place — used by `groundplan plan --render`. */
+    dryRun?: boolean;
+    skipPostApply?: boolean;
+    onProgress?: (message: string) => void;
+}
+/** True when a step that generation depends on failed — the repo is incomplete. */
+export declare function hasRequiredFailure(result: ApplyResult): boolean;
+export interface ApplyResult {
+    written: string[];
+    skipped: string[];
+    postApply: {
+        command: string;
+        ok: boolean;
+        optional: boolean;
+        output: string;
+    }[];
+}
+export declare function apply(plan: Plan, config: GroundplanConfig, options?: ApplyOptions): Promise<ApplyResult>;

package/dist/apply.js

@@ -0,0 +1,135 @@
+/**
+ * Apply phase. Only runs against an already-reviewed plan, and writes to a staging
+ * directory first so a mid-way failure cannot leave a half-generated repo behind.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { NOTICE_FILE } from './license.js';
+import { mergeContent } from './merge.js';
+import { renderContent } from './tokens.js';
+const runShell = promisify(exec);
+/** True when a step that generation depends on failed — the repo is incomplete. */
+export function hasRequiredFailure(result) {
+    return result.postApply.some((step) => !step.ok && !step.optional);
+}
+/** Extensions whose syntax collides with the token grammar; copied byte-for-byte. */
+const RAW_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.svg',
+    '.woff', '.woff2', '.ttf', '.eot',
+    '.pdf', '.zip', '.gz', '.jar', '.dll', '.so', '.dylib',
+]);
+export async function apply(plan, config, options = {}) {
+    const staging = await fs.mkdtemp(path.join(path.dirname(plan.target), '.groundplan-staging-'));
+    const written = [];
+    const skipped = [];
+    try {
+        for (const file of plan.files) {
+            if (file.action === 'skip' && (await exists(path.join(plan.target, file.path)))) {
+                skipped.push(file.path);
+                continue;
+            }
+            const destination = path.join(staging, file.path);
+            await fs.mkdir(path.dirname(destination), { recursive: true });
+            if (RAW_EXTENSIONS.has(path.extname(file.source).toLowerCase())) {
+                await fs.copyFile(file.source, destination);
+            }
+            else {
+                const rendered = renderContent(await fs.readFile(file.source, 'utf8'), plan.variables, file.source);
+                const content = file.action === 'merge'
+                    ? await mergeInto(destination, rendered, file.source, (m) => options.onProgress?.(`re-pins ${m} (${file.fromBlueprint})`))
+                    : rendered;
+                await fs.writeFile(destination, content, 'utf8');
+            }
+            written.push(file.path);
+            options.onProgress?.(file.path);
+        }
+        // Generated, not templated — attribution that depends on a template author remembering
+        // is attribution that goes missing.
+        if (plan.notice) {
+            await fs.writeFile(path.join(staging, NOTICE_FILE), plan.notice, 'utf8');
+            written.push(NOTICE_FILE);
+        }
+        if (options.dryRun)
+            return { written, skipped, postApply: [] };
+        await fs.mkdir(plan.target, { recursive: true });
+        await merge(staging, plan.target);
+        const postApply = options.skipPostApply ? [] : await runPostApply(plan, config, options);
+        return { written, skipped, postApply };
+    }
+    finally {
+        await fs.rm(staging, { recursive: true, force: true });
+    }
+}
+/**
+ * Folds a layer's fragment into a file the base already staged — for every stack, not only
+ * the JSON ones. The format is inferred from the destination; see merge.ts for why each
+ * merger edits surgically instead of round-tripping through a parser.
+ */
+async function mergeInto(destination, rendered, source, onConflict) {
+    const existing = await fs.readFile(destination, 'utf8').catch(() => null);
+    if (existing === null)
+        return rendered;
+    return mergeContent(existing, rendered, { source, destination, onConflict });
+}
+async function merge(from, to) {
+    for (const entry of await fs.readdir(from, { withFileTypes: true })) {
+        const source = path.join(from, entry.name);
+        const destination = path.join(to, entry.name);
+        if (entry.isDirectory()) {
+            await fs.mkdir(destination, { recursive: true });
+            await merge(source, destination);
+        }
+        else {
+            await fs.rename(source, destination).catch(async (error) => {
+                // rename fails across volumes; fall back to copy.
+                if (error.code !== 'EXDEV')
+                    throw error;
+                await fs.copyFile(source, destination);
+            });
+        }
+    }
+}
+async function runPostApply(plan, config, options) {
+    const results = [];
+    for (const step of plan.postApply) {
+        options.onProgress?.(`$ ${step.run}`);
+        try {
+            // Passed whole to the shell rather than pre-split: splitting on whitespace and letting
+            // the shell rejoin mangles any quoted argument (`npm pkg set x="a b"`).
+            //
+            // Safe because no user value reaches this string: `ShellStep` in schema.ts rejects a
+            // token outright, so a rendered postApply cannot be introduced by accident. The target
+            // directory is passed as `cwd`, never interpolated. Both are load-bearing — see the
+            // injection tests in __tests__/security.test.ts.
+            const { stdout, stderr } = await runShell(step.run, {
+                cwd: plan.target,
+                timeout: config.postApplyTimeoutMs,
+            });
+            results.push({ command: step.run, ok: true, optional: step.optional, output: stdout || stderr });
+        }
+        catch (error) {
+            // Files are never discarded — a failed install should not throw away a generated repo.
+            // But a required step that failed leaves the repo incomplete, and the caller must be
+            // able to tell that apart from an optional convenience step.
+            results.push({
+                command: step.run,
+                ok: false,
+                optional: step.optional,
+                output: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return results;
+}
+async function exists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=apply.js.map