@aion0/forge 0.9.1 → 0.9.3

package/lib/__tests__/foreach-snapshot.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Step-5 verification: snapshotIteration captures node states + correctly
+ * advances the iterations[] history. (Full checkPipelineCompletion has
+ * filesystem + scheduling side effects — exercised end-to-end in Step 7.)
+ *
+ * Run:  npx tsx lib/__tests__/foreach-snapshot.test.ts
+ */
+
+import { snapshotIteration } from '../pipeline';
+
+let passed = 0, failed = 0;
+function check(name: string, fn: () => void) {
+  try { fn(); console.log(`  ✓ ${name}`); passed++; }
+  catch (e) { console.log(`  ✗ ${name}\n    ${(e as Error).message}`); failed++; }
+}
+
+function makePipeline(items: unknown[], currentIndex = 0): any {
+  return {
+    id: 'test123',
+    workflowName: 'test',
+    status: 'running',
+    input: {},
+    vars: {},
+    nodes: {
+      a: { status: 'done', outputs: { x: '1' } },
+      b: { status: 'done', outputs: { y: '2' }, error: undefined },
+    },
+    nodeOrder: ['a', 'b'],
+    createdAt: '2026-01-01T00:00:00.000Z',
+    forEach: {
+      items,
+      currentIndex,
+      total: items.length,
+      asName: 'item',
+      onFailure: 'continue',
+      iterations: [],
+    },
+  };
+}
+
+console.log('snapshotIteration tests');
+
+check('snapshot captures all-done nodes with status="done"', () => {
+  const p = makePipeline([1, 2, 3]);
+  snapshotIteration(p, false);
+  if (p.forEach.iterations.length !== 1) throw new Error('iterations length wrong');
+  const iter = p.forEach.iterations[0];
+  if (iter.status !== 'done') throw new Error(`status wrong: ${iter.status}`);
+  if (iter.index !== 0) throw new Error('index wrong');
+  if (iter.nodes.a.status !== 'done') throw new Error('node a status wrong');
+  if (iter.nodes.a.outputs.x !== '1') throw new Error('node a output not preserved');
+});
+
+check('snapshot captures failed iter with status="failed"', () => {
+  const p = makePipeline([1, 2]);
+  p.nodes.b.status = 'failed';
+  p.nodes.b.error = 'boom';
+  snapshotIteration(p, true);
+  const iter = p.forEach.iterations[0];
+  if (iter.status !== 'failed') throw new Error(`status wrong: ${iter.status}`);
+  if (iter.nodes.b.error !== 'boom') throw new Error('error not preserved');
+});
+
+check('startedAt = createdAt for first iter', () => {
+  const p = makePipeline([1, 2]);
+  snapshotIteration(p, false);
+  if (p.forEach.iterations[0].startedAt !== p.createdAt) throw new Error('first startedAt should = createdAt');
+});
+
+check('startedAt = previous completedAt for subsequent iters', () => {
+  const p = makePipeline([1, 2]);
+  snapshotIteration(p, false);
+  const firstCompleted = p.forEach.iterations[0].completedAt;
+  p.forEach.currentIndex = 1;
+  snapshotIteration(p, false);
+  if (p.forEach.iterations[1].startedAt !== firstCompleted) {
+    throw new Error('second iter startedAt should chain from prev completedAt');
+  }
+});
+
+check('outputs are deep-copied (mutation safety)', () => {
+  const p = makePipeline([1]);
+  snapshotIteration(p, false);
+  const iter = p.forEach.iterations[0];
+  // Mutate live node — snapshot should NOT change
+  p.nodes.a.outputs.x = 'MUTATED';
+  if (iter.nodes.a.outputs.x !== '1') throw new Error('snapshot was mutated; need defensive copy');
+});
+
+check('multiple iterations accumulate', () => {
+  const p = makePipeline([1, 2, 3]);
+  snapshotIteration(p, false);
+  p.forEach.currentIndex = 1;
+  snapshotIteration(p, false);
+  p.forEach.currentIndex = 2;
+  snapshotIteration(p, true);
+  if (p.forEach.iterations.length !== 3) throw new Error('expected 3 iters');
+  if (p.forEach.iterations[2].status !== 'failed') throw new Error('iter 3 should be failed');
+  if (p.forEach.iterations[0].index !== 0) throw new Error('iter 0 index wrong');
+  if (p.forEach.iterations[1].index !== 1) throw new Error('iter 1 index wrong');
+  if (p.forEach.iterations[2].index !== 2) throw new Error('iter 2 index wrong');
+});
+
+check('no-op when pipeline.forEach undefined', () => {
+  const p: any = { id: 'x', nodes: {}, createdAt: '2026-01-01' };
+  snapshotIteration(p, false);
+  // Should not throw, should not add anything
+  if (p.forEach !== undefined) throw new Error('should leave forEach undefined');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/lib/__tests__/foreach-source.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Step-4 verification: resolveForEachSource resolves + splits items.
+ * Run:  npx tsx lib/__tests__/foreach-source.test.ts
+ */
+
+import { resolveForEachSource } from '../pipeline';
+
+let passed = 0, failed = 0;
+function check(name: string, fn: () => void) {
+  try { fn(); console.log(`  ✓ ${name}`); passed++; }
+  catch (e) { console.log(`  ✗ ${name}\n    ${(e as Error).message}`); failed++; }
+}
+function eqArr(a: unknown[], b: unknown[], label = '') {
+  if (a.length !== b.length || a.some((v, i) => v !== b[i])) {
+    throw new Error(`${label}: expected ${JSON.stringify(b)}, got ${JSON.stringify(a)}`);
+  }
+}
+
+console.log('resolveForEachSource tests');
+
+check('string source via {{input.x}} template, default split=","', () => {
+  const items = resolveForEachSource(
+    { source: '{{input.ids}}' },
+    { ids: '111,222,333' },
+    {},
+  );
+  eqArr(items, ['111', '222', '333']);
+});
+
+check('string source with whitespace around commas — trimmed', () => {
+  const items = resolveForEachSource(
+    { source: '{{input.ids}}' },
+    { ids: ' 111 ,222 , 333  ' },
+    {},
+  );
+  eqArr(items, ['111', '222', '333']);
+});
+
+check('string source with empty entries dropped', () => {
+  const items = resolveForEachSource(
+    { source: '{{input.ids}}' },
+    { ids: '111,,222, ,333,' },
+    {},
+  );
+  eqArr(items, ['111', '222', '333']);
+});
+
+check('empty input.ids → empty array', () => {
+  const items = resolveForEachSource({ source: '{{input.ids}}' }, { ids: '' }, {});
+  eqArr(items, []);
+});
+
+check('input missing → empty string template → empty array', () => {
+  const items = resolveForEachSource({ source: '{{input.missing}}' }, {}, {});
+  eqArr(items, []);
+});
+
+check('custom split: ";"', () => {
+  const items = resolveForEachSource(
+    { source: '{{input.ids}}', split: ';' },
+    { ids: '111;222;333' },
+    {},
+  );
+  eqArr(items, ['111', '222', '333']);
+});
+
+check('array literal source — used as-is', () => {
+  const items = resolveForEachSource(
+    { source: ['a', 'b', 'c'] },
+    {},
+    {},
+  );
+  eqArr(items, ['a', 'b', 'c']);
+});
+
+check('array literal with objects — preserved', () => {
+  const items = resolveForEachSource(
+    { source: [{ iid: 1 }, { iid: 2 }] },
+    {},
+    {},
+  );
+  if (items.length !== 2) throw new Error('length wrong');
+  if ((items[0] as any).iid !== 1) throw new Error('first item wrong');
+});
+
+check('vars source resolves', () => {
+  const items = resolveForEachSource(
+    { source: '{{vars.list}}' },
+    {},
+    { list: 'a,b,c' },
+  );
+  eqArr(items, ['a', 'b', 'c']);
+});
+
+check('literal string with no template, just split', () => {
+  const items = resolveForEachSource(
+    { source: 'foo,bar' },
+    {},
+    {},
+  );
+  eqArr(items, ['foo', 'bar']);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/lib/__tests__/foreach-template.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Step-3 verification: resolveTemplate handles for_each context.
+ * Run:  npx tsx lib/__tests__/foreach-template.test.ts
+ */
+
+import { resolveTemplate } from '../pipeline';
+
+let passed = 0;
+let failed = 0;
+function check(name: string, fn: () => void) {
+  try { fn(); console.log(`  ✓ ${name}`); passed++; }
+  catch (e) { console.log(`  ✗ ${name}\n    ${(e as Error).message}`); failed++; }
+}
+function eq(actual: string, expected: string, label = '') {
+  if (actual !== expected) {
+    throw new Error(`${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+const baseCtx = { input: {}, vars: {}, nodes: {} };
+
+console.log('resolveTemplate + for_each tests');
+
+check('no forEach in ctx — {{item}} is literal passthrough', () => {
+  eq(resolveTemplate('hello {{item}}', baseCtx), 'hello {{item}}');
+});
+
+check('scalar item: {{<as>}} substitutes', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'bug_id', item: 1213844, index: 0, total: 3 } };
+  eq(resolveTemplate('Fix bug {{bug_id}} now', ctx), 'Fix bug 1213844 now');
+});
+
+check('string item: {{<as>}} preserves string', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'name', item: 'alice', index: 0, total: 1 } };
+  eq(resolveTemplate('hi {{name}}', ctx), 'hi alice');
+});
+
+check('object item: {{<as>.field}} dotted access', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'mr', item: { iid: 42, title: 'fix x' }, index: 0, total: 1 } };
+  eq(resolveTemplate('MR !{{mr.iid}}: {{mr.title}}', ctx), 'MR !42: fix x');
+});
+
+check('object item: missing field → empty string', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'mr', item: { iid: 42 }, index: 0, total: 1 } };
+  eq(resolveTemplate('author=@{{mr.author}}', ctx), 'author=@');
+});
+
+check('object item: {{<as>}} alone → JSON', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'mr', item: { iid: 42, t: 'x' }, index: 0, total: 1 } };
+  eq(resolveTemplate('raw={{mr}}', ctx), 'raw={"iid":42,"t":"x"}');
+});
+
+check('{{loop.index}} + {{loop.total}}', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'item', item: 'x', index: 2, total: 5 } };
+  eq(resolveTemplate('Step {{loop.index}} of {{loop.total}}', ctx), 'Step 2 of 5');
+});
+
+check('shellMode escapes scalar item', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'name', item: "o'brien", index: 0, total: 1 } };
+  // shellEscapeAnsiC: ' → \'
+  const out = resolveTemplate("echo '{{name}}'", ctx, true);
+  if (!out.includes("o\\'brien")) throw new Error(`expected escaped apostrophe, got: ${out}`);
+});
+
+check('{{raw:<as>}} bypasses shell escape', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'name', item: "o'brien", index: 0, total: 1 } };
+  // raw: keeps verbatim
+  eq(resolveTemplate('{{raw:name}}', ctx, true), "o'brien");
+});
+
+check('input.x still works alongside forEach', () => {
+  const ctx = { input: { proj: 'FortiNAC' }, vars: {}, nodes: {}, forEach: { asName: 'bug_id', item: 1, index: 0, total: 1 } };
+  eq(resolveTemplate('{{input.proj}}/mantis-{{bug_id}}', ctx), 'FortiNAC/mantis-1');
+});
+
+check('nodes.X.outputs.Y still works alongside forEach', () => {
+  const ctx: any = {
+    input: {},
+    vars: {},
+    nodes: { ingest: { status: 'done', outputs: { ctx: 'hello' }, iterations: 1 } },
+    forEach: { asName: 'item', item: 'x', index: 0, total: 1 },
+  };
+  eq(resolveTemplate('{{nodes.ingest.outputs.ctx}}/{{item}}', ctx), 'hello/x');
+});
+
+check('run.tmp_dir still works alongside forEach', () => {
+  const ctx = {
+    ...baseCtx,
+    tmpDir: '/path/.forge/worktrees/pipeline-abc',
+    forEach: { asName: 'bug_id', item: 42, index: 0, total: 1 },
+  };
+  eq(resolveTemplate('{{run.tmp_dir}}/mantis-{{bug_id}}', ctx),
+     '/path/.forge/worktrees/pipeline-abc/mantis-42');
+});
+
+check('forEach.item = null → empty string', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'x', item: null, index: 0, total: 1 } };
+  eq(resolveTemplate('[{{x}}]', ctx), '[]');
+});
+
+check('forEach.item = false → "false"', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'x', item: false, index: 0, total: 1 } };
+  eq(resolveTemplate('[{{x}}]', ctx), '[false]');
+});
+
+check('loop.index works even when item is undefined-but-asName-set (defensive)', () => {
+  const ctx = { ...baseCtx, forEach: { asName: 'item', item: undefined, index: 7, total: 9 } };
+  eq(resolveTemplate('{{loop.index}}/{{loop.total}}', ctx), '7/9');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/lib/chat/agent-loop.ts

@@ -72,7 +72,7 @@ interface ProviderResolution {
  * Anthropic's API is the only first-class non-OpenAI shape we ship; LiteLLM /
  * Azure / OpenAI proxies / Grok / Google-via-LiteLLM all speak OpenAI.
  */
-function inferAdapter(provider: string | undefined): 'anthropic' | 'openai' {
+export function inferAdapter(provider: string | undefined): 'anthropic' | 'openai' {
   const p = (provider || '').toLowerCase();
   if (p === 'anthropic' || p === 'claude') return 'anthropic';
   return 'openai';
@@ -106,7 +106,7 @@ export function defaultBaseUrl(provider: string | undefined): string {
   }
 }
 
-function pickBaseUrl(
+export function pickBaseUrl(
   profile: { baseUrl?: string; env?: Record<string, string>; provider?: string },
   adapter: 'anthropic' | 'openai',
 ): string {
@@ -119,7 +119,7 @@ function pickBaseUrl(
   return defaultBaseUrl(profile.provider);
 }
 
-function pickApiKey(profile: { apiKey?: string; env?: Record<string, string> }, adapter: 'anthropic' | 'openai'): string {
+export function pickApiKey(profile: { apiKey?: string; env?: Record<string, string> }, adapter: 'anthropic' | 'openai'): string {
   if (profile.apiKey) return profile.apiKey;
   const env = profile.env || {};
   if (adapter === 'anthropic') return env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN || '';

package/lib/chat-standalone.ts

@@ -33,7 +33,7 @@
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
 import {
   createSession, getSession, listSessions, updateSession, deleteSession, listMessages,
-  clearSessionMessages, ensureMainSession, forkSession,
+  clearSessionMessages, ensureMainSession, forkSession, appendMessage,
 } from './chat/session-store';
 import { runTurn, type AgentEvent } from './chat/agent-loop';
 import { bridgePush } from './chat/bridge-client';
@@ -182,6 +182,28 @@ async function handleMessagePost(req: IncomingMessage, res: ServerResponse, id:
   sendJson(res, 202, { accepted: true, topic: `chat:${id}` });
 }
 
+/**
+ * Inject a pre-formed message into a session WITHOUT running a turn —
+ * used by schedule actions (and similar server-side surfaces) to push
+ * a notification into an open chat. Going via this endpoint (instead
+ * of calling appendMessage in the caller's process) is what gives the
+ * UI a real-time `message_saved` SSE push; otherwise the message lands
+ * in SQLite but the open tab only sees it after a reload.
+ */
+async function handleInjectMessage(req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  const session = getSession(id);
+  if (!session) return sendJson(res, 404, { error: 'session not found' });
+  const body = await readJson(req);
+  const role: 'user' | 'assistant' = body?.role === 'user' ? 'user' : 'assistant';
+  const blocks = Array.isArray(body?.blocks) ? body.blocks : null;
+  if (!blocks || blocks.length === 0) return sendJson(res, 400, { error: 'blocks[] required' });
+  const saved = appendMessage({ session_id: id, role, blocks });
+  // Payload shape must match what agent-loop emits — extension's
+  // messageFromServer(event.data) reads .id/.role/.blocks/.ts directly.
+  fanoutEvent(id, { type: 'message_saved', message_id: saved.id, data: saved });
+  sendJson(res, 200, { ok: true, message_id: saved.id });
+}
+
 function handleEventsSse(_req: IncomingMessage, res: ServerResponse, id: string): void {
   // Verify the session exists before opening the stream.
   const session = getSession(id);
@@ -244,6 +266,9 @@ async function route(req: IncomingMessage, res: ServerResponse): Promise<void> {
   if (messages && m === 'POST')   return handleMessagePost(req, res, messages[1]!);
   if (messages && m === 'DELETE') return handleSessionClearMessages(req, res, messages[1]!);
 
+  const inject = /^\/api\/sessions\/([^/]+)\/inject$/.exec(url.pathname);
+  if (inject && m === 'POST') return handleInjectMessage(req, res, inject[1]!);
+
   const fork = /^\/api\/sessions\/([^/]+)\/fork$/.exec(url.pathname);
   if (fork && m === 'POST') return handleSessionFork(req, res, fork[1]!);
 

package/lib/claude-process.ts

@@ -5,7 +5,7 @@
  * Runs on your Claude Code subscription, not API key.
  */
 
-import { spawn, type ChildProcess } from 'node:child_process';
+import { spawn, execSync, type ChildProcess } from 'node:child_process';
 import { loadSettings } from './settings';
 
 export interface ClaudeMessage {
@@ -93,13 +93,16 @@ export function sendToClaudeSession(
   const env = { ...process.env };
   delete env.CLAUDECODE;
 
-  // Resolve full path so spawn works without shell for PATH lookup
+  // Resolve full path so spawn works without shell for PATH lookup.
+  // Was a lazy require() — fired ReferenceError on Claude task spawn
+  // under ESM concurrent loads. Now top-level imported.
   let resolvedClaude = claudePath;
   if (!claudePath.startsWith('/')) {
     try {
-      const { execSync: execS } = require('node:child_process');
-      resolvedClaude = execS(`which ${claudePath}`, { encoding: 'utf-8', env }).trim() || claudePath;
-    } catch {}
+      resolvedClaude = execSync(`which ${claudePath}`, { encoding: 'utf-8', env }).trim() || claudePath;
+    } catch (e) {
+      console.warn(`[claude] which ${claudePath} failed: ${(e as Error).message}`);
+    }
   }
 
   const child = spawn(resolvedClaude, args, {

package/lib/connectors/sync.ts

@@ -139,7 +139,9 @@ export interface SyncResult {
  * cache the registry row — the manifest is pulled on demand at install
  * time (see installFromRegistry).
  */
-export async function syncRegistry(opts: { refreshInstalled?: boolean } = {}): Promise<SyncResult> {
+export async function syncRegistry(
+  opts: { refreshInstalled?: boolean; force?: boolean } = {},
+): Promise<SyncResult> {
   const base = baseUrl();
   console.log(`[connectors] Syncing registry from ${base}`);
   let registry: RegistryFile;
@@ -171,7 +173,11 @@ export async function syncRegistry(opts: { refreshInstalled?: boolean } = {}): P
       const local = getConnector(e.id);
       const isConfigOnly = configOnly.has(e.id);
       if (!local && !isConfigOnly) continue;
-      if (local && local.version === e.version) continue;
+      // Normally skip when local matches registry — saves bandwidth.
+      // `force` overrides so the user can pull a fresh manifest even
+      // when the version string hasn't changed (e.g. param-description
+      // tweaks shipped under the same patch version).
+      if (!opts.force && local && local.version === e.version) continue;
       try {
         const yamlText = await fetchManifest(e.id, e.manifest);
         installConnector(e.id, yamlText);

package/lib/crypto.ts

@@ -63,5 +63,5 @@ export function hashSecret(value: string): string {
 }
 
 /** Secret field names in settings */
-export const SECRET_FIELDS = ['telegramBotToken', 'telegramTunnelPassword', 'temperKey'] as const;
+export const SECRET_FIELDS = ['telegramBotToken', 'telegramTunnelPassword', 'temperKey', 'smtpPassword'] as const;
 export type SecretField = typeof SECRET_FIELDS[number];

package/lib/dirs.ts

@@ -9,7 +9,7 @@
 
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { existsSync, mkdirSync, renameSync, copyFileSync } from 'node:fs';
+import { existsSync, mkdirSync, renameSync, copyFileSync, readFileSync } from 'node:fs';
 
 /** Shared config directory — only binaries, fixed at ~/.forge/ */
 export function getConfigDir(): string {
@@ -85,15 +85,30 @@ export function migrateDataDir(): void {
   console.log('[forge] Migration complete. Old files kept as backup.');
 }
 
-/** Claude Code home directory — skills, commands, sessions */
+/** Claude Code home directory — skills, commands, sessions.
+ *
+ *  Circular-dep note: dirs ↔ settings (settings.ts imports getDataDir).
+ *  Used to do `require('./settings')` here as a lazy hack — but that
+ *  fires ReferenceError under ESM concurrent loads, and dirs is on
+ *  the hot path for every task / connector / pipeline node.
+ *
+ *  Cut the cycle by reading the YAML directly here. No parser needed:
+ *  we only need one field (`claudeHome`), which is plain "key: value".
+ *  Falls back to ~/.claude if anything goes sideways.
+ */
 export function getClaudeDir(): string {
-  // Env var takes precedence
   if (process.env.CLAUDE_HOME) return process.env.CLAUDE_HOME;
-  // Try to read from settings (lazy require to avoid circular dependency)
   try {
-    const { loadSettings } = require('./settings');
-    const settings = loadSettings();
-    if (settings.claudeHome) return settings.claudeHome.replace(/^~/, homedir());
+    const settingsFile = join(getDataDir(), 'settings.yaml');
+    if (existsSync(settingsFile)) {
+      const raw = readFileSync(settingsFile, 'utf-8');
+      // Match a top-level `claudeHome: <value>` line. Tolerates quoted /
+      // unquoted strings and stray whitespace. Not a full YAML parser
+      // because we explicitly want to avoid loading the YAML module
+      // (and settings.ts) from this hot path.
+      const m = raw.match(/^\s*claudeHome:\s*["']?(.+?)["']?\s*$/m);
+      if (m?.[1]) return m[1].replace(/^~/, homedir());
+    }
   } catch {}
   return join(homedir(), '.claude');
 }