@baseworks/cli 0.2.0

package/src/index.ts

@@ -0,0 +1,34 @@
+// @baseworks/cli — shared CLI primitives for Node.js CLIs.
+
+// Display
+export { clr, table, kv, success, warn, fatal, prompt, printOrJson, printOutput, outputOption } from './display.js';
+export type { ColDef, OutputFormat, TableOpts } from './display.js';
+
+// Format helpers
+export { fmtDate, fmtRole, fmtStatus, fmtBool, fmtCount, fmtId } from './fmt.js';
+
+// Tree display
+export { tree } from './tree.js';
+export type { TreeNode } from './tree.js';
+
+// Arg / flag parsing
+export { parseFlags, isJsonMode, getFlag } from './args.js';
+export type { ParsedArgs } from './args.js';
+
+// Context manager
+export { createContextManager } from './context.js';
+export type { ContextManager, BaseConfig } from './context.js';
+
+// Config field resolvers (env var names are project-specific — pass as params)
+export { resolveToken, resolveApiBase, resolveField } from './config-loader.js';
+export type { ResolveOptions, ResolveBaseOptions } from './config-loader.js';
+
+// HTTP client
+export { createApiClient } from './client.js';
+export type { ApiClient, ApiError } from './client.js';
+
+// Plugin system
+export { createCliRunner } from './runner.js';
+export type { CliRunner, CliRunnerConfig } from './runner.js';
+export type { CliPlugin, CliCommand, CliMiddlewareFn, CommandDeps, CliHooks } from './plugin.js';
+export { requiresToken, requiresContext, confirmDestructive } from './middleware.js';

package/src/middleware.ts

@@ -0,0 +1,80 @@
+/**
+ * Built-in CLI middleware.
+ *
+ * Each function returns a CliMiddlewareFn — pass the result to
+ * CliCommand.middleware[], or let the runner apply it via the
+ * requiresToken / requiresContext / confirm shorthand properties.
+ */
+
+import { fatal, prompt, warn } from './display.js';
+import type { CliMiddlewareFn } from './plugin.js';
+
+// ─── requiresToken ────────────────────────────────────────────────────────────
+
+/**
+ * Ensures deps.token is set before the command runs.
+ * The runner pre-populates deps.token from getToken(); this middleware
+ * just guards and gives a clear error message if it's missing.
+ *
+ * Applied automatically when CliCommand.requiresToken !== false.
+ */
+export function requiresToken(): CliMiddlewareFn {
+  return async (deps, next) => {
+    if (!deps.token) {
+      fatal('No API token found. Run: login');
+    }
+    await next();
+  };
+}
+
+// ─── requiresContext ──────────────────────────────────────────────────────────
+
+/**
+ * Ensures an active org/project context is set before the command runs.
+ * Sets deps.context to the result of ctx.getContext().
+ *
+ * Applied automatically when CliCommand.requiresContext === true.
+ */
+export function requiresContext(): CliMiddlewareFn {
+  return async (deps, next) => {
+    const ctx = deps.ctx.getContext();
+    if (!ctx) {
+      fatal('No active context. Set one with: use <org>');
+    }
+    deps.context = ctx;
+    await next();
+  };
+}
+
+// ─── confirmDestructive ───────────────────────────────────────────────────────
+
+/**
+ * Prompts the user with a y/N confirmation before continuing.
+ * In non-TTY / CI environments (stdin not interactive), auto-aborts
+ * unless the --yes / -y flag is present.
+ *
+ * Applied automatically when CliCommand.confirm is set.
+ */
+export function confirmDestructive(message: string): CliMiddlewareFn {
+  return async (deps, next) => {
+    // --yes / -y bypasses the prompt (CI-friendly)
+    if (deps.flags['yes'] || deps.flags['y']) {
+      await next();
+      return;
+    }
+
+    const isTTY = Boolean(process.stdin.isTTY);
+    if (!isTTY) {
+      fatal(`Destructive operation requires confirmation. Re-run with --yes to proceed.\n  ${message}`);
+    }
+
+    warn(message);
+    const answer = await prompt('Continue? (y/N) ');
+    if (answer.toLowerCase() !== 'y') {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+
+    await next();
+  };
+}

package/src/plugin.ts

@@ -0,0 +1,120 @@
+/**
+ * CLI plugin system — types.
+ *
+ * A CliPlugin groups related commands. Each command declares its middleware
+ * requirements declaratively; the runner builds and executes the chain.
+ *
+ *   argv → [requiresToken] → [requiresContext] → [confirmDestructive] → [custom…] → fn
+ */
+
+import type { ApiClient }      from './client.js';
+import type { ContextManager } from './context.js';
+
+// ─── Deps — shared context passed through every middleware and command ─────────
+
+export interface CommandDeps {
+  /** Full argv slice (after command name). */
+  argv:    string[];
+  /** Positional args (non-flag). */
+  args:    string[];
+  /** Parsed flags. */
+  flags:   Record<string, string | boolean>;
+  /** Authenticated HTTP client. */
+  http:    ApiClient;
+  /** Config / context manager for this app. */
+  ctx:     ContextManager<Record<string, string | undefined>>;
+  /** Frontend app URL (for browser-based flows like login). */
+  appBase: string;
+  /**
+   * Set by requiresToken middleware.
+   * Guaranteed non-null inside commands that declare requiresToken (default).
+   */
+  token?:  string;
+  /**
+   * Set by requiresContext middleware.
+   * Guaranteed non-null inside commands that declare requiresContext: true.
+   */
+  context?: Record<string, string | undefined>;
+}
+
+// ─── Middleware ───────────────────────────────────────────────────────────────
+
+/**
+ * A middleware function. Call next() to continue the chain.
+ * Throw (or call fatal()) to abort.
+ */
+export type CliMiddlewareFn = (
+  deps: CommandDeps,
+  next: () => Promise<void>,
+) => Promise<void>;
+
+// ─── Command ─────────────────────────────────────────────────────────────────
+
+export interface CliCommand {
+  /** The command handler — runs after all middleware. */
+  fn: (deps: CommandDeps) => Promise<void> | void;
+
+  /**
+   * Ensure a token is present before running.
+   * Default: true.  Set to false for commands like `login` or `help`.
+   */
+  requiresToken?: boolean;
+
+  /**
+   * Ensure org/project context is set (ctx.getContext() non-null).
+   * Default: false.
+   */
+  requiresContext?: boolean;
+
+  /**
+   * Show a "are you sure?" confirmation prompt before running.
+   * Supply the message to display. No prompt if undefined.
+   */
+  confirm?: string;
+
+  /**
+   * Additional middleware to run after the built-in guards,
+   * in declaration order, before fn.
+   */
+  middleware?: CliMiddlewareFn[];
+}
+
+// ─── Plugin ───────────────────────────────────────────────────────────────────
+
+export interface CliPlugin {
+  /** Map of command name → CliCommand. */
+  commands:  Record<string, CliCommand>;
+  /** Short aliases → canonical command name. */
+  aliases?:  Record<string, string>;
+  /** Help text section contributed by this plugin (shown by dtab --help). */
+  helpText?: string;
+  /**
+   * Per-subcommand help strings, shown when --help appears after a subcommand.
+   * Key format: "command sub"  e.g. "account tokens create"
+   * The runner prints this when deps.flags['help'] is true.
+   */
+  subHelp?:  Record<string, string>;
+}
+
+// ─── Hooks ────────────────────────────────────────────────────────────────────
+
+export interface CliHooks {
+  /**
+   * Fires before the middleware chain + command fn.
+   * Useful for telemetry, logging, debug output.
+   */
+  beforeCommand?: (name: string, deps: CommandDeps) => Promise<void> | void;
+
+  /**
+   * Fires after successful command completion.
+   * durationMs = wall-clock time including middleware.
+   */
+  afterCommand?: (name: string, deps: CommandDeps, durationMs: number) => Promise<void> | void;
+
+  /**
+   * Fires when any unhandled error escapes the command fn or its middleware.
+   * If you handle the error here, do NOT re-throw — the runner will not fatal().
+   * If you don't register this hook, the runner calls fatal(err.message).
+   */
+  onError?: (name: string, error: Error, deps: CommandDeps) => Promise<void> | void;
+}

package/src/runner.ts

@@ -0,0 +1,164 @@
+/**
+ * CLI runner — plugin registration, middleware chain execution, lifecycle hooks.
+ *
+ * Usage:
+ *   const runner = createCliRunner({
+ *     ctx,
+ *     appBase:    'https://myapp.com',
+ *     getToken:   () => resolveToken(ctx.loadConfig(), { env: 'MY_TOKEN' }),
+ *     getApiBase: () => resolveApiBase(ctx.loadConfig(), { env: 'MY_API_URL', default: 'https://api.myapp.com' }),
+ *   });
+ *
+ *   runner.register(accountCliPlugin({ ... }));
+ *   runner.register(orgCliPlugin());
+ *   runner.register(myAppPlugin);
+ *
+ *   runner.hooks({
+ *     onError: (name, err) => { ... },  // optional telemetry
+ *   });
+ *
+ *   await runner.run(process.argv.slice(2));
+ */
+
+import { parseFlags }     from './args.js';
+import { createApiClient } from './client.js';
+import { fatal }           from './display.js';
+import { requiresToken as requiresTokenMw, requiresContext as requiresContextMw, confirmDestructive } from './middleware.js';
+import type { ContextManager }                from './context.js';
+import type { CliPlugin, CliCommand, CliHooks, CommandDeps, CliMiddlewareFn } from './plugin.js';
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+export interface CliRunnerConfig {
+  /** Context manager for this application. */
+  ctx:        ContextManager<Record<string, string | undefined>>;
+  /** Frontend app base URL — used by browser-based flows (e.g. login). */
+  appBase:    string;
+  /**
+   * Returns the active API token, or undefined if not set.
+   * Called fresh on every request so config changes are picked up immediately.
+   */
+  getToken:   () => string | undefined;
+  /**
+   * Returns the API base URL.
+   * Called fresh on every request.
+   */
+  getApiBase: () => string;
+}
+
+// ─── Runner ───────────────────────────────────────────────────────────────────
+
+export interface CliRunner {
+  /** Register a plugin — merges its commands and aliases. */
+  register(plugin: CliPlugin): void;
+  /** Register lifecycle hooks (additive — multiple calls merge). */
+  hooks(h: Partial<CliHooks>): void;
+  /** Execute the CLI with the given argv (typically process.argv.slice(2)). */
+  run(argv: string[]): Promise<void>;
+}
+
+export function createCliRunner(config: CliRunnerConfig): CliRunner {
+  const allCommands: Record<string, CliCommand> = {};
+  const allAliases:  Record<string, string>     = {};
+  const helpSections: string[]                  = [];
+  let   activeHooks: Partial<CliHooks>          = {};
+
+  return {
+    register(plugin: CliPlugin) {
+      for (const [name, cmd] of Object.entries(plugin.commands)) {
+        allCommands[name] = cmd;
+      }
+      for (const [alias, target] of Object.entries(plugin.aliases ?? {})) {
+        allAliases[alias] = target;
+      }
+      if (plugin.helpText) helpSections.push(plugin.helpText);
+    },
+
+    hooks(h: Partial<CliHooks>) {
+      activeHooks = { ...activeHooks, ...h };
+    },
+
+    async run(argv: string[]) {
+      const { args: topArgs, flags: topFlags } = parseFlags(argv);
+
+      // Version / help short-circuits
+      if (topFlags['version'] || topFlags['v']) {
+        // Version is app-specific — let the command handle it, or noop here.
+        return;
+      }
+
+      const rawCmd = topArgs[0];
+      // Show global help only when: no command given, OR --help is the very first token
+      // (e.g. `dtab --help`).  When --help appears AFTER a command token
+      // (e.g. `dtab account tokens create --help`) pass it through to the command fn.
+      const globalHelp = !rawCmd || argv[0] === '--help' || argv[0] === '-h';
+      if (globalHelp) {
+        console.log(helpSections.join('\n'));
+        return;
+      }
+
+      const cmdName = allAliases[rawCmd] ?? rawCmd;
+      const cmd     = allCommands[cmdName];
+      if (!cmd) {
+        fatal(`Unknown command: ${rawCmd}. Run with --help for usage.`);
+      }
+
+      // Slice argv to get everything after the command name token
+      const rawIdx  = argv.indexOf(rawCmd);
+      const restArgv = argv.slice(rawIdx + 1);
+      const { args, flags } = parseFlags(restArgv);
+
+      // Build deps — token pre-populated so requiresToken middleware can guard
+      const deps: CommandDeps = {
+        argv:    restArgv,
+        args,
+        flags,
+        http:    createApiClient(config.getToken, config.getApiBase),
+        ctx:     config.ctx,
+        appBase: config.appBase,
+        token:   config.getToken(),
+      };
+
+      // Lifecycle: beforeCommand
+      await activeHooks.beforeCommand?.(cmdName, deps);
+      const t0 = Date.now();
+
+      try {
+        await executeCommand(cmd, deps);
+        await activeHooks.afterCommand?.(cmdName, deps, Date.now() - t0);
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        if (activeHooks.onError) {
+          await activeHooks.onError(cmdName, err, deps);
+        } else {
+          fatal(err.message);
+        }
+      }
+    },
+  };
+}
+
+// ─── Chain execution ─────────────────────────────────────────────────────────
+
+async function executeCommand(cmd: CliCommand, deps: CommandDeps): Promise<void> {
+  const chain: CliMiddlewareFn[] = [];
+
+  // Built-in guards from shorthand properties
+  if (cmd.requiresToken !== false) chain.push(requiresTokenMw());
+  if (cmd.requiresContext)         chain.push(requiresContextMw());
+  if (cmd.confirm)                 chain.push(confirmDestructive(cmd.confirm));
+
+  // Custom middleware declared on the command
+  if (cmd.middleware?.length) chain.push(...cmd.middleware);
+
+  // Execute chain then fn
+  let i = 0;
+  const next = async (): Promise<void> => {
+    if (i < chain.length) {
+      await chain[i++]!(deps, next);
+    } else {
+      await cmd.fn(deps);
+    }
+  };
+  await next();
+}

package/src/testing.ts

@@ -0,0 +1,125 @@
+/**
+ * @baseworks/cli/testing
+ *
+ * Shared test utilities for CLI packages.
+ * Import in test files only — do not use in production code.
+ *
+ * Usage:
+ *   import { runCommand, mockGet, mockPost, server } from '@baseworks/cli/testing'
+ */
+
+import { Command } from 'commander'
+
+// ─── runCommand ───────────────────────────────────────────────────────────────
+
+export interface RunResult {
+  stdout:   string
+  stderr:   string
+  exitCode: number
+}
+
+/**
+ * Runs a Commander program in-process, capturing stdout/stderr.
+ * Prevents process.exit from actually exiting.
+ *
+ * @param program - A Commander Command (root program)
+ * @param args    - User args, e.g. ['org', 'create', '--name', 'Foo']
+ */
+export async function runCommand(program: Command, args: string[]): Promise<RunResult> {
+  const stdoutChunks: string[] = []
+  const stderrChunks: string[] = []
+
+  const origWrite = process.stdout.write.bind(process.stdout)
+  const origErr   = process.stderr.write.bind(process.stderr)
+  const origLog   = console.log
+  const origError = console.error
+  const origExit  = process.exit.bind(process)
+
+  let exitCode = 0
+
+  process.stdout.write = ((c: unknown) => { stdoutChunks.push(String(c)); return true }) as typeof process.stdout.write
+  process.stderr.write = ((c: unknown) => { stderrChunks.push(String(c)); return true }) as typeof process.stderr.write
+  console.log   = (...a: unknown[]) => stdoutChunks.push(a.join(' ') + '\n')
+  console.error = (...a: unknown[]) => stderrChunks.push(a.join(' ') + '\n')
+  ;(process as NodeJS.Process & { exit: (c?: number) => never }).exit = (code?: number) => {
+    exitCode = code ?? 0
+    throw new Error(`__exit__${code ?? 0}`)
+  }
+
+  try {
+    await program.parseAsync(args, { from: 'user' })
+  } catch (err) {
+    if (err instanceof Error && !err.message.startsWith('__exit__')) {
+      if ((err as NodeJS.ErrnoException).code?.startsWith('commander.')) {
+        exitCode = 0
+      } else {
+        stderrChunks.push(err.message + '\n')
+        exitCode = exitCode || 1
+      }
+    }
+  } finally {
+    process.stdout.write = origWrite
+    process.stderr.write = origErr
+    console.log   = origLog
+    console.error = origError
+    ;(process as NodeJS.Process & { exit: (c?: number) => never }).exit = origExit
+  }
+
+  return { stdout: stdoutChunks.join(''), stderr: stderrChunks.join(''), exitCode }
+}
+
+// ─── MSW mock helpers ─────────────────────────────────────────────────────────
+
+import { http, HttpResponse, type HttpHandler } from 'msw'
+import { setupServer }                           from 'msw/node'
+
+export { http, HttpResponse }
+
+export const server = setupServer()
+
+/**
+ * Create mock helpers bound to a specific base URL.
+ * Usage:
+ *   const { mockGet, mockPost, ... } = createMocks('http://flect.test')
+ */
+export function createMocks(base: string) {
+  return {
+    mockGet(path: string, body: unknown, status = 200) {
+      server.use(http.get(`${base}${path}`, () => HttpResponse.json(body, { status })))
+    },
+
+    mockPost(path: string, body: unknown, status = 201) {
+      server.use(http.post(`${base}${path}`, () => HttpResponse.json(body, { status })))
+    },
+
+    mockPatch(path: string, body: unknown, status = 200) {
+      server.use(http.patch(`${base}${path}`, () => HttpResponse.json(body, { status })))
+    },
+
+    mockDelete(path: string, status = 204) {
+      server.use(http.delete(`${base}${path}`, () => new HttpResponse(null, { status })))
+    },
+
+    mockPostCapture(path: string, responseBody: unknown, status = 201) {
+      const captured: { body?: unknown } = {}
+      server.use(http.post(`${base}${path}`, async ({ request }) => {
+        captured.body = await request.json()
+        return HttpResponse.json(responseBody, { status })
+      }))
+      return captured
+    },
+
+    mockPatchCapture(path: string, responseBody: unknown, status = 200) {
+      const captured: { body?: unknown } = {}
+      server.use(http.patch(`${base}${path}`, async ({ request }) => {
+        captured.body = await request.json()
+        return HttpResponse.json(responseBody, { status })
+      }))
+      return captured
+    },
+
+    use(...handlers: HttpHandler[]) {
+      server.use(...handlers)
+    },
+  }
+}

package/src/tree.ts

@@ -0,0 +1,55 @@
+/**
+ * Hierarchical tree display for CLI output.
+ *
+ * Usage:
+ *   tree([
+ *     {
+ *       label: 'taskflow', badge: '●', meta: 'org',
+ *       children: [
+ *         {
+ *           label: 'platform', meta: 'workspace',
+ *           children: [
+ *             { label: 'taskflow', badge: '🌿', meta: 'project · production, staging' },
+ *           ],
+ *         },
+ *       ],
+ *     },
+ *   ]);
+ */
+
+import { clr } from './display.js';
+
+export interface TreeNode {
+  /** Primary label — printed bold. */
+  label:     string;
+  /** Optional badge/icon before the label. */
+  badge?:    string;
+  /** Dimmed metadata shown after the label. */
+  meta?:     string;
+  /** Child nodes. */
+  children?: TreeNode[];
+}
+
+export function tree(nodes: TreeNode[], prefix = ''): void {
+  for (let i = 0; i < nodes.length; i++) {
+    const node      = nodes[i]!;
+    const last      = i === nodes.length - 1;
+    const isRoot    = prefix === '';
+    const connector = isRoot ? '' : (last ? '└── ' : '├── ');
+    // Root nodes use '    '/'│   ' as childPfx so children are always indented
+    const childPfx  = isRoot
+      ? (last ? '    ' : '│   ')
+      : prefix + (last ? '    ' : '│   ');
+
+    const badge = node.badge ? node.badge + ' ' : '';
+    const meta  = node.meta  ? `  ${clr.dim}${node.meta}${clr.reset}` : '';
+
+    console.log(
+      `${clr.dim}${prefix}${connector}${clr.reset}${badge}${clr.bold}${node.label}${clr.reset}${meta}`,
+    );
+
+    if (node.children?.length) {
+      tree(node.children, childPfx);
+    }
+  }
+}