@agentled/cli 0.6.5 → 0.6.7

package/dist/utils/test-runner.js

@@ -0,0 +1,283 @@
+/**
+ * Declarative test runner — runs assertions against captured fixture outputs
+ * (zero credits) or live API calls (`--live`, costs credits for AI/app steps).
+ *
+ * Test file format (tests/<workflowId>.test.json):
+ * {
+ *   "workflowId": "wf_abc",
+ *   "fixtureExecutionId": "exec_xyz",
+ *   "steps": [
+ *     {
+ *       "stepId": "score-lead",
+ *       "type": "aiAction",
+ *       "fixtureSource": "exec_xyz/score-lead",
+ *       "assertions": [
+ *         { "verb": "hasKey",   "path": "score" },
+ *         { "verb": "isType",   "path": "score", "expect": "number" },
+ *         { "verb": "inRange",  "path": "score", "min": 0, "max": 100 },
+ *         { "verb": "matches",  "path": "decision", "pattern": "^(HOT|WARM|COLD)$" }
+ *       ]
+ *     }
+ *   ]
+ * }
+ *
+ * Assertion verbs: hasKey, isType, equals, matches, inRange, hasLength, contains
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+// ---------------------------------------------------------------------------
+// Path accessor
+// ---------------------------------------------------------------------------
+export function getPath(obj, dotPath) {
+    if (!dotPath || dotPath === '.')
+        return obj;
+    const parts = dotPath.split('.');
+    let cur = obj;
+    for (const part of parts) {
+        if (cur === null || cur === undefined)
+            return undefined;
+        if (Array.isArray(cur)) {
+            const idx = parseInt(part, 10);
+            cur = isNaN(idx) ? undefined : cur[idx];
+        }
+        else if (typeof cur === 'object') {
+            cur = cur[part];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}
+// ---------------------------------------------------------------------------
+// Assertion runner
+// ---------------------------------------------------------------------------
+export function runAssertion(output, assertion) {
+    const value = getPath(output, assertion.path);
+    const { verb } = assertion;
+    switch (verb) {
+        case 'hasKey': {
+            const pass = value !== undefined && value !== null;
+            return { pass, reason: pass ? '' : `Expected key "${assertion.path}" present and non-null, got: ${JSON.stringify(value)}` };
+        }
+        case 'isType': {
+            const expect = assertion.expect;
+            const actual = Array.isArray(value) ? 'array' : typeof value;
+            return { pass: actual === expect, reason: `Expected "${assertion.path}" type "${expect}", got "${actual}"` };
+        }
+        case 'equals': {
+            const pass = JSON.stringify(value) === JSON.stringify(assertion.expect);
+            return { pass, reason: pass ? '' : `Expected "${assertion.path}" to equal ${JSON.stringify(assertion.expect)}, got ${JSON.stringify(value)}` };
+        }
+        case 'matches': {
+            if (typeof value !== 'string')
+                return { pass: false, reason: `Expected "${assertion.path}" string for regex, got ${typeof value}` };
+            const re = new RegExp(assertion.pattern ?? '');
+            const pass = re.test(value);
+            return { pass, reason: pass ? '' : `Expected "${assertion.path}" to match /${assertion.pattern}/, got "${value}"` };
+        }
+        case 'inRange': {
+            if (typeof value !== 'number')
+                return { pass: false, reason: `Expected "${assertion.path}" number, got ${typeof value}` };
+            const min = assertion.min ?? -Infinity;
+            const max = assertion.max ?? Infinity;
+            const pass = value >= min && value <= max;
+            return { pass, reason: pass ? '' : `Expected "${assertion.path}" between ${min} and ${max}, got ${value}` };
+        }
+        case 'hasLength': {
+            if (!Array.isArray(value) && typeof value !== 'string')
+                return { pass: false, reason: `Expected "${assertion.path}" array/string, got ${typeof value}` };
+            const len = value.length;
+            if (assertion.expect !== undefined) {
+                const pass = len === Number(assertion.expect);
+                return { pass, reason: pass ? '' : `Expected length ${assertion.expect}, got ${len}` };
+            }
+            return { pass: len > 0, reason: `Expected non-empty, got length ${len}` };
+        }
+        case 'contains': {
+            if (typeof value === 'string') {
+                const pass = value.includes(String(assertion.expect ?? ''));
+                return { pass, reason: pass ? '' : `Expected "${assertion.path}" to contain "${assertion.expect}", got "${value}"` };
+            }
+            if (Array.isArray(value)) {
+                const pass = value.some((item) => JSON.stringify(item) === JSON.stringify(assertion.expect));
+                return { pass, reason: pass ? '' : `Expected array to contain ${JSON.stringify(assertion.expect)}` };
+            }
+            return { pass: false, reason: `Expected "${assertion.path}" string/array for contains` };
+        }
+        default:
+            return { pass: false, reason: `Unknown assertion verb: "${verb}"` };
+    }
+}
+// ---------------------------------------------------------------------------
+// Fixture loader
+// ---------------------------------------------------------------------------
+export function loadFixture(wsDir, fixtureSource) {
+    const parts = fixtureSource.split('/');
+    if (parts.length < 2)
+        return null;
+    const [executionId, ...stepParts] = parts;
+    const stepId = stepParts.join('/');
+    const candidates = [];
+    if (wsDir)
+        candidates.push(join(wsDir, 'fixtures', 'step-outputs', executionId, `${stepId}.json`));
+    candidates.push(resolve('fixtures', 'step-outputs', executionId, `${stepId}.json`));
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            try {
+                return JSON.parse(readFileSync(candidate, 'utf-8'));
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Run a step in fixture mode (zero credits)
+// ---------------------------------------------------------------------------
+export function runStepFixture(step, wsDir) {
+    const result = { stepId: step.stepId, description: step.description, passed: 0, failed: 0, skipped: 0, errors: [], mode: 'fixture' };
+    if (!step.fixtureSource) {
+        result.mode = 'skipped';
+        result.skipped = step.assertions.length;
+        result.errors.push('No fixtureSource set — run `agentled fixture capture` first.');
+        return result;
+    }
+    const fixture = loadFixture(wsDir, step.fixtureSource);
+    if (!fixture) {
+        result.mode = 'skipped';
+        result.skipped = step.assertions.length;
+        result.errors.push(`Fixture not found: ${step.fixtureSource}`);
+        return result;
+    }
+    const output = fixture.output ?? fixture;
+    for (const assertion of step.assertions) {
+        if (assertion.path === '?') {
+            result.skipped++;
+            continue;
+        }
+        const { pass, reason } = runAssertion(output, assertion);
+        if (pass)
+            result.passed++;
+        else {
+            result.failed++;
+            result.errors.push(reason);
+        }
+    }
+    return result;
+}
+export async function runStepLive(step, client) {
+    const result = { stepId: step.stepId, description: step.description, passed: 0, failed: 0, skipped: 0, errors: [], mode: 'live' };
+    let output;
+    try {
+        if (step.type === 'code') {
+            const response = await client.testCodeAction(step.codeConfig?.code ?? '', step.codeConfig?.language ?? 'javascript', step.liveInputs ?? {});
+            output = response.output ?? response.result ?? response;
+        }
+        else if (step.type === 'aiAction' || step.type === 'aiActionWithTools') {
+            if (!step.promptTemplate) {
+                result.mode = 'skipped';
+                result.skipped = step.assertions.length;
+                result.errors.push('Live mode requires "promptTemplate".');
+                return result;
+            }
+            const response = await client.testAiAction(step.promptTemplate, step.promptVariables ?? step.liveInputs ?? {}, step.promptResponseStructure ?? {});
+            output = response.output ?? response.result ?? response;
+        }
+        else if (step.type === 'appAction') {
+            if (!step.appId || !step.actionId) {
+                result.mode = 'skipped';
+                result.skipped = step.assertions.length;
+                result.errors.push('Live mode requires "appId" and "actionId".');
+                return result;
+            }
+            const response = await client.testAppAction(step.appId, step.actionId, step.appInputs ?? step.liveInputs ?? {});
+            output = response.output ?? response.result ?? response;
+        }
+        else {
+            result.mode = 'skipped';
+            result.skipped = step.assertions.length;
+            result.errors.push(`Step type "${step.type}" doesn't support live testing.`);
+            return result;
+        }
+    }
+    catch (err) {
+        result.failed = step.assertions.length;
+        result.errors.push(`API call failed: ${err instanceof Error ? err.message : String(err)}`);
+        return result;
+    }
+    for (const assertion of step.assertions) {
+        if (assertion.path === '?') {
+            result.skipped++;
+            continue;
+        }
+        const { pass, reason } = runAssertion(output, assertion);
+        if (pass)
+            result.passed++;
+        else {
+            result.failed++;
+            result.errors.push(reason);
+        }
+    }
+    return result;
+}
+export function makeTestSkeleton(workflowId, pipeline) {
+    const allSteps = (Array.isArray(pipeline.steps) ? pipeline.steps : []);
+    const testable = allSteps.filter((s) => ['aiAction', 'aiActionWithTools', 'appAction', 'code'].includes(String(s.type ?? '')));
+    return {
+        workflowId,
+        workflowName: String(pipeline.name ?? workflowId),
+        description: `Auto-generated test skeleton for ${pipeline.name ?? workflowId}. Edit assertions to match expected outputs.`,
+        fixtureExecutionId: null,
+        steps: testable.map((s) => {
+            const stepId = String(s.id ?? '');
+            const type = String(s.type ?? '');
+            const app = s.app;
+            const test = {
+                stepId,
+                type,
+                description: String(s.name ?? stepId),
+                fixtureSource: null,
+                assertions: [],
+            };
+            if (type === 'aiAction' || type === 'aiActionWithTools') {
+                const responseStructure = s.pipelineStepPrompt?.responseStructure;
+                if (responseStructure && typeof responseStructure === 'object') {
+                    test.assertions = Object.keys(responseStructure).slice(0, 5).map((key) => ({
+                        verb: 'hasKey',
+                        path: key,
+                        comment: `Step should output a "${key}" field`,
+                    }));
+                }
+                else {
+                    test.assertions = [{ verb: 'hasKey', path: '?', comment: 'Replace ? with an expected output field' }];
+                }
+            }
+            else if (type === 'appAction') {
+                const actionId = String(app?.actionId ?? '');
+                if (actionId.includes('read-list')) {
+                    test.assertions = [
+                        { verb: 'hasKey', path: 'listEntries' },
+                        { verb: 'isType', path: 'listEntries', expect: 'array' },
+                    ];
+                }
+                else if (actionId.includes('find-email')) {
+                    test.assertions = [
+                        { verb: 'hasKey', path: 'email' },
+                        { verb: 'matches', path: 'email', pattern: '.+@.+\\..+' },
+                    ];
+                }
+                else {
+                    test.assertions = [{ verb: 'hasKey', path: '?', comment: 'Replace ? with an expected output field' }];
+                }
+            }
+            else if (type === 'code') {
+                test.assertions = [{ verb: 'hasKey', path: '?', comment: 'Replace ? with an expected output field' }];
+            }
+            return test;
+        }),
+    };
+}
+//# sourceMappingURL=test-runner.js.map

package/dist/utils/test-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-runner.js","sourceRoot":"","sources":["../../src/utils/test-runner.ts"],"names":[],"mappings":"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"}

package/dist/utils/workspace-folder.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Workspace folder helpers — local agentled_<slug>/ directory used as the
+ * agent's working tree for building, testing, and iterating on workflows.
+ *
+ * Folder layout:
+ *
+ *   agentled_<slug>/
+ *   ├── README.md                # agent-facing guide
+ *   ├── .agentled/
+ *   │   ├── workspace.json       # workspaceId, slug, apiBase, syncedAt
+ *   │   └── cache/
+ *   │       ├── apps.json        # app registry
+ *   │       └── models.json      # supported models
+ *   ├── docs/
+ *   │   ├── SKILL.md             # full skill reference (copied from package)
+ *   │   └── GOTCHAS.md           # documented failure modes
+ *   ├── examples/
+ *   │   ├── scaffolds/           # bundled scaffold JSONs (editable)
+ *   │   └── live/                # workflows pulled from the workspace
+ *   ├── fixtures/
+ *   │   └── step-outputs/        # captured step outputs (zero-credit replay)
+ *   ├── tests/                   # <wfId>.test.json declarative test files
+ *   └── drafts/                  # in-progress pipeline JSON files
+ */
+export interface WorkspaceMeta {
+    workspaceId: string;
+    slug: string;
+    name: string;
+    apiBase: string;
+    syncedAt: string;
+}
+export declare function findWorkspaceDir(cwd?: string): string | null;
+export declare function readWorkspaceMeta(wsDir: string): WorkspaceMeta;
+export declare function writeWorkspaceMeta(wsDir: string, meta: WorkspaceMeta): void;
+export declare function bundledScaffoldsDir(): string;
+export declare function bundledSkillMd(): string;
+export declare const GOTCHAS_MD = "# Agentled \u2014 Documented Failure Modes (GOTCHAS)\n\nThese pass JSON syntax validation but silently misbehave at runtime.\nRun `agentled workflows lint <file>` to catch them statically before deploying.\n\n---\n\n## 1. `criteria` not `conditions` in entryConditions  [CRITERIA_NOT_CONDITIONS]\n\n**Wrong:** `{ \"entryConditions\": { \"conditions\": [...] } }`\n**Correct:** `{ \"entryConditions\": { \"criteria\": [...] } }`\n\nThe executor reads `entryConditions.criteria`. The key `conditions` is silently ignored.\n\n---\n\n## 2. `variable` not `field` in criteria items  [VARIABLE_NOT_FIELD]\n\n**Wrong:** `{ \"field\": \"{{steps.x.score}}\", \"operator\": \">\", \"value\": 70 }`\n**Correct:** `{ \"variable\": \"{{steps.x.score}}\", \"operator\": \">\", \"value\": 70 }`\n\nUsing `field` causes the criterion to be silently skipped.\n\n---\n\n## 3. Gmail label_id must be the internal Label_XXXX ID  [GMAIL_LABEL_DISPLAY_NAME]\n\nGmail's API requires `Label_XXXXXXXXXX` IDs, not display names.\nAdd a `GMAIL_CREATE_LABEL` step before and use `{{steps.ensure-label.id}}`.\n\n---\n\n## 4. `aiActionWithTools` with no tools  [AI_STEP_TOOLS_REQUIRED]\n\nA step with `type: \"aiActionWithTools\"` must have at least one tool in\n`step.tools` or `step.agent.tools`.\n\nValid `builtinType` values: `web_search`, `file_search`, `code_interpreter`,\n`fetch_website_content`, `kg_search`, `kg_traverse`, `kg_nodes`, `kg_write`,\n`workspace_memory`.\n\n---\n\n## 5. Email steps need type + approval action + outreachProfile  [EMAIL_MISSING_*]\n\nThree required pieces:\n- `pipelineStepPrompt.type: \"email\"`\n- `onApproval.action: \"schedule-email\"`\n- `outreachProfile` input page in `context.inputPages`\n\nMissing the schedule-email action means the email is drafted but never sent.\n\n---\n\n## 6. Only the first step in a loop gets `loopConfig`  [LOOP_CONFIG_MULTIPLE_STEPS]\n\n`loopConfig` must be on the first step in the loop chain only. Subsequent\nsteps inside the loop iterate automatically.\n\n---\n\n## 7. Don't pass raw `{{input.*}}` directly to search APIs  [RAW_INPUT_TO_SEARCH]\n\nAdd an aiAction step before the search that generates optimized queries.\nRaw user input makes poor search queries.\n\n---\n\n## 8. Child workflows must use `return` step, not `milestone`  [CHILD_WORKFLOW_NO_RETURN]\n\nIf a workflow is called via `agentled.call-workflow`, use `type: \"return\"`.\n`milestone` produces no return data. Also set `context.executionInputConfig.internal: true`.\n\n---\n\n## 9. Model IDs are internal format, not Anthropic format  [MODEL_ID_FORMAT]\n\nWrong: `claude-sonnet-4-6`. Correct: `claude-4-6-sonnet`.\nRun `agentled models list` for valid internal IDs.\n\n---\n\n## 10. Native app actionId must include appId prefix  [ACTION_ID_MISSING_PREFIX]\n\nWrong: `{ \"id\": \"kg\", \"actionId\": \"read-list\" }`\nCorrect: `{ \"id\": \"kg\", \"actionId\": \"kg.read-list\" }`\n\n---\n\n## 11. `loop_completion` criteria requires `onCriteriaFail: \"wait\"`  [LOOP_COMPLETION_NOT_WAIT]\n\nWithout `onCriteriaFail: \"wait\"`, the step skips instead of blocking until\nthe loop finishes. The `stepId` field is also required.\n\n---\n\n## 12. Arrays in JSON template strings \u2014 don't JSON.stringify\n\nThe serializer detects when a template variable is the sole content of a JSON\nfield and inlines the raw value. Pass `{ \"items\": \"{{steps.x.items}}\" }`\ndirectly \u2014 no stringify needed.\n\n---\n\n## 13. `kg.upsert-rows` needs `userKey` for dedup; `kg.add-rows` always inserts\n\n`kg.upsert-rows` with `userKey`: same key = same row, cross-run dedup O(1).\n`kg.add-rows`: always inserts a new row, duplicates accumulate.\nUse `mergeStrategy: \"merge\"` to preserve downstream-added fields.\n";
+export declare function makeWorkspaceReadme(meta: WorkspaceMeta): string;
+export declare function createWorkspaceFolder(folderPath: string, meta: WorkspaceMeta, opts?: {
+    appsList?: unknown;
+    modelsList?: unknown;
+}): void;
+export declare function refreshWorkspaceFolder(wsDir: string, opts: {
+    appsList?: unknown;
+    modelsList?: unknown;
+}): void;