@levu/snap 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-02-24
+
+### Added
+- **New Components**: Added `spinner` component for loading states during long-running operations
+- **New Components**: Added `password` component for secure text input
+- **New Terminal Features**: Added structured logging with `log.info()`, `log.success()`, `log.warn()`, `log.error()` utilities
+- **Documentation**: Comprehensive Getting Started guide with installation and quick start examples
+- **Documentation**: SnapArgs documentation - type-safe argument reading helpers
+- **Documentation**: SnapHelp documentation - schema-driven help generation
+- **Documentation**: SnapRuntime documentation - standardized action result helpers
+- **Documentation**: SnapTui documentation - typed TUI flow definitions and components
+- **Documentation**: SnapTerminal documentation - terminal output and logging helpers
+- **Documentation**: Integration examples demonstrating common patterns
+- **Examples**: Full example project in `example/` directory
+- **Tests**: Added comprehensive test coverage for new components and documentation examples
+
+### Changed
+- Enhanced `TerminalOutput` interface with `info()`, `success()`, and `warn()` methods
+- Updated `.gitignore` with comprehensive Node.js package patterns
+- Removed `.idea/` folder from git tracking
+
+### Fixed
+- Fixed issue where users couldn't discover available components (now fully documented)
+
+## [0.1.1] - 2025-02-10
+
+### Added
+- Initial release of Snap framework
+- Contract-first TypeScript framework for terminal workflows
+- Core contracts: ActionContract, ModuleContract, HelpContract, TuiContract
+- CLI runners: multi-module, single-module, and submodule support
+- DX helpers: SnapArgs, SnapHelp, SnapRuntime, SnapTui, SnapTerminal
+- TUI components: text, confirm, select, multiselect, cancel, group
+- Help system with deterministic, text-only output

package/README.md

@@ -8,10 +8,17 @@ It runs one action contract in 2 modes:
 
 It also enforces deterministic, text-only help so both **humans** and **AI agents** can discover commands reliably.
 
+For module/tool authors, Snap also exposes optional DX helper groups:
+- `SnapArgs` (typed argv readers/parsers)
+- `SnapHelp` (arg-schema driven help + commandline contracts)
+- `SnapRuntime` (standardized action result helpers)
+- `SnapTui` (typed flow/component definitions, including custom components)
+
 ## What this framework does
 
 - Enforces action triad at registration: `tui + commandline + help`
 - Uses one runtime engine for TUI and CLI paths
+- Uses Clack-powered prompt adapters for interactive TUI (`select`, `text`, `confirm`, `multiselect`)
 - Supports workflow transitions: `next`, `back`, `jump`, `exit`
 - Supports resume checkpoints for interrupted flows
 - Produces stable help output hierarchy:
@@ -45,5 +52,29 @@ npm run dev -- system node-info
 
 ## For module authors
 
-- `docs/module-authoring-guide.md`
-- `docs/help-contract-spec.md`
+### Documentation
+
+- **[Getting Started](./docs/getting-started.md)** - Quick start guide
+- **[Module Authoring Guide](./docs/module-authoring-guide.md)** - Core concepts
+- **[Help Contract Spec](./docs/help-contract-spec.md)** - Help format specification
+
+### DX Helper References
+
+- **[SnapArgs](./docs/snap-args.md)** - Type-safe argument reading
+- **[SnapHelp](./docs/snap-help.md)** - Schema-driven help generation
+- **[SnapRuntime](./docs/snap-runtime.md)** - Standardized action results
+- **[SnapTui](./docs/snap-tui.md)** - Typed TUI flow definitions
+- **[SnapTerminal](./docs/snap-terminal.md)** - Terminal output helpers
+
+### Additional Resources
+
+- **[Integration Examples](./docs/integration-examples.md)** - Common patterns
+- **[Component Reference](./docs/component-reference.md)** - All components and gaps
+
+### Examples
+
+See [`examples/`](./examples/) for working code examples:
+- `basic-module.ts` - Minimal module structure
+- `advanced-flow.ts` - Multi-step workflows
+- `dx-helpers.ts` - All DX helpers in action
+- `custom-prompt.ts` - Custom prompts with validation

package/dist/cli/cli-runner.d.ts

@@ -0,0 +1,37 @@
+import type { ActionRegistry } from '../core/registry/action-registry.js';
+import type { CliArgs } from '../dx/args/index.js';
+export interface ParsedCliInput {
+    wantsHelp: boolean;
+    positional: string[];
+    args: CliArgs;
+}
+export interface RunMultiModuleCliInput {
+    registry: ActionRegistry;
+    argv: string[];
+    isTTY?: boolean;
+}
+export interface RunSingleModuleCliInput {
+    registry: ActionRegistry;
+    argv: string[];
+    moduleId: string;
+    defaultActionId?: string;
+    helpDefaultTarget?: 'module' | 'action';
+    isTTY?: boolean;
+}
+export interface SubmoduleRoute {
+    moduleId: string;
+    defaultActionId?: string;
+    helpDefaultTarget?: 'module' | 'action';
+    aliases?: string[];
+}
+export interface RunSubmoduleCliInput {
+    registry: ActionRegistry;
+    argv: string[];
+    submodules: SubmoduleRoute[];
+    defaultSubmoduleId?: string;
+    isTTY?: boolean;
+}
+export declare const parseCliInput: (argv: string[]) => ParsedCliInput;
+export declare const runMultiModuleCli: (input: RunMultiModuleCliInput) => Promise<number>;
+export declare const runSingleModuleCli: (input: RunSingleModuleCliInput) => Promise<number>;
+export declare const runSubmoduleCli: (input: RunSubmoduleCliInput) => Promise<number>;

package/dist/cli/cli-runner.js

@@ -0,0 +1,161 @@
+import { createTerminalOutput } from '../dx/terminal/index.js';
+import { dispatchAction } from '../runtime/dispatch.js';
+import { runHelpCommand } from './help-command.js';
+const writeEnvelope = (envelope) => {
+    const terminal = createTerminalOutput();
+    if (envelope.data !== undefined)
+        terminal.line(String(envelope.data));
+    if (envelope.errorMessage)
+        terminal.error(envelope.errorMessage);
+    return envelope.exitCode;
+};
+const runSingleFromParsed = async (input) => {
+    const helpDefaultTarget = input.helpDefaultTarget ?? 'module';
+    const explicitActionId = input.parsed.positional[0] === input.moduleId
+        ? input.parsed.positional[1]
+        : input.parsed.positional[0];
+    if (input.parsed.wantsHelp) {
+        const helpActionId = explicitActionId ?? (helpDefaultTarget === 'action' ? input.defaultActionId : undefined);
+        return writeEnvelope(runHelpCommand({
+            registry: input.registry,
+            moduleId: input.moduleId,
+            actionId: helpActionId
+        }));
+    }
+    const actionId = explicitActionId ?? input.defaultActionId;
+    if (!actionId) {
+        return writeEnvelope(runHelpCommand({
+            registry: input.registry,
+            moduleId: input.moduleId
+        }));
+    }
+    const result = await dispatchAction({
+        registry: input.registry,
+        moduleId: input.moduleId,
+        actionId,
+        args: input.parsed.args,
+        isTTY: input.isTTY
+    });
+    return writeEnvelope(result);
+};
+const findSubmoduleRoute = (routes, token) => {
+    if (!token)
+        return undefined;
+    return routes.find((route) => route.moduleId === token || (route.aliases !== undefined && route.aliases.includes(token)));
+};
+export const parseCliInput = (argv) => {
+    const positional = [];
+    const args = {};
+    let wantsHelp = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '-h' || token === '--help') {
+            wantsHelp = true;
+            continue;
+        }
+        if (token === '--') {
+            positional.push(...argv.slice(index + 1));
+            break;
+        }
+        if (token.startsWith('--')) {
+            const body = token.slice(2);
+            const separatorIndex = body.indexOf('=');
+            if (separatorIndex >= 0) {
+                const key = body.slice(0, separatorIndex);
+                const value = body.slice(separatorIndex + 1);
+                if (key.length > 0)
+                    args[key] = value;
+                continue;
+            }
+            if (body.length === 0)
+                continue;
+            const next = argv[index + 1];
+            if (next !== undefined && !next.startsWith('-')) {
+                args[body] = next;
+                index += 1;
+            }
+            else {
+                args[body] = true;
+            }
+            continue;
+        }
+        positional.push(token);
+    }
+    return { wantsHelp, positional, args };
+};
+export const runMultiModuleCli = async (input) => {
+    const parsed = parseCliInput(input.argv);
+    const moduleId = parsed.positional[0];
+    const actionId = parsed.positional[1];
+    const isTTY = input.isTTY ?? Boolean(process.stdout.isTTY);
+    if (parsed.wantsHelp || !moduleId) {
+        return writeEnvelope(runHelpCommand({
+            registry: input.registry,
+            moduleId,
+            actionId
+        }));
+    }
+    if (!actionId) {
+        return writeEnvelope(runHelpCommand({
+            registry: input.registry,
+            moduleId
+        }));
+    }
+    const result = await dispatchAction({
+        registry: input.registry,
+        moduleId,
+        actionId,
+        args: parsed.args,
+        isTTY
+    });
+    return writeEnvelope(result);
+};
+export const runSingleModuleCli = async (input) => {
+    const parsed = parseCliInput(input.argv);
+    const isTTY = input.isTTY ?? Boolean(process.stdout.isTTY);
+    return runSingleFromParsed({
+        registry: input.registry,
+        parsed,
+        moduleId: input.moduleId,
+        defaultActionId: input.defaultActionId,
+        helpDefaultTarget: input.helpDefaultTarget,
+        isTTY
+    });
+};
+export const runSubmoduleCli = async (input) => {
+    const parsed = parseCliInput(input.argv);
+    const isTTY = input.isTTY ?? Boolean(process.stdout.isTTY);
+    const firstToken = parsed.positional[0];
+    const matchedRoute = findSubmoduleRoute(input.submodules, firstToken);
+    if (matchedRoute) {
+        return runSingleFromParsed({
+            registry: input.registry,
+            parsed: {
+                ...parsed,
+                positional: parsed.positional.slice(1)
+            },
+            moduleId: matchedRoute.moduleId,
+            defaultActionId: matchedRoute.defaultActionId,
+            helpDefaultTarget: matchedRoute.helpDefaultTarget,
+            isTTY
+        });
+    }
+    if (!parsed.wantsHelp && parsed.positional.length === 0 && input.defaultSubmoduleId) {
+        const defaultRoute = findSubmoduleRoute(input.submodules, input.defaultSubmoduleId);
+        if (defaultRoute) {
+            return runSingleFromParsed({
+                registry: input.registry,
+                parsed,
+                moduleId: defaultRoute.moduleId,
+                defaultActionId: defaultRoute.defaultActionId,
+                helpDefaultTarget: defaultRoute.helpDefaultTarget,
+                isTTY
+            });
+        }
+    }
+    return runMultiModuleCli({
+        registry: input.registry,
+        argv: input.argv,
+        isTTY
+    });
+};

package/dist/cli-entry.js

@@ -2,79 +2,21 @@ import { fileURLToPath } from 'node:url';
 import { createRegistry } from './index.js';
 import sampleContentModule from './modules/sample-content/module.js';
 import sampleSystemModule from './modules/sample-system/module.js';
-import { dispatchAction } from './runtime/dispatch.js';
-import { runHelpCommand } from './cli/help-command.js';
-const parseCliArgs = (argv) => {
-    const args = {};
-    const positional = [];
-    for (const token of argv) {
-        if (token.startsWith('--')) {
-            const body = token.slice(2);
-            const separatorIndex = body.indexOf('=');
-            if (separatorIndex === -1) {
-                if (body.length > 0)
-                    args[body] = true;
-            }
-            else {
-                const key = body.slice(0, separatorIndex);
-                const value = body.slice(separatorIndex + 1);
-                if (key.length > 0)
-                    args[key] = value;
-            }
-            continue;
-        }
-        positional.push(token);
-    }
-    return {
-        moduleId: positional[0],
-        actionId: positional[1],
-        args
-    };
-};
+import { runMultiModuleCli } from './cli/cli-runner.js';
+import { createTerminalOutput } from './dx/terminal/index.js';
 const registry = createRegistry([sampleContentModule, sampleSystemModule]);
-export const runCli = async (argv, isTTY = Boolean(process.stdout.isTTY)) => {
-    const wantsHelp = argv.includes('-h') || argv.includes('--help');
-    const filtered = argv.filter((item) => item !== '-h' && item !== '--help');
-    const parsed = parseCliArgs(filtered);
-    if (wantsHelp || !parsed.moduleId) {
-        const helpResult = runHelpCommand({
-            registry,
-            moduleId: parsed.moduleId,
-            actionId: parsed.actionId
-        });
-        if (helpResult.data)
-            process.stdout.write(`${helpResult.data}\n`);
-        if (helpResult.errorMessage)
-            process.stderr.write(`${helpResult.errorMessage}\n`);
-        return helpResult.exitCode;
-    }
-    if (!parsed.actionId) {
-        const helpResult = runHelpCommand({ registry, moduleId: parsed.moduleId });
-        if (helpResult.data)
-            process.stdout.write(`${helpResult.data}\n`);
-        return helpResult.exitCode;
-    }
-    const result = await dispatchAction({
-        registry,
-        moduleId: parsed.moduleId,
-        actionId: parsed.actionId,
-        args: parsed.args,
-        isTTY
-    });
-    if (result.data !== undefined)
-        process.stdout.write(`${String(result.data)}\n`);
-    if (result.errorMessage)
-        process.stderr.write(`${result.errorMessage}\n`);
-    return result.exitCode;
+export const runCli = async (argv, isTTY) => {
+    return runMultiModuleCli({ registry, argv, isTTY });
 };
 const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
 if (isMain) {
+    const terminal = createTerminalOutput();
     runCli(process.argv.slice(2))
         .then((code) => {
         process.exitCode = code;
     })
         .catch((error) => {
-        process.stderr.write(`${error instanceof Error ? error.message : 'Unknown CLI error'}\n`);
+        terminal.error(error instanceof Error ? error.message : 'Unknown CLI error');
         process.exitCode = 1;
     });
 }

package/dist/core/contracts/action-contract.d.ts

@@ -1,13 +1,11 @@
 import type { HelpContract } from './help-contract.js';
 import type { RuntimeContext } from '../../runtime/runtime-context.js';
+import type { TuiContract } from './tui-contract.js';
 export type RuntimeMode = 'tui' | 'commandline';
 export interface CommandlineContract {
     requiredArgs: string[];
     optionalArgs?: string[];
 }
-export interface TuiContract {
-    steps: string[];
-}
 export interface ActionResultEnvelope<T = unknown> {
     ok: boolean;
     mode: RuntimeMode;

package/dist/core/contracts/tui-contract.d.ts

@@ -0,0 +1,47 @@
+export type TuiComponentType = 'text' | 'confirm' | 'select' | 'multiselect' | 'group' | 'custom';
+export interface TuiOptionContract {
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface TuiStandardComponentContract {
+    componentId: string;
+    type: Exclude<TuiComponentType, 'custom'>;
+    label: string;
+    arg?: string;
+    required?: boolean;
+    placeholder?: string;
+    options?: TuiOptionContract[];
+    defaultValue?: string | boolean | string[];
+}
+export interface TuiCustomComponentContract<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+    componentId: string;
+    type: 'custom';
+    label: string;
+    arg?: string;
+    required?: boolean;
+    renderer: string;
+    config?: TConfig;
+    defaultValue?: string | boolean | string[];
+}
+export type TuiComponentContract = TuiStandardComponentContract | TuiCustomComponentContract;
+export type TuiTransitionType = 'next' | 'back' | 'jump' | 'exit';
+export interface TuiStepTransitionContract {
+    on: TuiTransitionType;
+    targetStepId?: string;
+}
+export interface TuiStepContract {
+    stepId: string;
+    title: string;
+    description?: string;
+    components?: TuiComponentContract[];
+    transitions?: TuiStepTransitionContract[];
+}
+export interface TuiFlowContract {
+    entryStepId?: string;
+    steps: TuiStepContract[];
+}
+export interface TuiContract {
+    steps?: string[];
+    flow?: TuiFlowContract;
+}

package/dist/core/contracts/tui-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/core/registry/action-registry.js

@@ -38,7 +38,9 @@ export class ActionRegistry {
         return `${moduleId}.${actionId}`;
     }
     assertTriad(moduleId, action) {
-        const hasTui = Array.isArray(action.tui?.steps) && action.tui.steps.length > 0;
+        const hasLegacySteps = Array.isArray(action.tui?.steps) && action.tui.steps.length > 0;
+        const hasFlowSteps = Array.isArray(action.tui?.flow?.steps) && action.tui.flow.steps.length > 0;
+        const hasTui = hasLegacySteps || hasFlowSteps;
         const hasCommandline = Array.isArray(action.commandline?.requiredArgs);
         const hasHelp = typeof action.help?.summary === 'string' &&
             Array.isArray(action.help?.args) &&

package/dist/dx/args/env.d.ts

@@ -0,0 +1,6 @@
+import type { CliArgs } from './types.js';
+export interface CollectEnvArgsInput {
+    args: CliArgs;
+    reservedKeys?: Iterable<string>;
+}
+export declare const collectUpperSnakeCaseEnvArgs: (input: CollectEnvArgsInput) => Record<string, string>;

package/dist/dx/args/env.js

@@ -0,0 +1,15 @@
+import { isUpperSnakeCaseKey } from './types.js';
+export const collectUpperSnakeCaseEnvArgs = (input) => {
+    const reserved = new Set(input.reservedKeys ?? []);
+    const env = {};
+    for (const [key, value] of Object.entries(input.args)) {
+        if (reserved.has(key))
+            continue;
+        if (!isUpperSnakeCaseKey(key))
+            continue;
+        if (typeof value !== 'string' || value.length === 0)
+            continue;
+        env[key] = value;
+    }
+    return env;
+};

package/dist/dx/args/index.d.ts

@@ -0,0 +1,4 @@
+export type { CliArgs, UpperSnakeCaseKey } from './types.js';
+export { isUpperSnakeCaseKey } from './types.js';
+export { readStringArg, readRequiredStringArg, parseBooleanLike, readBooleanArg } from './readers.js';
+export { collectUpperSnakeCaseEnvArgs } from './env.js';

package/dist/dx/args/index.js

@@ -0,0 +1,3 @@
+export { isUpperSnakeCaseKey } from './types.js';
+export { readStringArg, readRequiredStringArg, parseBooleanLike, readBooleanArg } from './readers.js';
+export { collectUpperSnakeCaseEnvArgs } from './env.js';

package/dist/dx/args/readers.d.ts

@@ -0,0 +1,5 @@
+import type { CliArgs } from './types.js';
+export declare const readStringArg: (args: CliArgs, ...keys: string[]) => string | undefined;
+export declare const readRequiredStringArg: (args: CliArgs, key: string, message?: string) => string;
+export declare const parseBooleanLike: (value: string | boolean | undefined) => boolean | undefined;
+export declare const readBooleanArg: (args: CliArgs, ...keys: string[]) => boolean | undefined;

package/dist/dx/args/readers.js

@@ -0,0 +1,36 @@
+export const readStringArg = (args, ...keys) => {
+    for (const key of keys) {
+        const value = args[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return undefined;
+};
+export const readRequiredStringArg = (args, key, message) => {
+    const value = readStringArg(args, key);
+    if (!value) {
+        throw new Error(message ?? `Missing required arg: ${key}`);
+    }
+    return value;
+};
+export const parseBooleanLike = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'boolean')
+        return value;
+    const normalized = value.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'y', 'on'].includes(normalized))
+        return true;
+    if (['0', 'false', 'no', 'n', 'off'].includes(normalized))
+        return false;
+    throw new Error(`Invalid boolean value "${value}".`);
+};
+export const readBooleanArg = (args, ...keys) => {
+    for (const key of keys) {
+        if (args[key] === undefined)
+            continue;
+        return parseBooleanLike(args[key]);
+    }
+    return undefined;
+};

package/dist/dx/args/types.d.ts

@@ -0,0 +1,5 @@
+export type CliArgs = Record<string, string | boolean>;
+export type UpperSnakeCaseKey = string & {
+    readonly __upperSnakeCaseKey: unique symbol;
+};
+export declare const isUpperSnakeCaseKey: (value: string) => value is UpperSnakeCaseKey;

package/dist/dx/args/types.js

@@ -0,0 +1 @@
+export const isUpperSnakeCaseKey = (value) => /^[A-Z_][A-Z0-9_]*$/.test(value);

package/dist/dx/help/builder.d.ts

@@ -0,0 +1,10 @@
+import type { HelpContract, HelpUseCaseSpec } from '../../core/contracts/help-contract.js';
+import type { ArgSchemaMap } from './schema.js';
+export interface HelpBuilderInput<Key extends string> {
+    summary: string;
+    argSchema: ArgSchemaMap<Key>;
+    examples?: string[];
+    useCases?: HelpUseCaseSpec[];
+    keybindings?: string[];
+}
+export declare const buildHelpFromArgSchema: <Key extends string>(input: HelpBuilderInput<Key>) => HelpContract;

package/dist/dx/help/builder.js

@@ -0,0 +1,11 @@
+import { helpArgsFromArgSchema } from './schema.js';
+const DEFAULT_KEYBINDINGS = ['Enter confirm', 'Esc cancel'];
+export const buildHelpFromArgSchema = (input) => {
+    return {
+        summary: input.summary,
+        args: helpArgsFromArgSchema(input.argSchema),
+        examples: input.examples ?? [],
+        useCases: input.useCases ?? [],
+        keybindings: input.keybindings ?? DEFAULT_KEYBINDINGS
+    };
+};

package/dist/dx/help/index.d.ts

@@ -0,0 +1,4 @@
+export type { ArgSchema, ArgSchemaMap } from './schema.js';
+export { defineArgSchema, commandlineFromArgSchema, helpArgsFromArgSchema } from './schema.js';
+export type { HelpBuilderInput } from './builder.js';
+export { buildHelpFromArgSchema } from './builder.js';

package/dist/dx/help/index.js

@@ -0,0 +1,2 @@
+export { defineArgSchema, commandlineFromArgSchema, helpArgsFromArgSchema } from './schema.js';
+export { buildHelpFromArgSchema } from './builder.js';

package/dist/dx/help/schema.d.ts

@@ -0,0 +1,14 @@
+import type { CommandlineContract } from '../../core/contracts/action-contract.js';
+import type { HelpArgumentSpec } from '../../core/contracts/help-contract.js';
+export interface ArgSchema {
+    description: string;
+    example?: string;
+    required?: boolean;
+    includeInCommandline?: boolean;
+    includeInHelp?: boolean;
+    helpName?: string;
+}
+export type ArgSchemaMap<Key extends string = string> = Record<Key, ArgSchema>;
+export declare const defineArgSchema: <Key extends string>(schema: ArgSchemaMap<Key>) => ArgSchemaMap<Key>;
+export declare const commandlineFromArgSchema: <Key extends string>(schema: ArgSchemaMap<Key>) => CommandlineContract;
+export declare const helpArgsFromArgSchema: <Key extends string>(schema: ArgSchemaMap<Key>) => HelpArgumentSpec[];

package/dist/dx/help/schema.js

@@ -0,0 +1,33 @@
+export const defineArgSchema = (schema) => schema;
+export const commandlineFromArgSchema = (schema) => {
+    const requiredArgs = [];
+    const optionalArgs = [];
+    for (const [name, spec] of Object.entries(schema)) {
+        if (spec.includeInCommandline === false)
+            continue;
+        if (spec.required) {
+            requiredArgs.push(name);
+        }
+        else {
+            optionalArgs.push(name);
+        }
+    }
+    return {
+        requiredArgs,
+        optionalArgs
+    };
+};
+export const helpArgsFromArgSchema = (schema) => {
+    const results = [];
+    for (const [name, spec] of Object.entries(schema)) {
+        if (spec.includeInHelp === false)
+            continue;
+        results.push({
+            name: spec.helpName ?? name,
+            required: Boolean(spec.required),
+            description: spec.description,
+            example: spec.example
+        });
+    }
+    return results;
+};

package/dist/dx/runtime/action-result.d.ts

@@ -0,0 +1,12 @@
+import type { ActionResultEnvelope } from '../../core/contracts/action-contract.js';
+import { ExitCode } from '../../core/errors/framework-errors.js';
+import type { RuntimeContext } from '../../runtime/runtime-context.js';
+export declare const toSuccessResult: <T>(context: RuntimeContext, data: T, exitCode?: ExitCode) => ActionResultEnvelope<T>;
+export declare const toErrorResult: <T = unknown>(context: RuntimeContext, error: unknown, fallbackMessage: string, exitCode?: ExitCode) => ActionResultEnvelope<T>;
+export interface RunActionSafelyInput<T> {
+    context: RuntimeContext;
+    execute: () => Promise<T>;
+    fallbackErrorMessage: string;
+    onSuccess?: (result: T) => T;
+}
+export declare const runActionSafely: <T>(input: RunActionSafelyInput<T>) => Promise<ActionResultEnvelope<T>>;