@fuzdev/fuz_app 0.1.0

package/dist/auth/session_queries.js

@@ -0,0 +1,186 @@
+/**
+ * Auth session database queries.
+ *
+ * Server-side sessions keyed by blake3 hash of the session token.
+ * The cookie contains the raw token; the database stores only the hash.
+ *
+ * @module
+ */
+import { hash_blake3 } from '@fuzdev/fuz_util/hash_blake3.js';
+import { generate_random_base64url } from '../crypto.js';
+/** Session lifetime in milliseconds (30 days). */
+export const AUTH_SESSION_LIFETIME_MS = 30 * 24 * 60 * 60 * 1000;
+/** Extend session when it has less than this remaining (1 day in ms). */
+export const AUTH_SESSION_EXTEND_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+/**
+ * Hash a session token to its storage key using blake3.
+ *
+ * @param token - the raw session token
+ * @returns hex-encoded blake3 hash
+ */
+export const hash_session_token = (token) => {
+    return hash_blake3(token);
+};
+/**
+ * Generate a cryptographically random session token.
+ *
+ * @returns a 32-byte base64url-encoded token
+ */
+export const generate_session_token = () => {
+    return generate_random_base64url();
+};
+/**
+ * Create a new auth session.
+ *
+ * @param deps - query dependencies
+ * @param token_hash - blake3 hash of the session token (use `hash_session_token`)
+ * @param account_id - the account this session belongs to
+ * @param expires_at - when the session expires
+ */
+export const query_create_session = async (deps, token_hash, account_id, expires_at) => {
+    await deps.db.query(`INSERT INTO auth_session (id, account_id, expires_at) VALUES ($1, $2, $3)`, [
+        token_hash,
+        account_id,
+        expires_at.toISOString(),
+    ]);
+};
+/**
+ * Get a session if it exists, is not expired, and has not been revoked.
+ *
+ * @param deps - query dependencies
+ * @param token_hash - blake3 hash of the session token
+ */
+export const query_session_get_valid = async (deps, token_hash) => {
+    return deps.db.query_one(`SELECT * FROM auth_session WHERE id = $1 AND expires_at > NOW()`, [token_hash]);
+};
+/**
+ * Update `last_seen_at` and optionally extend expiry for a session.
+ *
+ * Extends if less than `AUTH_SESSION_EXTEND_THRESHOLD_MS` remaining.
+ *
+ * @param deps - query dependencies
+ * @param token_hash - blake3 hash of the session token
+ */
+export const query_session_touch = async (deps, token_hash) => {
+    const new_expires = new Date(Date.now() + AUTH_SESSION_LIFETIME_MS);
+    await deps.db.query(`UPDATE auth_session
+		 SET last_seen_at = NOW(),
+		     expires_at = CASE
+		       WHEN expires_at - NOW() < INTERVAL '1 day' THEN $2::timestamptz
+		       ELSE expires_at
+		     END
+		 WHERE id = $1`, [token_hash, new_expires.toISOString()]);
+};
+/**
+ * Revoke (delete) a session by its token hash.
+ *
+ * No account_id constraint — caller must ensure the hash comes from a
+ * trusted source (e.g. the authenticated session cookie). For user-facing
+ * revocation of a specific session by ID, prefer `query_session_revoke_for_account`
+ * which includes an IDOR guard.
+ */
+export const query_session_revoke_by_hash = async (deps, token_hash) => {
+    await deps.db.query(`DELETE FROM auth_session WHERE id = $1`, [token_hash]);
+};
+/**
+ * Revoke a session only if it belongs to the specified account.
+ *
+ * Prevents cross-account session revocation.
+ *
+ * @param deps - query dependencies
+ * @param token_hash - blake3 hash of the session token
+ * @param account_id - the account that must own the session
+ * @returns `true` if a session was revoked, `false` if not found or wrong account
+ */
+export const query_session_revoke_for_account = async (deps, token_hash, account_id) => {
+    const rows = await deps.db.query(`DELETE FROM auth_session WHERE id = $1 AND account_id = $2 RETURNING id`, [token_hash, account_id]);
+    return rows.length > 0;
+};
+/**
+ * Revoke all sessions for an account.
+ *
+ * @returns the number of sessions revoked
+ */
+export const query_session_revoke_all_for_account = async (deps, account_id) => {
+    const rows = await deps.db.query(`DELETE FROM auth_session WHERE account_id = $1 RETURNING id`, [account_id]);
+    return rows.length;
+};
+/**
+ * List sessions for an account, newest first.
+ */
+export const query_session_list_for_account = async (deps, account_id, limit = 50) => {
+    return deps.db.query(`SELECT * FROM auth_session WHERE account_id = $1 ORDER BY created_at DESC LIMIT $2`, [account_id, limit]);
+};
+/**
+ * Enforce a per-account session limit by evicting the oldest sessions.
+ *
+ * Keeps the newest `max_sessions` sessions and deletes the rest.
+ *
+ * Race safety: this function must run inside a transaction alongside the
+ * INSERT that created the new session. All callers satisfy this requirement:
+ * - `POST /login` and `POST /tokens/create` use the default `transaction: true`
+ *   (framework-managed transaction wrapping in `apply_route_specs`)
+ * - `POST /bootstrap` and `POST /signup` manage their own transactions
+ *   and pass the transaction-scoped `deps` to `create_session_and_set_cookie`
+ *
+ * The transaction ensures the INSERT + enforce_limit pair is atomic —
+ * concurrent session creation cannot interleave between the two statements.
+ *
+ * @param deps - query dependencies (must be transaction-scoped)
+ * @param account_id - the account to enforce the limit for
+ * @param max_sessions - maximum number of sessions to keep
+ * @returns the number of sessions evicted
+ */
+export const query_session_enforce_limit = async (deps, account_id, max_sessions) => {
+    const rows = await deps.db.query(`DELETE FROM auth_session
+		 WHERE id IN (
+		   SELECT id FROM auth_session
+		   WHERE account_id = $1
+		   ORDER BY created_at DESC
+		   OFFSET $2
+		 ) RETURNING id`, [account_id, max_sessions]);
+    return rows.length;
+};
+/**
+ * List all active sessions across all accounts with usernames.
+ *
+ * @param deps - query dependencies
+ * @param limit - maximum entries to return
+ * @returns active sessions joined with account usernames, newest activity first
+ */
+export const query_session_list_all_active = async (deps, limit = 200) => {
+    return deps.db.query(`SELECT s.id, s.account_id, s.created_at, s.expires_at, s.last_seen_at, a.username
+		 FROM auth_session s
+		 JOIN account a ON a.id = s.account_id
+		 WHERE s.expires_at > NOW()
+		 ORDER BY s.last_seen_at DESC LIMIT $1`, [limit]);
+};
+/**
+ * Delete expired sessions.
+ *
+ * @returns the number of sessions cleaned up
+ */
+export const query_session_cleanup_expired = async (deps) => {
+    const rows = await deps.db.query(`DELETE FROM auth_session WHERE expires_at <= NOW() RETURNING id`);
+    return rows.length;
+};
+/**
+ * Touch a session without blocking the caller.
+ *
+ * Errors are logged to console — session touching never breaks request flows.
+ * Pass `pending_effects` (from `c.var.pending_effects`) to register
+ * the promise for test flushing.
+ *
+ * @param deps - query dependencies
+ * @param token_hash - blake3 hash of the session token
+ * @param pending_effects - optional array to register the effect for later awaiting
+ * @param log - the logger instance
+ * @returns the settled promise (callers may ignore it — fire-and-forget semantics preserved)
+ */
+export const session_touch_fire_and_forget = (deps, token_hash, pending_effects, log) => {
+    const p = query_session_touch(deps, token_hash).catch((err) => {
+        log.error('Session touch failed:', err);
+    });
+    pending_effects?.push(p);
+    return p;
+};

package/dist/auth/signup_routes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Signup route spec for account creation.
+ *
+ * Public endpoint that creates an account. When `open_signup` is disabled
+ * (default), a matching unclaimed invite is required. When enabled, anyone
+ * can sign up without an invite. Follows the `bootstrap_routes.ts` pattern.
+ *
+ * @module
+ */
+import { type RouteSpec } from '../http/route_spec.js';
+import { type RateLimiter } from '../rate_limiter.js';
+import type { RouteFactoryDeps } from './deps.js';
+import type { AppSettings } from './app_settings_schema.js';
+import type { AuthSessionRouteOptions } from './account_routes.js';
+/**
+ * Per-factory configuration for signup route specs.
+ */
+export interface SignupRouteOptions extends AuthSessionRouteOptions {
+    /** Rate limiter for signup attempts, keyed by submitted username. Pass `null` to disable. */
+    signup_account_rate_limiter: RateLimiter | null;
+    /** Mutable ref to app settings — when `open_signup` is true, invite check is skipped. */
+    app_settings: AppSettings;
+}
+/**
+ * Create signup route specs for account creation.
+ *
+ * @param deps - stateless capabilities
+ * @param options - per-factory configuration
+ * @returns route specs (not yet applied to Hono)
+ */
+export declare const create_signup_route_specs: (deps: RouteFactoryDeps, options: SignupRouteOptions) => Array<RouteSpec>;
+//# sourceMappingURL=signup_routes.d.ts.map

package/dist/auth/signup_routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAGhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,yFAAyF;IACzF,YAAY,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CAqIjB,CAAC"}

package/dist/auth/signup_routes.js

@@ -0,0 +1,150 @@
+/**
+ * Signup route spec for account creation.
+ *
+ * Public endpoint that creates an account. When `open_signup` is disabled
+ * (default), a matching unclaimed invite is required. When enabled, anyone
+ * can sign up without an invite. Follows the `bootstrap_routes.ts` pattern.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { create_session_and_set_cookie } from './session_lifecycle.js';
+import { query_create_account_with_actor } from './account_queries.js';
+import { query_invite_find_unclaimed_match, query_invite_claim } from './invite_queries.js';
+import { Username, Email } from './account_schema.js';
+import { Password } from './password.js';
+import { get_route_input } from '../http/route_spec.js';
+import { get_client_ip } from '../http/proxy.js';
+import { rate_limit_exceeded_response } from '../rate_limiter.js';
+import { ERROR_NO_MATCHING_INVITE, ERROR_SIGNUP_CONFLICT } from '../http/error_schemas.js';
+import { audit_log_fire_and_forget } from './audit_log_queries.js';
+import { is_pg_unique_violation } from '../db/pg_error.js';
+/**
+ * Create signup route specs for account creation.
+ *
+ * @param deps - stateless capabilities
+ * @param options - per-factory configuration
+ * @returns route specs (not yet applied to Hono)
+ */
+export const create_signup_route_specs = (deps, options) => {
+    const { keyring, password, on_audit_event } = deps;
+    const { session_options, ip_rate_limiter, signup_account_rate_limiter, app_settings } = options;
+    return [
+        {
+            method: 'POST',
+            path: '/signup',
+            auth: { type: 'none' },
+            description: 'Create account (invite-gated or open signup)',
+            transaction: false, // manages its own transaction for TOCTOU safety
+            input: z.strictObject({
+                username: Username,
+                password: Password,
+                email: Email.optional(),
+            }),
+            output: z.strictObject({ ok: z.literal(true) }),
+            rate_limit: signup_account_rate_limiter ? 'both' : 'ip',
+            errors: {
+                403: z.looseObject({ error: z.literal(ERROR_NO_MATCHING_INVITE) }),
+                409: z.looseObject({ error: z.literal(ERROR_SIGNUP_CONFLICT) }),
+            },
+            handler: async (c, route) => {
+                // Per-IP rate limit check (before any work)
+                const ip = ip_rate_limiter ? get_client_ip(c) : null;
+                if (ip_rate_limiter && ip) {
+                    const check = ip_rate_limiter.check(ip);
+                    if (!check.allowed) {
+                        return rate_limit_exceeded_response(c, check.retry_after);
+                    }
+                }
+                const { username, password: pw, email, } = get_route_input(c);
+                // Per-account rate limit check (after input parsing, before DB work)
+                const account_key = username.toLowerCase();
+                if (signup_account_rate_limiter) {
+                    const check = signup_account_rate_limiter.check(account_key);
+                    if (!check.allowed) {
+                        return rate_limit_exceeded_response(c, check.retry_after);
+                    }
+                }
+                // Check for matching invite (unless open signup is enabled)
+                let invite;
+                if (!app_settings.open_signup) {
+                    invite = await query_invite_find_unclaimed_match({ db: route.background_db }, email ?? null, username);
+                    if (!invite) {
+                        if (ip_rate_limiter && ip)
+                            ip_rate_limiter.record(ip);
+                        if (signup_account_rate_limiter)
+                            signup_account_rate_limiter.record(account_key);
+                        return c.json({ error: ERROR_NO_MATCHING_INVITE }, 403);
+                    }
+                }
+                // Create account, optionally claim invite, and create session atomically.
+                // Username/email uniqueness enforced by DB unique constraints.
+                const password_hash = await password.hash_password(pw);
+                let result;
+                try {
+                    result = await route.background_db.transaction(async (tx) => {
+                        const tx_deps = { db: tx };
+                        const { account } = await query_create_account_with_actor(tx_deps, {
+                            username,
+                            password_hash,
+                            email,
+                        });
+                        if (invite) {
+                            const claimed = await query_invite_claim(tx_deps, invite.id, account.id);
+                            if (!claimed) {
+                                // Race: invite was claimed between the find and this claim
+                                throw new SignupConflictError(ERROR_NO_MATCHING_INVITE);
+                            }
+                        }
+                        await create_session_and_set_cookie({
+                            keyring,
+                            deps: tx_deps,
+                            c,
+                            account_id: account.id,
+                            session_options,
+                        });
+                        return account;
+                    });
+                }
+                catch (e) {
+                    if (e instanceof SignupConflictError) {
+                        if (ip_rate_limiter && ip)
+                            ip_rate_limiter.record(ip);
+                        if (signup_account_rate_limiter)
+                            signup_account_rate_limiter.record(account_key);
+                        return c.json({ error: e.error }, 403);
+                    }
+                    // Unique constraint violation: username or email already exists.
+                    if (is_pg_unique_violation(e)) {
+                        if (ip_rate_limiter && ip)
+                            ip_rate_limiter.record(ip);
+                        if (signup_account_rate_limiter)
+                            signup_account_rate_limiter.record(account_key);
+                        return c.json({ error: ERROR_SIGNUP_CONFLICT }, 409);
+                    }
+                    throw e;
+                }
+                // Reset rate limiters on success
+                if (ip_rate_limiter && ip)
+                    ip_rate_limiter.reset(ip);
+                if (signup_account_rate_limiter)
+                    signup_account_rate_limiter.reset(account_key);
+                void audit_log_fire_and_forget(route, {
+                    event_type: 'signup',
+                    account_id: result.id,
+                    ip: get_client_ip(c),
+                    metadata: invite ? { invite_id: invite.id, username } : { open_signup: true, username },
+                }, deps.log, on_audit_event);
+                return c.json({ ok: true });
+            },
+        },
+    ];
+};
+/** Thrown inside the signup transaction to signal a conflict that should roll back. */
+class SignupConflictError extends Error {
+    error;
+    constructor(error) {
+        super(error);
+        this.error = error;
+    }
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared CLI argument parsing utilities.
+ *
+ * Provides `parse_command_args` for schema-validated command parsing and
+ * `create_extract_global_flags` as a factory for project-specific global flag extraction.
+ * Both are used identically across tx, zzz, and mageguild.
+ *
+ * @module
+ */
+import { type ParsedArgs } from '@fuzdev/fuz_util/args.js';
+import { z } from 'zod';
+/**
+ * Discriminated union result for CLI argument parsing.
+ */
+export type ParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Parse command-specific args against a Zod schema.
+ *
+ * Validates `remaining` args (after global flag extraction) with alias expansion
+ * and returns a typed result or a prettified error string.
+ *
+ * @param remaining - remaining args after global flag extraction
+ * @param schema - Zod schema for the command
+ * @returns parse result with typed data or error message
+ */
+export declare const parse_command_args: <T extends Record<string, unknown>>(remaining: ParsedArgs, schema: z.ZodType<T>) => ParseResult<T>;
+/**
+ * Create a project-specific global flag extractor.
+ *
+ * Returns a function that separates global flags from command-specific args.
+ * The schema defines which flags are global (with aliases via `.meta({aliases})`),
+ * and the fallback provides defaults when parsing fails.
+ *
+ * @param schema - Zod schema for global flags
+ * @param fallback - default values when parsing fails
+ * @returns extractor function `(unparsed) => {flags, remaining}`
+ */
+export declare const create_extract_global_flags: <T extends Record<string, unknown>>(schema: z.ZodType<T>, fallback: T) => ((unparsed: ParsedArgs) => {
+    flags: T;
+    remaining: ParsedArgs;
+});
+//# sourceMappingURL=args.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAwB,KAAK,UAAU,EAAgB,MAAM,0BAA0B,CAAC;AAC/F,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAC,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAC,GAAG;IAAC,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC;AAExF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,WAAW,UAAU,EACrB,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAClB,WAAW,CAAC,CAAC,CAMf,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,UAAU,CAAC,KACT,CAAC,CAAC,QAAQ,EAAE,UAAU,KAAK;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,SAAS,EAAE,UAAU,CAAA;CAAC,CAuC9D,CAAC"}

package/dist/cli/args.js

@@ -0,0 +1,76 @@
+/**
+ * Shared CLI argument parsing utilities.
+ *
+ * Provides `parse_command_args` for schema-validated command parsing and
+ * `create_extract_global_flags` as a factory for project-specific global flag extraction.
+ * Both are used identically across tx, zzz, and mageguild.
+ *
+ * @module
+ */
+import { args_parse } from '@fuzdev/fuz_util/args.js';
+import { z } from 'zod';
+import { zod_to_schema_properties, zod_to_schema_names_with_aliases } from '@fuzdev/fuz_util/zod.js';
+/**
+ * Parse command-specific args against a Zod schema.
+ *
+ * Validates `remaining` args (after global flag extraction) with alias expansion
+ * and returns a typed result or a prettified error string.
+ *
+ * @param remaining - remaining args after global flag extraction
+ * @param schema - Zod schema for the command
+ * @returns parse result with typed data or error message
+ */
+export const parse_command_args = (remaining, schema) => {
+    const parsed = args_parse(remaining, schema);
+    if (!parsed.success) {
+        return { success: false, error: z.prettifyError(parsed.error) };
+    }
+    return { success: true, data: parsed.data };
+};
+/**
+ * Create a project-specific global flag extractor.
+ *
+ * Returns a function that separates global flags from command-specific args.
+ * The schema defines which flags are global (with aliases via `.meta({aliases})`),
+ * and the fallback provides defaults when parsing fails.
+ *
+ * @param schema - Zod schema for global flags
+ * @param fallback - default values when parsing fails
+ * @returns extractor function `(unparsed) => {flags, remaining}`
+ */
+export const create_extract_global_flags = (schema, fallback) => {
+    return (unparsed) => {
+        // get all global flag names and aliases from schema
+        const global_names = zod_to_schema_names_with_aliases(schema);
+        const global_props = zod_to_schema_properties(schema);
+        // extract global flag values, handling aliases
+        const flags_input = {};
+        for (const prop of global_props) {
+            // check canonical name first, then aliases
+            if (prop.name in unparsed) {
+                flags_input[prop.name] = unparsed[prop.name];
+            }
+            else {
+                for (const alias of prop.aliases) {
+                    if (alias in unparsed) {
+                        flags_input[prop.name] = unparsed[alias];
+                        break;
+                    }
+                }
+            }
+        }
+        // parse global flags
+        const global_parsed = args_parse(flags_input, schema);
+        const flags = global_parsed.success ? global_parsed.data : fallback;
+        // build remaining args without global flags
+        const remaining = { _: [...unparsed._] };
+        for (const [key, value] of Object.entries(unparsed)) {
+            if (key === '_')
+                continue;
+            if (global_names.has(key))
+                continue;
+            remaining[key] = value;
+        }
+        return { flags, remaining };
+    };
+};

package/dist/cli/config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Generic CLI configuration loader.
+ *
+ * Manages CLI-specific configuration stored at `~/.{name}/config.json`.
+ * Consumers keep their project-specific Zod schemas locally and use
+ * these generic load/save functions.
+ *
+ * @module
+ */
+import type { z } from 'zod';
+import type { EnvDeps, FsReadDeps, FsWriteDeps, LogDeps } from '../runtime/deps.js';
+/**
+ * Get the CLI config directory path (`~/.{name}`).
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param name - application name (e.g., `"tx"`, `"zzz"`)
+ * @returns path to config directory, or null if `$HOME` is not set
+ */
+export declare const get_app_dir: (runtime: Pick<EnvDeps, "env_get">, name: string) => string | null;
+/**
+ * Get the CLI config file path (`~/.{name}/config.json`).
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param name - application name
+ * @returns path to `config.json`, or null if `$HOME` is not set
+ */
+export declare const get_config_path: (runtime: Pick<EnvDeps, "env_get">, name: string) => string | null;
+/**
+ * Load CLI configuration from a JSON file with Zod schema validation.
+ *
+ * @param runtime - runtime with file read capability
+ * @param path - path to the config JSON file
+ * @param schema - Zod schema to validate against
+ * @returns parsed config, or null if file doesn't exist or is invalid
+ */
+export declare const load_config: <T>(runtime: FsReadDeps & LogDeps, path: string, schema: z.ZodType<T>) => Promise<T | null>;
+/**
+ * Save CLI configuration to a JSON file.
+ *
+ * Creates parent directories if they don't exist.
+ *
+ * @param runtime - runtime with file write capability
+ * @param path - path to the config JSON file
+ * @param dir - directory containing the config file (created if missing)
+ * @param config - configuration to save
+ */
+export declare const save_config: <T>(runtime: FsWriteDeps, path: string, dir: string, config: T) => Promise<void>;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,IAGtF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,IAG1F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAClC,SAAS,UAAU,GAAG,OAAO,EAC7B,MAAM,MAAM,EACZ,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAClB,OAAO,CAAC,CAAC,GAAG,IAAI,CAoBlB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAClC,SAAS,WAAW,EACpB,MAAM,MAAM,EACZ,KAAK,MAAM,EACX,QAAQ,CAAC,KACP,OAAO,CAAC,IAAI,CAOd,CAAC"}

package/dist/cli/config.js

@@ -0,0 +1,77 @@
+/**
+ * Generic CLI configuration loader.
+ *
+ * Manages CLI-specific configuration stored at `~/.{name}/config.json`.
+ * Consumers keep their project-specific Zod schemas locally and use
+ * these generic load/save functions.
+ *
+ * @module
+ */
+/**
+ * Get the CLI config directory path (`~/.{name}`).
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param name - application name (e.g., `"tx"`, `"zzz"`)
+ * @returns path to config directory, or null if `$HOME` is not set
+ */
+export const get_app_dir = (runtime, name) => {
+    const home = runtime.env_get('HOME');
+    return home ? `${home}/.${name}` : null;
+};
+/**
+ * Get the CLI config file path (`~/.{name}/config.json`).
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param name - application name
+ * @returns path to `config.json`, or null if `$HOME` is not set
+ */
+export const get_config_path = (runtime, name) => {
+    const app_dir = get_app_dir(runtime, name);
+    return app_dir ? `${app_dir}/config.json` : null;
+};
+/**
+ * Load CLI configuration from a JSON file with Zod schema validation.
+ *
+ * @param runtime - runtime with file read capability
+ * @param path - path to the config JSON file
+ * @param schema - Zod schema to validate against
+ * @returns parsed config, or null if file doesn't exist or is invalid
+ */
+export const load_config = async (runtime, path, schema) => {
+    // check if file exists
+    const stat = await runtime.stat(path);
+    if (!stat) {
+        return null;
+    }
+    try {
+        const content = await runtime.read_file(path);
+        const parsed = JSON.parse(content);
+        const result = schema.safeParse(parsed);
+        if (!result.success) {
+            runtime.warn(`Invalid config.json: ${result.error.message}`);
+            return null;
+        }
+        return result.data;
+    }
+    catch (error) {
+        runtime.warn(`Failed to read config.json: ${error.message}`);
+        return null;
+    }
+};
+/**
+ * Save CLI configuration to a JSON file.
+ *
+ * Creates parent directories if they don't exist.
+ *
+ * @param runtime - runtime with file write capability
+ * @param path - path to the config JSON file
+ * @param dir - directory containing the config file (created if missing)
+ * @param config - configuration to save
+ */
+export const save_config = async (runtime, path, dir, config) => {
+    // ensure directory exists
+    await runtime.mkdir(dir, { recursive: true });
+    // write with pretty formatting
+    const content = JSON.stringify(config, null, '\t');
+    await runtime.write_file(path, content + '\n');
+};