@cosmicdrift/kumiko-cli 0.353.0 → 0.354.1

package/bin/kumiko-upgrade.ts

@@ -3,11 +3,19 @@
 // depend on kumiko-cli + kumiko-guards never get a transitive dependency's bin
 // linked, and guard-upgrade-state needs it in node_modules/.bin.
 
-import { runUpgradeCli } from "@cosmicdrift/kumiko-framework/upgrade-cli";
+import { missingPeerMessage } from "../src/missing-peer";
 
 // biome-ignore lint/suspicious/noConsole: CLI output is the feature.
 const out = { log: (l: string) => console.log(l), err: (l: string) => console.error(l) };
 const appCwd = process.env["INIT_CWD"] ?? process.cwd();
-const code = await runUpgradeCli(process.argv.slice(2), appCwd, out);
-// Let the event loop drain stdout (piped by guard-upgrade-state) before exit.
-process.exitCode = code;
+
+try {
+  const { runUpgradeCli } = await import("@cosmicdrift/kumiko-framework/upgrade-cli");
+  // Let the event loop drain stdout (piped by guard-upgrade-state) before exit.
+  process.exitCode = await runUpgradeCli(process.argv.slice(2), appCwd, out);
+} catch (error) {
+  const message = missingPeerMessage(error);
+  if (message === undefined) throw error;
+  out.err(message);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-cli",
-  "version": "0.353.0",
+  "version": "0.354.1",
   "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>",
@@ -36,14 +36,28 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.353.0",
-    "@cosmicdrift/kumiko-dev-server": "0.353.0",
-    "@cosmicdrift/kumiko-framework": "0.353.0",
-    "@cosmicdrift/kumiko-guards": "0.353.0",
-    "@cosmicdrift/kumiko-repo-manifest": "0.353.0",
-    "@cosmicdrift/kumiko-testing": "0.353.0",
+    "@cosmicdrift/kumiko-dev-server": "0.354.1",
+    "@cosmicdrift/kumiko-guards": "0.354.1",
+    "@cosmicdrift/kumiko-repo-manifest": "0.354.1",
+    "@cosmicdrift/kumiko-testing": "0.354.1",
     "zod": "^4.4.3"
   },
+  "peerDependencies": {
+    "@cosmicdrift/kumiko-bundled-features": ">=0.353.0 <1.0.0",
+    "@cosmicdrift/kumiko-framework": ">=0.353.0 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@cosmicdrift/kumiko-bundled-features": {
+      "optional": true
+    },
+    "@cosmicdrift/kumiko-framework": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "0.354.1",
+    "@cosmicdrift/kumiko-framework": "0.354.1"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "improvement",
+    "title": "kumiko-cli declares framework and bundled-features as optional peer dependencies",
+    "detail": "kumiko-cli declares @cosmicdrift/kumiko-framework and @cosmicdrift/kumiko-bundled-features as optional peer dependencies instead of hard dependencies, so `kumiko new app` no longer pulls them in; commands that need them report a missing install instead of a resolver stacktrace"
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "kumiko-cli optional peers no longer force a 1.0.0 release",
+    "detail": "kumiko-cli declares its optional peers framework and bundled-features with an explicit 0.x range, and changesets only bumps peer dependents when that range is left, so a minor framework release no longer pushes the fixed package group to 1.0.0"
+  },
   {
     "version": "0.351.0",
     "type": "fix",

package/src/commands/agent.ts

@@ -32,26 +32,39 @@ export const agentCommand: CliCommand = {
 
     const config = await loadAppConfig(ctx, configPath);
     if (config === null) return 1;
-    const { findAgentDocGaps, formatAgentDocGap } = await import(
+    const { findAgentDocGaps, findHandlerTranslationGaps, formatAgentDocGap } = await import(
       "@cosmicdrift/kumiko-bundled-features/agent-tools"
     );
 
     const gaps = findAgentDocGaps(config.features);
+    const translationGaps = findHandlerTranslationGaps(config.features);
 
-    if (gaps.length === 0) {
+    if (gaps.length === 0 && translationGaps.length === 0) {
       ctx.out.log("");
       ctx.out.log("  ✓ No AI-agent doc gaps found.");
       ctx.out.log("");
       return 0;
     }
 
-    ctx.out.log("");
-    ctx.out.log(`  ${gaps.length} AI-agent doc gap${gaps.length === 1 ? "" : "s"} found:`);
-    ctx.out.log("");
-    for (const gap of gaps) {
-      ctx.out.log(`    ${formatAgentDocGap(gap)}`);
+    if (gaps.length > 0) {
+      ctx.out.log("");
+      ctx.out.log(`  ${gaps.length} AI-agent doc gap${gaps.length === 1 ? "" : "s"} found:`);
+      ctx.out.log("");
+      for (const gap of gaps) {
+        ctx.out.log(`    ${formatAgentDocGap(gap)}`);
+      }
+    }
+    if (translationGaps.length > 0) {
+      ctx.out.log("");
+      ctx.out.log(
+        `  ${translationGaps.length} warning${translationGaps.length === 1 ? "" : "s"} (handler translations, do not affect the exit code):`,
+      );
+      ctx.out.log("");
+      for (const gap of translationGaps) {
+        ctx.out.log(`    ${formatAgentDocGap(gap)}`);
+      }
     }
     ctx.out.log("");
-    return 1;
+    return gaps.length === 0 ? 0 : 1;
   },
 };

package/src/index.ts

@@ -17,6 +17,7 @@ import {
 import { renderTestSetup } from "@cosmicdrift/kumiko-testing/scaffold";
 import type { CliCommand } from "./commands";
 import { APP_COMMANDS, findAppCommand } from "./commands";
+import { missingPeerMessage } from "./missing-peer";
 import type { Output } from "./output";
 
 export type { Output } from "./output";
@@ -60,13 +61,27 @@ export async function runCli(options: RunCliOptions): Promise<number> {
       printCommandHelp(appCommand, out);
       return 0;
     }
-    return await appCommand.run({ argv: rest, cwd, out });
+    return await runAppCommand(appCommand, { argv: rest, cwd, out });
   }
 
   out.err(`kumiko: unknown command "${first}". Run \`kumiko --help\` for usage.`);
   return 1;
 }
 
+async function runAppCommand(
+  command: CliCommand,
+  context: Parameters<CliCommand["run"]>[0],
+): Promise<number> {
+  try {
+    return await command.run(context);
+  } catch (error) {
+    const message = missingPeerMessage(error);
+    if (message === undefined) throw error;
+    context.out.err(`kumiko ${command.id}: ${message}`);
+    return 1;
+  }
+}
+
 async function runNew(args: readonly string[], out: Output, cwd: string): Promise<number> {
   const [subject, name] = args;
   if (subject !== "app") {

package/src/missing-peer.ts

@@ -0,0 +1,16 @@
+const APP_PEER_PACKAGES = [
+  "@cosmicdrift/kumiko-framework",
+  "@cosmicdrift/kumiko-bundled-features",
+] as const;
+
+// The runtime packages are optional peers (so `new app` runs without them); a
+// command that needs one must report the missing install, not a resolver stacktrace.
+export function missingPeerMessage(error: unknown): string | undefined {
+  if (!(error instanceof Error)) return undefined;
+  for (const peer of APP_PEER_PACKAGES) {
+    if (error.message.includes(`'${peer}`) && /cannot find (package|module)/i.test(error.message)) {
+      return `${peer} is not installed. Install ${peer} in your app (bun add ${peer}).`;
+    }
+  }
+  return undefined;
+}