@ykdz/template 0.0.32 → 0.0.35

package/node_modules/@ykdz/template-builtin-presets/templates/vike-app/web/playwright.config.ts

@@ -1,6 +1,18 @@
+import { execFileSync } from "node:child_process";
+import { rmSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { defineConfig, devices } from "@playwright/test";
 
 const externalBaseUrlName = "PLAYWRIGHT_EXTERNAL_BASE_URL";
+const externalReadinessTimeoutMs = 30_000;
+const webRoot = path.dirname(fileURLToPath(import.meta.url));
+const migrationsRoot = path.resolve(webRoot, "../../packages/db-migrations");
+const databaseFile = path.join(webRoot, "node_modules/.tmp/e2e.sqlite");
+const stateFile = path.join(webRoot, "node_modules/.tmp/playwright-port");
 
 function externalBaseUrl(): string | undefined {
   if (!Object.hasOwn(process.env, externalBaseUrlName)) {
@@ -26,31 +38,98 @@ function externalBaseUrl(): string | undefined {
   return url.toString();
 }
 
-function requiredPort(name: string): number {
-  return Number(requiredEnv(name));
+async function availablePort(): Promise<string> {
+  return await new Promise((resolve, reject) => {
+    const server = createServer();
+
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+
+      if (typeof address !== "object" || address === null) {
+        server.close(() => {
+          reject(new Error("Could not allocate a Playwright web port"));
+        });
+        return;
+      }
+
+      const port = String(address.port);
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+
+        resolve(port);
+      });
+    });
+  });
 }
 
-function requiredEnv(name: string): string {
-  const value = process.env[name];
+async function awaitExternalService(baseUrl: string): Promise<void> {
+  const deadline = Date.now() + externalReadinessTimeoutMs;
 
-  if (!value) {
-    throw new Error(`${name} must be set by scripts/run-playwright.ts`);
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(baseUrl, {
+        signal: AbortSignal.timeout(2_000),
+      });
+      if (response.ok) {
+        return;
+      }
+    } catch {
+      // The externally managed service may still be starting.
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 250));
   }
 
-  return value;
+  throw new Error(
+    `External Playwright service at ${baseUrl} was not ready within ${externalReadinessTimeoutMs}ms`,
+  );
+}
+
+async function sharedPort(envName: string): Promise<{
+  readonly port: string;
+  readonly prepared: boolean;
+}> {
+  const envPort = process.env[envName];
+  if (envPort !== undefined) {
+    return { port: envPort, prepared: false };
+  }
+  try {
+    return { port: await readFile(stateFile, "utf8"), prepared: false };
+  } catch {
+    const port = await availablePort();
+    await mkdir(path.dirname(stateFile), { recursive: true });
+    await writeFile(stateFile, port, "utf8");
+    return { port, prepared: true };
+  }
+}
+
+function prepareLocalDatabase(): void {
+  rmSync(databaseFile, { force: true });
+  execFileSync("pnpm", ["run", "db:push"], {
+    cwd: migrationsRoot,
+    env: { ...process.env, DATABASE_FILE: databaseFile },
+    stdio: "inherit",
+  });
 }
 
 const externalServiceUrl = externalBaseUrl();
-const previewPort = externalServiceUrl
-  ? undefined
-  : requiredPort("PLAYWRIGHT_WEB_PORT");
-const previewUrl = externalServiceUrl ?? `http://127.0.0.1:${previewPort}`;
-const databaseFile = externalServiceUrl
-  ? undefined
-  : requiredEnv("DATABASE_FILE");
-
-function shellValue(value: string): string {
-  return `'${value.replaceAll("'", "'\\''")}'`;
+let previewUrl: string;
+
+if (externalServiceUrl === undefined) {
+  const { port, prepared } = await sharedPort("PLAYWRIGHT_WEB_PORT");
+  previewUrl = `http://127.0.0.1:${port}`;
+  process.env.DATABASE_FILE = databaseFile;
+  process.env.PORT = port;
+  if (prepared) {
+    prepareLocalDatabase();
+  }
+} else {
+  previewUrl = externalServiceUrl;
+  await awaitExternalService(externalServiceUrl);
 }
 
 export default defineConfig({
@@ -60,16 +139,18 @@ export default defineConfig({
     baseURL: previewUrl,
     trace: "retain-on-failure",
   },
-  ...(externalServiceUrl
-    ? {}
-    : {
+  reporter: [["list"], ["html"]],
+  globalTeardown: "./test/playwright-teardown.ts",
+  ...(externalServiceUrl === undefined
+    ? {
         webServer: {
-          command: `DATABASE_FILE=${shellValue(databaseFile!)} pnpm --dir ../../packages/db-migrations run db:prepare:test && PORT=${previewPort} node dist/server/index.mjs`,
+          command: "node dist/server/index.mjs",
           reuseExistingServer: !process.env.CI,
           timeout: 60_000,
           url: previewUrl,
         },
-      }),
+      }
+    : {}),
   projects: [
     {
       name: "chromium",

package/node_modules/@ykdz/template-builtin-presets/templates/vike-app/web/test/playwright-teardown.ts

@@ -0,0 +1,12 @@
+import { rmSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const webRoot = path.dirname(fileURLToPath(import.meta.url));
+
+export default function teardown(): void {
+  rmSync(path.join(webRoot, "node_modules/.tmp/e2e.sqlite"), { force: true });
+  rmSync(path.join(webRoot, "node_modules/.tmp/playwright-port"), {
+    force: true,
+  });
+}

package/node_modules/@ykdz/template-builtin-presets/templates/vike-app/web/vite.config.ts

@@ -1,12 +1,50 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
 import tailwindcss from "@tailwindcss/vite";
 import vue from "@vitejs/plugin-vue";
 import telefunc from "telefunc/vite";
 import vike from "vike/plugin";
 import { defineConfig, type PluginOption } from "vite";
 
+const webRoot = path.dirname(fileURLToPath(import.meta.url));
+const migrationsRoot = path.resolve(webRoot, "../../packages/db-migrations");
+const databaseRoot = path.resolve(webRoot, "../../packages/db");
+const databaseFile = path.join(webRoot, "data/app.sqlite");
+
 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- telefunc/vite currently types its plugin factory as any.
 const telefuncPlugin = telefunc() as PluginOption;
 
+async function prepareDatabase(): Promise<void> {
+  const env = { ...process.env, DATABASE_FILE: databaseFile };
+  process.env.DATABASE_FILE = databaseFile;
+  execFileSync("pnpm", ["run", "db:push"], {
+    cwd: migrationsRoot,
+    env,
+    stdio: "inherit",
+  });
+  execFileSync("pnpm", ["run", "db:seed:example"], {
+    cwd: databaseRoot,
+    env,
+    stdio: "inherit",
+  });
+}
+
+function databasePreparationPlugin(): PluginOption {
+  return {
+    name: "database-preparation",
+    configureServer: () => prepareDatabase(),
+    configurePreviewServer: () => prepareDatabase(),
+  };
+}
+
 export default defineConfig({
-  plugins: [vike(), telefuncPlugin, vue(), tailwindcss()],
+  plugins: [
+    vike(),
+    telefuncPlugin,
+    vue(),
+    tailwindcss(),
+    databasePreparationPlugin(),
+  ],
 });

package/node_modules/@ykdz/template-builtin-presets/templates/vue-app/playwright.config.ts

@@ -1,24 +1,66 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { defineConfig, devices } from "@playwright/test";
 
-function requiredPort(name: string): number {
-  const value = process.env[name];
+const webRoot = path.dirname(fileURLToPath(import.meta.url));
+const stateFile = path.join(webRoot, "node_modules/.tmp/playwright-port");
 
-  if (!value) {
-    throw new Error(`${name} must be set by scripts/run-playwright.ts`);
-  }
+async function availablePort(): Promise<string> {
+  return await new Promise((resolve, reject) => {
+    const server = createServer();
+
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+
+      if (typeof address !== "object" || address === null) {
+        server.close(() => {
+          reject(new Error("Could not allocate a Playwright web port"));
+        });
+        return;
+      }
+
+      const port = String(address.port);
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
 
-  return Number(value);
+        resolve(port);
+      });
+    });
+  });
+}
+
+async function sharedPort(envName: string): Promise<string> {
+  const envPort = process.env[envName];
+  if (envPort !== undefined) {
+    return envPort;
+  }
+  try {
+    return await readFile(stateFile, "utf8");
+  } catch {
+    const port = await availablePort();
+    await mkdir(path.dirname(stateFile), { recursive: true });
+    await writeFile(stateFile, port, "utf8");
+    return port;
+  }
 }
 
-const previewPort = requiredPort("PLAYWRIGHT_WEB_PORT");
+const previewPort = await sharedPort("PLAYWRIGHT_WEB_PORT");
 const previewUrl = `http://127.0.0.1:${previewPort}`;
 
 export default defineConfig({
   testDir: "./test/e2e",
   use: {
     baseURL: previewUrl,
-    trace: "on-first-retry",
+    trace: "retain-on-failure",
   },
+  reporter: [["list"], ["html"]],
   webServer: {
     command: `pnpm run preview --host 127.0.0.1 --port ${previewPort}`,
     reuseExistingServer: !process.env.CI,

package/node_modules/@ykdz/template-builtin-presets/templates/vue-hono-app/web/playwright.config.ts

@@ -1,17 +1,68 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { defineConfig, devices } from "@playwright/test";
 
-function requiredPort(name: string): number {
-  const value = process.env[name];
+const webRoot = path.dirname(fileURLToPath(import.meta.url));
+const stateFile = path.join(webRoot, "node_modules/.tmp/playwright-ports");
 
-  if (!value) {
-    throw new Error(`${name} must be set by scripts/run-playwright.ts`);
-  }
+async function availablePort(): Promise<string> {
+  return await new Promise((resolve, reject) => {
+    const server = createServer();
+
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+
+      if (typeof address !== "object" || address === null) {
+        server.close(() => {
+          reject(new Error("Could not allocate a Playwright web port"));
+        });
+        return;
+      }
+
+      const port = String(address.port);
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
 
-  return Number(value);
+        resolve(port);
+      });
+    });
+  });
+}
+
+async function sharedPorts(): Promise<{
+  readonly api: string;
+  readonly web: string;
+}> {
+  const envApi = process.env.PLAYWRIGHT_API_PORT;
+  const envWeb = process.env.PLAYWRIGHT_WEB_PORT;
+  if (envApi !== undefined && envWeb !== undefined) {
+    return { api: envApi, web: envWeb };
+  }
+  try {
+    const parsed = JSON.parse(await readFile(stateFile, "utf8")) as {
+      readonly api: string;
+      readonly web: string;
+    };
+    return parsed;
+  } catch {
+    const ports = {
+      api: envApi ?? (await availablePort()),
+      web: envWeb ?? (await availablePort()),
+    };
+    await mkdir(path.dirname(stateFile), { recursive: true });
+    await writeFile(stateFile, JSON.stringify(ports), "utf8");
+    return ports;
+  }
 }
 
-const apiPort = requiredPort("PLAYWRIGHT_API_PORT");
-const webPort = requiredPort("PLAYWRIGHT_WEB_PORT");
+const { api: apiPort, web: webPort } = await sharedPorts();
 const apiBaseUrl = `http://127.0.0.1:${apiPort}`;
 const apiHealthUrl = `${apiBaseUrl}/api/health`;
 const webBaseUrl = `http://127.0.0.1:${webPort}`;
@@ -20,8 +71,10 @@ export default defineConfig({
   testDir: "./test/e2e",
   use: {
     baseURL: webBaseUrl,
+    trace: "retain-on-failure",
     ...devices["Desktop Chrome"],
   },
+  reporter: [["list"], ["html"]],
   webServer: [
     {
       command: `PORT=${apiPort} pnpm --dir ../api run start`,

package/node_modules/@ykdz/template-core/dist/ci-diagnostic-artifact.d.ts

@@ -0,0 +1,19 @@
+import type { PackageBoundaryOwner } from "./module-graph.ts";
+/** Closed, owner-scoped native evidence a Package Contribution may retain in CI. */
+export type CiDiagnosticArtifactDeclaration = {
+    readonly kind: "playwright";
+    readonly owner: PackageBoundaryOwner;
+};
+/**
+ * Validates the intentionally closed diagnostic declaration surface.  It does
+ * not accept paths: native paths are derived only after the owner is known.
+ */
+export declare function assertCiDiagnosticArtifactDeclaration(value: unknown): CiDiagnosticArtifactDeclaration;
+/**
+ * Composes closed native diagnostics independently of presets and environment
+ * preparation. Equivalent declarations collapse into stable owner order.
+ */
+export declare function composeCiDiagnosticArtifacts(options: {
+    readonly packagePaths: readonly string[];
+    readonly declarations: readonly unknown[];
+}): readonly CiDiagnosticArtifactDeclaration[];

package/node_modules/@ykdz/template-core/dist/ci-diagnostic-artifact.js

@@ -0,0 +1,68 @@
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    const actual = Object.keys(value).toSorted();
+    const expected = [...keys].toSorted();
+    return (actual.length === expected.length &&
+        actual.every((key, index) => key === expected[index]));
+}
+const reservedWorkspaceCollections = new Set([
+    ".git",
+    ".github",
+    ".devcontainer",
+    ".template",
+    "node_modules",
+    "dist",
+    "target",
+]);
+function isSafePackagePath(value) {
+    return (/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/u.test(value) &&
+        !reservedWorkspaceCollections.has(value.split("/", 1)[0]));
+}
+/**
+ * Validates the intentionally closed diagnostic declaration surface.  It does
+ * not accept paths: native paths are derived only after the owner is known.
+ */
+export function assertCiDiagnosticArtifactDeclaration(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ["kind", "owner"])) {
+        throw new Error("CI Diagnostic Artifact declarations may contain only kind and owner");
+    }
+    if (value.kind !== "playwright") {
+        throw new Error("Unsupported CI Diagnostic Artifact kind");
+    }
+    if (!isRecord(value.owner) || !hasExactKeys(value.owner, ["kind", "path"])) {
+        throw new Error("CI Diagnostic Artifact requires a Package Boundary owner");
+    }
+    if (value.owner.kind !== "package-boundary" ||
+        typeof value.owner.path !== "string" ||
+        !isSafePackagePath(value.owner.path)) {
+        throw new Error("CI Diagnostic Artifact owner has an unsafe Package Boundary path");
+    }
+    return {
+        kind: "playwright",
+        owner: { kind: "package-boundary", path: value.owner.path },
+    };
+}
+/**
+ * Composes closed native diagnostics independently of presets and environment
+ * preparation. Equivalent declarations collapse into stable owner order.
+ */
+export function composeCiDiagnosticArtifacts(options) {
+    for (const packagePath of options.packagePaths) {
+        if (!isSafePackagePath(packagePath)) {
+            throw new Error(`CI Diagnostic Artifact Package Boundary path is unsafe: ${packagePath}`);
+        }
+    }
+    const owners = new Set(options.packagePaths);
+    const artifacts = new Map();
+    for (const value of options.declarations) {
+        const declaration = assertCiDiagnosticArtifactDeclaration(value);
+        if (!owners.has(declaration.owner.path)) {
+            throw new Error(`CI Diagnostic Artifact owner is not a declared Package Boundary: ${declaration.owner.path}`);
+        }
+        const key = `${declaration.kind}:${declaration.owner.path}`;
+        artifacts.set(key, declaration);
+    }
+    return [...artifacts.values()].toSorted((left, right) => left.owner.path.localeCompare(right.owner.path));
+}

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

@@ -1,3 +1,4 @@
+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";
@@ -43,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/project-github.d.ts

@@ -1,16 +1,52 @@
+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 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 = {
@@ -19,19 +55,27 @@ export type DependencyMaintenancePolicy = {
     readonly extraDirectories?: Partial<Record<DependencyEcosystem, readonly DependabotDirectory[]>>;
     readonly interval: "weekly";
 };
-type ProjectCheckWorkflowOptions = {
+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: {
+/** 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;
-}): 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>;