@levu/snap 0.1.0

package/src/runtime/state-machine.ts

@@ -0,0 +1,77 @@
+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 class StateMachine {
+  private cursor = 0;
+  private exited = false;
+
+  constructor(
+    private readonly workflowId: string,
+    private readonly nodes: WorkflowNode[],
+    initialNodeId?: string
+  ) {
+    if (initialNodeId) {
+      const index = nodes.findIndex((node) => node.id === initialNodeId);
+      if (index >= 0) this.cursor = index;
+    }
+  }
+
+  transition(transition: StateTransition): StateMachineSnapshot {
+    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(): WorkflowNode {
+    return this.nodes[this.cursor];
+  }
+
+  checkpoint(): WorkflowCheckpoint {
+    return {
+      workflowId: this.workflowId,
+      nodeId: this.currentNode().id,
+      cursor: this.cursor,
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  snapshot(): StateMachineSnapshot {
+    return {
+      workflowId: this.workflowId,
+      nodes: this.nodes,
+      cursor: this.cursor,
+      exited: this.exited
+    };
+  }
+}

package/src/tui/accessibility-footer.ts

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

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

@@ -0,0 +1,8 @@
+export interface ConfirmPromptInput {
+  message: string;
+  initialValue?: boolean;
+}
+
+export const runConfirmPrompt = async (input: ConfirmPromptInput): Promise<boolean> => {
+  return input.initialValue ?? true;
+};

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

@@ -0,0 +1,12 @@
+export interface GroupStep<T = unknown> {
+  key: string;
+  run: () => Promise<T>;
+}
+
+export const runGroupPrompt = async <T = unknown>(steps: GroupStep<T>[]): Promise<Record<string, T>> => {
+  const result: Record<string, T> = {};
+  for (const step of steps) {
+    result[step.key] = await step.run();
+  }
+  return result;
+};

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

@@ -0,0 +1,22 @@
+export interface MultiSelectOption {
+  value: string;
+  label: string;
+}
+
+export interface MultiSelectPromptInput {
+  message: string;
+  options: MultiSelectOption[];
+  initialValues?: string[];
+}
+
+export const runMultiSelectPrompt = async (input: MultiSelectPromptInput): Promise<string[]> => {
+  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/src/tui/component-adapters/select.ts

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

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

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

package/src/tui/interrupt-handlers.ts

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

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

@@ -0,0 +1,19 @@
+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/tests/integration/runtime-dispatch.integration.test.ts

@@ -0,0 +1,23 @@
+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/tests/transcript/help.transcript.test.ts

@@ -0,0 +1,20 @@
+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/tests/unit/state-machine.test.ts

@@ -0,0 +1,22 @@
+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/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "vitest.config.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/vitest.config.ts

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