@levu/snap 0.1.1 → 0.2.0

package/docs/module-authoring-guide.md

@@ -0,0 +1,156 @@
+# Module Authoring Guide
+
+## Goal
+
+Define actions once with full triad contract:
+
+- `tui` flow steps (legacy `steps` or structured `flow`)
+- `commandline` required/optional args
+- `help` metadata
+
+## Minimal Module Shape
+
+```ts
+import type { ModuleContract } from '../core/contracts/module-contract.js';
+import { ExitCode } from '../core/errors/framework-errors.js';
+
+const moduleContract: ModuleContract = {
+  moduleId: 'example',
+  description: 'Example module',
+  actions: [
+    {
+      actionId: 'run',
+      description: 'Run example action',
+      tui: { steps: ['collect-input', 'confirm'] },
+      commandline: { requiredArgs: ['name'] },
+      help: {
+        summary: 'Run example with one name argument.',
+        args: [{ name: 'name', required: true, description: 'Target name' }],
+        examples: ['hub example run --name=alice'],
+        useCases: [{ name: 'default', description: 'Basic usage', command: 'hub example run --name=alice' }],
+        keybindings: ['Enter confirm', 'Esc cancel']
+      },
+      run: async (context) => ({
+        ok: true,
+        mode: context.mode,
+        exitCode: ExitCode.SUCCESS,
+        data: `hello ${String(context.args.name ?? '')}`
+      })
+    }
+  ]
+};
+
+export default moduleContract;
+```
+
+## Structured TUI Flow (Optional)
+
+Use `tui.flow` when you need explicit component/step definitions:
+
+```ts
+tui: {
+  flow: {
+    entryStepId: 'operation',
+    steps: [
+      {
+        stepId: 'operation',
+        title: 'Choose operation',
+        components: [
+          {
+            componentId: 'op',
+            type: 'select',
+            label: 'Operation',
+            arg: 'op',
+            required: true,
+            options: [
+              { value: 'list', label: 'List profiles' },
+              { value: 'upsert', label: 'Create/update profile' }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+`tui.steps` remains supported and backward compatible.
+
+## Custom TUI Components
+
+For advanced prompts (for example custom searchable selectors inspired by Clack patterns), declare custom components in flow metadata:
+
+```ts
+import { SnapTui } from '../src/index.js';
+
+const flow = SnapTui.defineTuiFlow({
+  entryStepId: 'choose',
+  steps: [
+    {
+      stepId: 'choose',
+      title: 'Choose target',
+      components: [
+        SnapTui.defineCustomTuiComponent({
+          componentId: 'target',
+          label: 'Target',
+          arg: 'target',
+          renderer: 'searchable-select',
+          config: { maxItems: 8, allowCustomValue: true }
+        })
+      ]
+    }
+  ]
+});
+```
+
+`renderer` identifies your adapter implementation while preserving a typed, framework-level contract.
+
+## Register Module
+
+Add module to registry bootstrapping in `/Users/khang/Documents/repo/snap/src/cli-entry.ts`.
+
+## CLI Bootstrapping Helpers
+
+Use Snap CLI helpers so module/tool authors do not re-implement argv parsing and dispatch:
+
+```ts
+import { createRegistry, runMultiModuleCli, runSingleModuleCli, runSubmoduleCli } from '../src/index.js';
+```
+
+- `runMultiModuleCli`: standard `tool <module> <action> --args`.
+- `runSingleModuleCli`: dedicated tool package mapped to one module, with optional default action.
+- `runSubmoduleCli`: dedicated tool package with multiple sub-modules (`tool <submodule> ...`) plus optional default sub-module.
+  - Supports `-h/--help`.
+  - Parses `--key=value`, `--key value`, and boolean flags.
+  - Routes help and action dispatch through framework runtime.
+
+## DX Helpers
+
+Snap exposes optional helpers so action authors avoid low-level terminal and argv plumbing:
+
+```ts
+import { SnapArgs, SnapHelp, SnapRuntime, SnapTui } from '../src/index.js';
+```
+
+- `SnapArgs`: typed argument readers and parsers (`readStringArg`, `readBooleanArg`, `collectUpperSnakeCaseEnvArgs`).
+- `SnapHelp`: help/commandline builder from arg schema (`defineArgSchema`, `buildHelpFromArgSchema`, `commandlineFromArgSchema`).
+- `SnapRuntime`: action result helpers (`runActionSafely`, standardized success/error envelopes).
+- `SnapTui`: typed TUI flow/component definitions (`defineTuiFlow`, `defineCustomTuiComponent`).
+
+Action runtime context already includes friendly APIs:
+
+```ts
+context.prompts.text(...)
+context.prompts.select(...)
+context.terminal.line(...)
+context.flow.next()
+```
+
+Interactive prompt calls are rendered with Clack components through Snap adapters, including option hints and cancellation handling.
+
+No direct `process.stdout` / state-machine wiring is required in module actions.
+
+## Validation Rules
+
+Registration fails if any action misses triad data (`tui`, `commandline`, `help`).
+A valid `tui` must provide either non-empty `steps` or non-empty `flow.steps`.

package/docs/snap-args.md

@@ -0,0 +1,323 @@
+# SnapArgs - Type-Safe Argument Reading
+
+`SnapArgs` provides typed helper functions for reading and parsing command-line arguments and environment variables.
+
+## Import
+
+```typescript
+import * as SnapArgs from 'snap-framework';
+```
+
+## API Reference
+
+### `readStringArg(args, ...keys)`
+
+Reads a string argument from multiple possible keys, returning the first non-empty value.
+
+```typescript
+const name = SnapArgs.readStringArg(context.args, 'name', 'username', 'user');
+// Returns: string | undefined
+```
+
+**Usage Example:**
+
+```typescript
+run: async (context) => {
+  const name = SnapArgs.readStringArg(context.args, 'name', 'username');
+  if (!name) {
+    return { ok: false, errorMessage: 'Name is required' };
+  }
+  return { ok: true, data: `Hello, ${name}` };
+}
+```
+
+### `readRequiredStringArg(args, key, message?)`
+
+Reads a required string argument, throwing an error if not present.
+
+```typescript
+const name = SnapArgs.readRequiredStringArg(context.args, 'name', 'Name is required');
+// Returns: string (throws if missing)
+```
+
+**Usage Example:**
+
+```typescript
+run: async (context) => {
+  try {
+    const name = SnapArgs.readRequiredStringArg(context.args, 'name');
+    return { ok: true, data: `Hello, ${name}` };
+  } catch (error) {
+    return {
+      ok: false,
+      errorMessage: error instanceof Error ? error.message : 'Unknown error'
+    };
+  }
+}
+```
+
+### `readBooleanArg(args, ...keys)`
+
+Reads a boolean argument, parsing common string representations.
+
+```typescript
+const verbose = SnapArgs.readBooleanArg(context.args, 'verbose', 'v');
+// Returns: boolean | undefined
+```
+
+**Supported string values:**
+- **True**: `'1'`, `'true'`, `'yes'`, `'y'`, `'on'`
+- **False**: `'0'`, `'false'`, `'no'`, `'n'`, `'off'`
+
+**Usage Example:**
+
+```typescript
+run: async (context) => {
+  const verbose = SnapArgs.readBooleanArg(context.args, 'verbose', 'v');
+  const debug = SnapArgs.readBooleanArg(context.args, 'debug');
+
+  if (verbose) {
+    context.terminal.line('Verbose mode enabled');
+  }
+
+  return { ok: true, data: { debug, verbose } };
+}
+```
+
+### `parseBooleanLike(value)`
+
+Parses a boolean-like string value into a boolean.
+
+```typescript
+const isTrue = SnapArgs.parseBooleanLike('yes');  // true
+const isFalse = SnapArgs.parseBooleanLike('0');   // false
+const isUndefined = SnapArgs.parseBooleanLike(undefined);  // undefined
+```
+
+**Usage Example:**
+
+```typescript
+run: async (context) => {
+  const forceValue = context.args.force;
+
+  if (forceValue !== undefined) {
+    const force = SnapArgs.parseBooleanLike(forceValue);
+    // Use force boolean
+  }
+
+  return { ok: true, data: {} };
+}
+```
+
+### `collectUpperSnakeCaseEnvArgs(args, prefix)`
+
+Collects environment variables with a given prefix into a typed object.
+
+```typescript
+const envArgs = SnapArgs.collectUpperSnakeCaseEnvArgs(context.args, 'MYAPP_');
+// Returns: Partial<Record<UpperSnakeCaseKey, string>>
+```
+
+**Usage Example:**
+
+```typescript
+// With environment variables: MYAPP_API_KEY, MYAPP_TIMEOUT
+run: async (context) => {
+  const envArgs = SnapArgs.collectUpperSnakeCaseEnvArgs(context.args, 'MYAPP_');
+
+  const apiKey = envArgs.MYAPP_API_KEY;
+  const timeout = envArgs.MYAPP_TIMEOUT;
+
+  return { ok: true, data: { apiKey, timeout } };
+}
+```
+
+## Complete Example Module
+
+Here's a complete module using `SnapArgs` helpers:
+
+```typescript
+import type { ModuleContract } from 'snap-framework';
+import { ExitCode } from 'snap-framework';
+import * as SnapArgs from 'snap-framework';
+
+const deployModule: ModuleContract = {
+  moduleId: 'deploy',
+  description: 'Deployment management',
+  actions: [
+    {
+      actionId: 'start',
+      description: 'Start a deployment',
+      tui: {
+        steps: ['collect-environment', 'collect-options', 'confirm'],
+        flow: {
+          entryStepId: 'collect-environment',
+          steps: [
+            {
+              stepId: 'collect-environment',
+              title: 'Select Environment',
+              components: [
+                {
+                  componentId: 'env',
+                  type: 'select',
+                  label: 'Environment',
+                  arg: 'environment',
+                  required: true,
+                  options: [
+                    { value: 'development', label: 'Development' },
+                    { value: 'staging', label: 'Staging' },
+                    { value: 'production', label: 'Production' }
+                  ]
+                }
+              ]
+            },
+            {
+              stepId: 'collect-options',
+              title: 'Deployment Options',
+              components: [
+                {
+                  componentId: 'verbose',
+                  type: 'confirm',
+                  label: 'Enable verbose logging',
+                  arg: 'verbose'
+                },
+                {
+                  componentId: 'force',
+                  type: 'confirm',
+                  label: 'Force deployment (skip checks)',
+                  arg: 'force'
+                }
+              ]
+            },
+            {
+              stepId: 'confirm',
+              title: 'Confirm Deployment'
+            }
+          ]
+        }
+      },
+      commandline: {
+        requiredArgs: ['environment'],
+        optionalArgs: ['verbose', 'force']
+      },
+      help: {
+        summary: 'Deploy application to the specified environment.',
+        args: [
+          {
+            name: 'environment',
+            required: true,
+            description: 'Target deployment environment',
+            example: '--environment=production'
+          },
+          {
+            name: 'verbose',
+            required: false,
+            description: 'Enable verbose output',
+            example: '--verbose=true'
+          },
+          {
+            name: 'force',
+            required: false,
+            description: 'Skip pre-deployment checks',
+            example: '--force=yes'
+          }
+        ],
+        examples: [
+          'mytool deploy start --environment=production',
+          'mytool deploy start --environment=staging --verbose=true'
+        ],
+        useCases: [
+          {
+            name: 'production',
+            description: 'Deploy to production',
+            command: 'mytool deploy start --environment=production'
+          }
+        ],
+        keybindings: ['Enter confirm', 'Esc cancel']
+      },
+      run: async (context) => {
+        // Read required environment
+        const environment = SnapArgs.readRequiredStringArg(
+          context.args,
+          'environment',
+          'Environment is required'
+        );
+
+        // Read optional boolean flags
+        const verbose = SnapArgs.readBooleanArg(context.args, 'verbose') ?? false;
+        const force = SnapArgs.readBooleanArg(context.args, 'force') ?? false;
+
+        if (verbose) {
+          context.terminal.line(`Deploying to ${environment}...`);
+        }
+
+        if (force) {
+          context.terminal.line('Warning: Skipping pre-deployment checks!');
+        }
+
+        // Perform deployment logic here...
+
+        return {
+          ok: true,
+          mode: context.mode,
+          exitCode: ExitCode.SUCCESS,
+          data: `Deployed to ${environment}`
+        };
+      }
+    }
+  ]
+};
+
+export default deployModule;
+```
+
+## Environment Variable Integration
+
+Combine commandline args with environment variables:
+
+```typescript
+run: async (context) => {
+  // Try commandline first, fall back to environment
+  const apiKey = SnapArgs.readStringArg(
+    context.args,
+    'api-key',
+    'apiKey',
+    'API_KEY'
+  );
+
+  if (!apiKey) {
+    return {
+      ok: false,
+      errorMessage: 'API key must be provided via --api-key or API_KEY env var'
+    };
+  }
+
+  return { ok: true, data: { apiKey } };
+}
+```
+
+## Best Practices
+
+1. **Always validate required args**: Use `readRequiredStringArg` for critical arguments
+2. **Provide fallback values**: Use `??` operator for optional defaults
+3. **Support multiple key aliases**: Use variadic args for flexible naming
+4. **Parse booleans safely**: Always use `readBooleanArg` for flag arguments
+5. **Collect environment prefixes**: Use `collectUpperSnakeCaseEnvArgs` for env var grouping
+
+## Type Safety
+
+`SnapArgs` provides full TypeScript type safety:
+
+```typescript
+import type { CliArgs } from 'snap-framework';
+
+const args: CliArgs = {
+  name: 'Alice',
+  verbose: 'true',
+  count: '42'
+};
+
+// TypeScript knows these return types
+const name: string | undefined = SnapArgs.readStringArg(args, 'name');
+const verbose: boolean | undefined = SnapArgs.readBooleanArg(args, 'verbose');
+```