@levu/snap 0.1.0

package/src/core/contracts/help-contract.ts

@@ -0,0 +1,20 @@
+export interface HelpArgumentSpec {
+  name: string;
+  required: boolean;
+  description: string;
+  example?: string;
+}
+
+export interface HelpUseCaseSpec {
+  name: string;
+  description: string;
+  command: string;
+}
+
+export interface HelpContract {
+  summary: string;
+  args: HelpArgumentSpec[];
+  examples: string[];
+  useCases: HelpUseCaseSpec[];
+  keybindings: string[];
+}

package/src/core/contracts/module-contract.ts

@@ -0,0 +1,7 @@
+import type { ActionContract } from './action-contract.js';
+
+export interface ModuleContract {
+  moduleId: string;
+  description: string;
+  actions: ActionContract[];
+}

package/src/core/errors/framework-errors.ts

@@ -0,0 +1,26 @@
+export enum ExitCode {
+  SUCCESS = 0,
+  VALIDATION_ERROR = 2,
+  INTERRUPTED = 130,
+  INTERNAL_ERROR = 1
+}
+
+export enum FrameworkErrorCode {
+  TRIAD_INCOMPLETE = 'TRIAD_INCOMPLETE',
+  DUPLICATE_ACTION = 'DUPLICATE_ACTION',
+  DUPLICATE_MODULE = 'DUPLICATE_MODULE',
+  MODULE_NOT_FOUND = 'MODULE_NOT_FOUND',
+  ACTION_NOT_FOUND = 'ACTION_NOT_FOUND',
+  INVALID_TRANSITION = 'INVALID_TRANSITION'
+}
+
+export class FrameworkError extends Error {
+  constructor(
+    public readonly code: FrameworkErrorCode,
+    public readonly exitCode: ExitCode,
+    message: string
+  ) {
+    super(message);
+    this.name = 'FrameworkError';
+  }
+}

package/src/core/registry/action-registry.ts

@@ -0,0 +1,94 @@
+import type { ActionContract } from '../contracts/action-contract.js';
+import type { ModuleContract } from '../contracts/module-contract.js';
+import {
+  ExitCode,
+  FrameworkError,
+  FrameworkErrorCode
+} from '../errors/framework-errors.js';
+
+export interface ActionRef {
+  moduleId: string;
+  action: ActionContract;
+}
+
+export class ActionRegistry {
+  private readonly modules = new Map<string, ModuleContract>();
+  private readonly actions = new Map<string, ActionRef>();
+
+  registerModule(moduleContract: ModuleContract): void {
+    if (this.modules.has(moduleContract.moduleId)) {
+      throw new FrameworkError(
+        FrameworkErrorCode.DUPLICATE_MODULE,
+        ExitCode.VALIDATION_ERROR,
+        `Duplicate module registration: ${moduleContract.moduleId}`
+      );
+    }
+
+    this.modules.set(moduleContract.moduleId, moduleContract);
+
+    for (const action of moduleContract.actions) {
+      this.assertTriad(moduleContract.moduleId, action);
+      const key = this.actionKey(moduleContract.moduleId, action.actionId);
+      if (this.actions.has(key)) {
+        throw new FrameworkError(
+          FrameworkErrorCode.DUPLICATE_ACTION,
+          ExitCode.VALIDATION_ERROR,
+          `Duplicate action registration: ${key}`
+        );
+      }
+      this.actions.set(key, { moduleId: moduleContract.moduleId, action });
+    }
+  }
+
+  listModules(): ModuleContract[] {
+    return [...this.modules.values()].sort((a, b) => a.moduleId.localeCompare(b.moduleId));
+  }
+
+  getModule(moduleId: string): ModuleContract {
+    const moduleContract = this.modules.get(moduleId);
+    if (!moduleContract) {
+      throw new FrameworkError(
+        FrameworkErrorCode.MODULE_NOT_FOUND,
+        ExitCode.VALIDATION_ERROR,
+        `Module not found: ${moduleId}`
+      );
+    }
+    return moduleContract;
+  }
+
+  getAction(moduleId: string, actionId: string): ActionContract {
+    const key = this.actionKey(moduleId, actionId);
+    const actionRef = this.actions.get(key);
+    if (!actionRef) {
+      throw new FrameworkError(
+        FrameworkErrorCode.ACTION_NOT_FOUND,
+        ExitCode.VALIDATION_ERROR,
+        `Action not found: ${key}`
+      );
+    }
+    return actionRef.action;
+  }
+
+  private actionKey(moduleId: string, actionId: string): string {
+    return `${moduleId}.${actionId}`;
+  }
+
+  private assertTriad(moduleId: string, action: ActionContract): void {
+    const hasTui = Array.isArray(action.tui?.steps) && action.tui.steps.length > 0;
+    const hasCommandline = Array.isArray(action.commandline?.requiredArgs);
+    const hasHelp =
+      typeof action.help?.summary === 'string' &&
+      Array.isArray(action.help?.args) &&
+      Array.isArray(action.help?.examples) &&
+      Array.isArray(action.help?.useCases) &&
+      Array.isArray(action.help?.keybindings);
+
+    if (!hasTui || !hasCommandline || !hasHelp) {
+      throw new FrameworkError(
+        FrameworkErrorCode.TRIAD_INCOMPLETE,
+        ExitCode.VALIDATION_ERROR,
+        `Triad incomplete for action ${moduleId}.${action.actionId}`
+      );
+    }
+  }
+}

package/src/help/help-command.ts

@@ -0,0 +1,32 @@
+import { ExitCode } from '../core/errors/framework-errors.js';
+import type { ActionResultEnvelope } from '../core/contracts/action-contract.js';
+import type { ActionRegistry } from '../core/registry/action-registry.js';
+import { resolveHelpHierarchy } from './hierarchy-resolver.js';
+import { renderHelp } from './help-renderer.js';
+
+export interface HelpCommandInput {
+  registry: ActionRegistry;
+  moduleId?: string;
+  actionId?: string;
+}
+
+export const runHelpCommand = (input: HelpCommandInput): ActionResultEnvelope<string> => {
+  const modules = input.registry.listModules();
+  const views = resolveHelpHierarchy(modules, input.moduleId, input.actionId);
+
+  if (views.length === 0) {
+    return {
+      ok: false,
+      mode: 'commandline',
+      exitCode: ExitCode.VALIDATION_ERROR,
+      errorMessage: 'No help target found'
+    };
+  }
+
+  return {
+    ok: true,
+    mode: 'commandline',
+    exitCode: ExitCode.SUCCESS,
+    data: renderHelp(views)
+  };
+};

package/src/help/help-model.ts

@@ -0,0 +1,10 @@
+export interface HelpSection {
+  title: 'MODULE' | 'ACTIONS' | 'SUMMARY' | 'ARGS' | 'EXAMPLES' | 'USE-CASES' | 'KEYBINDINGS';
+  lines: string[];
+}
+
+export interface ActionHelpView {
+  moduleId: string;
+  actionId?: string;
+  sections: HelpSection[];
+}

package/src/help/help-renderer.ts

@@ -0,0 +1,21 @@
+import type { ActionHelpView, HelpSection } from './help-model.js';
+
+const renderSection = (section: HelpSection): string => {
+  const header = `## ${section.title}`;
+  const lines =
+    section.lines.length > 0 ? section.lines.map((line) => `- ${line}`).join('\n') : '- (none)';
+  return `${header}\n${lines}`;
+};
+
+export const renderHelp = (views: ActionHelpView[]): string =>
+  views
+    .map((view) => {
+      const head = [
+        '# HELP',
+        `MODULE: ${view.moduleId}`,
+        `ACTION: ${view.actionId ?? '*'}`
+      ].join('\n');
+      const body = view.sections.map(renderSection).join('\n\n');
+      return `${head}\n\n${body}`;
+    })
+    .join('\n\n---\n\n');

package/src/help/hierarchy-resolver.ts

@@ -0,0 +1,54 @@
+import type { ActionContract } from '../core/contracts/action-contract.js';
+import type { ModuleContract } from '../core/contracts/module-contract.js';
+import type { ActionHelpView } from './help-model.js';
+
+export const resolveHelpHierarchy = (
+  modules: ModuleContract[],
+  moduleId?: string,
+  actionId?: string
+): ActionHelpView[] => {
+  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: string, action: ActionContract): ActionHelpView => ({
+  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/src/index.ts

@@ -0,0 +1,10 @@
+import { ActionRegistry } from './core/registry/action-registry.js';
+import type { ModuleContract } from './core/contracts/module-contract.js';
+
+export const createRegistry = (modules: ModuleContract[]): ActionRegistry => {
+  const registry = new ActionRegistry();
+  for (const moduleContract of modules) {
+    registry.registerModule(moduleContract);
+  }
+  return registry;
+};

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

@@ -0,0 +1,66 @@
+import type { ModuleContract } from '../../core/contracts/module-contract.js';
+import { ExitCode } from '../../core/errors/framework-errors.js';
+
+const toSlug = (value: string): string =>
+  value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-');
+
+const sampleContentModule: ModuleContract = {
+  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/src/modules/sample-system/module.ts

@@ -0,0 +1,74 @@
+import type { ModuleContract } from '../../core/contracts/module-contract.js';
+import { ExitCode } from '../../core/errors/framework-errors.js';
+
+const sampleSystemModule: ModuleContract = {
+  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/src/runtime/dispatch.ts

@@ -0,0 +1,64 @@
+import { ExitCode, FrameworkError } from '../core/errors/framework-errors.js';
+import type { ActionResultEnvelope } from '../core/contracts/action-contract.js';
+import type { ActionRegistry } from '../core/registry/action-registry.js';
+import { executeAction } from './engine.js';
+import { resolveRuntimeMode } from './mode-resolver.js';
+import { FileResumeStore } from './resume-store.js';
+
+export interface DispatchInput {
+  registry: ActionRegistry;
+  moduleId: string;
+  actionId: string;
+  args: Record<string, string | boolean>;
+  isTTY: boolean;
+  resumeFilePath?: string;
+}
+
+export const dispatchAction = async (input: DispatchInput): Promise<ActionResultEnvelope> => {
+  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/src/runtime/engine.ts

@@ -0,0 +1,59 @@
+import { ExitCode } from '../core/errors/framework-errors.js';
+import type { ActionContract, ActionResultEnvelope, RuntimeMode } from '../core/contracts/action-contract.js';
+import type { RuntimeContext } from './runtime-context.js';
+import { ResumeStore } from './resume-store.js';
+import { StateMachine, 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 const executeAction = async (input: EngineInput): Promise<ActionResultEnvelope> => {
+  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: string | undefined;
+  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: RuntimeContext = {
+    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/src/runtime/mode-resolver.ts

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

package/src/runtime/resume-store.ts

@@ -0,0 +1,53 @@
+import { promises as fs } from 'node:fs';
+import { dirname } from 'node:path';
+import type { WorkflowCheckpoint } from './state-machine.js';
+
+export interface ResumeStore {
+  load: () => Promise<WorkflowCheckpoint | undefined>;
+  save: (checkpoint: WorkflowCheckpoint) => Promise<void>;
+  clear: () => Promise<void>;
+}
+
+export class FileResumeStore implements ResumeStore {
+  constructor(private readonly filePath: string) {}
+
+  async load(): Promise<WorkflowCheckpoint | undefined> {
+    let raw: string;
+    try {
+      raw = await fs.readFile(this.filePath, 'utf8');
+    } catch (error: unknown) {
+      if (isIgnorableReadError(error)) {
+        return undefined;
+      }
+      throw error;
+    }
+
+    try {
+      return JSON.parse(raw) as WorkflowCheckpoint;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async save(checkpoint: WorkflowCheckpoint): Promise<void> {
+    await fs.mkdir(dirname(this.filePath), { recursive: true });
+    await fs.writeFile(this.filePath, JSON.stringify(checkpoint), 'utf8');
+  }
+
+  async clear(): Promise<void> {
+    try {
+      await fs.unlink(this.filePath);
+    } catch (error: unknown) {
+      if (isIgnorableReadError(error)) {
+        return;
+      }
+      throw error;
+    }
+  }
+}
+
+const isIgnorableReadError = (error: unknown): boolean =>
+  typeof error === 'object' &&
+  error !== null &&
+  'code' in error &&
+  ((error as { code?: string }).code === 'ENOENT');

package/src/runtime/runtime-context.ts

@@ -0,0 +1,10 @@
+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;
+}