@cosmicdrift/kumiko-dev-server 0.369.0 → 0.370.0

package/dist/scaffold-app.js

@@ -1,22 +1,31 @@
 // scaffoldApp — generate a runnable Kumiko app workspace from a name.
 //
 // Used by `kumiko new app <name>`. Produces the minimal app shape that
-// `KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts` runs successfully against:
-// run-config with 5 foundation features, bin/main.ts with auth-admin
-// stub, package.json with @cosmicdrift/* deps, tsconfig, .env.example,
-// README.
+// `KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts` and `kumiko check` run green
+// against. Every framework-owned file (deploy, workflows, bunfigs, presets,
+// kumiko/schema.ts) comes from the managed-files registry, the same renders
+// `kumiko check managed` compares against.
 //
 // Generated files are emitted already formatted to Biome's output (import
 // order, 100-col wrapping, trailing commas) so a fresh app passes `biome check`.
 // Static files (package.json, tsconfig, .env, README) stay text-based.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { APP_CONFIG_FILE } from "@cosmicdrift/kumiko-framework/config";
 import { collectTableMetas, generateMigration, writeSnapshotJson, } from "@cosmicdrift/kumiko-framework/db";
 import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";
 import { isKebabSegment } from "./kebab.js";
+import { PREPARE_SCRIPT, resolveManagedAppFacts, syncManagedFiles } from "./managed-files/index.js";
 import { renderAgentsMd, renderClaudeMd, renderMountedFeatureList } from "./scaffold-agent-docs.js";
 import { createDemoTasksFeature, renderDemoSeedFile, renderDemoTasksFeatureFile, renderDemoTasksI18n, renderDemoTasksIndex, renderDemoTasksWebIndex, } from "./scaffold-demo-tasks.js";
-import { scaffoldDeploy } from "./scaffold-deploy.js";
 // Exact pin (no caret): the generated files are formatted to this Biome's output,
 // and a scaffold-lint test keeps it equal to the monorepo's own Biome version.
 export const SCAFFOLD_BIOME_VERSION = "2.5.7";
@@ -44,20 +53,10 @@ export async function scaffoldApp(options) {
     const files = [];
     write(join(destination, "package.json"), renderPackageJson(options.name, version, testSetup));
     files.push("package.json");
-    write(join(destination, "tsconfig.json"), renderTsconfig());
-    files.push("tsconfig.json");
     write(join(destination, "kumiko.json"), renderKumikoManifest());
     files.push("kumiko.json");
-    write(join(destination, "biome.json"), renderBiomeJson());
-    files.push("biome.json");
     write(join(destination, ".gitignore"), SCAFFOLD_GITIGNORE);
     files.push(".gitignore");
-    if (testSetup === undefined) {
-        write(join(destination, "bunfig.toml"), renderBunfigToml());
-        files.push("bunfig.toml");
-        write(join(destination, "bunfig.ci.toml"), renderBunfigCiToml());
-        files.push("bunfig.ci.toml");
-    }
     write(join(destination, "src", "run-config.ts"), renderRunConfig(options.features));
     files.push("src/run-config.ts");
     mkdirSync(join(destination, "src", "features", "tasks", "web"), { recursive: true });
@@ -71,12 +70,14 @@ export async function scaffoldApp(options) {
     files.push("src/features/tasks/web/index.ts");
     write(join(destination, "src", "seed.ts"), renderDemoSeedFile());
     files.push("src/seed.ts");
-    write(join(destination, "kumiko", "schema.ts"), renderKumikoSchema());
-    files.push("kumiko/schema.ts");
+    write(join(destination, APP_CONFIG_FILE), renderAppConfig());
+    files.push(APP_CONFIG_FILE);
     write(join(destination, "bin", "main.ts"), renderMain(options.name));
     files.push("bin/main.ts");
-    write(join(destination, "bin", "dev.ts"), renderDev(options.name));
-    files.push("bin/dev.ts");
+    write(join(destination, "bin", "server.ts"), renderServer(options.name));
+    files.push("bin/server.ts");
+    write(join(destination, "bin", "env-schema.ts"), renderEnvSchema(options.name));
+    files.push("bin/env-schema.ts");
     write(join(destination, "bin", "kumiko.ts"), renderBinKumiko());
     files.push("bin/kumiko.ts");
     write(join(destination, "src", "client.tsx"), renderClient(options.name));
@@ -89,12 +90,6 @@ export async function scaffoldApp(options) {
     files.push("docker-compose.yml");
     await writeInitMigration(destination, options.features);
     files.push("kumiko/migrations/0001_init.sql", "kumiko/migrations/.snapshot.json");
-    const deploy = scaffoldDeploy({ appName: options.name, destination });
-    for (const f of deploy.files) {
-        if (f.written) {
-            files.push(relative(destination, f.path));
-        }
-    }
     if (testSetup !== undefined) {
         for (const [rel, content] of Object.entries(testSetup.files)) {
             mkdirSync(dirname(join(destination, rel)), { recursive: true });
@@ -102,6 +97,15 @@ export async function scaffoldApp(options) {
             files.push(rel);
         }
     }
+    const managedFacts = resolveManagedAppFacts({
+        appRoot: destination,
+        appName: options.name,
+        uiRoots: SCAFFOLD_UI_ROOTS,
+    });
+    for (const action of syncManagedFiles(managedFacts, { write: true, adopt: false })) {
+        if (action.action === "create")
+            files.push(action.path);
+    }
     write(join(destination, "README.md"), `${renderReadme(options.name, options.features)}${testSetup === undefined ? "" : `\n${testSetup.rulesMarkdown}`}`);
     files.push("README.md");
     write(join(destination, "AGENTS.md"), renderAgentsMd({
@@ -120,15 +124,17 @@ function write(path, content) {
 }
 function appScripts(testSetup) {
     return {
-        dev: "bun --watch bin/dev.ts",
+        dev: "bun --watch bin/server.ts",
         build: "bun kumiko-build",
         start: "bun run bin/main.ts",
         boot: "KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts",
         typecheck: "tsc --noEmit",
         lint: "biome check .",
-        ...(testSetup?.scripts ?? { test: "bun --config=bunfig.ci.toml test --dots" }),
+        check: "kumiko check",
+        ...(testSetup?.scripts ?? { test: "bun --config=bunfig.toml test --dots" }),
         "schema:apply": "bun kumiko-schema apply",
         "schema:generate": "bun kumiko-schema generate",
+        prepare: PREPARE_SCRIPT,
     };
 }
 function renderPackageJson(name, version, testSetup) {
@@ -150,6 +156,7 @@ function renderPackageJson(name, version, testSetup) {
         },
         devDependencies: sortedByName({
             "@biomejs/biome": SCAFFOLD_BIOME_VERSION,
+            "@cosmicdrift/kumiko-cli": version,
             "@tailwindcss/cli": "^4.3.0",
             "@types/react": "^19.2.0",
             "@types/react-dom": "^19.2.0",
@@ -163,114 +170,6 @@ function renderPackageJson(name, version, testSetup) {
 function sortedByName(record) {
     return Object.fromEntries(Object.entries(record).sort(([a], [b]) => (a < b ? -1 : 1)));
 }
-function renderTsconfig() {
-    return `${JSON.stringify({
-        compilerOptions: {
-            strict: true,
-            noUncheckedIndexedAccess: true,
-            forceConsistentCasingInFileNames: true,
-            verbatimModuleSyntax: true,
-            target: "ESNext",
-            module: "ESNext",
-            moduleResolution: "bundler",
-            esModuleInterop: true,
-            skipLibCheck: true,
-            lib: ["ESNext", "DOM"],
-            types: ["bun-types"],
-            jsx: "react-jsx",
-            noEmit: true,
-        },
-        include: ["bin", "src", "kumiko", "e2e", "playwright.config.ts"],
-    }, null, 2)}\n`;
-}
-function renderBiomeJson() {
-    return `${JSON.stringify({
-        $schema: `https://biomejs.dev/schemas/${SCAFFOLD_BIOME_VERSION}/schema.json`,
-        vcs: {
-            enabled: true,
-            clientKind: "git",
-            useIgnoreFile: true,
-            defaultBranch: "main",
-        },
-        files: {
-            includes: [
-                "src/**",
-                "bin/**",
-                "kumiko/**",
-                "e2e/**",
-                "playwright.config.ts",
-                "!**/dist",
-                "!kumiko/migrations",
-            ],
-        },
-        formatter: {
-            enabled: true,
-            indentStyle: "space",
-            indentWidth: 2,
-            lineWidth: 100,
-            lineEnding: "lf",
-        },
-        css: {
-            parser: { cssModules: false, tailwindDirectives: true },
-        },
-        javascript: {
-            formatter: {
-                quoteStyle: "double",
-                jsxQuoteStyle: "double",
-                semicolons: "always",
-                trailingCommas: "all",
-                arrowParentheses: "always",
-            },
-        },
-        json: { formatter: { indentWidth: 2, lineWidth: 80 } },
-        linter: {
-            enabled: true,
-            rules: {
-                preset: "recommended",
-                correctness: { noUnusedVariables: "error", noUnusedImports: "error" },
-                suspicious: { noExplicitAny: "error", noDebugger: "error", noConsole: "warn" },
-                complexity: { useLiteralKeys: "off" },
-                style: { useConst: "error" },
-                nursery: { noFloatingPromises: "error" },
-            },
-        },
-        overrides: [
-            {
-                includes: ["**/*.test.ts", "**/*.spec.ts", "**/*.integration.ts", "**/*.e2e.ts"],
-                linter: {
-                    rules: {
-                        suspicious: { noConsole: "off" },
-                        style: { noNonNullAssertion: "off" },
-                    },
-                },
-            },
-        ],
-    }, null, 2)}\n`;
-}
-function renderBunfigToml() {
-    return `[install]
-linker = "hoisted"
-
-[test]
-pathIgnorePatterns = [
-  "**/e2e/**",
-  "**/*.spec.ts",
-  "**/dist/**",
-]
-`;
-}
-function renderBunfigCiToml() {
-    return `[install]
-linker = "hoisted"
-
-[test]
-pathIgnorePatterns = [
-  "**/e2e/**",
-  "**/*.spec.ts",
-  "**/dist/**",
-]
-`;
-}
 const FOUNDATION_FEATURES = [
     {
         name: "secrets",
@@ -389,45 +288,51 @@ ${passwordAndExtras}
     },
   },`;
 }
-function renderMain(appName) {
-    const tenantId = deriveTenantId(appName);
+// Ports match runDevApp's default and kumiko-testing's SCAFFOLD_E2E_PORT.
+const SCAFFOLD_DEV_PORT = 4173;
+const SCAFFOLD_E2E_PORT = 4174;
+function renderAppConfig() {
     const imports = renderSortedImports([
-        { specifier: "@cosmicdrift/kumiko-dev-server/env-schema", names: ["frameworkCoreEnvSchema"] },
-        { specifier: "@cosmicdrift/kumiko-server-runtime", names: ["composeFeatures", "runProdApp"] },
-        { specifier: "@cosmicdrift/kumiko-framework/engine", names: ["TenantId"], typeOnly: true },
-        { specifier: "@cosmicdrift/kumiko-framework/env", names: ["composeEnvSchema"] },
+        { specifier: "@cosmicdrift/kumiko-framework/config", names: ["defineAppConfig"] },
         {
-            specifier: "@cosmicdrift/kumiko-framework/crypto",
-            names: ["requireKmsWiring", "resolveKmsWiring"],
+            specifier: "@cosmicdrift/kumiko-server-runtime/compose-features",
+            names: ["composeFeatures"],
         },
-        { specifier: "zod", names: ["z"] },
-        { specifier: "../src/run-config", names: ["APP_FEATURES", "HAS_AUTH"] },
+        { specifier: "./src/run-config", names: ["APP_FEATURES", "HAS_AUTH"] },
     ]);
-    const authBlock = renderAdminAuthBlock(appName, [
-        "// runProdApp validates envSchema before seeding: a missing or short value aborts the boot.",
-        'password: process.env["DEMO_ADMIN_PASSWORD"] ?? "",',
-        'displayName: "Admin",',
-    ]);
-    // The envSchema must cover the SAME features runProdApp mounts at boot:
-    // `auth: { admin: … }` makes runProdApp auto-mix config/user/tenant/
-    // auth-email-password, so the JWT_SECRET (min-32) declaration has to be part
-    // of the boot-gate here too. Subject-key KMS is optional locally (plaintext +
-    // loud warning) but required under NODE_ENV=production (fw#2317 / #2339).
-    return `// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after
-// composeFeatures + validateBoot + createRegistry without DB/Redis-connect
-// (see @cosmicdrift/kumiko-server-runtime runProdApp). The real dev boot
-// runs via \`bunx kumiko dev\` (in-repo dev-tool) with a Docker stack — DX-1.0
-// only covers the boot-mode path; \`kumiko dev\` lands in a later DX phase.
+    return `// The one place the tooling reads: features for schema, migrations and agent
+// lint, client entries, and the ports this app claims (see \`kumiko ports\`).
+// features is the composed list, so the bundled auth features count too.
 
 ${imports}
 
-const DEFAULT_TENANT_ID = "${tenantId}" as TenantId;
+export default defineAppConfig({
+  features: composeFeatures([...APP_FEATURES], { includeBundled: HAS_AUTH }),
+  client: { entries: ["src/client.tsx"] },
+  ports: { dev: ${SCAFFOLD_DEV_PORT}, e2e: ${SCAFFOLD_E2E_PORT} },
+});
+`;
+}
+function renderEnvSchema(appName) {
+    const imports = renderSortedImports([
+        { specifier: "@cosmicdrift/kumiko-dev-server/env-schema", names: ["frameworkCoreEnvSchema"] },
+        { specifier: "@cosmicdrift/kumiko-framework/config", names: ["allAppFeatures"] },
+        { specifier: "@cosmicdrift/kumiko-framework/env", names: ["composeEnvSchema"] },
+        { specifier: "zod", names: ["z"] },
+    ]);
+    // The schema must cover the SAME features runProdApp mounts at boot:
+    // `auth: { admin: … }` makes runProdApp auto-mix config/user/tenant/
+    // auth-email-password, so their JWT_SECRET (min-32) declaration is part of the
+    // boot gate. kumiko.config.ts already holds that composed list.
+    return `// Env contract of the production processes (bin/main.ts, bin/kumiko.ts).
+// Importing it must not read process.env; validation happens in runProdApp.
 
-const bootFeatures = composeFeatures(APP_FEATURES, { includeBundled: HAS_AUTH });
+${imports}
+import appConfig from "../kumiko.config";
 
-const envSchema = composeEnvSchema({
+export const envSchema = composeEnvSchema({
   core: frameworkCoreEnvSchema,
-  features: bootFeatures,
+  features: allAppFeatures(appConfig),
   extend: z.object({
     DEMO_ADMIN_PASSWORD: z
       .string()
@@ -438,6 +343,34 @@ const envSchema = composeEnvSchema({
       .meta({ kumiko: { pulumi: { secret: true } } }),
   }),
 });
+`;
+}
+function renderMain(appName) {
+    const tenantId = deriveTenantId(appName);
+    const imports = renderSortedImports([
+        { specifier: "@cosmicdrift/kumiko-server-runtime", names: ["runProdApp"] },
+        { specifier: "@cosmicdrift/kumiko-framework/engine", names: ["TenantId"], typeOnly: true },
+        {
+            specifier: "@cosmicdrift/kumiko-framework/crypto",
+            names: ["requireKmsWiring", "resolveKmsWiring"],
+        },
+        { specifier: "../src/run-config", names: ["APP_FEATURES"] },
+        { specifier: "./env-schema", names: ["envSchema"] },
+    ]);
+    const authBlock = renderAdminAuthBlock(appName, [
+        "// runProdApp validates envSchema before seeding: a missing or short value aborts the boot.",
+        'password: process.env["DEMO_ADMIN_PASSWORD"] ?? "",',
+        'displayName: "Admin",',
+    ]);
+    // Subject-key KMS is optional locally (plaintext + loud warning) but required
+    // under NODE_ENV=production (fw#2317 / #2339).
+    return `// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after
+// composeFeatures + validateBoot + createRegistry without DB/Redis-connect
+// (see @cosmicdrift/kumiko-server-runtime runProdApp).
+
+${imports}
+
+const DEFAULT_TENANT_ID = "${tenantId}" as TenantId;
 
 const kmsOpts = {
   logPrefix: "[${appName}]",
@@ -459,7 +392,7 @@ ${authBlock}
 });
 `;
 }
-function renderDev(appName) {
+function renderServer(appName) {
     const tenantId = deriveTenantId(appName);
     const imports = renderSortedImports([
         { specifier: "@cosmicdrift/kumiko-dev-server", names: ["runDevApp"] },
@@ -474,7 +407,7 @@ function renderDev(appName) {
         'displayName: "Admin",',
         "emailVerified: true,",
     ]);
-    return `// Dev bootstrap. \`bun --watch bin/dev.ts\` (see package.json scripts.dev)
+    return `// Dev bootstrap. \`bun --watch bin/server.ts\` (see package.json scripts.dev)
 // starts a full-featured dev server with auto-reload on code changes.
 // setupTestStack creates missing entity tables automatically — a new
 // r.entity(...) in a feature becomes a CREATE TABLE on the next reboot,
@@ -662,7 +595,9 @@ bun run boot
 \`\`\`
 
 Runs \`KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts\` — validates feature composition
-+ env schema, exits 0 without touching DB/Redis. Useful in CI. It needs
++ env schema, exits 0 without touching DB/Redis. Useful in CI. It prints every
+variable with its feature and status, never the value. An invalid value exits 1;
+a missing one exits 0 without validating the wiring, so set
 \`DEMO_ADMIN_PASSWORD\` (min 12 chars, \`openssl rand -hex 24\`) in \`.env\`.
 
 Without \`PLATFORM_KEK\` / \`SUBJECT_KEYS_DATABASE_URL\` / \`KUMIKO_BLIND_INDEX_KEY\`
@@ -692,13 +627,23 @@ bun run schema:generate <name>
 \`deploy/Dockerfile\` + \`deploy/migrate-step.sh\` are scaffolded for container
 deploys. Build context = app repo root; migrations ship in \`kumiko/migrations/\`.
 
+## Managed files
+
+Files whose first line reads \`kumiko-managed\` (deploy/, .github/workflows/,
+.husky/pre-push, the bunfigs, kumiko/schema.ts) belong to the framework.
+\`bun run check\` reports drift against the installed version;
+\`bunx kumiko sync-managed --write\` restores them. To keep a local change, add
+\`# kumiko-managed: local <reason>\` as line 2.
+
 ## Architecture
 
 - \`src/run-config.ts\` — single source of truth: which features your app mounts (\`APP_FEATURES\`, \`HAS_AUTH\`).
 - \`src/features/tasks/\` — demo feature (entity + handlers + screens + nav).
 - \`src/seed.ts\` — dev seed for demo tasks (\`bun dev\` only).
-- \`kumiko/schema.ts\` — same feature set → \`ENTITY_METAS\` for \`kumiko schema\`.
-- \`bin/dev.ts\` — dev-server entry (\`bun dev\`).
+- \`kumiko.config.ts\` — the composed feature list, client entries and ports the tooling reads.
+- \`kumiko/schema.ts\` — generated (\`kumiko-managed\`): \`ENTITY_METAS\` from kumiko.config.ts for \`kumiko schema\`.
+- \`bin/server.ts\` — dev-server entry (\`bun dev\`).
+- \`bin/env-schema.ts\` — env contract of the production processes.
 - \`bin/main.ts\` — production-bootstrap (\`bun run start\`).
 - \`bin/kumiko.ts\` — schema + consumer-ops CLI bundled into \`dist-server/kumiko.js\`.
 - \`docker-compose.yml\` — local Postgres + Redis for \`bun dev\`.
@@ -714,33 +659,14 @@ function renderStylesCss() {
         "",
     ].join("\n");
 }
-function renderKumikoSchema() {
-    return [
-        "// Live ENTITY_METAS source for `kumiko schema generate|apply|status`.",
-        "//",
-        "// Computes table-metas from the SAME composeFeatures(APP_FEATURES) the",
-        "// runtime sees (runProdApp/runDevApp) — migration and runtime cannot drift.",
-        "",
-        'import { collectTableMetas, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";',
-        'import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";',
-        'import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";',
-        'import { APP_FEATURES, HAS_AUTH } from "../src/run-config";',
-        "",
-        "export const FEATURES: readonly FeatureDefinition[] = composeFeatures([...APP_FEATURES], {",
-        "  includeBundled: HAS_AUTH,",
-        "});",
-        "",
-        "export const ENTITY_METAS: readonly EntityTableMeta[] = collectTableMetas(FEATURES);",
-        "",
-    ].join("\n");
-}
 // `kumiko check` fails a kind "app" without uiRoots, so a fresh app must declare them.
+const SCAFFOLD_UI_ROOTS = ["src/features/*/web"];
 function renderKumikoManifest() {
     return `${JSON.stringify({
         kind: "app",
         sourceRoots: ["src", "bin"],
         testGlobs: ["src/**/*.{test,integration}.{ts,tsx}"],
-        uiRoots: ["src/features/*/web"],
+        uiRoots: SCAFFOLD_UI_ROOTS,
         excludes: ["**/node_modules/**", "**/dist/**"],
     }, null, 2)}\n`;
 }
@@ -753,20 +679,20 @@ function renderBinKumiko() {
         "// consumer status|restart <name>` to recover a dead event consumer without",
         "// ad-hoc SQL. kumiko-build bundles this file to dist-server/kumiko.js.",
         "",
-        'import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";',
+        'import { allAppFeatures } from "@cosmicdrift/kumiko-framework/config";',
         'import { runConsumerCli } from "@cosmicdrift/kumiko-framework/consumer-cli";',
-        'import { composeEnvSchema, kmsSlotsOf } from "@cosmicdrift/kumiko-framework/env";',
+        'import { kmsSlotsOf } from "@cosmicdrift/kumiko-framework/env";',
         'import { runSchemaCli } from "@cosmicdrift/kumiko-framework/schema-cli";',
-        'import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";',
-        'import { APP_FEATURES, HAS_AUTH } from "../src/run-config";',
+        'import appConfig from "../kumiko.config";',
+        'import { envSchema } from "./env-schema";',
         "",
         "const [, , cmd, ...rest] = Bun.argv;",
         "// biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
         "const out = { log: (l: string) => console.log(l), err: (l: string) => console.error(l) };",
         "",
         'if (cmd === "schema") {',
-        "  const features = composeFeatures([...APP_FEATURES], { includeBundled: HAS_AUTH });",
-        "  const kmsSlots = kmsSlotsOf(composeEnvSchema({ core: frameworkCoreEnvSchema, features }).schema);",
+        "  const features = allAppFeatures(appConfig);",
+        "  const kmsSlots = kmsSlotsOf(envSchema.schema);",
         "  process.exit(",
         "    await runSchemaCli(rest, process.env.INIT_CWD ?? process.cwd(), out, { features, kmsSlots }),",
         "  );",
@@ -778,7 +704,7 @@ function renderBinKumiko() {
         "",
         "// biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
         "console.error(",
-        `  \`\\n  Unknown: kumiko \${cmd ?? ""} — only 'kumiko schema <sub>' or 'kumiko consumer <sub>' in the standalone bundle.\\n\`,`,
+        `  \`\\n  Unknown: kumiko \${cmd ?? ""} — the standalone bundle only runs 'kumiko schema' and 'kumiko consumer'.\\n\`,`,
         ");",
         "process.exit(1);",
         "",
@@ -789,7 +715,7 @@ async function instantiateScaffoldFeatures(features) {
     const effective = base.filter((f) => !COMPOSE_AUTO_MOUNTED_NAMES.has(f.name));
     const instances = [];
     for (const entry of effective) {
-        const mod = (await import(entry.importPath));
+        const mod = (await import(__rewriteRelativeImportExtension(entry.importPath)));
         const exp = mod[entry.exportName];
         if (exp === undefined) {
             throw new Error(`scaffoldApp: ${entry.importPath} missing export ${entry.exportName} for ${entry.callExpression}`);

package/dist/scaffold-deploy.d.ts

@@ -12,6 +12,9 @@ export type RenderDeployFilesOptions = {
      *  `destination`. Lets the caller scaffold into one dir while detecting
      *  optional surfaces in another (rare — mostly destination = sourceDir). */
     readonly sourceDir?: string;
+    /** Registry configs to treat as present although they may not exist yet:
+     *  the managed-files sync writes bunfig.toml in the same pass as the Dockerfile. */
+    readonly ensuredRegistryConfigFiles?: readonly RegistryConfigFile[];
 };
 export type ScaffoldDeployOptions = RenderDeployFilesOptions & {
     /** Overwrite existing files instead of skipping them. */
@@ -85,5 +88,11 @@ export declare function scaffoldDeploy(options: ScaffoldDeployOptions): Scaffold
 /** Read-only: compares the rendered deploy files against what's on disk
  *  without writing anything. */
 export declare function checkDeployDrift(options: RenderDeployFilesOptions): CheckDeployDriftResult;
+export type KumikoReleaseTarget = {
+    readonly namespace: string;
+    readonly deployment: string;
+};
+/** Release target from `package.json#kumiko.deploy`; throws on an invalid deploy config. */
+export declare function readReleaseTarget(sourceDir: string, appName: string): KumikoReleaseTarget;
 export declare function render(source: string, subs: Readonly<Record<string, string>>, flags: Readonly<Record<string, boolean>>): string;
 export {};

package/dist/scaffold-deploy.js

@@ -13,6 +13,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
 import { isKebabSegment } from "./kebab.js";
 const REGISTRY_CONFIG_FILES = ["bunfig.toml", ".npmrc"];
@@ -46,7 +47,7 @@ export function renderDeployFiles(options) {
     // a `seeds/` directory (e.g. studio) crash in Docker-build with
     // `failed to compute cache key: "/app/seeds": not found`.
     const sourceDir = options.sourceDir ?? destinationRoot;
-    const detected = detectOptionalSurfaces(sourceDir, options.appName);
+    const detected = detectOptionalSurfaces(sourceDir, options.appName, options.ensuredRegistryConfigFiles ?? []);
     if (detected.hasPrivateGhPackages && detected.registryConfigFiles.length === 0) {
         // The Dockerfile only forwards the auth build-arg; without a registry
         // config scope entry bun resolves @cosmicdriftgamestudio/* against npmjs
@@ -143,10 +144,17 @@ const LOCAL_DEP_SPEC_RE = /^(file:|workspace:|link:)/;
 // full Postgres identifier grammar (no quoting support) since they are
 // interpolated into a shell string, not passed through a driver's escaping.
 const DB_IDENTIFIER_RE = /^[a-zA-Z0-9_][a-zA-Z0-9_-]{0,62}$/;
+// Kubernetes object names (RFC 1123 label); they are interpolated into the
+// generated release workflow, so nothing outside this charset may pass.
+const K8S_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 const kumikoDeployConfigSchema = z
     .object({
     dbUser: z.string().regex(DB_IDENTIFIER_RE).optional(),
     dbName: z.string().regex(DB_IDENTIFIER_RE).optional(),
+    /** Namespace of the prod deployment; default = appName. */
+    namespace: z.string().regex(K8S_NAME_RE).optional(),
+    /** Name of the prod Deployment; default = appName. */
+    deployment: z.string().regex(K8S_NAME_RE).optional(),
     // "directory" is the only behaviour left; the key stays valid so existing
     // package.json files keep scaffolding.
     stackNetwork: z
@@ -176,6 +184,25 @@ function parseDeployConfig(raw) {
             : ["kumiko", "deploy", ...issue.path.map(String)].join(".");
     throw new Error(`scaffoldDeploy: invalid package.json#${location} — ${issue?.message ?? "validation failed"}`);
 }
+/** Release target from `package.json#kumiko.deploy`; throws on an invalid deploy config. */
+export function readReleaseTarget(sourceDir, appName) {
+    const pkgJsonPath = join(sourceDir, "package.json");
+    const raw = existsSync(pkgJsonPath)
+        ? parseJsonOrThrow(readFileSync(pkgJsonPath, "utf-8"), pkgJsonPath)
+        : undefined;
+    const config = parseDeployConfig(extractDeployConfigRaw(raw));
+    const namespace = config.namespace ?? appName;
+    const deployment = config.deployment ?? appName;
+    for (const [field, value] of [
+        ["namespace", namespace],
+        ["deployment", deployment],
+    ]) {
+        if (!K8S_NAME_RE.test(value)) {
+            throw new Error(`scaffoldDeploy: "${value}" cannot serve as the release ${field} (must match ${K8S_NAME_RE}); set package.json#kumiko.deploy.${field}`);
+        }
+    }
+    return { namespace, deployment };
+}
 function resolveDbIdentifier(configured, appName, field, role) {
     const effective = configured ?? appName;
     // The default (appName) already passed isKebabSegment's charset check but
@@ -197,7 +224,7 @@ function resolveDeployConfig(deployConfigRaw, appName) {
         dbName: resolveDbIdentifier(config.dbName, appName, "dbName", "DB name"),
     };
 }
-function detectOptionalSurfaces(sourceDir, appName) {
+function detectOptionalSurfaces(sourceDir, appName, ensuredRegistryConfigFiles) {
     const hasSeeds = existsSync(join(sourceDir, "seeds"));
     let hasPrivateGhPackages = false;
     let installFromFullTree = false;
@@ -237,7 +264,7 @@ function detectOptionalSurfaces(sourceDir, appName) {
             console.warn(message);
         }
     }
-    const registryConfigFiles = REGISTRY_CONFIG_FILES.filter((f) => existsSync(join(sourceDir, f)));
+    const registryConfigFiles = REGISTRY_CONFIG_FILES.filter((f) => ensuredRegistryConfigFiles.includes(f) || existsSync(join(sourceDir, f)));
     return {
         hasSeeds,
         hasPrivateGhPackages,
@@ -247,10 +274,11 @@ function detectOptionalSurfaces(sourceDir, appName) {
     };
 }
 // Unconsumed-mustache guard. After step 1+2 the only legitimate `{{`
-// survivors are Docker/Go template tags (`{{.Name}}`, leading `.`). An
+// survivors are Docker/Go template tags (`{{.Name}}`, leading `.`) and GitHub
+// Actions expressions (`${{ github.sha }}`, leading `$`). An
 // orphan close-tag (`{{/foo}}` without an opener) matches neither step and
 // would otherwise leak into the rendered file as a silent failure.
-const ORPHAN_MUSTACHE_RE = /\{\{(?!\.)[^}]*\}\}/;
+const ORPHAN_MUSTACHE_RE = /(?<!\$)\{\{(?!\.)[^}]*\}\}/;
 export function render(source, subs, flags) {
     // Step 1: handle mustache-style block conditionals `{{#flag}}...{{/flag}}`
     // (multiline-aware via [\s\S]). When flag is truthy → keep inner content;
@@ -267,7 +295,7 @@ export function render(source, subs, flags) {
     // narrow: lowercase-leading identifier followed by alphanumerics. That
     // excludes Docker/Go template syntax like `{{.Name}}` (leading `.`)
     // which appears verbatim in the migrate-step.sh shell snippet.
-    result = result.replace(/\{\{([a-z][a-zA-Z0-9]*)\}\}/g, (full, key) => {
+    result = result.replace(/(?<!\$)\{\{([a-z][a-zA-Z0-9]*)\}\}/g, (full, key) => {
         const value = subs[key];
         if (value === undefined) {
             throw new Error(`scaffoldDeploy.render: unknown placeholder "${full}"`);

package/dist/scaffold-feature.js

@@ -127,6 +127,7 @@ function renderTsconfig() {
             target: "ESNext",
             module: "ESNext",
             moduleResolution: "bundler",
+            allowImportingTsExtensions: true,
             esModuleInterop: true,
             skipLibCheck: true,
             lib: ["ESNext"],