@cosmicdrift/kumiko-dev-server 0.369.0 → 0.371.0

package/dist/managed-files/index.d.ts

@@ -0,0 +1,8 @@
+export { listAppPorts } from "@cosmicdrift/kumiko-framework/config";
+export { type AppScriptsReport, checkAppScripts, KNOWN_EXTRA_APP_SCRIPTS, PREPARE_SCRIPT, STANDARD_APP_SCRIPTS, type StandardAppScript, } from "./app-scripts.ts";
+export { checkManagedFiles, isManagedDrift, type ManagedCheckResult, type ManagedFileReport, type ManagedFileState, } from "./check.ts";
+export { addManagedMarker, MANAGED_MARKER, readManagedMarker, stripManagedMarker, } from "./marker.ts";
+export { findPortCollisions, type PortClaim, type PortCollision, type ScannedApp, scanWorkspaceApps, } from "./port-registry.ts";
+export { BIOME_PRESET, listManagedFiles, type ManagedAppFacts, type ManagedAppInput, type ManagedFile, type ManagedTemplateFile, renderBiomePresetJson, renderManagedBunfig, renderManagedTemplates, renderTsconfigPresetJson, resolveManagedAppFacts, TSCONFIG_PRESET, } from "./registry.ts";
+export { parseStaticAppConfig, readStaticAppConfig, type StaticAppConfig, } from "./static-app-config.ts";
+export { type SyncAction, type SyncManagedOptions, syncManagedFiles } from "./sync.ts";

package/dist/managed-files/index.js

@@ -0,0 +1,8 @@
+export { listAppPorts } from "@cosmicdrift/kumiko-framework/config";
+export { checkAppScripts, KNOWN_EXTRA_APP_SCRIPTS, PREPARE_SCRIPT, STANDARD_APP_SCRIPTS, } from "./app-scripts.js";
+export { checkManagedFiles, isManagedDrift, } from "./check.js";
+export { addManagedMarker, MANAGED_MARKER, readManagedMarker, stripManagedMarker, } from "./marker.js";
+export { findPortCollisions, scanWorkspaceApps, } from "./port-registry.js";
+export { BIOME_PRESET, listManagedFiles, renderBiomePresetJson, renderManagedBunfig, renderManagedTemplates, renderTsconfigPresetJson, resolveManagedAppFacts, TSCONFIG_PRESET, } from "./registry.js";
+export { parseStaticAppConfig, readStaticAppConfig, } from "./static-app-config.js";
+export { syncManagedFiles } from "./sync.js";

package/dist/managed-files/jsonc.d.ts

@@ -0,0 +1 @@
+export declare function parseJsonc(source: string, context: string): unknown;

package/dist/managed-files/jsonc.js

@@ -0,0 +1,12 @@
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+// Strings come first in each alternation, so comment and comma patterns
+// inside string literals are matched as part of the string and kept.
+const STRING_OR_COMMENT = /"(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\//g;
+const STRING_OR_TRAILING_COMMA = /"(?:\\.|[^"\\])*"|,(\s*[}\]])/g;
+// biome.json and tsconfig.json accept comments and trailing commas; strip both
+// (outside strings) so they parse as JSON.
+export function parseJsonc(source, context) {
+    const withoutComments = source.replace(STRING_OR_COMMENT, (match) => match.startsWith('"') ? match : "");
+    const withoutTrailingCommas = withoutComments.replace(STRING_OR_TRAILING_COMMA, (match, afterComma) => afterComma ?? match);
+    return parseJsonOrThrow(withoutTrailingCommas, context);
+}

package/dist/managed-files/line-diff.d.ts

@@ -0,0 +1,2 @@
+/** `-` lines are what the template expects, `+` lines what the repo has. */
+export declare function renderLineDiff(expected: string, actual: string): string;

package/dist/managed-files/line-diff.js

@@ -0,0 +1,60 @@
+// Unified-style line diff for drift reports. Managed files are a few hundred
+// lines at most, so the quadratic LCS table stays small.
+const CONTEXT_LINES = 2;
+function buildLcsTable(expected, actual) {
+    const cols = actual.length + 1;
+    const table = new Uint32Array((expected.length + 1) * cols);
+    const lengthAt = (i, j) => table[i * cols + j] ?? 0;
+    for (let i = expected.length - 1; i >= 0; i--) {
+        for (let j = actual.length - 1; j >= 0; j--) {
+            table[i * cols + j] =
+                expected[i] === actual[j]
+                    ? lengthAt(i + 1, j + 1) + 1
+                    : Math.max(lengthAt(i + 1, j), lengthAt(i, j + 1));
+        }
+    }
+    return { lengthAt };
+}
+function nextOp(left, right, dropLeftKeepsLonger) {
+    if (left !== undefined && left === right)
+        return { kind: " ", line: left };
+    if (right === undefined || (left !== undefined && dropLeftKeepsLonger))
+        return { kind: "-", line: left ?? "" };
+    return { kind: "+", line: right };
+}
+function diffOps(expected, actual) {
+    const lcs = buildLcsTable(expected, actual);
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < expected.length || j < actual.length) {
+        const op = nextOp(expected[i], actual[j], lcs.lengthAt(i + 1, j) >= lcs.lengthAt(i, j + 1));
+        ops.push(op);
+        if (op.kind !== "+")
+            i++;
+        if (op.kind !== "-")
+            j++;
+    }
+    return ops;
+}
+/** `-` lines are what the template expects, `+` lines what the repo has. */
+export function renderLineDiff(expected, actual) {
+    const ops = diffOps(expected.split("\n"), actual.split("\n"));
+    const keep = ops.map((_op, index) => ops
+        .slice(Math.max(0, index - CONTEXT_LINES), index + CONTEXT_LINES + 1)
+        .some((near) => near.kind !== " "));
+    const out = [];
+    let skipped = false;
+    for (const [index, op] of ops.entries()) {
+        if (keep[index]) {
+            if (skipped && out.length > 0)
+                out.push("...");
+            skipped = false;
+            out.push(`${op.kind} ${op.line}`);
+        }
+        else {
+            skipped = true;
+        }
+    }
+    return out.join("\n");
+}

package/dist/managed-files/marker.d.ts

@@ -0,0 +1,17 @@
+export declare const MANAGED_MARKER = "kumiko-managed";
+export type MarkerCommentStyle = "#" | "//";
+export type ManagedMarker = {
+    readonly kind: "managed";
+} | {
+    readonly kind: "local";
+    readonly reason: string;
+} | {
+    readonly kind: "unmarked";
+} | {
+    readonly kind: "invalid";
+    readonly message: string;
+};
+export declare function readManagedMarker(content: string): ManagedMarker;
+/** Removes the marker line and a following local line; the bunfig header is content, not a marker. */
+export declare function stripManagedMarker(content: string): string;
+export declare function addManagedMarker(content: string, style: MarkerCommentStyle): string;

package/dist/managed-files/marker.js

@@ -0,0 +1,49 @@
+export const MANAGED_MARKER = "kumiko-managed";
+// kumiko-testing has written this header into every bunfig since before the
+// marker existed; it already means "generated, do not edit".
+const BUNFIG_GENERATED_HEADER = "# Generated by kumiko-testing (";
+const LOCAL_MARKER_RE = /^(?:#|\/\/) kumiko-managed: local(?:[ \t]+(.*))?$/;
+// Docker requires `# syntax=` on line 1 and the kernel requires the shebang
+// there, so the marker moves one line down in those files.
+function isPreambleLine(line) {
+    return line !== undefined && (line.startsWith("#!") || line.startsWith("# syntax="));
+}
+function markerLineIndex(lines) {
+    return isPreambleLine(lines[0]) ? 1 : 0;
+}
+function isMarkerLine(line) {
+    return line === `# ${MANAGED_MARKER}` || line === `// ${MANAGED_MARKER}`;
+}
+export function readManagedMarker(content) {
+    const lines = content.split("\n");
+    const index = markerLineIndex(lines);
+    const line = lines[index];
+    if (!isMarkerLine(line) && !line?.startsWith(BUNFIG_GENERATED_HEADER))
+        return { kind: "unmarked" };
+    const local = LOCAL_MARKER_RE.exec(lines[index + 1] ?? "");
+    if (local === null)
+        return { kind: "managed" };
+    const reason = local[1]?.trim() ?? "";
+    if (reason === "") {
+        return {
+            kind: "invalid",
+            message: `line ${index + 2}: "kumiko-managed: local" needs a reason, e.g. "# kumiko-managed: local extra build step for pdf-parse"`,
+        };
+    }
+    return { kind: "local", reason };
+}
+/** Removes the marker line and a following local line; the bunfig header is content, not a marker. */
+export function stripManagedMarker(content) {
+    const lines = content.split("\n");
+    const index = markerLineIndex(lines);
+    if (!isMarkerLine(lines[index]))
+        return content;
+    const removeCount = LOCAL_MARKER_RE.test(lines[index + 1] ?? "") ? 2 : 1;
+    lines.splice(index, removeCount);
+    return lines.join("\n");
+}
+export function addManagedMarker(content, style) {
+    const lines = content.split("\n");
+    lines.splice(markerLineIndex(lines), 0, `${style} ${MANAGED_MARKER}`);
+    return lines.join("\n");
+}

package/dist/managed-files/port-registry.d.ts

@@ -0,0 +1,17 @@
+import { type AppPortRole } from "@cosmicdrift/kumiko-framework/config";
+import { type StaticAppConfig } from "./static-app-config.ts";
+export type ScannedApp = {
+    readonly app: string;
+    readonly config: StaticAppConfig;
+};
+export type PortClaim = {
+    readonly app: string;
+    readonly role: AppPortRole;
+};
+export type PortCollision = {
+    readonly port: number;
+    readonly claims: readonly PortClaim[];
+};
+/** Direct children of `root` with a kumiko.config.ts; worktrees and dot-dirs are skipped. */
+export declare function scanWorkspaceApps(root: string): readonly ScannedApp[];
+export declare function findPortCollisions(apps: readonly ScannedApp[]): readonly PortCollision[];

package/dist/managed-files/port-registry.js

@@ -0,0 +1,31 @@
+// Port registry across the apps of a workspace: every app declares its ports
+// in kumiko.config.ts, and two apps (or two roles of one app) must never claim
+// the same port, otherwise their local dev and E2E runs block each other.
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { APP_CONFIG_FILE, listAppPorts, } from "@cosmicdrift/kumiko-framework/config";
+import { readStaticAppConfig } from "./static-app-config.js";
+/** Direct children of `root` with a kumiko.config.ts; worktrees and dot-dirs are skipped. */
+export function scanWorkspaceApps(root) {
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules")
+        .filter((entry) => existsSync(join(root, entry.name, APP_CONFIG_FILE)))
+        .map((entry) => ({ app: entry.name, config: readStaticAppConfig(join(root, entry.name)) }))
+        .sort((a, b) => a.app.localeCompare(b.app));
+}
+export function findPortCollisions(apps) {
+    const claimsByPort = new Map();
+    for (const { app, config } of apps) {
+        if (config.kind !== "defined")
+            continue;
+        for (const { role, port } of listAppPorts(config.ports)) {
+            const claims = claimsByPort.get(port) ?? [];
+            claims.push({ app, role });
+            claimsByPort.set(port, claims);
+        }
+    }
+    return [...claimsByPort.entries()]
+        .filter(([, claims]) => claims.length > 1)
+        .map(([port, claims]) => ({ port, claims }))
+        .sort((a, b) => a.port - b.port);
+}

package/dist/managed-files/registry.d.ts

@@ -0,0 +1,51 @@
+import { type StaticAppConfig } from "./static-app-config.ts";
+export declare const BIOME_PRESET = "@cosmicdrift/kumiko-framework/biome";
+export declare const TSCONFIG_PRESET = "@cosmicdrift/kumiko-framework/tsconfig.app.json";
+export type ManagedAppInput = {
+    readonly appRoot: string;
+    /** Default: package.json `name`. */
+    readonly appName?: string;
+    /** kumiko.json uiRoots; a non-empty list turns on UI guards and DOM tests. */
+    readonly uiRoots: readonly string[];
+};
+export type ManagedAppFacts = {
+    readonly appRoot: string;
+    readonly appName: string;
+    readonly hasUi: boolean;
+    readonly config: StaticAppConfig;
+};
+/** Byte-compared after the marker lines are stripped. */
+export type ManagedTemplateFile = {
+    readonly kind: "template";
+    readonly path: string;
+    /** Rendered content including the marker. */
+    readonly content: string;
+    readonly executable: boolean;
+};
+/** Compared after kumiko-testing's merge, which keeps app extras such as [install.scopes]. */
+export type ManagedBunfigFile = {
+    readonly kind: "bunfig";
+    readonly path: string;
+    readonly variant: "unit" | "integration" | "real" | "dom";
+};
+/** Must extend the framework preset; app overrides below `extends` are allowed. */
+export type ManagedStructuralFile = {
+    readonly kind: "structural";
+    readonly path: "biome.json" | "tsconfig.json" | "kumiko.config.ts";
+};
+/** Written once by the scaffold, then owned by the app (wiring, env schema). */
+export type ManagedSeedFile = {
+    readonly kind: "seed";
+    readonly path: string;
+};
+export type ManagedFile = ManagedTemplateFile | ManagedBunfigFile | ManagedStructuralFile | ManagedSeedFile;
+export declare function resolveManagedAppFacts(input: ManagedAppInput): ManagedAppFacts;
+export declare function renderManagedTemplates(facts: ManagedAppFacts): readonly ManagedTemplateFile[];
+export declare function managedBunfigFiles(facts: ManagedAppFacts): readonly ManagedBunfigFile[];
+/** Options are the app's choice; read them from the file so the check only flags real drift. */
+export declare function renderManagedBunfig(file: ManagedBunfigFile, existing: string | undefined): string;
+export declare const MANAGED_STRUCTURAL_FILES: readonly ManagedStructuralFile[];
+export declare const MANAGED_SEED_FILES: readonly ManagedSeedFile[];
+export declare function listManagedFiles(facts: ManagedAppFacts): readonly ManagedFile[];
+export declare function renderBiomePresetJson(): string;
+export declare function renderTsconfigPresetJson(): string;

package/dist/managed-files/registry.js

@@ -0,0 +1,115 @@
+// One source for every file the framework owns in an app: the scaffold writes
+// these renders, `kumiko check managed` compares against them and
+// `kumiko sync-managed` writes them back.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import { BUNFIG_FILES, renderBunfig } from "@cosmicdrift/kumiko-testing/bunfig";
+import { isKebabSegment } from "../kebab.js";
+import { readReleaseTarget, render, renderDeployFiles } from "../scaffold-deploy.js";
+import { addManagedMarker } from "./marker.js";
+import { readStaticAppConfig } from "./static-app-config.js";
+export const BIOME_PRESET = "@cosmicdrift/kumiko-framework/biome";
+export const TSCONFIG_PRESET = "@cosmicdrift/kumiko-framework/tsconfig.app.json";
+function templatesDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..", "templates", "managed");
+}
+function readTemplate(name) {
+    return readFileSync(join(templatesDir(), name), "utf-8");
+}
+function readPackageName(appRoot) {
+    const path = join(appRoot, "package.json");
+    if (!existsSync(path))
+        throw new Error(`managed files: ${path} not found`);
+    const raw = parseJsonOrThrow(readFileSync(path, "utf-8"), path);
+    const name = typeof raw === "object" && raw !== null && "name" in raw ? raw.name : undefined;
+    if (typeof name !== "string")
+        throw new Error(`managed files: ${path} has no "name"`);
+    return name;
+}
+export function resolveManagedAppFacts(input) {
+    const appName = input.appName ?? readPackageName(input.appRoot);
+    // The name lands in workflow files, image names and shell scripts.
+    if (!isKebabSegment(appName)) {
+        throw new Error(`managed files: app name must be kebab-case (a-z, 0-9, -); got "${appName}"`);
+    }
+    return {
+        appRoot: input.appRoot,
+        appName,
+        hasUi: input.uiRoots.length > 0,
+        config: readStaticAppConfig(input.appRoot),
+    };
+}
+function marked(path, body, style, executable = false) {
+    return { kind: "template", path, content: addManagedMarker(body, style), executable };
+}
+function renderCiWorkflow(facts) {
+    const infra = facts.config.kind === "defined" ? facts.config.ports.infra : undefined;
+    const minio = infra?.s3 !== undefined;
+    const meilisearch = infra?.meilisearch !== undefined;
+    return render(readTemplate("ci.yml.template"), { appName: facts.appName, uiGuards: String(facts.hasUi) }, { minio, meilisearch, e2eInputs: minio || meilisearch });
+}
+export function renderManagedTemplates(facts) {
+    const deploy = renderDeployFiles({
+        appName: facts.appName,
+        destination: facts.appRoot,
+        ensuredRegistryConfigFiles: [BUNFIG_FILES.unit],
+    });
+    const target = readReleaseTarget(facts.appRoot, facts.appName);
+    return [
+        ...deploy.files.map((file) => marked(`deploy/${file.output}`, file.content, "#", file.output.endsWith(".sh"))),
+        marked(".husky/pre-push", readTemplate("husky-pre-push.template"), "#", true),
+        marked(".github/workflows/cache-cleanup.yml", readTemplate("cache-cleanup.yml.template"), "#"),
+        marked(".github/workflows/release.yml", render(readTemplate("release.yml.template"), { appName: facts.appName, ...target }, {}), "#"),
+        marked(".github/workflows/ci.yml", renderCiWorkflow(facts), "#"),
+        marked("kumiko/schema.ts", readTemplate("kumiko-schema.ts.template"), "//"),
+    ];
+}
+export function managedBunfigFiles(facts) {
+    return [
+        { kind: "bunfig", path: BUNFIG_FILES.unit, variant: "unit" },
+        { kind: "bunfig", path: BUNFIG_FILES.integration, variant: "integration" },
+        { kind: "bunfig", path: BUNFIG_FILES.real, variant: "real" },
+        ...(facts.hasUi ? [{ kind: "bunfig", path: BUNFIG_FILES.dom, variant: "dom" }] : []),
+    ];
+}
+/** Options are the app's choice; read them from the file so the check only flags real drift. */
+export function renderManagedBunfig(file, existing) {
+    const options = {
+        ...(existing === undefined || /^linker = "hoisted"$/m.test(existing)
+            ? { install: { linker: "hoisted" } }
+            : {}),
+        ...(existing !== undefined && /^coverage = true$/m.test(existing) ? { coverage: true } : {}),
+    };
+    return file.variant === "dom"
+        ? renderBunfig("unit", { ...options, dom: true })
+        : renderBunfig(file.variant, options);
+}
+export const MANAGED_STRUCTURAL_FILES = [
+    { kind: "structural", path: "biome.json" },
+    { kind: "structural", path: "tsconfig.json" },
+    { kind: "structural", path: "kumiko.config.ts" },
+];
+export const MANAGED_SEED_FILES = [
+    { kind: "seed", path: "bin/server.ts" },
+    { kind: "seed", path: "bin/env-schema.ts" },
+];
+export function listManagedFiles(facts) {
+    return [
+        ...renderManagedTemplates(facts),
+        ...managedBunfigFiles(facts),
+        ...MANAGED_STRUCTURAL_FILES,
+        ...MANAGED_SEED_FILES,
+    ];
+}
+// Written the way Biome formats it, so the app's own `biome check` stays green.
+export function renderBiomePresetJson() {
+    return `{\n  "extends": [${JSON.stringify(BIOME_PRESET)}]\n}\n`;
+}
+export function renderTsconfigPresetJson() {
+    return `${JSON.stringify({
+        extends: TSCONFIG_PRESET,
+        include: ["bin", "src", "kumiko", "e2e", "kumiko.config.ts", "playwright.config.ts"],
+    }, null, 2)}\n`;
+}

package/dist/managed-files/static-app-config.d.ts

@@ -0,0 +1,16 @@
+import { type AppPorts } from "@cosmicdrift/kumiko-framework/config";
+export type StaticAppConfig = {
+    readonly kind: "missing";
+}
+/** A config without defineAppConfig: the app has not adopted the standard yet. */
+ | {
+    readonly kind: "legacy";
+} | {
+    readonly kind: "invalid";
+    readonly message: string;
+} | {
+    readonly kind: "defined";
+    readonly ports: AppPorts;
+};
+export declare function parseStaticAppConfig(source: string): StaticAppConfig;
+export declare function readStaticAppConfig(appRoot: string): StaticAppConfig;

package/dist/managed-files/static-app-config.js

@@ -0,0 +1,99 @@
+// Reads the ports out of kumiko.config.ts without importing it: importing
+// would execute every feature module of the app, and the port registry scans
+// sibling apps whose dependencies may not even be installed.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { APP_CONFIG_FILE, findAppPortProblems, } from "@cosmicdrift/kumiko-framework/config";
+import { Project, SyntaxKind } from "ts-morph";
+const INFRA_KEYS = [
+    "postgres",
+    "redis",
+    "meilisearch",
+    "s3",
+];
+function isInfraKey(name) {
+    return INFRA_KEYS.some((key) => key === name);
+}
+class StaticConfigError extends Error {
+}
+function propertyName(node) {
+    if (node.isKind(SyntaxKind.PropertyAssignment))
+        return node.getName().replace(/^["']|["']$/g, "");
+    return undefined;
+}
+function objectProperty(object, name) {
+    for (const property of object.getProperties()) {
+        if (property.isKind(SyntaxKind.SpreadAssignment) ||
+            property.isKind(SyntaxKind.ShorthandPropertyAssignment)) {
+            throw new StaticConfigError(`${name}: spread and shorthand properties cannot be read statically`);
+        }
+        if (propertyName(property) === name && property.isKind(SyntaxKind.PropertyAssignment)) {
+            return property.getInitializerOrThrow();
+        }
+    }
+    return undefined;
+}
+function numericLiteral(node, path) {
+    if (node === undefined)
+        throw new StaticConfigError(`${path} is missing`);
+    if (!node.isKind(SyntaxKind.NumericLiteral)) {
+        throw new StaticConfigError(`${path} must be a number literal so tooling can read it, got "${node.getText()}"`);
+    }
+    return node.getLiteralValue();
+}
+function objectLiteral(node, path) {
+    if (node === undefined)
+        throw new StaticConfigError(`${path} is missing`);
+    if (!node.isKind(SyntaxKind.ObjectLiteralExpression)) {
+        throw new StaticConfigError(`${path} must be an object literal, got "${node.getText()}"`);
+    }
+    return node;
+}
+function readInfraPorts(node) {
+    if (node === undefined)
+        return undefined;
+    const object = objectLiteral(node, "ports.infra");
+    const infra = {};
+    for (const property of object.getProperties()) {
+        const name = propertyName(property);
+        if (name === undefined || !isInfraKey(name)) {
+            throw new StaticConfigError(`ports.infra: unknown entry "${property.getText()}", expected ${INFRA_KEYS.join(", ")}`);
+        }
+        infra[name] = numericLiteral(objectProperty(object, name), `ports.infra.${name}`);
+    }
+    return infra;
+}
+export function parseStaticAppConfig(source) {
+    const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+    const file = project.createSourceFile(APP_CONFIG_FILE, source);
+    const call = file
+        .getDescendantsOfKind(SyntaxKind.CallExpression)
+        .find((candidate) => candidate.getExpression().getText() === "defineAppConfig");
+    if (call === undefined)
+        return { kind: "legacy" };
+    try {
+        const config = objectLiteral(call.getArguments()[0], "defineAppConfig argument");
+        const ports = objectLiteral(objectProperty(config, "ports"), "ports");
+        const infra = readInfraPorts(objectProperty(ports, "infra"));
+        const parsed = {
+            dev: numericLiteral(objectProperty(ports, "dev"), "ports.dev"),
+            e2e: numericLiteral(objectProperty(ports, "e2e"), "ports.e2e"),
+            ...(infra === undefined ? {} : { infra }),
+        };
+        const problems = findAppPortProblems(parsed);
+        if (problems.length > 0)
+            return { kind: "invalid", message: problems.join("; ") };
+        return { kind: "defined", ports: parsed };
+    }
+    catch (error) {
+        if (error instanceof StaticConfigError)
+            return { kind: "invalid", message: error.message };
+        throw error;
+    }
+}
+export function readStaticAppConfig(appRoot) {
+    const path = join(appRoot, APP_CONFIG_FILE);
+    if (!existsSync(path))
+        return { kind: "missing" };
+    return parseStaticAppConfig(readFileSync(path, "utf-8"));
+}

package/dist/managed-files/sync.d.ts

@@ -0,0 +1,19 @@
+import { type ManagedAppFacts } from "./registry.ts";
+export type SyncManagedOptions = {
+    /** Without it nothing is written; the result lists what would happen. */
+    readonly write: boolean;
+    /** Also take over existing files without a marker (first adoption). */
+    readonly adopt: boolean;
+};
+export type SyncAction = {
+    readonly action: "create" | "update" | "adopt";
+    readonly path: string;
+} | {
+    readonly action: "unchanged";
+    readonly path: string;
+} | {
+    readonly action: "skip";
+    readonly path: string;
+    readonly skippedBecause: string;
+};
+export declare function syncManagedFiles(facts: ManagedAppFacts, options: SyncManagedOptions): readonly SyncAction[];

package/dist/managed-files/sync.js

@@ -0,0 +1,101 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { mergeBunfig } from "@cosmicdrift/kumiko-testing/bunfig";
+import { readManagedMarker } from "./marker.js";
+import { listManagedFiles, renderBiomePresetJson, renderManagedBunfig, renderTsconfigPresetJson, } from "./registry.js";
+// A symlinked .github or deploy/ would let the sync write outside the app.
+function symlinkOnPath(appRoot, path) {
+    const segments = relative(appRoot, path).split(sep);
+    let current = appRoot;
+    for (const segment of segments) {
+        current = join(current, segment);
+        if (!existsSync(current) && !isBrokenSymlink(current))
+            return undefined;
+        if (lstatSync(current).isSymbolicLink())
+            return relative(appRoot, current);
+    }
+    return undefined;
+}
+function isBrokenSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function plannedContent(file, existing) {
+    switch (file.kind) {
+        case "template":
+            return { content: file.content, executable: file.executable };
+        case "bunfig": {
+            const generated = renderManagedBunfig(file, existing);
+            if (existing === undefined)
+                return { content: generated, executable: false };
+            const merged = mergeBunfig(generated, existing);
+            if (!merged.ok) {
+                const keys = merged.unknownKeys.map(({ section, key }) => `[${section}] ${key}`).join(", ");
+                return `keys the generator does not own: ${keys}`;
+            }
+            return { content: merged.content, executable: false };
+        }
+        case "structural":
+            if (existing !== undefined)
+                return "exists; extend the preset by hand, app overrides stay";
+            if (file.path === "biome.json")
+                return { content: renderBiomePresetJson(), executable: false };
+            if (file.path === "tsconfig.json")
+                return { content: renderTsconfigPresetJson(), executable: false };
+            return "write kumiko.config.ts with defineAppConfig by hand (see docs/reference/app-skeleton.md)";
+        case "seed":
+            return existing === undefined
+                ? "app-owned seed; copy it from a fresh `kumiko new app`"
+                : "app-owned";
+    }
+}
+function planFile(file, facts, options) {
+    const path = join(facts.appRoot, file.path);
+    const symlink = symlinkOnPath(facts.appRoot, path);
+    if (symlink !== undefined)
+        return { action: "skip", path: file.path, skippedBecause: `${symlink} is a symlink` };
+    const existing = existsSync(path) ? readFileSync(path, "utf-8") : undefined;
+    if (existing !== undefined && file.kind !== "structural" && file.kind !== "seed") {
+        const marker = readManagedMarker(existing);
+        if (marker.kind === "local")
+            return { action: "skip", path: file.path, skippedBecause: `local: ${marker.reason}` };
+        if (marker.kind === "invalid")
+            return { action: "skip", path: file.path, skippedBecause: marker.message };
+        if (marker.kind === "unmarked" && !options.adopt) {
+            return {
+                action: "skip",
+                path: file.path,
+                skippedBecause: "no kumiko-managed marker; pass --adopt to take it over",
+            };
+        }
+    }
+    const planned = plannedContent(file, existing);
+    if (typeof planned === "string")
+        return { action: "skip", path: file.path, skippedBecause: planned };
+    const { content } = planned;
+    if (existing === content)
+        return { action: "unchanged", path: file.path };
+    const action = existing === undefined
+        ? "create"
+        : readManagedMarker(existing).kind === "unmarked"
+            ? "adopt"
+            : "update";
+    return { action, path: file.path, write: { content, executable: planned.executable } };
+}
+export function syncManagedFiles(facts, options) {
+    return listManagedFiles(facts).map((file) => {
+        const { write, ...action } = planFile(file, facts, options);
+        if (options.write && write !== undefined) {
+            const path = join(facts.appRoot, file.path);
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, write.content);
+            if (write.executable)
+                chmodSync(path, 0o755);
+        }
+        return action;
+    });
+}

package/dist/run-dev-app.d.ts

@@ -6,7 +6,7 @@ import type { ErrorDocsConfig } from "@cosmicdrift/kumiko-framework/errors";
 import type { EnvelopeCipher, MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import type { PageHeadResolver } from "@cosmicdrift/kumiko-headless/apex";
 import type { TestStack } from "@cosmicdrift/kumiko-testing/stack";
-import { type CreateKumikoServerOptions, type KumikoServerHandle } from "./create-kumiko-server.js";
+import { type CreateKumikoServerOptions, type KumikoServerHandle } from "./create-kumiko-server.ts";
 export type { AccountLockoutSetup, AccountUnlockSetup, AuthMailOptions, EmailVerificationSetup, InviteSetup, PasswordResetSetup, SignupSetup, } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
 import type { AccountLockoutSetup, AccountUnlockSetup, AuthMailOptions, EmailVerificationSetup, InviteSetup, PasswordResetSetup, SignupSetup } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
 import { type UnsubscribeOption } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";