@levu/snap 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: ['**']
+  pull_request:
+
+jobs:
+  test:
+    name: test-${{ matrix.os }}-node${{ matrix.node }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run build
+      - run: npm test

package/README.md

@@ -0,0 +1,49 @@
+# Snap
+
+Snap is a contract-first TypeScript framework for terminal workflows.
+
+It runs one action contract in 2 modes:
+- **TUI-first** (default for interactive terminals)
+- **Auto CLI** (non-interactive when required args are already provided)
+
+It also enforces deterministic, text-only help so both **humans** and **AI agents** can discover commands reliably.
+
+## What this framework does
+
+- Enforces action triad at registration: `tui + commandline + help`
+- Uses one runtime engine for TUI and CLI paths
+- Supports workflow transitions: `next`, `back`, `jump`, `exit`
+- Supports resume checkpoints for interrupted flows
+- Produces stable help output hierarchy:
+  - `snap -h`
+  - `snap -h <module>`
+  - `snap -h <module> <action>`
+
+## Repository
+
+```bash
+git clone git@github.com:khanglvm/snap.git
+cd snap
+```
+
+## Quick start
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+```
+
+## Usage
+
+```bash
+npm run dev -- -h
+npm run dev -- content slugify --text="Hello World"
+npm run dev -- system node-info
+```
+
+## For module authors
+
+- `docs/module-authoring-guide.md`
+- `docs/help-contract-spec.md`

package/dist/cli/help-command.d.ts

@@ -0,0 +1 @@
+export { runHelpCommand, type HelpCommandInput } from '../help/help-command.js';

package/dist/cli/help-command.js

@@ -0,0 +1 @@
+export { runHelpCommand } from '../help/help-command.js';

package/dist/cli-entry.d.ts

@@ -0,0 +1 @@
+export declare const runCli: (argv: string[], isTTY?: boolean) => Promise<number>;

package/dist/cli-entry.js

@@ -0,0 +1,80 @@
+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
+    };
+};
+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;
+};
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (isMain) {
+    runCli(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((error) => {
+        process.stderr.write(`${error instanceof Error ? error.message : 'Unknown CLI error'}\n`);
+        process.exitCode = 1;
+    });
+}

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

@@ -0,0 +1,25 @@
+import type { HelpContract } from './help-contract.js';
+import type { RuntimeContext } from '../../runtime/runtime-context.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;
+    exitCode: number;
+    data?: T;
+    errorMessage?: string;
+}
+export interface ActionContract {
+    actionId: string;
+    description: string;
+    tui: TuiContract;
+    commandline: CommandlineContract;
+    help: HelpContract;
+    run: (context: RuntimeContext) => Promise<ActionResultEnvelope>;
+}

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

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

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

@@ -0,0 +1,18 @@
+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/dist/core/contracts/help-contract.js

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

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

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

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

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

package/dist/core/errors/framework-errors.d.ts

@@ -0,0 +1,19 @@
+export declare enum ExitCode {
+    SUCCESS = 0,
+    VALIDATION_ERROR = 2,
+    INTERRUPTED = 130,
+    INTERNAL_ERROR = 1
+}
+export declare 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 declare class FrameworkError extends Error {
+    readonly code: FrameworkErrorCode;
+    readonly exitCode: ExitCode;
+    constructor(code: FrameworkErrorCode, exitCode: ExitCode, message: string);
+}

package/dist/core/errors/framework-errors.js

@@ -0,0 +1,26 @@
+export var ExitCode;
+(function (ExitCode) {
+    ExitCode[ExitCode["SUCCESS"] = 0] = "SUCCESS";
+    ExitCode[ExitCode["VALIDATION_ERROR"] = 2] = "VALIDATION_ERROR";
+    ExitCode[ExitCode["INTERRUPTED"] = 130] = "INTERRUPTED";
+    ExitCode[ExitCode["INTERNAL_ERROR"] = 1] = "INTERNAL_ERROR";
+})(ExitCode || (ExitCode = {}));
+export var FrameworkErrorCode;
+(function (FrameworkErrorCode) {
+    FrameworkErrorCode["TRIAD_INCOMPLETE"] = "TRIAD_INCOMPLETE";
+    FrameworkErrorCode["DUPLICATE_ACTION"] = "DUPLICATE_ACTION";
+    FrameworkErrorCode["DUPLICATE_MODULE"] = "DUPLICATE_MODULE";
+    FrameworkErrorCode["MODULE_NOT_FOUND"] = "MODULE_NOT_FOUND";
+    FrameworkErrorCode["ACTION_NOT_FOUND"] = "ACTION_NOT_FOUND";
+    FrameworkErrorCode["INVALID_TRANSITION"] = "INVALID_TRANSITION";
+})(FrameworkErrorCode || (FrameworkErrorCode = {}));
+export class FrameworkError extends Error {
+    code;
+    exitCode;
+    constructor(code, exitCode, message) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.name = 'FrameworkError';
+    }
+}

package/dist/core/registry/action-registry.d.ts

@@ -0,0 +1,16 @@
+import type { ActionContract } from '../contracts/action-contract.js';
+import type { ModuleContract } from '../contracts/module-contract.js';
+export interface ActionRef {
+    moduleId: string;
+    action: ActionContract;
+}
+export declare class ActionRegistry {
+    private readonly modules;
+    private readonly actions;
+    registerModule(moduleContract: ModuleContract): void;
+    listModules(): ModuleContract[];
+    getModule(moduleId: string): ModuleContract;
+    getAction(moduleId: string, actionId: string): ActionContract;
+    private actionKey;
+    private assertTriad;
+}

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

@@ -0,0 +1,52 @@
+import { ExitCode, FrameworkError, FrameworkErrorCode } from '../errors/framework-errors.js';
+export class ActionRegistry {
+    modules = new Map();
+    actions = new Map();
+    registerModule(moduleContract) {
+        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() {
+        return [...this.modules.values()].sort((a, b) => a.moduleId.localeCompare(b.moduleId));
+    }
+    getModule(moduleId) {
+        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, actionId) {
+        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;
+    }
+    actionKey(moduleId, actionId) {
+        return `${moduleId}.${actionId}`;
+    }
+    assertTriad(moduleId, action) {
+        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/dist/help/help-command.d.ts

@@ -0,0 +1,8 @@
+import type { ActionResultEnvelope } from '../core/contracts/action-contract.js';
+import type { ActionRegistry } from '../core/registry/action-registry.js';
+export interface HelpCommandInput {
+    registry: ActionRegistry;
+    moduleId?: string;
+    actionId?: string;
+}
+export declare const runHelpCommand: (input: HelpCommandInput) => ActionResultEnvelope<string>;

package/dist/help/help-command.js

@@ -0,0 +1,21 @@
+import { ExitCode } from '../core/errors/framework-errors.js';
+import { resolveHelpHierarchy } from './hierarchy-resolver.js';
+import { renderHelp } from './help-renderer.js';
+export const runHelpCommand = (input) => {
+    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/dist/help/help-model.d.ts

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

package/dist/help/help-model.js

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

package/dist/help/help-renderer.d.ts

@@ -0,0 +1,2 @@
+import type { ActionHelpView } from './help-model.js';
+export declare const renderHelp: (views: ActionHelpView[]) => string;

package/dist/help/help-renderer.js

@@ -0,0 +1,16 @@
+const renderSection = (section) => {
+    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) => 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/dist/help/hierarchy-resolver.d.ts

@@ -0,0 +1,3 @@
+import type { ModuleContract } from '../core/contracts/module-contract.js';
+import type { ActionHelpView } from './help-model.js';
+export declare const resolveHelpHierarchy: (modules: ModuleContract[], moduleId?: string, actionId?: string) => ActionHelpView[];

package/dist/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/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/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/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/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/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/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/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>;