@basaltkit/cli 1.0.0 → 1.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Machize Contributors
+Copyright (c) 2026 Basalt Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -87,8 +87,14 @@ Without registering anything, `runCli` always provides:
 | `basalt list` (or `basalt` with no arguments) | Lists all available commands, with their descriptions |
 | `basalt routes` | Lists the HTTP routes registered by the application (read from the `http:routes` metadata bucket, populated by HTTP adapters such as `@basaltkit/fastify`) |
 | `basalt schedule:list` | Lists scheduled tasks and their cron expressions (read from the `schedule:entries` bucket, populated by `@basaltkit/scheduler`) |
+| `basalt dev [--entry] [--worker] [--queue] [--no-routes]` | Runs the app with watch + restart, **prints the route table on boot**, and with `--worker` also starts a watched `queue:work` alongside it (server + worker in one command). Delegates watching to `tsx watch` / `node --watch`. |
+| `basalt upgrade [--dry] [--only=<id>]` | Applies framework upgrade codemods (ships the `@machize/*` → `@basaltkit/*` scope rename; `--dry` previews) |
+| `basalt publish [<id>] [--force]` | Copies a bundled stub group into the app — `dockerfile`, `ci`, `editorconfig` (run with no id to list) |
 
-If you also install `@basaltkit/generator`, you gain the `make:*` commands (see the "How it connects to other modules" section).
+If you also install `@basaltkit/generator`, you gain the `make:*` commands. Feature
+plugins register their own: `queue:work|stats|retry` (`@basaltkit/queue`),
+`tenant:list|create|migrate|seed|run` (`@basaltkit/tenancy`), `generate:docs`
+(`@basaltkit/http`), and `mail:preview` (`@basaltkit/mailer`).
 
 ### Defining a command with arguments and flags
 
@@ -211,7 +217,7 @@ Renders the rows as an aligned text table, with no external dependencies. Return
 
 ### `builtinCommands(): CommandDefinition[]`
 
-Returns `[routesCommand, scheduleListCommand]`. *(Advanced — `runCli` already includes them automatically.)*
+Returns `[routesCommand, scheduleListCommand, devCommand, upgradeCommand, publishCommand]`. *(Advanced — `runCli` already includes them automatically.)*
 
 ### `routesCommand` / `scheduleListCommand`
 

package/dist/index.d.ts

@@ -82,4 +82,136 @@ declare const routesCommand: CommandDefinition;
 declare const scheduleListCommand: CommandDefinition;
 declare function builtinCommands(): CommandDefinition[];
 
-export { type CommandContext, type CommandDefinition, type CommandIo, type ParsedArgv, type RouteMetadata, type RunCliOptions, type ScheduleMetadata, builtinCommands, commandsPlugin, consoleIo, defineCommand, memoryIo, parseArgv, renderTable, routesCommand, runCli, scheduleListCommand };
+/** Default entry files probed in order when `--entry` is not given. */
+declare const DEV_ENTRY_CANDIDATES: string[];
+/**
+ * Picks the first candidate that exists. Pure — `exists` is injected so the
+ * resolution is testable without touching disk.
+ */
+declare function resolveDevEntry(candidates: string[], exists: (path: string) => boolean): string | undefined;
+interface DevRunner {
+    command: string;
+    args: string[];
+}
+/**
+ * Chooses how to run the entry with watch/restart, delegating the actual
+ * watching to the runtime (no bespoke watcher). Pure and testable:
+ *
+ * - `.ts` with tsx available → `tsx watch <entry>`
+ * - `.ts` without tsx        → `node --watch --experimental-strip-types <entry>` (Node ≥ 22.6)
+ * - `.js`                     → `node --watch <entry>`
+ */
+declare function resolveDevRunner(entry: string, options?: {
+    tsx?: boolean;
+}): DevRunner;
+/** A route as published into the `http:routes` metadata bucket by an adapter. */
+interface DevRoute {
+    method: string;
+    url: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Formats the registered routes into printable rows (method, url, and a compact
+ * flags column for auth/rate-limit) — sorted by url then method. Pure: this is
+ * what `basalt dev` prints on boot, and `pnpm dev` (plain tsx watch) can't.
+ */
+declare function devRouteRows(routes: DevRoute[]): {
+    method: string;
+    url: string;
+    flags: string;
+}[];
+/**
+ * `basalt dev [--entry=<file>] [--worker] [--queue=<name>] [--no-routes]`
+ *
+ * A richer dev loop than a bare `tsx watch`: prints the app's **route table** on
+ * boot (the app is already booted by the CLI runner, so routes are known), then
+ * runs the server with watch/restart — and, with `--worker`, also starts a
+ * watched queue worker alongside it (server + worker in one command, the real
+ * producer/worker topology).
+ */
+declare const devCommand: CommandDefinition;
+
+/**
+ * Filesystem surface an upgrade migration works against. Injected so migrations
+ * (and `runUpgrade`) are testable with an in-memory tree — no disk needed.
+ */
+interface UpgradeFs {
+    /** Recursively lists files under `dir` (relative paths). Skips node_modules/dist/.git. */
+    list(dir: string): Promise<string[]>;
+    read(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+}
+/** A single edit a migration wants to make — surfaced for `--dry` before writing. */
+interface Edit {
+    path: string;
+    before: string;
+    after: string;
+}
+/** A versioned, idempotent codemod. `plan` computes edits without writing them. */
+interface Migration {
+    id: string;
+    description: string;
+    plan(fs: UpgradeFs, dir: string): Promise<Edit[]>;
+}
+interface UpgradeReport {
+    migration: string;
+    changed: string[];
+}
+/**
+ * A codemod that rewrites the deprecated `@machize/*` npm scope to `@basaltkit/*`
+ * across package.json and source imports. Unambiguous (scoped rename), so a plain
+ * text replace is safe and idempotent.
+ */
+declare const renameMachizeScope: Migration;
+/** All migrations shipped with the CLI, in application order. */
+declare const MIGRATIONS: Migration[];
+/**
+ * Runs the selected migrations. With `dry`, computes and reports edits without
+ * writing. Returns a per-migration report of the files it changed.
+ */
+declare function runUpgrade(migrations: Migration[], fs: UpgradeFs, options: {
+    dir: string;
+    dry?: boolean;
+    only?: string;
+}): Promise<UpgradeReport[]>;
+/** Node-backed {@link UpgradeFs}. Recursive, skipping build/vcs directories. */
+declare function nodeUpgradeFs(): UpgradeFs;
+/** `basalt upgrade [--dir=<path>] [--dry] [--only=<migration-id>]` */
+declare const upgradeCommand: CommandDefinition;
+
+/** One file a publishable drops into the app. */
+interface PublishableFile {
+    /** Path relative to the target dir, e.g. `Dockerfile` or `.github/workflows/ci.yml`. */
+    path: string;
+    content: string;
+}
+/** A named group of stub files an app can copy in and then own (à la vendor:publish). */
+interface Publishable {
+    id: string;
+    description: string;
+    files(): PublishableFile[];
+}
+/** Filesystem surface for publishing — injected so `runPublish` is testable. */
+interface PublishFs {
+    exists(path: string): Promise<boolean>;
+    write(path: string, content: string): Promise<void>;
+}
+interface PublishResult {
+    written: string[];
+    skipped: string[];
+}
+/** Stubs bundled with the CLI. Apps can register more via the metadata bucket. */
+declare const PUBLISHABLES: Publishable[];
+/**
+ * Copies a publishable's files into the target, skipping any that already exist
+ * unless `force` is set. Returns which files were written vs skipped.
+ */
+declare function runPublish(publishable: Publishable, fs: PublishFs, options?: {
+    force?: boolean;
+}): Promise<PublishResult>;
+/** Node-backed {@link PublishFs} rooted at `dir` (creates parent directories). */
+declare function nodePublishFs(dir: string): PublishFs;
+/** `basalt publish [<id>] [--dir=<path>] [--force]` — list, or copy a stub group. */
+declare const publishCommand: CommandDefinition;
+
+export { type CommandContext, type CommandDefinition, type CommandIo, DEV_ENTRY_CANDIDATES, type DevRoute, type DevRunner, type Edit, MIGRATIONS, type Migration, PUBLISHABLES, type ParsedArgv, type PublishFs, type PublishResult, type Publishable, type PublishableFile, type RouteMetadata, type RunCliOptions, type ScheduleMetadata, type UpgradeFs, type UpgradeReport, builtinCommands, commandsPlugin, consoleIo, defineCommand, devCommand, devRouteRows, memoryIo, nodePublishFs, nodeUpgradeFs, parseArgv, publishCommand, renameMachizeScope, renderTable, resolveDevEntry, resolveDevRunner, routesCommand, runCli, runPublish, runUpgrade, scheduleListCommand, upgradeCommand };

package/dist/index.js

@@ -4,10 +4,296 @@ function defineCommand(command) {
 }
 
 // src/runner.ts
-import { ensureMetadata } from "@basaltkit/core";
+import { ensureMetadata as ensureMetadata2 } from "@basaltkit/core";
 
 // src/builtins.ts
 import { METADATA } from "@basaltkit/core";
+
+// src/dev.ts
+import { ensureMetadata } from "@basaltkit/core";
+var DEV_ENTRY_CANDIDATES = ["src/main.ts", "src/server.ts", "src/index.ts", "src/main.js", "src/index.js"];
+function resolveDevEntry(candidates, exists) {
+  return candidates.find(exists);
+}
+function resolveDevRunner(entry, options = {}) {
+  const isTs = /\.tsx?$/.test(entry);
+  if (isTs && options.tsx) return { command: "tsx", args: ["watch", entry] };
+  if (isTs) return { command: "node", args: ["--watch", "--experimental-strip-types", entry] };
+  return { command: "node", args: ["--watch", entry] };
+}
+function devRouteRows(routes) {
+  return [...routes].sort((a, b) => a.url.localeCompare(b.url) || a.method.localeCompare(b.method)).map((r) => {
+    const flags = [];
+    if (r.meta?.["auth"] === true) flags.push("auth");
+    if (r.meta?.["rateLimit"]) flags.push("rate-limit");
+    const tags = r.meta?.["tags"];
+    if (Array.isArray(tags) && tags.length) flags.push(...tags.map(String));
+    return { method: r.method.toUpperCase(), url: r.url, flags: flags.join(", ") };
+  });
+}
+var devCommand = defineCommand({
+  name: "dev",
+  description: "Run the app with watch + restart, print the route table, and (--worker) an embedded queue worker",
+  async handle({ container, io, flags }) {
+    const { existsSync } = await import("fs");
+    const entry = typeof flags["entry"] === "string" ? flags["entry"] : resolveDevEntry(DEV_ENTRY_CANDIDATES, existsSync);
+    if (!entry) {
+      io.error(
+        `No entry file found. Looked for ${DEV_ENTRY_CANDIDATES.join(", ")}. Pass --entry=<file>.`
+      );
+      return 1;
+    }
+    if (flags["routes"] !== false) {
+      const routes = ensureMetadata(container).get("http:routes");
+      if (routes.length > 0) {
+        io.log(`Routes (${routes.length}):`);
+        io.table(devRouteRows(routes));
+      }
+    }
+    const tsx = await canResolve("tsx");
+    const server = resolveDevRunner(entry, { tsx });
+    const runners = [{ label: "server", runner: server }];
+    if (flags["worker"] === true || flags["w"] === true) {
+      const bin = process.argv[1] ?? entry;
+      const workerBase = resolveDevRunner(bin, { tsx });
+      const queue = typeof flags["queue"] === "string" ? [`--queue=${flags["queue"]}`] : [];
+      runners.push({ label: "worker", runner: { command: workerBase.command, args: [...workerBase.args, "queue:work", ...queue] } });
+    }
+    for (const { label, runner } of runners) {
+      io.log(`\u25B6 ${label}: ${runner.command} ${runner.args.join(" ")}`);
+    }
+    const { spawn } = await import("child_process");
+    return await new Promise((resolve) => {
+      const children = runners.map(({ runner }) => spawn(runner.command, runner.args, { stdio: "inherit" }));
+      const stop = () => children.forEach((c) => c.kill("SIGINT"));
+      process.once("SIGINT", stop);
+      let done = false;
+      const finish = (code) => {
+        if (done) return;
+        done = true;
+        process.removeListener("SIGINT", stop);
+        children.forEach((c) => c.kill("SIGINT"));
+        resolve(code);
+      };
+      children[0]?.on("exit", (code) => finish(code ?? 0));
+      children.forEach(
+        (child, i) => child.on("error", (error) => {
+          io.error(`Failed to start ${runners[i]?.label}: ${error.message}`);
+          finish(1);
+        })
+      );
+    });
+  }
+});
+async function canResolve(specifier) {
+  try {
+    const { createRequire } = await import("module");
+    createRequire(`${process.cwd()}/`).resolve(specifier);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/upgrade.ts
+var renameMachizeScope = {
+  id: "rename-machize-scope",
+  description: "Rewrite the deprecated @machize/* scope to @basaltkit/*",
+  async plan(fs, dir) {
+    const files = (await fs.list(dir)).filter((p) => /\.(t|j)sx?$|\.json$/.test(p));
+    const edits = [];
+    for (const path of files) {
+      const before = await fs.read(path);
+      if (!before.includes("@machize/")) continue;
+      const after = before.split("@machize/").join("@basaltkit/");
+      if (after !== before) edits.push({ path, before, after });
+    }
+    return edits;
+  }
+};
+var MIGRATIONS = [renameMachizeScope];
+async function runUpgrade(migrations, fs, options) {
+  const selected = options.only ? migrations.filter((m) => m.id === options.only) : migrations;
+  const reports = [];
+  for (const migration of selected) {
+    const edits = await migration.plan(fs, options.dir);
+    if (!options.dry) {
+      for (const edit of edits) await fs.write(edit.path, edit.after);
+    }
+    reports.push({ migration: migration.id, changed: edits.map((e) => e.path) });
+  }
+  return reports;
+}
+function nodeUpgradeFs() {
+  const SKIP = /* @__PURE__ */ new Set(["node_modules", "dist", ".git", ".next", "build", "coverage"]);
+  return {
+    async list(dir) {
+      const { readdir } = await import("fs/promises");
+      const { join, relative } = await import("path");
+      const out = [];
+      const walk = async (current) => {
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            if (!SKIP.has(entry.name)) await walk(join(current, entry.name));
+          } else {
+            out.push(relative(dir, join(current, entry.name)));
+          }
+        }
+      };
+      await walk(dir);
+      return out;
+    },
+    async read(path) {
+      const { readFile } = await import("fs/promises");
+      const { isAbsolute, join } = await import("path");
+      return readFile(isAbsolute(path) ? path : join(process.cwd(), path), "utf8");
+    },
+    async write(path, content) {
+      const { writeFile } = await import("fs/promises");
+      const { isAbsolute, join } = await import("path");
+      await writeFile(isAbsolute(path) ? path : join(process.cwd(), path), content, "utf8");
+    }
+  };
+}
+var upgradeCommand = defineCommand({
+  name: "upgrade",
+  description: "Apply framework upgrade codemods (--dry to preview, --only=<id>)",
+  async handle({ io, flags }) {
+    const dir = typeof flags["dir"] === "string" ? flags["dir"] : process.cwd();
+    const dry = flags["dry"] === true;
+    const only = typeof flags["only"] === "string" ? flags["only"] : void 0;
+    if (only && !MIGRATIONS.some((m) => m.id === only)) {
+      io.error(`Unknown migration "${only}". Available: ${MIGRATIONS.map((m) => m.id).join(", ")}.`);
+      return 1;
+    }
+    const reports = await runUpgrade(MIGRATIONS, nodeUpgradeFs(), {
+      dir,
+      dry,
+      ...only ? { only } : {}
+    });
+    let total = 0;
+    for (const report of reports) {
+      if (report.changed.length === 0) continue;
+      total += report.changed.length;
+      io.log(`${dry ? "[dry] " : ""}${report.migration}: ${report.changed.length} file(s)`);
+      for (const path of report.changed) io.log(`  ${path}`);
+    }
+    if (total === 0) io.log("Nothing to upgrade \u2014 everything is up to date.");
+    else if (dry) io.log(`
+${total} file(s) would change. Re-run without --dry to apply.`);
+    else io.log(`
+Applied ${total} change(s).`);
+    return 0;
+  }
+});
+
+// src/publish.ts
+var DOCKERFILE = `# syntax=docker/dockerfile:1
+FROM node:22-slim AS base
+ENV NODE_ENV=production
+WORKDIR /app
+
+FROM base AS deps
+COPY package.json pnpm-lock.yaml* ./
+RUN corepack enable && pnpm install --prod --frozen-lockfile
+
+FROM base AS run
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+`;
+var CI_WORKFLOW = `name: ci
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: pnpm run test
+`;
+var EDITORCONFIG = `root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+`;
+var PUBLISHABLES = [
+  { id: "dockerfile", description: "Production multi-stage Dockerfile", files: () => [{ path: "Dockerfile", content: DOCKERFILE }] },
+  { id: "ci", description: "GitHub Actions CI workflow", files: () => [{ path: ".github/workflows/ci.yml", content: CI_WORKFLOW }] },
+  { id: "editorconfig", description: "Shared .editorconfig", files: () => [{ path: ".editorconfig", content: EDITORCONFIG }] }
+];
+async function runPublish(publishable, fs, options = {}) {
+  const written = [];
+  const skipped = [];
+  for (const file of publishable.files()) {
+    if (!options.force && await fs.exists(file.path)) {
+      skipped.push(file.path);
+      continue;
+    }
+    await fs.write(file.path, file.content);
+    written.push(file.path);
+  }
+  return { written, skipped };
+}
+function nodePublishFs(dir) {
+  return {
+    async exists(path) {
+      const { access } = await import("fs/promises");
+      const { join } = await import("path");
+      return access(join(dir, path)).then(
+        () => true,
+        () => false
+      );
+    },
+    async write(path, content) {
+      const { mkdir, writeFile } = await import("fs/promises");
+      const { dirname, join } = await import("path");
+      const target = join(dir, path);
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, content, "utf8");
+    }
+  };
+}
+var publishCommand = defineCommand({
+  name: "publish",
+  description: "Copy a publishable stub group into the app (run with no id to list)",
+  async handle({ io, args, flags }) {
+    const id = args[0];
+    if (!id) {
+      io.log("Publishable groups:");
+      io.table(PUBLISHABLES.map((p) => ({ id: p.id, description: p.description })));
+      return 0;
+    }
+    const publishable = PUBLISHABLES.find((p) => p.id === id);
+    if (!publishable) {
+      io.error(`Unknown publishable "${id}". Available: ${PUBLISHABLES.map((p) => p.id).join(", ")}.`);
+      return 1;
+    }
+    const dir = typeof flags["dir"] === "string" ? flags["dir"] : process.cwd();
+    const result = await runPublish(publishable, nodePublishFs(dir), { force: flags["force"] === true });
+    for (const path of result.written) io.log(`  wrote ${path}`);
+    for (const path of result.skipped) io.log(`  skipped ${path} (exists \u2014 use --force to overwrite)`);
+    if (result.written.length === 0 && result.skipped.length > 0) {
+      io.log("Nothing written. Re-run with --force to overwrite existing files.");
+    }
+    return 0;
+  }
+});
+
+// src/builtins.ts
 var routesCommand = defineCommand({
   name: "routes",
   description: "List the HTTP routes registered by the app",
@@ -33,7 +319,7 @@ var scheduleListCommand = defineCommand({
   }
 });
 function builtinCommands() {
-  return [routesCommand, scheduleListCommand];
+  return [routesCommand, scheduleListCommand, devCommand, upgradeCommand, publishCommand];
 }
 
 // src/io.ts
@@ -109,7 +395,7 @@ async function runCli(options) {
   const { command, args, flags } = parseArgv(options.argv ?? process.argv.slice(2));
   if (app.phase === "created") await app.boot();
   try {
-    const registered = ensureMetadata(app.container).get("commands");
+    const registered = ensureMetadata2(app.container).get("commands");
     const commands = [...builtinCommands(), ...registered];
     if (command === void 0 || command === "list") {
       io.log("Available commands:");
@@ -131,25 +417,39 @@ async function runCli(options) {
 }
 
 // src/plugin.ts
-import { definePlugin, ensureMetadata as ensureMetadata2 } from "@basaltkit/core";
+import { definePlugin, ensureMetadata as ensureMetadata3 } from "@basaltkit/core";
 function commandsPlugin(commands) {
   return definePlugin({
     name: "basalt:commands",
     register({ container }) {
-      const metadata = ensureMetadata2(container);
+      const metadata = ensureMetadata3(container);
       for (const command of commands) metadata.add("commands", command);
     }
   });
 }
 export {
+  DEV_ENTRY_CANDIDATES,
+  MIGRATIONS,
+  PUBLISHABLES,
   builtinCommands,
   commandsPlugin,
   consoleIo,
   defineCommand,
+  devCommand,
+  devRouteRows,
   memoryIo,
+  nodePublishFs,
+  nodeUpgradeFs,
   parseArgv,
+  publishCommand,
+  renameMachizeScope,
   renderTable,
+  resolveDevEntry,
+  resolveDevRunner,
   routesCommand,
   runCli,
-  scheduleListCommand
+  runPublish,
+  runUpgrade,
+  scheduleListCommand,
+  upgradeCommand
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "The 'basalt' command framework for Basalt apps: define commands, run them against a booted app, and inspect routes and schedules.",
   "license": "MIT",
   "type": "module",