@ykdz/template 0.0.23 → 0.0.24

package/node_modules/@ykdz/template-core/dist/project-blueprint-v2.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The durable, preset-agnostic topology used by local template follow-up
+ * operations. Preset provenance deliberately belongs in Generation Record.
+ */
+export type PackageRole = "runtime-service" | "shared-library" | "native-package";
+export type PackageDefinition = {
+    readonly name: string;
+    readonly path: string;
+    readonly role: PackageRole;
+};
+export type PackageLinkIntent = {
+    readonly consumerPackagePath: string;
+    readonly providerPackagePath: string;
+};
+export type ProjectBlueprintV2 = {
+    readonly schemaVersion: 2;
+    readonly packages: readonly PackageDefinition[];
+    readonly packageLinkIntents?: readonly PackageLinkIntent[];
+};
+export type BlueprintV2ValidationIssue = {
+    readonly path: string;
+    readonly message: string;
+};
+export type BlueprintV2ValidationResult = {
+    readonly ok: true;
+    readonly value: ProjectBlueprintV2;
+} | {
+    readonly ok: false;
+    readonly issues: readonly BlueprintV2ValidationIssue[];
+};
+/** Validates persisted metadata before it is used to plan or render changes. */
+export declare function validateProjectBlueprintV2(value: unknown): BlueprintV2ValidationResult;
+export declare function assertProjectBlueprintV2(value: unknown): ProjectBlueprintV2;

package/node_modules/@ykdz/template-core/dist/project-blueprint-v2.js

@@ -0,0 +1,161 @@
+const packageName = /^@[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/;
+const packagePath = /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/;
+const roles = new Set([
+    "runtime-service",
+    "shared-library",
+    "native-package",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function reportUnknownKeys(value, allowed, path, issues) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            issues.push({
+                path: `${path}.${key}`,
+                message: "Unknown Blueprint v2 field",
+            });
+        }
+    }
+}
+/** Validates persisted metadata before it is used to plan or render changes. */
+export function validateProjectBlueprintV2(value) {
+    const issues = [];
+    if (!isRecord(value)) {
+        return {
+            ok: false,
+            issues: [
+                { path: ".", message: "Local Template Metadata must be an object" },
+            ],
+        };
+    }
+    reportUnknownKeys(value, ["schemaVersion", "packages", "packageLinkIntents"], ".", issues);
+    if (value.schemaVersion !== 2) {
+        issues.push({
+            path: ".schemaVersion",
+            message: `Unsupported Local Template Metadata schema version ${String(value.schemaVersion)}; expected 2`,
+        });
+    }
+    if (!Array.isArray(value.packages)) {
+        issues.push({
+            path: ".packages",
+            message: "Package Definitions must be an array",
+        });
+    }
+    const definitions = [];
+    if (Array.isArray(value.packages)) {
+        for (const [index, item] of value.packages.entries()) {
+            const itemPath = `.packages[${index}]`;
+            if (!isRecord(item)) {
+                issues.push({
+                    path: itemPath,
+                    message: "Package Definition must be an object",
+                });
+                continue;
+            }
+            reportUnknownKeys(item, ["name", "path", "role"], itemPath, issues);
+            if (typeof item.name !== "string" || !packageName.test(item.name)) {
+                issues.push({
+                    path: `${itemPath}.name`,
+                    message: "Package name must be a scoped lowercase package name",
+                });
+            }
+            if (typeof item.path !== "string" || !packagePath.test(item.path)) {
+                issues.push({
+                    path: `${itemPath}.path`,
+                    message: "Package Path must be exactly two safe path segments",
+                });
+            }
+            if (typeof item.role !== "string" ||
+                !roles.has(item.role)) {
+                issues.push({
+                    path: `${itemPath}.role`,
+                    message: "Package Role must be runtime-service, shared-library, or native-package",
+                });
+            }
+            if (typeof item.name === "string" &&
+                typeof item.path === "string" &&
+                typeof item.role === "string" &&
+                packageName.test(item.name) &&
+                packagePath.test(item.path) &&
+                roles.has(item.role)) {
+                definitions.push(item);
+            }
+        }
+    }
+    for (const [property, label] of [
+        ["name", "Package name"],
+        ["path", "Package Path"],
+    ]) {
+        const seen = new Set();
+        for (const definition of definitions) {
+            const member = definition[property];
+            if (seen.has(member))
+                issues.push({
+                    path: ".packages",
+                    message: `${label} must be unique: ${member}`,
+                });
+            seen.add(member);
+        }
+    }
+    if (value.packageLinkIntents !== undefined &&
+        !Array.isArray(value.packageLinkIntents)) {
+        issues.push({
+            path: ".packageLinkIntents",
+            message: "Package Link Intents must be an array",
+        });
+    }
+    const paths = new Set(definitions.map((definition) => definition.path));
+    const links = new Set();
+    if (Array.isArray(value.packageLinkIntents)) {
+        for (const [index, item] of value.packageLinkIntents.entries()) {
+            const itemPath = `.packageLinkIntents[${index}]`;
+            if (!isRecord(item)) {
+                issues.push({
+                    path: itemPath,
+                    message: "Package Link Intent must be an object",
+                });
+                continue;
+            }
+            reportUnknownKeys(item, ["consumerPackagePath", "providerPackagePath"], itemPath, issues);
+            const consumer = item.consumerPackagePath;
+            const provider = item.providerPackagePath;
+            if (typeof consumer !== "string" || !paths.has(consumer))
+                issues.push({
+                    path: `${itemPath}.consumerPackagePath`,
+                    message: "Package Link Intent references an unknown consumer package",
+                });
+            if (typeof provider !== "string" || !paths.has(provider))
+                issues.push({
+                    path: `${itemPath}.providerPackagePath`,
+                    message: "Package Link Intent references an unknown provider package",
+                });
+            if (consumer === provider && typeof consumer === "string")
+                issues.push({
+                    path: itemPath,
+                    message: "Package Link Intent cannot link a package to itself",
+                });
+            if (typeof consumer === "string" && typeof provider === "string") {
+                const key = `${consumer}\u0000${provider}`;
+                if (links.has(key))
+                    issues.push({
+                        path: itemPath,
+                        message: "Package Link Intent must be unique",
+                    });
+                links.add(key);
+            }
+        }
+    }
+    return issues.length === 0
+        ? { ok: true, value: value }
+        : { ok: false, issues };
+}
+export function assertProjectBlueprintV2(value) {
+    const result = validateProjectBlueprintV2(value);
+    if (!result.ok) {
+        throw new Error(result.issues
+            .map((issue) => `${issue.path}: ${issue.message}`)
+            .join("\n"));
+    }
+    return result.value;
+}

package/node_modules/@ykdz/template-core/dist/project-github.d.ts

@@ -1,4 +1,4 @@
-import { type CheckPlan } from "./module-graph.js";
+import { type CheckPlan } from "./module-graph.ts";
 export type CiCapability = {
     readonly workflowName: "Check";
     readonly jobName: "check";
@@ -27,5 +27,12 @@ type ProjectCheckWorkflowOptions = {
     readonly taskLayer?: PnpmTaskLayer | undefined;
 };
 export declare function projectCheckWorkflow(options: ProjectCheckWorkflowOptions): string;
+/** Limited substitutions for the Foundation-owned workflow Template Source. */
+export declare function projectCheckWorkflowTemplateReplacements(options: {
+    readonly checkPlan: CheckPlan;
+    readonly environmentPreparation?: Partial<CiEnvironmentPreparation>;
+}): Record<string, string>;
 export declare function projectDependabotConfig(policy: DependencyMaintenancePolicy): string;
+/** Limited substitution for the Foundation-owned Dependabot Template Source. */
+export declare function projectDependabotTemplateReplacements(policy: DependencyMaintenancePolicy): Record<string, string>;
 export {};

package/node_modules/@ykdz/template-core/dist/project-github.js

@@ -15,6 +15,8 @@ export function projectCheckWorkflow(options) {
         rustToolchain: false,
         ...options.environmentPreparation,
     };
+    const requiresRustToolchain = environmentPreparation.rustToolchain ||
+        options.checkPlan.environmentNeeds.some((need) => need.kind === "rust-toolchain");
     const taskLayer = options.taskLayer ?? pnpmTaskLayer;
     const deploymentChecks = options.checkPlan.deploymentChecks ?? [];
     const needsDocker = deploymentChecks.some((check) => deploymentCheckEnvironmentNeeds(check).some((need) => need.kind === "docker-engine"));
@@ -30,6 +32,13 @@ export function projectCheckWorkflow(options) {
         "jobs:",
         `  ${capability.jobName}:`,
         `    runs-on: ${capability.runner}`,
+        ...(deploymentChecks.length === 0
+            ? []
+            : [
+                "    strategy:",
+                "      matrix:",
+                "        check: [root, deployment]",
+            ]),
         "    steps:",
         "      - uses: actions/checkout@v7",
     ];
@@ -37,21 +46,74 @@ export function projectCheckWorkflow(options) {
         lines.push("      - uses: actions/setup-node@v6", "        with:", "          node-version-file: package.json", "      - run: corepack enable");
     }
     if (needsDocker) {
-        lines.push("      - uses: docker/setup-buildx-action@v3");
-    }
-    if (environmentPreparation.rustToolchain) {
-        lines.push("      - uses: dtolnay/rust-toolchain@stable", "        with:", "          components: rustfmt, clippy", "      - uses: Swatinem/rust-cache@v2");
+        lines.push("      - uses: docker/setup-buildx-action@v3", "        if: matrix.check == 'deployment'");
     }
+    if (requiresRustToolchain)
+        lines.push(...rustCiPreparationLines());
     lines.push(`      - run: ${taskLayer.installCommand}`);
-    lines.push(...options.checkPlan.environmentNeeds.map((need) => `      - run: ${renderCiEnvironmentNeedCommand(need)}`));
+    const checkEnvironmentLines = [];
+    for (const need of options.checkPlan.environmentNeeds) {
+        if (need.kind === "rust-toolchain")
+            continue;
+        checkEnvironmentLines.push(`      - run: ${renderCiEnvironmentNeedCommand(need)}`);
+        if (deploymentChecks.length > 0 && need.kind === "shellcheck-command") {
+            checkEnvironmentLines.push("        if: matrix.check == 'root'");
+        }
+    }
+    lines.push(...checkEnvironmentLines);
     lines.push(`      - run: ${taskLayer.checkCommand}`);
+    if (deploymentChecks.length > 0) {
+        lines.push("        if: matrix.check == 'root'");
+    }
     const deploymentCheck = deploymentChecks[0];
     if (deploymentCheck !== undefined) {
-        lines.push(`      - run: pnpm run ${deploymentCheckTaskName(deploymentCheck)}`);
+        lines.push(`      - run: pnpm run ${deploymentCheckTaskName(deploymentCheck)}`, "        if: matrix.check == 'deployment'");
     }
     lines.push("");
     return lines.join("\n");
 }
+function rustCiPreparationLines() {
+    return [
+        "      - uses: dtolnay/rust-toolchain@stable",
+        "        with:",
+        "          components: rustfmt, clippy",
+        "      - uses: Swatinem/rust-cache@v2",
+    ];
+}
+/** Limited substitutions for the Foundation-owned workflow Template Source. */
+export function projectCheckWorkflowTemplateReplacements(options) {
+    const requiresRustToolchain = options.environmentPreparation?.rustToolchain === true ||
+        options.checkPlan.environmentNeeds.some((need) => need.kind === "rust-toolchain");
+    const deploymentChecks = options.checkPlan.deploymentChecks ?? [];
+    const needsDocker = deploymentChecks.some((check) => deploymentCheckEnvironmentNeeds(check).some((need) => need.kind === "docker-engine"));
+    const deploymentCheck = deploymentChecks[0];
+    const environmentSteps = options.checkPlan.environmentNeeds
+        .filter((need) => need.kind !== "rust-toolchain")
+        .map((need) => [
+        `      - run: ${renderCiEnvironmentNeedCommand(need)}`,
+        ...(deploymentChecks.length > 0 && need.kind === "shellcheck-command"
+            ? ["        if: matrix.check == 'root'"]
+            : []),
+    ].join("\n"));
+    return {
+        RUST_CI_PREPARATION: requiresRustToolchain
+            ? `\n${rustCiPreparationLines().join("\n")}`
+            : "",
+        CHECK_ENVIRONMENT_PREPARATION: environmentSteps.length === 0 ? "" : `\n${environmentSteps.join("\n")}`,
+        DEPLOYMENT_MATRIX: deploymentChecks.length === 0
+            ? ""
+            : "\n    strategy:\n      matrix:\n        check: [root, deployment]",
+        DEPLOYMENT_DOCKER_PREPARATION: needsDocker
+            ? "\n      - uses: docker/setup-buildx-action@v3\n        if: matrix.check == 'deployment'"
+            : "",
+        ROOT_CHECK_CONDITION: deploymentChecks.length === 0
+            ? ""
+            : "\n        if: matrix.check == 'root'",
+        DEPLOYMENT_CHECK: deploymentCheck === undefined
+            ? ""
+            : `\n      - run: pnpm run ${deploymentCheckTaskName(deploymentCheck)}\n        if: matrix.check == 'deployment'`,
+    };
+}
 export function projectDependabotConfig(policy) {
     return [
         "version: 2",
@@ -65,6 +127,15 @@ export function projectDependabotConfig(policy) {
         "",
     ].join("\n");
 }
+/** Limited substitution for the Foundation-owned Dependabot Template Source. */
+export function projectDependabotTemplateReplacements(policy) {
+    const header = "version: 2\n\nupdates:\n";
+    const configuration = projectDependabotConfig(policy);
+    if (!configuration.startsWith(header)) {
+        throw new Error("Dependabot configuration must retain its Template Source header");
+    }
+    return { DEPENDABOT_UPDATES: configuration.slice(header.length).trimEnd() };
+}
 function renderDependabotUpdate(ecosystem, directory, interval) {
     const lines = [
         `  - package-ecosystem: ${ecosystem}`,
@@ -73,7 +144,7 @@ function renderDependabotUpdate(ecosystem, directory, interval) {
         `      interval: ${interval}`,
     ];
     if (ecosystem === "npm") {
-        lines.push("    groups:", "      drizzle:", "        patterns:", '          - "drizzle-*"', '          - "drizzle-orm"', "    ignore:", '      - dependency-name: "@types/node"', "        update-types:", "          - version-update:semver-major");
+        lines.push("    groups:", "      drizzle:", "        patterns:", '          - "drizzle-*"', '          - "drizzle-orm"', "    ignore:", '      - dependency-name: "@types/node"', "        update-types:", "          - version-update:semver-major", '      - dependency-name: "pnpm"', "        update-types:", "          - version-update:semver-major", "          - version-update:semver-minor", "          - version-update:semver-patch");
     }
     if (ecosystem === "docker" && directory === "/.devcontainer") {
         lines.push("    ignore:", "      - dependency-name: mcr.microsoft.com/devcontainers/typescript-node", "        update-types:", "          - version-update:semver-major");
@@ -87,5 +158,12 @@ function defaultDependabotDirectory(ecosystem) {
     return ecosystem === "docker" ? "/.devcontainer" : "/";
 }
 function renderCiEnvironmentNeedCommand(need) {
-    return renderPlaywrightBrowserInstallCommand(need, { withDeps: true });
+    switch (need.kind) {
+        case "playwright-browser-assets":
+            return renderPlaywrightBrowserInstallCommand(need, { withDeps: true });
+        case "shellcheck-command":
+            return need.nextStep.display;
+        case "rust-toolchain":
+            return need.nextStep.display;
+    }
 }

package/node_modules/@ykdz/template-core/dist/project-linking-v2.d.ts

@@ -0,0 +1,20 @@
+import type { PackageContribution } from "./package-contribution.ts";
+import { type ProjectBlueprintV2 } from "./project-blueprint-v2.ts";
+export type ExplicitProjectLinkPlan = {
+    readonly manifestDependenciesByPackagePath: ReadonlyMap<string, Readonly<Record<string, "workspace:*">>>;
+    /**
+     * Build ordering follows the same explicit package relationships as manifest
+     * dependencies.  Turbo resolves ^build:run through the derived workspace
+     * dependency rather than through Preset or framework vocabulary.
+     */
+    readonly hasBuildOrdering: boolean;
+};
+/**
+ * Resolves durable Link Intents using the explicit exposures supplied by
+ * Package Contributions. No Preset identity or string resource protocol is
+ * involved.
+ */
+export declare function planExplicitProjectLinks(options: {
+    readonly blueprint: ProjectBlueprintV2;
+    readonly contributions: readonly PackageContribution[];
+}): ExplicitProjectLinkPlan;

package/node_modules/@ykdz/template-core/dist/project-linking-v2.js

@@ -0,0 +1,37 @@
+import { assertProjectBlueprintV2, } from "./project-blueprint-v2.js";
+/**
+ * Resolves durable Link Intents using the explicit exposures supplied by
+ * Package Contributions. No Preset identity or string resource protocol is
+ * involved.
+ */
+export function planExplicitProjectLinks(options) {
+    const blueprint = assertProjectBlueprintV2(options.blueprint);
+    const contributionsByPath = new Map(options.contributions.map((contribution) => [
+        contribution.definition.path,
+        contribution,
+    ]));
+    const dependencies = new Map();
+    for (const intent of blueprint.packageLinkIntents ?? []) {
+        const provider = contributionsByPath.get(intent.providerPackagePath);
+        const consumer = contributionsByPath.get(intent.consumerPackagePath);
+        if (provider === undefined || consumer === undefined) {
+            throw new Error("Project Linking requires explicit Package Contributions for every Link Intent endpoint");
+        }
+        if (Object.keys(provider.exposure.exports).length === 0) {
+            throw new Error(`Package Link provider ${provider.definition.path} has no Package Exposure`);
+        }
+        const consumerDependencies = dependencies.get(intent.consumerPackagePath);
+        if (consumerDependencies === undefined) {
+            dependencies.set(intent.consumerPackagePath, {
+                [provider.definition.name]: "workspace:*",
+            });
+        }
+        else {
+            consumerDependencies[provider.definition.name] = "workspace:*";
+        }
+    }
+    return {
+        manifestDependenciesByPackagePath: dependencies,
+        hasBuildOrdering: dependencies.size > 0,
+    };
+}

package/node_modules/@ykdz/template-core/dist/renderer.d.ts

@@ -1,60 +1,95 @@
 type RenderVariables = Record<string, string>;
+export type RenderOperationProvenance = {
+    readonly definitionName: string;
+    readonly plannerSourceFile: string;
+    readonly planningContribution: string;
+    readonly ownershipRule: string;
+};
+/**
+ * An opaque, owned Template Source reference.  A renderer operation carries
+ * this directly instead of selecting a root from a string-keyed side map.
+ */
+declare const templateSourceHandleBrand: unique symbol;
+export type TemplateSourceHandle = {
+    readonly [templateSourceHandleBrand]: true;
+};
+export declare function createTemplateSourceHandle(root: string): TemplateSourceHandle;
+/** Resolves a handle-owned source path while enforcing containment. */
+export declare function resolveTemplateSource(source: TemplateSourceHandle, relativePath: string): string;
 export type CopyFileOperation = {
     kind: "copyFile";
     from: string;
     to: string;
-    sourceRoot?: string;
+    source: TemplateSourceHandle;
+    /** Foundation refreshes coordinated outputs during Package Addition. */
+    overwrite?: boolean;
+    provenance?: RenderOperationProvenance;
 };
 export type WriteJsonOperation = {
     kind: "writeJson";
     to: string;
     value: unknown;
     multilineArrays?: string[];
+    overwrite?: boolean;
+    provenance?: RenderOperationProvenance;
 };
 export type MergeJsonOperation = {
     kind: "mergeJson";
     to: string;
     value: unknown;
+    multilineArrays?: string[];
+    provenance?: RenderOperationProvenance;
 };
 export type WriteTextOperation = {
     kind: "writeText";
     to: string;
     text: string;
+    provenance?: RenderOperationProvenance;
 };
 export type WriteTextFromFragmentsOperation = {
     kind: "writeTextFromFragments";
     to: string;
     fragments: readonly {
         from: string;
-        sourceRoot?: string;
+        source: TemplateSourceHandle;
     }[];
+    overwrite?: boolean;
+    provenance?: RenderOperationProvenance;
 };
 export type WriteTextTemplateOperation = {
     kind: "writeTextTemplate";
     from: string;
     to: string;
-    sourceRoot?: string;
+    source: TemplateSourceHandle;
     replacements: Record<string, string>;
+    /** Follow-up plans may refresh a coordinated template-owned file. */
+    overwrite?: boolean;
+    provenance?: RenderOperationProvenance;
 };
 export type SetExecutableOperation = {
     kind: "setExecutable";
     path: string;
     executable: boolean;
+    provenance?: RenderOperationProvenance;
 };
 export type ReplaceAnchorsOperation = {
     kind: "replaceAnchors";
     path: string;
     language: "typescript";
     replacements: Record<string, string>;
+    provenance?: RenderOperationProvenance;
 };
 export type RenderOperation = CopyFileOperation | WriteJsonOperation | MergeJsonOperation | WriteTextOperation | WriteTextFromFragmentsOperation | WriteTextTemplateOperation | SetExecutableOperation | ReplaceAnchorsOperation;
 export type RenderProjectOptions = {
-    sourceRoot: string;
-    sourceRoots?: Record<string, string> | undefined;
     targetRoot: string;
     variables?: RenderVariables | undefined;
     operations: RenderOperation[];
 };
 export declare function renderProject(options: RenderProjectOptions): Promise<void>;
+/**
+ * Applies a follow-up plan in a sibling staging directory.  In particular,
+ * metadata updates cannot become visible when a later source operation fails.
+ */
+export declare function renderProjectAtomically(options: RenderProjectOptions): Promise<void>;
 export declare function renderNewProject(options: RenderProjectOptions): Promise<void>;
 export {};