@fuzdev/fuz_app 0.1.0

package/dist/cli/daemon.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Daemon lifecycle management.
+ *
+ * Provides daemon info schema, PID file management, and process lifecycle
+ * operations. Separates lifecycle from presentation — `stop_daemon` returns
+ * a result object instead of logging directly.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { type CommandDeps, type EnvDeps, type FsReadDeps, type FsRemoveDeps, type FsWriteDeps, type LogDeps } from '../runtime/deps.js';
+/**
+ * Daemon info schema for `~/.{name}/run/daemon.json`.
+ */
+export declare const DaemonInfo: z.ZodObject<{
+    /** Schema version. */
+    version: z.ZodNumber;
+    /** Server process ID. */
+    pid: z.ZodNumber;
+    /** Port the server is listening on. */
+    port: z.ZodNumber;
+    /** ISO timestamp when server started. */
+    started: z.ZodString;
+    /** Package version of the application. */
+    app_version: z.ZodString;
+}, z.core.$strict>;
+export type DaemonInfo = z.infer<typeof DaemonInfo>;
+/**
+ * Get the daemon info file path (`~/.{name}/run/daemon.json`).
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param name - application name
+ * @returns path to `daemon.json`, or null if `$HOME` is not set
+ */
+export declare const get_daemon_info_path: (runtime: Pick<EnvDeps, "env_get">, name: string) => string | null;
+/**
+ * Write daemon info to the PID file, creating directories as needed.
+ *
+ * @param runtime - runtime with file write and env capabilities
+ * @param name - application name
+ * @param info - daemon info to write
+ */
+export declare const write_daemon_info: (runtime: Pick<EnvDeps, "env_get"> & FsWriteDeps, name: string, info: DaemonInfo) => Promise<void>;
+/**
+ * Read and validate daemon info from the PID file.
+ *
+ * @param runtime - runtime with file read and env capabilities
+ * @param name - application name
+ * @returns parsed daemon info, or null if missing or invalid
+ */
+export declare const read_daemon_info: (runtime: Pick<EnvDeps, "env_get"> & FsReadDeps & LogDeps, name: string) => Promise<DaemonInfo | null>;
+/**
+ * Check if a process is running by PID.
+ *
+ * @param runtime - runtime with command execution capability
+ * @param pid - process ID to check
+ * @returns `true` if the process is running
+ */
+export declare const is_daemon_running: (runtime: CommandDeps, pid: number) => Promise<boolean>;
+/**
+ * Result of a `stop_daemon` operation.
+ */
+export interface StopDaemonResult {
+    /** Whether a daemon was stopped. */
+    stopped: boolean;
+    /** PID of the stopped daemon, if any. */
+    pid?: number;
+    /** Human-readable message describing the outcome. */
+    message: string;
+}
+/**
+ * Stop a running daemon by sending SIGTERM and cleaning up the PID file.
+ *
+ * Returns a result object instead of logging directly, separating
+ * lifecycle from presentation.
+ *
+ * @param runtime - runtime with command, file, and env capabilities
+ * @param name - application name
+ * @returns result describing the outcome
+ */
+export declare const stop_daemon: (runtime: Pick<EnvDeps, "env_get"> & FsReadDeps & FsRemoveDeps & CommandDeps & LogDeps, name: string) => Promise<StopDaemonResult>;
+//# sourceMappingURL=daemon.d.ts.map

package/dist/cli/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,MAAM,oBAAoB,CAAC;AAI5B;;GAEG;AACH,eAAO,MAAM,UAAU;IACtB,sBAAsB;;IAEtB,yBAAyB;;IAEzB,uCAAuC;;IAEvC,yCAAyC;;IAEzC,0CAA0C;;kBAEzC,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,MAAM,KACV,MAAM,GAAG,IAGX,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,WAAW,EAC/C,MAAM,MAAM,EACZ,MAAM,UAAU,KACd,OAAO,CAAC,IAAI,CAWd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC5B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,UAAU,GAAG,OAAO,EACxD,MAAM,MAAM,KACV,OAAO,CAAC,UAAU,GAAG,IAAI,CAwB3B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAU,SAAS,WAAW,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,OAAO,CAG1F,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GACvB,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,EACrF,MAAM,MAAM,KACV,OAAO,CAAC,gBAAgB,CA2C1B,CAAC"}

package/dist/cli/daemon.js

@@ -0,0 +1,149 @@
+/**
+ * Daemon lifecycle management.
+ *
+ * Provides daemon info schema, PID file management, and process lifecycle
+ * operations. Separates lifecycle from presentation — `stop_daemon` returns
+ * a result object instead of logging directly.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import {} from '../runtime/deps.js';
+import { write_file_atomic } from '../runtime/fs.js';
+import { get_app_dir } from './config.js';
+/**
+ * Daemon info schema for `~/.{name}/run/daemon.json`.
+ */
+export const DaemonInfo = z.strictObject({
+    /** Schema version. */
+    version: z.number(),
+    /** Server process ID. */
+    pid: z.number(),
+    /** Port the server is listening on. */
+    port: z.number(),
+    /** ISO timestamp when server started. */
+    started: z.string(),
+    /** Package version of the application. */
+    app_version: z.string(),
+});
+/**
+ * Get the daemon info file path (`~/.{name}/run/daemon.json`).
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param name - application name
+ * @returns path to `daemon.json`, or null if `$HOME` is not set
+ */
+export const get_daemon_info_path = (runtime, name) => {
+    const app_dir = get_app_dir(runtime, name);
+    return app_dir ? `${app_dir}/run/daemon.json` : null;
+};
+/**
+ * Write daemon info to the PID file, creating directories as needed.
+ *
+ * @param runtime - runtime with file write and env capabilities
+ * @param name - application name
+ * @param info - daemon info to write
+ */
+export const write_daemon_info = async (runtime, name, info) => {
+    const app_dir = get_app_dir(runtime, name);
+    if (!app_dir) {
+        throw new Error('$HOME not set');
+    }
+    const run_dir = `${app_dir}/run`;
+    await runtime.mkdir(run_dir, { recursive: true });
+    const content = JSON.stringify(info, null, '\t');
+    await write_file_atomic(runtime, `${run_dir}/daemon.json`, content + '\n');
+};
+/**
+ * Read and validate daemon info from the PID file.
+ *
+ * @param runtime - runtime with file read and env capabilities
+ * @param name - application name
+ * @returns parsed daemon info, or null if missing or invalid
+ */
+export const read_daemon_info = async (runtime, name) => {
+    const daemon_path = get_daemon_info_path(runtime, name);
+    if (!daemon_path) {
+        return null;
+    }
+    const stat = await runtime.stat(daemon_path);
+    if (!stat) {
+        return null;
+    }
+    try {
+        const content = await runtime.read_file(daemon_path);
+        const parsed = JSON.parse(content);
+        const result = DaemonInfo.safeParse(parsed);
+        if (!result.success) {
+            runtime.warn(`Invalid daemon.json: ${result.error.message}`);
+            return null;
+        }
+        return result.data;
+    }
+    catch {
+        runtime.warn('Failed to parse daemon.json');
+        return null;
+    }
+};
+/**
+ * Check if a process is running by PID.
+ *
+ * @param runtime - runtime with command execution capability
+ * @param pid - process ID to check
+ * @returns `true` if the process is running
+ */
+export const is_daemon_running = async (runtime, pid) => {
+    const result = await runtime.run_command('kill', ['-0', String(pid)]);
+    return result.success;
+};
+/**
+ * Stop a running daemon by sending SIGTERM and cleaning up the PID file.
+ *
+ * Returns a result object instead of logging directly, separating
+ * lifecycle from presentation.
+ *
+ * @param runtime - runtime with command, file, and env capabilities
+ * @param name - application name
+ * @returns result describing the outcome
+ */
+export const stop_daemon = async (runtime, name) => {
+    const daemon_path = get_daemon_info_path(runtime, name);
+    if (!daemon_path) {
+        return { stopped: false, message: '$HOME not set' };
+    }
+    // check if daemon.json exists
+    const stat = await runtime.stat(daemon_path);
+    if (!stat) {
+        return { stopped: false, message: 'No daemon running (no daemon.json found)' };
+    }
+    // read and validate daemon info
+    const info = await read_daemon_info(runtime, name);
+    if (!info) {
+        // corrupt file, clean up
+        try {
+            await runtime.remove(daemon_path);
+        }
+        catch {
+            // already removed
+        }
+        return { stopped: false, message: 'Corrupt daemon.json, removed' };
+    }
+    // send SIGTERM
+    const result = await runtime.run_command('kill', [String(info.pid)]);
+    const stopped = result.success;
+    // clean up daemon.json
+    try {
+        await runtime.remove(daemon_path);
+    }
+    catch {
+        // already removed by daemon's own shutdown handler
+    }
+    if (stopped) {
+        return { stopped: true, pid: info.pid, message: `Stopped daemon (pid ${info.pid})` };
+    }
+    return {
+        stopped: false,
+        pid: info.pid,
+        message: `Process ${info.pid} not running, cleaned up stale daemon.json`,
+    };
+};

package/dist/cli/help.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Schema-driven CLI help generator.
+ *
+ * Generalized from the identical pattern in tx and zzz. Consumers configure
+ * once with `create_help` and get back `generate_main_help`,
+ * `generate_command_help`, and `get_help_text`.
+ *
+ * @module
+ */
+import type { z } from 'zod';
+import { type ZodSchemaProperty } from '@fuzdev/fuz_util/zod.js';
+/**
+ * Command metadata for help generation.
+ */
+export interface CommandMeta<TCategory extends string = string> {
+    schema?: z.ZodType;
+    summary: string;
+    usage: string;
+    category: TCategory;
+}
+/**
+ * Category configuration for help display.
+ */
+export interface HelpCategory<TCategory extends string = string> {
+    key: TCategory;
+    title: string;
+}
+/**
+ * Configuration for `create_help`.
+ */
+export interface HelpOptions<TCategory extends string = string> {
+    /** Application name (e.g., `"tx"`, `"zzz"`). */
+    name: string;
+    /** Application version string. */
+    version: string;
+    /** Short description for the main help header. */
+    description: string;
+    /** Command registry keyed by command path (e.g., `"apply"`, `"daemon start"`). */
+    commands: Record<string, CommandMeta<TCategory>>;
+    /** Category display order for main help. */
+    categories: Array<HelpCategory<TCategory>>;
+    /** Example commands for main help. */
+    examples: Array<string>;
+    /** Zod schema for global arguments (shown in all help output). */
+    global_args_schema: z.ZodType;
+    /** Whether to use ANSI colors in output. Defaults to `true`. */
+    use_colors?: boolean;
+}
+/**
+ * Help generator returned by `create_help`.
+ */
+export interface HelpGenerator {
+    /** Generate main help text with all commands grouped by category. */
+    generate_main_help: () => string;
+    /** Generate help text for a specific command. */
+    generate_command_help: (command: string, meta: CommandMeta) => string;
+    /** Get help text for a command or main help. */
+    get_help_text: (command?: string, subcommand?: string) => string;
+}
+/**
+ * Get maximum length from array.
+ *
+ * @param items - array of items
+ * @param to_string - function to convert item to string for length measurement
+ * @returns maximum string length
+ */
+export declare const to_max_length: <T>(items: Array<T>, to_string: (item: T) => string) => number;
+/**
+ * Format argument name with short aliases for display.
+ *
+ * Only single-char aliases are shown (e.g., `-h, --help`).
+ * Flags use snake_case (e.g., `--env_file`, `--detect_only`).
+ *
+ * @param prop - schema property
+ * @returns formatted name string
+ */
+export declare const format_arg_name: (prop: ZodSchemaProperty) => string;
+/**
+ * Create a help generator configured for an application.
+ *
+ * @param options - help configuration
+ * @returns help generator with `generate_main_help`, `generate_command_help`, and `get_help_text`
+ */
+export declare const create_help: <TCategory extends string>(options: HelpOptions<TCategory>) => HelpGenerator;
+//# sourceMappingURL=help.d.ts.map

package/dist/cli/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAC3B,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,yBAAyB,CAAC;AAIjC;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IAC7D,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IAC9D,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IAC7D,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC;IACjD,4CAA4C;IAC5C,UAAU,EAAE,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3C,sCAAsC;IACtC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,kEAAkE;IAClE,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC;IAC9B,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,MAAM,CAAC;IACjC,iDAAiD;IACjD,qBAAqB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,MAAM,CAAC;IACtE,gDAAgD;IAChD,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CACjE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,KAAG,MACb,CAAC;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,iBAAiB,KAAG,MAWzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,SAAS,MAAM,EACnD,SAAS,WAAW,CAAC,SAAS,CAAC,KAC7B,aAoHF,CAAC"}

package/dist/cli/help.js

@@ -0,0 +1,138 @@
+/**
+ * Schema-driven CLI help generator.
+ *
+ * Generalized from the identical pattern in tx and zzz. Consumers configure
+ * once with `create_help` and get back `generate_main_help`,
+ * `generate_command_help`, and `get_help_text`.
+ *
+ * @module
+ */
+import { zod_to_schema_properties, zod_format_value, } from '@fuzdev/fuz_util/zod.js';
+import { colors } from './util.js';
+/**
+ * Get maximum length from array.
+ *
+ * @param items - array of items
+ * @param to_string - function to convert item to string for length measurement
+ * @returns maximum string length
+ */
+export const to_max_length = (items, to_string) => items.reduce((max, item) => Math.max(to_string(item).length, max), 0);
+/**
+ * Format argument name with short aliases for display.
+ *
+ * Only single-char aliases are shown (e.g., `-h, --help`).
+ * Flags use snake_case (e.g., `--env_file`, `--detect_only`).
+ *
+ * @param prop - schema property
+ * @returns formatted name string
+ */
+export const format_arg_name = (prop) => {
+    if (prop.name === '_') {
+        return '[...args]';
+    }
+    let name = `--${prop.name}`;
+    const short_aliases = prop.aliases.filter((a) => a.length === 1);
+    if (short_aliases.length > 0) {
+        const alias_str = short_aliases.map((a) => `-${a}`).join(', ');
+        name = `${alias_str}, ${name}`;
+    }
+    return name;
+};
+/**
+ * Create a help generator configured for an application.
+ *
+ * @param options - help configuration
+ * @returns help generator with `generate_main_help`, `generate_command_help`, and `get_help_text`
+ */
+export const create_help = (options) => {
+    const use_colors = options.use_colors !== false;
+    const c = use_colors
+        ? colors
+        : { green: '', yellow: '', blue: '', red: '', cyan: '', dim: '', bold: '', reset: '' };
+    const generate_global_options = () => {
+        const properties = zod_to_schema_properties(options.global_args_schema);
+        const max_width = to_max_length(properties, (p) => `  ${format_arg_name(p)}`);
+        return properties.map((prop) => {
+            const name = format_arg_name(prop);
+            const desc = prop.description || '';
+            return `  ${name}`.padEnd(max_width + 2) + desc;
+        });
+    };
+    const generate_command_help = (command, meta) => {
+        const lines = [];
+        lines.push(`${c.cyan}${options.name} ${command}${c.reset}: ${meta.summary}`);
+        lines.push('');
+        lines.push(`${c.yellow}Usage${c.reset}: ${meta.usage}`);
+        lines.push('');
+        if (meta.schema) {
+            const properties = zod_to_schema_properties(meta.schema);
+            const flag_props = properties.filter((p) => p.name !== '_');
+            const positional_prop = properties.find((p) => p.name === '_');
+            if (positional_prop?.description) {
+                lines.push(`Positional: ${positional_prop.description}`);
+                lines.push('');
+            }
+            if (flag_props.length > 0) {
+                lines.push(`${c.yellow}Options${c.reset}:`);
+                const longest_name = to_max_length(flag_props, format_arg_name);
+                const longest_type = to_max_length(flag_props, (p) => p.type);
+                for (const prop of flag_props) {
+                    const name = format_arg_name(prop).padEnd(longest_name);
+                    const type = prop.type.padEnd(longest_type);
+                    const def = zod_format_value(prop.default);
+                    const desc = prop.description || '';
+                    const default_str = def ? ` (default: ${def})` : '';
+                    lines.push(`  ${name}  ${type}  ${desc}${default_str}`);
+                }
+            }
+        }
+        // global options
+        lines.push('');
+        lines.push(`${c.yellow}Global Options${c.reset}:`);
+        for (const opt_line of generate_global_options()) {
+            lines.push(opt_line);
+        }
+        return lines.join('\n');
+    };
+    const generate_main_help = () => {
+        const lines = [];
+        lines.push(`${c.cyan}${options.name}${c.reset} v${options.version} - ${options.description}`);
+        lines.push('');
+        // categories with commands
+        for (const { key, title } of options.categories) {
+            const cat_commands = Object.entries(options.commands).filter(([_, meta]) => meta.category === key);
+            if (cat_commands.length === 0)
+                continue;
+            lines.push(`${c.yellow}${title}${c.reset}:`);
+            cat_commands.sort(([a], [b]) => a.localeCompare(b));
+            const max_usage_width = to_max_length(cat_commands, ([_, meta]) => `  ${meta.usage}`);
+            for (const [_, meta] of cat_commands) {
+                const padded = `  ${meta.usage}`.padEnd(Math.max(max_usage_width + 2, 40));
+                lines.push(`${padded}${meta.summary}`);
+            }
+            lines.push('');
+        }
+        // global options
+        lines.push(`${c.yellow}OPTIONS${c.reset}:`);
+        for (const opt_line of generate_global_options()) {
+            lines.push(opt_line);
+        }
+        lines.push('');
+        // examples
+        if (options.examples.length > 0) {
+            lines.push(`${c.yellow}EXAMPLES${c.reset}:`);
+            for (const example of options.examples) {
+                lines.push(`  ${example}`);
+            }
+        }
+        return lines.join('\n');
+    };
+    const get_help_text = (command, subcommand) => {
+        const cmd_key = subcommand ? `${command} ${subcommand}` : command;
+        if (cmd_key && options.commands[cmd_key]) {
+            return generate_command_help(cmd_key, options.commands[cmd_key]);
+        }
+        return generate_main_help();
+    };
+    return { generate_main_help, generate_command_help, get_help_text };
+};

package/dist/cli/logger.d.ts

@@ -0,0 +1,46 @@
+/**
+ * CLI logger wrapping `Logger` with semantic output methods.
+ *
+ * Why wrapper, not subclass: Logger has variadic `...args` methods, CLI adds
+ * single-string semantic methods. Mixing calling conventions on one class is confusing.
+ * Composition keeps both APIs clean.
+ *
+ * Why Logger prefixes for error/warn: Unifies error/warn visual style across CLI
+ * and backend. CLI-specific methods (success/skip/step/header) add their own semantic
+ * prefixes via `logger.info()`.
+ *
+ * @module
+ */
+import { Logger } from '@fuzdev/fuz_util/log.js';
+export interface CliLogger {
+    /** Logs an error via Logger (gets Logger's error prefix). */
+    error: (...args: Array<unknown>) => void;
+    /** Logs a warning via Logger (gets Logger's warn prefix). */
+    warn: (...args: Array<unknown>) => void;
+    /** Logs info via Logger (gets Logger's label prefix). */
+    info: (...args: Array<unknown>) => void;
+    /** Logs debug via Logger (gets Logger's debug prefix). */
+    debug: (...args: Array<unknown>) => void;
+    /** Logs raw output via Logger (no prefix, no level filtering). */
+    raw: (...args: Array<unknown>) => void;
+    /** Logs a success message with `[done]` prefix at info level. */
+    success: (msg: string) => void;
+    /** Logs a skip message with `[skip]` prefix at info level. */
+    skip: (msg: string) => void;
+    /** Logs a step message with `==>` prefix at info level. */
+    step: (msg: string) => void;
+    /** Logs a header with `=== title ===` decoration at info level. */
+    header: (title: string) => void;
+    /** Logs a dimmed message at info level. */
+    dim: (msg: string) => void;
+    /** The underlying Logger instance. */
+    logger: Logger;
+}
+/**
+ * Creates a CLI logger wrapping a Logger with semantic output methods.
+ *
+ * @param logger - the Logger instance to wrap
+ * @returns a `CliLogger` with CLI semantic methods mapped to Logger levels
+ */
+export declare const create_cli_logger: (logger: Logger) => CliLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/cli/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAK/C,MAAM,WAAW,SAAS;IACzB,6DAA6D;IAC7D,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IACzC,6DAA6D;IAC7D,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IACxC,yDAAyD;IACzD,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IACxC,0DAA0D;IAC1D,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IACzC,kEAAkE;IAClE,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAEvC,iEAAiE;IACjE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,8DAA8D;IAC9D,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,2DAA2D;IAC3D,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,mEAAmE;IACnE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,2CAA2C;IAG3C,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAE3B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG,SA6BjD,CAAC"}

package/dist/cli/logger.js

@@ -0,0 +1,48 @@
+/**
+ * CLI logger wrapping `Logger` with semantic output methods.
+ *
+ * Why wrapper, not subclass: Logger has variadic `...args` methods, CLI adds
+ * single-string semantic methods. Mixing calling conventions on one class is confusing.
+ * Composition keeps both APIs clean.
+ *
+ * Why Logger prefixes for error/warn: Unifies error/warn visual style across CLI
+ * and backend. CLI-specific methods (success/skip/step/header) add their own semantic
+ * prefixes via `logger.info()`.
+ *
+ * @module
+ */
+import { Logger } from '@fuzdev/fuz_util/log.js';
+/**
+ * Creates a CLI logger wrapping a Logger with semantic output methods.
+ *
+ * @param logger - the Logger instance to wrap
+ * @returns a `CliLogger` with CLI semantic methods mapped to Logger levels
+ */
+export const create_cli_logger = (logger) => ({
+    error: (...args) => logger.error(...args),
+    warn: (...args) => logger.warn(...args),
+    info: (...args) => logger.info(...args),
+    debug: (...args) => logger.debug(...args),
+    raw: (...args) => logger.raw(...args),
+    success: (msg) => {
+        const c = logger.colors;
+        logger.info(c ? `\x1b[32m[done]\x1b[0m ${msg}` : `[done] ${msg}`);
+    },
+    skip: (msg) => {
+        const c = logger.colors;
+        logger.info(c ? `\x1b[33m[skip]\x1b[0m ${msg}` : `[skip] ${msg}`);
+    },
+    step: (msg) => {
+        const c = logger.colors;
+        logger.info(c ? `\n\x1b[36m==>\x1b[0m ${msg}` : `\n==> ${msg}`);
+    },
+    header: (title) => {
+        const c = logger.colors;
+        logger.info(c ? `\n\x1b[33m=== ${title} ===\x1b[0m\n` : `\n=== ${title} ===\n`);
+    },
+    dim: (msg) => {
+        const c = logger.colors;
+        logger.info(c ? `\x1b[2m${msg}\x1b[0m` : msg);
+    },
+    logger,
+});

package/dist/cli/util.d.ts

@@ -0,0 +1,36 @@
+/**
+ * CLI utilities for colors, confirmation, and command delegation.
+ *
+ * For structured CLI logging, see `create_cli_logger` in `logger.ts`.
+ *
+ * @module
+ */
+import type { CommandDeps, CommandResult, TerminalDeps } from '../runtime/deps.js';
+export declare const colors: {
+    readonly green: "" | "\u001B[32m";
+    readonly yellow: "" | "\u001B[33m";
+    readonly blue: "" | "\u001B[34m";
+    readonly red: "" | "\u001B[31m";
+    readonly cyan: "" | "\u001B[36m";
+    readonly dim: "" | "\u001B[2m";
+    readonly bold: "" | "\u001B[1m";
+    readonly reset: "" | "\u001B[0m";
+};
+/**
+ * Run a local command and return the result.
+ *
+ * @param runtime - runtime with `run_command` capability
+ * @param command - command to run
+ * @param args - command arguments
+ * @returns command result
+ */
+export declare const run_local: (runtime: CommandDeps, command: string, args: Array<string>) => Promise<CommandResult>;
+/**
+ * Prompt for yes/no confirmation.
+ *
+ * @param runtime - runtime with `stdout_write` and `stdin_read` capabilities
+ * @param message - message to display
+ * @returns `true` if user confirms, `false` otherwise
+ */
+export declare const confirm: (runtime: TerminalDeps, message: string) => Promise<boolean>;
+//# sourceMappingURL=util.d.ts.map

package/dist/cli/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/util.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAE,aAAa,EAAE,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAQjF,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GACrB,SAAS,WAAW,EACpB,SAAS,MAAM,EACf,MAAM,KAAK,CAAC,MAAM,CAAC,KACjB,OAAO,CAAC,aAAa,CAEvB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAU,SAAS,YAAY,EAAE,SAAS,MAAM,KAAG,OAAO,CAAC,OAAO,CAYrF,CAAC"}

package/dist/cli/util.js

@@ -0,0 +1,50 @@
+/**
+ * CLI utilities for colors, confirmation, and command delegation.
+ *
+ * For structured CLI logging, see `create_cli_logger` in `logger.ts`.
+ *
+ * @module
+ */
+// TODO: `colors` duplicates the NO_COLOR detection Logger does internally.
+// Long-term, converge with Logger's color system or expose a shared color helper.
+const no_color = typeof process !== 'undefined' &&
+    (process.env.NO_COLOR !== undefined || process.env.CLAUDECODE !== undefined);
+export const colors = {
+    green: no_color ? '' : '\x1b[32m',
+    yellow: no_color ? '' : '\x1b[33m',
+    blue: no_color ? '' : '\x1b[34m',
+    red: no_color ? '' : '\x1b[31m',
+    cyan: no_color ? '' : '\x1b[36m',
+    dim: no_color ? '' : '\x1b[2m',
+    bold: no_color ? '' : '\x1b[1m',
+    reset: no_color ? '' : '\x1b[0m',
+};
+/**
+ * Run a local command and return the result.
+ *
+ * @param runtime - runtime with `run_command` capability
+ * @param command - command to run
+ * @param args - command arguments
+ * @returns command result
+ */
+export const run_local = async (runtime, command, args) => {
+    return runtime.run_command(command, args);
+};
+/**
+ * Prompt for yes/no confirmation.
+ *
+ * @param runtime - runtime with `stdout_write` and `stdin_read` capabilities
+ * @param message - message to display
+ * @returns `true` if user confirms, `false` otherwise
+ */
+export const confirm = async (runtime, message) => {
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    await runtime.stdout_write(encoder.encode(`${message} [y/N] `));
+    const buf = new Uint8Array(1024);
+    const n = await runtime.stdin_read(buf);
+    if (n === null)
+        return false;
+    const input = decoder.decode(buf.subarray(0, n)).trim().toLowerCase();
+    return input === 'y' || input === 'yes';
+};

package/dist/crypto.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared cryptographic utilities.
+ *
+ * @module
+ */
+/**
+ * Generate a cryptographically random base64url string.
+ *
+ * @param byte_length - number of random bytes (default 32 = 256 bits)
+ * @returns base64url-encoded string without padding
+ */
+export declare const generate_random_base64url: (byte_length?: number) => string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/crypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,oBAAgB,KAAG,MAO5D,CAAC"}