@levu/snap 0.1.0

package/plans/260209-1547-hub-dual-runtime-framework/phase-05-testing-and-quality-gates.md

@@ -0,0 +1,79 @@
+# Phase 05 — Testing and quality gates
+
+## Context links
+- Runtime/help phases: `./phase-02-runtime-and-state-machine.md`, `./phase-04-help-system-and-ai-readability.md`
+- Research: `./research/researcher-02-report.md`
+- Overview: `./plan.md`
+
+## Overview
+- Priority: P1
+- Status: complete
+- Description: define deterministic tests and CI gates for contract correctness, runtime behavior, help stability, and security guardrails.
+
+## Key Insights
+- Need 4-layer testing: unit, integration, transcript snapshot, e2e smoke.
+- Deterministic env controls are mandatory for terminal tests.
+- Security tests must cover injection, redaction, and escape sanitization.
+
+## Requirements
+<!-- Updated: Validation Session 1 - require 3-OS CI matrix for MVP -->
+- Functional:
+  - Add tests for contract triad enforcement.
+  - Add runtime mode-selection tests (default TUI vs auto non-interactive).
+  - Add help output contract/snapshot tests.
+  - Add cancel/timeout/exit code tests.
+- Non-functional:
+  - CI matrix includes Linux + macOS + Windows and target Node versions.
+  - Flake policy documented and enforced.
+
+## Architecture
+- Test layers:
+  - unit: validators, resolver, state transitions.
+  - integration: runtime + adapters + registry.
+  - transcript: deterministic output frames.
+  - e2e-smoke: critical user paths with real process.
+- Quality gates:
+  - lint + typecheck + tests + security assertions.
+
+## Related code files
+- Modify: none (greenfield)
+- Create:
+  - `vitest.config.ts`
+  - `tests/unit/*.test.ts`
+  - `tests/integration/*.test.ts`
+  - `tests/transcript/*.test.ts`
+  - `tests/e2e/*.test.ts`
+  - `.github/workflows/ci.yml`
+- Delete: none
+
+## Implementation Steps
+1. Configure test tooling and deterministic env defaults.
+2. Implement unit and integration suites for core/runtime/help.
+3. Add transcript snapshots with stable formatter policy.
+4. Add e2e smoke for top workflows.
+5. Configure CI gates and failure policy.
+
+## Todo list
+- [x] Test tooling configured
+- [x] Unit/integration suites implemented
+- [x] Transcript snapshots implemented
+- [x] E2E smoke implemented
+- [x] CI gates and matrix configured
+
+## Success Criteria
+- All quality gates pass on target matrix.
+- Runtime/help regressions caught before merge.
+- Security-sensitive behaviors covered by tests.
+
+## Risk Assessment
+- Risk: flaky terminal tests.
+  - Mitigation: deterministic env + focused e2e scope.
+- Risk: long CI runtime.
+  - Mitigation: split jobs, run smoke in PR and full nightly optional.
+
+## Security Considerations
+- Test command injection defenses and unsafe shell wrapping.
+- Test secret redaction and terminal escape sanitization paths.
+
+## Next steps
+- Deliver sample modules and adoption assets in Phase 06.

package/plans/260209-1547-hub-dual-runtime-framework/phase-06-sample-modules-and-adoption.md

@@ -0,0 +1,75 @@
+# Phase 06 — Sample modules and adoption
+
+## Context links
+- Plan: `./plan.md`
+- Prior phases: `./phase-01-foundation-and-contracts.md` to `./phase-05-testing-and-quality-gates.md`
+- Planner report: `./reports/planner-report.md`
+
+## Overview
+- Priority: P2
+- Status: complete
+- Description: add reference modules and adoption docs proving framework contract and runtime behavior for real teams.
+
+## Key Insights
+- Adoption fails if first module feels heavy.
+- Sample should cover both interactive and non-interactive execution.
+- Keep examples realistic but small.
+
+## Requirements
+- Functional:
+  - Provide 2 sample modules with at least 2 actions each.
+  - Each sample action includes TUI flow, commandline args/options, and complete help output.
+  - Include quickstart for module authors.
+- Non-functional:
+  - Minimal boilerplate.
+  - Consistent naming and folder conventions.
+
+## Architecture
+- Module shape:
+  - `module/index` exports action contracts.
+  - Action contracts registered via public API bootstrap.
+- Adoption assets:
+  - quickstart doc + “build first action in 10 minutes” path.
+
+## Related code files
+- Modify:
+  - `README.md` (create if absent)
+  - `src/cli-entry.ts`
+- Create:
+  - `src/modules/sample-system/module.ts`
+  - `src/modules/sample-content/module.ts`
+  - `docs/module-authoring-guide.md`
+  - `docs/help-contract-spec.md`
+- Delete: none
+
+## Implementation Steps
+1. Create two sample modules with distinct action types.
+2. Register modules into bootstrap entry.
+3. Validate each action triad and help coverage.
+4. Write concise adoption docs and migration notes.
+5. Run final quality gate suite.
+
+## Todo list
+- [x] Sample modules implemented
+- [x] Bootstrap wiring complete
+- [x] Authoring guide drafted
+- [x] Help contract spec drafted
+- [x] Final tests and smoke run complete
+
+## Success Criteria
+- New developer can add one action using docs without reading core internals.
+- Sample actions run in TUI default and auto non-interactive mode.
+- Help outputs satisfy strict contract for all sample actions.
+
+## Risk Assessment
+- Risk: samples diverge from real architecture.
+  - Mitigation: enforce same contract checks as production modules.
+- Risk: docs stale quickly.
+  - Mitigation: docs tied to tested examples in CI.
+
+## Security Considerations
+- Samples avoid unsafe command execution patterns.
+- Docs include explicit secret-handling and logging redaction notes.
+
+## Next steps
+- Hand off to implementation agent with phase-by-phase checklist execution.

package/plans/260209-1547-hub-dual-runtime-framework/plan.md

@@ -0,0 +1,105 @@
+---
+title: "Hub Dual-Runtime Framework Plan"
+description: "Implementation plan for a contract-first TypeScript framework that unifies TUI-default and auto headless CLI execution with strict AI-readable help."
+status: completed
+priority: P2
+effort: 6 phases / ~8-10d
+branch: no-git
+tags: [framework, cli, tui, clack, bombsh-args, ai-readable-help, state-machine]
+created: 2026-02-09
+---
+
+# Plan Overview
+
+Goal: build `hub` framework for human + AI terminal usage with one action contract enforcing `tui + commandline + help`.
+
+## Inputs
+- Scout: `./scout/scout-01-report.md`
+- Research: `./research/researcher-01-report.md`, `./research/researcher-02-report.md`
+- Summary: `./reports/planner-report.md`
+
+## Locked decisions
+- Default runtime mode = TUI.
+- Auto non-interactive run when required CLI args are sufficient.
+- Use clack prompts/core broadly.
+- In-process module loading only.
+- Text-first strict help sections for AI/human readability.
+- Workflow model = state machine.
+
+## Phases
+1. **Phase 01** (complete, 100%)
+   - Foundation contracts and triad enforcement
+   - `./phase-01-foundation-and-contracts.md`
+2. **Phase 02** (complete, 100%)
+   - Runtime resolver and shared state-machine engine
+   - `./phase-02-runtime-and-state-machine.md`
+3. **Phase 03** (complete, 100%)
+   - TUI component adapters and policy handling
+   - `./phase-03-tui-components-and-policies.md`
+4. **Phase 04** (complete, 100%)
+   - Hierarchical help system and AI-readable format
+   - `./phase-04-help-system-and-ai-readability.md`
+5. **Phase 05** (complete, 100%)
+   - Testing pyramid and quality/security gates
+   - `./phase-05-testing-and-quality-gates.md`
+6. **Phase 06** (complete, 100%)
+   - Sample modules and adoption assets
+   - `./phase-06-sample-modules-and-adoption.md`
+
+## Dependency chain
+`01 -> 02 -> 03 -> 04 -> 05 -> 06`
+
+## Delivery gates
+- Triad enforcement active at registration.
+- Runtime mode resolver deterministic in TTY/non-TTY.
+- Help output deterministic across all hierarchy levels.
+- Test matrix green on target OS/Node set.
+
+## Open items to confirm
+- Package layout preference (single package vs monorepo).
+- CI provider and mandatory OS/Node support for MVP.
+
+## Validation Log
+
+### Session 1 — 2026-02-09
+**Trigger:** Initial plan creation validation interview.
+**Questions asked:** 4
+
+#### Questions & Answers
+
+1. **[Architecture]** Which package layout should we lock for MVP implementation?
+   - Options: Single package (Recommended) | Monorepo now | Hybrid scaffold
+   - **Answer:** Single package (Recommended)
+   - **Rationale:** Reduces setup complexity, keeps velocity high for greenfield MVP.
+
+2. **[Risk]** What OS matrix do you want as required quality gate for MVP?
+   - Options: Linux + macOS + Windows (Recommended) | Linux only | Linux + macOS
+   - **Answer:** Linux + macOS + Windows (Recommended)
+   - **Rationale:** Terminal behavior differs by OS; cross-platform gate is required for framework trust.
+
+3. **[Scope]** How should we finalize the help output contract for MVP?
+   - Options: Text-only strict sections (Recommended) | Text + optional JSON | Text + required JSON
+   - **Answer:** Text-only strict sections (Recommended)
+   - **Rationale:** Aligns product goal and keeps MVP focused on deterministic text contract.
+
+4. **[Tradeoffs]** How much state-machine complexity should we include in MVP?
+   - Options: No resume/jump in MVP (Recommended) | Add jump only | Add jump + resume
+   - **Answer:** Add jump + resume
+   - **Rationale:** Stronger workflow UX requirement accepted despite extra implementation cost.
+
+#### Confirmed Decisions
+- Package layout: single package — optimize MVP speed.
+- CI OS gate: Linux + macOS + Windows — enforce terminal compatibility.
+- Help contract: text-only strict sections — deterministic AI/human read path.
+- State-machine scope: include jump + resume — richer workflow support in MVP.
+
+#### Action Items
+- [ ] Update phase-02 with jump + resume architecture and tasks.
+- [ ] Update phase-05 with mandatory 3-OS CI matrix requirement.
+- [ ] Mark package layout and text-help contract as locked in phase docs.
+
+#### Impact on Phases
+- Phase 01: record single-package architecture decision.
+- Phase 02: add persisted resume + node jump support requirements/architecture/tests.
+- Phase 04: lock text-only strict help contract in requirements.
+- Phase 05: mandate Linux+macOS+Windows CI matrix for MVP.

package/plans/260209-1547-hub-dual-runtime-framework/reports/planner-report.md

@@ -0,0 +1,27 @@
+# Planner Report
+
+## Summary
+Created full implementation plan for hub dual-runtime framework in active plan dir. Plan is contract-first, state-machine-driven, and enforces per-action triad: `tui + commandline + help`. Sequence is 6 phases from foundation to adoption, with strict quality gates.
+
+## Rationale
+- YAGNI: skip dynamic plugin loading, marketplace, resumable sessions in v1.
+- KISS: one execution engine, two adapters, one help contract.
+- DRY: single action contract generates runtime behavior and help surface.
+- User-lock alignment: default TUI, auto non-interactive run on sufficient args, clack-heavy interaction model, in-process loading, text-only machine-readable help.
+
+## Key trade-offs
+- Chosen: rigid text help contract over flexible prose.
+  - Pro: deterministic for AI/tools.
+  - Con: less expressive docs style.
+- Chosen: in-process module loading only.
+  - Pro: simpler security/runtime model.
+  - Con: no external plugin discovery in v1.
+- Chosen: state-machine orchestration for both runtime paths.
+  - Pro: predictable edge handling.
+  - Con: upfront modeling cost.
+
+## Unresolved questions
+1. Repo/package layout preference: single package vs monorepo from day 1?
+2. Canonical `@bomb.sh/args` reference/API location to lock exact parser contract?
+3. CI provider preference and mandatory OS coverage at MVP gate?
+4. Should machine-readable help include optional JSON mode later, while still keeping text contract primary?

package/plans/260209-1547-hub-dual-runtime-framework/research/researcher-01-report.md

@@ -0,0 +1,166 @@
+# Researcher 01 Report
+
+- Conducted: 2026-02-09 (Asia/Saigon)
+- Scope: greenfield TypeScript Node.js framework unifying TUI + CLI for human + AI operators
+- Bias: YAGNI/KISS/DRY, minimal moving parts, deterministic output
+
+## Executive takeaways
+
+1. Use **single-source action contracts** as core artifact; generate CLI, TUI, and help from same schema.
+2. Treat TUI as a **state machine wrapper** over the same command executor used by CLI.
+3. For AI compatibility, make help output **strict text sections** + stable keys (no ANSI, no prose drift).
+4. `@clack/prompts` is strong for interactive UX, but cancellation/interrupt handling must be centralized and explicit.
+5. `@bomb.sh/args` is suitable for typed parsing + discoverability; pair it with contract-driven metadata for rich help.
+
+---
+
+## 1) Architecture patterns: single-source contracts for TUI + CLI + docs
+
+### Recommended pattern: Action Contract Registry
+Define every action once:
+
+```ts
+type ActionContract = {
+  id: "module.action.useCase";
+  summary: string;
+  args: ArgSpec[];
+  options: OptionSpec[];
+  interactive: PromptPlan[];   // optional
+  execute: (ctx: RunContext) => Promise<Result>;
+  examples: string[];
+  aiNotes?: string[];
+};
+```
+
+Build layers:
+
+- **Contract layer**: pure metadata + validator + executor binding.
+- **Execution layer**: shared runtime, idempotent, no UI logic.
+- **Interface adapters**:
+  - CLI adapter (`@bomb.sh/args`) maps argv -> ctx
+  - TUI adapter (`@clack/prompts`) maps prompts -> same ctx
+  - Help adapter renders strict docs from contract
+
+Why this wins:
+- DRY: one action definition.
+- KISS: no duplicated business logic between TUI/CLI.
+- YAGNI: only add prompt plans for actions that need interactivity.
+
+### Contract-driven generation targets
+- Command tree (`module action [use-case]`)
+- Flags and defaults
+- Validation rules and coercion
+- Example snippets
+- Help docs (human + AI mode)
+
+---
+
+## 2) Clack capabilities/constraints relevant here
+
+Observed/known patterns from official package/docs:
+
+- Prompt primitives: `select`, `multiselect`, `confirm`, text-like inputs.
+- Flow control: `isCancel(value)` + `cancel()` pattern after each prompt.
+- Interrupt model: ESC/Ctrl+C should map to unified cancel path (do not continue execution).
+- Async tasks/logging: spinner/task progress style pattern (`intro/outro`, task wrappers) for long-running steps.
+- Grouped flows: compose multiple prompts sequentially, capture object payload, short-circuit on cancel.
+
+Practical constraints:
+- Terminal UX can break under non-TTY; detect and auto-fallback to CLI flags.
+- Avoid deep nested prompt flows; keep <=3 levels to reduce abandonment.
+- Cancellation must be treated as first-class result (`status: "cancelled"`) not exception spam.
+
+---
+
+## 3) `@bomb.sh/args` usage patterns for robust parsing/discoverability
+
+Recommended usage model:
+
+- Keep top-level parser thin; load command modules lazily.
+- Explicit command metadata in contract:
+  - `name`, `aliases`, `summary`, `examples`, `deprecated`, `hidden`
+- Use parser for:
+  - strict unknown-flag errors
+  - typed coercion
+  - defaulting
+  - per-command help
+- Discoverability:
+  - support `--help`, `help <module>`, `help <module> <action>`
+  - add “related commands” list from same registry
+  - always print next-step hints after errors
+
+Rule: parser does parsing; **contract executor does business logic**.
+
+---
+
+## 4) Help system design (hierarchical, AI-optimized text-only)
+
+### Output contract (strict sections, stable ordering)
+
+For every help response, always print:
+
+1. `PATH` (module/action/use-case)
+2. `PURPOSE`
+3. `USAGE`
+4. `ARGS`
+5. `OPTIONS`
+6. `EXAMPLES`
+7. `EXIT_CODES`
+8. `RELATED`
+9. `MACHINE_READABLE_SCHEMA` (compact JSON)
+
+Design notes:
+- No ANSI colors in AI mode.
+- No variable phrasing; keep section headers exact.
+- Keep line lengths predictable; avoid tables if parser stability matters.
+- Add `--format ai|human|json`; default human for TTY, ai for non-interactive agents.
+
+---
+
+## 5) Edge-case navigation policies for state-machine terminal UX
+
+Use finite states:
+
+`Idle -> CollectingInput -> Validating -> Confirming -> Executing -> Completed | Cancelled | Failed`
+
+Mandatory policies:
+- Invalid input: inline error + retry count (max 3), then suggest `--help`.
+- Cancel (ESC/Ctrl+C): immediate transition to `Cancelled`, print resumable hint.
+- Go back: support one-step back in prompt flows (`Back` option in selects).
+- Jump: allow “jump to section” only in long forms; otherwise YAGNI.
+- Exit: always available, same semantics as cancel.
+- Recoverability: if execution not started, lossless exit; if started, print rollback/retry guidance.
+
+Error taxonomy:
+- `E_INPUT_INVALID`
+- `E_USER_CANCELLED`
+- `E_RUNTIME_FAILURE`
+- `E_DEPENDENCY_UNAVAILABLE`
+
+Use same codes in CLI/TUI/help docs for deterministic automation.
+
+---
+
+## Suggested baseline stack (minimal)
+
+- Node.js LTS + TypeScript strict mode
+- `@bomb.sh/args` for argv parsing
+- `@clack/prompts` for interactive flows
+- `zod` (or equivalent) for contract validation
+- one shared `ActionRegistry` package inside monorepo/app
+
+---
+
+## Source URLs
+
+- https://www.npmjs.com/package/@clack/prompts
+- https://github.com/bombshell-dev/clack
+- https://bomb.sh
+- https://www.npmjs.com/search?q=%40bomb.sh%2Fargs
+- https://github.com/search?q=%40bomb.sh%2Fargs&type=repositories
+
+## Unresolved questions
+
+- Exact latest API surface of `@bomb.sh/args` (official reference pages were not directly retrievable in-session).
+- Preferred canonical doc URL for Bomb.sh args module (site path ambiguity).
+- Whether framework should support resumable prompt sessions (persisted checkpoints) in v1 or defer (YAGNI).

package/plans/260209-1547-hub-dual-runtime-framework/research/researcher-02-report.md

@@ -0,0 +1,87 @@
+# Researcher 02 Report
+
+_Date: 2026-02-09 (Asia/Saigon)_
+_Target: TypeScript Node.js framework for unified CLI/TUI (human + AI)_
+
+## Executive Summary
+- Use a 4-layer test strategy: unit, integration, transcript snapshot, e2e.
+- Use `tsup` for build outputs and `tsx` for dev ergonomics.
+- Keep plugin/module loading in-process and explicit.
+- Guardrails needed for command injection, secret leakage, and terminal escape issues.
+
+## 1) Testing Strategy for Terminal Frameworks
+Test pyramid:
+1. Unit (majority): parser, validation, flow transitions
+2. Integration: command execution and IO behavior
+3. Transcript snapshot: deterministic terminal output frames/events
+4. E2E: smoke critical flows via real process/PTY
+
+Flake controls:
+- deterministic env (TZ, locale, seeded randomness)
+- retries only for e2e/transcript where justified
+- quarantine policy for unstable tests
+
+CI matrix (minimal):
+- OS: ubuntu, macos, windows
+- Node: active LTS + current
+- job split: lint/typecheck/unit, integration, transcript, e2e-smoke
+
+## 2) TypeScript Packaging/Build
+Baseline strategy:
+- Build with `tsup` (ESM/CJS + d.ts)
+- Dev run with `tsx`
+- Published CLI uses compiled `bin` entry
+- `exports` map for framework API surface
+
+Suggested shape:
+- `src/core/*`
+- `src/cli-entry.ts`
+- `src/public-api.ts`
+- outputs in `dist/`
+
+## 3) Developer Bootstrap API Patterns
+Recommended fluent bootstrap style:
+- `createHub().use(...).command(...).start()`
+- capability plugins with explicit setup/dispose hooks
+- command objects with metadata + run(ctx,args)
+- typed context injection and lifecycle hooks
+
+Avoid:
+- hidden globals
+- excessive DI abstraction in v1
+- implicit runtime auto-discovery magic
+
+## 4) Security + Reliability Guardrails
+Security:
+- never shell-execute unsanitized input
+- redact secrets from logs/transcripts
+- sanitize untrusted terminal output
+- plugin compatibility checks + trust policy
+
+Reliability:
+- timeouts and cancellation via AbortController
+- stable exit code taxonomy
+- crash-safe top-level handlers
+- atomic writes for config/session artifacts
+
+Ship gate checklist:
+- shell wrapper audit
+- secret redaction tests
+- transcript sanitization
+- plugin version checks
+- cross-platform path/encoding tests
+
+## Sources
+- https://nodejs.org/api/packages.html
+- https://github.com/egoist/tsup
+- https://github.com/privatenumber/tsx
+- https://vitest.dev/guide/
+- https://playwright.dev/docs/test-cli
+- https://owasp.org/www-community/attacks/Command_Injection
+- https://owasp.org/www-project-top-ten/
+- https://oclif.io/
+
+## Unresolved questions
+1. Keep plugin runtime local-only in v1 or support dynamic package loading?
+2. Preferred transcript golden format: ANSI snapshot vs structured events vs both?
+3. Need compliance constraints (e.g., FIPS) now or later?

package/plans/260209-1547-hub-dual-runtime-framework/scout/scout-01-report.md

@@ -0,0 +1,24 @@
+# Scout Report
+
+## Relevant Files
+- `/Users/khang/Documents/repo/snap/` - project root exists, minimal content.
+- `/Users/khang/Documents/repo/snap/plans/` - created for planning artifacts.
+- `/Users/khang/Documents/repo/snap/plans/260209-1547-hub-dual-runtime-framework/` - active plan directory.
+- `/Users/khang/Documents/repo/snap/plans/260209-1547-hub-dual-runtime-framework/research/` - research reports location.
+- `/Users/khang/Documents/repo/snap/plans/260209-1547-hub-dual-runtime-framework/reports/` - planning reports location.
+- `/Users/khang/Documents/repo/snap/plans/260209-1547-hub-dual-runtime-framework/scout/` - scout reports location.
+
+## Findings
+- Repository currently has no discovered source code files.
+- `README.md` does not exist in project root.
+- `docs/` directory does not exist.
+- Planning must assume greenfield bootstrap with no existing architecture constraints.
+
+## Implications for Plan
+- Include bootstrap phases for project scaffold, coding standards baseline, test harness, and sample modules.
+- Include docs bootstrap inside plan scope where needed for framework adoption.
+
+## Unresolved Questions
+1. Should initial implementation be single package or monorepo layout?
+2. Should framework include built-in templates/generator in v1?
+3. Any required CI provider preference (GitHub Actions vs other)?

package/src/cli/help-command.ts

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

package/src/cli-entry.ts

@@ -0,0 +1,83 @@
+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: string[]): { moduleId?: string; actionId?: string; args: Record<string, string | boolean> } => {
+  const args: Record<string, string | boolean> = {};
+  const positional: string[] = [];
+
+  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: string[], isTTY = Boolean(process.stdout.isTTY)): Promise<number> => {
+  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: unknown) => {
+      process.stderr.write(`${error instanceof Error ? error.message : 'Unknown CLI error'}\n`);
+      process.exitCode = 1;
+    });
+}

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

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