@basaltkit/cli 1.4.1 → 1.5.0

package/README.md

@@ -24,6 +24,23 @@ pnpm add @basaltkit/cli
 
 > Note: the package depends on `@basaltkit/core` (the heart of the framework, where `createApp` and the dependency container live). If you created the project with `create-basalt --cli`, both are already installed.
 
+### The global `basalt` launcher
+
+Inside an app, `basalt` is a `package.json` script: `pnpm basalt <command>`.
+Install the launcher once to type `basalt <command>` instead:
+
+```bash
+npm i -g @basaltkit/cli
+basalt routes        # anywhere inside the app = pnpm basalt routes, in the app's root
+```
+
+It finds the nearest `package.json` with a `basalt` script, from the current
+directory up, and runs that script with the app's package manager
+(`packageManager`, else the lockfile). So the code that runs is always the
+app's, at its pinned versions. Arguments and the exit code pass through
+unchanged. Outside an app it says so and exits 1. The launcher loads nothing of
+the framework, only Node built-ins.
+
 ## Get started in 5 minutes
 
 1. Create a `bin/basalt.ts` file at the root of the project — this will be the entry point for the `basalt` command:

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runLauncher } from './launcher.js';
+process.exitCode = await runLauncher(process.argv.slice(2));

package/dist/launcher.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The global `basalt` launcher: `npm i -g @basaltkit/cli`, then `basalt <command>`
+ * anywhere inside an app does what `pnpm basalt <command>` does there.
+ *
+ * It never runs commands itself. It finds the app (the nearest package.json
+ * with a `basalt` script) and hands the arguments to that script through the
+ * app's own package manager — so the code that runs is always the app's, at
+ * the versions its lockfile pins, never the launcher's. Node built-ins only:
+ * nothing of the framework is loaded.
+ */
+export type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
+export interface LauncherProject {
+    /** The directory whose package.json declares the `basalt` script. */
+    root: string;
+    /** The script itself, e.g. `tsx bin/basalt.ts`. */
+    script: string;
+    pm: PackageManager;
+}
+/** Set on the script's environment: a `basalt` script that calls `basalt` again would loop. */
+export declare const LAUNCHER_ENV = "BASALT_LAUNCHER_ROOT";
+/** The nearest app at or above `from`: a package.json with a `basalt` script. */
+export declare function findProject(from: string): LauncherProject | undefined;
+/**
+ * `packageManager` in the nearest package.json that has one, else the nearest
+ * lockfile — both walking up, so an app inside a workspace uses the
+ * workspace's manager. Nothing found: npm.
+ */
+export declare function detectPackageManager(root: string): PackageManager;
+/**
+ * The command that runs the app's `basalt` script with `args`, as given:
+ * pnpm, yarn and bun pass everything after the script name through (a `--`
+ * included); npm needs a `--` first.
+ */
+export declare function launchCommand(pm: PackageManager, args: readonly string[]): {
+    command: string;
+    args: string[];
+};
+export interface RunLauncherOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Where the launcher's own lines go (never the app's output). */
+    error?: (line: string) => void;
+    log?: (line: string) => void;
+}
+/** Runs `basalt <argv>`: the app's `basalt` script, through the app's package manager. Resolves to the exit code. */
+export declare function runLauncher(argv: readonly string[], options?: RunLauncherOptions): Promise<number>;

package/dist/launcher.js

@@ -0,0 +1,154 @@
+/**
+ * The global `basalt` launcher: `npm i -g @basaltkit/cli`, then `basalt <command>`
+ * anywhere inside an app does what `pnpm basalt <command>` does there.
+ *
+ * It never runs commands itself. It finds the app (the nearest package.json
+ * with a `basalt` script) and hands the arguments to that script through the
+ * app's own package manager — so the code that runs is always the app's, at
+ * the versions its lockfile pins, never the launcher's. Node built-ins only:
+ * nothing of the framework is loaded.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** Set on the script's environment: a `basalt` script that calls `basalt` again would loop. */
+export const LAUNCHER_ENV = 'BASALT_LAUNCHER_ROOT';
+function readManifest(dir) {
+    const file = join(dir, 'package.json');
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        return typeof value === 'object' && value !== null ? value : undefined;
+    }
+    catch {
+        return undefined; // an unreadable package.json is not an app: keep walking
+    }
+}
+/** Every directory from `from` up to the filesystem root, nearest first. */
+function* ancestors(from) {
+    let dir = resolve(from);
+    while (true) {
+        yield dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return;
+        dir = parent;
+    }
+}
+/** The nearest app at or above `from`: a package.json with a `basalt` script. */
+export function findProject(from) {
+    for (const dir of ancestors(from)) {
+        const script = readManifest(dir)?.scripts?.['basalt'];
+        if (typeof script === 'string' && script.trim() !== '') {
+            return { root: dir, script, pm: detectPackageManager(dir) };
+        }
+    }
+    return undefined;
+}
+const LOCKFILES = [
+    ['pnpm', ['pnpm-lock.yaml']],
+    ['bun', ['bun.lock', 'bun.lockb']],
+    ['yarn', ['yarn.lock']],
+    ['npm', ['package-lock.json']],
+];
+/**
+ * `packageManager` in the nearest package.json that has one, else the nearest
+ * lockfile — both walking up, so an app inside a workspace uses the
+ * workspace's manager. Nothing found: npm.
+ */
+export function detectPackageManager(root) {
+    for (const dir of ancestors(root)) {
+        const declared = readManifest(dir)?.packageManager;
+        if (typeof declared === 'string') {
+            const name = declared.split('@')[0];
+            if (name === 'pnpm' || name === 'npm' || name === 'yarn' || name === 'bun')
+                return name;
+        }
+        for (const [pm, files] of LOCKFILES)
+            if (files.some((file) => existsSync(join(dir, file))))
+                return pm;
+    }
+    return 'npm';
+}
+/**
+ * The command that runs the app's `basalt` script with `args`, as given:
+ * pnpm, yarn and bun pass everything after the script name through (a `--`
+ * included); npm needs a `--` first.
+ */
+export function launchCommand(pm, args) {
+    switch (pm) {
+        case 'pnpm': return { command: 'pnpm', args: ['run', '--silent', 'basalt', ...args] };
+        case 'npm': return { command: 'npm', args: ['run', '--silent', 'basalt', '--', ...args] };
+        case 'yarn': return { command: 'yarn', args: ['run', 'basalt', ...args] };
+        case 'bun': return { command: 'bun', args: ['run', 'basalt', ...args] };
+    }
+}
+function launcherVersion() {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return manifest.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+const NOT_AN_APP = [
+    'basalt: no Basalt app here — no package.json with a "basalt" script in this directory or above it.',
+    '  Start one:   npm create basalt@latest my-app',
+    '  Or cd into an app first; `basalt <command>` then runs `<pm> basalt <command>` there.',
+];
+/** Runs `basalt <argv>`: the app's `basalt` script, through the app's package manager. Resolves to the exit code. */
+export async function runLauncher(argv, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const error = options.error ?? ((line) => process.stderr.write(`${line}\n`));
+    const log = options.log ?? ((line) => process.stdout.write(`${line}\n`));
+    const project = findProject(cwd);
+    if (!project) {
+        if (argv[0] === '--version' || argv[0] === '-v') {
+            log(`basalt launcher ${launcherVersion()} (@basaltkit/cli)`);
+            return 0;
+        }
+        for (const line of NOT_AN_APP)
+            error(line);
+        return 1;
+    }
+    if (env[LAUNCHER_ENV] === project.root) {
+        error(`basalt: the "basalt" script in ${join(project.root, 'package.json')} runs \`basalt\` again (${project.script}).`);
+        error('  Point it at the app\'s own CLI instead, e.g. "basalt": "tsx bin/basalt.ts".');
+        return 1;
+    }
+    const { command, args } = launchCommand(project.pm, argv);
+    return new Promise((done) => {
+        const child = spawn(command, args, {
+            cwd: project.root,
+            env: { ...env, [LAUNCHER_ENV]: project.root },
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+        // Ctrl-C reaches the whole foreground group: the app handles it; the
+        // launcher only waits for it to finish and reports its code.
+        const ignore = () => { };
+        const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+        for (const signal of signals)
+            process.on(signal, ignore);
+        const settle = (code) => {
+            for (const signal of signals)
+                process.off(signal, ignore);
+            done(code);
+        };
+        child.on('error', (cause) => {
+            error(cause.code === 'ENOENT'
+                ? `basalt: ${command} is not installed, and this app uses it (${project.root}).`
+                : `basalt: could not start ${command}: ${cause.message}`);
+            settle(1);
+        });
+        child.on('exit', (code, signal) => {
+            settle(code ?? (signal ? 128 + signalNumber(signal) : 1));
+        });
+    });
+}
+function signalNumber(signal) {
+    return { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 }[signal] ?? 1;
+}

package/dist/stubs.d.ts

@@ -22,9 +22,12 @@ export declare const DOCKERFILE = "# syntax=docker/dockerfile:1\n# Production im
  * private keys and VCS metadata into an image layer. Every secret rule is
  * \`**\/\`-prefixed: .dockerignore patterns are anchored at the context root, so
  * a bare \`.env\` or \`*.pem\` would still let \`prisma/.env\` or
- * \`certs/server.key\` through. \`dist\` is rebuilt inside the image.
+ * \`certs/server.key\` through. \`.basalt\` and \`backups\` at the root (the
+ * deploy's state and database dumps — anchored, so an app's own \`backups\`
+ * module is still copied) never belong in an image. \`dist\` is rebuilt
+ * inside the image.
  */
-export declare const DOCKERIGNORE = "**/.env\n**/.env.*\n!**/.env.example\n**/.npmrc\n**/.git\n**/node_modules\n**/coverage\n**/*.log\n**/*.pem\n**/*.key\n**/*.p12\n**/*.pfx\n**/.DS_Store\ndist\n";
+export declare const DOCKERIGNORE = "**/.env\n**/.env.*\n!**/.env.example\n**/.npmrc\n**/.git\n**/node_modules\n**/coverage\n**/*.log\n**/*.pem\n**/*.key\n**/*.p12\n**/*.pfx\n**/.DS_Store\n.basalt\nbackups\ndist\n";
 /** GitHub Actions CI: install, typecheck, build (the production path), test. */
 export declare const CI_WORKFLOW = "name: ci\non:\n  push: { branches: [main] }\n  pull_request:\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      # Drop `with: version` if package.json declares a packageManager.\n      - uses: pnpm/action-setup@v4\n        with: { version: 11 }\n      - uses: actions/setup-node@v4\n        with: { node-version: 22, cache: pnpm }\n      - run: pnpm install --frozen-lockfile\n      - run: pnpm run typecheck\n      - run: pnpm run build\n      - run: pnpm run test\n";
 export declare const EDITORCONFIG = "root = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\ninsert_final_newline = true\nindent_style = space\nindent_size = 2\ntrim_trailing_whitespace = true\n";

package/dist/stubs.js

@@ -73,7 +73,10 @@ CMD ["node", "--enable-source-maps", "${PRODUCTION_ENTRY}"]
  * private keys and VCS metadata into an image layer. Every secret rule is
  * \`**\/\`-prefixed: .dockerignore patterns are anchored at the context root, so
  * a bare \`.env\` or \`*.pem\` would still let \`prisma/.env\` or
- * \`certs/server.key\` through. \`dist\` is rebuilt inside the image.
+ * \`certs/server.key\` through. \`.basalt\` and \`backups\` at the root (the
+ * deploy's state and database dumps — anchored, so an app's own \`backups\`
+ * module is still copied) never belong in an image. \`dist\` is rebuilt
+ * inside the image.
  */
 export const DOCKERIGNORE = `**/.env
 **/.env.*
@@ -88,6 +91,8 @@ export const DOCKERIGNORE = `**/.env
 **/*.p12
 **/*.pfx
 **/.DS_Store
+.basalt
+backups
 dist
 `;
 /** GitHub Actions CI: install, typecheck, build (the production path), test. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cli",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -14,6 +14,9 @@
       "import": "./dist/index.js"
     }
   },
+  "bin": {
+    "basalt": "./dist/bin.js"
+  },
   "files": [
     "dist"
   ],
@@ -22,9 +25,9 @@
     "@basaltkit/http": "^3.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.6.1",
+    "@types/node": "^26.6.5",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.1",
+    "vitest": "^5.0.5",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {