@cosmicdrift/kumiko-cli 0.368.0 → 0.370.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-cli",
-  "version": "0.368.0",
+  "version": "0.370.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": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,10 +36,10 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dev-server": "0.368.0",
-    "@cosmicdrift/kumiko-guards": "0.368.0",
-    "@cosmicdrift/kumiko-repo-manifest": "0.368.0",
-    "@cosmicdrift/kumiko-testing": "0.368.0",
+    "@cosmicdrift/kumiko-dev-server": "0.370.0",
+    "@cosmicdrift/kumiko-guards": "0.370.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.370.0",
+    "@cosmicdrift/kumiko-testing": "0.370.0",
     "marked": "^18.0.3",
     "zod": "^4.4.3"
   },
@@ -64,9 +64,9 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.368.0",
-    "@cosmicdrift/kumiko-framework": "0.368.0",
-    "@cosmicdrift/kumiko-headless": "0.368.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.370.0",
+    "@cosmicdrift/kumiko-framework": "0.370.0",
+    "@cosmicdrift/kumiko-headless": "0.370.0",
     "sharp": "^0.35.5"
   },
   "publishConfig": {

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "kumiko ops backfill-pii encrypts plaintext PII events of the app in kumiko.config.ts",
+    "detail": "kumiko ops backfill-pii [--dry-run] [--resolve-owner-from-projection] [--rekey-tenant-keyed-owner-fields] [--erase-unresolvable-subjects] runs the framework PII backfill over the features of kumiko.config.ts with DATABASE_URL, PLATFORM_KEK (and PLATFORM_KEK_PREVIOUS) and KUMIKO_BLIND_INDEX_KEY from the environment. It does not rebuild projections; run kumiko ops backfill-pii --rebuild afterwards, which rebuilds only the projections of entities with personal fields. A second backfill run changes nothing. Apps with their own backfill-pii script switch to this command and to the two-step runbook."
+  },
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "kumiko check gains the managed and scripts steps; new kumiko sync-managed and kumiko ports",
+    "detail": "kumiko check managed compares framework-owned files with the installed templates and prints a diff; files with a local marker are skipped and listed. kumiko check scripts requires dev, build, start, typecheck, lint, check, test, test:unit, test:integration, test:integration:ci, test:dom (with uiRoots), test:real, e2e, e2e:real, screenshots and prepare, and lists extras. Both steps fail only once the app calls defineAppConfig. kumiko check accepts step ids as positional filters (kumiko check managed scripts). kumiko sync-managed [--write] [--adopt] writes the templates; it never overwrites a file without marker unless --adopt is passed, never touches local files and refuses symlinked paths. kumiko ports [workspace-root] lists the ports of every app below the root and exits 1 on a collision. kumiko agent lint also checks prodFeatures."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/src/commands/agent.ts

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { loadAppConfig } from "./load-app-config";
+import { allConfiguredFeatures, loadAppConfig } from "./load-app-config";
 import type { CliCommand } from "./types";
 
 const LINT_SUBCOMMAND = "lint";
@@ -24,8 +24,9 @@ export const agentCommand: CliCommand = {
       ctx.out.err("");
       ctx.out.err("  Create a file that exports your features:");
       ctx.out.err("    // kumiko.config.ts");
+      ctx.out.err('    import { defineAppConfig } from "@cosmicdrift/kumiko-framework/config";');
       ctx.out.err('    import { myFeature } from "./src/features/my-feature";');
-      ctx.out.err("    export default { features: [myFeature] };");
+      ctx.out.err("    export default defineAppConfig({ features: [myFeature], client, ports });");
       ctx.out.err("");
       return 1;
     }
@@ -36,8 +37,9 @@ export const agentCommand: CliCommand = {
       "@cosmicdrift/kumiko-bundled-features/agent-tools"
     );
 
-    const gaps = findAgentDocGaps(config.features);
-    const translationGaps = findHandlerTranslationGaps(config.features);
+    const features = allConfiguredFeatures(config);
+    const gaps = findAgentDocGaps(features);
+    const translationGaps = findHandlerTranslationGaps(features);
 
     if (gaps.length === 0 && translationGaps.length === 0) {
       ctx.out.log("");

package/src/commands/check-managed.ts

@@ -0,0 +1,58 @@
+import type { Output } from "../output";
+
+type ManagedFilesModule = typeof import("@cosmicdrift/kumiko-dev-server/managed-files");
+type ManagedFileReport = ReturnType<ManagedFilesModule["checkManagedFiles"]>["files"][number];
+
+const NOT_ADOPTED_NOTE =
+  "kumiko.config.ts does not call defineAppConfig yet, so these findings are warnings; they fail the check once it does.";
+
+function describeReport(report: ManagedFileReport): string {
+  switch (report.state) {
+    case "ok":
+      return "matches";
+    case "missing":
+      return report.kind === "seed" ? "missing (app-owned seed from `kumiko new app`)" : "missing";
+    case "differs":
+      return "differs from the template (- template, + repo)";
+    case "unmarked":
+      return report.diff === undefined
+        ? "matches but has no kumiko-managed marker"
+        : "no kumiko-managed marker and differs from the template (- template, + repo)";
+    case "local":
+      return `local: ${report.reason}`;
+    case "invalid":
+      return report.message;
+  }
+}
+
+function printIndented(out: Output, text: string): void {
+  for (const line of text.split("\n")) out.log(`        ${line}`);
+}
+
+export async function runManagedCheckStep(
+  out: Output,
+  repoRoot: string,
+  uiRoots: readonly string[],
+): Promise<number> {
+  const managed: ManagedFilesModule = await import("@cosmicdrift/kumiko-dev-server/managed-files");
+  const facts = managed.resolveManagedAppFacts({ appRoot: repoRoot, uiRoots });
+  const result = managed.checkManagedFiles(facts);
+  const drift = result.files.filter(managed.isManagedDrift);
+  const local = result.files.filter((report) => report.state === "local");
+  const okCount = result.files.length - drift.length - local.length;
+  out.log(`    ${okCount}/${result.files.length} managed file(s) match the installed template`);
+  for (const report of local) out.log(`    ~ ${report.path}: ${describeReport(report)}`);
+  for (const report of drift) {
+    out.log(`    ${result.adopted ? "✗" : "!"} ${report.path}: ${describeReport(report)}`);
+    if ((report.state === "differs" || report.state === "unmarked") && report.diff !== undefined) {
+      printIndented(out, report.diff);
+    }
+  }
+  if (drift.length === 0) return 0;
+  out.log("    Fix: kumiko sync-managed --write (files without a marker: add --adopt)");
+  if (!result.adopted) {
+    out.log(`    ${NOT_ADOPTED_NOTE}`);
+    return 0;
+  }
+  return 1;
+}

package/src/commands/check-scripts.ts

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import type { Output } from "../output";
+
+type ManagedFilesModule = typeof import("@cosmicdrift/kumiko-dev-server/managed-files");
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.values(value).every((entry) => typeof entry === "string")
+  );
+}
+
+function readScripts(repoRoot: string): Record<string, string> {
+  const path = join(repoRoot, "package.json");
+  if (!existsSync(path)) throw new Error(`${path} not found`);
+  const raw = parseJsonOrThrow<unknown>(readFileSync(path, "utf-8"), path);
+  const scripts = typeof raw === "object" && raw !== null && "scripts" in raw ? raw.scripts : {};
+  if (!isStringRecord(scripts)) throw new Error(`${path}: "scripts" must map names to strings`);
+  return scripts;
+}
+
+export async function runScriptsCheckStep(
+  out: Output,
+  repoRoot: string,
+  uiRoots: readonly string[],
+): Promise<number> {
+  const managed: ManagedFilesModule = await import("@cosmicdrift/kumiko-dev-server/managed-files");
+  const report = managed.checkAppScripts(readScripts(repoRoot), { hasUi: uiRoots.length > 0 });
+  const adopted = managed.readStaticAppConfig(repoRoot).kind === "defined";
+  if (report.knownExtras.length > 0)
+    out.log(`    extras (standard): ${report.knownExtras.join(", ")}`);
+  if (report.appExtras.length > 0) out.log(`    extras (app): ${report.appExtras.join(", ")}`);
+  if (report.missing.length === 0) {
+    out.log("    all standard scripts present");
+    return 0;
+  }
+  out.log(`    ${adopted ? "✗" : "!"} missing standard scripts: ${report.missing.join(", ")}`);
+  if (!adopted) {
+    out.log("    kumiko.config.ts does not call defineAppConfig yet, so this is a warning.");
+    return 0;
+  }
+  return 1;
+}

package/src/commands/check.ts

@@ -5,7 +5,16 @@ import type { CliCommand, CliCommandContext } from "./types";
 
 const APP_SCHEMA_FILE = "kumiko/schema.ts";
 
-export type CheckStepId = "boot" | "guards" | "ui" | "checks";
+export type CheckStepId = "boot" | "guards" | "ui" | "checks" | "managed" | "scripts";
+
+const CHECK_STEP_IDS: readonly CheckStepId[] = [
+  "boot",
+  "guards",
+  "ui",
+  "checks",
+  "managed",
+  "scripts",
+];
 
 export type CheckStep = {
   readonly id: CheckStepId;
@@ -73,6 +82,20 @@ export function resolveCheckSteps(manifest: RepoManifest, facts: RepoFacts): Che
     label: "Repo checks",
     why: `kind "${manifest.kind}" — testGlobs ${manifest.testGlobs.join(", ")}`,
   });
+  if (manifest.kind === "app") {
+    steps.push(
+      {
+        id: "managed",
+        label: "Managed files",
+        why: 'kind "app" — framework-owned files against the installed template',
+      },
+      {
+        id: "scripts",
+        label: "Standard scripts",
+        why: 'kind "app" — package.json scripts against the script standard',
+      },
+    );
+  }
   return { kind: "steps", steps, waivers };
 }
 
@@ -86,17 +109,49 @@ export type SchemaCli = Pick<
   "runSchemaCli"
 >;
 
+export type AppCheckSteps = {
+  readonly runManagedCheckStep: typeof import("./check-managed").runManagedCheckStep;
+  readonly runScriptsCheckStep: typeof import("./check-scripts").runScriptsCheckStep;
+};
+
 export type CheckDeps = {
   readonly loadGuards: () => Promise<GuardsCli>;
   readonly loadSchemaCli: () => Promise<SchemaCli>;
+  readonly loadAppSteps: () => Promise<AppCheckSteps>;
 };
 
 // Lazy: `kumiko new app` must not pay for ts-morph or the framework runtime.
 const DEFAULT_DEPS: CheckDeps = {
   loadGuards: () => import("@cosmicdrift/kumiko-guards"),
   loadSchemaCli: () => import("@cosmicdrift/kumiko-framework/schema-cli"),
+  loadAppSteps: async () => ({
+    runManagedCheckStep: (await import("./check-managed")).runManagedCheckStep,
+    runScriptsCheckStep: (await import("./check-scripts")).runScriptsCheckStep,
+  }),
 };
 
+function isCheckStepId(arg: string): arg is CheckStepId {
+  return CHECK_STEP_IDS.some((id) => id === arg);
+}
+
+// Positional step ids narrow the run to those steps; an id outside the repo's
+// plan is an error rather than a silent no-op.
+function selectRequestedSteps(
+  ctx: CliCommandContext,
+  plannedSteps: readonly CheckStep[],
+): readonly CheckStep[] | undefined {
+  const onlySteps = ctx.argv.filter(isCheckStepId);
+  const notApplicable = onlySteps.filter((id) => !plannedSteps.some((step) => step.id === id));
+  if (notApplicable.length > 0) {
+    ctx.out.err(`  ✗ step(s) not part of this repo's plan: ${notApplicable.join(", ")}`);
+    ctx.out.err("");
+    return undefined;
+  }
+  return onlySteps.length === 0
+    ? plannedSteps
+    : plannedSteps.filter((step) => onlySteps.includes(step.id));
+}
+
 export async function runCheck(
   ctx: CliCommandContext,
   deps: CheckDeps = DEFAULT_DEPS,
@@ -123,7 +178,7 @@ export async function runCheck(
     return 1;
   }
 
-  const flagsError = guards.cliFlagsError("check", ctx.argv, CHECK_FLAGS);
+  const flagsError = guards.cliFlagsError("check", ctx.argv, [...CHECK_FLAGS, ...CHECK_STEP_IDS]);
   if (flagsError !== undefined) {
     ctx.out.err("");
     ctx.out.err(`  ${flagsError}`);
@@ -131,24 +186,12 @@ export async function runCheck(
     return 1;
   }
 
-  let repo: ReturnType<GuardsCli["findLocalRepo"]>;
-  try {
-    repo = guards.findLocalRepo(ctx.cwd);
-  } catch (e) {
-    ctx.out.err("");
-    ctx.out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
-    ctx.out.err("");
-    return 1;
-  }
-  if (repo === undefined) {
-    ctx.out.err("");
-    ctx.out.err(`  ✗ No Kumiko repo above ${ctx.cwd}.`);
-    ctx.out.err(`    Add a ${REPO_MANIFEST_FILE} at the repo root (kind, sourceRoots, testGlobs).`);
-    ctx.out.err("");
-    return 1;
-  }
+  const repo = findCheckedRepo(ctx, guards);
+  if (repo === undefined) return 1;
 
-  const steps = printCheckPlan(ctx, repo);
+  const plannedSteps = printCheckPlan(ctx, repo);
+  if (plannedSteps === undefined) return 1;
+  const steps = selectRequestedSteps(ctx, plannedSteps);
   if (steps === undefined) return 1;
 
   if (steps.length === 0) {
@@ -165,13 +208,33 @@ export async function runCheck(
   let failed = 0;
   for (const step of steps) {
     ctx.out.log(`  ▸ ${step.label}`);
-    failed += await runStepReportingThrow(step, ctx, repo.absPath, guards, deps);
+    failed += await runStepReportingThrow(step, ctx, repo, guards, deps);
   }
   return failed > 0 ? 1 : 0;
 }
 
 type LocalRepo = NonNullable<ReturnType<GuardsCli["findLocalRepo"]>>;
 
+/** Returns undefined when no repo can be checked; the reason is already printed. */
+function findCheckedRepo(ctx: CliCommandContext, guards: GuardsCli): LocalRepo | undefined {
+  let repo: ReturnType<GuardsCli["findLocalRepo"]>;
+  try {
+    repo = guards.findLocalRepo(ctx.cwd);
+  } catch (e) {
+    ctx.out.err("");
+    ctx.out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+    ctx.out.err("");
+    return undefined;
+  }
+  if (repo === undefined) {
+    ctx.out.err("");
+    ctx.out.err(`  ✗ No Kumiko repo above ${ctx.cwd}.`);
+    ctx.out.err(`    Add a ${REPO_MANIFEST_FILE} at the repo root (kind, sourceRoots, testGlobs).`);
+    ctx.out.err("");
+  }
+  return repo;
+}
+
 /** Returns undefined when the manifest cannot be checked; the reason is already printed. */
 function printCheckPlan(ctx: CliCommandContext, repo: LocalRepo): readonly CheckStep[] | undefined {
   const plan = resolveCheckSteps(repo.manifest, {
@@ -199,12 +262,12 @@ function printCheckPlan(ctx: CliCommandContext, repo: LocalRepo): readonly Check
 async function runStepReportingThrow(
   step: { readonly id: CheckStepId; readonly label: string },
   ctx: CliCommandContext,
-  repoRoot: string,
+  repo: LocalRepo,
   guards: GuardsCli,
   deps: CheckDeps,
 ): Promise<number> {
   try {
-    return await runStep(step.id, ctx, repoRoot, guards, deps);
+    return await runStep(step.id, ctx, repo, guards, deps);
   } catch (e) {
     ctx.out.err(`  ✗ ${step.label}: ${e instanceof Error ? e.message : String(e)}`);
     return 1;
@@ -214,7 +277,7 @@ async function runStepReportingThrow(
 async function runStep(
   id: CheckStepId,
   ctx: CliCommandContext,
-  repoRoot: string,
+  repo: LocalRepo,
   guards: GuardsCli,
   deps: CheckDeps,
 ): Promise<number> {
@@ -222,8 +285,20 @@ async function runStep(
     case "boot": {
       const { runSchemaCli } = await deps.loadSchemaCli();
       // findLocalRepo walks upwards, so ctx.cwd may be a subdirectory without kumiko/schema.ts.
-      return await runSchemaCli(["validate"], repoRoot, ctx.out);
+      return await runSchemaCli(["validate"], repo.absPath, ctx.out);
     }
+    case "managed":
+      return (await deps.loadAppSteps()).runManagedCheckStep(
+        ctx.out,
+        repo.absPath,
+        repo.manifest.uiRoots ?? [],
+      );
+    case "scripts":
+      return (await deps.loadAppSteps()).runScriptsCheckStep(
+        ctx.out,
+        repo.absPath,
+        repo.manifest.uiRoots ?? [],
+      );
     case "guards":
       return guards.runGuardsCli([]);
     case "ui":
@@ -235,7 +310,7 @@ async function runStep(
 
 export const checkCommand: CliCommand = {
   id: "check",
-  description: "Boot validation + guard suites, step list derived from kumiko.json",
+  description: "Boot validation, guard suites, managed files and scripts; steps from kumiko.json",
   help: [
     `Derives the step list from ${REPO_MANIFEST_FILE} instead of a hand-written command chain:`,
     "",
@@ -244,6 +319,10 @@ export const checkCommand: CliCommand = {
     "  ui       uiRoots declared      UI guards (App-Mounting 2.0)",
     '           kind "app" must declare uiRoots; uiRoots: [] skips the UI guards on purpose',
     '  checks   kind != "tooling"     repo checks over sourceRoots + testGlobs',
+    '  managed  kind "app"            framework-owned files against the installed template',
+    '  scripts  kind "app"            package.json scripts against the script standard',
+    "",
+    "Pass step ids to run only those steps: `kumiko check managed scripts`.",
     "",
     "Flags:",
     "  --explain    print the resolved step list and the guards' own scan explanation, run nothing",

package/src/commands/index.ts

@@ -2,15 +2,21 @@ import { agentCommand } from "./agent";
 import { checkCommand } from "./check";
 import { consumerCommand } from "./consumer";
 import { handbuchCommand } from "./handbuch";
+import { opsCommand } from "./ops";
+import { portsCommand } from "./ports";
 import { projectCommand } from "./project";
+import { syncManagedCommand } from "./sync-managed";
 import type { CliCommand } from "./types";
 
 export const APP_COMMANDS: ReadonlyArray<CliCommand> = [
   checkCommand,
+  syncManagedCommand,
+  portsCommand,
   agentCommand,
   projectCommand,
   consumerCommand,
   handbuchCommand,
+  opsCommand,
 ];
 
 export function findAppCommand(id: string): CliCommand | undefined {
@@ -18,6 +24,7 @@ export function findAppCommand(id: string): CliCommand | undefined {
 }
 
 export {
+  type AppCheckSteps,
   type CheckDeps,
   type CheckStep,
   type CheckStepId,
@@ -25,4 +32,13 @@ export {
   runCheck,
 } from "./check";
 export type { CliCommand, CliCommandContext } from "./types";
-export { agentCommand, checkCommand, consumerCommand, handbuchCommand, projectCommand };
+export {
+  agentCommand,
+  checkCommand,
+  consumerCommand,
+  handbuchCommand,
+  opsCommand,
+  portsCommand,
+  projectCommand,
+  syncManagedCommand,
+};

package/src/commands/load-app-config.ts

@@ -1,17 +1,30 @@
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import type { CliCommandContext } from "./types";
 
-export type AppConfig = { readonly features: readonly FeatureDefinition[] };
+/** What the CLI reads from kumiko.config.ts. A bare `{ features }` without
+ *  defineAppConfig is still accepted for one release. */
+export type AppConfig = {
+  readonly features: readonly FeatureDefinition[];
+  readonly prodFeatures?: readonly FeatureDefinition[];
+};
 
 function isAppConfig(value: unknown): value is AppConfig {
   return (
     typeof value === "object" &&
     value !== null &&
     "features" in value &&
-    Array.isArray(value.features)
+    Array.isArray(value.features) &&
+    (!("prodFeatures" in value) ||
+      value.prodFeatures === undefined ||
+      Array.isArray(value.prodFeatures))
   );
 }
 
+/** Everything prod mounts: lint and docs checks must see the prod-only features too. */
+export function allConfiguredFeatures(config: AppConfig): readonly FeatureDefinition[] {
+  return [...config.features, ...(config.prodFeatures ?? [])];
+}
+
 // kumiko.config.ts is user-authored: a missing default export or `features`
 // array must produce a readable message, not a TypeError further down.
 export async function loadAppConfig(
@@ -24,7 +37,8 @@ export async function loadAppConfig(
   if (!isAppConfig(config)) {
     ctx.out.err("");
     ctx.out.err(`  ${configPath} must default-export an object with a "features" array:`);
-    ctx.out.err("    export default { features: [myFeature] };");
+    ctx.out.err('    import { defineAppConfig } from "@cosmicdrift/kumiko-framework/config";');
+    ctx.out.err("    export default defineAppConfig({ features: [myFeature], client, ports });");
     ctx.out.err("");
     return null;
   }

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

@@ -0,0 +1,246 @@
+import { join } from "node:path";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { loadAppConfig } from "../load-app-config";
+import type { CliCommandContext } from "../types";
+
+const BACKFILL_PII_FLAGS = [
+  "--dry-run",
+  "--rebuild",
+  "--resolve-owner-from-projection",
+  "--rekey-tenant-keyed-owner-fields",
+  "--erase-unresolvable-subjects",
+] as const;
+type BackfillPiiFlag = (typeof BACKFILL_PII_FLAGS)[number];
+
+function isBackfillPiiFlag(value: string): value is BackfillPiiFlag {
+  return BACKFILL_PII_FLAGS.some((flag) => flag === value);
+}
+
+export type BackfillPiiArgs =
+  | { readonly mode: "rebuild" }
+  | {
+      readonly mode: "backfill";
+      readonly dryRun: boolean;
+      readonly resolveOwnerFromProjection: boolean;
+      readonly rekeyTenantKeyedOwnerFields: boolean;
+      readonly eraseUnresolvableSubjects: boolean;
+    };
+
+// A typo such as `--dryrun` must fail instead of silently running the real
+// backfill. The rebuild is a separate invocation on purpose: it may only run
+// once the backfill (and any forget-subject follow-up) has completed, and an
+// erasing run must never propagate into the read side unchecked.
+export function parseBackfillPiiArgs(argv: readonly string[]): BackfillPiiArgs {
+  const flags = new Set<BackfillPiiFlag>();
+  for (const arg of argv) {
+    if (!isBackfillPiiFlag(arg)) throw new Error(`unknown flag: ${arg}`);
+    flags.add(arg);
+  }
+  if (flags.has("--rebuild")) {
+    if (flags.size > 1) {
+      throw new Error("--rebuild runs the projection rebuild only and takes no other flag");
+    }
+    return { mode: "rebuild" };
+  }
+  return {
+    mode: "backfill",
+    dryRun: flags.has("--dry-run"),
+    resolveOwnerFromProjection: flags.has("--resolve-owner-from-projection"),
+    rekeyTenantKeyedOwnerFields: flags.has("--rekey-tenant-keyed-owner-fields"),
+    eraseUnresolvableSubjects: flags.has("--erase-unresolvable-subjects"),
+  };
+}
+
+// Must match backfillEventPiiEncryption's target set; rebuilding more would
+// shadow-swap tables the backfill never touched.
+export function selectPiiProjections<
+  P extends { readonly name: string; readonly sources: readonly string[] },
+>(
+  registry: Registry,
+  projections: readonly P[],
+  piiDeps: {
+    readonly collectPiiSubjectFields: typeof import("@cosmicdrift/kumiko-framework/crypto").collectPiiSubjectFields;
+    readonly configuredEventPiiCatalog: typeof import("@cosmicdrift/kumiko-framework/crypto").configuredEventPiiCatalog;
+  },
+): P[] {
+  const piiEntityNames = new Set<string>();
+  for (const [name, entity] of registry.getAllEntities()) {
+    if (piiDeps.collectPiiSubjectFields(entity).length > 0) piiEntityNames.add(name);
+  }
+  const piiEventTypes = new Set(piiDeps.configuredEventPiiCatalog().keys());
+  const sourceCarriesPii = (source: string): boolean => {
+    if (piiEntityNames.has(source) || piiEventTypes.has(source)) return true;
+    // "<entity>.<event>" sources; a dotless source must not be truncated.
+    const dot = source.lastIndexOf(".");
+    return dot > 0 && piiEntityNames.has(source.slice(0, dot));
+  };
+  // Event-sourced aggregates without an entity only show up through the
+  // catalog event types their projection applies.
+  const appliesPiiEvent = (projectionName: string): boolean =>
+    Object.keys(registry.getAllProjections().get(projectionName)?.apply ?? {}).some((eventType) =>
+      piiEventTypes.has(eventType),
+    );
+  return projections.filter((p) => p.sources.some(sourceCarriesPii) || appliesPiiEvent(p.name));
+}
+
+const LOG_PREFIX = "[backfill-pii]";
+
+const KMS_SLOTS = ["PLATFORM_KEK", "PLATFORM_KEK_PREVIOUS", "KUMIKO_BLIND_INDEX_KEY"] as const;
+
+const BIGINT_SAFE = (_key: string, value: unknown): unknown =>
+  typeof value === "bigint" ? String(value) : value;
+
+export const BACKFILL_PII_HELP = [
+  "Re-encrypts pre-KMS plaintext PII in the event store, then (separately)",
+  "rebuilds the projections that read it. Reads kumiko.config.ts in cwd.",
+  "",
+  "Env: DATABASE_URL, SUBJECT_KEYS_DATABASE_URL, PLATFORM_KEK (or",
+  "PLATFORM_KEK_CIPHERTEXT + PLATFORM_KEK_KMS_KEY_ID + PLATFORM_KEK_KMS_TOKEN),",
+  "KUMIKO_BLIND_INDEX_KEY, optional PLATFORM_KEK_VERSION / _PREVIOUS / _PREVIOUS_VERSION.",
+  "",
+  "Flags:",
+  "  --dry-run                          scan and count only",
+  "  --resolve-owner-from-projection    owner missing in old payloads: read it from the projection",
+  "  --rekey-tenant-keyed-owner-fields  move tenant-keyed owner fields under the resolved owner",
+  "  --erase-unresolvable-subjects      erase fields whose subject stays unresolvable (irreversible)",
+  "  --rebuild                          rebuild the PII projections only; run after the backfill",
+].join("\n");
+
+type PiiDeps = Parameters<typeof selectPiiProjections>[2];
+type BackfillArgs = Extract<BackfillPiiArgs, { readonly mode: "backfill" }>;
+
+function errorMessage(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+async function rebuildPiiProjections(
+  ctx: CliCommandContext,
+  db: DbConnection,
+  registry: Registry,
+  piiDeps: PiiDeps,
+): Promise<number> {
+  const { listProjectionsWithState, rebuildProjection } = await import(
+    "@cosmicdrift/kumiko-framework/pipeline"
+  );
+  const all = await listProjectionsWithState(db, registry, { includeImplicit: true });
+  const rebuildFailures: string[] = [];
+  for (const projection of selectPiiProjections(registry, all, piiDeps)) {
+    try {
+      const result = await rebuildProjection(projection.name, { db, registry });
+      ctx.out.log(
+        `${LOG_PREFIX} rebuilt ${projection.name}: ${JSON.stringify(result, BIGINT_SAFE)}`,
+      );
+    } catch (e) {
+      // One broken projection must not block the remaining rebuilds.
+      rebuildFailures.push(`${projection.name}: ${errorMessage(e)}`);
+      ctx.out.err(`${LOG_PREFIX} REBUILD FAILED ${projection.name}`);
+    }
+  }
+  if (rebuildFailures.length === 0) return 0;
+  ctx.out.err(
+    `${LOG_PREFIX} ${rebuildFailures.length} rebuild(s) failed:\n${rebuildFailures.join("\n")}`,
+  );
+  return 1;
+}
+
+async function backfillPii(
+  ctx: CliCommandContext,
+  db: DbConnection,
+  registry: Registry,
+  args: BackfillArgs,
+): Promise<number> {
+  const { backfillEventPiiEncryption } = await import("@cosmicdrift/kumiko-framework/event-store");
+  const result = await backfillEventPiiEncryption(db, registry, {
+    dryRun: args.dryRun,
+    resolveOwnerFromProjection: args.resolveOwnerFromProjection,
+    rekeyTenantKeyedOwnerFields: args.rekeyTenantKeyedOwnerFields,
+    eraseUnresolvableSubjects: args.eraseUnresolvableSubjects,
+  });
+  ctx.out.log(
+    `${LOG_PREFIX}${args.dryRun ? " DRY-RUN" : ""} ${JSON.stringify(result, BIGINT_SAFE, 2)}`,
+  );
+  if (result.erasedUnresolvable > 0) {
+    // Erasure is irreversible; a separate line so it cannot hide in the JSON above.
+    ctx.out.err(
+      `${LOG_PREFIX} WARNING: ${result.erasedUnresolvable} unresolvable subject(s) ${args.dryRun ? "would be" : "were"} erased — compare against the dry-run count before running --rebuild.`,
+    );
+  }
+  if (result.failures.length > 0) {
+    ctx.out.err(
+      `${LOG_PREFIX} ${result.failures.length} events failed — nothing skipped silently, rerun after inspecting.`,
+    );
+    return 1;
+  }
+  if (!args.dryRun) ctx.out.log(`${LOG_PREFIX} next: kumiko ops backfill-pii --rebuild`);
+  return 0;
+}
+
+export async function runBackfillPii(ctx: CliCommandContext): Promise<number> {
+  let args: BackfillPiiArgs;
+  try {
+    args = parseBackfillPiiArgs(ctx.argv);
+  } catch (e) {
+    ctx.out.err(`${LOG_PREFIX} ${errorMessage(e)}`);
+    ctx.out.err(BACKFILL_PII_HELP);
+    return 1;
+  }
+
+  const configPath = join(ctx.cwd, "kumiko.config.ts");
+  if (!(await Bun.file(configPath).exists())) {
+    ctx.out.err(`${LOG_PREFIX} kumiko.config.ts not found at: ${configPath}`);
+    return 1;
+  }
+  const databaseUrl = process.env["DATABASE_URL"];
+  if (!databaseUrl) {
+    ctx.out.err(`${LOG_PREFIX} DATABASE_URL not set. Run against the app env.`);
+    return 1;
+  }
+
+  const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
+  await ensureTemporalPolyfill();
+
+  const config = await loadAppConfig(ctx, configPath);
+  if (config === null) return 1;
+
+  const crypto = await import("@cosmicdrift/kumiko-framework/crypto");
+  const { createRegistry } = await import("@cosmicdrift/kumiko-framework/engine");
+  const { createDbConnection } = await import("@cosmicdrift/kumiko-framework/db");
+
+  // Without the full KMS wiring the backfill would have nothing to encrypt
+  // under, so there is deliberately no plaintext fallback here.
+  let wiring: Awaited<ReturnType<typeof crypto.requireKmsWiringAsync>>;
+  try {
+    wiring = await crypto.requireKmsWiringAsync(process.env, {
+      logPrefix: LOG_PREFIX,
+      slots: KMS_SLOTS,
+      log: (line) => ctx.out.log(line),
+    });
+  } catch (e) {
+    ctx.out.err(errorMessage(e));
+    return 1;
+  }
+  crypto.configurePiiSubjectKms(wiring.kms);
+  crypto.configureBlindIndexKey(wiring.blindIndexKey);
+
+  const registry = createRegistry(config.features);
+  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);
+  } catch (e) {
+    ctx.out.err(`${LOG_PREFIX} ${errorMessage(e)}`);
+    return 1;
+  } finally {
+    await close();
+    // The KMS pool keeps the process alive otherwise.
+    await wiring.close();
+  }
+}
+
+export const backfillPiiOp = {
+  id: "backfill-pii",
+  description: "Encrypt pre-KMS plaintext PII in the event store",
+  run: runBackfillPii,
+} as const;

package/src/commands/ops/index.ts

@@ -0,0 +1,32 @@
+import type { CliCommand, CliCommandContext } from "../types";
+import { backfillPiiOp } from "./backfill-pii";
+import { waitlistMigrateOp } from "./waitlist-migrate";
+
+export type OpsSubcommand = {
+  readonly id: string;
+  readonly description: string;
+  readonly run: (ctx: CliCommandContext) => Promise<number>;
+};
+
+export const OPS_SUBCOMMANDS: ReadonlyArray<OpsSubcommand> = [backfillPiiOp, waitlistMigrateOp];
+
+function opsUsage(): string {
+  return OPS_SUBCOMMANDS.map((op) => `  ${op.id.padEnd(20)} ${op.description}`).join("\n");
+}
+
+export const opsCommand: CliCommand = {
+  id: "ops",
+  description: "One-off operations on an existing app (backfill-pii, waitlist-migrate)",
+  help: `Subcommands:\n${opsUsage()}`,
+  run: async (ctx) => {
+    const sub = OPS_SUBCOMMANDS.find((op) => op.id === ctx.argv[0]);
+    if (!sub) {
+      ctx.out.err("");
+      ctx.out.err("  Usage: kumiko ops <subcommand>");
+      ctx.out.err(opsUsage());
+      ctx.out.err("");
+      return 1;
+    }
+    return await sub.run({ ...ctx, argv: ctx.argv.slice(1) });
+  },
+};

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

@@ -0,0 +1,70 @@
+import { join } from "node:path";
+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>]";
+
+function flagValue(argv: readonly string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  return index === -1 ? undefined : argv[index + 1];
+}
+
+function fail(ctx: CliCommandContext, ...lines: readonly string[]): number {
+  ctx.out.err("");
+  for (const line of lines) ctx.out.err(`  ${line}`);
+  ctx.out.err("");
+  return 1;
+}
+
+export const waitlistMigrateOp = {
+  id: "waitlist-migrate",
+  description: "Copy a legacy app waitlist into the framework waitlist entity (idempotent)",
+  run: async (ctx: CliCommandContext): Promise<number> => {
+    const {
+      DEFAULT_IMPORT_LOCALE,
+      DEFAULT_LEGACY_SOURCE_TABLE,
+      isLegacyWaitlistSource,
+      migrateLegacyWaitlist,
+    } = await import("@cosmicdrift/kumiko-bundled-features/waitlist");
+    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 dryRun = ctx.argv.includes("--dry-run");
+    const { createDbConnection } = await import("@cosmicdrift/kumiko-framework/db");
+    const { db, close } = createDbConnection({ url: databaseUrl });
+    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,
+      });
+      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}`,
+      );
+      ctx.out.log("");
+      return report.unreadable > 0 ? 1 : 0;
+    } catch (e) {
+      return fail(ctx, `✗ ${e instanceof Error ? e.message : String(e)}`);
+    } finally {
+      await close();
+    }
+  },
+} as const;

package/src/commands/ports.ts

@@ -0,0 +1,60 @@
+import { resolve } from "node:path";
+import type { CliCommand, CliCommandContext } from "./types";
+
+// Fixed column order so the table reads the same in every run.
+const PORT_COLUMNS = ["dev", "e2e", "postgres", "redis", "meilisearch", "s3"] as const;
+
+export async function runPorts(ctx: CliCommandContext): Promise<number> {
+  if (ctx.argv.length > 1 || ctx.argv.some((arg) => arg.startsWith("-"))) {
+    ctx.out.err("  usage: kumiko ports [workspace-root]");
+    return 1;
+  }
+  const root = resolve(ctx.cwd, ctx.argv[0] ?? ".");
+  const managed = await import("@cosmicdrift/kumiko-dev-server/managed-files");
+  const apps = managed.scanWorkspaceApps(root);
+  if (apps.length === 0) {
+    ctx.out.err(`  No app with kumiko.config.ts directly below ${root}.`);
+    return 1;
+  }
+  ctx.out.log("");
+  ctx.out.log(`  ${"app".padEnd(20)}${PORT_COLUMNS.map((column) => column.padEnd(12)).join("")}`);
+  let undeclared = 0;
+  for (const { app, config: appConfig } of apps) {
+    if (appConfig.kind !== "defined") {
+      undeclared++;
+      const reason = appConfig.kind === "invalid" ? appConfig.message : "no defineAppConfig ports";
+      ctx.out.log(`  ${app.padEnd(20)}(${reason})`);
+      continue;
+    }
+    const byRole = new Map(
+      managed.listAppPorts(appConfig.ports).map(({ role, port }) => [role, port]),
+    );
+    ctx.out.log(
+      `  ${app.padEnd(20)}${PORT_COLUMNS.map((column) => String(byRole.get(column) ?? "-").padEnd(12)).join("")}`,
+    );
+  }
+  const collisions = managed.findPortCollisions(apps);
+  ctx.out.log("");
+  for (const { port, claims } of collisions) {
+    ctx.out.err(`  ✗ port ${port}: ${claims.map(({ app, role }) => `${app} ${role}`).join(", ")}`);
+  }
+  if (undeclared > 0)
+    ctx.out.log(
+      `  ${undeclared} app(s) without readable ports are not part of the collision check.`,
+    );
+  if (collisions.length === 0)
+    ctx.out.log(`  No port collisions among ${apps.length - undeclared} of ${apps.length} app(s).`);
+  ctx.out.log("");
+  return collisions.length > 0 ? 1 : 0;
+}
+
+export const portsCommand: CliCommand = {
+  id: "ports",
+  description: "List the ports of every app in a workspace and report collisions",
+  help: [
+    "Scans the direct children of [workspace-root] (default: cwd) for kumiko.config.ts,",
+    "reads ports.dev, ports.e2e and ports.infra statically (no app code runs) and",
+    "exits 1 when two apps, or two roles of one app, claim the same port.",
+  ].join("\n"),
+  run: runPorts,
+};

package/src/commands/sync-managed.ts

@@ -0,0 +1,67 @@
+import { loadRepoManifest, REPO_MANIFEST_FILE } from "../repo-manifest";
+import type { CliCommand, CliCommandContext } from "./types";
+
+const SYNC_FLAGS = ["--write", "--adopt"] as const;
+
+export async function runSyncManaged(ctx: CliCommandContext): Promise<number> {
+  const unknown = ctx.argv.filter((arg) => !SYNC_FLAGS.some((flag) => flag === arg));
+  if (unknown.length > 0) {
+    ctx.out.err(
+      `  Unknown argument(s) for "sync-managed": ${unknown.join(", ")}. Known flags: ${SYNC_FLAGS.join(", ")}`,
+    );
+    return 1;
+  }
+  const { manifest } = loadRepoManifest(ctx.cwd, {
+    warn: (message) => ctx.out.err(`  ${message}`),
+  });
+  if (manifest.kind !== "app") {
+    ctx.out.err(
+      `  sync-managed needs kind "app" in ${REPO_MANIFEST_FILE}, got "${manifest.kind}".`,
+    );
+    return 1;
+  }
+  const write = ctx.argv.includes("--write");
+  const managed = await import("@cosmicdrift/kumiko-dev-server/managed-files");
+  const facts = managed.resolveManagedAppFacts({
+    appRoot: ctx.cwd,
+    uiRoots: manifest.uiRoots ?? [],
+  });
+  const actions = managed.syncManagedFiles(facts, { write, adopt: ctx.argv.includes("--adopt") });
+  ctx.out.log("");
+  for (const entry of actions) {
+    if (entry.action === "unchanged") continue;
+    const verb = write ? entry.action : `would ${entry.action}`;
+    ctx.out.log(
+      entry.action === "skip"
+        ? `  skip    ${entry.path}: ${entry.skippedBecause}`
+        : `  ${verb.padEnd(7)} ${entry.path}`,
+    );
+  }
+  const pending = actions.filter(
+    (entry) => entry.action !== "unchanged" && entry.action !== "skip",
+  );
+  ctx.out.log("");
+  if (!write && pending.length > 0)
+    ctx.out.log("  Dry run. Write the changes with: kumiko sync-managed --write");
+  if (pending.length === 0) ctx.out.log("  All writable managed files are up to date.");
+  ctx.out.log("");
+  return 0;
+}
+
+export const syncManagedCommand: CliCommand = {
+  id: "sync-managed",
+  description: "Write the framework-owned files of an app from the installed templates",
+  help: [
+    "Renders the managed files (deploy/, .husky/pre-push, .github/workflows, bunfigs,",
+    "kumiko/schema.ts) from the installed @cosmicdrift/kumiko-dev-server and writes",
+    "the ones that differ. Without --write it only lists what would change.",
+    "",
+    "Only files that carry the kumiko-managed marker are overwritten. A file with",
+    "`kumiko-managed: local <reason>` on the line after the marker is left alone.",
+    "",
+    "Flags:",
+    "  --write    write the changes",
+    "  --adopt    also take over existing files without a marker (first adoption)",
+  ].join("\n"),
+  run: runSyncManaged,
+};