@cosmicdrift/kumiko-cli 0.388.0 → 0.390.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-cli",
-  "version": "0.388.0",
+  "version": "0.390.0",
   "description": "CLI for Kumiko apps. `bunx @cosmicdrift/kumiko-cli new app <name>` scaffolds a runnable workspace; `add feature <name>` mounts a feature; `check` runs boot validation plus the guard suites with the step list derived from kumiko.json; `agent lint`, `project` and `consumer` operate on an existing app; `handbuch build` renders the HTML handbuch.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,18 +36,19 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dev-server": "0.388.0",
-    "@cosmicdrift/kumiko-guards": "0.388.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.388.0",
-    "@cosmicdrift/kumiko-testing": "0.388.0",
+    "@cosmicdrift/kumiko-dev-server": "0.390.0",
+    "@cosmicdrift/kumiko-feature-ast": "0.390.0",
+    "@cosmicdrift/kumiko-guards": "0.390.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.390.0",
+    "@cosmicdrift/kumiko-testing": "0.390.0",
     "marked": "^18.0.3",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
     "sharp": "^0.35.5",
-    "@cosmicdrift/kumiko-bundled-features": "0.388.0",
-    "@cosmicdrift/kumiko-framework": "0.388.0",
-    "@cosmicdrift/kumiko-renderer": "0.388.0"
+    "@cosmicdrift/kumiko-bundled-features": "0.390.0",
+    "@cosmicdrift/kumiko-framework": "0.390.0",
+    "@cosmicdrift/kumiko-renderer": "0.390.0"
   },
   "peerDependenciesMeta": {
     "sharp": {
@@ -64,9 +65,9 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.388.0",
-    "@cosmicdrift/kumiko-framework": "0.388.0",
-    "@cosmicdrift/kumiko-renderer": "0.388.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.390.0",
+    "@cosmicdrift/kumiko-framework": "0.390.0",
+    "@cosmicdrift/kumiko-renderer": "0.390.0",
     "sharp": "^0.35.5"
   },
   "publishConfig": {

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "handbuch build no longer wipes its own inputs",
+    "detail": "The out directory is deleted before the build, so it is now rejected when it sits inside the configured repo, a flow source repo or an input directory, not only when it contains one."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "waitlist-migrate encrypts imported personal data or aborts",
+    "detail": "waitlist-migrate wires the PII KMS and blind-index key from the environment before importing. Without them it aborts with a clear message; --allow-plaintext-pii <reason> opts out for apps without subject encryption."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/src/commands/codemod.ts

@@ -39,13 +39,13 @@ async function runCodemod(ctx: CliCommandContext): Promise<number> {
 
   const { resolveCodemodScript } = await import("@cosmicdrift/kumiko-framework/upgrade-cli");
   const scriptField = `scripts/codemod/${name}.ts`;
-  // The project's own install wins; the framework next to this CLI is the fallback.
+  // The project's own install wins; the feature-ast package next to this CLI is the fallback.
   const script =
     resolveCodemodScript(ctx.cwd, scriptField) ??
     resolveCodemodScript(import.meta.dir, scriptField);
   if (script === null) {
     ctx.out.err(
-      "  Codemod script not found. Install @cosmicdrift/kumiko-framework in this project.",
+      "  Codemod script not found. Install @cosmicdrift/kumiko-feature-ast in this project.",
     );
     return 1;
   }

package/src/commands/consumer.ts

@@ -62,30 +62,44 @@ export const consumerCommand: CliCommand = {
       SEARCH_CONSUMER_NAME,
       ...registry.getAllMultiStreamProjections().keys(),
     ];
+    const { runInSystemRowLevelSecurityScope } = await import(
+      "@cosmicdrift/kumiko-framework/internal/row-level-security"
+    );
     const { db, close } = createDbConnection({ url: databaseUrl });
 
     try {
       await createEventConsumerStateTable(db);
-      switch (sub) {
-        case "list":
-          return await listConsumers(ctx, db, registeredConsumerNames, listConsumersWithState);
-        case "status":
-          return await showConsumerStatus(ctx, db, arg, registeredConsumerNames, getConsumerState);
-        case "restart":
-          return await transitionOne(ctx, "restart", arg, "restarted", (name) =>
-            restartConsumer(db, name),
-          );
-        case "disable":
-          return await transitionOne(ctx, "disable", arg, "disabled", (name) =>
-            disableConsumer(db, name),
-          );
-        case "enable":
-          return await transitionOne(ctx, "enable", arg, "enabled", (name) =>
-            enableConsumer(db, name),
-          );
-        case "skip":
-          return await skipOne(ctx, db, arg, skipPoisonEvent);
-      }
+      return await runInSystemRowLevelSecurityScope(
+        "operator consumer tool skips poison events, which reads the events of every tenant",
+        async () => {
+          switch (sub) {
+            case "list":
+              return await listConsumers(ctx, db, registeredConsumerNames, listConsumersWithState);
+            case "status":
+              return await showConsumerStatus(
+                ctx,
+                db,
+                arg,
+                registeredConsumerNames,
+                getConsumerState,
+              );
+            case "restart":
+              return await transitionOne(ctx, "restart", arg, "restarted", (name) =>
+                restartConsumer(db, name),
+              );
+            case "disable":
+              return await transitionOne(ctx, "disable", arg, "disabled", (name) =>
+                disableConsumer(db, name),
+              );
+            case "enable":
+              return await transitionOne(ctx, "enable", arg, "enabled", (name) =>
+                enableConsumer(db, name),
+              );
+            case "skip":
+              return await skipOne(ctx, db, arg, skipPoisonEvent);
+          }
+        },
+      );
     } catch (e) {
       ctx.out.err("");
       ctx.out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);

package/src/commands/handbuch.ts

@@ -46,6 +46,33 @@ function containsPath(parentDir: string, candidate: string): boolean {
   return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
 
+type OutDirContext = {
+  readonly outDir: string;
+  readonly rootDir: string;
+  readonly cwd: string;
+  readonly sourceRepoDirs: readonly string[];
+  readonly inputDirs: readonly string[];
+};
+
+function wipesBuildInputs({
+  outDir,
+  rootDir,
+  cwd,
+  sourceRepoDirs,
+  inputDirs,
+}: OutDirContext): boolean {
+  const containsOutDir = (dir: string) => containsPath(dir, outDir);
+  const wipesProtectedDir = [cwd, rootDir, ...sourceRepoDirs, ...inputDirs].some((dir) =>
+    containsPath(outDir, dir),
+  );
+  // The default out dir lives under --root, which a "." repo legitimately is.
+  const outIsDefaultLocation = containsPath(join(rootDir, ".handbuch"), outDir);
+  const lieInsideSource =
+    inputDirs.some(containsOutDir) ||
+    (!outIsDefaultLocation && sourceRepoDirs.some(containsOutDir));
+  return wipesProtectedDir || lieInsideSource;
+}
+
 async function runBuild(ctx: CliCommandContext, args: ReadonlyArray<string>): Promise<number> {
   let parsed: ReturnType<
     typeof parseArgs<{ options: typeof BUILD_OPTIONS; allowPositionals: true }>
@@ -90,20 +117,21 @@ async function runBuild(ctx: CliCommandContext, args: ReadonlyArray<string>): Pr
   // buildHandbuch wipes outDir recursively, so a mistyped --out must never be
   // (or contain) a directory the build reads from or the user works in.
   const outDir = resolve(ctx.cwd, values.out ?? join(rootDir, ".handbuch", appSlug(configPath)));
-  const protectedDirs = [
-    ctx.cwd,
-    rootDir,
+  const optionalDir = (value: string | undefined) => (value ? resolve(ctx.cwd, value) : undefined);
+  const inputDirs = [values.texts, values.shots, values["web-texts"], values["web-shots"]].flatMap(
+    (value) => optionalDir(value) ?? [],
+  );
+  const sourceRepoDirs = [
     resolve(rootDir, config.repo),
     ...(config.flowSources ?? []).map((source) => resolve(rootDir, source.repo)),
   ];
-  if (protectedDirs.some((dir) => containsPath(outDir, dir))) {
+  if (wipesBuildInputs({ outDir, rootDir, cwd: ctx.cwd, sourceRepoDirs, inputDirs })) {
     return usageError(
       ctx,
-      `Refusing to build into ${outDir}: it is or contains the working directory, --root or a source repo, and is deleted before the build.`,
+      `Refusing to build into ${outDir}: it is, contains or lies inside the working directory, --root, a source repo or an input directory, and is deleted before the build.`,
     );
   }
 
-  const optionalDir = (value: string | undefined) => (value ? resolve(ctx.cwd, value) : undefined);
   try {
     const result = await buildHandbuch(config, {
       rootDir,

package/src/commands/kms-wiring.ts

@@ -17,6 +17,8 @@ export async function wireKmsFromEnv(options: {
   readonly log: (line: string) => void;
   readonly features: readonly FeatureDefinition[];
   readonly allowPlaintextPii?: string | undefined;
+  /** What goes wrong without the wiring; completes the abort message. */
+  readonly consequence?: string;
 }): Promise<KmsWiring> {
   const crypto = await import("@cosmicdrift/kumiko-framework/crypto");
   const { assertPiiBootInvariants } = await import(
@@ -46,7 +48,7 @@ export async function wireKmsFromEnv(options: {
     await wiring.close();
     const reason = e instanceof Error ? e.message : String(e);
     throw new Error(
-      `${options.logPrefix} ${reason} The rebuild would null the blind-index columns. Provide PLATFORM_KEK, SUBJECT_KEYS_DATABASE_URL and KUMIKO_BLIND_INDEX_KEY, or pass --allow-plaintext-pii <reason>.`,
+      `${options.logPrefix} ${reason} ${options.consequence ?? "The rebuild would null the blind-index columns."} Provide PLATFORM_KEK, SUBJECT_KEYS_DATABASE_URL and KUMIKO_BLIND_INDEX_KEY, or pass --allow-plaintext-pii <reason>.`,
     );
   }
   return wiring;

package/src/commands/ops/backfill-pii.ts

@@ -223,11 +223,18 @@ export async function runBackfillPii(ctx: CliCommandContext): Promise<number> {
     crypto.configurePiiSubjectKms(wiring.kms);
     crypto.configureBlindIndexKey(wiring.blindIndexKey);
     const registry = createRegistry(config.features);
+    const { runInSystemRowLevelSecurityScope } = await import(
+      "@cosmicdrift/kumiko-framework/internal/row-level-security"
+    );
     const { db, close } = createDbConnection({ url: databaseUrl, maxConnections: 4 });
     try {
-      return args.mode === "rebuild"
-        ? await rebuildPiiProjections(ctx, db, registry, crypto)
-        : await backfillPii(ctx, db, registry, args);
+      return await runInSystemRowLevelSecurityScope(
+        "operator PII backfill rewrites events and projections of every tenant",
+        () =>
+          args.mode === "rebuild"
+            ? rebuildPiiProjections(ctx, db, registry, crypto)
+            : backfillPii(ctx, db, registry, args),
+      );
     } finally {
       await close();
     }

package/src/commands/ops/waitlist-migrate.ts

@@ -1,9 +1,10 @@
 import { join } from "node:path";
+import { wireKmsFromEnv } from "../kms-wiring";
 import { loadAppConfig } from "../load-app-config";
 import type { CliCommandContext } from "../types";
 
 const USAGE =
-  "Usage: kumiko ops waitlist-migrate --from <offlot|publicstatus> [--dry-run] [--source-table <name>] [--locale <tag>]";
+  "Usage: kumiko ops waitlist-migrate --from <offlot|publicstatus> [--dry-run] [--source-table <name>] [--locale <tag>] [--allow-plaintext-pii <reason>]";
 
 function flagValue(argv: readonly string[], flag: string): string | undefined {
   const index = argv.indexOf(flag);
@@ -17,6 +18,35 @@ function fail(ctx: CliCommandContext, ...lines: readonly string[]): number {
   return 1;
 }
 
+type AppConfig = NonNullable<Awaited<ReturnType<typeof loadAppConfig>>>;
+type Preflight =
+  | { readonly ok: true; readonly databaseUrl: string; readonly config: AppConfig }
+  | { readonly ok: false; readonly exitCode: number };
+
+async function preflight(ctx: CliCommandContext): Promise<Preflight> {
+  const configPath = join(ctx.cwd, "kumiko.config.ts");
+  if (!(await Bun.file(configPath).exists())) {
+    return { ok: false, exitCode: fail(ctx, `kumiko.config.ts not found at: ${configPath}`) };
+  }
+  const databaseUrl = process.env["DATABASE_URL"];
+  if (!databaseUrl) return { ok: false, exitCode: fail(ctx, "DATABASE_URL not set.") };
+  const config = await loadAppConfig(ctx, configPath);
+  if (config === null) return { ok: false, exitCode: 1 };
+  if (!config.features.some((feature) => feature.name === "waitlist")) {
+    const message =
+      "The app config does not mount the framework `waitlist` feature; add createWaitlistFeature() first.";
+    return { ok: false, exitCode: fail(ctx, message) };
+  }
+  return { ok: true, databaseUrl, config };
+}
+
+function plaintextPiiReasonIsMissing(ctx: CliCommandContext): boolean {
+  return (
+    ctx.argv.includes("--allow-plaintext-pii") &&
+    !flagValue(ctx.argv, "--allow-plaintext-pii")?.trim()
+  );
+}
+
 export const waitlistMigrateOp = {
   id: "waitlist-migrate",
   description: "Copy a legacy app waitlist into the framework waitlist entity (idempotent)",
@@ -30,31 +60,39 @@ export const waitlistMigrateOp = {
     const from = flagValue(ctx.argv, "--from");
     if (!isLegacyWaitlistSource(from)) return fail(ctx, USAGE);
 
-    const configPath = join(ctx.cwd, "kumiko.config.ts");
-    if (!(await Bun.file(configPath).exists())) {
-      return fail(ctx, `kumiko.config.ts not found at: ${configPath}`);
-    }
-    const databaseUrl = process.env["DATABASE_URL"];
-    if (!databaseUrl) return fail(ctx, "DATABASE_URL not set.");
-    const config = await loadAppConfig(ctx, configPath);
-    if (config === null) return 1;
-    if (!config.features.some((feature) => feature.name === "waitlist")) {
-      return fail(
-        ctx,
-        "The app config does not mount the framework `waitlist` feature; add createWaitlistFeature() first.",
-      );
+    const checked = await preflight(ctx);
+    if (!checked.ok) return checked.exitCode;
+    if (plaintextPiiReasonIsMissing(ctx)) {
+      return fail(ctx, "--allow-plaintext-pii requires a non-empty reason");
     }
 
     const dryRun = ctx.argv.includes("--dry-run");
     const { createDbConnection } = await import("@cosmicdrift/kumiko-framework/db");
-    const { db, close } = createDbConnection({ url: databaseUrl });
+    const { runInSystemRowLevelSecurityScope } = await import(
+      "@cosmicdrift/kumiko-framework/internal/row-level-security"
+    );
+    const { db, close } = createDbConnection({ url: checked.databaseUrl });
+    let wiring: Awaited<ReturnType<typeof wireKmsFromEnv>> | undefined;
     try {
-      const report = await migrateLegacyWaitlist(db, {
-        from,
-        dryRun,
-        sourceTable: flagValue(ctx.argv, "--source-table") ?? DEFAULT_LEGACY_SOURCE_TABLE[from],
-        defaultLocale: flagValue(ctx.argv, "--locale") ?? DEFAULT_IMPORT_LOCALE,
+      // Without the KMS the executor would write name/email/message as plaintext into the
+      // event log, where crypto-shredding cannot reach them.
+      wiring = await wireKmsFromEnv({
+        logPrefix: "[kumiko ops waitlist-migrate]",
+        log: (line) => ctx.out.log(line),
+        features: checked.config.features,
+        allowPlaintextPii: flagValue(ctx.argv, "--allow-plaintext-pii"),
+        consequence: "The import would store personal data as plaintext in the event log.",
       });
+      const report = await runInSystemRowLevelSecurityScope(
+        "operator waitlist migration imports signups into the platform tenant and archives legacy streams",
+        () =>
+          migrateLegacyWaitlist(db, {
+            from,
+            dryRun,
+            sourceTable: flagValue(ctx.argv, "--source-table") ?? DEFAULT_LEGACY_SOURCE_TABLE[from],
+            defaultLocale: flagValue(ctx.argv, "--locale") ?? DEFAULT_IMPORT_LOCALE,
+          }),
+      );
       ctx.out.log("");
       ctx.out.log(
         `  ${dryRun ? "[dry-run] " : ""}waitlist-migrate --from ${from}: read ${report.read}, ${dryRun ? "would create" : "created"} ${report.created}, already present ${report.skipped}, unreadable ${report.unreadable}, legacy streams ${dryRun ? "would archive" : "archived"} ${report.archivedStreams}`,
@@ -64,6 +102,7 @@ export const waitlistMigrateOp = {
     } catch (e) {
       return fail(ctx, `✗ ${e instanceof Error ? e.message : String(e)}`);
     } finally {
+      await wiring?.close();
       await close();
     }
   },

package/src/commands/project.ts

@@ -67,6 +67,9 @@ export const projectCommand: CliCommand = {
     } = await import("@cosmicdrift/kumiko-framework/pipeline");
 
     const registry = createRegistry(config.features);
+    const { runInSystemRowLevelSecurityScope } = await import(
+      "@cosmicdrift/kumiko-framework/internal/row-level-security"
+    );
     const { db, close } = createDbConnection({ url: databaseUrl });
     let wiring: Awaited<ReturnType<typeof wireKmsFromEnv>> | undefined;
 
@@ -80,14 +83,19 @@ export const projectCommand: CliCommand = {
         });
       }
       await createProjectionStateTable(db);
-      switch (sub) {
-        case "list":
-          return await listProjections(ctx, db, registry, listProjectionsWithState);
-        case "status":
-          return await showProjectionStatus(ctx, db, arg, registry, getProjectionState);
-        case "rebuild":
-          return await rebuildOne(ctx, db, arg, registry, rebuildProjection);
-      }
+      return await runInSystemRowLevelSecurityScope(
+        "operator projection tool reads and rebuilds projections of every tenant",
+        async () => {
+          switch (sub) {
+            case "list":
+              return await listProjections(ctx, db, registry, listProjectionsWithState);
+            case "status":
+              return await showProjectionStatus(ctx, db, arg, registry, getProjectionState);
+            case "rebuild":
+              return await rebuildOne(ctx, db, arg, registry, rebuildProjection);
+          }
+        },
+      );
     } catch (e) {
       ctx.out.err("");
       ctx.out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);

package/src/handbuch/buildinfo.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { findInstalledPackageDir } from "@cosmicdrift/kumiko-server-runtime/resolve-installed-package";
 
 const FRAMEWORK_PACKAGE = "@cosmicdrift/kumiko-framework";
 
@@ -31,12 +32,10 @@ function stringField(record: Record<string, unknown> | undefined, key: string):
 }
 
 function resolvedFrameworkVersion(repoDir: string): string | undefined {
-  try {
-    const manifest = Bun.resolveSync(`${FRAMEWORK_PACKAGE}/package.json`, repoDir);
-    return stringField(readJson(manifest), "version");
-  } catch {
-    return undefined;
-  }
+  const packageDir = findInstalledPackageDir(FRAMEWORK_PACKAGE, repoDir);
+  return packageDir === undefined
+    ? undefined
+    : stringField(readJson(join(packageDir, "package.json")), "version");
 }
 
 function gitOutput(repoDir: string, args: string[]): string | undefined {

package/src/handbuch/uistrings.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findInstalledPackageDir } from "@cosmicdrift/kumiko-server-runtime/resolve-installed-package";
 
 export type UiStringSources = {
   repoDir: string;
@@ -183,23 +184,6 @@ export function findMissingUiTerms(
   );
 }
 
-function packageDirectory(packageName: string, fromDir: string): string | undefined {
-  try {
-    // Bare-name resolution fails for packages without a "." export (bundled-features).
-    let current = dirname(Bun.resolveSync(`${packageName}/package.json`, fromDir));
-    while (current !== dirname(current)) {
-      const manifest = join(current, "package.json");
-      if (existsSync(manifest) && JSON.parse(readFileSync(manifest, "utf8")).name === packageName) {
-        return current;
-      }
-      current = dirname(current);
-    }
-  } catch {
-    return undefined;
-  }
-  return undefined;
-}
-
 function scanFiles(cwd: string, patterns: readonly string[]): string[] {
   const files = new Set<string>();
   for (const pattern of patterns) {
@@ -273,7 +257,7 @@ export function collectUiStrings(sources: UiStringSources): UiStringMap {
   };
   absorb(scanFiles(sources.repoDir, sources.globs));
   for (const entry of sources.packages) {
-    const directory = packageDirectory(entry.package, sources.repoDir);
+    const directory = findInstalledPackageDir(entry.package, sources.repoDir);
     if (directory) absorb(scanFiles(directory, entry.files), entry.locale);
   }
   return merged;

package/src/index.ts

@@ -9,11 +9,7 @@
 // `consumer`). Workspace-only maintainer commands (ci:guards, dev, build, …)
 // stay in the framework repo's bin/kumiko.ts.
 
-import {
-  resolveFrameworkVersion,
-  scaffoldApp,
-  scaffoldAppFeature,
-} from "@cosmicdrift/kumiko-dev-server";
+import { scaffoldApp, scaffoldAppFeature } from "@cosmicdrift/kumiko-dev-server";
 import { renderTestSetup } from "@cosmicdrift/kumiko-testing/scaffold";
 import type { CliCommand } from "./commands";
 import { APP_COMMANDS, findAppCommand } from "./commands";
@@ -93,12 +89,10 @@ async function runNew(args: readonly string[], out: Output, cwd: string): Promis
     return 1;
   }
   try {
-    const frameworkVersion = resolveFrameworkVersion();
     const result = await scaffoldApp({
       name,
       destination: `${cwd}/${name}`,
       testSetup: renderTestSetup,
-      ...(frameworkVersion !== undefined && { frameworkVersion }),
     });
     out.log(`✓ Scaffolded ${result.appName} → ${result.destination}`);
     out.log("");