@ykdz/template 0.0.33 → 0.0.36

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

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -5,14 +6,17 @@ import { composeCiDiagnosticArtifacts } from "#template-core/ci-diagnostic-artif
 import { collectGeneratedManifestCatalogReferences, selectTemplateDependencyCatalogEntries, } from "#template-core/dependency-catalog";
 import { planDevelopmentContainerToolLayersSync, } from "#template-core/development-container-tool-layer";
 import { editorCustomizationForCapabilities, loadEditorCustomizationDeclarations, } from "#template-core/editor-customization";
-import { checkEnvironmentNeedFact, checkEnvironmentNeedFromFact, deploymentEnvironmentNeedFact, deploymentEnvironmentNeedFromFact, renderDeploymentCheckCommand, renderFixCommand, renderRootCheckCommand, } from "#template-core/module-graph";
-import { assertPackageContribution, } from "#template-core/package-contribution";
-import { assertProjectBlueprintV2, validateProjectBlueprintV2 as validateCoreProjectBlueprintV2, } from "#template-core/project-blueprint-v2";
+import { normalizeEnvironmentNeeds, parseEnvironmentNeedsMetadata, renderDeploymentCheckCommand, renderFixCommand, renderRootCheckCommand, renderTurboRunCommand, } from "#template-core/module-graph";
+import { assertPackageContribution, assertPackageContributionCommandNames, } from "#template-core/package-contribution";
+import { assertProjectBlueprint, assertProjectBlueprintDraft, isValidNewNpmPackageName, validateNewPackagePath, validateProjectBlueprint as validateCoreProjectBlueprint, } from "#template-core/project-blueprint";
 import { projectCheckWorkflowTemplateSource, projectCheckWorkflowTemplateReplacements, projectDependabotTemplateReplacements, } from "#template-core/project-github";
 import { planExplicitProjectLinks } from "#template-core/project-linking-v2";
+import { validateProjectProjectionPlan } from "#template-core/project-projection";
 import { resolveTemplateSource, } from "#template-core/renderer";
+import { isValidDefaultPackageScope, parseGenerationRecord, } from "./generation-record.js";
 import { rustBinDefinition } from "./rust-bin/definition.js";
-import { typescriptConfigContribution, typescriptConfigPackageDefinition, typescriptConfigPackageName, } from "./shared/typescript.js";
+import { githubCliDevelopmentContainerToolLayer } from "./shared/development-container.js";
+import { typescriptConfigContribution, typescriptConfigPackageDefinition, typescriptConfigReplayAdapter, } from "./shared/typescript.js";
 import { vuePnpmDependencyOverrides } from "./shared/vue.js";
 import { templateSources } from "./template-sources.js";
 import { tsCliDefinition } from "./ts-cli/definition.js";
@@ -20,6 +24,7 @@ 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 localTemplateMetadataStateKey = Symbol("localTemplateMetadataState");
 const environmentNeedsPath = ".template/environment-needs.json";
 const packageManifestKeyOrder = [
     "name",
@@ -52,8 +57,8 @@ const packageConditionKeyOrder = ["source", "types", "default"];
 export function resolveBuiltInTemplateSource(source, relativePath) {
     return resolveTemplateSource(source, relativePath);
 }
-export function validateProjectBlueprintV2(value) {
-    return validateCoreProjectBlueprintV2(value);
+export function validateProjectBlueprint(value) {
+    return validateCoreProjectBlueprint(value);
 }
 class PresetRegistry {
     #definitions;
@@ -63,6 +68,14 @@ class PresetRegistry {
             new Set(names).size !== names.length) {
             throw new Error("Preset Registry requires unique non-empty Definition names");
         }
+        for (const definition of definitions) {
+            const adapterIdentities = definition.packageContributionReplayAdapters.map((adapter) => adapter.identity);
+            if (adapterIdentities.length === 0 ||
+                adapterIdentities.some((identity) => identity.length === 0) ||
+                new Set(adapterIdentities).size !== adapterIdentities.length) {
+                throw new Error(`Built-in Preset ${definition.metadata.name} requires unique non-empty Package Contribution replay adapters`);
+            }
+        }
         this.#definitions = [...definitions].toSorted((left, right) => left.metadata.name.localeCompare(right.metadata.name));
     }
     all() {
@@ -83,245 +96,304 @@ export const builtInPresetRegistry = new PresetRegistry([
     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));
+    const repositoryName = path.basename(path.resolve(options.targetDir));
+    const defaultPackageScope = options.defaultPackageScope ?? repositoryName;
     return {
         targetDir: options.targetDir,
-        projectName,
-        scope: options.scope ?? projectName,
+        repositoryName,
+        defaultPackageScope,
+        foundationPackages: {
+            typescriptConfiguration: {
+                name: `@${defaultPackageScope}/typescript-config`,
+            },
+        },
         toolchain: options.toolchain,
     };
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+const packageDefinitionIdDomain = "ykdz.template.package-definition-id.v1";
+function packageDefinitionIdDigest(value) {
+    return `package-${createHash("sha256")
+        .update(JSON.stringify(value))
+        .digest("hex")}`;
+}
+function allocatePackageDefinitionId(options) {
+    const creationFacts = {
+        domain: packageDefinitionIdDomain,
+        definition: {
+            name: options.definition.name,
+            path: options.definition.path,
+            role: options.definition.role,
+        },
+        provenance: {
+            definitionName: options.provenance.definitionName,
+            planningContribution: options.provenance.planningContribution,
+            contributionIdentity: options.provenance.contributionIdentity,
+        },
+    };
+    let nonce = 0;
+    while (true) {
+        const candidate = packageDefinitionIdDigest(nonce === 0
+            ? creationFacts
+            : {
+                creationFacts,
+                occupiedIds: [...options.occupiedIds].toSorted(),
+                nonce,
+            });
+        if (!options.occupiedIds.has(candidate))
+            return candidate;
+        nonce += 1;
+    }
+}
+function persistPackageDefinition(options) {
+    const packageDefinitionId = allocatePackageDefinitionId(options);
+    options.occupiedIds.add(packageDefinitionId);
+    return { ...options.definition, packageDefinitionId };
+}
 function readGenerationRecord(options) {
-    const generationPath = path.join(options.context.targetDir, ".template/generation.json");
-    let value;
+    const generationPath = path.join(options.repositoryRoot, ".template/generation.json");
+    return parseGenerationRecord(readJsonFile(generationPath, "Generation Record facts"));
+}
+function readJsonFile(filePath, label) {
     try {
-        value = JSON.parse(readFileSync(generationPath, "utf8"));
+        return JSON.parse(readFileSync(filePath, "utf8"));
     }
     catch (error) {
-        throw new Error(`Package Addition requires valid Generation Record facts: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (isRecord(value)) {
-        for (const key of Object.keys(value)) {
-            if (![
-                "schemaVersion",
-                "preset",
-                "templateVersion",
-                "toolchain",
-                "packages",
-            ].includes(key)) {
-                throw new Error(`Package Addition Generation Record contains unknown field: ${key}`);
-            }
-        }
-        if (isRecord(value.toolchain)) {
-            for (const key of Object.keys(value.toolchain)) {
-                if (!["nodeLtsMajor", "packageManagerPin"].includes(key)) {
-                    throw new Error(`Package Addition Generation Record toolchain contains unknown field: ${key}`);
-                }
-            }
-        }
+        throw new Error(`Package Addition requires valid ${label}: ${error instanceof Error ? error.message : String(error)}`);
     }
-    if (!isRecord(value) ||
-        value.schemaVersion !== 1 ||
-        typeof value.preset !== "string" ||
-        value.templateVersion !== "0.0.0" ||
-        !isRecord(value.toolchain) ||
-        typeof value.toolchain.nodeLtsMajor !== "string" ||
-        typeof value.toolchain.packageManagerPin !== "string" ||
-        !Array.isArray(value.packages)) {
-        throw new Error("Package Addition requires a supported Generation Record in .template/generation.json");
-    }
-    const packages = [];
-    for (const [index, item] of value.packages.entries()) {
-        if (isRecord(item)) {
-            for (const key of Object.keys(item)) {
-                if (!["path", "definitionName", "planningContribution"].includes(key)) {
-                    throw new Error(`Package Addition Generation Record packages[${index}] contains unknown field: ${key}`);
-                }
-            }
+}
+function barePackageDefinition(definition) {
+    return {
+        name: definition.name,
+        path: definition.path,
+        role: definition.role,
+    };
+}
+function preflightLocalTemplateMetadata(options) {
+    const definitionsById = new Map(options.blueprint.packages.map((definition) => [
+        definition.packageDefinitionId,
+        definition,
+    ]));
+    const joinedPackages = options.generationRecord.packages.map((record) => {
+        const definition = definitionsById.get(record.packageDefinitionId);
+        if (definition === undefined) {
+            throw new Error(`Generation Record Package Definition ID ${record.packageDefinitionId} has no matching Project Blueprint Package Definition`);
         }
-        if (!isRecord(item) ||
-            typeof item.path !== "string" ||
-            typeof item.definitionName !== "string" ||
-            !["foundationPlan", "planInitialization", "planPackageAddition"].includes(String(item.planningContribution))) {
-            throw new Error(`Package Addition requires valid package planning facts at .template/generation.json packages[${index}]`);
+        if (record.path !== definition.path) {
+            throw new Error(`Generation Record path witness ${record.path} for Package Definition ID ${record.packageDefinitionId} conflicts with Project Blueprint path ${definition.path}`);
         }
-        packages.push(item);
+        return { record, definition: barePackageDefinition(definition) };
+    });
+    const recordedIds = new Set(options.generationRecord.packages.map((record) => record.packageDefinitionId));
+    const unrecordedDefinition = options.blueprint.packages.find((definition) => !recordedIds.has(definition.packageDefinitionId));
+    if (unrecordedDefinition !== undefined) {
+        throw new Error(`Project Blueprint Package Definition ID ${unrecordedDefinition.packageDefinitionId} has no matching Generation Record provenance`);
     }
-    const blueprintPaths = options.blueprint.packages
-        .map((definition) => definition.path)
-        .toSorted();
-    const recordedPaths = packages.map((item) => item.path).toSorted();
-    if (JSON.stringify(blueprintPaths) !== JSON.stringify(recordedPaths) ||
-        new Set(recordedPaths).size !== recordedPaths.length) {
-        throw new Error("Package Addition requires Generation Record packages to match the current Project Blueprint");
+    const records = options.generationRecord.packages.filter((record) => record.planningContribution === "foundationPlan");
+    if (records.length !== 1) {
+        throw new Error(`Package Addition requires exactly one Foundation Package Planning Provenance record; found ${records.length}`);
     }
-    const generationRecord = {
-        schemaVersion: 1,
-        preset: value.preset,
-        templateVersion: value.templateVersion,
-        toolchain: {
-            nodeLtsMajor: value.toolchain.nodeLtsMajor,
-            packageManagerPin: value.toolchain.packageManagerPin,
-        },
-        packages,
-    };
-    assertGenerationRecordFoundationConsistency({
-        context: options.context,
-        blueprint: options.blueprint,
-        generationRecord,
-    });
-    return generationRecord;
-}
-function assertGenerationRecordFoundationConsistency(options) {
-    const configDefinition = typescriptConfigPackageDefinition(options.context);
-    const foundationRecords = options.generationRecord.packages.filter((record) => record.planningContribution === "foundationPlan");
-    if (foundationRecords.length !== 1 ||
-        foundationRecords[0].definitionName !== "foundation" ||
-        foundationRecords[0].path !== configDefinition.path) {
-        throw new Error("Package Addition Generation Record must contain exactly one Foundation TypeScript configuration provenance record");
+    const record = records[0];
+    if (record.definitionName !== "foundation") {
+        throw new Error(`Foundation Package Planning Provenance at ${record.path} must use definitionName foundation; received ${record.definitionName}`);
+    }
+    if (record.contributionIdentity !== typescriptConfigReplayAdapter.identity) {
+        throw new Error(`Foundation TypeScript Configuration Package provenance must use contribution identity ${typescriptConfigReplayAdapter.identity}`);
+    }
+    const foundationPackage = joinedPackages.find((candidate) => candidate.record === record);
+    let initialDefinition;
+    try {
+        initialDefinition = builtInPresetRegistry.require(options.generationRecord.preset);
     }
-    const initialRecords = options.generationRecord.packages.filter((record) => record.planningContribution === "planInitialization");
+    catch {
+        throw new Error(`Package Addition Generation Record preset ${options.generationRecord.preset} is not a registered Built-in Preset`);
+    }
+    const initialRecords = options.generationRecord.packages.filter((candidate) => candidate.planningContribution === "planInitialization");
     if (initialRecords.length === 0) {
         throw new Error(`Package Addition Generation Record preset ${options.generationRecord.preset} has no initial Package provenance`);
     }
-    const conflictingRecord = initialRecords.find((record) => record.definitionName !== options.generationRecord.preset);
+    const conflictingRecord = initialRecords.find((candidate) => candidate.definitionName !== options.generationRecord.preset);
     if (conflictingRecord !== undefined) {
         throw new Error(`Package Addition Generation Record preset ${options.generationRecord.preset} conflicts with initial Package provenance ${conflictingRecord.definitionName} for Blueprint package ${conflictingRecord.path}`);
     }
-    let rootDefinition;
-    try {
-        rootDefinition = builtInPresetRegistry.require(options.generationRecord.preset);
-    }
-    catch {
-        throw new Error(`Package Addition Generation Record preset ${options.generationRecord.preset} is not a registered Built-in Preset`);
+    const preparedWithoutInitialLookup = joinedPackages.map((candidate) => {
+        if (candidate.record === record) {
+            return {
+                ...candidate,
+                owner: "foundation",
+                adapter: typescriptConfigReplayAdapter,
+                kind: "foundation",
+            };
+        }
+        let definition;
+        try {
+            definition = builtInPresetRegistry.require(candidate.record.definitionName);
+        }
+        catch {
+            throw new Error(`Package Addition Generation Record Package Planning Provenance references unknown Built-in Preset ${candidate.record.definitionName} for Blueprint package ${candidate.record.path}`);
+        }
+        if (candidate.record.planningContribution === "planPackageAddition" &&
+            definition.planPackageAddition === undefined) {
+            throw new Error(`Package Addition Generation Record Package Planning Provenance references unsupported Package Addition for Built-in Preset ${candidate.record.definitionName} at ${candidate.record.path}`);
+        }
+        return {
+            ...candidate,
+            owner: definition.metadata.name,
+            adapter: requireRecordReplayAdapter({
+                owner: definition.metadata.name,
+                adapters: definition.packageContributionReplayAdapters,
+                record: candidate.record,
+            }),
+            kind: "package",
+        };
+    });
+    const initialPlanningKeys = initialRecords.map((candidate) => `${candidate.definitionName}:${candidate.contributionIdentity}`);
+    if (new Set(initialPlanningKeys).size !== initialPlanningKeys.length) {
+        throw new Error("Package Addition Generation Record contains duplicate initialization contribution identity");
     }
-    const initialBlueprint = rootDefinition.blueprint(options.context);
-    assertProjectBlueprintV2(initialBlueprint);
-    const expectedPaths = initialBlueprint.packages
-        .map((definition) => definition.path)
-        .toSorted();
-    const recordedInitialPaths = initialRecords
-        .map((record) => record.path)
-        .toSorted();
-    if (JSON.stringify(recordedInitialPaths) !== JSON.stringify(expectedPaths)) {
-        throw new Error(`Package Addition Generation Record preset ${options.generationRecord.preset} expects initial Blueprint packages ${expectedPaths.join(", ")}, but initial provenance records ${recordedInitialPaths.join(", ")}`);
-    }
-    for (const expectedDefinition of initialBlueprint.packages) {
-        const currentDefinition = options.blueprint.packages.find((definition) => definition.path === expectedDefinition.path);
-        if (currentDefinition === undefined ||
-            !packageDefinitionsEqual(currentDefinition, expectedDefinition)) {
-            throw new Error(`Package Addition Generation Record preset ${options.generationRecord.preset} cannot reproduce initial Blueprint Package Definition ${expectedDefinition.name} at ${expectedDefinition.path} (${expectedDefinition.role})`);
+    if (initialDefinition.initialPrimaryPackage !== undefined) {
+        if (initialRecords.length !== 1) {
+            throw new Error(`${initialDefinition.metadata.name} requires exactly one initial Primary Package Contribution provenance record`);
         }
     }
-    for (const expectedIntent of initialBlueprint.packageLinkIntents ?? []) {
-        if (!(options.blueprint.packageLinkIntents ?? []).some((currentIntent) => packageLinkIntentsEqual(currentIntent, expectedIntent))) {
-            throw new Error(`Package Addition Generation Record preset ${options.generationRecord.preset} cannot reproduce initial Blueprint Package Link Intent ${expectedIntent.consumerPackagePath} -> ${expectedIntent.providerPackagePath}`);
+    else {
+        for (const adapter of initialDefinition.packageContributionReplayAdapters) {
+            const matchingRecords = initialRecords.filter((candidate) => candidate.contributionIdentity === adapter.identity);
+            if (matchingRecords.length !== 1) {
+                throw new Error(`${initialDefinition.metadata.name} requires exactly one initial ${adapter.identity} Package Contribution provenance record`);
+            }
         }
     }
+    const initialDefinitions = new Map(preparedWithoutInitialLookup.flatMap((candidate) => candidate.record.planningContribution === "planInitialization"
+        ? [[candidate.record.contributionIdentity, candidate.definition]]
+        : []));
+    const initialPackages = {
+        require(identity) {
+            const definition = initialDefinitions.get(identity);
+            if (definition === undefined) {
+                throw new Error(`${initialDefinition.metadata.name} has no preflighted initial ${identity} Package Definition`);
+            }
+            return definition;
+        },
+    };
+    const noInitialPackages = {
+        require(identity) {
+            throw new Error(`Foundation replay adapter does not declare initial Package ${identity}`);
+        },
+    };
+    return {
+        foundationPackage,
+        replays: preparedWithoutInitialLookup.map((candidate) => ({
+            ...candidate,
+            initialPackages: candidate.kind === "foundation" ? noInitialPackages : initialPackages,
+        })),
+    };
+}
+export function loadLocalTemplateMetadata(repositoryRoot) {
+    const resolvedRoot = path.resolve(repositoryRoot);
+    const blueprintPath = path.join(resolvedRoot, ".template/blueprint.json");
+    let blueprint;
+    try {
+        blueprint = assertProjectBlueprint(readJsonFile(blueprintPath, "Project Blueprint facts"));
+    }
+    catch (error) {
+        throw new Error(`Package Addition requires a supported Project Blueprint in .template/blueprint.json: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const generationRecord = readGenerationRecord({
+        repositoryRoot: resolvedRoot,
+    });
+    const preflight = preflightLocalTemplateMetadata({
+        blueprint,
+        generationRecord,
+    });
+    const context = {
+        targetDir: resolvedRoot,
+        repositoryName: generationRecord.repositoryName,
+        defaultPackageScope: generationRecord.defaultPackageScope,
+        foundationPackages: {
+            typescriptConfiguration: {
+                name: preflight.foundationPackage.definition.name,
+            },
+        },
+        toolchain: generationRecord.toolchain,
+    };
+    const planningState = replayLocalTemplateMetadata({
+        context,
+        preflight,
+    });
+    return {
+        blueprint,
+        context,
+        [localTemplateMetadataStateKey]: { generationRecord, ...planningState },
+    };
+}
+function requireReplayAdapter(options) {
+    const adapter = options.adapters.find((candidate) => candidate.identity === options.identity);
+    if (adapter === undefined) {
+        throw new Error(`unknown Package Contribution replay adapter ${options.identity}; expected ${options.adapters.map((candidate) => candidate.identity).join(", ")} for ${options.owner}`);
+    }
+    return adapter;
 }
-function environmentNeedOwner(value) {
-    if (!isRecord(value))
-        return undefined;
-    if (value.kind === "workspace-orchestration" && value.path === ".") {
-        return { kind: "workspace-orchestration", path: "." };
+function requireRecordReplayAdapter(options) {
+    try {
+        return requireReplayAdapter({
+            owner: options.owner,
+            adapters: options.adapters,
+            identity: options.record.contributionIdentity,
+        });
     }
-    if (value.kind === "package-boundary" && typeof value.path === "string") {
-        return { kind: "package-boundary", path: value.path };
+    catch (error) {
+        throw new Error(`Package Planning Provenance ${options.owner}:${options.record.contributionIdentity} (${options.record.planningContribution}) at ${options.record.path} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
-    return undefined;
 }
-function assertEnvironmentNeedFactKeys(value, allowedKeys, context) {
-    for (const key of Object.keys(value)) {
-        if (!allowedKeys.includes(key)) {
-            throw new Error(`Package Addition Environment Need ${context} contains unknown field: ${key}`);
-        }
+function packageLeafName(packageDefinition) {
+    return packageDefinition.name.slice(packageDefinition.name.lastIndexOf("/") + 1);
+}
+function replayPersistedPackageContribution(options) {
+    let contribution;
+    try {
+        contribution = options.adapter.replay({
+            context: options.context,
+            planningContribution: options.record.planningContribution,
+            packageDefinition: options.packageDefinition,
+            packageLeafName: packageLeafName(options.packageDefinition),
+            initialPackages: options.initialPackages,
+        });
+    }
+    catch (error) {
+        throw new Error(`Package Planning Provenance ${options.owner}:${options.record.contributionIdentity} (${options.record.planningContribution}) at ${options.record.path} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (!packageDefinitionsEqual(contribution.definition, options.packageDefinition)) {
+        throw new Error(`Package Planning Provenance ${options.owner}:${options.record.contributionIdentity} at ${options.record.path} expected ${options.packageDefinition.name} / ${options.packageDefinition.path} / ${options.packageDefinition.role}, received ${contribution.definition.name} / ${contribution.definition.path} / ${contribution.definition.role}`);
     }
+    return options.adapter.identify(contribution);
 }
-function persistedCheckEnvironmentNeedFact(value, index) {
-    if (!isRecord(value))
-        return undefined;
-    const context = `check[${index}]`;
-    switch (value.kind) {
-        case "playwright-browser-assets":
-            assertEnvironmentNeedFactKeys(value, ["kind", "browser", "owner"], context);
-            break;
-        case "shellcheck-command":
-            assertEnvironmentNeedFactKeys(value, ["kind", "owner"], context);
-            break;
-        case "rust-toolchain":
-            assertEnvironmentNeedFactKeys(value, ["kind", "owner", "toolchain"], context);
-            break;
-        default:
-            return undefined;
-    }
-    if (isRecord(value.owner)) {
-        assertEnvironmentNeedFactKeys(value.owner, ["kind", "path"], `${context}.owner`);
-    }
-    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 replayLocalTemplateMetadata(options) {
+    let foundationContribution;
+    const packageContributions = [];
+    for (const replay of options.preflight.replays) {
+        const contribution = replayPersistedPackageContribution({
+            context: options.context,
+            owner: replay.owner,
+            adapter: replay.adapter,
+            record: replay.record,
+            packageDefinition: replay.definition,
+            initialPackages: replay.initialPackages,
+        });
+        if (replay.kind === "foundation") {
+            foundationContribution = contribution;
+        }
+        else {
+            packageContributions.push(contribution);
+        }
     }
+    if (foundationContribution === undefined) {
+        throw new Error("Package Addition Generation Record is missing its validated Foundation contribution");
+    }
+    return { foundationContribution, packageContributions };
 }
 function readPersistedEnvironmentNeeds(targetDir) {
     const filePath = path.join(targetDir, environmentNeedsPath);
@@ -335,88 +407,31 @@ function readPersistedEnvironmentNeeds(targetDir) {
     catch (error) {
         throw new Error(`Package Addition requires valid Check Environment Need facts: ${error instanceof Error ? error.message : String(error)}`);
     }
-    if (isRecord(value)) {
-        for (const key of Object.keys(value)) {
-            if (!["schemaVersion", "check", "deployment"].includes(key)) {
-                throw new Error(`Package Addition Environment Need facts contain unknown field: ${key}`);
-            }
-        }
-    }
-    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}`);
+    try {
+        return parseEnvironmentNeedsMetadata(value);
     }
-    if (value.deployment.some((fact, index) => {
-        if (!isRecord(fact) || fact.kind !== "docker-engine")
-            return true;
-        assertEnvironmentNeedFactKeys(fact, ["kind"], `deployment[${index}]`);
-        return false;
-    })) {
-        throw new Error(`Package Addition requires supported deployment Environment Need facts in ${environmentNeedsPath}`);
+    catch (error) {
+        throw new Error(`Package Addition requires valid Environment Need metadata in ${environmentNeedsPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
-    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;
-    });
 }
 function readExistingPackageAdditionState(options) {
-    const generationRecord = readGenerationRecord(options);
-    const persistedEnvironmentNeeds = readPersistedEnvironmentNeeds(options.context.targetDir);
+    const { blueprint, context } = options.localTemplateMetadata;
+    const state = options.localTemplateMetadata[localTemplateMetadataStateKey];
+    const { foundationContribution, generationRecord, packageContributions: contributions, } = state;
+    const persistedEnvironmentNeeds = readPersistedEnvironmentNeeds(context.targetDir);
     const manifestTruthByPackagePath = new Map();
-    const contributions = generationRecord.packages.flatMap((record) => {
-        if (record.planningContribution === "foundationPlan") {
-            return [];
-        }
-        const expectedDefinition = options.blueprint.packages.find((definition) => definition.path === record.path);
-        const definition = builtInPresetRegistry.require(record.definitionName);
-        let candidates;
-        if (record.planningContribution === "planInitialization") {
-            candidates = definition.planInitializationContributions?.(options.context) ?? [definition.planInitialization(options.context)];
-        }
-        else {
-            if (definition.planPackageAddition === undefined) {
-                throw new Error(`Generation Record Definition ${record.definitionName} no longer supports Package Addition`);
-            }
-            const packageLeafName = expectedDefinition.name.split("/")[1];
-            if (!packageLeafName) {
-                throw new Error(`Generation Record package has an invalid name: ${expectedDefinition.name}`);
-            }
-            candidates = [
-                definition.planPackageAddition({
-                    context: options.context,
-                    packageLeafName,
-                    packagePath: expectedDefinition.path,
-                }),
-            ];
-        }
-        const contribution = candidates.find((candidate) => packageDefinitionsEqual(candidate.definition, expectedDefinition));
-        if (contribution === undefined) {
-            throw new Error(`Generation Record cannot reproduce Package Definition ${expectedDefinition.name} at ${expectedDefinition.path}`);
-        }
-        return [contribution];
-    });
-    for (const packagePath of new Set(options.manifestTruthPackagePaths ?? [])) {
-        const expectedDefinition = options.blueprint.packages.find((definition) => definition.path === packagePath);
-        if (expectedDefinition === undefined) {
+    const requiredManifestTruthPackagePaths = new Set(options.requiredManifestTruthPackagePaths ?? []);
+    for (const packagePath of requiredManifestTruthPackagePaths) {
+        if (!blueprint.packages.some((definition) => definition.path === packagePath)) {
             throw new Error(`Package Addition requires manifest truth for unknown Package Path ${packagePath}`);
         }
-        const manifestPath = path.join(options.context.targetDir, packagePath, "package.json");
+    }
+    for (const expectedDefinition of blueprint.packages) {
+        const manifestPath = path.join(context.targetDir, expectedDefinition.path, "package.json");
+        if (!existsSync(manifestPath) &&
+            !requiredManifestTruthPackagePaths.has(expectedDefinition.path)) {
+            continue;
+        }
         let manifest;
         try {
             manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
@@ -429,17 +444,16 @@ function readExistingPackageAdditionState(options) {
         }
         manifestTruthByPackagePath.set(expectedDefinition.path, manifest);
     }
-    const reconstructedCheckFacts = uniqueEnvironmentNeeds(contributions.flatMap((contribution) => contribution.environmentNeeds)).map(checkEnvironmentNeedFact);
-    const reconstructedDeploymentFacts = uniqueEnvironmentNeeds(contributions.flatMap((contribution) => contribution.deploymentEnvironmentNeeds ?? [])).map(deploymentEnvironmentNeedFact);
-    const persistedCheckFacts = persistedEnvironmentNeeds.check.map(checkEnvironmentNeedFact);
-    const persistedDeploymentFacts = persistedEnvironmentNeeds.deployment.map(deploymentEnvironmentNeedFact);
-    if (JSON.stringify(reconstructedCheckFacts) !==
-        JSON.stringify(persistedCheckFacts) ||
-        JSON.stringify(reconstructedDeploymentFacts) !==
-            JSON.stringify(persistedDeploymentFacts)) {
-        throw new Error("Package Addition requires persisted Environment Need facts to match the reproducible Project Projection");
+    const reconstructedEnvironmentNeeds = normalizeEnvironmentNeeds({
+        check: [foundationContribution, ...contributions].flatMap((contribution) => contribution.environmentNeeds),
+        deployment: [foundationContribution, ...contributions].flatMap((contribution) => contribution.deploymentEnvironmentNeeds ?? []),
+    });
+    if (JSON.stringify(reconstructedEnvironmentNeeds) !==
+        JSON.stringify(persistedEnvironmentNeeds)) {
+        throw new Error("Package Addition requires persisted Environment Needs to match the reproducible Project Projection");
     }
     return {
+        foundationContribution,
         contributions,
         manifestTruthByPackagePath,
         deploymentEnvironmentNeeds: persistedEnvironmentNeeds.deployment,
@@ -451,6 +465,13 @@ function packageDefinitionsEqual(left, right) {
         left.path === right.path &&
         left.role === right.role);
 }
+function requirePersistedPackageDefinition(blueprint, definition) {
+    const persisted = blueprint.packages.find((candidate) => packageDefinitionsEqual(candidate, definition));
+    if (persisted === undefined) {
+        throw new Error(`Project Blueprint has no persisted Package Definition for ${definition.name} at ${definition.path} (${definition.role})`);
+    }
+    return persisted;
+}
 function packageLinkIntentsEqual(left, right) {
     return (left.consumerPackagePath === right.consumerPackagePath &&
         left.providerPackagePath === right.providerPackagePath);
@@ -499,7 +520,7 @@ function contributedDevcontainerComposition(options) {
                 },
             ],
         },
-        layers: options.layers,
+        layers: [githubCliDevelopmentContainerToolLayer(), ...options.layers],
     });
     return {
         operations: [
@@ -509,7 +530,7 @@ function contributedDevcontainerComposition(options) {
                 from: "devcontainer.json",
                 to: ".devcontainer/devcontainer.json",
                 replacements: {
-                    PROJECT_NAME: options.context.projectName,
+                    PROJECT_NAME: options.context.repositoryName,
                     NODE_LTS_MAJOR: options.context.toolchain.nodeLtsMajor,
                     PACKAGE_MANAGER_PIN: options.context.toolchain.packageManagerPin,
                 },
@@ -641,13 +662,36 @@ function composeDependencyMaintenancePolicy(contributions) {
         interval: "weekly",
     };
 }
+function localTypescriptConfigurationSpecifier(options) {
+    const relativePackagePath = path.posix.relative(options.consumerPackagePath, options.configurationPackagePath);
+    if (relativePackagePath.length === 0) {
+        throw new Error("TypeScript Configuration Package must have a distinct Package Path");
+    }
+    return `link:${relativePackagePath}`;
+}
+function publicCliCandidate(contributions) {
+    const candidates = contributions.filter((contribution) => contribution.foundation.npmPublication?.kind === "public-cli-candidate");
+    if (candidates.length > 1) {
+        throw new Error(`Generated Repository Plan supports at most one public CLI candidate; found ${candidates.map((candidate) => `${candidate.definition.name} at ${candidate.definition.path}`).join(", ")}`);
+    }
+    const candidate = candidates[0];
+    if (candidate !== undefined && candidate.definition.role !== "cli-tool") {
+        throw new Error(`Public CLI candidate ${candidate.definition.name} must use the cli-tool Package role`);
+    }
+    return candidate;
+}
+function renderPublicationRootCheckCommand(candidatePackagePath) {
+    return [
+        renderTurboRunCommand(["boundaries", "format:check", "lint", "typecheck", "test"], [], { continueAfterFailure: true, taskPrefix: true }),
+        renderTurboRunCommand(["build", "test:e2e"], [`--filter=!./${candidatePackagePath}`], { continueAfterFailure: true, taskPrefix: true }),
+        "pnpm run publication:artifact",
+    ].join(" && ");
+}
 function foundationPlan(options) {
-    assertProjectBlueprintV2(options.blueprint);
-    const configDefinition = typescriptConfigPackageDefinition(options.context);
-    const persistedConfigDefinition = options.blueprint.packages.find((definition) => definition.name === configDefinition.name ||
-        definition.path === configDefinition.path);
-    if (persistedConfigDefinition === undefined ||
-        !packageDefinitionsEqual(persistedConfigDefinition, configDefinition)) {
+    assertProjectBlueprint(options.blueprint);
+    const configContribution = options.foundationContribution;
+    const configDefinition = configContribution.definition;
+    if (!options.blueprint.packages.some((definition) => packageDefinitionsEqual(definition, configDefinition))) {
         throw new Error("Project Blueprint must contain the Foundation TypeScript configuration Package Definition");
     }
     const initialProjectLinkPlan = planExplicitProjectLinks({
@@ -662,15 +706,26 @@ function foundationPlan(options) {
     const injectedProviderNames = new Set([...initialProjectLinkPlan.manifestPatchesByPackagePath.values()].flatMap((patch) => Object.entries(patch.dependenciesMeta)
         .filter(([, metadata]) => metadata.injected)
         .map(([name]) => name)));
-    const configPackageName = typescriptConfigPackageName(options.context);
+    const configPackageName = options.context.foundationPackages.typescriptConfiguration.name;
+    if (configDefinition.name !== configPackageName) {
+        throw new Error(`Generation Context TypeScript Configuration Package ${configPackageName} conflicts with Blueprint Package Definition ${configDefinition.name}`);
+    }
+    const publicationCandidate = publicCliCandidate(options.contributions);
     const packageContributions = options.contributions.map((contribution) => {
-        const ownsTypeScriptConfig = contribution.operations.some((operation) => "to" in operation &&
-            operation.to === `${contribution.definition.path}/tsconfig.json`);
-        if (!ownsTypeScriptConfig)
+        if (contribution.foundation.typescriptConfigurationPackage === undefined) {
             return contribution;
+        }
         const dependencyField = injectedProviderNames.has(contribution.definition.name)
             ? "dependencies"
             : "devDependencies";
+        const dependencySpecifier = dependencyField === "devDependencies" &&
+            (contribution.manifest.private !== true ||
+                publicationCandidate?.definition.path === contribution.definition.path)
+            ? localTypescriptConfigurationSpecifier({
+                consumerPackagePath: contribution.definition.path,
+                configurationPackagePath: configDefinition.path,
+            })
+            : "workspace:*";
         const existingDependencies = contribution.manifest[dependencyField];
         return {
             ...contribution,
@@ -678,43 +733,67 @@ function foundationPlan(options) {
                 ...contribution.manifest,
                 [dependencyField]: {
                     ...(isRecord(existingDependencies) ? existingDependencies : {}),
-                    [configPackageName]: "workspace:*",
+                    [configPackageName]: dependencySpecifier,
                 },
             },
         };
     });
-    const configContribution = typescriptConfigContribution(options.context);
+    const requiresPackingHook = packageContributions.some((contribution) => {
+        const developmentDependencies = contribution.manifest.devDependencies;
+        return (isRecord(developmentDependencies) &&
+            typeof developmentDependencies[configPackageName] === "string" &&
+            developmentDependencies[configPackageName].startsWith("link:"));
+    });
     const contributions = [configContribution, ...packageContributions];
-    const generationRecord = options.generationRecord ?? {
-        schemaVersion: 1,
+    assertPackageContributionCommandNames(contributions.map((contribution) => {
+        const manifest = options.manifestTruthByPackagePath?.get(contribution.definition.path);
+        return manifest === undefined
+            ? contribution
+            : { ...contribution, manifest };
+    }));
+    const candidateRecord = options.generationRecord ?? {
+        schemaVersion: 2,
+        repositoryName: options.context.repositoryName,
+        defaultPackageScope: options.context.defaultPackageScope,
         preset: options.definition.metadata.name,
         templateVersion: "0.0.0",
         toolchain: options.context.toolchain,
         packages: [
-            ...options.contributions.map((contribution) => ({
-                path: contribution.definition.path,
-                definitionName: options.definition.metadata.name,
-                planningContribution: options.mode === "initialization"
+            ...options.contributions.map((contribution) => {
+                const planningContribution = options.mode === "initialization"
                     ? "planInitialization"
-                    : "planPackageAddition",
-            })),
+                    : "planPackageAddition";
+                return {
+                    packageDefinitionId: requirePersistedPackageDefinition(options.blueprint, contribution.definition).packageDefinitionId,
+                    path: contribution.definition.path,
+                    definitionName: options.definition.metadata.name,
+                    planningContribution,
+                    contributionIdentity: requireReplayAdapter({
+                        owner: options.definition.metadata.name,
+                        adapters: options.definition.packageContributionReplayAdapters,
+                        identity: contribution.planningIdentity,
+                    }).identity,
+                };
+            }),
             {
+                packageDefinitionId: requirePersistedPackageDefinition(options.blueprint, configDefinition).packageDefinitionId,
                 path: configDefinition.path,
                 definitionName: "foundation",
                 planningContribution: "foundationPlan",
+                contributionIdentity: typescriptConfigReplayAdapter.identity,
             },
         ],
     };
-    const environmentNeeds = uniqueEnvironmentNeeds(contributions.flatMap((item) => item.environmentNeeds));
-    const deploymentEnvironmentNeeds = uniqueEnvironmentNeeds([
-        ...(options.existingDeploymentEnvironmentNeeds ?? []),
-        ...contributions.flatMap((item) => item.deploymentEnvironmentNeeds ?? []),
-    ]);
-    const persistedEnvironmentNeeds = {
-        schemaVersion: 1,
-        check: environmentNeeds.map(checkEnvironmentNeedFact),
-        deployment: deploymentEnvironmentNeeds.map(deploymentEnvironmentNeedFact),
-    };
+    const generationRecord = parseGenerationRecord(candidateRecord);
+    const persistedEnvironmentNeeds = normalizeEnvironmentNeeds({
+        check: contributions.flatMap((item) => item.environmentNeeds),
+        deployment: [
+            ...(options.existingDeploymentEnvironmentNeeds ?? []),
+            ...contributions.flatMap((item) => item.deploymentEnvironmentNeeds ?? []),
+        ],
+    });
+    const environmentNeeds = persistedEnvironmentNeeds.check;
+    const deploymentEnvironmentNeeds = persistedEnvironmentNeeds.deployment;
     const hasDeploymentTask = contributions.some((contribution) => {
         const scripts = contribution.manifest.scripts;
         return (typeof scripts === "object" &&
@@ -758,13 +837,27 @@ function foundationPlan(options) {
     const editorCustomization = editorCustomizationForCapabilities(contributions.flatMap((contribution) => contribution.foundation.editorCapabilities), loadEditorCustomizationDeclarations(resolveTemplateSource(templateSources.editorCustomization, "capabilities.json")));
     const dependencyMaintenancePolicy = composeDependencyMaintenancePolicy(contributions);
     const rootManifest = {
-        name: options.context.projectName,
-        version: "0.0.0",
+        name: options.context.repositoryName,
         private: true,
         type: "module",
+        ...(publicationCandidate === undefined
+            ? {}
+            : {
+                imports: {
+                    "#npm-publication/*": "./scripts/npm-publication/*.ts",
+                },
+            }),
         scripts: {
-            check: renderRootCheckCommand(),
+            check: publicationCandidate === undefined
+                ? renderRootCheckCommand()
+                : renderPublicationRootCheckCommand(publicationCandidate.definition.path),
             boundaries: "node --conditions=source scripts/check-boundaries.ts",
+            ...(publicationCandidate === undefined
+                ? {}
+                : {
+                    "publication:readiness": "node --conditions=source scripts/npm-publication/check-readiness.ts",
+                    "publication:artifact": "node --conditions=source scripts/npm-publication/check-artifact.ts",
+                }),
             ...(hasDeploymentTask
                 ? { "check:deployment": renderDeploymentCheckCommand() }
                 : {}),
@@ -777,9 +870,23 @@ function foundationPlan(options) {
         },
         devDependencies: {
             "@types/node": "catalog:",
+            ...(publicationCandidate === undefined
+                ? {}
+                : {
+                    "@types/semver": "catalog:",
+                    "@types/spdx-expression-parse": "catalog:",
+                }),
             oxfmt: "catalog:",
             oxlint: "catalog:",
             "oxlint-tsgolint": "catalog:",
+            ...(publicationCandidate === undefined
+                ? {}
+                : {
+                    semver: "catalog:",
+                    "spdx-expression-parse": "catalog:",
+                    npm: "catalog:",
+                    tar: "catalog:",
+                }),
             turbo: "catalog:",
             "typescript-7": "catalog:",
         },
@@ -846,6 +953,16 @@ function foundationPlan(options) {
         };
     const workflowOperations = [
         workflowOperation,
+        ...(publicationCandidate === undefined
+            ? []
+            : [
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication/release.yml",
+                    to: ".github/workflows/release.yml",
+                },
+            ]),
         {
             kind: "writeTextTemplate",
             source: templateSources.foundation,
@@ -865,6 +982,16 @@ function foundationPlan(options) {
             nestedKeyOrder: packageConditionKeyOrder,
         },
         workspaceOperation,
+        ...(requiresPackingHook
+            ? [
+                {
+                    kind: "copyFile",
+                    source: templateSources.foundation,
+                    from: ".pnpmfile.mjs",
+                    to: ".pnpmfile.mjs",
+                },
+            ]
+            : []),
         {
             kind: "copyFile",
             source: templateSources.foundation,
@@ -877,6 +1004,16 @@ function foundationPlan(options) {
             from: "turbo.json",
             to: "turbo.json",
         },
+        ...(publicationCandidate === undefined
+            ? []
+            : [
+                {
+                    kind: "mergeJsonTemplate",
+                    source: templateSources.tsCli,
+                    from: "publication/turbo.json",
+                    to: "turbo.json",
+                },
+            ]),
         ...turboBoundaryTags.map((tag) => ({
             kind: "mergeJsonTemplate",
             source: templateSources.foundation,
@@ -901,6 +1038,27 @@ function foundationPlan(options) {
             from: "tsconfig.json",
             to: "tsconfig.json",
         },
+        ...(publicationCandidate === undefined
+            ? []
+            : [
+                {
+                    kind: "mergeJsonTemplate",
+                    source: templateSources.tsCli,
+                    from: "publication/root-tsconfig.json",
+                    to: "tsconfig.json",
+                    multilineArrays: ["include"],
+                },
+            ]),
+        ...(requiresPackingHook && publicationCandidate === undefined
+            ? [
+                {
+                    kind: "mergeJsonTemplate",
+                    source: templateSources.foundation,
+                    from: "tsconfig.packing-hook.json",
+                    to: "tsconfig.json",
+                },
+            ]
+            : []),
         {
             kind: "copyFile",
             source: templateSources.sharedOxc,
@@ -919,6 +1077,135 @@ function foundationPlan(options) {
             from: "oxfmt.config.ts",
             to: "oxfmt.config.ts",
         },
+        ...(publicationCandidate === undefined
+            ? []
+            : [
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication/readiness.ts",
+                    to: "scripts/npm-publication/readiness.ts",
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication/artifact.ts",
+                    to: "scripts/npm-publication/artifact.ts",
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication/handoff.ts",
+                    to: "scripts/npm-publication/handoff.ts",
+                },
+                {
+                    kind: "writeTextTemplate",
+                    source: templateSources.tsCli,
+                    from: "publication/check-artifact.ts",
+                    to: "scripts/npm-publication/check-artifact.ts",
+                    replacements: {
+                        PUBLIC_CLI_PACKAGE_PATH: publicationCandidate.definition.path,
+                    },
+                },
+                {
+                    kind: "writeTextTemplate",
+                    source: templateSources.tsCli,
+                    from: "publication/publish.ts",
+                    to: "scripts/npm-publication/publish.ts",
+                    replacements: {
+                        PUBLIC_CLI_PACKAGE_PATH: publicationCandidate.definition.path,
+                    },
+                },
+                {
+                    kind: "writeTextTemplate",
+                    source: templateSources.tsCli,
+                    from: "publication/release.ts",
+                    to: "scripts/npm-publication/release.ts",
+                    replacements: {
+                        PUBLIC_CLI_PACKAGE_PATH: publicationCandidate.definition.path,
+                    },
+                },
+                {
+                    kind: "writeTextTemplate",
+                    source: templateSources.tsCli,
+                    from: "publication/check-readiness.ts",
+                    to: "scripts/npm-publication/check-readiness.ts",
+                    replacements: {
+                        PUBLIC_CLI_PACKAGE_PATH: publicationCandidate.definition.path,
+                    },
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication/changelog.ts",
+                    to: "scripts/npm-publication/changelog.ts",
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication/RELEASING.md",
+                    to: "RELEASING.md",
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "src/cli-command-identity.ts",
+                    to: "scripts/npm-publication/cli-command-identity.ts",
+                },
+                {
+                    kind: "writeTextTemplate",
+                    source: templateSources.tsCli,
+                    from: "publication-setup/setup.sh",
+                    to: "scripts/npm-publication-setup/setup.sh",
+                    replacements: {
+                        PUBLIC_CLI_PACKAGE_PATH: publicationCandidate.definition.path,
+                    },
+                },
+                {
+                    kind: "setExecutable",
+                    path: "scripts/npm-publication-setup/setup.sh",
+                    executable: true,
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication-setup/README.md",
+                    to: "scripts/npm-publication-setup/README.md",
+                },
+                {
+                    kind: "writeTextTemplate",
+                    source: templateSources.tsCli,
+                    from: "publication-setup/bridge.ts",
+                    to: "scripts/npm-publication-setup/bridge.ts",
+                    replacements: {
+                        PUBLIC_CLI_PACKAGE_PATH: publicationCandidate.definition.path,
+                    },
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication-setup/assets/LICENSE-MIT.txt",
+                    to: "scripts/npm-publication-setup/assets/LICENSE-MIT.txt",
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication-setup/assets/LICENSE-APACHE-2.0.txt",
+                    to: "scripts/npm-publication-setup/assets/LICENSE-APACHE-2.0.txt",
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication-setup/assets/README.md.template",
+                    to: "scripts/npm-publication-setup/assets/README.md.template",
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.tsCli,
+                    from: "publication-setup/assets/CHANGELOG.md.template",
+                    to: "scripts/npm-publication-setup/assets/CHANGELOG.md.template",
+                },
+            ]),
         {
             kind: "writeJson",
             to: ".vscode/extensions.json",
@@ -1007,6 +1294,7 @@ function foundationPlan(options) {
         ...linkOperations.map((operation) => withProvenance(operation, foundationProvenance)),
     ];
     const reconciliation = [
+        { path: "tsconfig.json", driver: "structured" },
         { path: "turbo.json", driver: "structured" },
         {
             path: ".devcontainer/devcontainer.json",
@@ -1035,6 +1323,7 @@ function foundationPlan(options) {
             : "planInitialization",
         blueprint: options.blueprint,
         generationRecord,
+        packageContributions,
         operations,
         reconciliation,
         developmentContainer: {
@@ -1056,40 +1345,342 @@ function foundationPlan(options) {
         ],
     };
 }
-export function planGeneratedRepositoryInitialization(options) {
-    const presetBlueprint = options.definition.blueprint(options.context);
+function hasConfigurablePrimaryPackage(definition) {
+    return definition.initialPrimaryPackage !== undefined;
+}
+function errorDiagnostics(error) {
+    return (error instanceof Error ? error.message : String(error))
+        .split("\n")
+        .filter((diagnostic) => diagnostic.length > 0);
+}
+function preparePresetInitialization(options) {
+    if (!hasConfigurablePrimaryPackage(options.definition)) {
+        const diagnostics = [];
+        let presetBlueprint;
+        let contributions;
+        try {
+            presetBlueprint = assertProjectBlueprintDraft(options.definition.blueprint(options.context));
+        }
+        catch (error) {
+            diagnostics.push(...errorDiagnostics(error));
+        }
+        try {
+            contributions = options.definition.planInitializationContributions?.(options.context) ?? [options.definition.planInitialization(options.context)];
+        }
+        catch (error) {
+            diagnostics.push(...errorDiagnostics(error));
+        }
+        if (diagnostics.length > 0)
+            throw new Error(diagnostics.join("\n"));
+        return {
+            presetBlueprint: presetBlueprint,
+            contributions: contributions,
+        };
+    }
+    const capability = options.definition.initialPrimaryPackage;
+    const leafName = options.overrides?.name ?? capability.defaultLeafName;
+    const resolvedPackageIdentity = {
+        leafName,
+        definition: {
+            name: `@${options.context.defaultPackageScope}/${leafName}`,
+            path: options.overrides?.path ??
+                capability.defaultPackagePath({ packageLeafName: leafName }),
+            role: capability.role,
+        },
+    };
+    const diagnostics = [];
+    let presetBlueprint;
+    let contribution;
+    try {
+        presetBlueprint = assertProjectBlueprintDraft({
+            schemaVersion: 3,
+            packages: [resolvedPackageIdentity.definition],
+        });
+    }
+    catch (error) {
+        diagnostics.push(...errorDiagnostics(error));
+    }
+    try {
+        contribution = capability.planInitialContribution({
+            context: options.context,
+            resolvedPackageIdentity,
+        });
+    }
+    catch (error) {
+        diagnostics.push(...errorDiagnostics(error));
+    }
+    if (diagnostics.length > 0)
+        throw new Error(diagnostics.join("\n"));
+    return {
+        presetBlueprint: presetBlueprint,
+        contributions: [contribution],
+        resolvedPackageIdentity,
+    };
+}
+function planPreparedRepositoryInitialization(options) {
+    const { presetBlueprint, contributions } = options;
     const configDefinition = typescriptConfigPackageDefinition(options.context);
-    if (presetBlueprint.packages.some((definition) => definition.name === configDefinition.name ||
-        definition.path === configDefinition.path)) {
-        throw new Error("Preset Blueprint must not redefine the Foundation TypeScript configuration Package Definition");
+    const foundationIdentityDiagnostics = presetBlueprint.packages.flatMap((definition) => [
+        ...(definition.name === configDefinition.name
+            ? [
+                `Initial package name ${definition.name} conflicts with Foundation package ${configDefinition.name}`,
+            ]
+            : []),
+        ...(definition.path === configDefinition.path
+            ? [
+                `Initial Package Path ${definition.path} conflicts with Foundation Package Path ${configDefinition.path}`,
+            ]
+            : []),
+    ]);
+    if (foundationIdentityDiagnostics.length > 0) {
+        throw new Error(foundationIdentityDiagnostics.join("\n"));
     }
+    const occupiedIds = new Set();
     const blueprint = {
         ...presetBlueprint,
-        packages: [...presetBlueprint.packages, configDefinition],
+        packages: [
+            ...presetBlueprint.packages.map((definition) => {
+                const contribution = contributions.find((candidate) => packageDefinitionsEqual(candidate.definition, definition));
+                if (contribution === undefined) {
+                    throw new Error(`Preset Blueprint Package Definition ${definition.path} has no initialization Package Contribution`);
+                }
+                return persistPackageDefinition({
+                    definition,
+                    provenance: {
+                        definitionName: options.definition.metadata.name,
+                        planningContribution: "planInitialization",
+                        contributionIdentity: requireReplayAdapter({
+                            owner: options.definition.metadata.name,
+                            adapters: options.definition.packageContributionReplayAdapters,
+                            identity: contribution.planningIdentity,
+                        }).identity,
+                    },
+                    occupiedIds,
+                });
+            }),
+            persistPackageDefinition({
+                definition: configDefinition,
+                provenance: {
+                    definitionName: "foundation",
+                    planningContribution: "foundationPlan",
+                    contributionIdentity: typescriptConfigReplayAdapter.identity,
+                },
+                occupiedIds,
+            }),
+        ],
     };
-    const contributions = options.definition.planInitializationContributions?.(options.context) ?? [options.definition.planInitialization(options.context)];
     return foundationPlan({
         definition: options.definition,
         context: options.context,
         blueprint,
+        foundationContribution: typescriptConfigReplayAdapter.identify(typescriptConfigContribution(options.context, configDefinition)),
         contributions,
         mode: "initialization",
     });
 }
+function assertPreflightedInitializationPlan(plan) {
+    const projectionDiagnostics = validateProjectProjectionPlan({
+        operations: plan.operations,
+        reconciliation: plan.reconciliation,
+    });
+    if (projectionDiagnostics.length > 0) {
+        throw new Error(projectionDiagnostics.join("\n"));
+    }
+    return plan;
+}
+export function planGeneratedRepositoryInitialization(options) {
+    const prepared = preparePresetInitialization(options);
+    return assertPreflightedInitializationPlan(planPreparedRepositoryInitialization({
+        definition: options.definition,
+        context: options.context,
+        presetBlueprint: prepared.presetBlueprint,
+        contributions: prepared.contributions,
+    }));
+}
+export function prepareGeneratedRepositoryInitialization(options) {
+    const diagnostics = [];
+    const appendDiagnostics = (error) => {
+        diagnostics.push(...errorDiagnostics(error));
+    };
+    const scopeOverride = options.overrides?.scope;
+    const normalizedScope = scopeOverride?.startsWith("@") === true
+        ? scopeOverride.slice(1)
+        : scopeOverride;
+    const nameOverride = options.overrides?.name;
+    const pathOverride = options.overrides?.path;
+    const repositoryName = path.basename(path.resolve(options.targetDir));
+    const configurablePrimaryPackage = options.definition.initialPrimaryPackage !== undefined;
+    if (!configurablePrimaryPackage &&
+        (nameOverride !== undefined || pathOverride !== undefined)) {
+        diagnostics.push(`Built-in Preset ${options.definition.metadata.name} has fixed initial package topology and does not accept --name or --path`);
+    }
+    let validNameOverride = nameOverride !== undefined &&
+        isValidNewNpmPackageName(`@x/${nameOverride}`);
+    if (nameOverride !== undefined && !validNameOverride) {
+        diagnostics.push("--name must be an unscoped package leaf name");
+    }
+    let validPathOverride = pathOverride !== undefined;
+    if (pathOverride !== undefined) {
+        const pathValidation = validateNewPackagePath(pathOverride);
+        if (!pathValidation.hasValidShape) {
+            diagnostics.push("--path must be exactly two safe path segments");
+            validPathOverride = false;
+        }
+        if (pathValidation.reservedWorkspaceCollection !== undefined) {
+            diagnostics.push(`--path ${pathOverride} uses reserved workspace collection ${pathValidation.reservedWorkspaceCollection}`);
+            validPathOverride = false;
+        }
+    }
+    let validScopeOverride = normalizedScope !== undefined &&
+        scopeOverride === scopeOverride?.trim() &&
+        isValidDefaultPackageScope(normalizedScope) &&
+        isValidNewNpmPackageName(`@${normalizedScope}/typescript-config`);
+    if (normalizedScope !== undefined && !validScopeOverride) {
+        diagnostics.push("--scope must be a valid npm scope without whitespace");
+    }
+    let validRepositoryScope = isValidDefaultPackageScope(repositoryName) &&
+        isValidNewNpmPackageName(`@${repositoryName}/typescript-config`);
+    if (normalizedScope === undefined && !validRepositoryScope) {
+        diagnostics.push(`Repository Identity ${repositoryName} is not a valid default package scope; pass --scope with a valid npm scope`);
+    }
+    const resolvedScope = validScopeOverride
+        ? (normalizedScope ?? "repository")
+        : validRepositoryScope
+            ? repositoryName
+            : "repository";
+    const resolvedLeaf = configurablePrimaryPackage &&
+        nameOverride !== undefined &&
+        validNameOverride
+        ? nameOverride
+        : configurablePrimaryPackage
+            ? options.definition.initialPrimaryPackage?.defaultLeafName
+            : undefined;
+    if (resolvedLeaf !== undefined &&
+        !isValidNewNpmPackageName(`@${resolvedScope}/${resolvedLeaf}`)) {
+        if (nameOverride !== undefined) {
+            validNameOverride = false;
+            diagnostics.push("--name must be an unscoped package leaf name");
+        }
+        else if (scopeOverride !== undefined) {
+            validScopeOverride = false;
+            diagnostics.push("--scope must be a valid npm scope without whitespace");
+        }
+        else {
+            validRepositoryScope = false;
+            diagnostics.push(`Repository Identity ${repositoryName} is not a valid default package scope; pass --scope with a valid npm scope`);
+        }
+    }
+    const context = createGenerationContext({
+        targetDir: options.targetDir,
+        defaultPackageScope: validScopeOverride
+            ? (normalizedScope ?? "repository")
+            : validRepositoryScope
+                ? repositoryName
+                : "repository",
+        toolchain: options.toolchain,
+    });
+    const safeNameOverride = configurablePrimaryPackage && nameOverride !== undefined
+        ? validNameOverride
+            ? nameOverride
+            : "x"
+        : undefined;
+    let safeDerivedPathOverride;
+    const initialPrimaryPackage = options.definition.initialPrimaryPackage;
+    if (initialPrimaryPackage !== undefined && pathOverride === undefined) {
+        const safeLeafName = safeNameOverride ?? initialPrimaryPackage.defaultLeafName;
+        const derivedPackagePath = initialPrimaryPackage.defaultPackagePath({
+            packageLeafName: safeLeafName,
+        });
+        const derivedPathValidation = validateNewPackagePath(derivedPackagePath);
+        if (!derivedPathValidation.hasValidShape ||
+            derivedPathValidation.reservedWorkspaceCollection !== undefined) {
+            diagnostics.push(`Preset-derived Package Path ${derivedPackagePath} is unsafe; pass --path with exactly two safe path segments`);
+            safeDerivedPathOverride = "packages/invalid";
+        }
+    }
+    const safeIdentityOverrides = {
+        ...(safeNameOverride === undefined ? {} : { name: safeNameOverride }),
+        ...(configurablePrimaryPackage && pathOverride !== undefined
+            ? { path: validPathOverride ? pathOverride : "packages/invalid" }
+            : safeDerivedPathOverride === undefined
+                ? {}
+                : { path: safeDerivedPathOverride }),
+    };
+    let prepared;
+    try {
+        prepared = preparePresetInitialization({
+            definition: options.definition,
+            context,
+            ...(Object.keys(safeIdentityOverrides).length === 0
+                ? {}
+                : { overrides: safeIdentityOverrides }),
+        });
+    }
+    catch (error) {
+        appendDiagnostics(error);
+    }
+    let plan;
+    if (prepared !== undefined) {
+        try {
+            plan = planPreparedRepositoryInitialization({
+                definition: options.definition,
+                context,
+                presetBlueprint: prepared.presetBlueprint,
+                contributions: prepared.contributions,
+            });
+        }
+        catch (error) {
+            appendDiagnostics(error);
+        }
+    }
+    if (plan !== undefined) {
+        diagnostics.push(...validateProjectProjectionPlan({
+            operations: plan.operations,
+            reconciliation: plan.reconciliation,
+        }));
+    }
+    if (diagnostics.length > 0)
+        throw new Error(diagnostics.join("\n"));
+    if (prepared === undefined || plan === undefined) {
+        throw new Error("Initialization preparation did not produce a plan");
+    }
+    return {
+        context,
+        resolved: {
+            preset: options.definition.metadata.name,
+            topology: prepared.resolvedPackageIdentity === undefined
+                ? "fixed"
+                : "configurable-primary-package",
+            packages: prepared.presetBlueprint.packages.map(({ name, path }) => ({
+                name,
+                path,
+            })),
+            scope: context.defaultPackageScope,
+        },
+        ...(prepared.resolvedPackageIdentity === undefined
+            ? {}
+            : { resolvedPackageIdentity: prepared.resolvedPackageIdentity }),
+        plan,
+        publicationSetup: publicCliCandidate(prepared.contributions) === undefined
+            ? null
+            : { command: "./scripts/npm-publication-setup/setup.sh" },
+    };
+}
 export function planGeneratedRepositoryPackageAddition(options) {
-    assertProjectBlueprintV2(options.blueprint);
+    const { blueprint: persistedBlueprint, context } = options.localTemplateMetadata;
+    assertProjectBlueprint(persistedBlueprint);
     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,
+            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,
+        context,
         packageLeafName: options.packageLeafName,
         packagePath,
     });
@@ -1097,28 +1688,31 @@ export function planGeneratedRepositoryPackageAddition(options) {
         consumerPackagePath,
         providerPackagePath: contribution.definition.path,
     }));
-    const conflictingPackage = options.blueprint.packages.find((existing) => existing.name === contribution.definition.name ||
+    const conflictingPackage = persistedBlueprint.packages.find((existing) => existing.name === contribution.definition.name ||
         existing.path === contribution.definition.path);
     if (conflictingPackage !== undefined) {
         const isExactPackageDefinition = packageDefinitionsEqual(conflictingPackage, contribution.definition);
-        const existingPackageLinkIntents = options.blueprint.packageLinkIntents ?? [];
+        const existingPackageLinkIntents = persistedBlueprint.packageLinkIntents ?? [];
         const missingPackageLinkIntent = requestedPackageLinkIntents.find((requested) => !existingPackageLinkIntents.some((existing) => packageLinkIntentsEqual(existing, requested)));
         if (isExactPackageDefinition && missingPackageLinkIntent === undefined) {
             const existing = readExistingPackageAdditionState(options);
             const plan = foundationPlan({
                 definition: options.definition,
-                context: options.context,
-                blueprint: options.blueprint,
+                context,
+                blueprint: persistedBlueprint,
+                foundationContribution: existing.foundationContribution,
                 contributions: existing.contributions,
                 renderContributions: [],
                 existingDeploymentEnvironmentNeeds: existing.deploymentEnvironmentNeeds,
+                manifestTruthByPackagePath: existing.manifestTruthByPackagePath,
                 generationRecord: existing.generationRecord,
                 mode: "addition",
             });
             const currentProjection = foundationPlan({
                 definition: options.definition,
-                context: options.context,
-                blueprint: options.blueprint,
+                context,
+                blueprint: persistedBlueprint,
+                foundationContribution: existing.foundationContribution,
                 contributions: existing.contributions,
                 existingDeploymentEnvironmentNeeds: existing.deploymentEnvironmentNeeds,
                 generationRecord: existing.generationRecord,
@@ -1145,47 +1739,64 @@ export function planGeneratedRepositoryPackageAddition(options) {
         }
         throw new Error(`Package Addition conflicts with existing Package Definition ${conflictingPackage.name} at ${conflictingPackage.path} (${conflictingPackage.role}); requested ${contribution.definition.name} at ${contribution.definition.path} (${contribution.definition.role})`);
     }
+    const contributionIdentity = requireReplayAdapter({
+        owner: options.definition.metadata.name,
+        adapters: options.definition.packageContributionReplayAdapters,
+        identity: contribution.planningIdentity,
+    }).identity;
+    const persistedContributionDefinition = persistPackageDefinition({
+        definition: contribution.definition,
+        provenance: {
+            definitionName: options.definition.metadata.name,
+            planningContribution: "planPackageAddition",
+            contributionIdentity,
+        },
+        occupiedIds: new Set(persistedBlueprint.packages.map((definition) => definition.packageDefinitionId)),
+    });
     const blueprint = {
-        ...options.blueprint,
-        packages: [...options.blueprint.packages, contribution.definition],
+        ...persistedBlueprint,
+        packages: [...persistedBlueprint.packages, persistedContributionDefinition],
         ...(requestedPackageLinkIntents.length > 0
             ? {
                 packageLinkIntents: [
-                    ...(options.blueprint.packageLinkIntents ?? []),
+                    ...(persistedBlueprint.packageLinkIntents ?? []),
                     ...requestedPackageLinkIntents,
                 ],
             }
             : {}),
     };
-    assertProjectBlueprintV2(blueprint);
-    const manifestTruthPackagePaths = requestedPackageLinkIntents.length === 0
+    assertProjectBlueprint(blueprint);
+    const requiredManifestTruthPackagePaths = requestedPackageLinkIntents.length === 0
         ? []
         : [
-            ...(options.blueprint.packageLinkIntents ?? []).flatMap((intent) => [
+            ...(persistedBlueprint.packageLinkIntents ?? []).flatMap((intent) => [
                 intent.consumerPackagePath,
                 intent.providerPackagePath,
             ]),
             ...requestedPackageLinkIntents.map((intent) => intent.consumerPackagePath),
         ];
     const existing = readExistingPackageAdditionState({
-        ...options,
-        manifestTruthPackagePaths,
+        localTemplateMetadata: options.localTemplateMetadata,
+        requiredManifestTruthPackagePaths,
     });
     const generationRecord = {
         ...existing.generationRecord,
         packages: [
             ...existing.generationRecord.packages,
             {
+                packageDefinitionId: persistedContributionDefinition.packageDefinitionId,
                 path: contribution.definition.path,
                 definitionName: options.definition.metadata.name,
                 planningContribution: "planPackageAddition",
+                contributionIdentity,
             },
         ],
     };
     const beforeProjection = foundationPlan({
         definition: options.definition,
-        context: options.context,
-        blueprint: options.blueprint,
+        context,
+        blueprint: persistedBlueprint,
+        foundationContribution: existing.foundationContribution,
         contributions: existing.contributions,
         existingDeploymentEnvironmentNeeds: existing.deploymentEnvironmentNeeds,
         generationRecord: existing.generationRecord,
@@ -1193,30 +1804,24 @@ export function planGeneratedRepositoryPackageAddition(options) {
     });
     const afterProjection = foundationPlan({
         definition: options.definition,
-        context: options.context,
+        context,
         blueprint,
+        foundationContribution: existing.foundationContribution,
         contributions: [...existing.contributions, contribution],
         existingDeploymentEnvironmentNeeds: existing.deploymentEnvironmentNeeds,
-        ...(requestedPackageLinkIntents.length === 0
-            ? {}
-            : {
-                manifestTruthByPackagePath: existing.manifestTruthByPackagePath,
-            }),
+        manifestTruthByPackagePath: existing.manifestTruthByPackagePath,
         generationRecord,
         mode: "initialization",
     });
     const plan = foundationPlan({
         definition: options.definition,
-        context: options.context,
+        context,
         blueprint,
+        foundationContribution: existing.foundationContribution,
         contributions: [...existing.contributions, contribution],
         renderContributions: [contribution],
         existingDeploymentEnvironmentNeeds: existing.deploymentEnvironmentNeeds,
-        ...(requestedPackageLinkIntents.length === 0
-            ? {}
-            : {
-                manifestTruthByPackagePath: existing.manifestTruthByPackagePath,
-            }),
+        manifestTruthByPackagePath: existing.manifestTruthByPackagePath,
         generationRecord,
         mode: "addition",
     });