@kairos-sdk/core 0.5.1 → 0.6.0

package/dist/index.cjs

@@ -43,6 +43,7 @@ __export(index_exports, {
   N8nValidator: () => N8nValidator,
   NodeRegistry: () => NodeRegistry,
   NullLibrary: () => NullLibrary,
+  PackBuilder: () => PackBuilder,
   ProviderError: () => ProviderError,
   ResponseParseError: () => ResponseParseError,
   TelemetryCollector: () => TelemetryCollector,
@@ -51,10 +52,13 @@ __export(index_exports, {
   ValidationError: () => ValidationError,
   buildSearchCorpus: () => buildSearchCorpus,
   clusterWorkflows: () => clusterWorkflows,
+  derivePackStatus: () => derivePackStatus,
+  generateHandoff: () => generateHandoff,
   hybridScore: () => hybridScore,
   nullLogger: () => nullLogger,
   rerank: () => rerank,
-  tokenize: () => tokenize
+  tokenize: () => tokenize,
+  validatePack: () => validatePack
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -735,6 +739,7 @@ var N8nValidator = class {
     this.checkRule32(workflow, issues);
     this.checkRule33(workflow, issues);
     this.checkRule34(workflow, issues);
+    this.checkRule35(workflow, issues);
     if (Array.isArray(workflow.nodes)) {
       const nodeById = new Map(workflow.nodes.map((n) => [n.id, n.type]));
       for (const issue of issues) {
@@ -1307,6 +1312,43 @@ var N8nValidator = class {
       }
     }
   }
+  // Rule 35 (WARN): email-sending node with no duplicate-prevention signal
+  checkRule35(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    const sendNodes = w.nodes.filter((node) => {
+      if (node.type === "n8n-nodes-base.gmail") {
+        const op = node.parameters?.["operation"];
+        return !op || op === "send" || op === "sendEmail" || op === "reply";
+      }
+      return node.type === "n8n-nodes-base.emailSend" || node.type === "n8n-nodes-base.sendEmail";
+    });
+    if (sendNodes.length === 0) return;
+    const workflowText = JSON.stringify(w).toLowerCase();
+    const IDEMPOTENCY_SIGNALS = [
+      "sent_at",
+      "last_sent",
+      "last_reminder",
+      "processed_at",
+      "already_sent",
+      "email_sent",
+      "notified_at",
+      "reminder_sent",
+      "contacted_at",
+      "dedupe",
+      "idempotent"
+    ];
+    const hasIdempotencySignal = IDEMPOTENCY_SIGNALS.some((s) => workflowText.includes(s));
+    if (!hasIdempotencySignal) {
+      for (const node of sendNodes) {
+        this.warn(
+          issues,
+          35,
+          `Node "${node.name}" sends email but no duplicate-prevention signal detected \u2014 add a sent_at timestamp field, a prior-send IF check, or a deduplication key to avoid repeat sends`,
+          node.id
+        );
+      }
+    }
+  }
   // Rule 34 (WARN): webhook path contains spaces, starts with slash, or looks like a full URL
   checkRule34(w, issues) {
     if (!Array.isArray(w.nodes)) return;
@@ -1569,7 +1611,7 @@ function scoreToMode(score) {
 }
 
 // src/validation/rule-metadata.ts
-var VALIDATOR_RULE_IDS = Array.from({ length: 34 }, (_, i) => i + 1);
+var VALIDATOR_RULE_IDS = Array.from({ length: 35 }, (_, i) => i + 1);
 var RULE_PIPELINE_STAGES = {
   1: "node_generation",
   2: "node_generation",
@@ -1604,7 +1646,8 @@ var RULE_PIPELINE_STAGES = {
   31: "node_generation",
   32: "node_generation",
   33: "node_generation",
-  34: "node_generation"
+  34: "node_generation",
+  35: "node_generation"
 };
 var RULE_EXAMPLES = {
   17: {
@@ -1654,6 +1697,10 @@ var RULE_EXAMPLES = {
   34: {
     bad: '"path": "/my webhook"',
     good: '"path": "my-webhook"'
+  },
+  35: {
+    bad: '"type": "n8n-nodes-base.gmail", "parameters": { "operation": "send" }  // no sent_at tracking',
+    good: 'Add a Set node after send that writes "sent_at": "={{ $now }}" back to the sheet, or an IF node that checks sent_at before sending'
   }
 };
 var RULE_MITIGATIONS = {
@@ -1690,7 +1737,8 @@ var RULE_MITIGATIONS = {
   31: "Add at least one condition to the if node \u2014 conditions.conditions array must be non-empty",
   32: "Add field assignments to the set node \u2014 assignments.assignments array must be non-empty for typeVersion 3.x",
   33: "Add at least one schedule rule to scheduleTrigger \u2014 rule.interval array must have at least one entry",
-  34: 'Webhook path must be a relative path without spaces, leading slashes, or protocol prefixes (e.g. "my-hook")'
+  34: 'Webhook path must be a relative path without spaces, leading slashes, or protocol prefixes (e.g. "my-hook")',
+  35: "Add duplicate-prevention to email-sending workflows: a sent_at timestamp field updated after each send, or an IF node that checks prior-send status before sending"
 };
 
 // src/generation/prompt-builder.ts
@@ -3925,6 +3973,334 @@ var FileLibrary = class {
   }
 };
 
+// src/pack/pack-builder.ts
+var import_sdk2 = __toESM(require("@anthropic-ai/sdk"), 1);
+function derivePackStatus(pack) {
+  const hasBlocking = pack.assumptions.some((a) => a.type === "blocking");
+  const hasFailures = pack.workflows.some((w) => w.error);
+  const allDeployed = pack.workflows.length > 0 && pack.workflows.every((w) => w.deployed);
+  const hasNeedsConfirmation = pack.assumptions.some((a) => a.type === "needs_confirmation");
+  if (pack.status === "active" && !hasBlocking && !hasFailures && allDeployed) return "active";
+  if (pack.workflows.length === 0 || !allDeployed && !hasFailures) return "draft";
+  if (hasBlocking) return "blocked";
+  if (hasFailures) return "needs_attention";
+  if (hasNeedsConfirmation) return "ready_for_test";
+  return "ready_for_activation";
+}
+var PLAN_PROMPT = `You are planning an n8n workflow automation pack for a business.
+
+Business context: {CONTEXT}
+
+Generate a list of 4-8 n8n workflows that would meaningfully automate this business's operations. Focus on workflows that save time on repetitive tasks, improve customer communication, prevent things falling through the cracks, and are realistic to implement with n8n nodes.
+
+For each workflow, write a detailed build description (2-4 sentences) suitable for passing directly to an n8n workflow generator. Be specific: name the trigger type, data sources (Google Sheets columns if applicable), actions, and outputs.
+
+For assumptions, classify each one:
+- "safe": a clearly reasonable default the business likely expects (e.g. "Schedule runs Monday 9 AM")
+- "needs_confirmation": should be confirmed before going live but won't break things immediately (e.g. "Assumed professional email tone \u2014 confirm brand voice")
+- "blocking": MUST be resolved before activation or the workflow will fail, send duplicates, or surprise customers (e.g. "Google Sheet ID not provided", "emails auto-send without approval gate \u2014 add confirmation step")
+
+Treat any open question that would block safe deployment as a blocking assumption.
+
+Return ONLY valid JSON with no markdown or extra text:
+{
+  "workflows": [
+    {
+      "name": "Short descriptive name",
+      "description": "Detailed generator-ready description specifying trigger, data sources, actions, outputs",
+      "purpose": "One sentence explaining the business value"
+    }
+  ],
+  "assumptions": [
+    { "type": "safe" | "needs_confirmation" | "blocking", "text": "Description of the assumption" }
+  ],
+  "sheetsColumns": [
+    { "sheet": "Sheet name", "columns": ["col1", "col2"] }
+  ],
+  "testChecklist": [
+    { "workflow": "Workflow name", "steps": ["How to manually test this workflow"] }
+  ]
+}`;
+function normalizeAssumptions(raw) {
+  const validTypes = /* @__PURE__ */ new Set(["safe", "needs_confirmation", "blocking"]);
+  return raw.map((a) => {
+    if (typeof a === "string") {
+      return { type: "needs_confirmation", text: a };
+    }
+    if (typeof a === "object" && a !== null) {
+      const obj = a;
+      const type = typeof obj["type"] === "string" && validTypes.has(obj["type"]) ? obj["type"] : "needs_confirmation";
+      const text = typeof obj["text"] === "string" ? obj["text"] : JSON.stringify(obj);
+      return { type, text };
+    }
+    return { type: "needs_confirmation", text: String(a) };
+  });
+}
+var PackBuilder = class {
+  client;
+  kairos;
+  model;
+  constructor(options) {
+    this.client = new import_sdk2.default({ apiKey: options.anthropicApiKey });
+    this.kairos = options.kairos;
+    this.model = options.model ?? "claude-sonnet-4-6";
+  }
+  async plan(businessContext) {
+    const prompt = PLAN_PROMPT.replace("{CONTEXT}", businessContext);
+    const response = await this.client.messages.create({
+      model: this.model,
+      max_tokens: 4096,
+      messages: [{ role: "user", content: prompt }]
+    });
+    const text = response.content[0]?.type === "text" ? response.content[0].text.trim() : "";
+    const cleaned = text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
+    const parsed = JSON.parse(cleaned);
+    const rawAssumptions = Array.isArray(parsed["assumptions"]) ? parsed["assumptions"] : [];
+    const rawOpenQuestions = Array.isArray(parsed["openQuestions"]) ? parsed["openQuestions"] : [];
+    const assumptions = normalizeAssumptions([...rawAssumptions, ...rawOpenQuestions.map(
+      (q) => typeof q === "string" ? { type: "needs_confirmation", text: q } : q
+    )]);
+    return {
+      businessContext,
+      workflows: Array.isArray(parsed["workflows"]) ? parsed["workflows"] : [],
+      assumptions,
+      sheetsColumns: Array.isArray(parsed["sheetsColumns"]) ? parsed["sheetsColumns"] : [],
+      testChecklist: Array.isArray(parsed["testChecklist"]) ? parsed["testChecklist"] : []
+    };
+  }
+  async build(plan, options = {}) {
+    const hasBlockingAssumptions = plan.assumptions.some((a) => a.type === "blocking");
+    const effectiveActivate = hasBlockingAssumptions ? false : options.activate ?? false;
+    const results = [];
+    const credentialMap = /* @__PURE__ */ new Map();
+    for (let i = 0; i < plan.workflows.length; i++) {
+      const wf = plan.workflows[i];
+      options.onProgress?.(wf, i, plan.workflows.length);
+      try {
+        const result = await this.kairos.build(wf.description, {
+          name: wf.name,
+          dryRun: options.dryRun ?? false,
+          activate: effectiveActivate
+        });
+        for (const cred of result.credentialsNeeded) {
+          credentialMap.set(cred.service, { service: cred.service, credentialType: cred.credentialType });
+        }
+        results.push({
+          name: wf.name,
+          purpose: wf.purpose,
+          workflowId: result.workflowId,
+          deployed: !result.dryRun,
+          generationAttempts: result.generationAttempts,
+          credentialsNeeded: result.credentialsNeeded
+        });
+      } catch (err) {
+        results.push({
+          name: wf.name,
+          purpose: wf.purpose,
+          workflowId: null,
+          deployed: false,
+          generationAttempts: 0,
+          credentialsNeeded: [],
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+    const packName = plan.businessContext.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const partial = {
+      businessContext: plan.businessContext,
+      packName,
+      status: "draft",
+      workflows: results,
+      allCredentials: Array.from(credentialMap.values()),
+      sheetsColumns: plan.sheetsColumns,
+      assumptions: plan.assumptions,
+      testChecklist: plan.testChecklist,
+      builtAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    return { ...partial, status: derivePackStatus(partial) };
+  }
+};
+
+// src/pack/pack-exporter.ts
+var STATUS_LABELS = {
+  draft: "Draft",
+  blocked: "Blocked \u2014 resolve issues before activation",
+  ready_for_test: "Ready for Testing",
+  ready_for_activation: "Ready for Activation",
+  active: "Active",
+  needs_attention: "Needs Attention"
+};
+function generateHandoff(pack) {
+  const lines = [];
+  const line = () => lines.push("");
+  lines.push(`# ${pack.businessContext} \u2014 Workflow Pack`);
+  line();
+  lines.push(`**Status:** ${STATUS_LABELS[pack.status] ?? pack.status}`);
+  lines.push(`**Generated:** ${new Date(pack.builtAt).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" })}`);
+  lines.push(`**Workflows:** ${pack.workflows.length} (${pack.workflows.filter((w) => w.deployed).length} deployed)`);
+  line();
+  lines.push(`## Overview`);
+  line();
+  lines.push(
+    `This workflow pack automates operations for **${pack.businessContext}**. It was built with Kairos and requires credential setup before workflows can be activated in n8n.`
+  );
+  line();
+  const blocking = pack.assumptions.filter((a) => a.type === "blocking");
+  if (blocking.length > 0) {
+    lines.push(`## Blocking Issues`);
+    line();
+    lines.push(`> These must be resolved before any workflows are activated.`);
+    line();
+    for (const a of blocking) {
+      lines.push(`- [ ] ${a.text}`);
+    }
+    line();
+  }
+  lines.push(`## Workflows`);
+  line();
+  for (const wf of pack.workflows) {
+    const icon = wf.error ? "\u2717" : "\u2713";
+    lines.push(`### ${icon} ${wf.name}`);
+    line();
+    lines.push(`**Purpose:** ${wf.purpose}`);
+    if (wf.workflowId) lines.push(`**n8n ID:** \`${wf.workflowId}\``);
+    if (!wf.deployed && !wf.error) lines.push(`**Status:** Not deployed (dry run)`);
+    if (wf.error) lines.push(`**Error:** ${wf.error}`);
+    line();
+  }
+  if (pack.allCredentials.length > 0) {
+    lines.push(`## Required Credentials`);
+    line();
+    lines.push(`Connect these in n8n before activating workflows:`);
+    line();
+    for (const cred of pack.allCredentials) {
+      lines.push(`- [ ] **${cred.service}** (${cred.credentialType})`);
+    }
+    line();
+  }
+  if (pack.sheetsColumns.length > 0) {
+    lines.push(`## Required Google Sheets`);
+    line();
+    for (const sheet of pack.sheetsColumns) {
+      lines.push(`### ${sheet.sheet}`);
+      line();
+      lines.push(`Columns: ${sheet.columns.map((c) => `\`${c}\``).join(", ")}`);
+      line();
+    }
+  }
+  const needsConfirmation = pack.assumptions.filter((a) => a.type === "needs_confirmation");
+  if (needsConfirmation.length > 0) {
+    lines.push(`## Needs Confirmation`);
+    line();
+    lines.push(`Verify these with the client before going live:`);
+    line();
+    for (const a of needsConfirmation) {
+      lines.push(`- [ ] ${a.text}`);
+    }
+    line();
+  }
+  const safe = pack.assumptions.filter((a) => a.type === "safe");
+  if (safe.length > 0) {
+    lines.push(`## Safe Assumptions`);
+    line();
+    lines.push(`These defaults were used during generation \u2014 no action needed:`);
+    line();
+    for (const a of safe) {
+      lines.push(`- ${a.text}`);
+    }
+    line();
+  }
+  lines.push(`## Setup Checklist`);
+  line();
+  lines.push(`Complete before testing:`);
+  line();
+  for (const cred of pack.allCredentials) {
+    lines.push(`- [ ] Connect **${cred.service}** credential in n8n Settings \u2192 Credentials`);
+  }
+  for (const sheet of pack.sheetsColumns) {
+    lines.push(`- [ ] Create Google Sheet: "${sheet.sheet}" with columns: ${sheet.columns.join(", ")}`);
+  }
+  for (const a of blocking) {
+    lines.push(`- [ ] Resolve: ${a.text}`);
+  }
+  for (const a of needsConfirmation) {
+    lines.push(`- [ ] Confirm: ${a.text}`);
+  }
+  line();
+  if (pack.testChecklist.length > 0) {
+    lines.push(`## Testing Checklist`);
+    line();
+    for (const item of pack.testChecklist) {
+      lines.push(`### ${item.workflow}`);
+      line();
+      for (const step of item.steps) {
+        lines.push(`- [ ] ${step}`);
+      }
+      line();
+    }
+  }
+  const deployedWorkflows = pack.workflows.filter((w) => w.deployed && !w.error);
+  if (deployedWorkflows.length > 0) {
+    lines.push(`## Activation Checklist`);
+    line();
+    lines.push(`Activate in n8n after testing is complete:`);
+    line();
+    for (const wf of deployedWorkflows) {
+      const idSuffix = wf.workflowId ? ` (n8n ID: \`${wf.workflowId}\`)` : "";
+      lines.push(`- [ ] Activate: **${wf.name}**${idSuffix}`);
+    }
+    line();
+  }
+  lines.push(`## Maintenance Notes`);
+  line();
+  lines.push(`- Monitor n8n executions weekly \u2014 check the Executions tab for failures`);
+  lines.push(`- Re-run \`kairos build-pack\` to regenerate workflows if business needs change`);
+  lines.push(`- Update Google Sheets data as business information changes`);
+  lines.push(`- Rotate API credentials before expiration (n8n Settings \u2192 Credentials)`);
+  lines.push(`- Run \`kairos validate-pack <name>\` before activating after any changes`);
+  return lines.join("\n");
+}
+
+// src/pack/pack-validator.ts
+function validatePack(pack) {
+  const issues = [];
+  const names = pack.workflows.map((w) => w.name);
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    if (seen.has(name)) duplicates.add(name);
+    seen.add(name);
+  }
+  if (duplicates.size > 0) {
+    issues.push({
+      type: "duplicate_name",
+      severity: "error",
+      message: `Duplicate workflow names: ${[...duplicates].join(", ")} \u2014 n8n may overwrite existing workflows on deploy`,
+      workflows: [...duplicates]
+    });
+  }
+  const blocking = pack.assumptions.filter((a) => a.type === "blocking");
+  if (blocking.length > 0) {
+    const plural = blocking.length === 1 ? "assumption" : "assumptions";
+    issues.push({
+      type: "blocking_assumption",
+      severity: "error",
+      message: `${blocking.length} blocking ${plural} must be resolved before activation:
+  ${blocking.map((a) => `\u2022 ${a.text}`).join("\n  ")}`
+    });
+  }
+  const failed = pack.workflows.filter((w) => w.error);
+  for (const wf of failed) {
+    issues.push({
+      type: "unsafe_activation",
+      severity: "error",
+      message: `Workflow "${wf.name}" failed to deploy: ${wf.error ?? "unknown error"}`,
+      workflows: [wf.name]
+    });
+  }
+  return issues;
+}
+
 // src/templates/safety.ts
 var BLOCKED_NODE_TYPES = /* @__PURE__ */ new Set([
   "n8n-nodes-base.code",
@@ -4150,6 +4526,7 @@ var TemplateSyncer = class {
   N8nValidator,
   NodeRegistry,
   NullLibrary,
+  PackBuilder,
   ProviderError,
   ResponseParseError,
   TelemetryCollector,
@@ -4158,9 +4535,12 @@ var TemplateSyncer = class {
   ValidationError,
   buildSearchCorpus,
   clusterWorkflows,
+  derivePackStatus,
+  generateHandoff,
   hybridScore,
   nullLogger,
   rerank,
-  tokenize
+  tokenize,
+  validatePack
 });
 //# sourceMappingURL=index.cjs.map