@baseworks/cli 0.2.0

package/dist/config-loader.d.ts

@@ -0,0 +1,41 @@
+import { BaseConfig } from './context.js';
+
+/**
+ * Typed helpers for reading standard fields from a BaseConfig.
+ *
+ * Env var names are passed as parameters — this module has no knowledge of
+ * project-specific env vars (DTAB_TOKEN, ORBSEAL_TOKEN, etc.).
+ *
+ * Usage:
+ *   const cfg = ctx.loadConfig();
+ *   const token   = resolveToken(cfg,   { env: 'DTAB_TOKEN' });
+ *   const apiBase = resolveApiBase(cfg, { env: 'DTAB_API_URL', default: 'https://api.driptab.app' });
+ */
+
+interface ResolveOptions {
+    /** Name of the environment variable to fall back to (e.g. 'DTAB_TOKEN'). */
+    env?: string;
+}
+interface ResolveBaseOptions extends ResolveOptions {
+    /** Default value if neither config nor env has a value. */
+    default?: string;
+}
+/**
+ * Read `token` from config, falling back to the named env var.
+ * Returns undefined if neither is set.
+ */
+declare function resolveToken(cfg: BaseConfig, opts?: ResolveOptions): string | undefined;
+/**
+ * Read `apiBase` from config, falling back to the named env var,
+ * then to opts.default. Strips trailing slash.
+ */
+declare function resolveApiBase(cfg: BaseConfig, opts?: ResolveBaseOptions): string;
+/**
+ * Read an arbitrary string field from config by key,
+ * falling back to the named env var.
+ */
+declare function resolveField(cfg: BaseConfig, key: string, opts?: ResolveOptions & {
+    default?: string;
+}): string | undefined;
+
+export { type ResolveBaseOptions, type ResolveOptions, resolveApiBase, resolveField, resolveToken };

package/dist/config-loader.js

@@ -0,0 +1,10 @@
+import {
+  resolveApiBase,
+  resolveField,
+  resolveToken
+} from "./chunk-BEHHVEGL.js";
+export {
+  resolveApiBase,
+  resolveField,
+  resolveToken
+};

package/dist/context.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Generic CLI context manager.
+ *
+ * Read resolution order (first found wins):
+ *   1. {cwd}/.{appName}/config.json   — project-local
+ *   2. {home}/.{appName}/config.json  — global fallback
+ *
+ * Write always targets {cwd}/.{appName}/config.json — so `dtab login`
+ * creates a project-local config wherever you run the command.
+ *
+ * Usage:
+ *   const ctx = createContextManager<DriptabContext>('dtab');
+ *   ctx.setContext({ org: 'acme', project: 'billing' });
+ *   const { org } = ctx.getContext() ?? {};
+ *   console.log(ctx.configPath); // shows which file will be written
+ */
+interface BaseConfig {
+    token?: string;
+    apiBase?: string;
+    [key: string]: unknown;
+}
+interface ContextManager<TContext extends Record<string, string | undefined>> {
+    /** Read the full config file (local first, then global). */
+    loadConfig(): BaseConfig & {
+        context?: TContext;
+    };
+    /** Write the full config file to the active path (local if present, else global). */
+    saveConfig(cfg: BaseConfig & {
+        context?: TContext;
+    }): void;
+    /** Return the stored context, or undefined if none set. */
+    getContext(): TContext | undefined;
+    /** Merge partial context into the stored context and persist. */
+    setContext(parts: Partial<TContext>): void;
+    /** Remove the stored context (keeps token/apiBase). */
+    clearContext(): void;
+    /**
+     * Active config file path — whichever was found (local or global).
+     * Recalculated on each access so it reflects the current working directory.
+     */
+    readonly configPath: string;
+}
+declare function createContextManager<TContext extends Record<string, string | undefined>>(appName: string): ContextManager<TContext>;
+
+export { type BaseConfig, type ContextManager, createContextManager };

package/dist/context.js

@@ -0,0 +1,6 @@
+import {
+  createContextManager
+} from "./chunk-ZD7NOFZL.js";
+export {
+  createContextManager
+};

package/dist/display.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Terminal display primitives. Node.js only — TTY-aware ANSI colours.
+ */
+declare const clr: {
+    reset: string;
+    bold: string;
+    dim: string;
+    green: string;
+    yellow: string;
+    cyan: string;
+    red: string;
+};
+/**
+ * Truncate a UUID or long ID to first `n` chars + `…`.
+ * Short IDs (no dash at pos 8) are returned as-is.
+ */
+declare function truncateId(id: string, n?: number): string;
+/** Colorize a status string for terminal display. */
+declare function statusColor(status: string): string;
+/** Print a dim summary line below a table. */
+declare function summary(text: string): void;
+type OutputFormat = 'table' | 'wide' | 'json' | 'yaml' | 'code';
+interface ColDef<T> {
+    key: keyof T;
+    label: string;
+    fmt?: (value: T[keyof T], row: T) => string;
+    /** If true, column is only shown in -o wide mode. */
+    wide?: boolean;
+    /** @deprecated use wide instead */
+    detail?: boolean;
+}
+interface TableOpts {
+    /**
+     * Message shown when rows is empty. Use a hint to guide the user.
+     * Default: "(none)"
+     */
+    emptyHint?: string;
+}
+declare function table<T extends Record<string, unknown>>(rows: T[], cols: ColDef<T>[], opts?: TableOpts & {
+    wide?: boolean;
+}): void;
+declare function kv(pairs: [string, string][]): void;
+declare function success(msg: string): void;
+declare function warn(msg: string): void;
+declare function fatal(msg: string): never;
+declare function prompt(question: string): Promise<string>;
+/**
+ * Lookup and print subcommand help, return true if help was printed.
+ * Use at the top of each command fn:
+ *
+ *   if (helpFor('account tokens', deps.args, deps.flags, HELP)) return;
+ *
+ * helpMap keys are subcommand paths WITHOUT the top-level command name,
+ * e.g. { 'tokens create': '...', 'tokens list': '...' }
+ */
+declare function helpFor(cmdName: string, args: string[], flags: Record<string, string | boolean>, helpMap: Record<string, string>): boolean;
+/**
+ * @deprecated Use printOutput instead.
+ * Kept for backward compatibility with legacy CliPlugin commands.
+ */
+declare function printOrJson<T>(data: T, textFn: () => void, argv?: string[]): void;
+/**
+ * Universal output formatter for Commander-based commands.
+ *
+ * @param data      Raw data to output (array or object)
+ * @param format    Output format from -o/--output option
+ * @param renderFn  Called for table/wide; receives wide=true for -o wide
+ * @param codeKey   Key (or fn) used for -o code output. Falls back to short_id → id.
+ *
+ * Usage:
+ *   printOutput(plans, opts.output, (wide) => table(plans, cols, { wide }), 'code');
+ */
+declare function printOutput<T extends Record<string, unknown>>(data: T | T[], format: string | undefined, renderFn: (wide: boolean) => void, codeKey?: string | ((item: T) => string)): void;
+/**
+ * Returns the Commander output option definition string.
+ * Use with .addOption() or .option():
+ *
+ *   cmd.option(...outputOption())
+ */
+declare function outputOption(): [string, string, string];
+
+export { type ColDef, type OutputFormat, type TableOpts, clr, fatal, helpFor, kv, outputOption, printOrJson, printOutput, prompt, statusColor, success, summary, table, truncateId, warn };

package/dist/display.js

@@ -0,0 +1,32 @@
+import {
+  clr,
+  fatal,
+  helpFor,
+  kv,
+  outputOption,
+  printOrJson,
+  printOutput,
+  prompt,
+  statusColor,
+  success,
+  summary,
+  table,
+  truncateId,
+  warn
+} from "./chunk-C2YZKMJ7.js";
+export {
+  clr,
+  fatal,
+  helpFor,
+  kv,
+  outputOption,
+  printOrJson,
+  printOutput,
+  prompt,
+  statusColor,
+  success,
+  summary,
+  table,
+  truncateId,
+  warn
+};

package/dist/fmt.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Display formatters for common field types.
+ * All return ANSI-colored strings safe to pass to table/kv.
+ */
+/**
+ * Format a date value for terminal display.
+ * Accepts:
+ *   - Unix ms timestamp (number)
+ *   - ISO 8601 string
+ *   - null / undefined → "—"
+ */
+declare function fmtDate(val: string | number | null | undefined): string;
+declare function fmtRole(role: string | null | undefined): string;
+declare function fmtStatus(revokedAt: string | null | undefined): string;
+declare function fmtBool(val: boolean | number | null | undefined): string;
+declare function fmtCount(n: number | null | undefined): string;
+declare function fmtId(id: string | null | undefined): string;
+
+export { fmtBool, fmtCount, fmtDate, fmtId, fmtRole, fmtStatus };

package/dist/fmt.js

@@ -0,0 +1,17 @@
+import {
+  fmtBool,
+  fmtCount,
+  fmtDate,
+  fmtId,
+  fmtRole,
+  fmtStatus
+} from "./chunk-HJFKWDPX.js";
+import "./chunk-C2YZKMJ7.js";
+export {
+  fmtBool,
+  fmtCount,
+  fmtDate,
+  fmtId,
+  fmtRole,
+  fmtStatus
+};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { ColDef, OutputFormat, TableOpts, clr, fatal, kv, outputOption, printOrJson, printOutput, prompt, success, table, warn } from './display.js';
+export { fmtBool, fmtCount, fmtDate, fmtId, fmtRole, fmtStatus } from './fmt.js';
+export { TreeNode, tree } from './tree.js';
+export { ParsedArgs, getFlag, isJsonMode, parseFlags } from './args.js';
+export { BaseConfig, ContextManager, createContextManager } from './context.js';
+export { ResolveBaseOptions, ResolveOptions, resolveApiBase, resolveField, resolveToken } from './config-loader.js';
+export { ApiClient, ApiError, createApiClient } from './client.js';
+export { CliRunner, CliRunnerConfig, createCliRunner } from './runner.js';
+export { CliCommand, CliHooks, CliMiddlewareFn, CliPlugin, CommandDeps } from './plugin.js';
+export { confirmDestructive, requiresContext, requiresToken } from './middleware.js';

package/dist/index.js

@@ -0,0 +1,78 @@
+import {
+  createCliRunner
+} from "./chunk-LQJTQ52B.js";
+import {
+  confirmDestructive,
+  requiresContext,
+  requiresToken
+} from "./chunk-TSVJD4R6.js";
+import {
+  fmtBool,
+  fmtCount,
+  fmtDate,
+  fmtId,
+  fmtRole,
+  fmtStatus
+} from "./chunk-HJFKWDPX.js";
+import {
+  getFlag,
+  isJsonMode,
+  parseFlags
+} from "./chunk-H4M2NPA2.js";
+import {
+  createContextManager
+} from "./chunk-ZD7NOFZL.js";
+import {
+  resolveApiBase,
+  resolveField,
+  resolveToken
+} from "./chunk-BEHHVEGL.js";
+import {
+  tree
+} from "./chunk-5U3CFW6F.js";
+import {
+  clr,
+  fatal,
+  kv,
+  outputOption,
+  printOrJson,
+  printOutput,
+  prompt,
+  success,
+  table,
+  warn
+} from "./chunk-C2YZKMJ7.js";
+import {
+  createApiClient
+} from "./chunk-XQGLG3X3.js";
+export {
+  clr,
+  confirmDestructive,
+  createApiClient,
+  createCliRunner,
+  createContextManager,
+  fatal,
+  fmtBool,
+  fmtCount,
+  fmtDate,
+  fmtId,
+  fmtRole,
+  fmtStatus,
+  getFlag,
+  isJsonMode,
+  kv,
+  outputOption,
+  parseFlags,
+  printOrJson,
+  printOutput,
+  prompt,
+  requiresContext,
+  requiresToken,
+  resolveApiBase,
+  resolveField,
+  resolveToken,
+  success,
+  table,
+  tree,
+  warn
+};

package/dist/middleware.d.ts

@@ -0,0 +1,37 @@
+import { CliMiddlewareFn } from './plugin.js';
+import './client.js';
+import './context.js';
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare function requiresToken(): CliMiddlewareFn;
+/**
+ * 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.
+ */
+declare function requiresContext(): CliMiddlewareFn;
+/**
+ * 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.
+ */
+declare function confirmDestructive(message: string): CliMiddlewareFn;
+
+export { confirmDestructive, requiresContext, requiresToken };

package/dist/middleware.js

@@ -0,0 +1,11 @@
+import {
+  confirmDestructive,
+  requiresContext,
+  requiresToken
+} from "./chunk-TSVJD4R6.js";
+import "./chunk-C2YZKMJ7.js";
+export {
+  confirmDestructive,
+  requiresContext,
+  requiresToken
+};

package/dist/plugin.d.ts

@@ -0,0 +1,99 @@
+import { ApiClient } from './client.js';
+import { ContextManager } from './context.js';
+
+/**
+ * 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
+ */
+
+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>;
+}
+/**
+ * A middleware function. Call next() to continue the chain.
+ * Throw (or call fatal()) to abort.
+ */
+type CliMiddlewareFn = (deps: CommandDeps, next: () => Promise<void>) => Promise<void>;
+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[];
+}
+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>;
+}
+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;
+}
+
+export type { CliCommand, CliHooks, CliMiddlewareFn, CliPlugin, CommandDeps };

package/dist/runner.d.ts

@@ -0,0 +1,53 @@
+import { ContextManager } from './context.js';
+import { CliPlugin, CliHooks } from './plugin.js';
+import './client.js';
+
+/**
+ * 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));
+ */
+
+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;
+}
+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>;
+}
+declare function createCliRunner(config: CliRunnerConfig): CliRunner;
+
+export { type CliRunner, type CliRunnerConfig, createCliRunner };

package/dist/runner.js

@@ -0,0 +1,10 @@
+import {
+  createCliRunner
+} from "./chunk-LQJTQ52B.js";
+import "./chunk-TSVJD4R6.js";
+import "./chunk-H4M2NPA2.js";
+import "./chunk-C2YZKMJ7.js";
+import "./chunk-XQGLG3X3.js";
+export {
+  createCliRunner
+};

package/dist/tree.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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' },
+ *           ],
+ *         },
+ *       ],
+ *     },
+ *   ]);
+ */
+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[];
+}
+declare function tree(nodes: TreeNode[], prefix?: string): void;
+
+export { type TreeNode, tree };

package/dist/tree.js

@@ -0,0 +1,7 @@
+import {
+  tree
+} from "./chunk-5U3CFW6F.js";
+import "./chunk-C2YZKMJ7.js";
+export {
+  tree
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@baseworks/cli",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./display": "./dist/display.js",
+    "./fmt": "./dist/fmt.js",
+    "./args": "./dist/args.js",
+    "./context": "./dist/context.js",
+    "./config-loader": "./dist/config-loader.js",
+    "./tree": "./dist/tree.js",
+    "./client": "./dist/client.js",
+    "./runner": "./dist/runner.js",
+    "./middleware": "./dist/middleware.js",
+    "./plugin": "./dist/plugin.js",
+    "./testing": "./src/testing.ts"
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@baseworks/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@baseworks/tsconfig": "workspace:*",
+    "@types/node": "^25.9.1",
+    "msw": "^2.14.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.0"
+  }
+}