@agentled/cli 0.1.5 → 0.4.3

package/dist/utils/preflight.js

@@ -0,0 +1,185 @@
+/**
+ * Client-side preflight checks for a pipeline JSON before it's sent to the
+ * server. Catches the "Nick-class" failure mode (invalid step types, missing
+ * required fields, unreachable steps, silently-stripped root fields) without
+ * spending a create + validate + delete round trip.
+ *
+ * The valid step types list is kept in sync with the orchestrator's runtime
+ * VALID_STEP_TYPES via the drift test in
+ * agentled-mcp-server/__tests__/skill-step-types.test.ts.
+ */
+/**
+ * Canonical valid step types. Must stay in sync with:
+ *   shared/services/chat/orchestrator/validators/index.ts (runtime)
+ *   packages/cli/skills/agentled/SKILL.md (agent-facing doc)
+ *   agentled-mcp-server/__tests__/skill-step-types.test.ts (drift guard)
+ */
+const VALID_STEP_TYPES = new Set([
+    'trigger', 'appAction', 'aiAction', 'aiActionWithTools', 'toolAction',
+    'code', 'knowledgeSync', 'return', 'milestone', 'share', 'wait',
+    'branch', 'parallel', 'loop', 'end_if', 'agentOrchestrator',
+    'manualAction', 'systemAction',
+]);
+/**
+ * Root-level fields that the API silently strips. Detecting these at the
+ * step root is the single highest-leverage check — it's the exact class of
+ * bug that produced Nick's 201-created-but-broken workflows.
+ */
+const STRIPPED_ROOT_FIELDS = {
+    prompt: 'Move to `pipelineStepPrompt.template`',
+    responseStructure: 'Move to `pipelineStepPrompt.responseStructure`',
+    appId: 'Move into `app: { id, actionId, source: "native" }`',
+    actionId: 'Move into `app: { id, actionId, source: "native" }`',
+    listKey: 'Use `knowledgeSync.listKey` (for knowledgeSync steps) or put inside `stepInputData`',
+    channel: 'Put inside `stepInputData.channel`',
+    webhookUrl: 'Put inside `stepInputData.webhookUrl`',
+    condition: 'Use `entryConditions.criteria[]` with { variable, operator, value }',
+    triggerType: 'Use `pipelineStepStartConditions.trigger.type` instead — `triggerType` at step root is silently stripped',
+};
+/** Steps where we expect an outgoing `next` link (everything except terminals). */
+const TERMINAL_TYPES = new Set(['milestone', 'return', 'end_if']);
+export function preflightPipeline(pipeline) {
+    const errors = [];
+    const warnings = [];
+    if (!pipeline || typeof pipeline !== 'object') {
+        errors.push({ severity: 'error', code: 'not-object', message: 'Pipeline is not a JSON object' });
+        return { valid: false, errors, warnings, stepCount: 0 };
+    }
+    if (typeof pipeline.name !== 'string' || pipeline.name.trim() === '') {
+        errors.push({ severity: 'error', code: 'missing-name', message: 'Top-level `name` is required' });
+    }
+    const steps = pipeline.steps;
+    if (!Array.isArray(steps) || steps.length === 0) {
+        errors.push({ severity: 'error', code: 'missing-steps', message: 'Top-level `steps` must be a non-empty array' });
+        return { valid: errors.length === 0, errors, warnings, stepCount: 0 };
+    }
+    const stepIds = new Set();
+    for (const step of steps) {
+        if (!step || typeof step !== 'object') {
+            errors.push({ severity: 'error', code: 'bad-step', message: 'Step is not an object' });
+            continue;
+        }
+        if (typeof step.id !== 'string' || step.id.trim() === '') {
+            errors.push({ severity: 'error', code: 'missing-id', message: 'Step is missing `id`' });
+        }
+        else if (stepIds.has(step.id)) {
+            errors.push({ severity: 'error', stepId: step.id, code: 'duplicate-id', message: `Duplicate step id: ${step.id}` });
+        }
+        else {
+            stepIds.add(step.id);
+        }
+        // type check — the Nick-class bug
+        if (typeof step.type !== 'string') {
+            errors.push({ severity: 'error', stepId: step.id, code: 'missing-type', message: 'Step is missing `type`' });
+        }
+        else if (!VALID_STEP_TYPES.has(step.type)) {
+            errors.push({
+                severity: 'error',
+                stepId: step.id,
+                code: 'invalid-type',
+                message: `Unknown step type "${step.type}". Valid: ${[...VALID_STEP_TYPES].sort().join(', ')}`,
+                suggestedFix: suggestTypeFix(step.type),
+            });
+        }
+        // silently-stripped root fields
+        for (const [field, fix] of Object.entries(STRIPPED_ROOT_FIELDS)) {
+            if (Object.prototype.hasOwnProperty.call(step, field)) {
+                warnings.push({
+                    severity: 'warning',
+                    stepId: step.id,
+                    code: 'stripped-root-field',
+                    message: `Field \`${field}\` at step root will be silently stripped on save`,
+                    suggestedFix: fix,
+                });
+            }
+        }
+        // aiAction + aiActionWithTools must have pipelineStepPrompt.template
+        if ((step.type === 'aiAction' || step.type === 'aiActionWithTools')) {
+            const tpl = step.pipelineStepPrompt?.template;
+            if (typeof tpl !== 'string' || tpl.trim() === '') {
+                errors.push({
+                    severity: 'error',
+                    stepId: step.id,
+                    code: 'missing-prompt-template',
+                    message: `${step.type} step requires \`pipelineStepPrompt.template\``,
+                });
+            }
+        }
+        // appAction must have app.id + app.actionId
+        if (step.type === 'appAction') {
+            if (!step.app || typeof step.app !== 'object') {
+                errors.push({
+                    severity: 'error', stepId: step.id, code: 'missing-app',
+                    message: 'appAction step requires `app: { id, actionId, source }`',
+                });
+            }
+            else {
+                if (typeof step.app.id !== 'string') {
+                    errors.push({ severity: 'error', stepId: step.id, code: 'missing-app-id', message: '`app.id` is required on appAction steps' });
+                }
+                if (typeof step.app.actionId !== 'string') {
+                    errors.push({ severity: 'error', stepId: step.id, code: 'missing-action-id', message: '`app.actionId` is required on appAction steps' });
+                }
+            }
+        }
+        // trigger steps need pipelineStepStartConditions.trigger.type
+        // (the runtime reads this; `triggerType` at step root is not in the
+        // step schema and is silently stripped on save)
+        if (step.type === 'trigger') {
+            const tType = step.pipelineStepStartConditions?.trigger?.type;
+            if (typeof tType !== 'string') {
+                errors.push({
+                    severity: 'error', stepId: step.id, code: 'missing-trigger-type',
+                    message: 'trigger step requires `pipelineStepStartConditions.trigger.type` (manual | schedule | webhook | event | delay | app_event)',
+                    suggestedFix: 'Set `pipelineStepStartConditions: { trigger: { type: "manual" } }` (or replace "manual" with schedule/webhook/event/delay/app_event).',
+                });
+            }
+        }
+        // non-terminal steps should have a next.stepId
+        if (!TERMINAL_TYPES.has(step.type)) {
+            const nextId = step.next?.stepId;
+            if (typeof step.type === 'string' && VALID_STEP_TYPES.has(step.type) && !nextId) {
+                warnings.push({
+                    severity: 'warning', stepId: step.id, code: 'missing-next',
+                    message: `Non-terminal step "${step.id}" has no \`next.stepId\` — will halt after this step`,
+                });
+            }
+        }
+    }
+    // next.stepId must point to an existing step
+    for (const step of steps) {
+        if (!step?.next?.stepId)
+            continue;
+        if (!stepIds.has(step.next.stepId)) {
+            errors.push({
+                severity: 'error', stepId: step.id, code: 'dangling-next',
+                message: `Step "${step.id}" next.stepId "${step.next.stepId}" does not reference any step`,
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings, stepCount: steps.length };
+}
+/**
+ * Heuristic fix suggestions for the exact invented types Nick-class agents produce.
+ */
+function suggestTypeFix(invalid) {
+    const map = {
+        ai: 'Use `type: "aiAction"` (or `aiActionWithTools` if the LLM needs runtime tools).',
+        integration: 'Use `type: "appAction"` with `app: { id, actionId, source: "native" }`.',
+        conditional_integration: 'Use `type: "appAction"` with `entryConditions.criteria`.',
+        knowledge_graph_query: 'Use `type: "appAction"` with `app.id: "kg"`, actionId one of `read-list`/`read-text`/`get-rows-by-ids`/`traverse-edges`.',
+        knowledge_graph_upsert: 'Use `type: "appAction"` with `app.id: "kg"`, actionId `add-rows`/`update-rows`/`upsert-text`.',
+        knowledge_graph: 'Use `type: "appAction"` with `app.id: "kg"` (see `agentled apps actions kg`).',
+        slack: 'Use `type: "appAction"` with `app.id: "slack"` (or a `webhook` appAction if using a Slack incoming webhook URL).',
+        gmail: 'Use `type: "appAction"` with `app.id: "gmail"`.',
+        webhook: '`webhook` is a `triggerType` on a `trigger` step, not a step type. For outbound webhooks use `app.id: "webhook"` with actionId `trigger`.',
+        schedule: '`schedule` is a `triggerType` on a `trigger` step, not a step type.',
+    };
+    return map[invalid];
+}
+export function formatPreflightIssue(issue) {
+    const scope = issue.stepId ? `[${issue.stepId}] ` : '';
+    const fix = issue.suggestedFix ? `\n      fix: ${issue.suggestedFix}` : '';
+    return `    - ${scope}${issue.message} (${issue.code})${fix}`;
+}
+//# sourceMappingURL=preflight.js.map

package/dist/utils/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../src/utils/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiBH;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC7B,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,mBAAmB,EAAE,YAAY;IACrE,MAAM,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM;IAC/D,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB;IAC3D,cAAc,EAAE,cAAc;CACjC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,oBAAoB,GAA2B;IACjD,MAAM,EAAE,uCAAuC;IAC/C,iBAAiB,EAAE,gDAAgD;IACnE,KAAK,EAAE,qDAAqD;IAC5D,QAAQ,EAAE,qDAAqD;IAC/D,OAAO,EAAE,qFAAqF;IAC9F,OAAO,EAAE,oCAAoC;IAC7C,UAAU,EAAE,uCAAuC;IACnD,SAAS,EAAE,qEAAqE;IAChF,WAAW,EAAE,0GAA0G;CAC1H,CAAC;AAEF,mFAAmF;AACnF,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAElE,MAAM,UAAU,iBAAiB,CAAC,QAAa;IAC3C,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAqB,EAAE,CAAC;IAEtC,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC,CAAC;QACjG,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAC5D,CAAC;IAED,IAAI,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACnE,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC,CAAC;IACtG,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;IAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,6CAA6C,EAAE,CAAC,CAAC;QAClH,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAC1E,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC;YACvF,SAAS;QACb,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACvD,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC,CAAC;QAC5F,CAAC;aAAM,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,sBAAsB,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACxH,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;QAED,kCAAkC;QAClC,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC,CAAC;QACjH,CAAC;aAAM,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,CAAC,IAAI,CAAC;gBACR,QAAQ,EAAE,OAAO;gBACjB,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,IAAI,EAAE,cAAc;gBACpB,OAAO,EAAE,sBAAsB,IAAI,CAAC,IAAI,aAAa,CAAC,GAAG,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBAC9F,YAAY,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;aAC1C,CAAC,CAAC;QACP,CAAC;QAED,gCAAgC;QAChC,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,CAAC;YAC9D,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;gBACpD,QAAQ,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,SAAS;oBACnB,MAAM,EAAE,IAAI,CAAC,EAAE;oBACf,IAAI,EAAE,qBAAqB;oBAC3B,OAAO,EAAE,WAAW,KAAK,mDAAmD;oBAC5E,YAAY,EAAE,GAAG;iBACpB,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAED,qEAAqE;QACrE,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,IAAI,KAAK,mBAAmB,CAAC,EAAE,CAAC;YAClE,MAAM,GAAG,GAAG,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC;YAC9C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;gBAC/C,MAAM,CAAC,IAAI,CAAC;oBACR,QAAQ,EAAE,OAAO;oBACjB,MAAM,EAAE,IAAI,CAAC,EAAE;oBACf,IAAI,EAAE,yBAAyB;oBAC/B,OAAO,EAAE,GAAG,IAAI,CAAC,IAAI,gDAAgD;iBACxE,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAED,4CAA4C;QAC5C,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5C,MAAM,CAAC,IAAI,CAAC;oBACR,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,aAAa;oBACvD,OAAO,EAAE,yDAAyD;iBACrE,CAAC,CAAC;YACP,CAAC;iBAAM,CAAC;gBACJ,IAAI,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;oBAClC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,yCAAyC,EAAE,CAAC,CAAC;gBACpI,CAAC;gBACD,IAAI,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBACxC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,+CAA+C,EAAE,CAAC,CAAC;gBAC7I,CAAC;YACL,CAAC;QACL,CAAC;QAED,8DAA8D;QAC9D,oEAAoE;QACpE,gDAAgD;QAChD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,2BAA2B,EAAE,OAAO,EAAE,IAAI,CAAC;YAC9D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC5B,MAAM,CAAC,IAAI,CAAC;oBACR,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,sBAAsB;oBAChE,OAAO,EAAE,4HAA4H;oBACrI,YAAY,EAAE,uIAAuI;iBACxJ,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAED,+CAA+C;QAC/C,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;YACjC,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC9E,QAAQ,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,cAAc;oBAC1D,OAAO,EAAE,sBAAsB,IAAI,CAAC,EAAE,sDAAsD;iBAC/F,CAAC,CAAC;YACP,CAAC;QACL,CAAC;IACL,CAAC;IAED,6CAA6C;IAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM;YAAE,SAAS;QAClC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC;gBACR,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,eAAe;gBACzD,OAAO,EAAE,SAAS,IAAI,CAAC,EAAE,kBAAkB,IAAI,CAAC,IAAI,CAAC,MAAM,+BAA+B;aAC7F,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;AACrF,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,OAAe;IACnC,MAAM,GAAG,GAA2B;QAChC,EAAE,EAAE,iFAAiF;QACrF,WAAW,EAAE,yEAAyE;QACtF,uBAAuB,EAAE,0DAA0D;QACnF,qBAAqB,EAAE,0HAA0H;QACjJ,sBAAsB,EAAE,+FAA+F;QACvH,eAAe,EAAE,+EAA+E;QAChG,KAAK,EAAE,kHAAkH;QACzH,KAAK,EAAE,iDAAiD;QACxD,OAAO,EAAE,2IAA2I;QACpJ,QAAQ,EAAE,qEAAqE;KAClF,CAAC;IACF,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAqB;IACtD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,MAAM,GAAG,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,gBAAgB,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,OAAO,SAAS,KAAK,GAAG,KAAK,CAAC,OAAO,KAAK,KAAK,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC;AAClE,CAAC"}

package/dist/utils/skills.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Skills installer — copies the bundled Agentled Claude Code skills into the
+ * user's `~/.claude/skills/` (global) or `./.claude/skills/` (project) dir.
+ *
+ * Why: When an agent drives the CLI with a fresh Claude Code session, it does
+ * not have the Agentled skill loaded unless the skill is present on disk in a
+ * Claude-discoverable location. Without the skill, the LLM invents invalid
+ * step types (`type: "ai"`, `knowledge_graph_query`, …) — the exact class of
+ * silent CLI failure that MCP-025 is closing.
+ *
+ * The installer is version-aware:
+ *   - Reads a `version:` frontmatter field from each `SKILL.md`
+ *   - Leaves newer or hand-edited skills alone (unless --force)
+ *   - Reports status so we can print a one-line summary after `auth login`
+ */
+export type SkillInstallOutcome = 'installed' | 'updated' | 'up-to-date' | 'newer-local' | 'hand-edited' | 'forced';
+export interface SkillInstallResult {
+    skill: string;
+    outcome: SkillInstallOutcome;
+    bundledVersion: string;
+    installedVersion: string | null;
+    targetPath: string;
+}
+export interface InstallSkillsOptions {
+    /** true = install to `~/.claude/skills/` (global); false = `./.claude/skills/` (project) */
+    global?: boolean;
+    /** overwrite regardless of version comparison or local edits */
+    force?: boolean;
+}
+/**
+ * Locate the `skills/` directory that ships with @agentled/cli.
+ *
+ * When running from source (`node dist/index.js`) the layout is:
+ *   packages/cli/dist/utils/skills.js  → packages/cli/skills/…
+ * When installed globally via npm, the package layout is the same relative
+ * structure (`dist/utils/skills.js` → `skills/`).
+ */
+export declare function resolveBundledSkillsDir(): string;
+export declare function getSkillsTargetDir(global: boolean): string;
+export declare function installSkills(options?: InstallSkillsOptions): SkillInstallResult[];
+export declare function describeSkillsInstall(results: SkillInstallResult[], targetDir: string): string;
+/**
+ * Produce a short one-line hint for the `auth login` summary, e.g.
+ *   "Skill installed: agentled v0.2.0 → ~/.claude/skills/"
+ *   "Skill already installed (v0.1.0), latest is v0.2.0 — run `agentled skills update` to refresh."
+ *
+ * Returns null if there is nothing worth showing.
+ */
+export declare function summarizeForLoginBanner(results: SkillInstallResult[], targetDir: string): string | null;

package/dist/utils/skills.js

@@ -0,0 +1,214 @@
+/**
+ * Skills installer — copies the bundled Agentled Claude Code skills into the
+ * user's `~/.claude/skills/` (global) or `./.claude/skills/` (project) dir.
+ *
+ * Why: When an agent drives the CLI with a fresh Claude Code session, it does
+ * not have the Agentled skill loaded unless the skill is present on disk in a
+ * Claude-discoverable location. Without the skill, the LLM invents invalid
+ * step types (`type: "ai"`, `knowledge_graph_query`, …) — the exact class of
+ * silent CLI failure that MCP-025 is closing.
+ *
+ * The installer is version-aware:
+ *   - Reads a `version:` frontmatter field from each `SKILL.md`
+ *   - Leaves newer or hand-edited skills alone (unless --force)
+ *   - Reports status so we can print a one-line summary after `auth login`
+ */
+import { existsSync, readFileSync, mkdirSync, readdirSync, statSync, cpSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+/**
+ * Locate the `skills/` directory that ships with @agentled/cli.
+ *
+ * When running from source (`node dist/index.js`) the layout is:
+ *   packages/cli/dist/utils/skills.js  → packages/cli/skills/…
+ * When installed globally via npm, the package layout is the same relative
+ * structure (`dist/utils/skills.js` → `skills/`).
+ */
+export function resolveBundledSkillsDir() {
+    const here = fileURLToPath(import.meta.url);
+    // dist/utils/skills.js → package root is two levels up
+    const pkgRoot = resolve(dirname(here), '..', '..');
+    return join(pkgRoot, 'skills');
+}
+export function getSkillsTargetDir(global) {
+    return global
+        ? join(homedir(), '.claude', 'skills')
+        : join(process.cwd(), '.claude', 'skills');
+}
+/**
+ * Parse a `version:` field out of the YAML-style frontmatter at the top of a
+ * SKILL.md file. Returns null if no frontmatter or no version field is present.
+ */
+function parseSkillVersion(skillMdPath) {
+    try {
+        const content = readFileSync(skillMdPath, 'utf-8');
+        // Only inspect frontmatter (between the first two --- delimiters)
+        const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch)
+            return null;
+        const versionMatch = fmMatch[1].match(/^version:\s*(.+)$/m);
+        return versionMatch ? versionMatch[1].trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare two semver-ish version strings. Returns -1, 0, or 1.
+ * Handles missing prereleases by treating undefined segments as 0.
+ */
+function compareVersions(a, b) {
+    const parse = (v) => v.replace(/^v/, '').split('.').map(n => parseInt(n, 10) || 0);
+    const [a1, a2 = 0, a3 = 0] = parse(a);
+    const [b1, b2 = 0, b3 = 0] = parse(b);
+    if (a1 !== b1)
+        return a1 < b1 ? -1 : 1;
+    if (a2 !== b2)
+        return a2 < b2 ? -1 : 1;
+    if (a3 !== b3)
+        return a3 < b3 ? -1 : 1;
+    return 0;
+}
+/**
+ * Recursively hash-compare two directories by content. Returns true if the
+ * byte contents of every file match (directory structure + file bytes).
+ *
+ * Used to detect hand-edited installs: if the installed version matches the
+ * bundled version but the bytes differ, the user (or a prior agent session)
+ * has customised the skill and we should not overwrite without --force.
+ */
+function directoriesIdentical(a, b) {
+    try {
+        const aEntries = readdirSync(a).sort();
+        const bEntries = readdirSync(b).sort();
+        if (aEntries.length !== bEntries.length)
+            return false;
+        for (let i = 0; i < aEntries.length; i++) {
+            if (aEntries[i] !== bEntries[i])
+                return false;
+            const aChild = join(a, aEntries[i]);
+            const bChild = join(b, bEntries[i]);
+            const aStat = statSync(aChild);
+            const bStat = statSync(bChild);
+            if (aStat.isDirectory() !== bStat.isDirectory())
+                return false;
+            if (aStat.isDirectory()) {
+                if (!directoriesIdentical(aChild, bChild))
+                    return false;
+            }
+            else {
+                const aBuf = readFileSync(aChild);
+                const bBuf = readFileSync(bChild);
+                if (!aBuf.equals(bBuf))
+                    return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function installSkills(options = {}) {
+    const sourceDir = resolveBundledSkillsDir();
+    if (!existsSync(sourceDir)) {
+        throw new Error(`Bundled skills directory not found at ${sourceDir}`);
+    }
+    const targetBase = getSkillsTargetDir(options.global ?? false);
+    const results = [];
+    const skills = readdirSync(sourceDir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => d.name);
+    for (const skill of skills) {
+        const src = join(sourceDir, skill);
+        const dest = join(targetBase, skill);
+        const bundledVersion = parseSkillVersion(join(src, 'SKILL.md')) ?? '0.0.0';
+        const installedVersion = existsSync(dest) ? parseSkillVersion(join(dest, 'SKILL.md')) : null;
+        let outcome;
+        if (!existsSync(dest)) {
+            outcome = 'installed';
+        }
+        else if (options.force) {
+            outcome = 'forced';
+        }
+        else if (installedVersion && compareVersions(installedVersion, bundledVersion) > 0) {
+            outcome = 'newer-local';
+        }
+        else if (installedVersion && compareVersions(installedVersion, bundledVersion) === 0) {
+            outcome = directoriesIdentical(src, dest) ? 'up-to-date' : 'hand-edited';
+        }
+        else {
+            outcome = 'updated';
+        }
+        if (outcome === 'installed' || outcome === 'updated' || outcome === 'forced') {
+            mkdirSync(dest, { recursive: true });
+            cpSync(src, dest, { recursive: true, force: true });
+        }
+        results.push({
+            skill,
+            outcome,
+            bundledVersion,
+            installedVersion,
+            targetPath: dest,
+        });
+    }
+    return results;
+}
+export function describeSkillsInstall(results, targetDir) {
+    if (results.length === 0)
+        return 'No skills to install.';
+    const lines = [];
+    for (const r of results) {
+        switch (r.outcome) {
+            case 'installed':
+                lines.push(`  ✓ ${r.skill} v${r.bundledVersion} installed`);
+                break;
+            case 'updated':
+                lines.push(`  ✓ ${r.skill} v${r.installedVersion} → v${r.bundledVersion} updated`);
+                break;
+            case 'forced':
+                lines.push(`  ✓ ${r.skill} v${r.bundledVersion} installed (forced)`);
+                break;
+            case 'up-to-date':
+                lines.push(`  • ${r.skill} v${r.bundledVersion} already installed`);
+                break;
+            case 'newer-local':
+                lines.push(`  • ${r.skill} local v${r.installedVersion} is newer than bundled v${r.bundledVersion} — left as-is`);
+                break;
+            case 'hand-edited':
+                lines.push(`  • ${r.skill} v${r.bundledVersion} already installed with local edits — left as-is (run with --force to overwrite)`);
+                break;
+        }
+    }
+    lines.push(`  Skills directory: ${targetDir}`);
+    return lines.join('\n');
+}
+/**
+ * Produce a short one-line hint for the `auth login` summary, e.g.
+ *   "Skill installed: agentled v0.2.0 → ~/.claude/skills/"
+ *   "Skill already installed (v0.1.0), latest is v0.2.0 — run `agentled skills update` to refresh."
+ *
+ * Returns null if there is nothing worth showing.
+ */
+export function summarizeForLoginBanner(results, targetDir) {
+    if (results.length === 0)
+        return null;
+    const fresh = results.filter(r => r.outcome === 'installed');
+    const stale = results.filter(r => r.outcome === 'newer-local' || r.outcome === 'hand-edited');
+    const updatable = results.filter(r => r.outcome === 'up-to-date' && r.installedVersion && r.bundledVersion && compareVersions(r.installedVersion, r.bundledVersion) < 0);
+    if (fresh.length > 0) {
+        const names = fresh.map(r => `${r.skill} v${r.bundledVersion}`).join(', ');
+        return `Installed Claude Code skill: ${names} → ${targetDir}`;
+    }
+    if (stale.length > 0) {
+        const r = stale[0];
+        return `Skill "${r.skill}" already installed (v${r.installedVersion ?? '?'}), bundled is v${r.bundledVersion} — run \`agentled skills update\` to refresh.`;
+    }
+    if (updatable.length > 0) {
+        const r = updatable[0];
+        return `Skill "${r.skill}" v${r.installedVersion} installed, v${r.bundledVersion} available — run \`agentled skills update\` to refresh.`;
+    }
+    return null;
+}
+//# sourceMappingURL=skills.js.map

package/dist/utils/skills.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentled/cli",
-  "version": "0.1.5",
+  "version": "0.4.3",
   "description": "CLI for Agentled — manage workflows, apps, and knowledge from the command line. Zero context-window cost for AI agents.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,6 +28,9 @@
   },
   "files": [
     "dist",
+    "skills",
+    "patterns",
+    "scaffolds",
     "README.md",
     "llms.txt",
     "llms-full.txt"

package/patterns/v1/00-why-agentic-ops.md

@@ -0,0 +1,107 @@
+# 00 — Why agentic-ops
+
+> The ops discipline that makes AI agents production-ready.
+
+---
+
+## The pitch deck demo works. Production doesn't.
+
+You've seen it: an AI agent that looks brilliant in a demo — processes a lead, writes a personalized email, updates the CRM. Then you run it on 500 leads a week and the wheels fall off. Duplicates. Missing records. Costs 3× what you expected. No way to know what actually went through.
+
+This isn't an AI problem. It's an **architecture problem**.
+
+The fix has a name in every other engineering discipline: operations. CI/CD, observability, idempotency, retries, caching, audit trails — these didn't exist on day one of web development either. Developers invented them because raw execution didn't scale. Agentic workflows are at the same inflection point.
+
+This is **agentic-ops**: the patterns that make the gap between "demo" and "production" crossable.
+
+---
+
+## 1. Unit economics collapse without dedup discipline
+
+This is the argument that lands before developers hit the wall themselves.
+
+You're processing 500 inbound leads per week. Your workflow enriches each one (5 credits). No dedup gate — the workflow polls every hour, no label marking what's been processed.
+
+- Average lead appears in 3 polls before it's handled: **1,500 enrichments instead of 500**
+- At 5 credits each: **5,000 wasted credits per week**
+- At scale, you're paying for work you already did
+
+This isn't hypothetical. It's the default outcome of any polling workflow without a dedup gate. See [02-dedup-gates](02-dedup-gates.md) for the fix.
+
+---
+
+## 2. Non-determinism at scale
+
+A one-off prompt works once. Run the same prompt 1,000 times against your pipeline and you get 1,000 slightly different outputs — different field names, different score ranges, different JSON shapes. No two downstream steps can reliably consume the previous one.
+
+Structured workflows define a **response contract**: the output schema is declared upfront, validated at runtime, and consistent across every execution. The AI fills in the values; the workflow enforces the shape.
+
+Without this contract, you're parsing surprises, not outputs.
+
+---
+
+## 3. No audit trail, no trust
+
+"The AI processed our deal flow last week" — can you tell me exactly which companies it looked at, what data it used, what score it assigned, and why three were dropped? If not, you can't trust it in any context that matters: regulated industries, board reporting, customer-facing processes.
+
+Structured workflows produce **per-step execution records**: inputs, outputs, duration, status, timestamp. You can replay any run. You can compare two runs on the same input. You can show an auditor exactly what happened.
+
+Ad-hoc prompts produce a chat message and nothing else.
+
+---
+
+## 4. Retries without idempotency destroy partial state
+
+An AI agent that crashes halfway through is worse than one that never started. You have partial writes: some records enriched, some not; some CRM entries created, some missing. You don't know where it stopped.
+
+Structured workflows solve this at two levels:
+- **Step-level retry**: resume from the exact failed step with the same inputs — no re-running the work that succeeded
+- **Idempotency gates**: dedup keys, label markers, and processed flags ensure a retried step produces the same outcome as the original, not a duplicate
+
+See [07-error-handling](07-error-handling.md) and [02-dedup-gates](02-dedup-gates.md).
+
+---
+
+## 5. Caching requires stable step boundaries
+
+Enriching the same LinkedIn company URL twice in the same workflow shouldn't hit the API twice. But caching requires a **stable cache key**: a defined input that uniquely identifies the computation.
+
+Ad-hoc prompts have no stable key — the prompt is the key, and it changes with every rephrasing. Structured steps have explicit inputs, which means the platform can cache at the step level, deduplicate in-flight requests, and short-circuit repeated work.
+
+No step boundary = no cache key = no caching.
+
+---
+
+## 6. Production requirements don't exist in raw prompting
+
+Running AI agents at production scale without structured execution is like running a web server without a framework. You'll reinvent every wheel:
+
+- **Observability**: knowing which step is running, how long it's taking, when it silently failed
+- **Rate limiting**: preventing a burst of executions from hammering a downstream API
+- **Concurrency control**: ensuring two parallel runs don't write conflicting records to the same CRM entry
+- **Backpressure**: slowing intake when the processing queue backs up
+
+These are solved problems in structured workflow systems. They don't exist as primitives in a prompt-and-hope architecture.
+
+---
+
+## 7. Human-in-the-loop gates need a first-class abstraction
+
+"Have a human review the AI's output before it sends an email" sounds simple. In practice it requires: a UI to surface the output for review, a way to approve or reject, a mechanism to block the next step until the human acts, and a timeout path if they don't.
+
+This is a first-class primitive in workflow systems — an approval gate with configurable behavior. In raw prompting, you build it from scratch every time.
+
+Any workflow that touches customers, sends communications, or writes to a system of record should have a human-in-the-loop gate. See [09-human-in-the-loop](../v2/09-human-in-the-loop.md) (v2).
+
+---
+
+## The pattern
+
+Every production failure in agentic workflows traces back to one of these seven gaps. The patterns in this repo address each one directly — not as theoretical advice, but as the specific implementations that fix them.
+
+Start with the one that matches your current pain:
+- Burning credits → [03-credit-efficiency](03-credit-efficiency.md)
+- Processing duplicates → [02-dedup-gates](02-dedup-gates.md)
+- Steps silently skipping → [06-conditional-routing](06-conditional-routing.md)
+- Crashes with partial state → [07-error-handling](07-error-handling.md)
+- Wrong trigger choice → [01-trigger-design](01-trigger-design.md)