@cosmicdrift/kumiko-dev-server 0.368.0 → 0.370.0

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"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.368.0",
+  "version": "0.370.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -18,6 +18,7 @@
     "runtime": "dev",
     "bunOnlyExports": [
       ".",
+      "./managed-files",
       "./setup-test-stack-from-features"
     ]
   },
@@ -38,6 +39,10 @@
       "types": "./dist/env-schema.d.ts",
       "default": "./dist/env-schema.js"
     },
+    "./managed-files": {
+      "types": "./dist/managed-files/index.d.ts",
+      "default": "./dist/managed-files/index.js"
+    },
     "./setup-test-stack-from-features": {
       "types": "./dist/setup-test-stack-from-features.d.ts",
       "default": "./dist/setup-test-stack-from-features.js"
@@ -67,14 +72,14 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.368.0",
-    "@cosmicdrift/kumiko-framework": "0.368.0",
-    "@cosmicdrift/kumiko-headless": "0.368.0",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.368.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.368.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.368.0",
-    "@cosmicdrift/kumiko-testing": "0.368.0",
-    "@cosmicdrift/kumiko-types": "0.368.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.370.0",
+    "@cosmicdrift/kumiko-framework": "0.370.0",
+    "@cosmicdrift/kumiko-headless": "0.370.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.370.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.370.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.370.0",
+    "@cosmicdrift/kumiko-testing": "0.370.0",
+    "@cosmicdrift/kumiko-types": "0.370.0",
     "bun-types": "^1.3.13",
     "ts-morph": "^28.0.0",
     "zod": "^4.4.3"
@@ -99,6 +104,10 @@
         "types": "./dist/env-schema.d.ts",
         "default": "./dist/env-schema.js"
       },
+      "./managed-files": {
+        "types": "./dist/managed-files/index.d.ts",
+        "default": "./dist/managed-files/index.js"
+      },
       "./setup-test-stack-from-features": {
         "types": "./dist/setup-test-stack-from-features.d.ts",
         "default": "./dist/setup-test-stack-from-features.js"

package/src/changes.json

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "runDevApp binds the MFA token secrets",
+    "detail": "When auth-mfa is mounted and JWT_SECRET is set, runDevApp binds the MFA token secrets the same way runProdApp does."
+  },
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "composeAuthStack, composeSaasStack and composeSecurityStack",
+    "detail": "composeAuthStack({ sessions?, mfa?, accountSecurity? }) mounts auth-foundation and sessions, with mfa also auth-mfa and account-security; the password login still comes from the auth option or composeFeatures. composeSaasStack({ billing: \"stripe\" | \"mollie\", tiers, caps?, waitlist?, billingFoundation? }) mounts billing-foundation and tier-engine, cap-counter plus cap-overview with caps, waitlist with waitlist. With \"stripe\" the runProdApp billing option mounts subscription-stripe and the tier-sync webhook route; with \"mollie\" the stack mounts subscription-mollie from the mollie options and the app adds the webhook route. composeSecurityStack({ includeSessions? }) mounts sessions, crypto-shredding, rate-limiting and audit. composeGdprStack({ selfService: { userDataRights? } }) adds sessions, user-data-rights and user-profile in the order dsgvoSelfServiceFeatures used. billing-foundation requires tenant-lifecycle and compliance-profiles, which composeGdprStack({ tenantLifecycle: true }) mounts. user-profile in selfService requires user-data-rights-defaults and auth-email-password; composeUserDataRightsStack mounts the defaults, and the login comes from the auth option. Recipe: samples/recipes/compose-stacks."
+  },
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "Managed files: one template source for the scaffold, kumiko check managed and kumiko sync-managed",
+    "detail": "deploy/Dockerfile, deploy/Dockerfile.dockerignore, deploy/migrate-step.sh, .husky/pre-push, .github/workflows/{ci,release,cache-cleanup}.yml, the bunfigs and kumiko/schema.ts carry a kumiko-managed marker on line 1 (line 2 after a shebang or # syntax= line). kumiko new app writes them, plus kumiko.config.ts, bin/server.ts (was bin/dev.ts), bin/env-schema.ts, e2e/_helpers and src/__tests__/_setup.ts; bunfig.ci.toml is gone. kumiko/schema.ts is generated from kumiko.config.ts. kumiko-init-deploy prints a deprecation notice and goes away in the next release. Release targets come from package.json#kumiko.deploy.namespace and .deployment (default: the app name).",
+    "migration": "Existing apps: add kumiko.config.ts with defineAppConfig, then run kumiko sync-managed (dry run), kumiko sync-managed --write --adopt for files that are identical or should follow the template, and mark deliberate deviations with \"# kumiko-managed: local <reason>\" on line 2. Until kumiko.config.ts calls defineAppConfig, kumiko check only warns about drift and missing scripts."
+  },
   {
     "version": "0.368.0",
     "type": "breaking",

package/templates/managed/cache-cleanup.yml.template

@@ -0,0 +1,30 @@
+name: cache-cleanup
+
+on:
+  schedule:
+    - cron: "0 3 * * 1"
+  workflow_dispatch: {}
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+    steps:
+      - name: Delete caches unused for 3+ days
+        # Actions cache is branch-scoped: every PR branch writes its own copy
+        # even with an identical key, and GitHub only auto-evicts on the
+        # per-repo 10GB cap or 7-day-unused rule. This keeps repos well under
+        # that cap instead of relying on eviction churn.
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          cutoff=$(date -u -d '3 days ago' +%s)
+          gh api --paginate "repos/$REPO/actions/caches?per_page=100" --jq '.actions_caches[] | "\(.id) \(.last_accessed_at)"' |
+          while read -r id ts; do
+            age=$(date -u -d "$ts" +%s)
+            if [ "$age" -lt "$cutoff" ]; then
+              gh api -X DELETE "repos/$REPO/actions/caches/$id" && echo "deleted $id"
+            fi
+          done

package/templates/managed/ci.yml.template

@@ -0,0 +1,65 @@
+# CI for {{appName}}: a thin orchestrator over the reusable workflows in
+# cosmicdriftgamestudio/infra. Jobs only this app needs go into an unmanaged
+# workflow next to this one (e.g. ci-extra.yml).
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+env:
+  HUSKY: "0"
+
+jobs:
+  test:
+    uses: cosmicdriftgamestudio/infra/.github/workflows/_app-test.yml@main
+    with:
+      ui-guards: {{uiGuards}}
+      # The boot gate in kumiko-schema validate demands a provider for file
+      # fields; CI only checks that one is configured.
+      file-storage-provider: "inmemory"
+    secrets: inherit
+
+  integration:
+    uses: cosmicdriftgamestudio/infra/.github/workflows/_app-integration.yml@main
+{{#minio}}
+    with:
+      minio: true
+{{/minio}}
+    secrets: inherit
+
+  # merge_group included: as a required check in a merge queue, e2e would
+  # otherwise never report and block the merge.
+  e2e:
+    if: contains(fromJSON('["pull_request","merge_group"]'), github.event_name)
+    uses: cosmicdriftgamestudio/infra/.github/workflows/_app-e2e.yml@main
+{{#e2eInputs}}
+    with:
+{{/e2eInputs}}
+{{#meilisearch}}
+      meilisearch: true
+{{/meilisearch}}
+{{#minio}}
+      minio: true
+{{/minio}}
+    secrets: inherit
+
+  # Build on main only; the rollout runs through the manual release workflow.
+  build:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [test, integration]
+    permissions:
+      contents: read
+      packages: write
+    uses: cosmicdriftgamestudio/infra/.github/workflows/_docker-build-push.yml@main
+    with:
+      image-name: {{appName}}
+      dockerfile: deploy/Dockerfile
+    secrets: inherit

package/templates/managed/husky-pre-push.template

@@ -0,0 +1,36 @@
+#!/usr/bin/env sh
+# PRE_PUSH_SKIP is checked here too so the bypass works even without node_modules.
+if [ "${PRE_PUSH_SKIP:-0}" = "1" ]; then
+  echo "[pre-push] PRE_PUSH_SKIP=1 — hook skipped"
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+if [ -z "$REPO_ROOT" ]; then
+  echo "[pre-push] FATAL: git rev-parse --show-toplevel failed — refusing push" >&2
+  exit 1
+fi
+
+# Walk up to / so a worktree without its own node_modules resolves via the
+# parent install; `[ -x ]` also skips a broken (uninstalled) symlink.
+BIN=""
+DIR="$REPO_ROOT"
+while true; do
+  CANDIDATE="$DIR/node_modules/.bin/kumiko-pre-push"
+  if [ -x "$CANDIDATE" ]; then
+    BIN="$CANDIDATE"
+    break
+  fi
+  if [ "$DIR" = "/" ]; then
+    break
+  fi
+  DIR="$(dirname "$DIR")"
+done
+
+if [ -z "$BIN" ]; then
+  echo "[pre-push] kumiko-pre-push not found in any node_modules/.bin above $REPO_ROOT." >&2
+  echo "Run \`bun install\`, or set PRE_PUSH_SKIP=1 to bypass this hook." >&2
+  exit 1
+fi
+
+cd "$REPO_ROOT" && exec "$BIN" "$@"

package/templates/managed/kumiko-schema.ts.template

@@ -0,0 +1,12 @@
+// Input of the schema tooling (kumiko-schema generate|apply|validate and the
+// boot step of kumiko check), derived from kumiko.config.ts. Edit the feature
+// lists there.
+
+import { allAppFeatures } from "@cosmicdrift/kumiko-framework/config";
+import { collectTableMetas, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import appConfig from "../kumiko.config";
+
+export const FEATURES: readonly FeatureDefinition[] = allAppFeatures(appConfig);
+
+export const ENTITY_METAS: readonly EntityTableMeta[] = collectTableMetas(FEATURES);

package/templates/managed/release.yml.template

@@ -0,0 +1,55 @@
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: "Full 40-char main SHA; image sha-<7> must exist"
+        required: true
+        type: string
+
+concurrency:
+  group: release-{{appName}}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  actions: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Verify SHA
+        env:
+          SHA: ${{ inputs.sha }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          if ! [[ "$SHA" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "::error::sha must be a full 40-char lowercase hex SHA."
+            exit 1
+          fi
+          if ! git merge-base --is-ancestor "$SHA" origin/main; then
+            echo "::error::$SHA is not an ancestor of origin/main."
+            exit 1
+          fi
+          count=$(gh api "repos/$GITHUB_REPOSITORY/actions/workflows/ci.yml/runs?head_sha=$SHA&event=push&status=success" --jq '.total_count')
+          if [ "${count:-0}" -le 0 ]; then
+            echo "::error::No successful CI push run found for $SHA."
+            exit 1
+          fi
+
+  deploy:
+    needs: verify
+    uses: cosmicdriftgamestudio/infra/.github/workflows/_app-deploy.yml@main
+    with:
+      namespace: {{namespace}}
+      deployment: {{deployment}}
+      image-name: {{appName}}
+      git_sha: ${{ inputs.sha }}
+    secrets: inherit