@siglo/cli 0.0.0-stage → 1.0.0

package/ECOSYSTEM.md

@@ -0,0 +1,85 @@
+# Ecosystem step generation
+
+Use `siglo generate step <name> --type=<type>` from your project directory.
+Names may be identifiers or kebab-case. Generation rejects invalid options and
+existing step or test files; it never merges into an existing file.
+
+```sh
+siglo generate step callStripe --type=http --url=https://api.stripe.com/v1/charges
+siglo generate step verifyStripeWebhook --type=crypto --provider=stripe
+siglo generate step managerApproval --type=notification --channel=slack --interactive=true
+siglo generate step triageTicket --type=ai --provider=anthropic --model=YOUR_MODEL_ID
+```
+
+The default remains the generic step and Mocha/Chai test. Ecosystem templates
+export a `create<Name>Step` factory so tests can supply adapters, transports or
+secret resolvers. Generated filenames retain the existing lowercase convention.
+Options use `--key=value`; interactive prompting is not implemented.
+
+## Consumer dependencies
+
+Use Node.js `^22.13.0 || >=24`, TypeScript 5.7+, `tsx`, and `@types/node`.
+Install `@siglo/core` and the package selected by the template (`@siglo/http`,
+`@siglo/crypto`, `@siglo/notifications`, or `@siglo/ai`) as runtime dependencies.
+Tests import each package's testing subpath; no separate mock package is needed.
+The crypto test uses Node's built-in HMAC implementation: crypto has no testing
+subpath. The HTTP and AI templates contain a concrete Standard Schema validator
+and require no third-party validator. If replacing it with Zod, install Zod as a
+runtime dependency. Generic templates additionally require Mocha, Chai, and their
+types as development dependencies.
+
+Run ecosystem tests serially because the HTTP testing utility replaces global
+fetch:
+
+```sh
+node --import tsx --test --test-concurrency=1 src/steps/*.step.test.ts
+```
+
+Run generic tests with `mocha -r tsx 'src/steps/*.step.test.ts'`. Do not mix the
+two runner conventions in a single invocation. Compile generated files with
+`tsc --noEmit` using Node16 module resolution, ES2022 target, and esModuleInterop.
+
+## Runtime wiring
+
+HTTP uses a static URL and POST with sample request and response validators.
+Change the sample body and validators to your API contract. Static URLs declare
+the hostname automatically; a URL resolver must explicitly declare permitted
+hosts using `.allowNetwork([...])`. Tests install core network interceptors
+before replacing fetch, restore fetch in `finally`, and reject unmatched calls.
+The mock covers fetch only; it does not isolate other transports.
+
+Webhook factories resolve `WEBHOOK_SECRET` at runtime, or accept an injected
+resolver. Pass raw request bytes/string and signature headers. Never parse and
+re-serialize the body before verification. Tests sign a synthetic body locally
+and verify rejection after tampering. Supported providers are Stripe, GitHub,
+Shopify, Slack, Svix, and generic HMAC.
+
+AI factories accept an optional adapter inside the model configuration. Supply
+a provider-supported model ID and configure that provider's credentials in the
+application. Tests inject `MockAiProvider`, validate structured data, and assert
+`result.data`. Supported generated providers are OpenAI, Anthropic, Gemini and
+Ollama; custom adapters remain available through the package API.
+
+Notification factories require an explicit transport. For example:
+
+```ts
+import { SlackTransport, ResendTransport } from '@siglo/notifications';
+const slack = new SlackTransport({ apiKey: process.env.SLACK_TOKEN! });
+const email = new ResendTransport({
+  apiKey: process.env.RESEND_API_KEY!, from: 'workflow@example.com',
+});
+```
+
+For Discord use `DiscordTransport`; for SMS use `TwilioTransport` with the provider's configuration; for push use
+`PushWebhookTransport` or implement the `NotificationTransport` interface. Replace the generated example recipient.
+The factory supplies transport host declarations to the runtime. Tests use
+`MockNotificationTransport` and perform no delivery.
+
+Approval generation is explicit and supports email and Slack. The generated
+step dispatches signed actions; it does not itself suspend the workflow. In the
+application, use a unique correlation key for each approval, register a durable
+wait for the approved/rejected events, configure persistent workflow storage and
+the notification dispatch/revocation stores, and expose the package's callback
+handler with the same signing secret. Authorize the approver at that boundary.
+Use an HTTPS callback URL and keep signing secrets in runtime configuration.
+The generated test verifies action dispatch only, not durable resume or expiry.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Jerico de guzman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,481 @@
-# Temporary Holding Version
+# @siglo/cli Developer Tools & CLI Guide
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@siglo/cli` provides developer tooling, code scaffolding, static analysis, command-line inspection, architecture export, and regression testing utilities for `Siglo` workflows. It allows engineering teams to scaffold typed steps/workflows, visualize execution graphs, export to Mermaid/Graphviz/JSON, detect cyclic dependencies, inspect serialized checkpoints, and replay golden test fixtures in CI/CD pipelines.
+
+See the [ecosystem generator cookbook](ECOSYSTEM.md) for HTTP, webhook, notification, and AI step templates and offline testing.
+
+---
+
+## 1. Overview
+
+`@siglo/cli` operates both as an executable terminal tool (`Siglo`) and as a programmatic TypeScript library:
+
+```mermaid
+flowchart TD
+    CLI["@siglo/cli"] --> CLI_Term["Terminal Command Line"]
+    CLI --> CLI_API["Programmatic Node.js API"]
+
+    subgraph TerminalCommands["CLI Commands"]
+        C1["siglo init<br/>siglo generate workflow<br/>siglo generate step<br/>siglo visualize<br/>siglo export<br/>siglo validate<br/>siglo inspect<br/>siglo checkpoint<br/>siglo replay"]
+    end
+
+    subgraph ProgrammaticAPI["Node.js API"]
+        A1["initProject()<br/>generateWorkflow()<br/>generateStep()<br/>visualizeWorkflow()<br/>exportWorkflow()<br/>validateWorkflow()<br/>inspectWorkflow()<br/>inspectCheckpoint()<br/>replayFixture()"]
+    end
+
+    CLI_Term --> TerminalCommands
+    CLI_API --> ProgrammaticAPI
+```
+
+---
+
+## 2. Installation
+
+Install `@siglo/cli` locally in your project or globally:
+
+```bash
+# Local development dependency (recommended)
+npm install --save-dev @siglo/cli @siglo/testing @siglo/core tsx
+
+# Or run directly via npx
+npm exec --package=@siglo/cli -- siglo --help
+```
+
+---
+
+## 3. Command Line Interface (CLI)
+
+The CLI executable is `Siglo`.
+
+### General Usage
+
+```bash
+Siglo <command> [arguments] [options]
+```
+
+### Global Options:
+- `--format=mermaid|text|dot|json`: Diagram representation or export format (default: `mermaid`).
+- `--direction=TD|LR|TB`: Graph layout direction for Mermaid or DOT diagrams (default: `TD`).
+- `--out=<file>`: Write output directly to a file instead of `stdout`.
+- `--redact=key1,key2`: Comma-delimited list of sensitive context keys or node names to mask with `[REDACTED]`.
+- `--help`, `-h`: Show CLI usage guide.
+- `--version`, `-v`: Display CLI version.
+
+---
+
+### Command 1: `siglo init [dir]`
+
+Scaffolds a clean starter project preconfigured with `Siglo`, `tsx`, modern TypeScript config, and a runnable workflow test.
+
+```bash
+siglo init ./services/order-orchestrator
+```
+
+#### Generated Files:
+1. `package.json`: Contains scripts (`npm test`, `npm start`) and required dependencies.
+2. `src/workflow.ts`: Example order processing pipeline with validation and payment steps.
+3. `src/workflow.test.ts`: Automated test executing the workflow with assertions.
+
+---
+
+### Command 2: `siglo generate workflow <name>`
+
+Scaffolds a brand new typed workflow file and companion unit test powered by `@siglo/testing`.
+
+```bash
+siglo generate workflow order-processing
+```
+
+#### Generated Files:
+1. `src/workflows/order-processing.workflow.ts`: Strongly-typed input/output interfaces, steps, and default workflow export.
+2. `src/workflows/order-processing.workflow.test.ts`: Test harness setup verifying end-to-end execution and step invocations.
+
+---
+
+### Command 3: `siglo generate step <name>`
+
+Scaffolds an isolated, strongly-typed `Step` module and companion unit test.
+
+```bash
+siglo generate step send-notification
+```
+
+#### Generated Files:
+1. `src/steps/send-notification.step.ts`: Typed step module with input/output interfaces.
+2. `src/steps/send-notification.step.test.ts`: Direct step execution test.
+
+---
+
+### Command 4: `siglo visualize <workflow-file> [options]`
+
+Renders the workflow graph AST as either a Mermaid flowchart or an indented ASCII text hierarchy.
+
+#### Mermaid Diagram (Default):
+```bash
+siglo visualize src/workflows/checkout.ts
+```
+*Output:*
+```mermaid
+flowchart TD
+    validateOrder["validateOrder (step)"]
+    chargePayment["chargePayment (step)"]
+    reserveInventory["reserveInventory (step)"]
+    validateOrder --> chargePayment
+    chargePayment --> reserveInventory
+```
+
+#### Text Diagram (`--format=text`):
+```bash
+siglo visualize src/workflows/checkout.ts --format=text
+```
+*Output:*
+```text
+Workflow Graph (total nodes: 3, edges: 2):
+├── [step] validateOrder (validateOrder)
+├── [step] chargePayment (chargePayment)
+└── [step] reserveInventory (reserveInventory)
+```
+
+---
+
+### Command 5: `siglo export <workflow-file> [options]`
+
+Exports the workflow topology graph directly to standard formats for architectural documentation, diagrams, or web visualization:
+- `--format=mermaid`: Mermaid flowchart with policy badges (retries, timeouts, fallback).
+- `--format=dot`: Graphviz DOT format compatible with Graphviz tools and PlantUML.
+- `--format=json`: Comprehensive AST node/edge graph JSON.
+- `--direction=TD|LR|TB`: Graph layout orientation (top-down, left-to-right).
+- `--out=<file>`: Save result directly to a specified destination file.
+
+```bash
+# Export Mermaid diagram to file with Left-to-Right layout
+siglo export src/workflows/order.workflow.ts --format=mermaid --direction=LR --out=docs/order-flow.mmd
+
+# Export Graphviz DOT format
+siglo export src/workflows/order.workflow.ts --format=dot --out=diagrams/order.dot
+
+# Export raw JSON AST
+siglo export src/workflows/order.workflow.ts --format=json --out=dist/order-ast.json
+```
+
+---
+
+### Command 6: `siglo validate <workflow-file>`
+
+Performs static analysis on the workflow graph AST without executing any step business logic:
+- Detects cyclic dependencies.
+- Identifies unreachable nodes or disconnected subgraphs.
+- Verifies combinator structures (`parallel`, `branch`, `map`).
+
+```bash
+siglo validate src/workflows/loan-pipeline.ts
+```
+
+*Success Output:*
+```text
+✔ Workflow graph is valid (acyclic, reachable)
+```
+
+*Failure Output (Exit Code 1):*
+```text
+✖ Workflow validation failed:
+  - Cycle detected between nodes 'processPayment' and 'retryPayment'
+```
+
+---
+
+### Command 7: `siglo inspect <workflow-file> [options]`
+
+Returns a detailed JSON telemetry summary of the workflow topology, node classifications, edge connections, and total complexity metrics.
+
+```bash
+siglo inspect src/workflows/settlement.ts --redact=taxId,secretKey
+```
+
+*Output:*
+```json
+{
+  "totalNodes": 4,
+  "edges": [
+    { "from": "step1", "to": "step2" },
+    { "from": "step2", "to": "step3" }
+  ],
+  "nodes": [
+    { "id": "step1", "name": "validateInput", "type": "step" },
+    { "id": "step2", "name": "[REDACTED]", "type": "step" },
+    { "id": "step3", "name": "persistAudit", "type": "step" }
+  ],
+  "redactedFields": ["taxId", "secretKey"]
+}
+```
+
+---
+
+### Command 8: `siglo checkpoint <file> [options]`
+
+Parses and validates a serialized checkpoint state JSON file (e.g., dumped from Redis or PostgreSQL during debugging), summarizing step chains and execution context while masking sensitive credentials.
+
+```bash
+siglo checkpoint ./logs/crash-checkpoint.json --redact=apiKey,password
+```
+
+*Output:*
+```json
+{
+  "stackId": "stack-8123-bba8",
+  "namespace": "tenant-enterprise",
+  "type": "flow",
+  "stepCount": 3,
+  "chains": ["validate", "charge", "notify"],
+  "contexts": {
+    "charge": {
+      "apiKey": "[REDACTED]",
+      "status": "APPROVED",
+      "amount": 250
+    }
+  }
+}
+```
+
+---
+
+### Command 9: `siglo replay <fixture> [workflow-file]`
+
+Replays an end-to-end workflow execution using recorded inputs and validates that output values match golden expectations.
+
+```bash
+# Replay against default src/workflow.ts
+siglo replay fixtures/order-regression.json
+
+# Replay against explicit workflow module
+siglo replay fixtures/order-regression.json src/workflows/order.workflow.ts
+```
+
+*Success Output:*
+```text
+✔ Replay passed in 14ms
+```
+
+*Regression Output (Exit Code 1):*
+```text
+✖ Replay failed with discrepancies: {
+  "total": {
+    "expected": 100,
+    "actual": 120
+  }
+}
+```
+
+---
+
+## 4. Programmatic API Reference
+
+Import programmatic utilities directly in your tests, scripts, and build pipelines:
+
+```typescript
+import {
+    initProject,
+    generateWorkflow,
+    generateStep,
+    visualizeWorkflow,
+    validateWorkflow,
+    inspectWorkflow,
+    inspectCheckpoint,
+    replayFixture,
+    exportWorkflow,
+    toMermaid,
+    toTextGraph,
+    ReplayFixture,
+    ReplayResult,
+    WorkflowVisualizationResult,
+    ExportWorkflowOptions
+} from '@siglo/cli';
+```
+
+---
+
+### `generateWorkflow(name, targetDir?)`
+
+Generates typed workflow and test templates:
+
+```typescript
+const { filePath, testPath } = generateWorkflow('payment-settlement');
+console.log(`Generated: ${filePath} and ${testPath}`);
+```
+
+---
+
+### `generateStep(name, targetDir?)`
+
+Generates typed step and test templates:
+
+```typescript
+const { filePath, testPath } = generateStep('audit-logger');
+console.log(`Generated: ${filePath} and ${testPath}`);
+```
+
+---
+
+### `exportWorkflow(workflow, options?)`
+
+Exports a workflow to Mermaid, Graphviz DOT, or JSON format:
+
+```typescript
+// Mermaid format with top-to-bottom layout
+const mermaidDiagram = exportWorkflow(myWorkflow, {
+    format: 'mermaid',
+    direction: 'TD',
+    includeBadges: true
+});
+
+// Graphviz DOT format with left-to-right layout
+const dotGraph = exportWorkflow(myWorkflow, {
+    format: 'dot',
+    direction: 'LR'
+});
+
+// JSON AST format
+const jsonAST = exportWorkflow(myWorkflow, {
+    format: 'json'
+});
+```
+
+---
+
+### `visualizeWorkflow(workflow)`
+
+Generates both Mermaid and ASCII text representations of a workflow:
+
+```typescript
+const result: WorkflowVisualizationResult = visualizeWorkflow(orderWorkflow);
+
+console.log(result.mermaid);   // Mermaid flowchart TD string
+console.log(result.text);      // ASCII text tree
+console.log(result.nodeCount); // Total nodes in AST
+console.log(result.hasCycles); // Boolean cycle indicator
+```
+
+---
+
+### `validateWorkflow(workflow)`
+
+Runs cycle detection and connectivity validation on the compiled graph:
+
+```typescript
+const validation = validateWorkflow(myWorkflow);
+
+if (!validation.valid) {
+    console.error('Validation errors:', validation.errors);
+}
+```
+
+---
+
+### `inspectWorkflow(workflow, options?)`
+
+Analyzes graph structure and optionally redacts sensitive node names:
+
+```typescript
+const inspection = inspectWorkflow(myWorkflow, {
+    redact: ['confidentialStep', 'authStep']
+});
+```
+
+---
+
+### `inspectCheckpoint(checkpoint, options?)`
+
+Inspects a checkpoint object or JSON string, redacting specified context fields across all steps:
+
+```typescript
+const summary = inspectCheckpoint(checkpointJsonString, {
+    redact: ['accessToken', 'cardToken']
+});
+```
+
+---
+
+### `replayFixture(workflow, fixture)`
+
+Replays an end-to-end workflow against a recorded golden test fixture. Ideal for CI regression testing, schema evolution validation, and deterministic output verification.
+
+#### TypeScript Interface:
+
+```typescript
+export interface ReplayFixture {
+    name?: string;
+    version?: string;
+    initialParam: Record<string, any>;
+    expectedOutputs?: Record<string, any>;
+    checkpoints?: any[];
+}
+
+export interface ReplayResult {
+    success: boolean;
+    durationMs: number;
+    finalContext: Record<string, any>;
+    diff?: Record<string, { expected: any; actual: any }>;
+}
+```
+
+---
+
+## 5. Golden Fixture Testing in CI
+
+Use `replayFixture` in your test suite to ensure that workflow refactoring preserves identical behavior and contract outputs:
+
+### Step 1: Define Fixture File (`test/fixtures/pricing-fixture.json`)
+
+```json
+{
+  "name": "StandardTierPricing",
+  "version": "2.0.0",
+  "initialParam": {
+    "seats": 10,
+    "tier": "pro",
+    "annualDiscount": true
+  },
+  "expectedOutputs": {
+    "subtotal": 1200,
+    "discount": 240,
+    "total": 960,
+    "approved": true
+  }
+}
+```
+
+### Step 2: Implement Test Runner (`test/pricing.test.ts`)
+
+```typescript
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as path from 'path';
+import { replayFixture } from '@siglo/cli';
+import { pricingFlow } from '../src/workflows/pricingFlow';
+
+test('Pricing Flow matches golden fixture expectations', async () => {
+    const fixturePath = path.resolve(__dirname, 'fixtures/pricing-fixture.json');
+    const result = await replayFixture(pricingFlow, fixturePath);
+
+    assert.equal(
+        result.success,
+        true,
+        `Workflow regression detected: ${JSON.stringify(result.diff, null, 2)}`
+    );
+
+    assert.ok(result.durationMs < 500, `Execution took ${result.durationMs}ms, exceeded 500ms budget`);
+});
+```
+
+---
+
+## 6. Workflow File Loading Mechanics
+
+When `Siglo` loads a workflow file specified on the command line (e.g. `siglo visualize src/workflow.ts` or `siglo export src/workflow.ts`):
+1. The file is dynamically imported using Node.js ES modules.
+2. The loader checks exports in the following order:
+   - `export default flowInstance`
+   - `export const workflow = flowInstance`
+   - `export const pipeline = flowInstance`
+   - Any named export satisfying `isFlow` or containing a `run()` function.
+   - If the candidate is a zero-argument factory function (e.g., `export default () => flow(...)`), it is invoked automatically to construct the graph.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}