@cosmicdrift/kumiko-cli 0.413.1 → 0.415.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-cli",
-  "version": "0.413.1",
+  "version": "0.415.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,19 +36,19 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dev-server": "0.413.1",
-    "@cosmicdrift/kumiko-feature-ast": "0.413.1",
-    "@cosmicdrift/kumiko-guards": "0.413.1",
-    "@cosmicdrift/kumiko-server-runtime": "0.413.1",
-    "@cosmicdrift/kumiko-testing": "0.413.1",
+    "@cosmicdrift/kumiko-dev-server": "0.415.0",
+    "@cosmicdrift/kumiko-feature-ast": "0.415.0",
+    "@cosmicdrift/kumiko-guards": "0.415.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.415.0",
+    "@cosmicdrift/kumiko-testing": "0.415.0",
     "marked": "^18.1.2",
     "zod": "^4.6.7"
   },
   "peerDependencies": {
     "sharp": "^0.35.5",
-    "@cosmicdrift/kumiko-bundled-features": "0.413.1",
-    "@cosmicdrift/kumiko-framework": "0.413.1",
-    "@cosmicdrift/kumiko-renderer": "0.413.1"
+    "@cosmicdrift/kumiko-bundled-features": "0.415.0",
+    "@cosmicdrift/kumiko-framework": "0.415.0",
+    "@cosmicdrift/kumiko-renderer": "0.415.0"
   },
   "peerDependenciesMeta": {
     "sharp": {
@@ -65,9 +65,9 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.413.1",
-    "@cosmicdrift/kumiko-framework": "0.413.1",
-    "@cosmicdrift/kumiko-renderer": "0.413.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.415.0",
+    "@cosmicdrift/kumiko-framework": "0.415.0",
+    "@cosmicdrift/kumiko-renderer": "0.415.0",
     "sharp": "^0.35.5"
   },
   "publishConfig": {

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.415.0",
+    "type": "breaking",
+    "title": "kumiko check fails when biome.json does not extend the Kumiko Biome preset",
+    "detail": "The lint step now reads `biome.json` or `biome.jsonc` (comments allowed) before it starts Biome and follows relative `extends` entries. It passes only if the chain reaches `@cosmicdrift/kumiko-framework/biome-rules`, `@cosmicdrift/kumiko-framework/biome` or a relative path to the framework's `presets/biome-rules.json` or `presets/biome-app.json`. Without the preset the SSRF, path-traversal, event-store write and admin-API plugins are missing and the step used to stay green; now it exits 1 and does not start Biome.",
+    "migration": "Add `\"extends\": [\"@cosmicdrift/kumiko-framework/biome\"]` to the repo's `biome.json` (`@cosmicdrift/kumiko-framework/biome-rules` for repos that keep their own file layout)."
+  },
   {
     "version": "0.413.0",
     "type": "fix",

package/src/commands/api-docs.ts

@@ -17,7 +17,6 @@ import type { CliCommand, CliCommandContext } from "./types";
 const USAGE = "Usage: kumiko api-docs [--out <dir>] [--locales en,de] [--check]";
 const DEFAULT_OUT_DIR = "api-docs";
 const DEFAULT_EXAMPLES_DIR = "api-examples";
-const INDEX_FILE = "index.json";
 const WEBHOOK_EXAMPLES_SUBDIR = "webhooks";
 const WEBHOOK_EXAMPLES_PREFIX = `${WEBHOOK_EXAMPLES_SUBDIR}/`;
 
@@ -91,17 +90,17 @@ function appSource(cwd: string): { name: string; version: string } {
 }
 
 /** Files the previous run listed in its index.json, so stale pages can go without touching foreign files. */
-function previouslyGenerated(outDir: string): string[] {
-  const indexPath = join(outDir, INDEX_FILE);
+function previouslyGenerated(outDir: string, indexFile: string): string[] {
+  const indexPath = join(outDir, indexFile);
   if (!existsSync(indexPath)) return [];
   try {
     const parsed = IndexFileSchema.safeParse(readJson(indexPath));
     return parsed.success
-      ? [INDEX_FILE, ...parsed.data.pages.map((page) => page.path)]
-      : [INDEX_FILE];
+      ? [indexFile, ...parsed.data.pages.map((page) => page.path)]
+      : [indexFile];
   } catch {
     // skip: an unreadable index.json is rewritten below, so there is nothing stale to learn from it
-    return [INDEX_FILE];
+    return [indexFile];
   }
 }
 
@@ -135,8 +134,8 @@ function readExamples<T>(
   return examples;
 }
 
-function writeOutput(outDir: string, files: ReadonlyMap<string, string>): void {
-  for (const stale of previouslyGenerated(outDir)) {
+function writeOutput(outDir: string, files: ReadonlyMap<string, string>, indexFile: string): void {
+  for (const stale of previouslyGenerated(outDir, indexFile)) {
     const target = resolve(outDir, stale);
     if (
       !files.has(stale) &&
@@ -156,6 +155,7 @@ function writeOutput(outDir: string, files: ReadonlyMap<string, string>): void {
 
 type Values = { out?: string; locales?: string; check?: boolean };
 type AgentTools = typeof import("@cosmicdrift/kumiko-bundled-features/agent-tools");
+type ResolvedApiDocsConfig = ReturnType<AgentTools["resolveApiDocsConfig"]>;
 
 function errorBlock(ctx: CliCommandContext, message: string): number {
   ctx.out.err("");
@@ -198,15 +198,14 @@ function report(
     for (const line of problemLines) ctx.out.err(`  ${line}`);
     return 1;
   }
-  writeOutput(target.outDir, files);
+  writeOutput(target.outDir, files, tools.INDEX_FILE);
   for (const line of problemLines) ctx.out.log(`  warning ${line}`);
   ctx.out.log(`  ✓ ${files.size} files written to ${target.outDir}`);
   return 0;
 }
 
 type Target = {
-  locales: readonly string[];
-  baseUrl: string;
+  resolved: ResolvedApiDocsConfig;
   outDir: string;
   onDisk: Map<string, string>;
   check: boolean;
@@ -219,9 +218,11 @@ function resolveTarget(
   apiDocs: AppApiDocsConfig,
   values: Values,
 ): Target | number {
-  const locales = values.locales?.split(",").map((locale) => locale.trim()) ??
-    apiDocs.locales ?? ["en"];
-  const badLocales = localeProblem(locales, tools);
+  const resolved = tools.resolveApiDocsConfig(apiDocs, {
+    appName: appSource(ctx.cwd).name,
+    locales: values.locales?.split(",").map((locale) => locale.trim()),
+  });
+  const badLocales = localeProblem(resolved.locales, tools);
   if (badLocales !== undefined) return usageError(ctx, badLocales);
   if (apiDocs.baseUrl === undefined) {
     return errorBlock(
@@ -238,13 +239,13 @@ function resolveTarget(
   }
   const onDisk = readOutDir(outDir);
   const check = values.check === true;
-  if (!check && onDisk.size > 0 && !onDisk.has(INDEX_FILE)) {
+  if (!check && onDisk.size > 0 && !onDisk.has(tools.INDEX_FILE)) {
     return errorBlock(
       ctx,
-      `${outDir} is not empty and holds no ${INDEX_FILE}, so it was not generated by this command. Pick another --out.`,
+      `${outDir} is not empty and holds no ${tools.INDEX_FILE}, so it was not generated by this command. Pick another --out.`,
     );
   }
-  return { locales, baseUrl: apiDocs.baseUrl, outDir, onDisk, check };
+  return { resolved, outDir, onDisk, check };
 }
 
 async function generate(
@@ -259,7 +260,7 @@ async function generate(
   const apiDocs = config.apiDocs ?? {};
   const target = resolveTarget(ctx, tools, apiDocs, values);
   if (typeof target === "number") return target;
-  const { locales, baseUrl, outDir, onDisk, check } = target;
+  const { resolved, outDir, onDisk, check } = target;
 
   const examplesDir = resolve(ctx.cwd, apiDocs.examplesDir ?? DEFAULT_EXAMPLES_DIR);
   const examples = readExamples(
@@ -282,12 +283,7 @@ async function generate(
       registry: createRegistry(
         composeFeatures(allAppFeatures(config), { includeBundled: config.includeBundled === true }),
       ),
-      config: {
-        ...apiDocs,
-        locales,
-        baseUrl,
-        appName: apiDocs.appName ?? appSource(ctx.cwd).name,
-      },
+      config: resolved,
       source: { framework: frameworkVersion(), app: appSource(ctx.cwd) },
       examples,
       webhookExamples,

package/src/commands/check-lint.ts

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { Output } from "../output";
+
+const PRESET_PACKAGE_EXTENDS: ReadonlySet<string> = new Set([
+  "@cosmicdrift/kumiko-framework/biome-rules",
+  "@cosmicdrift/kumiko-framework/biome",
+]);
+const PRESET_FILE_SUFFIXES = ["/presets/biome-rules.json", "/presets/biome-app.json"];
+const BIOME_CONFIG_NAMES = ["biome.json", "biome.jsonc"];
+const PRESET_FIX = '"extends": ["@cosmicdrift/kumiko-framework/biome"]';
+
+function readExtendsList(configPath: string): string[] {
+  let parsed: unknown;
+  try {
+    parsed = Bun.JSONC.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    return [];
+  }
+  const list =
+    typeof parsed === "object" && parsed !== null && "extends" in parsed
+      ? parsed.extends
+      : undefined;
+  const entries = Array.isArray(list) ? list : [list];
+  return entries.filter((entry): entry is string => typeof entry === "string");
+}
+
+function extendsFrameworkPreset(configPath: string, visited: Set<string>): boolean {
+  if (visited.has(configPath)) return false;
+  visited.add(configPath);
+  return readExtendsList(configPath).some((entry) => {
+    if (PRESET_PACKAGE_EXTENDS.has(entry)) return true;
+    if (!entry.startsWith(".")) return false;
+    const target = resolve(dirname(configPath), entry);
+    if (PRESET_FILE_SUFFIXES.some((suffix) => target.endsWith(suffix))) return true;
+    return existsSync(target) && extendsFrameworkPreset(target, visited);
+  });
+}
+
+function repoExtendsFrameworkPreset(repoRoot: string): boolean {
+  const configPath = BIOME_CONFIG_NAMES.map((name) => join(repoRoot, name)).find((candidate) =>
+    existsSync(candidate),
+  );
+  return configPath !== undefined && extendsFrameworkPreset(configPath, new Set());
+}
+
+function resolveBiomeBin(repoRoot: string): string | undefined {
+  try {
+    return join(dirname(Bun.resolveSync("@biomejs/biome/package.json", repoRoot)), "bin", "biome");
+  } catch {
+    return undefined;
+  }
+}
+
+/** Runs the repo's own Biome so builtin rules and the biome-rules plugins count towards `kumiko check`. */
+export async function runLintCheckStep(out: Output, repoRoot: string): Promise<number> {
+  const biomeBin = resolveBiomeBin(repoRoot);
+  if (biomeBin === undefined) {
+    out.err(
+      "  ✗ @biomejs/biome is not installed in this repo — kumiko check needs it for the lint step.",
+    );
+    out.err("    Fix: `bun add -d @biomejs/biome`");
+    return 1;
+  }
+  // Without the preset the SSRF, path-traversal, event-store-write and admin-API plugins are missing and the lint step stays green.
+  if (!repoExtendsFrameworkPreset(repoRoot)) {
+    out.err(
+      "  ✗ biome.json does not extend the Kumiko Biome preset — the security plugins (SSRF, path traversal, event-store writes, admin API) would not run.",
+    );
+    out.err(`    Fix: add ${PRESET_FIX} to biome.json`);
+    return 1;
+  }
+  const proc = Bun.spawn(["bun", biomeBin, "lint", "."], {
+    cwd: repoRoot,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  for (const line of `${stdout}${stderr}`.split("\n")) {
+    if (line.trim().length > 0) out.log(`    ${line}`);
+  }
+  return code === 0 ? 0 : 1;
+}

package/src/commands/check.ts

@@ -1,17 +1,30 @@
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { REPO_MANIFEST_FILE, type RepoManifest } from "@cosmicdrift/kumiko-guards/repo-manifest";
+import type { Output } from "../output";
 import type { CliCommand, CliCommandContext } from "./types";
 
 const APP_SCHEMA_FILE = "kumiko/schema.ts";
+const APP_CONFIG_FILE = "kumiko.config.ts";
+const BIOME_CONFIG_FILES = ["biome.json", "biome.jsonc"] as const;
 
-export type CheckStepId = "boot" | "guards" | "ui" | "checks" | "managed" | "scripts";
+export type CheckStepId =
+  | "boot"
+  | "guards"
+  | "ui"
+  | "checks"
+  | "lint"
+  | "agent"
+  | "managed"
+  | "scripts";
 
 const CHECK_STEP_IDS: readonly CheckStepId[] = [
   "boot",
   "guards",
   "ui",
   "checks",
+  "lint",
+  "agent",
   "managed",
   "scripts",
 ];
@@ -29,6 +42,10 @@ 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;
+  /** `kumiko agent lint` loads kumiko.config.ts and fails without it. */
+  readonly hasAppConfig: boolean;
+  /** The repo lints with Biome (builtin rules plus the biome-rules plugins); without a config there is nothing to run. */
+  readonly hasBiomeConfig: boolean;
   readonly manifestSource: "file" | "derived";
 };
 
@@ -82,23 +99,42 @@ 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',
-      },
-    );
-  }
+  steps.push(...resolveLintAndAppSteps(manifest, facts));
   return { kind: "steps", steps, waivers };
 }
 
+function resolveLintAndAppSteps(manifest: RepoManifest, facts: RepoFacts): readonly CheckStep[] {
+  const steps: CheckStep[] = [];
+  if (facts.hasBiomeConfig) {
+    steps.push({
+      id: "lint",
+      label: "Biome lint",
+      why: `${BIOME_CONFIG_FILES.join(" or ")} present — biome lint over the repo (builtin rules and the biome-rules plugins that replaced single-file guards)`,
+    });
+  }
+  if (manifest.kind !== "app") return steps;
+  if (facts.hasAppConfig) {
+    steps.push({
+      id: "agent",
+      label: "Agent docs",
+      why: `kind "app" with ${APP_CONFIG_FILE} — kumiko agent lint over its composed features`,
+    });
+  }
+  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 steps;
+}
+
 export type GuardsCli = Pick<
   typeof import("@cosmicdrift/kumiko-guards"),
   "cliFlagsError" | "findLocalRepo" | "runGuardsCli" | "runRepoChecksCli" | "runUiGuardsCli"
@@ -112,6 +148,8 @@ export type SchemaCli = Pick<
 export type AppCheckSteps = {
   readonly runManagedCheckStep: typeof import("./check-managed").runManagedCheckStep;
   readonly runScriptsCheckStep: typeof import("./check-scripts").runScriptsCheckStep;
+  readonly runLintCheckStep: typeof import("./check-lint").runLintCheckStep;
+  readonly runAgentLint: (out: Output, repoRoot: string) => Promise<number>;
 };
 
 export type CheckDeps = {
@@ -127,6 +165,9 @@ const DEFAULT_DEPS: CheckDeps = {
   loadAppSteps: async () => ({
     runManagedCheckStep: (await import("./check-managed")).runManagedCheckStep,
     runScriptsCheckStep: (await import("./check-scripts")).runScriptsCheckStep,
+    runLintCheckStep: (await import("./check-lint")).runLintCheckStep,
+    runAgentLint: async (out, repoRoot) =>
+      (await import("./agent")).agentCommand.run({ argv: ["lint"], cwd: repoRoot, out }),
   }),
 };
 
@@ -239,6 +280,8 @@ function findCheckedRepo(ctx: CliCommandContext, guards: GuardsCli): LocalRepo |
 function printCheckPlan(ctx: CliCommandContext, repo: LocalRepo): readonly CheckStep[] | undefined {
   const plan = resolveCheckSteps(repo.manifest, {
     hasAppSchema: existsSync(join(repo.absPath, APP_SCHEMA_FILE)),
+    hasAppConfig: existsSync(join(repo.absPath, APP_CONFIG_FILE)),
+    hasBiomeConfig: BIOME_CONFIG_FILES.some((file) => existsSync(join(repo.absPath, file))),
     manifestSource: repo.manifestSource,
   });
   if (plan.kind === "error") {
@@ -287,6 +330,10 @@ async function runStep(
       // findLocalRepo walks upwards, so ctx.cwd may be a subdirectory without kumiko/schema.ts.
       return await runSchemaCli(["validate"], repo.absPath, ctx.out);
     }
+    case "lint":
+      return (await deps.loadAppSteps()).runLintCheckStep(ctx.out, repo.absPath);
+    case "agent":
+      return (await deps.loadAppSteps()).runAgentLint(ctx.out, repo.absPath);
     case "managed":
       return (await deps.loadAppSteps()).runManagedCheckStep(
         ctx.out,
@@ -319,6 +366,8 @@ 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',
+    "  lint     biome.json present     biome lint (builtin rules and the biome-rules GritQL plugins)",
+    `  agent    kind "app" + ${APP_CONFIG_FILE}  kumiko agent lint (AI-agent doc gaps in the composed features)`,
     '  managed  kind "app"            framework-owned files against the installed template',
     '  scripts  kind "app"            package.json scripts against the script standard',
     "",

package/src/index.ts

@@ -24,7 +24,6 @@ export type RunCliOptions = {
 
 const DEFAULT_OUT: Output = {
   log: (line) => console.log(line),
-  // @wrapper-known semantic-alias
   err: (line) => console.error(line),
 };