@levu/snap 0.1.0

package/dist/tests/integration/runtime-dispatch.integration.test.js

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { createRegistry } from '../../src/index.js';
+import sampleContentModule from '../../src/modules/sample-content/module.js';
+import sampleSystemModule from '../../src/modules/sample-system/module.js';
+import { dispatchAction } from '../../src/runtime/dispatch.js';
+describe('integration dispatch runtime', () => {
+    it('dispatches commandline action with required args', async () => {
+        const registry = createRegistry([sampleContentModule, sampleSystemModule]);
+        const result = await dispatchAction({
+            registry,
+            moduleId: 'content',
+            actionId: 'slugify',
+            args: { text: 'Hello Integration Test' },
+            isTTY: true
+        });
+        expect(result.ok).toBe(true);
+        expect(result.mode).toBe('commandline');
+        expect(result.data).toBe('hello-integration-test');
+    });
+});

package/dist/tests/transcript/help.transcript.test.d.ts

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

package/dist/tests/transcript/help.transcript.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { renderHelp } from '../../src/help/help-renderer.js';
+import { resolveHelpHierarchy } from '../../src/help/hierarchy-resolver.js';
+import sampleContentModule from '../../src/modules/sample-content/module.js';
+describe('transcript help output', () => {
+    it('renders deterministic action help transcript', () => {
+        const views = resolveHelpHierarchy([sampleContentModule], 'content', 'slugify');
+        const output = renderHelp(views);
+        expect(output).toContain('# HELP');
+        expect(output).toContain('MODULE: content');
+        expect(output).toContain('ACTION: slugify');
+        expect(output).toContain('## SUMMARY');
+        expect(output).toContain('## ARGS');
+        expect(output).toContain('## EXAMPLES');
+        expect(output).toContain('## USE-CASES');
+        expect(output).toContain('## KEYBINDINGS');
+    });
+});

package/dist/tests/unit/state-machine.test.d.ts

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

package/dist/tests/unit/state-machine.test.js

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { StateMachine } from '../../src/runtime/state-machine.js';
+describe('state-machine', () => {
+    it('supports next/back/jump/exit transitions', () => {
+        const machine = new StateMachine('wf', [
+            { id: 'a', label: 'A' },
+            { id: 'b', label: 'B' },
+            { id: 'c', label: 'C' }
+        ]);
+        expect(machine.currentNode().id).toBe('a');
+        machine.transition({ type: 'next' });
+        expect(machine.currentNode().id).toBe('b');
+        machine.transition({ type: 'jump', targetNodeId: 'c' });
+        expect(machine.currentNode().id).toBe('c');
+        machine.transition({ type: 'back' });
+        expect(machine.currentNode().id).toBe('b');
+        machine.transition({ type: 'exit' });
+        expect(machine.snapshot().exited).toBe(true);
+    });
+});

package/dist/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/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/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/tui/component-adapters/confirm.js

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

package/dist/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/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/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/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/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/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/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/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/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/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/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/vitest.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        environment: 'node',
+        include: ['tests/**/*.test.ts']
+    }
+});

package/docs/help-contract-spec.md

@@ -0,0 +1,29 @@
+# Help Contract Spec
+
+## Output Contract
+
+Help renderer must produce deterministic text sections in this order:
+
+1. `# HELP`
+2. `MODULE: <module-id>`
+3. `ACTION: <action-id|*>`
+4. Section blocks:
+   - `## MODULE`
+   - `## ACTIONS`
+   - `## SUMMARY`
+   - `## ARGS`
+   - `## EXAMPLES`
+   - `## USE-CASES`
+   - `## KEYBINDINGS`
+
+Each line item in section body uses `- <content>`.
+
+## CLI Levels
+
+- `hub -h` => module overview list.
+- `hub -h <module>` => module scoped list.
+- `hub -h <module> <action>` => action detail.
+
+## Validation
+
+Missing target returns non-zero exit code with deterministic error message.

package/docs/module-authoring-guide.md

@@ -0,0 +1,52 @@
+# Module Authoring Guide
+
+## Goal
+
+Define actions once with full triad contract:
+
+- `tui` flow steps
+- `commandline` required/optional args
+- `help` metadata
+
+## Minimal Module Shape
+
+```ts
+import type { ModuleContract } from '../core/contracts/module-contract.js';
+import { ExitCode } from '../core/errors/framework-errors.js';
+
+const moduleContract: ModuleContract = {
+  moduleId: 'example',
+  description: 'Example module',
+  actions: [
+    {
+      actionId: 'run',
+      description: 'Run example action',
+      tui: { steps: ['collect-input', 'confirm'] },
+      commandline: { requiredArgs: ['name'] },
+      help: {
+        summary: 'Run example with one name argument.',
+        args: [{ name: 'name', required: true, description: 'Target name' }],
+        examples: ['hub example run --name=alice'],
+        useCases: [{ name: 'default', description: 'Basic usage', command: 'hub example run --name=alice' }],
+        keybindings: ['Enter confirm', 'Esc cancel']
+      },
+      run: async (context) => ({
+        ok: true,
+        mode: context.mode,
+        exitCode: ExitCode.SUCCESS,
+        data: `hello ${String(context.args.name ?? '')}`
+      })
+    }
+  ]
+};
+
+export default moduleContract;
+```
+
+## Register Module
+
+Add module to registry bootstrapping in `/Users/khang/Documents/repo/snap/src/cli-entry.ts`.
+
+## Validation Rules
+
+Registration fails if any action misses triad data (`tui`, `commandline`, `help`).

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@levu/snap",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "snap": "./dist/cli-entry.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "dev": "tsx src/cli-entry.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.20.3",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/plans/260209-1547-hub-dual-runtime-framework/phase-01-foundation-and-contracts.md

@@ -0,0 +1,71 @@
+# Phase 01 — Foundation and contracts
+
+## Context links
+- Parent plan: `./plan.md`
+- Inputs: `./scout/scout-01-report.md`, `./research/researcher-01-report.md`, `./research/researcher-02-report.md`
+- Planner summary: `./reports/planner-report.md`
+
+## Overview
+- Date: 2026-02-09
+- Description: define core framework contracts and registry model enforcing TUI + CLI + help triad.
+- Priority: P0
+- Implementation status: complete
+- Review status: complete
+
+## Key Insights
+- Contract-first is required to prevent CLI/TUI/help drift.
+- Greenfield repo allows clean architecture without migration baggage.
+
+## Requirements
+- Functional:
+  - Define module/action contract types.
+  - Enforce triad presence at registration time.
+  - Define error taxonomy and exit-code map.
+  - Define runtime context and lifecycle hooks.
+- Non-functional:
+  - Type-safe API surface.
+  - Minimal public API for v1 (KISS).
+
+## Architecture
+<!-- Updated: Validation Session 1 - lock single-package layout for MVP -->
+- Locked MVP packaging: single package layout (`src/*`) with modular folders; no monorepo split in v1.
+- `core/contracts/*` for typed schemas and compile-time helpers.
+- `core/registry/*` for module/action registration and validation.
+- `core/errors/*` for standardized framework errors.
+
+## Related code files
+- Modify: none (greenfield)
+- Create:
+  - `src/core/contracts/module-contract.ts`
+  - `src/core/contracts/action-contract.ts`
+  - `src/core/contracts/help-contract.ts`
+  - `src/core/registry/action-registry.ts`
+  - `src/core/errors/framework-errors.ts`
+- Delete: none
+
+## Implementation Steps
+1. Define TypeScript contract interfaces and helper builders.
+2. Implement registry with startup validation.
+3. Add triad completeness checks and diagnostic messages.
+4. Add error codes and exit-code policy map.
+
+## Todo list
+- [x] Core contract interfaces defined
+- [x] Registry implemented
+- [x] Triad enforcement implemented
+- [x] Error taxonomy added
+
+## Success Criteria
+- Registering incomplete action fails deterministically with clear diagnostics.
+- Complete action contract can be registered and discovered.
+
+## Risk Assessment
+- Risk: over-modeling too early.
+  - Mitigation: keep v1 contracts minimal and extensible.
+
+## Security Considerations
+- Validate user-defined metadata before rendering/executing.
+- Avoid arbitrary code execution in registration path.
+
+## Next steps
+- Build runtime resolver + state machine in Phase 02.

package/plans/260209-1547-hub-dual-runtime-framework/phase-02-runtime-and-state-machine.md

@@ -0,0 +1,76 @@
+# Phase 02 — Runtime and state machine
+
+## Context links
+- Parent plan: `./plan.md`
+- Depends on: `./phase-01-foundation-and-contracts.md`
+- Research: `./research/researcher-01-report.md`, `./research/researcher-02-report.md`
+
+## Overview
+- Date: 2026-02-09
+- Description: implement shared runtime engine and workflow state machine for TUI-default + auto non-interactive behavior.
+- Priority: P0
+- Implementation status: complete
+- Review status: complete
+
+## Key Insights
+- One execution engine must serve both TUI and command paths.
+- Mode resolution must be deterministic and safe in non-TTY contexts.
+
+## Requirements
+- Functional:
+  - Implement runtime resolver: default TUI, auto headless when required args provided.
+  - Implement state-machine transitions for flow nodes including `next/back/jump/exit`.
+  - Implement persisted resume checkpoints for interrupted multi-step workflows.
+  - Implement in-process module loading and action dispatch.
+  - Implement unified result envelope and exit semantics.
+- Non-functional:
+  - Deterministic behavior for CI/automation.
+  - No duplicated business logic across adapters.
+
+## Architecture
+<!-- Updated: Validation Session 1 - include jump + resume in MVP -->
+- `runtime/mode-resolver.ts` decides interactive vs non-interactive.
+- `runtime/engine.ts` executes action handlers with shared context.
+- `runtime/state-machine.ts` handles transitions: next/back/jump/exit.
+- `runtime/resume-store.ts` persists and restores workflow checkpoints.
+- `runtime/dispatch.ts` maps parser result to action contract.
+
+## Related code files
+- Modify: none (greenfield)
+- Create:
+  - `src/runtime/mode-resolver.ts`
+  - `src/runtime/engine.ts`
+  - `src/runtime/state-machine.ts`
+  - `src/runtime/resume-store.ts`
+  - `src/runtime/dispatch.ts`
+  - `src/runtime/runtime-context.ts`
+- Delete: none
+
+## Implementation Steps
+1. Implement mode resolver with strict decision tree.
+2. Implement shared runtime executor and result envelope.
+3. Implement workflow state-machine and transition guards including jump.
+4. Implement resume checkpoint store and restore path.
+5. Wire dispatch path from parser to runtime.
+
+## Todo list
+- [x] Mode resolver implemented
+- [x] Runtime engine implemented
+- [x] State machine with jump implemented
+- [x] Resume checkpoint store implemented
+- [x] Dispatch integration complete
+
+## Success Criteria
+- Same action handler runs correctly from both TUI and command invocation.
+- Missing args in non-TTY returns strict help/error output without prompt hang.
+
+## Risk Assessment
+- Risk: mode ambiguity in mixed argument scenarios.
+  - Mitigation: explicit precedence rules and diagnostics.
+
+## Security Considerations
+- Validate parsed input before dispatch.
+- Enforce safe defaults for cancellation/timeouts.
+
+## Next steps
+- Build TUI component adapters and edge policies in Phase 03.

package/plans/260209-1547-hub-dual-runtime-framework/phase-03-tui-components-and-policies.md

@@ -0,0 +1,71 @@
+# Phase 03 — TUI components and policies
+
+## Context links
+- Parent plan: `./plan.md`
+- Depends on: `./phase-02-runtime-and-state-machine.md`
+- Research: `./research/researcher-01-report.md`
+
+## Overview
+- Date: 2026-02-09
+- Description: implement clack-based component adapters, accessibility footer, and policy-driven edge handling.
+- Priority: P1
+- Implementation status: complete
+- Review status: complete
+
+## Key Insights
+- Use clack primitives fully, wrap them in framework contracts.
+- Accessibility line helps both humans and AI snapshots understand current state.
+
+## Requirements
+- Functional:
+  - Support clack prompts/core patterns (select, multiselect, confirm, text, groups, task logs/spinners).
+  - Implement framework wrapper components with validation hooks.
+  - Add accessibility footer with current node, selection, keybind hints.
+  - Enforce ESC/Ctrl+C/error/invalid-input policies with configurable actions.
+- Non-functional:
+  - Async-safe prompt flows.
+  - Non-TTY fallback to runtime resolver path.
+
+## Architecture
+- `tui/component-adapters/*` wraps clack APIs.
+- `tui/accessibility-footer.ts` renders stable context text.
+- `tui/interrupt-handlers.ts` maps cancel signals to policy engine.
+
+## Related code files
+- Modify: none (greenfield)
+- Create:
+  - `src/tui/component-adapters/select.ts`
+  - `src/tui/component-adapters/multiselect.ts`
+  - `src/tui/component-adapters/confirm.ts`
+  - `src/tui/component-adapters/text.ts`
+  - `src/tui/component-adapters/group.ts`
+  - `src/tui/accessibility-footer.ts`
+  - `src/tui/interrupt-handlers.ts`
+- Delete: none
+
+## Implementation Steps
+1. Implement component wrappers and shared adapter interfaces.
+2. Implement input validation and cancellation normalization.
+3. Add accessibility footer renderer.
+4. Integrate policy engine hooks for edge-case handling.
+
+## Todo list
+- [x] Core component wrappers implemented
+- [x] Validation/cancel normalization implemented
+- [x] Accessibility footer implemented
+- [x] Policy hooks integrated
+
+## Success Criteria
+- TUI flows execute with consistent keybinding/interrupt behavior.
+- Accessibility footer appears on each interactive step.
+
+## Risk Assessment
+- Risk: terminal compatibility differences.
+  - Mitigation: isolate adapter layer and test across OS.
+
+## Security Considerations
+- Sanitize untrusted text displayed in terminal.
+- Avoid leaking sensitive values in prompts and logs.
+
+## Next steps
+- Implement strict help contract and hierarchy in Phase 04.

package/plans/260209-1547-hub-dual-runtime-framework/phase-04-help-system-and-ai-readability.md

@@ -0,0 +1,69 @@
+# Phase 04 — Help system and AI readability
+
+## Context links
+- Parent plan: `./plan.md`
+- Depends on: `./phase-01-foundation-and-contracts.md`, `./phase-02-runtime-and-state-machine.md`
+- Research: `./research/researcher-01-report.md`
+
+## Overview
+- Date: 2026-02-09
+- Description: implement strict hierarchical help outputs for module/action/use-case discovery.
+- Priority: P1
+- Implementation status: complete
+- Review status: complete
+
+## Key Insights
+- Text-only can be AI-safe if sections are fixed and deterministic.
+- Help hierarchy must mirror command hierarchy exactly.
+
+## Requirements
+<!-- Updated: Validation Session 1 - lock text-only strict help contract for MVP -->
+- Functional:
+  - Implement `hub -h`, `hub -h <module>`, `hub -h <module> <use-case>`.
+  - Render strict text-only sections with stable ordering and markers.
+  - Include keybindings/navigation notes for TUI-relevant actions.
+  - Enforce every action defines complete help metadata.
+- Non-functional:
+  - No prose drift across runs.
+  - Human-readable and parser-friendly formatting.
+
+## Architecture
+- `help-registry-view` queries contracts and returns normalized help model.
+- `help-renderer` outputs strict sections and delimiters.
+- `diagnostic-renderer` prints missing args/error guidance in same format family.
+
+## Related code files
+- Modify: none (greenfield)
+- Create:
+  - `src/help/help-model.ts`
+  - `src/help/help-renderer.ts`
+  - `src/help/hierarchy-resolver.ts`
+  - `src/cli/help-command.ts`
+- Delete: none
+
+## Implementation Steps
+1. Define strict help section schema and formatting rules.
+2. Implement hierarchy resolver for module/action/use-case.
+3. Implement renderers for normal help and error-help.
+4. Wire help command to parser/runtime paths.
+
+## Todo list
+- [x] Help schema defined
+- [x] Hierarchy resolver implemented
+- [x] Renderer implemented
+- [x] CLI integration complete
+
+## Success Criteria
+- All help levels print deterministic sections.
+- Agent can discover command usage without interacting with TUI.
+
+## Risk Assessment
+- Risk: over-verbose help harms scanability.
+  - Mitigation: concise defaults + expanded use-case mode.
+
+## Security Considerations
+- Ensure help/examples never include secrets.
+- Validate untrusted metadata before rendering.
+
+## Next steps
+- Add test matrix and quality gates in Phase 05.