@spilno/herald-mcp 1.34.2 → 1.34.4

package/README.md

@@ -30,11 +30,31 @@ herald.gotStuck('What failed');
 
 ## Quick Start
 
+### MCP Server (for AI agents like Claude)
+
 ```bash
 cd your-project
 npx @spilno/herald-mcp init
 ```
 
+### SDK (for programmatic access)
+
+```typescript
+import { herald } from '@spilno/herald-mcp';
+
+// Capture a pattern (something that worked)
+await herald.learned('Always run tests before committing');
+
+// Capture an antipattern (something that failed)
+await herald.gotStuck('Forgot to check existing tests before refactoring');
+
+// Query patterns
+const patterns = await herald.recall();
+
+// Configure (optional - uses git context by default)
+herald.configure({ baseUrl: 'https://custom.ceda.com', token: 'your-token' });
+```
+
 **What this does:**
 1. Creates `.mcp.json` with Herald MCP configuration
 2. Fetches learned patterns from CEDA (if any exist)
@@ -42,6 +62,41 @@ npx @spilno/herald-mcp init
 
 Company and project default to your folder name. Zero config.
 
+## Interactive Chat
+
+For humans who want to capture patterns directly from the terminal:
+
+```bash
+npx @spilno/herald-mcp chat
+```
+
+```
+Herald Pattern Journal
+
+Commands:
+  /learned <insight>  - capture what worked
+  /stuck <insight>    - capture what failed
+  /recall [topic]     - see your patterns
+  /quit               - exit
+
+> /learned Error boundaries prevent silent failures
+Pattern captured
+
+> /stuck Forgot to await in test setup
+Antipattern captured
+
+> /recall testing
+Patterns:
+  - Error boundaries prevent silent failures
+Antipatterns:
+  - Forgot to await in test setup
+
+> /quit
+Bye! Your patterns are saved.
+```
+
+No AI key needed. Just pattern capture and recall.
+
 ## Init Options
 
 ```bash
@@ -188,6 +243,82 @@ CEDA (Cognitive Event-Driven Architecture) is pattern memory for AI:
 
 Unlike RAG (retrieves content), CEDA retrieves **what worked**.
 
+## SDK API
+
+The SDK provides programmatic access to CEDA pattern memory for use in your own applications.
+
+### Installation
+
+```bash
+npm install @spilno/herald-mcp
+```
+
+### API Reference
+
+#### `herald.learned(insight, context?)`
+
+Capture a pattern (something that worked).
+
+```typescript
+await herald.learned('Always run tests before committing');
+await herald.learned('Use feature flags for gradual rollouts', 'deployment pipeline');
+```
+
+#### `herald.gotStuck(insight, context?)`
+
+Capture an antipattern (something that failed).
+
+```typescript
+await herald.gotStuck('Forgot to check existing tests before refactoring');
+await herald.gotStuck('Deployed without running migrations', 'production incident');
+```
+
+#### `herald.recall(topic?)`
+
+Query learned patterns and antipatterns.
+
+```typescript
+const patterns = await herald.recall();
+const deployPatterns = await herald.recall('deployment');
+```
+
+Returns an array of `Pattern` objects:
+
+```typescript
+interface Pattern {
+  insight: string;
+  feeling: 'success' | 'stuck';
+  signal?: string;
+  reinforcement?: string;
+  warning?: string;
+  scope?: string;
+}
+```
+
+#### `herald.configure(opts)`
+
+Configure the SDK (optional - uses git context by default).
+
+```typescript
+herald.configure({
+  baseUrl: 'https://custom.ceda.com',
+  token: 'your-api-token',
+  company: 'acme',
+  project: 'backend',
+  user: 'developer'
+});
+```
+
+### Context Detection
+
+By default, the SDK automatically derives context from:
+
+1. **Git remote** - Organization and repository name from git origin
+2. **Git user** - User name from git config
+3. **Path** - Falls back to folder names if not in a git repo
+
+This means you can use the SDK without any configuration in most projects.
+
 ## Links
 
 - **CEDA**: https://getceda.com
@@ -200,4 +331,4 @@ MIT
 
 ---
 
-*Herald v1.25.0 — Pattern memory for AI agents*
+*Herald v1.33.0 — Pattern memory for AI agents*

package/dist/cli/chat.d.ts

@@ -0,0 +1,2 @@
+export declare function runChat(): Promise<void>;
+//# sourceMappingURL=chat.d.ts.map

package/dist/cli/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/cli/chat.ts"],"names":[],"mappings":"AAIA,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAoF7C"}

package/dist/cli/chat.js

@@ -0,0 +1,91 @@
+import * as readline from 'readline';
+const BASE_URL = process.env.CEDA_URL || process.env.HERALD_API_URL || 'https://getceda.com';
+export async function runChat() {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    console.log('\nHerald Pattern Journal\n');
+    console.log('Commands:');
+    console.log('  /learned <insight>  - capture what worked');
+    console.log('  /stuck <insight>    - capture what failed');
+    console.log('  /recall [topic]     - see your patterns');
+    console.log('  /quit               - exit\n');
+    const prompt = () => {
+        rl.question('> ', async (input) => {
+            const trimmed = input.trim();
+            if (!trimmed) {
+                prompt();
+                return;
+            }
+            const [cmd, ...args] = trimmed.split(' ');
+            const text = args.join(' ');
+            if (cmd === '/learned' && text) {
+                try {
+                    await fetch(`${BASE_URL}/api/herald/reflect`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ feeling: 'success', insight: text, session: 'chat' })
+                    });
+                    console.log('Pattern captured\n');
+                }
+                catch {
+                    console.log('Failed to capture pattern\n');
+                }
+            }
+            else if (cmd === '/stuck' && text) {
+                try {
+                    await fetch(`${BASE_URL}/api/herald/reflect`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ feeling: 'stuck', insight: text, session: 'chat' })
+                    });
+                    console.log('Antipattern captured\n');
+                }
+                catch {
+                    console.log('Failed to capture antipattern\n');
+                }
+            }
+            else if (cmd === '/recall') {
+                try {
+                    const url = text
+                        ? `${BASE_URL}/api/herald/reflections?limit=10&topic=${encodeURIComponent(text)}`
+                        : `${BASE_URL}/api/herald/reflections?limit=10`;
+                    const res = await fetch(url);
+                    const data = await res.json();
+                    const patterns = data.patterns || [];
+                    const antipatterns = data.antipatterns || [];
+                    if (patterns.length > 0) {
+                        console.log('Patterns:');
+                        patterns.forEach(p => console.log(`  - ${p.insight}`));
+                    }
+                    else {
+                        console.log('Patterns: (none)');
+                    }
+                    if (antipatterns.length > 0) {
+                        console.log('Antipatterns:');
+                        antipatterns.forEach(p => console.log(`  - ${p.insight}`));
+                    }
+                    else {
+                        console.log('Antipatterns: (none)');
+                    }
+                    console.log('');
+                }
+                catch {
+                    console.log('Failed to recall patterns\n');
+                }
+            }
+            else if (cmd === '/quit') {
+                console.log('Bye! Your patterns are saved.');
+                rl.close();
+                return;
+            }
+            else if (cmd === '/learned' || cmd === '/stuck') {
+                console.log(`Usage: ${cmd} <insight>\n`);
+            }
+            else {
+                console.log('Commands: /learned <text>, /stuck <text>, /recall [topic], /quit\n');
+            }
+            prompt();
+        });
+    };
+    prompt();
+}
+//# sourceMappingURL=chat.js.map

package/dist/cli/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../../src/cli/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAErC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,qBAAqB,CAAC;AAE7F,MAAM,CAAC,KAAK,UAAU,OAAO;IAC3B,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEtF,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACzB,OAAO,CAAC,GAAG,CAAC,6CAA6C,CAAC,CAAC;IAC3D,OAAO,CAAC,GAAG,CAAC,6CAA6C,CAAC,CAAC;IAC3D,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;IAE9C,MAAM,MAAM,GAAG,GAAS,EAAE;QACxB,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAChC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;YAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,EAAE,CAAC;gBACT,OAAO;YACT,CAAC;YAED,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAE5B,IAAI,GAAG,KAAK,UAAU,IAAI,IAAI,EAAE,CAAC;gBAC/B,IAAI,CAAC;oBACH,MAAM,KAAK,CAAC,GAAG,QAAQ,qBAAqB,EAAE;wBAC5C,MAAM,EAAE,MAAM;wBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;wBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;qBAC7E,CAAC,CAAC;oBACH,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;gBACpC,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;gBAC7C,CAAC;YACH,CAAC;iBAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,IAAI,EAAE,CAAC;gBACpC,IAAI,CAAC;oBACH,MAAM,KAAK,CAAC,GAAG,QAAQ,qBAAqB,EAAE;wBAC5C,MAAM,EAAE,MAAM;wBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;wBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;qBAC3E,CAAC,CAAC;oBACH,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;gBACxC,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;gBACjD,CAAC;YACH,CAAC;iBAAM,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBAC7B,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,IAAI;wBACd,CAAC,CAAC,GAAG,QAAQ,0CAA0C,kBAAkB,CAAC,IAAI,CAAC,EAAE;wBACjF,CAAC,CAAC,GAAG,QAAQ,kCAAkC,CAAC;oBAClD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;oBAC7B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAA0F,CAAC;oBAEtH,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;oBACrC,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;oBAE7C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACxB,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;wBACzB,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;oBACzD,CAAC;yBAAM,CAAC;wBACN,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;oBAClC,CAAC;oBAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBAC5B,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;wBAC7B,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;oBAC7D,CAAC;yBAAM,CAAC;wBACN,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;oBACtC,CAAC;oBACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAClB,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;gBAC7C,CAAC;YACH,CAAC;iBAAM,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;gBAC3B,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;gBAC7C,EAAE,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO;YACT,CAAC;iBAAM,IAAI,GAAG,KAAK,UAAU,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAClD,OAAO,CAAC,GAAG,CAAC,UAAU,GAAG,cAAc,CAAC,CAAC;YAC3C,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;YACpF,CAAC;YACD,MAAM,EAAE,CAAC;QACX,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IACF,MAAM,EAAE,CAAC;AACX,CAAC"}