@ykdz/template 0.0.23 → 0.0.25

package/node_modules/@ykdz/template-builtin-presets/dist/src/foundation.js

@@ -0,0 +1,804 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { collectGeneratedManifestCatalogReferences, selectTemplateDependencyCatalogEntries, } from "@ykdz/template-core/dependency-catalog";
+import { browserTestToolLayer } from "@ykdz/template-core/devcontainer";
+import { editorCustomizationForCapabilities, loadEditorCustomizationDeclarations, } from "@ykdz/template-core/editor-customization";
+import { checkEnvironmentNeedFact, checkEnvironmentNeedFromFact, deploymentEnvironmentNeedFact, deploymentEnvironmentNeedFromFact, renderDeploymentCheckCommand, renderFixCommand, renderRootCheckCommand, } from "@ykdz/template-core/module-graph";
+import { assertPackageContribution, } from "@ykdz/template-core/package-contribution";
+import { assertProjectBlueprintV2, validateProjectBlueprintV2 as validateCoreProjectBlueprintV2, } from "@ykdz/template-core/project-blueprint-v2";
+import { projectCheckWorkflowTemplateReplacements, projectDependabotTemplateReplacements, } from "@ykdz/template-core/project-github";
+import { planExplicitProjectLinks } from "@ykdz/template-core/project-linking-v2";
+import { resolveTemplateSource, } from "@ykdz/template-core/renderer";
+import { rustBinDefinition } from "./rust-bin/definition.js";
+import { vuePnpmDependencyOverrides } from "./shared/vue.js";
+import { templateSources } from "./template-sources.js";
+import { tsLibDefinition } from "./ts-lib/definition.js";
+import { vikeAppDefinition } from "./vike-app/definition.js";
+import { vueAppDefinition } from "./vue-app/definition.js";
+import { vueHonoAppDefinition } from "./vue-hono-app/definition.js";
+const environmentNeedsPath = ".template/environment-needs.json";
+/**
+ * The Foundation persists the non-rendering half of every Package
+ * Contribution with the Generated Repository.  Package Addition cannot infer
+ * fix, deployment, or maintenance semantics from a package name (or
+ * from a lossy subset of scripts), so this is the durable topology it reads.
+ */
+/** Resolve an owned source handle for diagnostics and source checks. */
+export function resolveBuiltInTemplateSource(source, relativePath) {
+    return resolveTemplateSource(source, relativePath);
+}
+export function validateProjectBlueprintV2(value) {
+    return validateCoreProjectBlueprintV2(value);
+}
+class PresetRegistry {
+    #definitions;
+    constructor(definitions) {
+        const names = definitions.map((definition) => definition.metadata.name);
+        if (names.some((name) => name.length === 0) ||
+            new Set(names).size !== names.length) {
+            throw new Error("Preset Registry requires unique non-empty Definition names");
+        }
+        this.#definitions = [...definitions].toSorted((left, right) => left.metadata.name.localeCompare(right.metadata.name));
+    }
+    all() {
+        return this.#definitions;
+    }
+    require(name) {
+        const definition = this.#definitions.find((item) => item.metadata.name === name);
+        if (!definition)
+            throw new Error(`Unknown Built-in Preset: ${name}`);
+        return definition;
+    }
+}
+export const builtInPresetRegistry = new PresetRegistry([
+    tsLibDefinition,
+    rustBinDefinition,
+    vueAppDefinition,
+    vueHonoAppDefinition,
+    vikeAppDefinition,
+]);
+/** Registry-derived Template Source roots checked independently of render plans. */
+export function builtInPresetTemplateSourceContexts() {
+    return [
+        ...builtInPresetRegistry.all().map((definition) => ({
+            name: definition.metadata.name,
+            root: resolveBuiltInTemplateSource(definition.source, "."),
+        })),
+        {
+            name: "foundation",
+            root: resolveBuiltInTemplateSource(templateSources.foundation, "."),
+        },
+        {
+            name: "shared-devcontainer",
+            root: resolveBuiltInTemplateSource(templateSources.sharedDevcontainer, "."),
+        },
+        {
+            name: "shared-oxc",
+            root: resolveBuiltInTemplateSource(templateSources.sharedOxc, "."),
+        },
+        {
+            name: "shared-vue",
+            root: resolveBuiltInTemplateSource(templateSources.vue, "."),
+        },
+    ];
+}
+/**
+ * Derives direct Template Source checks from every registered Definition's
+ * actual initial contributions, without maintaining a second Preset catalog.
+ */
+export function builtInPresetTemplateSourceCheckContexts() {
+    return builtInPresetRegistry.all().flatMap((definition) => {
+        const context = createGenerationContext({
+            targetDir: path.join("generated-repository", "template-source", definition.metadata.name),
+            toolchain: { nodeLtsMajor: "24", packageManagerPin: "pnpm@11.11.0" },
+        });
+        const plan = planGeneratedRepositoryInitialization({ definition, context });
+        const contributions = definition.planInitializationContributions?.(context) ?? [definition.planInitialization(context)];
+        return contributions.map((contribution) => ({
+            definition,
+            contribution,
+            plan,
+        }));
+    });
+}
+export function createGenerationContext(options) {
+    const projectName = path.basename(path.resolve(options.targetDir));
+    return {
+        targetDir: options.targetDir,
+        projectName,
+        scope: options.scope ?? projectName,
+        toolchain: options.toolchain,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function environmentNeedOwner(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (value.kind === "workspace-orchestration" && value.path === ".") {
+        return { kind: "workspace-orchestration", path: "." };
+    }
+    if (value.kind === "package-boundary" && typeof value.path === "string") {
+        return { kind: "package-boundary", path: value.path };
+    }
+    return undefined;
+}
+function persistedCheckEnvironmentNeedFact(value) {
+    if (!isRecord(value))
+        return undefined;
+    const owner = environmentNeedOwner(value.owner);
+    if (owner === undefined)
+        return undefined;
+    switch (value.kind) {
+        case "playwright-browser-assets":
+            return value.browser === "chromium"
+                ? { kind: value.kind, browser: value.browser, owner }
+                : undefined;
+        case "shellcheck-command":
+            return { kind: value.kind, owner };
+        case "rust-toolchain":
+            return value.toolchain === "stable"
+                ? { kind: value.kind, toolchain: value.toolchain, owner }
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+function readPersistedEnvironmentNeeds(targetDir) {
+    const filePath = path.join(targetDir, environmentNeedsPath);
+    if (!existsSync(filePath)) {
+        throw new Error(`Package Addition requires explicit Check Environment Need facts: ${environmentNeedsPath} is missing`);
+    }
+    let value;
+    try {
+        value = JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Package Addition requires valid Check Environment Need facts: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(value) ||
+        value.schemaVersion !== 1 ||
+        !Array.isArray(value.check) ||
+        !Array.isArray(value.deployment)) {
+        throw new Error(`Package Addition requires valid Check Environment Need facts in ${environmentNeedsPath}`);
+    }
+    const check = value.check.map(persistedCheckEnvironmentNeedFact);
+    if (check.some((fact) => fact === undefined)) {
+        throw new Error(`Package Addition requires supported Check Environment Need facts in ${environmentNeedsPath}`);
+    }
+    if (value.deployment.some((fact) => !isRecord(fact) || fact.kind !== "docker-engine")) {
+        throw new Error(`Package Addition requires supported deployment Environment Need facts in ${environmentNeedsPath}`);
+    }
+    return {
+        check: check.map(checkEnvironmentNeedFromFact),
+        deployment: value.deployment.map((fact) => deploymentEnvironmentNeedFromFact(fact)),
+    };
+}
+function uniqueEnvironmentNeeds(needs) {
+    const seen = new Set();
+    return needs.filter((need) => {
+        const key = JSON.stringify(need);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Package Addition reconstructs generic current facts from the Blueprint,
+ * manifest truth, and explicit persisted Environment Need facts. Environment
+ * preparation is never derived from task script text.
+ */
+function existingPackageContribution(options) {
+    const packageRoot = path.join(options.context.targetDir, options.definition.path);
+    const manifestPath = path.join(packageRoot, "package.json");
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Package Addition requires manifest truth for ${options.definition.path}: package.json is missing`);
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    if (typeof manifest !== "object" ||
+        manifest === null ||
+        Array.isArray(manifest) ||
+        manifest.name !== options.definition.name) {
+        throw new Error(`Package Addition requires manifest truth for ${options.definition.path}: expected name ${options.definition.name}`);
+    }
+    const record = manifest;
+    const dependencyMaintenance = existingDependencyMaintenancePolicy(options.context.targetDir);
+    const environmentNeeds = options.environmentNeeds.filter((need) => need.owner.kind === "package-boundary" &&
+        need.owner.path === options.definition.path);
+    const rust = environmentNeeds.some((need) => need.kind === "rust-toolchain");
+    const editorRecommendationsPath = path.join(options.context.targetDir, ".vscode/extensions.json");
+    const editorRecommendations = existsSync(editorRecommendationsPath)
+        ? JSON.parse(readFileSync(editorRecommendationsPath, "utf8")).recommendations
+        : [];
+    const existingExtensions = Array.isArray(editorRecommendations)
+        ? new Set(editorRecommendations.filter((item) => typeof item === "string"))
+        : new Set();
+    const editorCapabilities = rust
+        ? ["rust-tooling"]
+        : [
+            "oxc-format-lint",
+            ...(existingExtensions.has("Vue.volar") ? ["vue"] : []),
+            ...(existingExtensions.has("bradlc.vscode-tailwindcss")
+                ? ["tailwind"]
+                : []),
+            ...(existingExtensions.has("vitest.explorer")
+                ? ["vitest"]
+                : []),
+        ];
+    return {
+        definition: options.definition,
+        manifest: record,
+        exposure: {
+            exports: typeof record.exports === "object" && record.exports !== null
+                ? record.exports
+                : {},
+            imports: typeof record.imports === "object" && record.imports !== null
+                ? record.imports
+                : {},
+        },
+        operations: [],
+        environmentNeeds,
+        foundation: {
+            toolchains: rust
+                ? { rust: { toolchain: "stable", components: ["rustfmt", "clippy"] } }
+                : {},
+            editorCapabilities,
+            dependencyMaintenance: {
+                ...dependencyMaintenance,
+            },
+        },
+    };
+}
+/**
+ * Dependabot is the Foundation-owned durable declaration of maintenance
+ * coverage. Package Addition reads it back so rebuilding root policy cannot
+ * silently discard a base repository's non-default directories.
+ */
+function existingDependencyMaintenancePolicy(targetDir) {
+    const dependabotPath = path.join(targetDir, ".github/dependabot.yml");
+    if (!existsSync(dependabotPath)) {
+        throw new Error("Package Addition requires maintenance truth: .github/dependabot.yml is missing");
+    }
+    const ecosystems = [];
+    const directories = {};
+    const extraDirectories = {};
+    const supportedEcosystems = new Set([
+        "npm",
+        "cargo",
+        "github-actions",
+        "docker",
+        "rust-toolchain",
+    ]);
+    let ecosystem;
+    for (const line of readFileSync(dependabotPath, "utf8").split("\n")) {
+        const ecosystemMatch = /^\s*- package-ecosystem: (\S+)\s*$/u.exec(line);
+        if (ecosystemMatch) {
+            if (!supportedEcosystems.has(ecosystemMatch[1])) {
+                throw new Error(`Package Addition requires supported Dependabot ecosystems: ${ecosystemMatch[1]}`);
+            }
+            ecosystem = ecosystemMatch[1];
+            if (!ecosystems.includes(ecosystem))
+                ecosystems.push(ecosystem);
+            continue;
+        }
+        const directoryMatch = /^\s+directory: "?(\/[^"\s]*)"?\s*$/u.exec(line);
+        if (!directoryMatch || ecosystem === undefined)
+            continue;
+        const directory = directoryMatch[1];
+        if (directories[ecosystem] === undefined) {
+            directories[ecosystem] = directory;
+        }
+        else {
+            (extraDirectories[ecosystem] ??= []).push(directory);
+        }
+    }
+    if (ecosystems.length === 0) {
+        throw new Error("Package Addition requires maintenance truth: .github/dependabot.yml has no update entries");
+    }
+    return {
+        ecosystems,
+        directories,
+        ...(Object.keys(extraDirectories).length === 0 ? {} : { extraDirectories }),
+        interval: "weekly",
+    };
+}
+function devcontainerDockerfileOperations(options) {
+    const hasBrowserTests = options.environmentNeeds.some((need) => need.kind === "playwright-browser-assets");
+    const hasShellChecks = options.environmentNeeds.some((need) => need.kind === "shellcheck-command");
+    const browserLayer = hasBrowserTests ? browserTestToolLayer() : undefined;
+    return [
+        {
+            kind: "writeTextTemplate",
+            source: templateSources.foundation,
+            from: "devcontainer.json",
+            to: ".devcontainer/devcontainer.json",
+            replacements: {
+                PROJECT_NAME: options.context.projectName,
+                NODE_LTS_MAJOR: options.context.toolchain.nodeLtsMajor,
+                PACKAGE_MANAGER_PIN: options.context.toolchain.packageManagerPin,
+                PLAYWRIGHT_CLI_PACKAGE: browserLayer?.playwrightCliPackage ?? "unused",
+            },
+        },
+        {
+            kind: "writeTextFromFragments",
+            to: ".devcontainer/Dockerfile",
+            fragments: [
+                {
+                    source: templateSources.sharedDevcontainer,
+                    from: "node-pnpm.Dockerfile",
+                },
+                ...(browserLayer === undefined
+                    ? []
+                    : [
+                        {
+                            source: templateSources.sharedDevcontainer,
+                            from: "browser-test.Dockerfile",
+                        },
+                    ]),
+                ...(hasShellChecks
+                    ? [
+                        {
+                            source: templateSources.sharedDevcontainer,
+                            from: "shellcheck.Dockerfile",
+                        },
+                    ]
+                    : []),
+            ],
+        },
+    ];
+}
+function foundationPlan(options) {
+    assertProjectBlueprintV2(options.blueprint);
+    const environmentNeeds = uniqueEnvironmentNeeds(options.contributions.flatMap((item) => item.environmentNeeds));
+    const deploymentEnvironmentNeeds = uniqueEnvironmentNeeds([
+        ...(options.existingDeploymentEnvironmentNeeds ?? []),
+        ...options.contributions.flatMap((item) => item.deploymentEnvironmentNeeds ?? []),
+    ]);
+    const persistedEnvironmentNeeds = {
+        schemaVersion: 1,
+        check: environmentNeeds.map(checkEnvironmentNeedFact),
+        deployment: deploymentEnvironmentNeeds.map(deploymentEnvironmentNeedFact),
+    };
+    const hasDeploymentTask = options.contributions.some((contribution) => {
+        const scripts = contribution.manifest.scripts;
+        return (typeof scripts === "object" &&
+            scripts !== null &&
+            typeof scripts.deployment === "string");
+    });
+    const packagePaths = options.contributions.map((contribution) => contribution.definition.path);
+    if (new Set(packagePaths).size !== packagePaths.length)
+        throw new Error("Package Contributions must have unique Package Paths");
+    const packageNames = options.contributions.map((contribution) => contribution.definition.name);
+    if (new Set(packageNames).size !== packageNames.length)
+        throw new Error("Package Contributions must have unique package names");
+    const rustToolchain = options.contributions
+        .map((contribution) => contribution.foundation.toolchains.rust)
+        .find((toolchain) => toolchain !== undefined);
+    if (options.contributions.some((contribution) => contribution.foundation.toolchains.rust !== undefined &&
+        contribution.foundation.toolchains.rust !== rustToolchain)) {
+        throw new Error("Foundation requires one coordinated Rust toolchain");
+    }
+    const workspacePackageGlobs = [
+        "apps/*",
+        "packages/*",
+        ...new Set([
+            ...options.blueprint.packages
+                .map((definition) => `${definition.path.split("/")[0]}/*`)
+                .filter((glob) => glob !== "apps/*" && glob !== "packages/*"),
+            ...options.contributions
+                .flatMap((contribution) => contribution.foundation.workspacePackageGlobs ?? [])
+                .filter((glob) => glob !== "apps/*" && glob !== "packages/*"),
+        ]),
+    ];
+    const editorCustomization = editorCustomizationForCapabilities(options.contributions.flatMap((contribution) => contribution.foundation.editorCapabilities), loadEditorCustomizationDeclarations(resolveTemplateSource(templateSources.editorCustomization, "capabilities.json")));
+    const dependencyMaintenancePolicy = {
+        ecosystems: [
+            ...new Set(options.contributions.flatMap((contribution) => contribution.foundation.dependencyMaintenance.ecosystems)),
+        ],
+        directories: Object.assign({}, ...options.contributions.map((contribution) => contribution.foundation.dependencyMaintenance.directories ?? {})),
+        extraDirectories: Object.assign({}, ...options.contributions.map((contribution) => contribution.foundation.dependencyMaintenance.extraDirectories ?? {})),
+        interval: "weekly",
+    };
+    const rootManifest = {
+        name: options.context.projectName,
+        version: "0.0.0",
+        private: true,
+        type: "module",
+        scripts: {
+            check: renderRootCheckCommand(),
+            boundaries: "node scripts/check-boundaries.ts",
+            ...(hasDeploymentTask
+                ? { "check:deployment": renderDeploymentCheckCommand() }
+                : {}),
+            fix: renderFixCommand(),
+            "format:check": "node scripts/run-root-owned-task.ts format:check",
+            "format:write": "node scripts/run-root-owned-task.ts format:write",
+            lint: "node scripts/run-root-owned-task.ts lint",
+            "lint:fix": "node scripts/run-root-owned-task.ts lint:fix",
+            typecheck: "tsc -p tsconfig.json --noEmit --pretty false",
+        },
+        devDependencies: {
+            "@types/node": "catalog:",
+            oxfmt: "catalog:",
+            oxlint: "catalog:",
+            "oxlint-tsgolint": "catalog:",
+            turbo: "catalog:",
+            "typescript-7": "catalog:",
+        },
+        engines: { node: options.context.toolchain.nodeLtsMajor },
+        packageManager: options.context.toolchain.packageManagerPin,
+    };
+    const dependencyCatalog = selectTemplateDependencyCatalogEntries(collectGeneratedManifestCatalogReferences([
+        ...options.contributions.map((contribution) => contribution.manifest),
+        rootManifest,
+    ]));
+    const dependencyOverrides = {
+        ...(Object.hasOwn(dependencyCatalog, "vue") ||
+            Object.hasOwn(dependencyCatalog, "pinia")
+            ? vuePnpmDependencyOverrides
+            : {}),
+    };
+    const requiresCoordinatedWorkspaceRefresh = true;
+    const workspaceOperation = requiresCoordinatedWorkspaceRefresh
+        ? {
+            kind: "writeTextTemplate",
+            source: templateSources.foundation,
+            from: "pnpm-workspace.dynamic.txt",
+            to: "pnpm-workspace.yaml",
+            replacements: {
+                WORKSPACE_PACKAGE_GLOBS: workspacePackageGlobs
+                    .map((glob) => `  - ${glob}`)
+                    .join("\n"),
+                DEPENDENCY_CATALOG: Object.entries(dependencyCatalog)
+                    .toSorted(([left], [right]) => left.localeCompare(right))
+                    .map(([name, version]) => `  ${JSON.stringify(name)}: ${String(version)}`)
+                    .join("\n"),
+                DEPENDENCY_OVERRIDES_SECTION: Object.keys(dependencyOverrides).length === 0
+                    ? ""
+                    : [
+                        "",
+                        "overrides:",
+                        ...Object.entries(dependencyOverrides)
+                            .toSorted(([left], [right]) => left.localeCompare(right))
+                            .map(([dependency, version]) => `  ${JSON.stringify(dependency)}: ${JSON.stringify(version)}`),
+                        "",
+                    ].join("\n"),
+            },
+            ...(options.mode === "addition" ? { overwrite: true } : {}),
+        }
+        : {
+            kind: "copyFile",
+            source: templateSources.foundation,
+            from: "pnpm-workspace.yaml",
+            to: "pnpm-workspace.yaml",
+        };
+    const workflowOperation = {
+        kind: "writeTextTemplate",
+        source: templateSources.foundation,
+        from: ".github/workflows/check.dynamic.template",
+        to: ".github/workflows/check.yml",
+        replacements: projectCheckWorkflowTemplateReplacements({
+            environment: { needs: environmentNeeds },
+            deploymentEnvironmentNeeds,
+            hasDeploymentTask,
+        }),
+        ...(options.mode === "addition" ? { overwrite: true } : {}),
+    };
+    const workflowOperations = [
+        workflowOperation,
+        {
+            kind: "writeTextTemplate",
+            source: templateSources.foundation,
+            from: ".github/dependabot.dynamic.template",
+            to: ".github/dependabot.yml",
+            replacements: projectDependabotTemplateReplacements(dependencyMaintenancePolicy),
+            ...(options.mode === "addition" ? { overwrite: true } : {}),
+        },
+    ];
+    const projectLinkPlan = planExplicitProjectLinks({
+        blueprint: options.blueprint,
+        contributions: options.contributions,
+    });
+    const initializationFoundationOperations = [
+        { kind: "writeJson", to: "package.json", value: rootManifest },
+        workspaceOperation,
+        {
+            kind: "copyFile",
+            source: templateSources.foundation,
+            from: "gitignore",
+            to: ".gitignore",
+        },
+        {
+            kind: "copyFile",
+            source: templateSources.foundation,
+            from: "turbo.json",
+            to: "turbo.json",
+        },
+        {
+            kind: "copyFile",
+            source: templateSources.foundation,
+            from: "scripts/check-boundaries.ts",
+            to: "scripts/check-boundaries.ts",
+        },
+        {
+            kind: "copyFile",
+            source: templateSources.foundation,
+            from: "scripts/run-root-owned-task.ts",
+            to: "scripts/run-root-owned-task.ts",
+        },
+        {
+            kind: "copyFile",
+            source: templateSources.foundation,
+            from: "tsconfig.json",
+            to: "tsconfig.json",
+        },
+        {
+            kind: "copyFile",
+            source: templateSources.sharedOxc,
+            from: "tsconfig.config.json",
+            to: "tsconfig.config.json",
+        },
+        {
+            kind: "copyFile",
+            source: templateSources.sharedOxc,
+            from: "node/oxlint.config.ts",
+            to: "oxlint.config.ts",
+        },
+        {
+            kind: "copyFile",
+            source: templateSources.sharedOxc,
+            from: "oxfmt.config.ts",
+            to: "oxfmt.config.ts",
+        },
+        {
+            kind: "writeJson",
+            to: ".vscode/extensions.json",
+            value: { recommendations: editorCustomization.extensions },
+            ...(editorCustomization.extensions.length > 2
+                ? { multilineArrays: ["recommendations"] }
+                : {}),
+        },
+        {
+            kind: "writeJson",
+            to: ".vscode/settings.json",
+            value: editorCustomization.settings,
+        },
+        ...(rustToolchain === undefined
+            ? [
+                ...devcontainerDockerfileOperations({
+                    context: options.context,
+                    environmentNeeds,
+                }),
+            ]
+            : [
+                {
+                    kind: "writeTextTemplate",
+                    source: templateSources.foundation,
+                    from: "rust/rust-toolchain.toml",
+                    to: "rust-toolchain.toml",
+                    replacements: { RUST_TOOLCHAIN: rustToolchain.toolchain },
+                },
+                {
+                    kind: "writeTextTemplate",
+                    source: templateSources.foundation,
+                    from: "rust/devcontainer/devcontainer.json",
+                    to: ".devcontainer/devcontainer.json",
+                    replacements: {
+                        PROJECT_NAME: options.context.projectName,
+                        NODE_LTS_MAJOR: options.context.toolchain.nodeLtsMajor,
+                        PACKAGE_MANAGER_PIN: options.context.toolchain.packageManagerPin,
+                        RUST_TOOLCHAIN: rustToolchain.toolchain,
+                    },
+                },
+                {
+                    kind: "writeTextFromFragments",
+                    to: ".devcontainer/Dockerfile",
+                    fragments: [
+                        {
+                            source: templateSources.sharedDevcontainer,
+                            from: "node-pnpm.Dockerfile",
+                        },
+                        {
+                            source: templateSources.foundation,
+                            from: "rust/devcontainer/rust.Dockerfile",
+                        },
+                        ...(environmentNeeds.some((need) => need.kind === "playwright-browser-assets")
+                            ? [
+                                {
+                                    source: templateSources.sharedDevcontainer,
+                                    from: "browser-test.Dockerfile",
+                                },
+                            ]
+                            : []),
+                        ...(environmentNeeds.some((need) => need.kind === "shellcheck-command")
+                            ? [
+                                {
+                                    source: templateSources.sharedDevcontainer,
+                                    from: "shellcheck.Dockerfile",
+                                },
+                            ]
+                            : []),
+                    ],
+                },
+            ]),
+        ...workflowOperations,
+        {
+            kind: "writeJson",
+            to: ".template/blueprint.json",
+            value: options.blueprint,
+        },
+        {
+            kind: "writeJson",
+            to: environmentNeedsPath,
+            value: persistedEnvironmentNeeds,
+        },
+        {
+            kind: "writeJson",
+            to: ".template/generation.json",
+            value: {
+                preset: options.definition.metadata.name,
+                templateVersion: "0.0.0",
+                toolchain: options.context.toolchain,
+            },
+        },
+    ];
+    const refreshFoundationOperation = (operation) => {
+        switch (operation.kind) {
+            case "copyFile":
+            case "writeTextTemplate":
+            case "writeTextFromFragments":
+            case "writeJson":
+                return { ...operation, overwrite: true };
+            case "mergeJson":
+            case "replaceAnchors":
+            case "setExecutable":
+            case "writeText":
+                return operation;
+        }
+    };
+    const plannedFoundationOperations = options.mode === "addition"
+        ? initializationFoundationOperations
+            .filter((operation) => !("to" in operation &&
+            operation.to === ".template/generation.json"))
+            .map(refreshFoundationOperation)
+        : initializationFoundationOperations;
+    const linkOperations = [
+        ...projectLinkPlan.manifestDependenciesByPackagePath,
+    ].map(([packagePath, dependencies]) => ({
+        kind: "mergeJson",
+        to: `${packagePath}/package.json`,
+        value: { dependencies },
+        multilineArrays: ["files"],
+    }));
+    const contributionProvenance = {
+        definitionName: options.definition.metadata.name,
+        plannerSourceFile: options.definition.plannerSourceFile,
+        planningContribution: options.mode === "addition"
+            ? "planPackageAddition"
+            : "planInitialization",
+        ownershipRule: "Package Contribution may write only its owned Package Boundary",
+    };
+    const foundationProvenance = {
+        definitionName: options.definition.metadata.name,
+        plannerSourceFile: fileURLToPath(import.meta.url),
+        planningContribution: "foundationPlan",
+        ownershipRule: "Foundation owns coordinated root outputs",
+    };
+    const withProvenance = (operation, provenance) => ({ ...operation, provenance });
+    const operations = [
+        ...(options.renderContributions ?? options.contributions)
+            .map((item) => assertPackageContribution(item, {
+            definitionName: options.definition.metadata.name,
+            planner: options.mode === "addition"
+                ? "planPackageAddition"
+                : "planInitialization",
+        }))
+            .flatMap((item) => item.operations.map((operation) => operation.kind === "writeJson" &&
+            operation.to.endsWith("/package.json")
+            ? { ...operation, value: item.manifest }
+            : operation))
+            .map((operation) => withProvenance(operation, contributionProvenance)),
+        ...plannedFoundationOperations.map((operation) => withProvenance(operation, foundationProvenance)),
+        ...linkOperations.map((operation) => withProvenance(operation, foundationProvenance)),
+    ];
+    return {
+        definitionName: options.definition.metadata.name,
+        plannerSourceFile: options.definition.plannerSourceFile,
+        planningContribution: options.mode === "addition"
+            ? "planPackageAddition"
+            : "planInitialization",
+        blueprint: options.blueprint,
+        generationRecord: {
+            preset: options.definition.metadata.name,
+            templateVersion: "0.0.0",
+            toolchain: options.context.toolchain,
+        },
+        operations,
+        environmentNeeds,
+        deploymentEnvironmentNeeds,
+        manifests: [
+            ...options.contributions.map((item) => item.manifest),
+            rootManifest,
+        ],
+        dependencyCatalog,
+        dependencyMaintenancePolicy,
+        nextStepInstructions: [
+            { display: "pnpm install" },
+            ...environmentNeeds.map((need) => ({ display: need.nextStep.display })),
+            { display: "pnpm run fix" },
+            { display: "pnpm run check" },
+        ],
+    };
+}
+export function planGeneratedRepositoryInitialization(options) {
+    const blueprint = options.definition.blueprint(options.context);
+    return foundationPlan({
+        definition: options.definition,
+        context: options.context,
+        blueprint,
+        contributions: options.definition.planInitializationContributions?.(options.context) ?? [options.definition.planInitialization(options.context)],
+        mode: "initialization",
+    });
+}
+export function planGeneratedRepositoryPackageAddition(options) {
+    assertProjectBlueprintV2(options.blueprint);
+    if (!options.definition.planPackageAddition)
+        throw new Error(`Built-in Preset ${options.definition.metadata.name} does not support Package Addition`);
+    const packagePath = options.packagePath ??
+        options.definition.defaultPackagePath?.({
+            context: options.context,
+            packageLeafName: options.packageLeafName,
+        });
+    if (packagePath === undefined) {
+        throw new Error(`Built-in Preset ${options.definition.metadata.name} must own a default Package Path or receive an explicit Package Path`);
+    }
+    const contribution = options.definition.planPackageAddition({
+        context: options.context,
+        packageLeafName: options.packageLeafName,
+        packagePath,
+    });
+    const conflictingPackage = options.blueprint.packages.find((existing) => existing.name === contribution.definition.name ||
+        existing.path === contribution.definition.path);
+    if (conflictingPackage !== undefined) {
+        throw new Error(`Package Addition conflicts with existing Package Definition ${conflictingPackage.name} at ${conflictingPackage.path}`);
+    }
+    const blueprint = {
+        ...options.blueprint,
+        packages: [...options.blueprint.packages, contribution.definition],
+        ...(options.linkFrom && options.linkFrom.length > 0
+            ? {
+                packageLinkIntents: [
+                    ...(options.blueprint.packageLinkIntents ?? []),
+                    ...[...new Set(options.linkFrom)].map((consumerPackagePath) => ({
+                        consumerPackagePath,
+                        providerPackagePath: contribution.definition.path,
+                    })),
+                ],
+            }
+            : {}),
+    };
+    assertProjectBlueprintV2(blueprint);
+    const persistedEnvironmentNeeds = readPersistedEnvironmentNeeds(options.context.targetDir);
+    const existingContributions = options.blueprint.packages.map((definition) => existingPackageContribution({
+        context: options.context,
+        definition,
+        environmentNeeds: persistedEnvironmentNeeds.check,
+    }));
+    if (existingContributions.length !== options.blueprint.packages.length ||
+        existingContributions.some((existing) => !options.blueprint.packages.some((definition) => definition.path === existing.definition.path &&
+            definition.name === existing.definition.name))) {
+        throw new Error("Migration Package Addition check Contributions must match the current Project Blueprint");
+    }
+    return foundationPlan({
+        definition: options.definition,
+        context: options.context,
+        blueprint,
+        contributions: [...existingContributions, contribution],
+        renderContributions: [contribution],
+        existingDeploymentEnvironmentNeeds: persistedEnvironmentNeeds.deployment,
+        mode: "addition",
+    });
+}