@basaltkit/cli 1.2.0 → 1.2.1

package/dist/publish.js

@@ -0,0 +1,110 @@
+import { defineCommand } from './command.js';
+const 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"]
+`;
+const 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
+`;
+const EDITORCONFIG = `root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+`;
+/** Stubs bundled with the CLI. Apps can register more via the metadata bucket. */
+export const 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 }] },
+];
+/**
+ * Copies a publishable's files into the target, skipping any that already exist
+ * unless `force` is set. Returns which files were written vs skipped.
+ */
+export 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 };
+}
+/** Node-backed {@link PublishFs} rooted at `dir` (creates parent directories). */
+export function nodePublishFs(dir) {
+    return {
+        async exists(path) {
+            const { access } = await import('node:fs/promises');
+            const { join } = await import('node:path');
+            return access(join(dir, path)).then(() => true, () => false);
+        },
+        async write(path, content) {
+            const { mkdir, writeFile } = await import('node:fs/promises');
+            const { dirname, join } = await import('node:path');
+            const target = join(dir, path);
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, content, 'utf8');
+        },
+    };
+}
+/** `basalt publish [<id>] [--dir=<path>] [--force]` — list, or copy a stub group. */
+export const 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 — 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;
+    },
+});

package/dist/runner.d.ts

@@ -0,0 +1,16 @@
+import { type BasaltApp } from '@basaltkit/core';
+import type { CommandIo } from './command.js';
+export interface RunCliOptions {
+    app: BasaltApp;
+    /** Defaults to process.argv.slice(2). */
+    argv?: string[];
+    /** Defaults to console output — swap in tests. */
+    io?: CommandIo;
+}
+/**
+ * Boots the app, resolves the command (built-ins + everything registered in
+ * the 'commands' metadata bucket), runs it and shuts the app down.
+ * Returns the process exit code instead of calling process.exit — the bin
+ * wrapper decides what to do with it.
+ */
+export declare function runCli(options: RunCliOptions): Promise<number>;

package/dist/runner.js

@@ -0,0 +1,36 @@
+import { ensureMetadata } from '@basaltkit/core';
+import { builtinCommands } from './builtins.js';
+import { consoleIo } from './io.js';
+import { parseArgv } from './parse.js';
+/**
+ * Boots the app, resolves the command (built-ins + everything registered in
+ * the 'commands' metadata bucket), runs it and shuts the app down.
+ * Returns the process exit code instead of calling process.exit — the bin
+ * wrapper decides what to do with it.
+ */
+export async function runCli(options) {
+    const { app } = options;
+    const io = options.io ?? consoleIo();
+    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 commands = [...builtinCommands(), ...registered];
+        if (command === undefined || command === 'list') {
+            io.log('Available commands:');
+            io.table(commands.map(({ name, description }) => ({ command: name, description: description ?? '' })));
+            return 0;
+        }
+        const found = commands.find((candidate) => candidate.name === command);
+        if (!found) {
+            io.error(`Unknown command "${command}". Run "basalt list" to see what is available.`);
+            return 1;
+        }
+        const code = await found.handle({ app, container: app.container, io, args, flags });
+        return code ?? 0;
+    }
+    finally {
+        await app.shutdown();
+    }
+}

package/dist/upgrade.d.ts

@@ -0,0 +1,48 @@
+import { type CommandDefinition } from './command.js';
+/**
+ * Filesystem surface an upgrade migration works against. Injected so migrations
+ * (and `runUpgrade`) are testable with an in-memory tree — no disk needed.
+ */
+export 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. */
+export interface Edit {
+    path: string;
+    before: string;
+    after: string;
+}
+/** A versioned, idempotent codemod. `plan` computes edits without writing them. */
+export interface Migration {
+    id: string;
+    description: string;
+    plan(fs: UpgradeFs, dir: string): Promise<Edit[]>;
+}
+export 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.
+ */
+export declare const renameMachizeScope: Migration;
+/** All migrations shipped with the CLI, in application order. */
+export 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.
+ */
+export 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. */
+export declare function nodeUpgradeFs(): UpgradeFs;
+/** `basalt upgrade [--dir=<path>] [--dry] [--only=<migration-id>]` */
+export declare const upgradeCommand: CommandDefinition;

package/dist/upgrade.js

@@ -0,0 +1,112 @@
+import { defineCommand } from './command.js';
+/**
+ * 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.
+ */
+export const 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;
+    },
+};
+/** All migrations shipped with the CLI, in application order. */
+export const MIGRATIONS = [renameMachizeScope];
+/**
+ * Runs the selected migrations. With `dry`, computes and reports edits without
+ * writing. Returns a per-migration report of the files it changed.
+ */
+export 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;
+}
+/** Node-backed {@link UpgradeFs}. Recursive, skipping build/vcs directories. */
+export function nodeUpgradeFs() {
+    const SKIP = new Set(['node_modules', 'dist', '.git', '.next', 'build', 'coverage']);
+    return {
+        async list(dir) {
+            const { readdir } = await import('node:fs/promises');
+            const { join, relative } = await import('node: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('node:fs/promises');
+            const { isAbsolute, join } = await import('node:path');
+            return readFile(isAbsolute(path) ? path : join(process.cwd(), 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');
+        },
+    };
+}
+/** `basalt upgrade [--dir=<path>] [--dry] [--only=<migration-id>]` */
+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 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(), {
+            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 — everything is up to date.');
+        else if (dry)
+            io.log(`\n${total} file(s) would change. Re-run without --dry to apply.`);
+        else
+            io.log(`\nApplied ${total} change(s).`);
+        return 0;
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cli",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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",
@@ -14,13 +14,12 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.0.0"
+    "@basaltkit/core": "^1.1.2"
   },
   "devDependencies": {
-    "@types/node": "^22.15.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0",
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -28,11 +27,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "url": "git+https://github.com/basaltkit/basalt.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/cli#readme",
-  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "homepage": "https://github.com/basaltkit/basalt/tree/main/packages/cli#readme",
+  "bugs": "https://github.com/basaltkit/basalt/issues",
   "keywords": [
     "basalt",
     "typescript",
@@ -40,7 +39,7 @@
     "commands"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }