footprintjs 0.10.0 → 0.10.2

package/AGENTS.md

@@ -0,0 +1,125 @@
+# footprint.js — AI Agent Instructions
+
+> The flowchart pattern for backend code — self-explainable systems that AI can reason about.
+
+## What This Library Does
+
+footprint.js structures backend logic as a graph of named functions with transactional state. Every run auto-generates a causal trace showing what happened and why. An LLM reads the trace and explains decisions accurately — no hallucination.
+
+## Core Principle
+
+**Collect during traversal, never post-process.** All data collection (narrative, metrics, manifest) happens as side effects of the single DFS traversal pass. Never walk the tree again after execution.
+
+## Architecture
+
+```
+src/lib/
+├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
+├── schema/    → Validation (Zod optional, duck-typed detection)
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
+├── scope/     → Per-stage facades + recorders + providers
+├── engine/    → DFS traversal + narrative + handlers
+├── runner/    → High-level executor (FlowChartExecutor)
+└── contract/  → I/O schema + OpenAPI generation
+```
+
+Two entry points:
+- `import { ... } from 'footprintjs'` — public API
+- `import { ... } from 'footprintjs/advanced'` — internals
+
+## Quick Start
+
+```typescript
+import { flowChart, FlowChartExecutor } from 'footprintjs';
+
+const chart = flowChart('ReceiveOrder', (scope) => {
+    scope.setValue('orderId', 'ORD-123');
+    scope.setValue('amount', 49.99);
+  }, 'receive-order', undefined, 'Receive the incoming order')
+  .addFunction('ProcessPayment', (scope) => {
+    const amount = scope.getValue('amount');
+    scope.setValue('paymentStatus', amount < 100 ? 'approved' : 'review');
+  }, 'process-payment', 'Charge customer')
+  .setEnableNarrative()
+  .build();
+
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input: { orderId: 'ORD-123' } });
+console.log(executor.getNarrative());
+```
+
+## Builder API
+
+```typescript
+flowChart(name, fn, id, extractor?, description?)  // start chain
+  .addFunction(name, fn, id, description?)          // linear stage
+  .addDeciderFunction(name, fn, id, description?)   // single-choice branch
+    .addFunctionBranch(branchId, name, fn)           //   branch option
+    .addSubFlowChartBranch(branchId, subflow)        //   subflow branch
+    .setDefault(branchId)                             //   fallback
+    .end()                                            //   close decider
+  .addSelectorFunction(name, fn, id, description?)  // multi-choice fan-out
+  .addListOfFunction([...], { failFast? })           // parallel fork
+  .addSubFlowChartNext(id, subflow, mount, opts?)   // mount subflow inline
+  .loopTo(stageId)                                   // back-edge loop
+  .setEnableNarrative()                              // enable narrative
+  .setInputSchema(schema)                            // Zod or JSON Schema
+  .build()                                           // compile
+  .toSpec()                                          // JSON structure
+  .toMermaid()                                       // diagram
+```
+
+## Stage Function Signature
+
+```typescript
+(scope: ScopeFacade, breakPipeline: () => void, streamCallback?: StreamCallback) => void | Promise<void>
+```
+
+## ScopeFacade (per-stage state access)
+
+```typescript
+scope.getValue('key')              // tracked read → appears in narrative
+scope.setValue('key', value)        // tracked write → appears in narrative
+scope.updateValue('key', partial)  // deep merge (tracked)
+scope.deleteValue('key')           // tracked delete
+scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
+```
+
+## Executor
+
+```typescript
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input, timeoutMs?, signal? });
+
+executor.getNarrative()         // string[] — combined flow + data
+executor.getNarrativeEntries()  // CombinedNarrativeEntry[] — structured
+executor.getSnapshot()          // full memory state
+executor.attachFlowRecorder(r)  // plug observer before run()
+executor.setRedactionPolicy({   // PII protection
+  keys: ['ssn'], patterns: [/password/i]
+})
+```
+
+## Two Observer Systems
+
+**Scope Recorder** — fires DURING stage: `onRead`, `onWrite`, `onCommit`, `onStageStart/End`
+**FlowRecorder** — fires AFTER stage: `onStageExecuted`, `onDecision`, `onFork`, `onNext`, `onLoop`, `onError`
+
+8 built-in FlowRecorder strategies: Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest, Silent.
+
+`CombinedNarrativeRecorder` implements BOTH — auto-attached by `setEnableNarrative()`.
+
+## Anti-Patterns
+
+- Never post-process the tree — use recorders
+- Never use deprecated `CombinedNarrativeBuilder`
+- Don't use `getArgs()` for tracked data — use `getValue()`/`setValue()`
+- Don't manually create `CombinedNarrativeRecorder` — `setEnableNarrative()` handles it
+
+## Build
+
+```bash
+npm install footprintjs
+npm run build    # CJS + ESM dual output
+npm test
+```

package/CLAUDE.md

@@ -0,0 +1,127 @@
+# footprint.js — AI Coding Instructions
+
+This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
+
+## Core Principle
+
+**Collect during traversal, never post-process.** All data collection (narrative, metrics, manifest, identity) happens as side effects of the single DFS traversal pass. Never walk the tree again after execution.
+
+## Architecture — Library of Libraries
+
+```
+src/lib/
+├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer, EventLog)
+├── schema/    → Validation abstraction (Zod optional, duck-typed detection)
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart(), DeciderList, SelectorFnList)
+├── scope/     → Per-stage facades + recorders + providers (largest module)
+├── engine/    → DFS traversal + narrative + 13 handlers
+├── runner/    → High-level executor (FlowChartExecutor)
+└── contract/  → I/O schema + OpenAPI generation
+```
+
+Dependency DAG: `memory ← scope ← engine ← runner`, `schema ← engine`, `builder (standalone) → engine`, `contract ← schema`
+
+Two entry points:
+- `import { ... } from 'footprintjs'` — public API
+- `import { ... } from 'footprintjs/advanced'` — internals
+
+## Key API
+
+### Builder
+
+```typescript
+import { flowChart, FlowChartBuilder } from 'footprintjs';
+
+// flowChart(name, fn, id, buildTimeExtractor?, description?)
+const chart = flowChart('Stage1', fn1, 'stage-1', undefined, 'Description')
+  .addFunction('Stage2', fn2, 'stage-2', 'Description')
+  .addDeciderFunction('Decide', deciderFn, 'decide', 'Route based on risk')
+    .addFunctionBranch('high', 'Reject', rejectFn)
+    .addFunctionBranch('low', 'Approve', approveFn)
+    .setDefault('high')
+    .end()
+  .setEnableNarrative()
+  .build();
+```
+
+Methods: `start()`, `addFunction()`, `addStreamingFunction()`, `addDeciderFunction()`, `addSelectorFunction()`, `addListOfFunction()`, `addSubFlowChart()`, `addSubFlowChartNext()`, `loopTo()`, `setEnableNarrative()`, `setInputSchema()`, `setOutputSchema()`, `setOutputMapper()`, `build()`, `toSpec()`, `toMermaid()`
+
+### Stage Functions
+
+```typescript
+type PipelineStageFunction = (
+  scope: ScopeFacade,
+  breakPipeline: () => void,
+  streamCallback?: StreamCallback,
+) => Promise<void> | void;
+```
+
+### ScopeFacade
+
+```typescript
+scope.getValue('key')              // tracked read (appears in narrative)
+scope.setValue('key', value)        // tracked write
+scope.updateValue('key', partial)  // deep merge
+scope.deleteValue('key')           // tracked delete
+scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
+scope.attachRecorder(recorder)     // plug observer
+```
+
+**IMPORTANT:** `getValue`/`setValue` are tracked. `getArgs()` is NOT tracked and returns frozen input.
+
+### Executor
+
+```typescript
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input: data, timeoutMs: 5000, signal: abortSignal });
+
+executor.getNarrative()         // combined flow + data narrative
+executor.getNarrativeEntries()  // structured entries with type/depth/stageName
+executor.getFlowNarrative()     // flow-only (no data ops)
+executor.getSnapshot()          // full memory state
+executor.attachFlowRecorder(r)  // plug flow observer
+executor.setRedactionPolicy({}) // PII protection
+```
+
+## Two Observer Systems
+
+Both use `{ id, hooks } → dispatcher → error isolation → attach/detach`. Intentionally NOT unified.
+
+**Scope Recorder** (data ops — fires DURING stage execution):
+- `onRead`, `onWrite`, `onCommit`, `onError`, `onStageStart`, `onStageEnd`
+- Built-in: `NarrativeRecorder`, `MetricRecorder`, `DebugRecorder`
+
+**FlowRecorder** (control flow — fires AFTER stage execution):
+- `onStageExecuted`, `onNext`, `onDecision`, `onFork`, `onSelected`, `onSubflowEntry/Exit`, `onLoop`, `onBreak`, `onError`
+- Built-in: 8 strategies (Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest, Silent)
+
+**CombinedNarrativeRecorder** implements BOTH interfaces. Auto-attached by `setEnableNarrative()`.
+
+## Event Ordering
+
+```
+1. Recorder.onStageStart        — stage begins
+2. Recorder.onRead/onWrite      — DURING execution (buffered per-stage)
+3. Recorder.onCommit            — transaction flush
+4. Recorder.onStageEnd          — stage completes
+5. FlowRecorder.onStageExecuted — CombinedNarrativeRecorder flushes buffered ops
+6. FlowRecorder.onNext/onDecision/onFork — control flow continues
+```
+
+## Anti-Patterns
+
+- Never post-process the tree — use recorders
+- Never use deprecated `CombinedNarrativeBuilder` — use `CombinedNarrativeRecorder`
+- Don't extract shared base for Recorder/FlowRecorder — two instances = coincidence
+- Don't use `getArgs()` for tracked data — use `getValue()`/`setValue()`
+- Don't manually create `CombinedNarrativeRecorder` — `setEnableNarrative()` handles it
+
+## Build & Test
+
+```bash
+npm run build    # tsc (CJS) + tsc -p tsconfig.esm.json (ESM)
+npm test         # full suite
+npm run test:unit
+```
+
+Dual output: CommonJS (`dist/`) + ESM (`dist/esm/`) + types (`dist/types/`)

package/README.md

@@ -537,6 +537,54 @@ src/lib/
 
 ---
 
+## AI Coding Tool Support
+
+FootPrint ships with built-in instructions for every major AI coding assistant. Your AI tool understands the library's API, patterns, and anti-patterns out of the box.
+
+### Quick setup
+
+```bash
+# After installing footprintjs, run:
+npx footprintjs-setup
+```
+
+This interactive installer copies the right instruction files for your tool(s):
+
+| Tool | What gets installed | Format |
+|------|-------------------|--------|
+| **[Claude Code](https://claude.com/claude-code)** | `.claude/skills/footprint/SKILL.md` + `CLAUDE.md` | Interactive skill + project rules |
+| **[OpenAI Codex](https://openai.com/index/codex/)** | `AGENTS.md` | Agent instructions |
+| **[GitHub Copilot](https://github.com/features/copilot)** | `.github/copilot-instructions.md` | Custom instructions |
+| **[Cursor](https://cursor.com)** | `.cursor/rules/footprint.md` | Project rules |
+| **[Windsurf](https://windsurf.com)** | `.windsurfrules` | Project rules |
+| **[Cline](https://github.com/cline/cline)** | `.clinerules` | Project rules |
+| **[Kiro](https://kiro.dev)** | `.kiro/rules/footprint.md` | Project rules |
+
+Or install manually:
+
+```bash
+# Claude Code skill
+mkdir -p .claude/skills/footprint
+cp node_modules/footprintjs/ai-instructions/claude-code/SKILL.md .claude/skills/footprint/
+
+# Cursor rules
+mkdir -p .cursor/rules
+cp node_modules/footprintjs/ai-instructions/cursor/footprint.md .cursor/rules/
+
+# Any other tool — files are in node_modules/footprintjs/ai-instructions/
+```
+
+Every file teaches the AI assistant:
+- The **Builder**, **Executor**, and **ScopeFacade** APIs
+- The **recorder system** (scope + flow, two observer layers)
+- The **core principle**: collect during traversal, never post-process
+- **Anti-patterns** to avoid (deprecated APIs, wrong state access patterns)
+- **Event ordering** that makes inline narrative collection work
+
+This means any AI coding tool can help you build flowchart pipelines correctly from day one.
+
+---
+
 ## License
 
 [MIT](./LICENSE) © [Sanjay Krishna Anbalagan](https://github.com/sanjay1909)