@levu/snap 0.1.0

package/dist/src/help/hierarchy-resolver.js

@@ -0,0 +1,43 @@
+export const resolveHelpHierarchy = (modules, moduleId, actionId) => {
+    const scopedModules = moduleId ? modules.filter((m) => m.moduleId === moduleId) : modules;
+    return scopedModules.flatMap((moduleContract) => {
+        if (!actionId) {
+            return [
+                {
+                    moduleId: moduleContract.moduleId,
+                    sections: [
+                        {
+                            title: 'MODULE',
+                            lines: [moduleContract.description]
+                        },
+                        {
+                            title: 'ACTIONS',
+                            lines: moduleContract.actions.map((action) => `${action.actionId} - ${action.description}`)
+                        }
+                    ]
+                }
+            ];
+        }
+        const action = moduleContract.actions.find((item) => item.actionId === actionId);
+        if (!action)
+            return [];
+        return [toActionHelp(moduleContract.moduleId, action)];
+    });
+};
+const toActionHelp = (moduleId, action) => ({
+    moduleId,
+    actionId: action.actionId,
+    sections: [
+        { title: 'SUMMARY', lines: [action.help.summary] },
+        {
+            title: 'ARGS',
+            lines: action.help.args.map((arg) => `${arg.required ? '*' : '-'} ${arg.name}: ${arg.description}`)
+        },
+        { title: 'EXAMPLES', lines: action.help.examples },
+        {
+            title: 'USE-CASES',
+            lines: action.help.useCases.map((useCase) => `${useCase.name}: ${useCase.command}`)
+        },
+        { title: 'KEYBINDINGS', lines: action.help.keybindings }
+    ]
+});

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+import { ActionRegistry } from './core/registry/action-registry.js';
+import type { ModuleContract } from './core/contracts/module-contract.js';
+export declare const createRegistry: (modules: ModuleContract[]) => ActionRegistry;

package/dist/src/index.js

@@ -0,0 +1,8 @@
+import { ActionRegistry } from './core/registry/action-registry.js';
+export const createRegistry = (modules) => {
+    const registry = new ActionRegistry();
+    for (const moduleContract of modules) {
+        registry.registerModule(moduleContract);
+    }
+    return registry;
+};

package/dist/src/modules/sample-content/module.d.ts

@@ -0,0 +1,3 @@
+import type { ModuleContract } from '../../core/contracts/module-contract.js';
+declare const sampleContentModule: ModuleContract;
+export default sampleContentModule;

package/dist/src/modules/sample-content/module.js

@@ -0,0 +1,61 @@
+import { ExitCode } from '../../core/errors/framework-errors.js';
+const toSlug = (value) => value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-');
+const sampleContentModule = {
+    moduleId: 'content',
+    description: 'Content-processing sample actions for framework adoption.',
+    actions: [
+        {
+            actionId: 'slugify',
+            description: 'Convert text into URL-safe slug.',
+            tui: { steps: ['collect-text', 'preview-slug'] },
+            commandline: { requiredArgs: ['text'] },
+            help: {
+                summary: 'Convert input text into deterministic lowercase slug.',
+                args: [{ name: 'text', required: true, description: 'Source text to transform.', example: '--text="Hello World"' }],
+                examples: ['hub content slugify --text="Hello World"'],
+                useCases: [{ name: 'blog url', description: 'Generate post slug', command: 'hub content slugify --text="my post"' }],
+                keybindings: ['Enter confirm', 'Esc cancel']
+            },
+            run: async (context) => {
+                const text = typeof context.args.text === 'string' && context.args.text.length > 0
+                    ? context.args.text
+                    : 'interactive text';
+                return {
+                    ok: true,
+                    mode: context.mode,
+                    exitCode: ExitCode.SUCCESS,
+                    data: toSlug(text)
+                };
+            }
+        },
+        {
+            actionId: 'word-count',
+            description: 'Count words from input text.',
+            tui: { steps: ['collect-text', 'show-count'] },
+            commandline: { requiredArgs: ['text'] },
+            help: {
+                summary: 'Count whitespace-separated words in deterministic way.',
+                args: [{ name: 'text', required: true, description: 'Input text for counting.', example: '--text="one two"' }],
+                examples: ['hub content word-count --text="one two three"'],
+                useCases: [{ name: 'draft checks', description: 'Validate article length quickly', command: 'hub content word-count --text="draft body"' }],
+                keybindings: ['Enter confirm', 'Esc cancel']
+            },
+            run: async (context) => {
+                const text = typeof context.args.text === 'string' ? context.args.text.trim() : '';
+                const words = text.length === 0 ? 0 : text.split(/\s+/).length;
+                return {
+                    ok: true,
+                    mode: context.mode,
+                    exitCode: ExitCode.SUCCESS,
+                    data: String(words)
+                };
+            }
+        }
+    ]
+};
+export default sampleContentModule;

package/dist/src/modules/sample-system/module.d.ts

@@ -0,0 +1,3 @@
+import type { ModuleContract } from '../../core/contracts/module-contract.js';
+declare const sampleSystemModule: ModuleContract;
+export default sampleSystemModule;

package/dist/src/modules/sample-system/module.js

@@ -0,0 +1,71 @@
+import { ExitCode } from '../../core/errors/framework-errors.js';
+const sampleSystemModule = {
+    moduleId: 'system',
+    description: 'System utility sample actions for framework adoption.',
+    actions: [
+        {
+            actionId: 'env-check',
+            description: 'Read environment and report platform details.',
+            tui: { steps: ['select-keys', 'review-output'] },
+            commandline: { requiredArgs: ['key'] },
+            help: {
+                summary: 'Check environment variable and runtime platform.',
+                args: [
+                    {
+                        name: 'key',
+                        required: true,
+                        description: 'Environment key to inspect.',
+                        example: '--key=HOME'
+                    }
+                ],
+                examples: ['hub system env-check --key=HOME'],
+                useCases: [
+                    {
+                        name: 'debug env',
+                        description: 'Inspect required runtime variable',
+                        command: 'hub system env-check --key=NODE_ENV'
+                    }
+                ],
+                keybindings: ['Enter confirm', 'Esc cancel']
+            },
+            run: async (context) => {
+                const key = typeof context.args.key === 'string' ? context.args.key : '';
+                const value = key ? process.env[key] ?? '' : '';
+                return {
+                    ok: true,
+                    mode: context.mode,
+                    exitCode: ExitCode.SUCCESS,
+                    data: `${key}=${value}`
+                };
+            }
+        },
+        {
+            actionId: 'node-info',
+            description: 'Display Node and OS info.',
+            tui: { steps: ['collect-options', 'show-runtime'] },
+            commandline: { requiredArgs: [] },
+            help: {
+                summary: 'Print deterministic Node runtime and platform info.',
+                args: [],
+                examples: ['hub system node-info'],
+                useCases: [
+                    {
+                        name: 'verify runtime',
+                        description: 'Check active node version and OS',
+                        command: 'hub system node-info'
+                    }
+                ],
+                keybindings: ['Enter confirm', 'Esc cancel']
+            },
+            run: async (context) => {
+                return {
+                    ok: true,
+                    mode: context.mode,
+                    exitCode: ExitCode.SUCCESS,
+                    data: `node=${process.version};platform=${process.platform}`
+                };
+            }
+        }
+    ]
+};
+export default sampleSystemModule;

package/dist/src/runtime/dispatch.d.ts

@@ -0,0 +1,11 @@
+import type { ActionResultEnvelope } from '../core/contracts/action-contract.js';
+import type { ActionRegistry } from '../core/registry/action-registry.js';
+export interface DispatchInput {
+    registry: ActionRegistry;
+    moduleId: string;
+    actionId: string;
+    args: Record<string, string | boolean>;
+    isTTY: boolean;
+    resumeFilePath?: string;
+}
+export declare const dispatchAction: (input: DispatchInput) => Promise<ActionResultEnvelope>;

package/dist/src/runtime/dispatch.js

@@ -0,0 +1,47 @@
+import { ExitCode, FrameworkError } from '../core/errors/framework-errors.js';
+import { executeAction } from './engine.js';
+import { resolveRuntimeMode } from './mode-resolver.js';
+import { FileResumeStore } from './resume-store.js';
+export const dispatchAction = async (input) => {
+    try {
+        const action = input.registry.getAction(input.moduleId, input.actionId);
+        const mode = resolveRuntimeMode({
+            isTTY: input.isTTY,
+            providedArgs: input.args,
+            commandline: action.commandline
+        });
+        const missingRequired = action.commandline.requiredArgs.filter((arg) => input.args[arg] === undefined || input.args[arg] === '');
+        if (mode === 'commandline' && missingRequired.length > 0) {
+            return {
+                ok: false,
+                mode,
+                exitCode: ExitCode.VALIDATION_ERROR,
+                errorMessage: `Missing required args: ${missingRequired.join(', ')}`
+            };
+        }
+        const resumeStore = input.resumeFilePath ? new FileResumeStore(input.resumeFilePath) : undefined;
+        return executeAction({
+            moduleId: input.moduleId,
+            action,
+            mode,
+            args: input.args,
+            resumeStore
+        });
+    }
+    catch (error) {
+        if (error instanceof FrameworkError) {
+            return {
+                ok: false,
+                mode: 'commandline',
+                exitCode: error.exitCode,
+                errorMessage: error.message
+            };
+        }
+        return {
+            ok: false,
+            mode: 'commandline',
+            exitCode: ExitCode.INTERNAL_ERROR,
+            errorMessage: error instanceof Error ? error.message : 'Unknown dispatch error'
+        };
+    }
+};

package/dist/src/runtime/engine.d.ts

@@ -0,0 +1,13 @@
+import type { ActionContract, ActionResultEnvelope, RuntimeMode } from '../core/contracts/action-contract.js';
+import { ResumeStore } from './resume-store.js';
+import { type WorkflowNode } from './state-machine.js';
+export interface EngineInput {
+    moduleId: string;
+    action: ActionContract;
+    mode: RuntimeMode;
+    args: Record<string, string | boolean>;
+    workflowId?: string;
+    workflowNodes?: WorkflowNode[];
+    resumeStore?: ResumeStore;
+}
+export declare const executeAction: (input: EngineInput) => Promise<ActionResultEnvelope>;

package/dist/src/runtime/engine.js

@@ -0,0 +1,44 @@
+import { ExitCode } from '../core/errors/framework-errors.js';
+import { StateMachine } from './state-machine.js';
+export const executeAction = async (input) => {
+    const nodes = input.workflowNodes ?? input.action.tui.steps.map((step) => ({ id: step, label: step }));
+    const workflowId = input.workflowId ?? `${input.moduleId}.${input.action.actionId}`;
+    let initialNodeId;
+    if (input.resumeStore) {
+        const checkpoint = await input.resumeStore.load();
+        if (checkpoint?.workflowId === workflowId) {
+            initialNodeId = checkpoint.nodeId;
+        }
+    }
+    const stateMachine = new StateMachine(workflowId, nodes, initialNodeId);
+    const context = {
+        moduleId: input.moduleId,
+        actionId: input.action.actionId,
+        mode: input.mode,
+        args: input.args,
+        stateMachine
+    };
+    try {
+        const result = await input.action.run(context);
+        if (input.resumeStore) {
+            if (stateMachine.snapshot().exited || result.ok) {
+                await input.resumeStore.clear();
+            }
+            else {
+                await input.resumeStore.save(stateMachine.checkpoint());
+            }
+        }
+        return { ...result, mode: input.mode, exitCode: result.exitCode ?? ExitCode.SUCCESS };
+    }
+    catch (error) {
+        if (input.resumeStore) {
+            await input.resumeStore.save(stateMachine.checkpoint());
+        }
+        return {
+            ok: false,
+            mode: input.mode,
+            exitCode: ExitCode.INTERNAL_ERROR,
+            errorMessage: error instanceof Error ? error.message : 'Unknown error'
+        };
+    }
+};

package/dist/src/runtime/mode-resolver.d.ts

@@ -0,0 +1,8 @@
+import type { CommandlineContract, RuntimeMode } from '../core/contracts/action-contract.js';
+export interface RuntimeResolutionInput {
+    isTTY: boolean;
+    providedArgs: Record<string, string | boolean>;
+    commandline: CommandlineContract;
+}
+export declare const hasRequiredArgs: (requiredArgs: string[], providedArgs: Record<string, string | boolean>) => boolean;
+export declare const resolveRuntimeMode: (input: RuntimeResolutionInput) => RuntimeMode;

package/dist/src/runtime/mode-resolver.js

@@ -0,0 +1,8 @@
+export const hasRequiredArgs = (requiredArgs, providedArgs) => requiredArgs.every((arg) => providedArgs[arg] !== undefined && providedArgs[arg] !== '');
+export const resolveRuntimeMode = (input) => {
+    if (!input.isTTY)
+        return 'commandline';
+    if (hasRequiredArgs(input.commandline.requiredArgs, input.providedArgs))
+        return 'commandline';
+    return 'tui';
+};

package/dist/src/runtime/resume-store.d.ts

@@ -0,0 +1,13 @@
+import type { WorkflowCheckpoint } from './state-machine.js';
+export interface ResumeStore {
+    load: () => Promise<WorkflowCheckpoint | undefined>;
+    save: (checkpoint: WorkflowCheckpoint) => Promise<void>;
+    clear: () => Promise<void>;
+}
+export declare class FileResumeStore implements ResumeStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    load(): Promise<WorkflowCheckpoint | undefined>;
+    save(checkpoint: WorkflowCheckpoint): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/src/runtime/resume-store.js

@@ -0,0 +1,45 @@
+import { promises as fs } from 'node:fs';
+import { dirname } from 'node:path';
+export class FileResumeStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async load() {
+        let raw;
+        try {
+            raw = await fs.readFile(this.filePath, 'utf8');
+        }
+        catch (error) {
+            if (isIgnorableReadError(error)) {
+                return undefined;
+            }
+            throw error;
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async save(checkpoint) {
+        await fs.mkdir(dirname(this.filePath), { recursive: true });
+        await fs.writeFile(this.filePath, JSON.stringify(checkpoint), 'utf8');
+    }
+    async clear() {
+        try {
+            await fs.unlink(this.filePath);
+        }
+        catch (error) {
+            if (isIgnorableReadError(error)) {
+                return;
+            }
+            throw error;
+        }
+    }
+}
+const isIgnorableReadError = (error) => typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    (error.code === 'ENOENT');

package/dist/src/runtime/runtime-context.d.ts

@@ -0,0 +1,9 @@
+import type { RuntimeMode } from '../core/contracts/action-contract.js';
+import type { StateMachine } from './state-machine.js';
+export interface RuntimeContext {
+    moduleId: string;
+    actionId: string;
+    mode: RuntimeMode;
+    args: Record<string, string | boolean>;
+    stateMachine?: StateMachine;
+}

package/dist/src/runtime/runtime-context.js

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

package/dist/src/runtime/state-machine.d.ts

@@ -0,0 +1,32 @@
+export type StateTransitionType = 'next' | 'back' | 'jump' | 'exit';
+export interface WorkflowNode {
+    id: string;
+    label: string;
+}
+export interface WorkflowCheckpoint {
+    workflowId: string;
+    nodeId: string;
+    cursor: number;
+    timestamp: string;
+}
+export interface StateTransition {
+    type: StateTransitionType;
+    targetNodeId?: string;
+}
+export interface StateMachineSnapshot {
+    workflowId: string;
+    nodes: WorkflowNode[];
+    cursor: number;
+    exited: boolean;
+}
+export declare class StateMachine {
+    private readonly workflowId;
+    private readonly nodes;
+    private cursor;
+    private exited;
+    constructor(workflowId: string, nodes: WorkflowNode[], initialNodeId?: string);
+    transition(transition: StateTransition): StateMachineSnapshot;
+    currentNode(): WorkflowNode;
+    checkpoint(): WorkflowCheckpoint;
+    snapshot(): StateMachineSnapshot;
+}

package/dist/src/runtime/state-machine.js

@@ -0,0 +1,50 @@
+export class StateMachine {
+    workflowId;
+    nodes;
+    cursor = 0;
+    exited = false;
+    constructor(workflowId, nodes, initialNodeId) {
+        this.workflowId = workflowId;
+        this.nodes = nodes;
+        if (initialNodeId) {
+            const index = nodes.findIndex((node) => node.id === initialNodeId);
+            if (index >= 0)
+                this.cursor = index;
+        }
+    }
+    transition(transition) {
+        if (this.exited)
+            return this.snapshot();
+        if (transition.type === 'next')
+            this.cursor = Math.min(this.cursor + 1, this.nodes.length - 1);
+        if (transition.type === 'back')
+            this.cursor = Math.max(this.cursor - 1, 0);
+        if (transition.type === 'jump' && transition.targetNodeId) {
+            const index = this.nodes.findIndex((node) => node.id === transition.targetNodeId);
+            if (index >= 0)
+                this.cursor = index;
+        }
+        if (transition.type === 'exit')
+            this.exited = true;
+        return this.snapshot();
+    }
+    currentNode() {
+        return this.nodes[this.cursor];
+    }
+    checkpoint() {
+        return {
+            workflowId: this.workflowId,
+            nodeId: this.currentNode().id,
+            cursor: this.cursor,
+            timestamp: new Date().toISOString()
+        };
+    }
+    snapshot() {
+        return {
+            workflowId: this.workflowId,
+            nodes: this.nodes,
+            cursor: this.cursor,
+            exited: this.exited
+        };
+    }
+}

package/dist/src/tui/accessibility-footer.d.ts

@@ -0,0 +1,7 @@
+export interface AccessibilityFooterInput {
+    moduleId: string;
+    actionId: string;
+    nodeId: string;
+    keybindings: string[];
+}
+export declare const renderAccessibilityFooter: (input: AccessibilityFooterInput) => string;

package/dist/src/tui/accessibility-footer.js

@@ -0,0 +1,4 @@
+export const renderAccessibilityFooter = (input) => {
+    const keys = input.keybindings.join(' | ');
+    return `[ctx module=${input.moduleId} action=${input.actionId} node=${input.nodeId}] [keys ${keys}]`;
+};

package/dist/src/tui/component-adapters/confirm.d.ts

@@ -0,0 +1,5 @@
+export interface ConfirmPromptInput {
+    message: string;
+    initialValue?: boolean;
+}
+export declare const runConfirmPrompt: (input: ConfirmPromptInput) => Promise<boolean>;

package/dist/src/tui/component-adapters/confirm.js

@@ -0,0 +1,3 @@
+export const runConfirmPrompt = async (input) => {
+    return input.initialValue ?? true;
+};

package/dist/src/tui/component-adapters/group.d.ts

@@ -0,0 +1,5 @@
+export interface GroupStep<T = unknown> {
+    key: string;
+    run: () => Promise<T>;
+}
+export declare const runGroupPrompt: <T = unknown>(steps: GroupStep<T>[]) => Promise<Record<string, T>>;

package/dist/src/tui/component-adapters/group.js

@@ -0,0 +1,7 @@
+export const runGroupPrompt = async (steps) => {
+    const result = {};
+    for (const step of steps) {
+        result[step.key] = await step.run();
+    }
+    return result;
+};

package/dist/src/tui/component-adapters/multiselect.d.ts

@@ -0,0 +1,10 @@
+export interface MultiSelectOption {
+    value: string;
+    label: string;
+}
+export interface MultiSelectPromptInput {
+    message: string;
+    options: MultiSelectOption[];
+    initialValues?: string[];
+}
+export declare const runMultiSelectPrompt: (input: MultiSelectPromptInput) => Promise<string[]>;

package/dist/src/tui/component-adapters/multiselect.js

@@ -0,0 +1,9 @@
+export const runMultiSelectPrompt = async (input) => {
+    if (input.options.length === 0) {
+        throw new Error(`No options available for multiselect prompt: ${input.message}`);
+    }
+    if (input.initialValues && input.initialValues.length > 0) {
+        return input.initialValues.filter((value) => input.options.some((option) => option.value === value));
+    }
+    return [input.options[0].value];
+};

package/dist/src/tui/component-adapters/select.d.ts

@@ -0,0 +1,10 @@
+export interface SelectOption {
+    value: string;
+    label: string;
+}
+export interface SelectPromptInput {
+    message: string;
+    options: SelectOption[];
+    initialValue?: string;
+}
+export declare const runSelectPrompt: (input: SelectPromptInput) => Promise<string>;

package/dist/src/tui/component-adapters/select.js

@@ -0,0 +1,7 @@
+export const runSelectPrompt = async (input) => {
+    const selected = input.initialValue ?? input.options[0]?.value;
+    if (!selected) {
+        throw new Error(`No options available for select prompt: ${input.message}`);
+    }
+    return selected;
+};

package/dist/src/tui/component-adapters/text.d.ts

@@ -0,0 +1,6 @@
+export interface TextPromptInput {
+    message: string;
+    initialValue?: string;
+    required?: boolean;
+}
+export declare const runTextPrompt: (input: TextPromptInput) => Promise<string>;

package/dist/src/tui/component-adapters/text.js

@@ -0,0 +1,7 @@
+export const runTextPrompt = async (input) => {
+    const value = input.initialValue ?? '';
+    if (input.required && value.trim().length === 0) {
+        throw new Error(`Required text value missing: ${input.message}`);
+    }
+    return value;
+};

package/dist/src/tui/interrupt-handlers.d.ts

@@ -0,0 +1,7 @@
+import { ExitCode } from '../core/errors/framework-errors.js';
+export type InterruptSignal = 'SIGINT' | 'ESC' | 'TIMEOUT';
+export interface InterruptResult {
+    exitCode: ExitCode;
+    reason: string;
+}
+export declare const handleInterrupt: (signal: InterruptSignal) => InterruptResult;

package/dist/src/tui/interrupt-handlers.js

@@ -0,0 +1,7 @@
+import { ExitCode } from '../core/errors/framework-errors.js';
+export const handleInterrupt = (signal) => {
+    if (signal === 'TIMEOUT') {
+        return { exitCode: ExitCode.VALIDATION_ERROR, reason: 'Workflow timed out' };
+    }
+    return { exitCode: ExitCode.INTERRUPTED, reason: `Interrupted by ${signal}` };
+};

package/dist/tests/e2e/cli-smoke.e2e.test.d.ts

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

package/dist/tests/e2e/cli-smoke.e2e.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+describe('e2e cli smoke', () => {
+    it('prints help output from cli entry', () => {
+        const projectRoot = resolve(__dirname, '../..');
+        const tsxCli = resolve(projectRoot, 'node_modules/tsx/dist/cli.mjs');
+        const cliEntry = resolve(projectRoot, 'src/cli-entry.ts');
+        const result = spawnSync(process.execPath, [tsxCli, cliEntry, '-h'], {
+            cwd: projectRoot,
+            encoding: 'utf8'
+        });
+        expect(result.status).toBe(0);
+        expect(result.stdout).toContain('# HELP');
+    });
+});

package/dist/tests/integration/runtime-dispatch.integration.test.d.ts

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