@basaltkit/cli 1.2.5 → 1.3.0

package/README.md

@@ -94,9 +94,15 @@ Without registering anything, `runCli` always provides:
 | `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 upgrade [--dry] [--only=<id>] [--dir=<path>]` | Applies framework upgrade codemods (ships the `@machize/*` → `@basaltkit/*` scope rename; `--dry` previews). `create-basalt update` runs them for you after an install. `nodeUpgradeFs(baseDir)` resolves relative paths against the directory being upgraded, so `--dir=` reads the tree it lists |
 | `basalt publish [<id>] [--force]` | Copies a bundled stub group into the app — `dockerfile` (plus a `.dockerignore` keeping `.env` and keys out of the image), `ci`, `editorconfig` (run with no id to list) |
 
+Not served by `runCli`: the **project commands** `update`, `add`, `doctor` and
+`info` belong to `create-basalt` — the scaffolded `bin/basalt.ts` forwards them
+before booting the app (so `pnpm basalt update` works even when the app does
+not boot). On an older `bin/basalt.ts` they hit `Unknown command`, followed by a
+hint to run `npx create-basalt@latest <command>`.
+
 If you also install `@basaltkit/generator`, you gain the `make:*` commands. Feature
 plugins register their own: `queue:work|stats|retry|jobs` (`@basaltkit/queue`),
 `tenant:list|create|migrate|seed|run` (`@basaltkit/tenancy`), `generate:docs`
@@ -243,7 +249,7 @@ The definitions of the built-in `routes` and `schedule:list` commands. *(Advance
 ## Common errors and solutions (FAQ)
 
 **`Unknown command "x". Run "basalt list" to see what is available.`**
-The command isn't registered. Confirm you passed it inside `commandsPlugin([...])` and that plugin is in the `plugins` list of `createApp`. Run `basalt list` to see what's available.
+The command isn't registered. Confirm you passed it inside `commandsPlugin([...])` and that plugin is in the `plugins` list of `createApp`. Run `basalt list` to see what's available. For `update`, `add`, `doctor` or `info`, see the second line of the error: those are create-basalt's project commands, and `npx create-basalt@latest update` teaches an old `bin/basalt.ts` to forward them.
 
 **My command runs but the `--step 2` flag doesn't work.**
 The parser only recognizes the equals-sign form: `--step=2`. Written with a space, `2` is treated as a positional argument (it shows up in `args`).
@@ -263,4 +269,4 @@ Return a number from `handle` (for example `return 3`). `runCli` propagates it;
 - **`@basaltkit/generator`** — provides `generatorCommands()`, a list of `make:*` commands (code generators) ready to pass to `commandsPlugin`. That's how `basalt make:resource` shows up.
 - **`@basaltkit/fastify`** — writes routes into the `http:routes` bucket, which the built-in `routes` command reads.
 - **`@basaltkit/scheduler`** — writes tasks into the `schedule:entries` bucket, which `schedule:list` reads.
-- **`create-basalt`** — with the `--cli` flag, the project generator creates `bin/basalt.ts`, the `pnpm basalt` script, and registers `commandsPlugin(generatorCommands())` for you.
+- **`create-basalt`** — with the `--cli` flag (or later, `create-basalt add cli`), the project generator creates `bin/basalt.ts`, the `pnpm basalt` script, and registers `commandsPlugin(generatorCommands())` for you. It also provides the project commands `bin/basalt.ts` forwards: `update`, `add`, `doctor`, `info`.

package/dist/runner.js

@@ -2,6 +2,8 @@ import { ensureMetadata } from '@basaltkit/core';
 import { builtinCommands } from './builtins.js';
 import { consoleIo } from './io.js';
 import { parseArgv } from './parse.js';
+/** Commands create-basalt serves (bin/basalt.ts forwards them before booting the app). */
+const PROJECT_COMMANDS = ['update', 'add', 'doctor', 'info'];
 /**
  * Boots the app, resolves the command (built-ins + everything registered in
  * the 'commands' metadata bucket), runs it and shuts the app down.
@@ -25,6 +27,11 @@ export async function runCli(options) {
         const found = commands.find((candidate) => candidate.name === command);
         if (!found) {
             io.error(`Unknown command "${command}". Run "basalt list" to see what is available.`);
+            if (PROJECT_COMMANDS.includes(command)) {
+                // A bin/basalt.ts generated before the project commands existed: they
+                // live in create-basalt, which also patches this file.
+                io.error(`"${command}" is a project command of create-basalt: run \`npx create-basalt@latest ${command}\` (its \`update\` also teaches this bin/basalt.ts to forward it).`);
+            }
             return 1;
         }
         const code = await found.handle({ app, container: app.container, io, args, flags });

package/dist/upgrade.d.ts

@@ -42,7 +42,15 @@ export declare function runUpgrade(migrations: Migration[], fs: UpgradeFs, optio
     dry?: boolean;
     only?: string;
 }): Promise<UpgradeReport[]>;
-/** Node-backed {@link UpgradeFs}. Recursive, skipping build/vcs directories. */
-export declare function nodeUpgradeFs(): UpgradeFs;
+/**
+ * Node-backed {@link UpgradeFs}. Recursive, skipping build/vcs directories.
+ *
+ * `list(dir)` returns paths relative to `dir`; `read`/`write` resolve a relative
+ * path against `baseDir` — pass the same directory you upgrade (default: the
+ * current working directory). Before `baseDir` existed, relative paths always
+ * resolved against `process.cwd()`, so `basalt upgrade --dir=<other>` listed
+ * one tree and read another.
+ */
+export declare function nodeUpgradeFs(baseDir?: string): UpgradeFs;
 /** `basalt upgrade [--dir=<path>] [--dry] [--only=<migration-id>]` */
 export declare const upgradeCommand: CommandDefinition;

package/dist/upgrade.js

@@ -40,13 +40,26 @@ export async function runUpgrade(migrations, fs, options) {
     }
     return reports;
 }
-/** Node-backed {@link UpgradeFs}. Recursive, skipping build/vcs directories. */
-export function nodeUpgradeFs() {
+/**
+ * Node-backed {@link UpgradeFs}. Recursive, skipping build/vcs directories.
+ *
+ * `list(dir)` returns paths relative to `dir`; `read`/`write` resolve a relative
+ * path against `baseDir` — pass the same directory you upgrade (default: the
+ * current working directory). Before `baseDir` existed, relative paths always
+ * resolved against `process.cwd()`, so `basalt upgrade --dir=<other>` listed
+ * one tree and read another.
+ */
+export function nodeUpgradeFs(baseDir) {
     const SKIP = new Set(['node_modules', 'dist', '.git', '.next', 'build', 'coverage']);
+    const at = async (path) => {
+        const { isAbsolute, resolve } = await import('node:path');
+        return isAbsolute(path) ? path : resolve(baseDir ?? process.cwd(), path);
+    };
     return {
         async list(dir) {
             const { readdir } = await import('node:fs/promises');
             const { join, relative } = await import('node:path');
+            const root = await at(dir);
             const out = [];
             const walk = async (current) => {
                 const entries = await readdir(current, { withFileTypes: true });
@@ -56,22 +69,20 @@ export function nodeUpgradeFs() {
                             await walk(join(current, entry.name));
                     }
                     else {
-                        out.push(relative(dir, join(current, entry.name)));
+                        out.push(relative(root, join(current, entry.name)));
                     }
                 }
             };
-            await walk(dir);
+            await walk(root);
             return out;
         },
         async read(path) {
             const { readFile } = await import('node:fs/promises');
-            const { isAbsolute, join } = await import('node:path');
-            return readFile(isAbsolute(path) ? path : join(process.cwd(), path), 'utf8');
+            return readFile(await at(path), 'utf8');
         },
         async write(path, content) {
             const { writeFile } = await import('node:fs/promises');
-            const { isAbsolute, join } = await import('node:path');
-            await writeFile(isAbsolute(path) ? path : join(process.cwd(), path), content, 'utf8');
+            await writeFile(await at(path), content, 'utf8');
         },
     };
 }
@@ -80,14 +91,15 @@ export const 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 { resolve } = await import('node:path');
+        const dir = resolve(typeof flags['dir'] === 'string' ? flags['dir'] : process.cwd());
         const dry = flags['dry'] === true;
         const only = typeof flags['only'] === 'string' ? flags['only'] : undefined;
         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(), {
+        const reports = await runUpgrade(MIGRATIONS, nodeUpgradeFs(dir), {
             dir,
             dry,
             ...(only ? { only } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cli",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -18,12 +18,12 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.3.1"
+    "@basaltkit/core": "^1.5.0"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.1",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0",
+    "vitest": "^5.0.1",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {