@cosmicdrift/kumiko-cli 0.341.0 → 0.342.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-cli",
-  "version": "0.341.0",
+  "version": "0.342.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.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -35,12 +35,12 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.341.0",
-    "@cosmicdrift/kumiko-dev-server": "0.341.0",
-    "@cosmicdrift/kumiko-framework": "0.341.0",
-    "@cosmicdrift/kumiko-guards": "0.341.0",
-    "@cosmicdrift/kumiko-repo-manifest": "0.341.0",
-    "@cosmicdrift/kumiko-testing": "0.341.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.342.0",
+    "@cosmicdrift/kumiko-dev-server": "0.342.0",
+    "@cosmicdrift/kumiko-framework": "0.342.0",
+    "@cosmicdrift/kumiko-guards": "0.342.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.342.0",
+    "@cosmicdrift/kumiko-testing": "0.342.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.342.0",
+    "type": "breaking",
+    "title": "kumiko check requires uiRoots for kind \"app\"",
+    "detail": "`kumiko check` fails a kind \"app\" without uiRoots\nA repo with `kind: \"app\"` and no `uiRoots` used to skip the UI guards silently. `kumiko check` (also with `--explain`) now prints an error and exits 1 before any step runs. Declare `uiRoots`, or set `uiRoots: []` for an app without UI; the step list then shows that the UI guards are skipped on purpose. A repo that relies on the derived manifest also gets the hint to add a `kumiko.json`. Other kinds are unchanged. `kumiko new app` now writes a `kumiko.json` with `uiRoots: [\"src/features/*/web\"]`.",
+    "migration": "Add `uiRoots` to the `kumiko.json` of every `kind: \"app\"` repo, for example `[\"src/app\", \"src/features/*/web\"]`, or `[]` for an app without UI. A repo without a `kumiko.json` needs one first, since the derived manifest cannot declare uiRoots.\nWorkspace state at release: kumiko-platform, offlot-app, phronexsis and show-pony declare `kind: \"app\"` without `uiRoots`."
+  },
   {
     "version": "0.337.0",
     "type": "fix",

package/src/commands/check.ts

@@ -20,10 +20,31 @@ export type RepoFacts = {
   /** A `kind: "app"` repo without one is an app by role only (an Astro site, a
    *  docs repo) — there is no composed feature set for validateBoot to check. */
   readonly hasAppSchema: boolean;
+  readonly manifestSource: "file" | "derived";
 };
 
-export function resolveCheckSteps(manifest: RepoManifest, facts: RepoFacts): readonly CheckStep[] {
-  if (manifest.kind === "tooling") return [];
+export type CheckPlan =
+  | {
+      readonly kind: "steps";
+      readonly steps: readonly CheckStep[];
+      readonly waivers: readonly string[];
+    }
+  | { readonly kind: "error"; readonly message: string };
+
+export function resolveCheckSteps(manifest: RepoManifest, facts: RepoFacts): CheckPlan {
+  if (manifest.kind === "tooling") return { kind: "steps", steps: [], waivers: [] };
+  if (manifest.kind === "app" && manifest.uiRoots === undefined) {
+    // A silent skip would let an app with UI pass without the UI guards ever running.
+    const derivedHint = facts.manifestSource === "derived" ? ` Add a ${REPO_MANIFEST_FILE}.` : "";
+    return {
+      kind: "error",
+      message:
+        `kind "app" must declare uiRoots in ${REPO_MANIFEST_FILE}: list the UI directories ` +
+        '(e.g. ["src/app", "src/features/*/web"]) or set uiRoots: [] for an app without UI.' +
+        derivedHint,
+    };
+  }
+  const waivers: string[] = [];
   const steps: CheckStep[] = [];
   if (manifest.kind === "app" && facts.hasAppSchema) {
     steps.push({
@@ -44,12 +65,15 @@ export function resolveCheckSteps(manifest: RepoManifest, facts: RepoFacts): rea
       why: `uiRoots ${manifest.uiRoots.join(", ")}`,
     });
   }
+  if (manifest.kind === "app" && manifest.uiRoots?.length === 0) {
+    waivers.push("UI guards skipped on purpose: uiRoots is [] (app without UI)");
+  }
   steps.push({
     id: "checks",
     label: "Repo checks",
     why: `kind "${manifest.kind}" — testGlobs ${manifest.testGlobs.join(", ")}`,
   });
-  return steps;
+  return { kind: "steps", steps, waivers };
 }
 
 export type GuardsCli = Pick<
@@ -124,17 +148,8 @@ export async function runCheck(
     return 1;
   }
 
-  const steps = resolveCheckSteps(repo.manifest, {
-    hasAppSchema: existsSync(join(repo.absPath, APP_SCHEMA_FILE)),
-  });
-  ctx.out.log("");
-  ctx.out.log(
-    `  ${repo.name} — kind "${repo.manifest.kind}", ${steps.length} step(s) from ${REPO_MANIFEST_FILE}`,
-  );
-  for (const step of steps) {
-    ctx.out.log(`    ${step.id.padEnd(8)}${step.label} — ${step.why}`);
-  }
-  ctx.out.log("");
+  const steps = printCheckPlan(ctx, repo);
+  if (steps === undefined) return 1;
 
   if (steps.length === 0) {
     ctx.out.log(`  Nothing to check: kind "${repo.manifest.kind}" declares no product code.`);
@@ -155,6 +170,32 @@ export async function runCheck(
   return failed > 0 ? 1 : 0;
 }
 
+type LocalRepo = NonNullable<ReturnType<GuardsCli["findLocalRepo"]>>;
+
+/** 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, {
+    hasAppSchema: existsSync(join(repo.absPath, APP_SCHEMA_FILE)),
+    manifestSource: repo.manifestSource,
+  });
+  if (plan.kind === "error") {
+    ctx.out.err("");
+    ctx.out.err(`  ✗ ${repo.name}: ${plan.message}`);
+    ctx.out.err("");
+    return undefined;
+  }
+  ctx.out.log("");
+  ctx.out.log(
+    `  ${repo.name} — kind "${repo.manifest.kind}", ${plan.steps.length} step(s) from ${REPO_MANIFEST_FILE}`,
+  );
+  for (const step of plan.steps) {
+    ctx.out.log(`    ${step.id.padEnd(8)}${step.label} — ${step.why}`);
+  }
+  for (const waiver of plan.waivers) ctx.out.log(`    ${"ui".padEnd(8)}${waiver}`);
+  ctx.out.log("");
+  return plan.steps;
+}
+
 async function runStepReportingThrow(
   step: { readonly id: CheckStepId; readonly label: string },
   ctx: CliCommandContext,
@@ -201,6 +242,7 @@ export const checkCommand: CliCommand = {
     `  boot     kind "app" + ${APP_SCHEMA_FILE}   validateBoot over its composed FEATURES`,
     '  guards   kind != "tooling"     AST guards over sourceRoots',
     "  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',
     "",
     "Flags:",