@cosmicdrift/kumiko-dev-server 0.368.0 → 0.370.0

package/dist/run-dev-app.js

@@ -14,7 +14,7 @@
 import { AuthErrors, AuthHandlers, AuthQueries, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
 import { seedAdminGuarded, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
 import { EXT_SESSION_STORE, resolveSessionStore, resolveTokenVerifier, } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
-import { AUTH_MFA_FEATURE, AuthMfaHandlers, bindMfaRevokeAllOtherSessionsFromFeature, bindRevokeAllPatTokensFromFeature, } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+import { AUTH_MFA_FEATURE, AuthMfaHandlers, bindMfaRevokeAllOtherSessionsFromFeature, bindMfaTokenSecretsFromFeature, bindRevokeAllPatTokensFromFeature, } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
 import { buildEnvConfigOverrides, createConfigResolver, } from "@cosmicdrift/kumiko-bundled-features/config";
 import { bindPatAutoRevokeOnPasswordChangeFromFeature, PAT_FEATURE, patRateLimitFromFeature, revokeAllPatTokensForUser, } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import { bindAutoRevokeFromFeature, SESSIONS_FEATURE, } from "@cosmicdrift/kumiko-bundled-features/sessions";
@@ -23,6 +23,7 @@ import { createInMemoryLoginRateLimiter, parseTrustedProxyHopsEnv, TRUSTED_PROXY
 import { configureBlindIndexKey, configurePiiSubjectKms, } from "@cosmicdrift/kumiko-framework/crypto";
 import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
 import { collectWriteHandlerQns, createRegistry, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, findTierResolverUsage, requireTierResolverPlugin, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { applyBootSeeds } from "@cosmicdrift/kumiko-server-runtime/boot/apply-boot-seeds";
 import { resolveBootCrypto } from "@cosmicdrift/kumiko-server-runtime/boot/boot-crypto";
@@ -32,7 +33,7 @@ import { assertSessionBootInvariants } from "@cosmicdrift/kumiko-server-runtime/
 import { createKumikoServer, logInfo, } from "./create-kumiko-server.js";
 import { captureEphemeralDevPiiKms, resolveDevPiiKms } from "./resolve-dev-pii-kms.js";
 import { renderWelcomeBanner } from "./welcome-banner.js";
-import { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, requireEnv, resolveAuthMail, } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
+import { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, requireEnv, resolveAuthMail, resolveUnsubscribeWiring, } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
 export async function runDevApp(options) {
     // Auto-mix Standard-Features im auth-mode via composeFeatures (single
     // source of truth — auch runProdApp und der per-app drizzle-Schema-
@@ -46,6 +47,16 @@ export async function runDevApp(options) {
         ? resolveAuthMail(options.auth, requireEnv("JWT_SECRET", envSource, "runDevApp"), envSource)
         : undefined;
     const composeAuthOptions = buildComposeAuthOptions(effectiveAuth);
+    const { unsubscribeLinks, unsubscribeRoutes } = resolveUnsubscribeWiring({
+        unsubscribe: options.unsubscribe,
+        publicOrigin: undefined,
+        mailBaseUrl: effectiveAuth?.mail?.baseUrl,
+        envSource,
+        warn: (message) => createFallbackLogger("runDevApp").warn(message),
+    });
+    const extraRoutes = unsubscribeRoutes.length === 0
+        ? options.extraRoutes
+        : [...(options.extraRoutes ?? []), ...unsubscribeRoutes];
     const features = composeFeatures(options.features, {
         includeBundled: !!effectiveAuth,
         ...(composeAuthOptions && { authOptions: composeAuthOptions }),
@@ -163,6 +174,7 @@ export async function runDevApp(options) {
             redis: deps.redis,
             crypto: bootCrypto,
             ...(bootLogger && { log: bootLogger }),
+            ...(unsubscribeLinks && { unsubscribeLinks }),
         });
         return {
             ...boot,
@@ -186,6 +198,12 @@ export async function runDevApp(options) {
     let tokenVerifier;
     const patFeature = features.find((f) => f.name === PAT_FEATURE);
     const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
+    // Same master secret as runProdApp. Without JWT_SECRET the feature keeps
+    // its explicit secrets, or its handlers report the missing binding.
+    const devMasterSecret = envSource["JWT_SECRET"];
+    if (mfaFeature && devMasterSecret) {
+        bindMfaTokenSecretsFromFeature(mfaFeature)?.(devMasterSecret, envSource);
+    }
     if (effectiveAuth &&
         mfaFeature &&
         registry?.getWriteHandler(AuthHandlers.switchTenantMfaGate) === undefined) {
@@ -239,7 +257,7 @@ export async function runDevApp(options) {
         ...(extraContext !== undefined && { extraContext }),
         ...(options.anonymousAccess !== undefined && { anonymousAccess: options.anonymousAccess }),
         ...(options.files !== undefined && { files: options.files }),
-        ...(options.extraRoutes !== undefined && { extraRoutes: options.extraRoutes }),
+        ...(extraRoutes !== undefined && { extraRoutes }),
         ...(options.wire !== undefined && { wire: options.wire }),
         ...(trustedProxyHops !== undefined && { trustedProxyHops }),
         ...(finalEffectiveFeatures !== undefined && {

package/dist/scaffold-app.d.ts

@@ -33,9 +33,9 @@ export type ScaffoldAppOptions = {
      *  (the historical foundation). create-kumiko-app passes the picker output
      *  here so the generated APP_FEATURES reflects the user's selection. */
     readonly features?: ReadonlyArray<ScaffoldFeatureEntry>;
-    /** Test wiring (bunfigs, scripts, example tests, e2e) — `renderTestSetup` from
-     *  @cosmicdrift/kumiko-testing/scaffold. Without it the app gets the legacy
-     *  bunfig pair and no example tests. */
+    /** Test wiring (scripts, example tests, e2e) — `renderTestSetup` from
+     *  @cosmicdrift/kumiko-testing/scaffold. Without it the app gets the managed
+     *  bunfigs but no example tests and fewer standard scripts. */
     readonly testSetup?: ScaffoldTestSetupFactory;
 };
 export type ScaffoldAppResult = {

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 {};