@zibby/workflow-templates 0.1.0 → 0.2.1

package/browser-test-automation/graph.mjs

@@ -13,12 +13,17 @@ import {
   generateScriptNode,
 } from './nodes/index.mjs';
 import { BrowserTestResultHandler } from './result-handler.mjs';
-import { browserTestAutomationStateSchema } from './state.js';
+import {
+  browserTestAutomationInputSchema,
+  browserTestAutomationContextSchema,
+} from './state.js';
 
 export class BrowserTestAutomationAgent extends WorkflowAgent {
   buildGraph() {
     const graph = new WorkflowGraph();
-    graph.setStateSchema(browserTestAutomationStateSchema);
+    graph
+      .setInputSchema(browserTestAutomationInputSchema)
+      .setContextSchema(browserTestAutomationContextSchema);
 
     graph.addNode('preflight', preflightNode);
     graph.addNode('cache_replay', cacheReplayNode);

package/browser-test-automation/package.json

@@ -6,7 +6,7 @@
   "description": "Browser Test Automation \u2014 preflight + live Playwright execution + Playwright-script emission, driven by a Claude/Cursor agent.",
   "main": "graph.mjs",
   "dependencies": {
-    "@zibby/core": "^0.4.0",
+    "@zibby/core": "^0.5.1",
     "zod": "^3.23.0"
   }
 }

package/browser-test-automation/state.js

@@ -1,42 +1,36 @@
 /**
- * Browser Test Automation — Workflow State Schema
+ * Browser Test Automation — Workflow State Schemas
  *
- * Declares the input shape that nodes in this template actually read off
- * `state`. Wired into the graph via `graph.setStateSchema(...)` in
- * graph.mjs so that:
+ * Three-schema model (LangGraph / Mastra style):
  *
- *   - `zibby workflow run <slug> -p testSpec=...` validates inputs
- *     against this schema before nodes ever execute.
- *   - The post-scaffold `Pass inputs:` cheatsheet reads top-level fields
- *     from this schema so the printed examples match what the template
- *     actually consumes (testSpec, model) instead of generic placeholders.
+ *   - browserTestAutomationInputSchema   — trigger-time user input
+ *   - browserTestAutomationContextSchema — runner-injected fields
+ *   - browserTestAutomationStateSchema   — derived merge of the two
  *
- * Field provenance:
- *   - testSpec, model        — USER input (passed via -p / --input).
- *   - cwd, sessionPath,      — FRAMEWORK-injected by the workflow runner
- *     outputPath, context      (NOT user input). Declared optional so a
- *                              user-only payload validates cleanly.
- *   - preflight, execute_live — DOWNSTREAM node outputs (set by earlier
- *                              nodes during graph execution). Same: kept
- *                              optional so initial inputs validate.
+ * `graph.mjs` wires the first two via setInputSchema/setContextSchema; the
+ * engine derives the merged schema internally for run-time validation.
  *
- * `zod` is imported directly from the `zod` package (not re-exported via
- * @zibby/core) — same convention as code-analysis/state.js. The
- * scaffolded user copy gets `zod` via the template's dep merge in
- * templates/index.js.
+ * Field provenance:
+ *   - testSpec, model                     — USER input (passed via -p / --input).
+ *   - cwd, sessionPath, outputPath, context — RUNNER-injected (NOT user input).
+ *   - preflight, execute_live             — node outputs (set during the run;
+ *                                           kept optional so initial state validates).
  */
 
 import { z } from 'zod';
 
-export const browserTestAutomationStateSchema = z.object({
-  // ---- USER INPUT (what `-p` / `--input` populates) ----
+// Trigger-time user input. The trigger modal + CLI render fields from this.
+export const browserTestAutomationInputSchema = z.object({
   testSpec: z.string().describe(
     'Plain-English description of the browser test to analyze + execute (REQUIRED).',
   ),
   model: z.string().default('auto').describe(
     'Agent model override (e.g. "auto", "opus-4.6"). Defaults to "auto".',
   ),
+});
 
+// Runner-injected at runtime. NOT in the trigger UI.
+export const browserTestAutomationContextSchema = z.object({
   // ---- FRAMEWORK-INJECTED (set by the workflow runner, not the user) ----
   cwd: z.string().optional().describe(
     'Working directory the workflow runs in. Injected by the runner.',
@@ -52,6 +46,9 @@ export const browserTestAutomationStateSchema = z.object({
   ),
 
   // ---- DOWNSTREAM NODE OUTPUTS (populated mid-graph, not by the user) ----
+  // Declared on contextSchema (not as a per-node outputSchema) until the
+  // graph-engine supports per-node output declarations natively. Optional
+  // so initial state validates cleanly before nodes have written them.
   preflight: z.any().optional().describe(
     'Output of the preflight node (assertion checklist + title). Set during the run.',
   ),
@@ -59,3 +56,7 @@ export const browserTestAutomationStateSchema = z.object({
     'Output of the execute_live node (recorded actions + steps). Set during the run.',
   ),
 });
+
+// Derived: the full runtime state shape. Exported for tests + tooling.
+export const browserTestAutomationStateSchema =
+  browserTestAutomationInputSchema.merge(browserTestAutomationContextSchema);

package/code-analysis/graph.mjs

@@ -18,10 +18,17 @@
 
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
 import { buildAnalysisGraph } from './graph.js';
+import {
+  analysisInputSchema,
+  analysisContextSchema,
+} from './state.js';
 
 export class CodeAnalysisAgent extends WorkflowAgent {
   buildGraph() {
     const graph = new WorkflowGraph();
+    graph
+      .setInputSchema(analysisInputSchema)
+      .setContextSchema(analysisContextSchema);
     buildAnalysisGraph(graph);
     return graph;
   }

package/code-analysis/package.json

@@ -6,7 +6,7 @@
   "description": "Code Analysis \u2014 multi-node Jira-to-code workflow: analyze ticket \u2192 generate scoped code changes \u2192 emit covering test cases.",
   "main": "graph.mjs",
   "dependencies": {
-    "@zibby/core": "^0.4.0",
+    "@zibby/core": "^0.5.1",
     "axios": "^1.6.0",
     "handlebars": "^4.7.8",
     "zod": "^3.23.0"

package/code-analysis/state.js

@@ -1,48 +1,79 @@
 /**
- * Analysis Workflow State Schema
+ * Code Analysis Workflow — schemas
+ *
+ * Three exports following the LangGraph / Mastra three-schema model:
+ *
+ *  - `analysisInputSchema`   — trigger-time user input. What the web
+ *    trigger modal renders, what `zibby workflow trigger -p …` validates,
+ *    what an external caller (Slack bot, Zapier, CI) sends in `{ input }`
+ *    to POST /trigger. Strictly the fields a HUMAN provides.
+ *
+ *  - `analysisContextSchema` — system-injected fields. Workspace path,
+ *    integration tokens, project repos, deploy-time config. The runner
+ *    populates these from project settings + the resolver registry
+ *    BEFORE handing the state to nodes. Never user-supplied.
+ *
+ *  - `analysisStateSchema`   — derived `inputSchema.merge(contextSchema)`.
+ *    What the engine validates initial state against. Exported so tests
+ *    + tooling that need the merged shape don't have to re-merge.
+ *
+ * Membership IS the declaration: if a field is on `inputSchema` the user
+ * supplies it; if on `contextSchema` the runner injects it. No marker
+ * convention (no `@inject`, no metadata) — same model as LangGraph's
+ * `StateGraph(input_schema=, context_schema=)` split.
  */
 
 import { z } from 'zod';
 
-export const analysisStateSchema = z.object({
-  workspace: z.string().describe('Local workspace path'),
-  
-  repos: z.array(z.object({
-    name: z.string(),
-    url: z.string().url(),
-    path: z.string().optional(),
-    branch: z.string().default('main'),
-    isPrimary: z.boolean().default(false),
-  })).optional().describe('Repository configurations'),
-  
+// What the user types at trigger time.
+export const analysisInputSchema = z.object({
   ticketContext: z.object({
-    key: z.string().regex(/^[A-Z]+-\d+$/, 'Invalid ticket format (expected PROJ-123)').optional(),
-    ticketKey: z.string().optional(),
+    key: z.string().regex(/^[A-Z]+-\d+$/, 'Invalid ticket format (expected PROJ-123)').optional()
+      .describe('Ticket key (e.g. PROJ-123) — optional if `summary` carries enough context'),
     summary: z.string().min(1).describe('Ticket summary/title'),
-    description: z.any().optional().describe('Ticket description (string or ADF object)'),
+    description: z.any().optional().describe('Ticket description (string or Atlassian Document Format)'),
     acceptanceCriteria: z.string().optional(),
-    type: z.string().optional(),
+    type: z.string().optional().describe('Issue type (Bug / Story / Task)'),
     priority: z.string().optional(),
     labels: z.array(z.string()).optional(),
     components: z.array(z.string()).optional(),
-  }).describe('Jira/ticket context'),
-  
-  promptsDir: z.string().optional().describe('Path to prompts directory'),
-  githubToken: z.string().optional().describe('GitHub personal access token'),
-  model: z.string().default('auto').describe('AI model to use'),
-  nodeConfigs: z.record(z.string(), z.any()).optional().describe('Per-node configuration overrides'),
+  }).describe('Ticket details — the only required user input'),
+
+  model: z.string().default('auto')
+    .describe('Agent model override (e.g. "auto", "opus-4.6"). Defaults to "auto".'),
+});
+
+// System-injected at runtime — the runner populates these from project
+// config + integrations before any node executes. NOT exposed to the
+// trigger UI; users can't override them.
+export const analysisContextSchema = z.object({
+  workspace: z.string()
+    .describe('Local workspace path — injected by the runner from project root'),
+
+  repos: z.array(z.object({
+    name: z.string(),
+    url: z.string().url(),
+    path: z.string().optional(),
+    branch: z.string().default('main'),
+    isPrimary: z.boolean().default(false),
+  })).optional()
+    .describe('Repository configurations — injected from the project\'s repo settings'),
+
+  ticketKey: z.string().optional()
+    .describe('Convenience alias of ticketContext.key — set by the setup node'),
+
+  promptsDir: z.string().optional()
+    .describe('Path to prompts directory — injected by the runner (defaults to template-bundled prompts/)'),
+
+  githubToken: z.string().optional()
+    .describe('GitHub PAT — injected by the runner from the user\'s GitHub integration'),
+
+  nodeConfigs: z.record(z.string(), z.any()).optional()
+    .describe('Per-node configuration overrides — set at deploy time, not trigger time'),
 });
 
-// NOTE: legacy `EXECUTION_ID`, `PROGRESS_QUEUE_URL`, `PROGRESS_API_URL`,
-// `SQS_AUTH_TOKEN`, `PROJECT_API_TOKEN` fields are no longer declared in
-// this schema. They were used only by the legacy `analyze-graph` cli +
-// the analysis UI's progress reporter — never by template nodes. Zod's
-// safeParse here doesn't strip unknown keys (see graph.js:504), so the
-// legacy flow still works at runtime: analyze-graph.js injects them
-// into initialState, validation passes, nodes ignore them, the
-// progress-reporter middleware reads them off the state argument.
-//
-// Keeping them out of the schema means scaffolded user copies (via
-// `zibby workflow new -t code-analysis`) ship a clean state that
-// reflects only what the template actually needs — no false coupling
-// to internal infra fields.
+// Derived: what the engine actually validates initialState against at
+// graph.run() time. Re-export so tests and tooling that need the merged
+// shape don't re-merge. NOT canonical — the two source-of-truth schemas
+// above are.
+export const analysisStateSchema = analysisInputSchema.merge(analysisContextSchema);

package/generate-test-cases/graph.mjs

@@ -21,12 +21,17 @@
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
 import { setupNode } from './nodes/setup-node.js';
 import { generateTestCasesNode } from './nodes/generate-test-cases-node.js';
-import { generateTestCasesStateSchema } from './state.js';
+import {
+  generateTestCasesInputSchema,
+  generateTestCasesContextSchema,
+} from './state.js';
 
 export class GenerateTestCasesAgent extends WorkflowAgent {
   buildGraph() {
     const graph = new WorkflowGraph();
-    graph.setStateSchema(generateTestCasesStateSchema);
+    graph
+      .setInputSchema(generateTestCasesInputSchema)
+      .setContextSchema(generateTestCasesContextSchema);
 
     graph.addNode('setup', setupNode);
     graph.addNode('generate_test_cases', generateTestCasesNode);

package/generate-test-cases/package.json

@@ -6,7 +6,7 @@
   "description": "Generate Test Cases \u2014 standalone slice that turns a code diff into prioritized, AI-runnable test specs.",
   "main": "graph.mjs",
   "dependencies": {
-    "@zibby/core": "^0.4.0",
+    "@zibby/core": "^0.5.1",
     "zod": "^3.23.0"
   }
 }

package/generate-test-cases/state.js

@@ -1,28 +1,25 @@
 /**
- * State schema for the generate-test-cases standalone template.
+ * generate-test-cases — Workflow State Schemas
  *
- * Same shape as code-analysis (workspace + repos + ticketContext) PLUS
- * a `codeImplementation` field — the diff this template generates tests
- * for. In code-analysis that field is produced by the upstream
- * generate_code node; here, the user provides it directly.
+ * Same three-schema model as code-analysis + browser-test-automation:
+ *
+ *   - generateTestCasesInputSchema   — trigger-time user input
+ *   - generateTestCasesContextSchema — runner-injected fields
+ *   - generateTestCasesStateSchema   — derived merge of the two
+ *
+ * Differs from code-analysis in one place: `codeImplementation` is part of
+ * USER input here (the user already has a PR diff and wants tests for it),
+ * whereas in code-analysis it's produced by an upstream `generate_code`
+ * node. Otherwise the context fields are the same: workspace + repos +
+ * tokens + nodeConfigs come from the runner, not the trigger caller.
  */
 
 import { z } from 'zod';
 
-export const generateTestCasesStateSchema = z.object({
-  workspace: z.string().describe('Local workspace path'),
-
-  repos: z.array(z.object({
-    name: z.string(),
-    url: z.string().url(),
-    path: z.string().optional(),
-    branch: z.string().default('main'),
-    isPrimary: z.boolean().default(false),
-  })).optional().describe('Repository configurations (cloned by setup node so the LLM can explore routing/components)'),
-
+// Trigger-time user input.
+export const generateTestCasesInputSchema = z.object({
   ticketContext: z.object({
     key: z.string().regex(/^[A-Z]+-\d+$/, 'Invalid ticket format (expected PROJ-123)').optional(),
-    ticketKey: z.string().optional(),
     summary: z.string().min(1).describe('Ticket summary/title'),
     description: z.any().optional().describe('Ticket description (string or ADF object)'),
     acceptanceCriteria: z.string().optional(),
@@ -32,23 +29,38 @@ export const generateTestCasesStateSchema = z.object({
     components: z.array(z.string()).optional(),
   }).describe('Jira/ticket context — informs test priorities + naming'),
 
-  // The new direct-input field that distinguishes this standalone template
-  // from code-analysis. In code-analysis this comes from generate_code's
-  // output; here the user supplies it (e.g. from `git diff` of a PR they
-  // want tests for).
   codeImplementation: z.object({
-    diff: z.string().describe('Unified-diff string of the changes'),
+    diff: z.string().describe('Unified-diff string of the changes (e.g. from `git diff` of a PR)'),
     changedFiles: z.array(z.string()).describe('List of file paths touched'),
   }).describe('Code changes to generate tests for'),
 
-  githubToken: z.string().optional().describe('GitHub PAT (needed only if repos[].url requires auth)'),
   model: z.string().default('auto').describe('AI model to use'),
-  nodeConfigs: z.record(z.string(), z.any()).optional().describe('Per-node configuration overrides (e.g. extractContext for test credentials)'),
 });
 
-// Clean isolation: this schema declares ONLY what the template's nodes
-// actually need. No EXECUTION_ID / PROGRESS_QUEUE_URL / SQS_AUTH_TOKEN
-// / PROJECT_API_TOKEN — those were legacy analysis-UI plumbing fields
-// and the new templates run via the standard `workflow run` /
-// `workflow trigger` cloud pipeline, which has its own progress
-// reporting outside the state object.
+// Runner-injected at runtime. NOT in the trigger UI.
+export const generateTestCasesContextSchema = z.object({
+  workspace: z.string()
+    .describe('Local workspace path — injected by the runner from project root'),
+
+  repos: z.array(z.object({
+    name: z.string(),
+    url: z.string().url(),
+    path: z.string().optional(),
+    branch: z.string().default('main'),
+    isPrimary: z.boolean().default(false),
+  })).optional()
+    .describe('Repository configurations — injected from the project\'s repo settings (cloned by setup node)'),
+
+  ticketKey: z.string().optional()
+    .describe('Convenience alias of ticketContext.key — set by setup node'),
+
+  githubToken: z.string().optional()
+    .describe('GitHub PAT — injected by the runner from the user\'s GitHub integration'),
+
+  nodeConfigs: z.record(z.string(), z.any()).optional()
+    .describe('Per-node configuration overrides — set at deploy time, not trigger time'),
+});
+
+// Derived: full runtime state. Exported for tests + tooling.
+export const generateTestCasesStateSchema =
+  generateTestCasesInputSchema.merge(generateTestCasesContextSchema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/workflow-templates",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Built-in workflow templates for Zibby — browser-test-automation, code-analysis, generate-test-cases. Carved out of @zibby/core@0.4.6 so the engine ships without scaffolding payload.",
   "type": "module",
   "main": "index.js",
@@ -57,7 +57,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.88.0",
-    "@zibby/agent-workflow": "^0.3.0",
+    "@zibby/agent-workflow": "^0.4.0",
     "axios": "^1.15.0",
     "handlebars": "^4.7.9",
     "zod": "^3.23.0 || ^4.0.0"