@cosmicdrift/kumiko-cli 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @cosmicdrift/kumiko-cli
+
+## 0.2.0
+
+### Minor Changes
+
+- b8e1d48: New package `@cosmicdrift/kumiko-cli` — provides `kumiko` bin for
+  `bunx @cosmicdrift/kumiko-cli new app <name>` and `add feature <name>`.
+  Fixes the walkthrough's broken `bunx @cosmicdrift/kumiko-framework`
+  promise (bin-name ≠ pkg-name). Delegates to scaffoldApp +
+  scaffoldAppFeature from `@cosmicdrift/kumiko-dev-server`.
+
+### Patch Changes
+
+- Updated dependencies [b8e1d48]
+- Updated dependencies [ce23d48]
+  - @cosmicdrift/kumiko-dev-server@0.14.0

package/bin/cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runCli } from "../src/index";
+
+process.exit(await runCli({ argv: process.argv.slice(2) }));

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@cosmicdrift/kumiko-cli",
+  "version": "0.2.0",
+  "description": "Standalone CLI for scaffolding Kumiko apps. `bunx @cosmicdrift/kumiko-cli new app <name>` produces a runnable workspace; `add feature <name>` mounts a feature automatically.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.so",
+  "type": "module",
+  "kumiko": {
+    "runtime": "dev"
+  },
+  "bin": {
+    "kumiko": "./bin/cli.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-dev-server": "0.14.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/__tests__/cli.integration.ts

@@ -0,0 +1,121 @@
+// Drives runCli in-process — captures stdout/stderr via the injected
+// Output, exercises the 3-command-walkthrough end-to-end (new app +
+// add feature) into a tmp directory.
+
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { runCli } from "../index";
+
+type Captured = { logs: string[]; errs: string[] };
+
+function capture(): {
+  out: { log: (s: string) => void; err: (s: string) => void };
+  captured: Captured;
+} {
+  const captured: Captured = { logs: [], errs: [] };
+  return {
+    captured,
+    out: {
+      log: (s) => captured.logs.push(s),
+      err: (s) => captured.errs.push(s),
+    },
+  };
+}
+
+describe("kumiko cli", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "kumiko-cli-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("--help prints commands + docs link", async () => {
+    const { out, captured } = capture();
+    const code = await runCli({ argv: ["--help"], out });
+    expect(code).toBe(0);
+    const joined = captured.logs.join("\n");
+    expect(joined).toContain("kumiko new app");
+    expect(joined).toContain("kumiko add feature");
+    expect(joined).toContain("docs.kumiko.so");
+  });
+
+  test("no args prints help", async () => {
+    const { out, captured } = capture();
+    const code = await runCli({ argv: [], out });
+    expect(code).toBe(0);
+    expect(captured.logs.join("\n")).toContain("kumiko new app");
+  });
+
+  test("--version prints semver", async () => {
+    const { out, captured } = capture();
+    const code = await runCli({ argv: ["--version"], out });
+    expect(code).toBe(0);
+    expect(captured.logs[0]).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  test("unknown command exits 1", async () => {
+    const { out, captured } = capture();
+    const code = await runCli({ argv: ["bogus"], out });
+    expect(code).toBe(1);
+    expect(captured.errs.join("\n")).toContain("unknown command");
+  });
+
+  test("new app <name> scaffolds the 6 walkthrough files", async () => {
+    const { out, captured } = capture();
+    const code = await runCli({ argv: ["new", "app", "my-notes"], cwd: tmp, out });
+    expect(code).toBe(0);
+    const appRoot = join(tmp, "my-notes");
+    for (const f of [
+      "package.json",
+      "tsconfig.json",
+      "src/run-config.ts",
+      "bin/main.ts",
+      ".env.example",
+      "README.md",
+    ]) {
+      expect(() => readFileSync(join(appRoot, f), "utf-8")).not.toThrow();
+    }
+    expect(captured.logs.join("\n")).toContain("Scaffolded my-notes");
+  });
+
+  test("new app rejects bad name", async () => {
+    const { out, captured } = capture();
+    const code = await runCli({ argv: ["new", "app", "My Notes"], cwd: tmp, out });
+    expect(code).toBe(1);
+    expect(captured.errs.join("\n")).toContain("kebab-case");
+  });
+
+  test("new app without name exits 1 with usage hint", async () => {
+    const { out, captured } = capture();
+    const code = await runCli({ argv: ["new", "app"], cwd: tmp, out });
+    expect(code).toBe(1);
+    expect(captured.errs.join("\n")).toContain("missing <name>");
+  });
+
+  test("add feature mounts into scaffolded app", async () => {
+    const { out: out1 } = capture();
+    await runCli({ argv: ["new", "app", "my-notes"], cwd: tmp, out: out1 });
+    const appRoot = join(tmp, "my-notes");
+
+    const { out: out2, captured } = capture();
+    const code = await runCli({ argv: ["add", "feature", "notes"], cwd: appRoot, out: out2 });
+    expect(code).toBe(0);
+
+    const runConfig = readFileSync(join(appRoot, "src/run-config.ts"), "utf-8");
+    expect(runConfig).toContain(`import { notesFeature } from "./features/notes";`);
+    expect(runConfig).toContain("notesFeature");
+    expect(captured.logs.join("\n")).toContain("auto-mounted");
+  });
+
+  test("add feature without name exits 1", async () => {
+    const { out, captured } = capture();
+    const code = await runCli({ argv: ["add", "feature"], cwd: tmp, out });
+    expect(code).toBe(1);
+    expect(captured.errs.join("\n")).toContain("missing <name>");
+  });
+});

package/src/index.ts

@@ -0,0 +1,117 @@
+// biome-ignore-all lint/suspicious/noConsole: CLI-Script, console ist Feature.
+//
+// runCli — programmatic entry-point for the kumiko CLI. The bin-shim
+// (../bin/cli.ts) is a 3-line wrapper that forwards process.argv. Tests
+// drive runCli directly with a captured Output so no subprocess is needed.
+//
+// Scope (DX-1.2 minimum-viable): `new app <name>` + `add feature <name>`.
+// Other commands (dev, build, check, …) stay in the in-repo bin/kumiko.ts
+// for now — that one operates on the framework workspace, not on a
+// user-app workspace.
+
+import { scaffoldApp, scaffoldAppFeature } from "@cosmicdrift/kumiko-dev-server";
+
+export type Output = {
+  readonly log: (line: string) => void;
+  readonly err: (line: string) => void;
+};
+
+export type RunCliOptions = {
+  readonly argv: readonly string[];
+  readonly cwd?: string;
+  readonly out?: Output;
+};
+
+const DEFAULT_OUT: Output = {
+  log: (line) => console.log(line),
+  err: (line) => console.error(line),
+};
+
+const VERSION = "0.1.0";
+
+export async function runCli(options: RunCliOptions): Promise<number> {
+  const out = options.out ?? DEFAULT_OUT;
+  const argv = [...options.argv];
+  const cwd = options.cwd ?? process.cwd();
+
+  const first = argv[0];
+  if (!first || first === "-h" || first === "--help") {
+    printHelp(out);
+    return 0;
+  }
+  if (first === "-v" || first === "--version") {
+    out.log(VERSION);
+    return 0;
+  }
+
+  if (first === "new") return runNew(argv.slice(1), out, cwd);
+  if (first === "add") return runAdd(argv.slice(1), out, cwd);
+
+  out.err(`kumiko: unknown command "${first}". Run \`kumiko --help\` for usage.`);
+  return 1;
+}
+
+function runNew(args: readonly string[], out: Output, cwd: string): number {
+  const [subject, name] = args;
+  if (subject !== "app") {
+    out.err(`kumiko new: only "new app <name>" is supported. Got "${subject ?? "(nothing)"}".`);
+    return 1;
+  }
+  if (!name) {
+    out.err("kumiko new app: missing <name>. Example: `kumiko new app my-shop`.");
+    return 1;
+  }
+  try {
+    const result = scaffoldApp({ name, destination: `${cwd}/${name}` });
+    out.log(`✓ Scaffolded ${result.appName} → ${result.destination}`);
+    out.log("");
+    for (const f of result.files) out.log(`  ${f}`);
+    out.log("");
+    out.log("Next:");
+    out.log(`  cd ${name}`);
+    out.log("  yarn install && cp .env.example .env");
+    out.log("  bun run boot");
+    return 0;
+  } catch (e) {
+    out.err(`kumiko new app: ${(e as Error).message}`);
+    return 1;
+  }
+}
+
+function runAdd(args: readonly string[], out: Output, cwd: string): number {
+  const [subject, name] = args;
+  if (subject !== "feature") {
+    out.err(`kumiko add: only "add feature <name>" is supported. Got "${subject ?? "(nothing)"}".`);
+    return 1;
+  }
+  if (!name) {
+    out.err("kumiko add feature: missing <name>. Example: `kumiko add feature notes`.");
+    return 1;
+  }
+  try {
+    const result = scaffoldAppFeature({ name, appRoot: cwd });
+    out.log(`✓ Added feature ${result.featureName}:`);
+    for (const f of result.files) out.log(`  ${f}`);
+    out.log(
+      result.autoMounted
+        ? "  src/run-config.ts (auto-mounted)"
+        : "  ⚠ src/run-config.ts not auto-mounted — hand-edit APP_FEATURES.",
+    );
+    return 0;
+  } catch (e) {
+    out.err(`kumiko add feature: ${(e as Error).message}`);
+    return 1;
+  }
+}
+
+function printHelp(out: Output): void {
+  out.log(`kumiko v${VERSION} — scaffold Kumiko apps`);
+  out.log("");
+  out.log("Commands:");
+  out.log("  kumiko new app <name>        Scaffold a new app workspace");
+  out.log("  kumiko add feature <name>    Add + auto-mount a feature");
+  out.log("  kumiko --version             Print version");
+  out.log("  kumiko --help                This help");
+  out.log("");
+  out.log("Docs: https://docs.kumiko.so");
+}