@maroonedsoftware/johnny5 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marooned Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @maroonedsoftware/johnny5
+
+A CLI framework for ServerKit-based applications. Provides:
+
+- **`createCliApp`** — single-call factory that wires a `commander` program from a list of `CommandModule` definitions.
+- **Doctor runner** — built-in `doctor` subcommand backed by a list of `Check` objects, with optional `--fix` auto-remediation.
+- **Plugin discovery** — workspace packages can register additional commands by declaring `"johnny5": { "commands": "./path.js" }` in their `package.json`; collisions with core commands throw at startup.
+- **ServerKit integration** (subpath `/serverkit`) — `bootstrapForCli` runs each `ServerKitModule.setup()` (but not `start()`) and gives commands a scoped InjectKit container via `requireContainer`.
+- **Opt-in check libraries** under subpath exports — `/postgres`, `/redis`, `/docker`, `/versions`, `/filesystem`. Each is a tiny module so non-Postgres (or non-Redis, etc.) consumers don't pull the underlying drivers.
+
+## Install
+
+```bash
+pnpm add @maroonedsoftware/johnny5
+# plus whichever optional peers your CLI needs:
+pnpm add pg ioredis kysely
+```
+
+## Quickstart
+
+```ts
+#!/usr/bin/env node
+import { createCliApp, defineCommand } from '@maroonedsoftware/johnny5';
+import { nodeVersion } from '@maroonedsoftware/johnny5/versions';
+import { postgresReachable } from '@maroonedsoftware/johnny5/postgres';
+
+const hello = defineCommand({
+    description: 'say hello',
+    options: [{ flags: '--name <name>', description: 'who to greet' }],
+    run: async (opts, ctx) => {
+        ctx.logger.success(`hi, ${opts['name'] ?? 'world'}`);
+    },
+});
+
+const app = await createCliApp({
+    name: 'my-cli',
+    description: 'example CLI',
+    version: '0.0.1',
+    commands: [{ path: ['hello'], module: hello }],
+    checks: [nodeVersion({ min: 22 }), postgresReachable()],
+});
+
+process.exit(await app.run(process.argv));
+```
+
+`my-cli doctor` auto-registers because `checks` is non-empty. `my-cli hello --name alice` invokes the registered command. Add `modules: [...]` to enable the ServerKit integration and use `requireContainer` for commands that need DI-resolved services.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import { AppConfig } from '@maroonedsoftware/appconfig';
+import { C as CliContext, D as DiscoveredCommand, a as CommandRegistration, b as Check, c as CliLogger, d as CommandModule } from './types-CH7ccr3j.js';
+export { A as ArgSpec, e as CheckResult, f as CliPaths, g as CreateLoggerOptions, O as OptionSpec, h as OptionType, P as PluginManifest, S as Shell, i as ShellOptions, j as createDefaultLogger, k as createShell } from './types-CH7ccr3j.js';
+import { Command } from 'commander';
+import * as clack from '@clack/prompts';
+import 'execa';
+
+/** Options accepted by `loadWorkspacePlugins`. */
+interface WorkspacePluginOptions {
+    repoRoot: string;
+    /**
+     * Workspace-relative directories whose immediate children are scanned for
+     * `package.json` files. Defaults to `['apps', 'packages']`.
+     */
+    roots?: string[];
+    /**
+     * Package names to skip — typically the consumer's own CLI package whose
+     * commands are loaded directly, not via plugin discovery.
+     */
+    excludePackages?: string[];
+}
+/**
+ * Scan every workspace package in the configured roots for a `"johnny5"` field
+ * in `package.json`. When present, the referenced file is dynamically imported
+ * and expected to default-export a `PluginManifest`. Failures to load a single
+ * plugin log a warning through `ctx.logger.warn` but don't abort the CLI.
+ */
+declare const loadWorkspacePlugins: (ctx: CliContext, options: WorkspacePluginOptions) => Promise<DiscoveredCommand[]>;
+
+interface ServerKitModuleLike<ConfigT> {
+    name?: string;
+    setup?: (registry: unknown, config: ConfigT) => Promise<void>;
+    start?: (container: unknown) => Promise<void>;
+    shutdown?: (container: unknown) => Promise<void>;
+}
+/** Options accepted by `createCliApp`. */
+interface CliAppOptions<ConfigT extends AppConfig = AppConfig> {
+    name: string;
+    description: string;
+    version: string;
+    commands: CommandRegistration[];
+    checks?: Check[];
+    config?: ConfigT | (() => Promise<ConfigT>);
+    logger?: CliLogger;
+    modules?: ServerKitModuleLike<ConfigT>[];
+    plugins?: {
+        workspace?: Omit<WorkspacePluginOptions, 'repoRoot'> & {
+            repoRoot?: string;
+        };
+    };
+    doctorCommandPath?: string[] | null;
+}
+/** The runnable CLI returned by `createCliApp`. */
+interface CliApp {
+    /** Parse `argv` (defaults to `process.argv`) and resolve with a process exit code. */
+    run: (argv?: string[]) => Promise<number>;
+}
+/**
+ * Identity helper that exists purely to give TypeScript a place to infer the
+ * `Opts` generic from the literal passed in. Equivalent to writing the type
+ * annotation manually.
+ */
+declare const defineCommand: <Opts = Record<string, unknown>>(mod: CommandModule<Opts>) => CommandModule<Opts>;
+/**
+ * Build a CLI from a list of `CommandModule` registrations. Auto-registers a
+ * `doctor` subcommand when `checks` is non-empty, discovers workspace plugins
+ * when `plugins.workspace` is configured, and wires up the ServerKit
+ * integration when `modules` is supplied.
+ */
+declare const createCliApp: <ConfigT extends AppConfig = AppConfig>(options: CliAppOptions<ConfigT>) => Promise<CliApp>;
+
+/** Options accepted by `buildContext`. */
+interface BuildContextOptions {
+    config?: AppConfig;
+    logger?: CliLogger;
+    verbose?: boolean;
+    repoRoot?: string;
+    /**
+     * Paths to .env files (absolute, or relative to the resolved repoRoot) to
+     * load into process.env before building AppConfig. Missing files are
+     * silently skipped. Existing process.env values are not overridden.
+     * Defaults to ['.env', 'apps/api/.env'].
+     */
+    envFiles?: string[];
+}
+/**
+ * Build an AppConfig with only the dotenv provider attached. Callers are
+ * expected to have loaded .env files into `process.env` beforehand — see
+ * `buildContext` for the default loading sequence.
+ */
+declare const buildDefaultAppConfig: () => Promise<AppConfig>;
+/**
+ * Build the `CliContext` handed to every command, check, and plugin hook. Loads
+ * `.env` files into `process.env`, resolves the workspace `repoRoot`, and wires
+ * up shell, logger, and config.
+ */
+declare const buildContext: (options?: BuildContextOptions) => Promise<CliContext>;
+
+/** Options passed to `runChecks`. */
+interface DoctorOptions {
+    /** When true, failing checks with an `autoFix` hook get a chance to remediate. */
+    fix?: boolean;
+}
+/**
+ * Run a list of doctor checks sequentially, rendering progress to stdout. Returns
+ * a process exit code: `0` when every check passes (including via `autoFix` when
+ * `--fix` is supplied), `1` when at least one check fails.
+ */
+declare const runChecks: (ctx: CliContext, checks: Check[], options: DoctorOptions) => Promise<number>;
+/**
+ * Build the `CommandModule` for the built-in `doctor` subcommand from a set of
+ * checks. `createCliApp` auto-registers this when `checks` is non-empty.
+ */
+declare const buildDoctorCommand: (checks: Check[]) => CommandModule<{
+    fix?: boolean;
+}>;
+
+/**
+ * Attach every discovered command to a commander `Program`, building intermediate
+ * group nodes as needed. Core registrations are processed before plugin ones, so
+ * a plugin that tries to claim a path already held by core throws with a
+ * descriptive error.
+ */
+declare const registerCommands: (program: Command, discovered: DiscoveredCommand[], ctx: CliContext) => void;
+
+/**
+ * Best-effort guess at whether the CLI is talking to a human. Returns false in
+ * CI (`CI=true` / `CI=1`), when `JOHNNY5_NON_INTERACTIVE=1`, or when either of
+ * stdout/stdin isn't a TTY.
+ */
+declare const isInteractive: () => boolean;
+
+/** Re-export of the `@clack/prompts` namespace under a stable name. */
+declare const prompts: typeof clack;
+/** Thrown by `unwrap` when the user cancels a clack prompt (e.g. Ctrl+C). */
+declare class PromptCancelledError extends Error {
+    constructor();
+}
+/**
+ * Unwrap a clack prompt result, throwing `PromptCancelledError` when the user
+ * cancelled. Lets command handlers use try/catch instead of branching on
+ * `isCancel` at every prompt.
+ */
+declare const unwrap: <T>(value: T | symbol) => T;
+
+export { type BuildContextOptions, Check, type CliApp, type CliAppOptions, CliContext, CliLogger, CommandModule, CommandRegistration, DiscoveredCommand, type DoctorOptions, PromptCancelledError, type WorkspacePluginOptions, buildContext, buildDefaultAppConfig, buildDoctorCommand, createCliApp, defineCommand, isInteractive, loadWorkspacePlugins, prompts, registerCommands, runChecks, unwrap };