@getstrata/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,11 +1,31 @@
 # @getstrata/cli
 
-Strata framework CLI for migrations, queue workers, and code generation.
+Framework CLI for Strata apps. Bun stays the runtime, installer, and test runner. `strata` owns app lifecycle and framework commands.
 
 ```bash
-bunx @getstrata/cli migrate
-bunx @getstrata/cli queue:work
-bunx @getstrata/cli make:migration create_users_table
+strata dev
+strata start
+strata migrate
+strata run src/scripts/backfill.ts
 ```
 
-Run from your application root (where `src/db/migrations` and environment variables are configured).
+## How it finds your app
+
+From the current working directory, `strata` loads `strata.config.ts` if present, then falls back to conventions:
+
+| Setting | Convention |
+| --- | --- |
+| `preload` | `src/bootstrap/preload.ts` or `src/bootstrap/preloadModules.ts` |
+| `server` | `src/bootstrap/server.ts` |
+| `modulesDirectory` | `src/modules` |
+| `commands` | `src/cli/register.ts` |
+| `migrate` | `src/db/migrate.ts` |
+| `fresh` | `src/db/fresh.ts` |
+
+`src/cli/register.ts` can export `commands` or `registerCommands()` to add app-specific commands such as WorkHub's `make:*`, `queue:work`, and `openapi:*`.
+
+`strata run <file>` executes a file with the app preload. It is not an alias for `bun run <package.json script>`.
+
+## WorkHub
+
+In this monorepo, `bun run cli <command>` is an alias for `strata <command>`.

package/cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runCli } from "./src/runCli.ts";
+
+await runCli();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getstrata/cli",
-  "version": "0.1.0",
-  "description": "Strata CLI — migrate, queue:work, make:* scaffolding",
+  "version": "0.2.0",
+  "description": "Strata CLI — framework commands for Bun apps (dev, start, migrate, run)",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -10,29 +10,26 @@
     "directory": "packages/strata-cli"
   },
   "bin": {
-    "strata": "./dist/cli.js"
+    "strata": "./cli.ts"
   },
   "exports": {
     ".": {
-      "import": "./dist/cli.js",
-      "default": "./dist/cli.js"
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
     }
   },
   "files": [
-    "dist",
+    "cli.ts",
+    "src",
     "README.md"
   ],
   "scripts": {
-    "build": "bun build cli.ts --outdir dist --target bun --external bun --external eta --external @getstrata/core",
+    "build": "bun build cli.ts --outdir dist --target bun --external bun",
     "prepublishOnly": "bun run build"
   },
   "publishConfig": {
     "access": "public"
   },
-  "peerDependencies": {
-    "@getstrata/core": "^0.5.0",
-    "typescript": "^5.9.0"
-  },
   "engines": {
     "bun": ">=1.1.0"
   }

package/src/commands/dev.ts

@@ -0,0 +1,20 @@
+import { spawnBun } from "../spawnBun.ts";
+import type { StrataAppConfig } from "../types.ts";
+
+async function devCommand(app: StrataAppConfig): Promise<void> {
+  if (!app.server) {
+    throw new Error(
+      "No server entry found. Add src/bootstrap/server.ts or set server in strata.config.ts.",
+    );
+  }
+
+  const args = app.preload
+    ? ["--preload", app.preload, "--watch", app.server]
+    : ["--watch", app.server];
+  const code = await spawnBun(app, args);
+  if (code !== 0) {
+    process.exitCode = code;
+  }
+}
+
+export { devCommand };

package/src/commands/help.ts

@@ -0,0 +1,7 @@
+function printHelp(commandNames: string[]): void {
+  const unique = [...new Set(commandNames)].sort();
+  const list = unique.map((name) => `- ${name}`).join("\n");
+  console.log(`Available commands:\n${list}`);
+}
+
+export { printHelp };

package/src/commands/migrate.ts

@@ -0,0 +1,48 @@
+import { pathToFileURL } from "node:url";
+import type { StrataAppConfig } from "../types.ts";
+
+type MigrateModule = {
+  migrate?: (...args: string[]) => Promise<void> | void;
+  seed?: (...args: string[]) => Promise<void> | void;
+  fresh?: (...args: string[]) => Promise<void> | void;
+};
+
+async function importEntry(path: string): Promise<MigrateModule> {
+  return (await import(pathToFileURL(path).href)) as MigrateModule;
+}
+
+async function migrateCommand(app: StrataAppConfig, args: string[]): Promise<void> {
+  if (!app.migrate) {
+    throw new Error(
+      "No migrate entry found. Add src/db/migrate.ts or set migrate in strata.config.ts.",
+    );
+  }
+
+  const entry = await importEntry(app.migrate);
+  if (typeof entry.migrate !== "function") {
+    throw new Error(`${app.migrate} must export a migrate() function.`);
+  }
+
+  await entry.migrate(...args);
+
+  if (typeof entry.seed === "function") {
+    await entry.seed(...args);
+  }
+}
+
+async function migrateFreshCommand(app: StrataAppConfig, args: string[]): Promise<void> {
+  if (app.fresh) {
+    const entry = await importEntry(app.fresh);
+    if (typeof entry.fresh !== "function") {
+      throw new Error(`${app.fresh} must export a fresh() function.`);
+    }
+    await entry.fresh(...args);
+    return;
+  }
+
+  throw new Error(
+    "No migrate:fresh entry found. Add src/db/fresh.ts or register a migrate:fresh command.",
+  );
+}
+
+export { migrateCommand, migrateFreshCommand };

package/src/commands/run.ts

@@ -0,0 +1,19 @@
+import { resolve } from "node:path";
+import { spawnBun } from "../spawnBun.ts";
+import type { StrataAppConfig } from "../types.ts";
+
+async function runCommand(app: StrataAppConfig, args: string[]): Promise<void> {
+  const [file, ...rest] = args;
+  if (!file) {
+    throw new Error("run requires a file path. Example: strata run src/scripts/backfill.ts");
+  }
+
+  const filePath = resolve(app.root, file);
+  const bunArgs = app.preload ? ["--preload", app.preload, filePath, ...rest] : [filePath, ...rest];
+  const code = await spawnBun(app, bunArgs);
+  if (code !== 0) {
+    process.exitCode = code;
+  }
+}
+
+export { runCommand };

package/src/commands/start.ts

@@ -0,0 +1,18 @@
+import { spawnBun } from "../spawnBun.ts";
+import type { StrataAppConfig } from "../types.ts";
+
+async function startCommand(app: StrataAppConfig): Promise<void> {
+  if (!app.server) {
+    throw new Error(
+      "No server entry found. Add src/bootstrap/server.ts or set server in strata.config.ts.",
+    );
+  }
+
+  const args = app.preload ? ["--preload", app.preload, app.server] : [app.server];
+  const code = await spawnBun(app, args);
+  if (code !== 0) {
+    process.exitCode = code;
+  }
+}
+
+export { startCommand };

package/src/index.ts

@@ -0,0 +1,10 @@
+export { loadAppCommands, resolveApp } from "./resolveApp.ts";
+export { runCli } from "./runCli.ts";
+export type {
+  RunCliOptions,
+  StrataAppConfig,
+  StrataCommand,
+  StrataCommandLoader,
+  StrataCommandMap,
+  StrataFileConfig,
+} from "./types.ts";

package/src/resolveApp.ts

@@ -0,0 +1,77 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { StrataAppConfig, StrataCommandMap, StrataFileConfig } from "./types.ts";
+
+function firstExisting(root: string, candidates: string[]): string | undefined {
+  for (const candidate of candidates) {
+    const absolutePath = join(root, candidate);
+    if (existsSync(absolutePath)) {
+      return absolutePath;
+    }
+  }
+
+  return undefined;
+}
+
+function resolvePath(
+  root: string,
+  value: string | undefined,
+  fallbacks: string[],
+): string | undefined {
+  if (value) {
+    return isAbsolute(value) ? value : join(root, value);
+  }
+
+  return firstExisting(root, fallbacks);
+}
+
+async function loadFileConfig(root: string): Promise<StrataFileConfig> {
+  const configPath = firstExisting(root, ["strata.config.ts", "strata.config.js"]);
+  if (!configPath) {
+    return {};
+  }
+
+  const loaded = (await import(pathToFileURL(configPath).href)) as {
+    default?: StrataFileConfig;
+  } & StrataFileConfig;
+
+  return loaded.default ?? loaded;
+}
+
+async function resolveApp(cwd = process.cwd()): Promise<StrataAppConfig> {
+  const root = resolve(cwd);
+  const file = await loadFileConfig(root);
+
+  return {
+    root,
+    preload: resolvePath(root, file.preload, [
+      "src/bootstrap/preload.ts",
+      "src/bootstrap/preloadModules.ts",
+    ]),
+    server: resolvePath(root, file.server, ["src/bootstrap/server.ts"]),
+    modulesDirectory: resolvePath(root, file.modulesDirectory, ["src/modules"]),
+    commandsModule: resolvePath(root, file.commands, ["src/cli/register.ts"]),
+    migrate: resolvePath(root, file.migrate, ["src/db/migrate.ts"]),
+    fresh: resolvePath(root, file.fresh, ["src/db/fresh.ts"]),
+  };
+}
+
+async function loadAppCommands(app: StrataAppConfig): Promise<StrataCommandMap> {
+  if (!app.commandsModule) {
+    return {};
+  }
+
+  const loaded = (await import(pathToFileURL(app.commandsModule).href)) as {
+    commands?: StrataCommandMap;
+    registerCommands?: () => StrataCommandMap | Promise<StrataCommandMap>;
+  };
+
+  if (typeof loaded.registerCommands === "function") {
+    return await loaded.registerCommands();
+  }
+
+  return loaded.commands ?? {};
+}
+
+export { loadAppCommands, resolveApp };

package/src/runCli.ts

@@ -0,0 +1,89 @@
+import { pathToFileURL } from "node:url";
+import { devCommand } from "./commands/dev.ts";
+import { printHelp } from "./commands/help.ts";
+import { migrateCommand, migrateFreshCommand } from "./commands/migrate.ts";
+import { runCommand } from "./commands/run.ts";
+import { startCommand } from "./commands/start.ts";
+import { loadAppCommands, resolveApp } from "./resolveApp.ts";
+import type { RunCliOptions, StrataAppConfig, StrataCommandMap } from "./types.ts";
+
+function builtinCommands(app: StrataAppConfig): StrataCommandMap {
+  const commands: StrataCommandMap = {
+    dev: async () => async () => {
+      await devCommand(app);
+    },
+    start: async () => async () => {
+      await startCommand(app);
+    },
+    run:
+      async () =>
+      async (...args: string[]) => {
+        await runCommand(app, args);
+      },
+  };
+
+  if (app.migrate) {
+    commands.migrate =
+      async () =>
+      async (...args: string[]) => {
+        await migrateCommand(app, args);
+      };
+  }
+
+  if (app.fresh) {
+    commands["migrate:fresh"] =
+      async () =>
+      async (...args: string[]) => {
+        await migrateFreshCommand(app, args);
+      };
+  }
+
+  return commands;
+}
+
+async function runCli(options: RunCliOptions = {}): Promise<number> {
+  const exitProcess = options.exitProcess ?? true;
+  const app = await resolveApp(options.cwd ?? process.cwd());
+
+  if (!options.skipBoot && app.preload) {
+    await import(pathToFileURL(app.preload).href);
+  }
+
+  const appCommands = options.commands ?? (await loadAppCommands(app));
+  const registry: StrataCommandMap = {
+    ...builtinCommands(app),
+    ...appCommands,
+  };
+
+  const commandNames = [...new Set(["help", ...Object.keys(registry)])];
+  registry.help = async () => async () => {
+    printHelp(commandNames);
+  };
+
+  const [command = "help", ...args] = options.argv ?? process.argv.slice(2);
+  const loadHandler = registry[command];
+
+  const fail = (code: number): number => {
+    if (exitProcess) {
+      process.exit(code);
+    }
+    return code;
+  };
+
+  if (!loadHandler) {
+    console.error(`Unknown command: ${command}`);
+    printHelp(commandNames);
+    return fail(1);
+  }
+
+  try {
+    const handler = await loadHandler();
+    await handler(...args);
+    return typeof process.exitCode === "number" ? process.exitCode : 0;
+  } catch (error) {
+    console.error(error);
+    return fail(1);
+  }
+}
+
+export { runCli };

package/src/spawnBun.ts

@@ -0,0 +1,19 @@
+import type { StrataAppConfig } from "./types.ts";
+
+function bunExecutable(): string {
+  return process.execPath.includes("bun") ? process.execPath : "bun";
+}
+
+async function spawnBun(app: StrataAppConfig, bunArgs: string[]): Promise<number> {
+  const proc = Bun.spawn([bunExecutable(), ...bunArgs], {
+    cwd: app.root,
+    stdout: "inherit",
+    stderr: "inherit",
+    stdin: "inherit",
+    env: process.env,
+  });
+
+  return await proc.exited;
+}
+
+export { bunExecutable, spawnBun };

package/src/types.ts

@@ -0,0 +1,39 @@
+type StrataCommand = (...args: string[]) => Promise<void> | void;
+type StrataCommandLoader = () => Promise<StrataCommand>;
+type StrataCommandMap = Record<string, StrataCommandLoader>;
+
+type StrataFileConfig = {
+  preload?: string;
+  server?: string;
+  modulesDirectory?: string;
+  commands?: string;
+  migrate?: string;
+  fresh?: string;
+};
+
+type StrataAppConfig = {
+  root: string;
+  preload?: string;
+  server?: string;
+  modulesDirectory?: string;
+  commandsModule?: string;
+  migrate?: string;
+  fresh?: string;
+};
+
+type RunCliOptions = {
+  argv?: string[];
+  cwd?: string;
+  commands?: StrataCommandMap;
+  skipBoot?: boolean;
+  exitProcess?: boolean;
+};
+
+export type {
+  RunCliOptions,
+  StrataAppConfig,
+  StrataCommand,
+  StrataCommandLoader,
+  StrataCommandMap,
+  StrataFileConfig,
+};