@ykdz/template 0.0.31 → 0.0.33

package/node_modules/@ykdz/template-core/dist/development-container-tool-layer.js

@@ -0,0 +1,361 @@
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveTemplateSource, } from "./renderer.js";
+function hasContinuation(line, escapeCharacter) {
+    const trimmed = line.trimEnd();
+    let escapeCount = 0;
+    for (let index = trimmed.length - 1; index >= 0 && trimmed[index] === escapeCharacter; index -= 1) {
+        escapeCount += 1;
+    }
+    return escapeCount % 2 === 1;
+}
+function parseLogicalDockerfileInstructions(text, sourceFile) {
+    const instructions = [];
+    let escapeCharacter = "\\";
+    let logicalLine = "";
+    for (const physicalLine of text.split(/\r?\n/u)) {
+        const trimmed = physicalLine.trim();
+        if (logicalLine.length === 0 && trimmed.startsWith("#")) {
+            const escapeDirective = trimmed.match(/^#\s*escape\s*=\s*([\\`])\s*$/iu);
+            if (escapeDirective?.[1] !== undefined) {
+                escapeCharacter = escapeDirective[1];
+            }
+            continue;
+        }
+        if (trimmed.length === 0 || trimmed.startsWith("#")) {
+            continue;
+        }
+        const continuation = hasContinuation(physicalLine, escapeCharacter);
+        const physicalContent = continuation
+            ? physicalLine.trimEnd().slice(0, -1)
+            : physicalLine;
+        logicalLine += physicalContent.trimStart();
+        if (continuation) {
+            continue;
+        }
+        const match = logicalLine.match(/^([A-Za-z]+)(?:[ \t]+(.*))?$/u);
+        if (match?.[1] === undefined) {
+            throw new Error(`Development Container Dockerfile fragment ${sourceFile} contains an invalid logical instruction: ${logicalLine}`);
+        }
+        instructions.push({
+            name: match[1].toUpperCase(),
+            arguments: match[2] ?? "",
+        });
+        logicalLine = "";
+    }
+    if (logicalLine.length > 0) {
+        throw new Error(`Development Container Dockerfile fragment ${sourceFile} ends with an unterminated line continuation.`);
+    }
+    return instructions;
+}
+function instructionNames(instructions, instruction) {
+    return new Set(instructions
+        .filter(({ name }) => name === instruction)
+        .map(({ arguments: value }) => value.trim().split(/[\s=]/u)[0])
+        .filter((name) => name.length > 0));
+}
+function dockerfileWords(value) {
+    const words = [];
+    let word = "";
+    let quote;
+    let escaped = false;
+    for (const character of value) {
+        if (escaped) {
+            word += character;
+            escaped = false;
+            continue;
+        }
+        if (character === "\\" && quote !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quote !== undefined) {
+            if (character === quote) {
+                quote = undefined;
+            }
+            else {
+                word += character;
+            }
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (/\s/u.test(character)) {
+            if (word.length > 0) {
+                words.push(word);
+                word = "";
+            }
+            continue;
+        }
+        word += character;
+    }
+    if (escaped) {
+        word += "\\";
+    }
+    if (word.length > 0) {
+        words.push(word);
+    }
+    return words;
+}
+function environmentNames(instructions) {
+    const names = new Set();
+    for (const instruction of instructions) {
+        if (instruction.name !== "ENV") {
+            continue;
+        }
+        const words = dockerfileWords(instruction.arguments);
+        const first = words[0];
+        if (first === undefined) {
+            continue;
+        }
+        if (!first.includes("=")) {
+            names.add(first);
+            continue;
+        }
+        for (const assignment of words) {
+            const separator = assignment.indexOf("=");
+            if (separator > 0) {
+                names.add(assignment.slice(0, separator));
+            }
+        }
+    }
+    return names;
+}
+function validateDockerfileFragment(fragment) {
+    if (!fragment.from.endsWith(".Dockerfile")) {
+        throw new Error(`Development Container Tool Layer ${fragment.identity} must reference checked .Dockerfile template source; received ${fragment.from}.`);
+    }
+    const instructions = parseLogicalDockerfileInstructions(fragment.text, fragment.from);
+    const allowedInstructions = fragment.kind === "base"
+        ? new Set(["ARG", "ENV", "FROM", "RUN", "SHELL"])
+        : new Set(["ARG", "ENV", "RUN"]);
+    for (const instruction of instructions) {
+        if (!allowedInstructions.has(instruction.name)) {
+            const role = fragment.kind === "base" ? "base" : "optional";
+            const allowed = fragment.kind === "base"
+                ? "ARG, ENV, FROM, RUN, and SHELL"
+                : "ARG, ENV, and RUN";
+            throw new Error(`Development Container Tool Layer ${fragment.identity} ${role} fragment ${fragment.from} must not use Dockerfile instruction ${instruction.name}; allowed instructions are ${allowed}.`);
+        }
+    }
+    if (fragment.kind === "base") {
+        const fromCount = instructions.filter((instruction) => instruction.name === "FROM").length;
+        if (fromCount !== 1) {
+            throw new Error(`Development Container Tool Layer ${fragment.identity} base fragment ${fragment.from} must contain exactly one FROM instruction; found ${fromCount}.`);
+        }
+    }
+    return instructions;
+}
+export function validateDevelopmentContainerDockerfileFragments(options) {
+    validateDockerfileFragment({ ...options.baseFragment, kind: "base" });
+    for (const fragment of options.fragments ?? []) {
+        validateDockerfileFragment({ ...fragment, kind: "optional" });
+    }
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function assertDockerfileTemplateSource(layer) {
+    if (!layer.dockerfile.from.endsWith(".Dockerfile")) {
+        throw new Error(`Development Container Tool Layer ${layer.identity} must reference checked .Dockerfile template source; received ${layer.dockerfile.from}.`);
+    }
+}
+function normalizeLayer(layer) {
+    assertDockerfileTemplateSource(layer);
+    const buildArgumentNames = new Set();
+    for (const argument of layer.buildArguments ?? []) {
+        if (buildArgumentNames.has(argument.name)) {
+            throw new Error(`Development Container Tool Layer ${layer.identity} declares build argument ${argument.name} more than once.`);
+        }
+        buildArgumentNames.add(argument.name);
+    }
+    return {
+        ...layer,
+        requires: [...new Set(layer.requires ?? [])].toSorted(compareText),
+        buildArguments: [...(layer.buildArguments ?? [])].toSorted((left, right) => compareText(left.name, right.name) ||
+            compareText(left.value, right.value)),
+        mounts: [...(layer.mounts ?? [])]
+            .map((mount) => ({
+            ...mount,
+            target: path.posix.normalize(mount.target),
+        }))
+            .toSorted((left, right) => compareText(left.identity, right.identity) ||
+            compareText(left.target, right.target)),
+        probes: [...(layer.probes ?? [])]
+            .map((probe) => ({
+            ...probe,
+            args: [...(probe.args ?? [])],
+        }))
+            .toSorted((left, right) => compareText(left.identity, right.identity) ||
+            compareText(left.command, right.command) ||
+            compareText(JSON.stringify(left.args), JSON.stringify(right.args))),
+    };
+}
+function layerFingerprint(layer, kind) {
+    return JSON.stringify({
+        kind,
+        identity: layer.identity,
+        dockerfile: resolveTemplateSource(layer.dockerfile.source, layer.dockerfile.from),
+        requires: layer.requires,
+        buildArguments: layer.buildArguments,
+        mounts: layer.mounts,
+        probes: layer.probes,
+    });
+}
+function findDependencyCycle(layers) {
+    const byIdentity = new Map(layers.map((layer) => [layer.identity, layer]));
+    const complete = new Set();
+    const active = [];
+    const activeSet = new Set();
+    const visit = (identity) => {
+        if (activeSet.has(identity)) {
+            return active.slice(active.indexOf(identity)).toSorted(compareText);
+        }
+        if (complete.has(identity)) {
+            return undefined;
+        }
+        active.push(identity);
+        activeSet.add(identity);
+        const layer = byIdentity.get(identity);
+        for (const dependency of layer?.requires ?? []) {
+            if (!byIdentity.has(dependency)) {
+                continue;
+            }
+            const cycle = visit(dependency);
+            if (cycle !== undefined) {
+                return cycle;
+            }
+        }
+        active.pop();
+        activeSet.delete(identity);
+        complete.add(identity);
+        return undefined;
+    };
+    for (const identity of [...byIdentity.keys()].toSorted(compareText)) {
+        const cycle = visit(identity);
+        if (cycle !== undefined) {
+            return cycle;
+        }
+    }
+    return undefined;
+}
+function orderLayers(baseLayer, optionalLayers) {
+    const normalizedBase = normalizeLayer(baseLayer);
+    if ((normalizedBase.requires?.length ?? 0) > 0) {
+        throw new Error(`Development Container Tool Layer ${normalizedBase.identity} is the base foundation and must not require other layers.`);
+    }
+    const base = {
+        ...normalizedBase,
+        kind: "base",
+    };
+    const identities = new Map([[base.identity, layerFingerprint(base, "base")]]);
+    const uniqueOptionalLayers = [];
+    for (const layer of optionalLayers) {
+        const normalized = normalizeLayer(layer);
+        const fingerprint = layerFingerprint(normalized, "optional");
+        const previous = identities.get(normalized.identity);
+        if (previous === fingerprint) {
+            continue;
+        }
+        if (previous !== undefined) {
+            throw new Error(`Development Container Tool Layer identity ${normalized.identity} has conflicting descriptors.`);
+        }
+        identities.set(normalized.identity, fingerprint);
+        uniqueOptionalLayers.push(normalized);
+    }
+    for (const layer of uniqueOptionalLayers) {
+        for (const requiredIdentity of layer.requires ?? []) {
+            if (!identities.has(requiredIdentity)) {
+                throw new Error(`Development Container Tool Layer ${layer.identity} requires missing layer ${requiredIdentity}.`);
+            }
+        }
+    }
+    const cycle = findDependencyCycle(uniqueOptionalLayers);
+    if (cycle !== undefined) {
+        throw new Error(`Development Container Tool Layer dependency cycle involves: ${cycle.join(", ")}.`);
+    }
+    const remaining = uniqueOptionalLayers
+        .map((layer) => ({
+        ...layer,
+        kind: "optional",
+    }))
+        .toSorted((left, right) => compareText(left.identity, right.identity));
+    const ordered = [base];
+    const resolved = new Set([base.identity]);
+    while (remaining.length > 0) {
+        const readyIndex = remaining.findIndex((layer) => (layer.requires ?? []).every((identity) => resolved.has(identity)));
+        if (readyIndex === -1) {
+            throw new Error("Development Container Tool Layer dependencies cannot be resolved.");
+        }
+        const [next] = remaining.splice(readyIndex, 1);
+        if (next === undefined) {
+            throw new Error("Development Container Tool Layer dependency resolution failed.");
+        }
+        ordered.push(next);
+        resolved.add(next.identity);
+    }
+    return ordered;
+}
+function completeDevelopmentContainerToolLayerPlan(layers, fragmentTexts) {
+    const buildArgumentOwners = new Map();
+    const environmentOwners = new Map();
+    const mountIdentityOwners = new Map();
+    const mountTargetOwners = new Map();
+    for (const [index, layer] of layers.entries()) {
+        for (const mount of layer.mounts ?? []) {
+            const previousIdentityOwner = mountIdentityOwners.get(mount.identity);
+            if (previousIdentityOwner !== undefined) {
+                throw new Error(`Development Container Tool Layer mount identity ${mount.identity} is declared by both ${previousIdentityOwner} and ${layer.identity}.`);
+            }
+            const previousTargetOwner = mountTargetOwners.get(mount.target);
+            if (previousTargetOwner !== undefined) {
+                throw new Error(`Development Container Tool Layer mount target ${mount.target} is declared by both ${previousTargetOwner} and ${layer.identity}.`);
+            }
+            mountIdentityOwners.set(mount.identity, layer.identity);
+            mountTargetOwners.set(mount.target, layer.identity);
+        }
+        const instructions = validateDockerfileFragment({
+            identity: layer.identity,
+            kind: layer.kind,
+            from: layer.dockerfile.from,
+            text: fragmentTexts[index],
+        });
+        const declaredArguments = instructionNames(instructions, "ARG");
+        for (const name of declaredArguments) {
+            const previousOwner = buildArgumentOwners.get(name);
+            if (previousOwner !== undefined) {
+                throw new Error(`Development Container Tool Layer build argument ${name} is declared by both ${previousOwner} and ${layer.identity}.`);
+            }
+            buildArgumentOwners.set(name, layer.identity);
+        }
+        for (const name of environmentNames(instructions)) {
+            const previousOwner = environmentOwners.get(name);
+            if (previousOwner !== undefined) {
+                throw new Error(`Development Container Tool Layer environment ${name} is declared by both ${previousOwner} and ${layer.identity}.`);
+            }
+            environmentOwners.set(name, layer.identity);
+        }
+        for (const argument of layer.buildArguments ?? []) {
+            if (!declaredArguments.has(argument.name)) {
+                throw new Error(`Development Container Tool Layer ${layer.identity} supplies build argument ${argument.name}, but ${layer.dockerfile.from} does not declare it with ARG.`);
+            }
+        }
+    }
+    return {
+        layers,
+        buildArguments: layers.flatMap((layer) => layer.buildArguments ?? []),
+        mounts: layers.flatMap((layer) => layer.mounts ?? []),
+        probes: layers.flatMap((layer) => layer.probes ?? []),
+    };
+}
+export function planDevelopmentContainerToolLayersSync(options) {
+    const layers = orderLayers(options.baseLayer, options.layers ?? []);
+    return completeDevelopmentContainerToolLayerPlan(layers, layers.map((layer) => readFileSync(resolveTemplateSource(layer.dockerfile.source, layer.dockerfile.from), "utf8")));
+}
+export async function planDevelopmentContainerToolLayers(options) {
+    const layers = orderLayers(options.baseLayer, options.layers ?? []);
+    return completeDevelopmentContainerToolLayerPlan(layers, await Promise.all(layers.map((layer) => readFile(resolveTemplateSource(layer.dockerfile.source, layer.dockerfile.from), "utf8"))));
+}

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

@@ -1,8 +1,10 @@
+import { type CiDiagnosticArtifactDeclaration } from "./ci-diagnostic-artifact.ts";
+import type { DevelopmentContainerToolLayer } from "./development-container-tool-layer.ts";
 import type { EditorCustomizationCapability } from "./editor-customization.ts";
 import type { CheckEnvironmentNeed, DeploymentEnvironmentNeed } from "./module-graph.ts";
 import type { PackageDefinition } from "./project-blueprint-v2.ts";
 import type { DependencyMaintenancePolicy } from "./project-github.ts";
-import type { RenderOperation } from "./renderer.ts";
+import type { RenderOperation, TemplateSourceHandle } from "./renderer.ts";
 export type FoundationContribution = {
     /** Toolchains the Foundation must install and project into coordinated root files. */
     readonly toolchains: {
@@ -19,6 +21,16 @@ export type FoundationContribution = {
     readonly workspacePackageGlobs?: readonly string[];
     /** Dependency Catalog entries required by package-owned manifests. */
     readonly dependencyCatalog?: Readonly<Record<string, string>>;
+    /** Source-backed Development Container capabilities coordinated by Foundation. */
+    readonly developmentContainerToolLayers?: readonly DevelopmentContainerToolLayer[] | undefined;
+    /** Source-backed coordinated files projected by Foundation. */
+    readonly templateFiles?: readonly {
+        readonly identity: string;
+        readonly source: TemplateSourceHandle;
+        readonly from: string;
+        readonly to: string;
+        readonly replacements?: Readonly<Record<string, string>> | undefined;
+    }[] | undefined;
 };
 /** A preset-agnostic package-sized part of a Generated Repository Plan. */
 export type PackageContribution = {
@@ -32,6 +44,8 @@ export type PackageContribution = {
     /** Typed requirements consumed by the Foundation for coordinated root outputs. */
     readonly foundation: FoundationContribution;
     readonly environmentNeeds: readonly CheckEnvironmentNeed[];
+    /** Closed native CI evidence owned by this Package Boundary. */
+    readonly ciDiagnosticArtifacts?: readonly CiDiagnosticArtifactDeclaration[];
     /** Requirements prepared only by a focused deployment entrypoint. */
     readonly deploymentEnvironmentNeeds?: readonly DeploymentEnvironmentNeed[];
 };

package/node_modules/@ykdz/template-core/dist/package-contribution.js

@@ -1,3 +1,4 @@
+import { assertCiDiagnosticArtifactDeclaration, } from "./ci-diagnostic-artifact.js";
 const operationPath = (operation) => {
     if ("to" in operation)
         return operation.to;
@@ -20,5 +21,11 @@ export function assertPackageContribution(contribution, provenance = {}) {
             : `${provenance.definitionName}: ${provenance.planner ?? "Package Contribution"} `;
         throw new Error(`${owner}${rule}; ${contribution.definition.path} attempted ${target}`);
     }
+    for (const artifact of contribution.ciDiagnosticArtifacts ?? []) {
+        const declaration = assertCiDiagnosticArtifactDeclaration(artifact);
+        if (declaration.owner.path !== contribution.definition.path) {
+            throw new Error(`CI Diagnostic Artifact owner must match its Package Contribution: ${contribution.definition.path}`);
+        }
+    }
     return contribution;
 }

package/node_modules/@ykdz/template-core/dist/pnpm-workspace.yaml

@@ -21,6 +21,7 @@ overrides:
   "vue>typescript": "-"
 
 catalog:
+  "@devcontainers/cli": 0.88.0
   "@hono/node-server": ^2.0.12
   "@playwright/test": ^1.61.1
   "@tailwindcss/vite": ^4.3.3

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

@@ -1,17 +1,52 @@
-import { type CheckEnvironmentNeed, type DeploymentEnvironmentNeed } from "./module-graph.ts";
+import { type CiDiagnosticArtifactDeclaration } from "./ci-diagnostic-artifact.ts";
+import type { DeploymentEnvironmentNeed } from "./module-graph.ts";
 export type CiCapability = {
     readonly workflowName: "Check";
     readonly jobName: "check";
+    readonly jobDisplayName: "Root Check";
     readonly runner: "ubuntu-latest";
+    readonly timeoutMinutes: 30;
 };
 export type CiEnvironmentPreparation = {
     readonly nodeFromPackageMetadata: boolean;
-    readonly rustToolchain: boolean;
+    readonly packageManagerFromPackageMetadata: boolean;
+    readonly pnpmStoreCache: boolean;
 };
 export type PnpmTaskLayer = {
-    readonly installCommand: "pnpm install";
+    readonly installCommand: "pnpm install --frozen-lockfile";
     readonly checkCommand: "pnpm run check";
 };
+export type CiCheckMatrixEntry = {
+    readonly capability: "root" | "deployment";
+    readonly jobDisplayName: "Root Check" | "Deployment Check";
+    readonly taskEntrypoint: "pnpm run check" | "pnpm run check:deployment";
+    readonly timeoutMinutes: 30 | 45;
+    readonly requiresDocker: boolean;
+};
+export type ProjectCheckWorkflowPlan = {
+    readonly workflowName: "Check";
+    readonly triggers: {
+        readonly pullRequest: true;
+        readonly pushBranches: readonly ["main"];
+    };
+    readonly permissions: {
+        readonly contents: "read";
+    };
+    readonly concurrency: {
+        readonly group: "${{ github.workflow }}-${{ github.ref }}";
+        readonly cancelInProgress: true;
+    };
+    readonly rootCheck: CiCapability;
+    readonly matrix: {
+        readonly failFast: false;
+        readonly include: readonly CiCheckMatrixEntry[];
+    } | undefined;
+    readonly environmentPreparation: CiEnvironmentPreparation;
+    readonly taskLayer: PnpmTaskLayer;
+    /** Actual Package Boundaries allowed to own retained native diagnostics. */
+    readonly packagePaths: readonly string[];
+    readonly diagnosticArtifacts: readonly CiDiagnosticArtifactDeclaration[];
+};
 export type DependencyEcosystem = "npm" | "cargo" | "github-actions" | "docker" | "rust-toolchain";
 export type DependabotDirectory = `/${string}`;
 export type DependencyMaintenancePolicy = {
@@ -20,26 +55,27 @@ export type DependencyMaintenancePolicy = {
     readonly extraDirectories?: Partial<Record<DependencyEcosystem, readonly DependabotDirectory[]>>;
     readonly interval: "weekly";
 };
-type ProjectCheckWorkflowOptions = {
-    readonly environment: {
-        readonly needs: readonly CheckEnvironmentNeed[];
-    };
+export type ProjectCheckWorkflowDiagnosticOptions = {
+    /** Package Paths from the real Project Blueprint or Package Contributions. */
+    readonly packagePaths: readonly string[];
+    readonly diagnosticArtifacts?: readonly unknown[] | undefined;
+};
+type ProjectCheckWorkflowOptions = ProjectCheckWorkflowDiagnosticOptions & {
     readonly deploymentEnvironmentNeeds?: readonly DeploymentEnvironmentNeed[];
     readonly hasDeploymentTask?: boolean | undefined;
     readonly capability?: CiCapability | undefined;
     readonly environmentPreparation?: Partial<CiEnvironmentPreparation> | undefined;
     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 environment: {
-        readonly needs: readonly CheckEnvironmentNeed[];
-    };
+/** Capability facts for the Foundation-owned GitHub Actions Template Source. */
+export declare function projectCheckWorkflowPlan(options: ProjectCheckWorkflowOptions): ProjectCheckWorkflowPlan;
+/** Selects a complete Foundation-owned workflow Template Source. */
+export declare function projectCheckWorkflowTemplateSource(options: ProjectCheckWorkflowDiagnosticOptions & {
     readonly deploymentEnvironmentNeeds?: readonly DeploymentEnvironmentNeed[];
     readonly hasDeploymentTask?: boolean | undefined;
-    readonly environmentPreparation?: Partial<CiEnvironmentPreparation>;
-}): Record<string, string>;
+}): ".github/workflows/check.yml" | ".github/workflows/check-diagnostics.yml" | ".github/workflows/check-deployment.yml" | ".github/workflows/check-deployment-diagnostics.yml";
+/** Limited, validated facts for static Foundation diagnostic staging. */
+export declare function projectCheckWorkflowTemplateReplacements(options: ProjectCheckWorkflowDiagnosticOptions): 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>;