@levu/snap 0.1.0

package/dist/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/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/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/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/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/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/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/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/runtime/runtime-context.js

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

package/dist/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/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/cli/help-command.d.ts

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

package/dist/src/cli/help-command.js

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

package/dist/src/cli-entry.d.ts

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

package/dist/src/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/src/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/src/core/contracts/action-contract.js

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

package/dist/src/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/src/core/contracts/help-contract.js

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

package/dist/src/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/src/core/contracts/module-contract.js

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

package/dist/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/help/help-model.js

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

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