markform 0.1.22 → 0.1.24

package/README.md

@@ -1,10 +1,12 @@
 # Markform
 
-[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21885509869)
-[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21885509869)
+[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/22024451235)
+[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/22024451235)
 [![npm version](https://img.shields.io/npm/v/markform)](https://www.npmjs.com/package/markform)
 [![X Follow](https://img.shields.io/twitter/follow/ojoshe)](https://x.com/ojoshe)
 
+### What if your Markdown docs had an agent-friendly semantic API?
+
 **Markform** is a text format for defining structured forms that humans can read,
 machines can parse, and agents can fill via tool calls.
 
@@ -13,12 +15,14 @@ Agents fill forms incrementally via patches.
 Fields are validated, so errors are caught early and can be corrected.
 Humans can review or intervene at any point.
 
-**Why forms?** For deep research or complex AI tasks, you need more than just prompts or
+### Why forms?
+
+For deep research or complex AI tasks, you need more than just prompts or
 flow: you need *structure*, which is precise control over agent output at every stage of
 a workflow. A well-designed form combines instructions, structured data, and validations
 in one place.
 
-**How it works:**
+### How it Works
 
 - A Markform document exposes a programmatic interface: users fill fields via CLI or web
   UI, agents fill via tool calls ([Vercel AI SDK](https://github.com/vercel/ai)
@@ -33,9 +37,25 @@ in one place.
   [precise specification](https://github.com/jlevy/markform/blob/main/docs/markform-spec.md).
   Export Markform syntax to JSON, YAML, JSON Schema, or plain Markdown reports.
 
-Markform syntax is a good source format: token-efficient text you can read, diff, and
-version control. Structure is defined with HTML comment tags (`<!-- field -->`) that
-render invisibly on GitHub, so forms look like regular Markdown.
+- Optionally, the whole thing is wrapped in a harness where large forms can be filled
+  concurrently by any LLM in a structured agentic loop.
+
+### Useful details
+
+- Markform syntax is a good source format: it is **token-efficient text** you can read, diff, and
+  version control and it is **ideal for context engineering** because it combines
+  document context, data schema, and memory (data filled so far).
+
+- Structure is defined with HTML comment tags (`<!-- field -->`) that
+  render invisibly on GitHub, so **forms look like regular Markdown**. (Jinja-style
+  tag syntax also works if you prefer.)
+
+- Optionally, **a fill record** of the form-filling process is kept, so you can see
+  and debug exactly how forms are filled by agents, tool usage, LLM call time, etc.
+
+- The CLI has a built-in web renderer, **`markform serve`**, for easy viewing and debugging
+  of forms (including a form web UI, the form schema, and a waterfall-style overview of the
+  fill record, including performance details, which is useful for large, concurrently filled forms).
 
 ## Simple Example: Research a Movie
 
@@ -310,6 +330,23 @@ npm install -g markform
 npm install markform
 ```
 
+### Use as a Claude Code Skill
+
+If you install markform globally (`npm install -g markform`), you can tell Claude to run
+`markform setup --auto` to install it as a Claude Code skill. This teaches Claude how to
+use markform commands when working with `.form.md` files in your project.
+
+```bash
+# Install as a Claude Code skill (non-interactive, for agents)
+markform setup --auto
+
+# Or guided setup with prompts (for humans)
+markform setup --interactive
+
+# View the skill content
+markform skill
+```
+
 ### More Example Forms
 
 The package includes example forms.
@@ -364,16 +401,16 @@ flowchart LR
     subgraph SPEC["<b>MARKFORM SPEC</b>"]
         direction TB
 
-        subgraph L1["<b>LAYER 1: SYNTAX</b><br/>Markdoc tag syntax and frontmatter (form, group, string-field, checkboxes, etc.)"]
+        subgraph L1["<b>LAYER 1: SYNTAX</b><br/>Markdoc tag syntax<br/>and frontmatter (form,<br/>group, string-field, <br/>checkboxes, etc.)"]
         end
 
-        subgraph L2["<b>LAYER 2: FORM DATA MODEL</b><br/>Schema definitions for forms, fields, values (in Zod but mappable to JSON Schema or Pydantic)"]
+        subgraph L2["<b>LAYER 2: FORM DATA MODEL</b><br/>Schema definitions<br/>for forms, fields, values"]
         end
 
-        subgraph L3["<b>LAYER 3: VALIDATION & FORM FILLING</b><br/>Rules for filling forms via patches, field ids, required field semantics, validation hooks"]
+        subgraph L3["<b>LAYER 3: VALIDATION <br/>AND PATCHES</b><br/>Rules for filling forms<br/>via patches, required<br/>field semantics, validation"]
         end
 
-        subgraph L4["<b>LAYER 4: TOOL API & INTERFACES</b><br/>Abstract API for agents and humans (TypeScript and AI SDK integration)"]
+        subgraph L4["<b>LAYER 4: TOOL API <br/>AND INTERFACES</b><br/>Abstract form-filling<br/>loop, concurrency<br/>model, tool layer"]
         end
 
         L4 --> L3 --> L2 --> L1
@@ -382,19 +419,19 @@ flowchart LR
     subgraph IMPL["<b>THIS IMPLEMENTATION</b>"]
         direction TB
 
-        subgraph CLI["<b>`markform` CLI</b><br/>Command-line interface to all features"]
+        subgraph CLI["<b>`markform` CLI</b><br/>Command-line interface<br/>to all features"]
         end
 
-        subgraph AGENT["<b>AGENT TOOL INTERFACE</b><br/>Tool API library using AI SDK tools"]
+        subgraph AGENT["<b>AGENT TOOL INTERFACE</b><br/>Tool API library><br/>(AI SDK tools)"]
         end
 
-        subgraph HARNESS["<b>EXECUTION HARNESS</b><br/>Step-by-step form-filling agentic loop"]
+        subgraph HARNESS["<b>EXECUTION HARNESS</b><br/>Concurrent form-filling<br/>agentic loop<br/>(AI SDK)"]
         end
 
-        subgraph ENGINE["<b>CORE TYPESCRIPT APIS</b><br/>Markdoc parser, serializer, patch application, validation (uses jiti for TypeScript rules)"]
+        subgraph ENGINE["<b>CORE TYPESCRIPT APIS</b><br/>Markdoc parser, serializer,<br/>patch application,<br/>validation (jiti for rules)"]
         end
 
-        subgraph TEST["<b>TESTING FRAMEWORK</b><br/>Golden session testing with .session.yaml transcripts"]
+        subgraph TEST["<b>TESTING FRAMEWORK</b><br/>Golden session testing<br/>(.session.yaml transcripts)"]
         end
 
         CLI --> ENGINE

package/dist/ai-sdk.d.mts

@@ -1,5 +1,5 @@
 
-import { At as ParsedForm, Nt as PatchSchema, U as FieldResponse, Y as FormSchema, at as InspectResult, et as Id, hr as ValidatorRegistry, jt as Patch, r as ApplyResult } from "./coreTypes-BlsJkU1w.mjs";
+import { At as ParsedForm, Nt as PatchSchema, U as FieldResponse, Y as FormSchema, at as InspectResult, et as Id, gr as ValidatorRegistry, jt as Patch, r as ApplyResult } from "./coreTypes-GxzWNXap.mjs";
 import { z } from "zod";
 
 //#region src/integrations/toolTypes.d.ts

package/dist/ai-sdk.mjs

@@ -1,6 +1,6 @@
 
-import { R as PatchSchema } from "./coreTypes-CTLr-NGd.mjs";
-import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-C7mO7VkZ.mjs";
+import { R as PatchSchema } from "./coreTypes-CctFK6uE.mjs";
+import { _ as inspect, m as applyPatches, p as findFieldById, s as getPatchFormatHint, u as getFieldIdFromRef, w as serializeForm } from "./prompts-BCnYaH4_.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts
@@ -64,7 +64,7 @@ const InspectInputSchema = z.object({}).describe("No input parameters required.
 /**
 * Input schema for markform_apply tool.
 */
-const ApplyInputSchema = z.object({ patches: z.array(PatchSchema).min(1).max(20).describe("Array of patches to apply to the form. Each patch sets or clears a field value. Operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, set_url, set_url_list, set_date, set_year, set_table, clear_field, skip_field, abort_field. Example: [{ \"op\": \"set_string\", \"fieldId\": \"name\", \"value\": \"Alice\" }]") }).describe("Apply patches to update form field values.");
+const ApplyInputSchema = z.object({ patches: z.array(PatchSchema).min(1).max(20).describe("Array of patches to apply to the form. Each patch sets or clears a field value. Set operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, set_url, set_url_list, set_date, set_year, set_table. Incremental operations: append_table, delete_table, append_string_list, delete_string_list, append_url_list, delete_url_list. Meta operations: clear_field, skip_field, abort_field. Example: [{ \"op\": \"set_string\", \"fieldId\": \"name\", \"value\": \"Alice\" }]") }).describe("Apply patches to update form field values.");
 /**
 * Input schema for markform_export tool (no parameters).
 */
@@ -73,6 +73,43 @@ const ExportInputSchema = z.object({}).describe("No input parameters required. C
 * Input schema for markform_get_markdown tool (no parameters).
 */
 const GetMarkdownInputSchema = z.object({}).describe("No input parameters required. Call this tool to get the canonical Markdown representation of the current form.");
+function buildFieldMeta(field) {
+	const meta = {
+		kind: field.kind,
+		label: field.label,
+		required: field.required
+	};
+	if (field.kind === "single_select" || field.kind === "multi_select") meta.options = field.options.map((o) => o.id);
+	else if (field.kind === "checkboxes") {
+		meta.options = field.options.map((o) => o.id);
+		meta.checkbox_mode = field.checkboxMode;
+	} else if (field.kind === "table") meta.columns = field.columns.map((c) => ({
+		id: c.id,
+		type: c.type,
+		required: c.required
+	}));
+	return meta;
+}
+function generatePatchExample(field) {
+	const opts = { fieldId: field.id };
+	if (field.kind === "table") opts.columnIds = field.columns.map((c) => c.id);
+	else if (field.kind === "checkboxes") {
+		opts.checkboxMode = field.checkboxMode;
+		opts.optionIds = field.options.map((o) => o.id);
+	}
+	return getPatchFormatHint(field.kind, opts);
+}
+function enrichIssue(issue, form) {
+	const fieldId = getFieldIdFromRef(issue.ref, issue.scope);
+	const field = fieldId ? findFieldById(form, fieldId) : void 0;
+	if (!field) return issue;
+	return {
+		...issue,
+		field: buildFieldMeta(field),
+		set_example: generatePatchExample(field),
+		skip_example: field.required ? null : `{ op: "skip_field", fieldId: "${field.id}", reason: "Not applicable" }`
+	};
+}
 /**
 * Create Markform AI SDK tools for agent-driven form filling.
 *
@@ -105,18 +142,23 @@ function createMarkformTools(options) {
 			description: "Inspect the current form state. Returns structure summary, progress summary, validation issues, and completion status. Use this to understand what fields need to be filled and what issues exist. Issues are sorted by priority (1 = highest). Focus on 'required' severity issues first.",
 			inputSchema: InspectInputSchema,
 			execute: () => {
-				const result = inspect(sessionStore.getForm());
+				const form = sessionStore.getForm();
+				const result = inspect(form);
+				const enrichedIssues = result.issues.map((issue) => enrichIssue(issue, form));
 				const requiredCount = result.issues.filter((i) => i.severity === "required").length;
 				const message = result.isComplete ? "Form is complete. All required fields are filled." : `Form has ${requiredCount} required issue(s) to resolve.`;
 				return Promise.resolve({
 					success: true,
-					data: result,
+					data: {
+						...result,
+						issues: enrichedIssues
+					},
 					message
 				});
 			}
 		},
 		markform_apply: {
-			description: "Apply patches to update form field values. Valid patches are applied even if some fail. Single values are automatically coerced to arrays for list fields. Returns applied patches, warnings for coerced values, and rejected patches separately. Patch operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, set_url, set_url_list, set_date, set_year, set_table, clear_field, skip_field, abort_field.",
+			description: "Apply patches to update form field values. Valid patches are applied even if some fail. Single values are automatically coerced to arrays for list fields. Returns applied patches, warnings for coerced values, and rejected patches separately. Set operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, set_url, set_url_list, set_date, set_year, set_table. Incremental: append_table, delete_table, append_string_list, delete_string_list, append_url_list, delete_url_list. Meta: clear_field, skip_field, abort_field.",
 			inputSchema: ApplyInputSchema,
 			execute: ({ patches }) => {
 				const form = sessionStore.getForm();

package/dist/ai-sdk.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk.mjs","names":[],"sources":["../src/integrations/vercelAiSdkTools.ts"],"sourcesContent":["/**\n * AI SDK Integration for Markform.\n *\n * Provides Vercel AI SDK compatible tools for agent-driven form filling.\n * Use createMarkformTools() to create a toolset that wraps the Markform engine.\n *\n * @example\n * ```typescript\n * import { createMarkformTools, MarkformSessionStore } from 'markform/ai-sdk';\n * import { generateText } from 'ai';\n *\n * const store = new MarkformSessionStore(parsedForm);\n * const tools = createMarkformTools({ sessionStore: store });\n *\n * const { text } = await generateText({\n *   model: openai('gpt-4'),\n *   prompt: 'Fill out this form...',\n *   tools,\n * });\n * ```\n */\n\nimport { z } from 'zod';\nimport type { ParsedForm, Patch, ValidatorRegistry } from '../engine/coreTypes.js';\nimport { inspect } from '../engine/inspect.js';\nimport { applyPatches } from '../engine/apply.js';\nimport { serializeForm } from '../engine/serialize.js';\nimport { PatchSchema } from '../engine/coreTypes.js';\n\n// =============================================================================\n// Session Store\n// =============================================================================\n\n/**\n * Session store for managing form state during AI interactions.\n *\n * The AI SDK tools operate on a shared form instance through this store.\n * Create one store per form-filling session.\n */\nexport class MarkformSessionStore {\n  private form: ParsedForm;\n  private validatorRegistry: ValidatorRegistry;\n\n  constructor(form: ParsedForm, validatorRegistry?: ValidatorRegistry) {\n    this.form = form;\n    this.validatorRegistry = validatorRegistry ?? {};\n  }\n\n  /**\n   * Get the current form.\n   */\n  getForm(): ParsedForm {\n    return this.form;\n  }\n\n  /**\n   * Get the validator registry.\n   */\n  getValidatorRegistry(): ValidatorRegistry {\n    return this.validatorRegistry;\n  }\n\n  /**\n   * Update the form values.\n   */\n  updateForm(form: ParsedForm): void {\n    this.form = form;\n  }\n}\n\n// =============================================================================\n// Tool Creation Options\n// =============================================================================\n\n/**\n * Options for creating Markform AI SDK tools.\n */\nexport interface CreateMarkformToolsOptions {\n  /**\n   * Session store managing the form state.\n   */\n  sessionStore: MarkformSessionStore;\n\n  /**\n   * Whether to include the markform_get_markdown tool.\n   * Defaults to true.\n   */\n  includeGetMarkdown?: boolean;\n}\n\n// =============================================================================\n// Tool Types (imported from toolTypes.ts)\n// =============================================================================\n\nimport type {\n  ApplyToolResult,\n  ExportToolResult,\n  GetMarkdownToolResult,\n  InspectToolResult,\n  MarkformTool,\n  MarkformToolSet,\n} from './toolTypes.js';\n\n// Re-export types for backwards compatibility\nexport type {\n  ApplyToolResult,\n  ExportToolResult,\n  GetMarkdownToolResult,\n  InspectToolResult,\n  MarkformTool,\n  MarkformToolSet,\n} from './toolTypes.js';\n\n// =============================================================================\n// Zod Schemas for Tool Inputs\n// =============================================================================\n\n/**\n * Input schema for markform_inspect tool (no parameters).\n */\nconst InspectInputSchema = z\n  .object({})\n  .describe('No input parameters required. Call this tool to inspect the current form state.');\n\n/**\n * Input schema for markform_apply tool.\n */\nconst ApplyInputSchema = z\n  .object({\n    patches: z\n      .array(PatchSchema)\n      .min(1)\n      .max(20)\n      .describe(\n        'Array of patches to apply to the form. Each patch sets or clears a field value. ' +\n          'Operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, ' +\n          'set_checkboxes, set_url, set_url_list, set_date, set_year, set_table, clear_field, skip_field, abort_field. ' +\n          'Example: [{ \"op\": \"set_string\", \"fieldId\": \"name\", \"value\": \"Alice\" }]',\n      ),\n  })\n  .describe('Apply patches to update form field values.');\n\n/**\n * Input schema for markform_export tool (no parameters).\n */\nconst ExportInputSchema = z\n  .object({})\n  .describe(\n    'No input parameters required. Call this tool to export the form schema and current values as JSON.',\n  );\n\n/**\n * Input schema for markform_get_markdown tool (no parameters).\n */\nconst GetMarkdownInputSchema = z\n  .object({})\n  .describe(\n    'No input parameters required. Call this tool to get the canonical Markdown representation of the current form.',\n  );\n\n// =============================================================================\n// Tool Factory\n// =============================================================================\n\n/**\n * Create Markform AI SDK tools for agent-driven form filling.\n *\n * Returns a toolset compatible with Vercel AI SDK's generateText and streamText.\n *\n * @param options - Tool creation options including session store\n * @returns MarkformToolSet containing all tools\n *\n * @example\n * ```typescript\n * import { parseForm } from 'markform';\n * import { createMarkformTools, MarkformSessionStore } from 'markform/ai-sdk';\n *\n * const form = parseForm(markdownContent);\n * const store = new MarkformSessionStore(form);\n * const tools = createMarkformTools({ sessionStore: store });\n *\n * // Use with AI SDK\n * const result = await generateText({\n *   model: yourModel,\n *   tools,\n *   prompt: 'Fill out this form based on the user information...',\n * });\n * ```\n */\nexport function createMarkformTools(options: CreateMarkformToolsOptions): MarkformToolSet {\n  const { sessionStore, includeGetMarkdown = true } = options;\n\n  // markform_inspect - Get current form state with issues\n  const markform_inspect: MarkformTool<Record<string, never>, InspectToolResult> = {\n    description:\n      'Inspect the current form state. Returns structure summary, progress summary, validation issues, ' +\n      'and completion status. Use this to understand what fields need to be filled and what issues exist. ' +\n      \"Issues are sorted by priority (1 = highest). Focus on 'required' severity issues first.\",\n    inputSchema: InspectInputSchema,\n    execute: () => {\n      const form = sessionStore.getForm();\n      const result = inspect(form);\n\n      const requiredCount = result.issues.filter((i) => i.severity === 'required').length;\n      const message = result.isComplete\n        ? 'Form is complete. All required fields are filled.'\n        : `Form has ${requiredCount} required issue(s) to resolve.`;\n\n      return Promise.resolve({\n        success: true,\n        data: result,\n        message,\n      });\n    },\n  };\n\n  // markform_apply - Apply patches to update form values\n  const markform_apply: MarkformTool<{ patches: Patch[] }, ApplyToolResult> = {\n    description:\n      'Apply patches to update form field values. Valid patches are applied even if some fail. ' +\n      'Single values are automatically coerced to arrays for list fields. ' +\n      'Returns applied patches, warnings for coerced values, and rejected patches separately. ' +\n      'Patch operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, ' +\n      'set_checkboxes, set_url, set_url_list, set_date, set_year, set_table, clear_field, skip_field, abort_field.',\n    inputSchema: ApplyInputSchema,\n    execute: ({ patches }) => {\n      const form = sessionStore.getForm();\n      const result = applyPatches(form, patches);\n\n      // Update the store with the modified form\n      sessionStore.updateForm(form);\n\n      const warningNote = result.warnings.length > 0 ? ` (${result.warnings.length} coerced)` : '';\n      const remaining = result.issues.filter((i) => i.severity === 'required').length;\n\n      const message =\n        result.applyStatus === 'applied'\n          ? `Applied ${patches.length} patch(es)${warningNote}. ${\n              result.isComplete\n                ? 'Form is now complete!'\n                : `${remaining} required issue(s) remaining.`\n            }`\n          : result.applyStatus === 'partial'\n            ? `Applied ${result.appliedPatches.length}/${patches.length} patches${warningNote}. ` +\n              `${result.rejectedPatches.length} rejected.`\n            : `All patches rejected. Check field IDs and value types.`;\n\n      return Promise.resolve({\n        success: result.applyStatus !== 'rejected',\n        data: result,\n        message,\n      });\n    },\n  };\n\n  // markform_export - Export schema and values as JSON\n  const markform_export: MarkformTool<Record<string, never>, ExportToolResult> = {\n    description:\n      'Export the form schema and current values as JSON. Use this to get a machine-readable ' +\n      'representation of the form structure and all field values. Useful for processing or analysis.',\n    inputSchema: ExportInputSchema,\n    execute: () => {\n      const form = sessionStore.getForm();\n\n      // Count answered fields\n      const answeredCount = Object.values(form.responsesByFieldId).filter(\n        (response) => response.state === 'answered',\n      ).length;\n\n      return Promise.resolve({\n        success: true,\n        data: {\n          schema: form.schema,\n          values: form.responsesByFieldId,\n        },\n        message: `Exported form with ${form.schema.groups.length} group(s) and ${answeredCount} answered field(s).`,\n      });\n    },\n  };\n\n  // Build the toolset\n  const toolset: MarkformToolSet = {\n    markform_inspect,\n    markform_apply,\n    markform_export,\n  };\n\n  // Optionally include markform_get_markdown\n  if (includeGetMarkdown) {\n    const markform_get_markdown: MarkformTool<Record<string, never>, GetMarkdownToolResult> = {\n      description:\n        'Get the canonical Markdown representation of the current form. ' +\n        'Use this to see the complete form with all current values in Markform format. ' +\n        'The output is deterministic and round-trip safe.',\n      inputSchema: GetMarkdownInputSchema,\n      execute: () => {\n        const form = sessionStore.getForm();\n        const markdown = serializeForm(form);\n\n        return Promise.resolve({\n          success: true,\n          data: {\n            markdown,\n          },\n          message: `Generated Markdown (${markdown.length} characters).`,\n        });\n      },\n    };\n\n    toolset.markform_get_markdown = markform_get_markdown;\n  }\n\n  return toolset;\n}\n\n// =============================================================================\n// Convenience Exports\n// =============================================================================\n\nexport { PatchSchema } from '../engine/coreTypes.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAa,uBAAb,MAAkC;CAChC,AAAQ;CACR,AAAQ;CAER,YAAY,MAAkB,mBAAuC;AACnE,OAAK,OAAO;AACZ,OAAK,oBAAoB,qBAAqB,EAAE;;;;;CAMlD,UAAsB;AACpB,SAAO,KAAK;;;;;CAMd,uBAA0C;AACxC,SAAO,KAAK;;;;;CAMd,WAAW,MAAwB;AACjC,OAAK,OAAO;;;;;;AAsDhB,MAAM,qBAAqB,EACxB,OAAO,EAAE,CAAC,CACV,SAAS,kFAAkF;;;;AAK9F,MAAM,mBAAmB,EACtB,OAAO,EACN,SAAS,EACN,MAAM,YAAY,CAClB,IAAI,EAAE,CACN,IAAI,GAAG,CACP,SACC,2WAID,EACJ,CAAC,CACD,SAAS,6CAA6C;;;;AAKzD,MAAM,oBAAoB,EACvB,OAAO,EAAE,CAAC,CACV,SACC,qGACD;;;;AAKH,MAAM,yBAAyB,EAC5B,OAAO,EAAE,CAAC,CACV,SACC,iHACD;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BH,SAAgB,oBAAoB,SAAsD;CACxF,MAAM,EAAE,cAAc,qBAAqB,SAAS;CA2FpD,MAAM,UAA2B;EAC/B,kBAzF+E;GAC/E,aACE;GAGF,aAAa;GACb,eAAe;IAEb,MAAM,SAAS,QADF,aAAa,SAAS,CACP;IAE5B,MAAM,gBAAgB,OAAO,OAAO,QAAQ,MAAM,EAAE,aAAa,WAAW,CAAC;IAC7E,MAAM,UAAU,OAAO,aACnB,sDACA,YAAY,cAAc;AAE9B,WAAO,QAAQ,QAAQ;KACrB,SAAS;KACT,MAAM;KACN;KACD,CAAC;;GAEL;EAqEC,gBAlE0E;GAC1E,aACE;GAKF,aAAa;GACb,UAAU,EAAE,cAAc;IACxB,MAAM,OAAO,aAAa,SAAS;IACnC,MAAM,SAAS,aAAa,MAAM,QAAQ;AAG1C,iBAAa,WAAW,KAAK;IAE7B,MAAM,cAAc,OAAO,SAAS,SAAS,IAAI,KAAK,OAAO,SAAS,OAAO,aAAa;IAC1F,MAAM,YAAY,OAAO,OAAO,QAAQ,MAAM,EAAE,aAAa,WAAW,CAAC;IAEzE,MAAM,UACJ,OAAO,gBAAgB,YACnB,WAAW,QAAQ,OAAO,YAAY,YAAY,IAChD,OAAO,aACH,0BACA,GAAG,UAAU,mCAEnB,OAAO,gBAAgB,YACrB,WAAW,OAAO,eAAe,OAAO,GAAG,QAAQ,OAAO,UAAU,YAAY,IAC7E,OAAO,gBAAgB,OAAO,cACjC;AAER,WAAO,QAAQ,QAAQ;KACrB,SAAS,OAAO,gBAAgB;KAChC,MAAM;KACN;KACD,CAAC;;GAEL;EA+BC,iBA5B6E;GAC7E,aACE;GAEF,aAAa;GACb,eAAe;IACb,MAAM,OAAO,aAAa,SAAS;IAGnC,MAAM,gBAAgB,OAAO,OAAO,KAAK,mBAAmB,CAAC,QAC1D,aAAa,SAAS,UAAU,WAClC,CAAC;AAEF,WAAO,QAAQ,QAAQ;KACrB,SAAS;KACT,MAAM;MACJ,QAAQ,KAAK;MACb,QAAQ,KAAK;MACd;KACD,SAAS,sBAAsB,KAAK,OAAO,OAAO,OAAO,gBAAgB,cAAc;KACxF,CAAC;;GAEL;EAOA;AAGD,KAAI,mBAqBF,SAAQ,wBApBkF;EACxF,aACE;EAGF,aAAa;EACb,eAAe;GAEb,MAAM,WAAW,cADJ,aAAa,SAAS,CACC;AAEpC,UAAO,QAAQ,QAAQ;IACrB,SAAS;IACT,MAAM,EACJ,UACD;IACD,SAAS,uBAAuB,SAAS,OAAO;IACjD,CAAC;;EAEL;AAKH,QAAO"}
+{"version":3,"file":"ai-sdk.mjs","names":[],"sources":["../src/integrations/vercelAiSdkTools.ts"],"sourcesContent":["/**\n * AI SDK Integration for Markform.\n *\n * Provides Vercel AI SDK compatible tools for agent-driven form filling.\n * Use createMarkformTools() to create a toolset that wraps the Markform engine.\n *\n * @example\n * ```typescript\n * import { createMarkformTools, MarkformSessionStore } from 'markform/ai-sdk';\n * import { generateText } from 'ai';\n *\n * const store = new MarkformSessionStore(parsedForm);\n * const tools = createMarkformTools({ sessionStore: store });\n *\n * const { text } = await generateText({\n *   model: openai('gpt-4'),\n *   prompt: 'Fill out this form...',\n *   tools,\n * });\n * ```\n */\n\nimport { z } from 'zod';\nimport type {\n  Field,\n  InspectIssue,\n  ParsedForm,\n  Patch,\n  ValidatorRegistry,\n} from '../engine/coreTypes.js';\nimport { inspect } from '../engine/inspect.js';\nimport { applyPatches } from '../engine/apply.js';\nimport { serializeForm } from '../engine/serialize.js';\nimport { PatchSchema } from '../engine/coreTypes.js';\nimport { getFieldIdFromRef } from '../engine/issueFiltering.js';\nimport { findFieldById } from '../engine/valueCoercion.js';\nimport { getPatchFormatHint } from '../harness/prompts.js';\n\n// =============================================================================\n// Session Store\n// =============================================================================\n\n/**\n * Session store for managing form state during AI interactions.\n *\n * The AI SDK tools operate on a shared form instance through this store.\n * Create one store per form-filling session.\n */\nexport class MarkformSessionStore {\n  private form: ParsedForm;\n  private validatorRegistry: ValidatorRegistry;\n\n  constructor(form: ParsedForm, validatorRegistry?: ValidatorRegistry) {\n    this.form = form;\n    this.validatorRegistry = validatorRegistry ?? {};\n  }\n\n  /**\n   * Get the current form.\n   */\n  getForm(): ParsedForm {\n    return this.form;\n  }\n\n  /**\n   * Get the validator registry.\n   */\n  getValidatorRegistry(): ValidatorRegistry {\n    return this.validatorRegistry;\n  }\n\n  /**\n   * Update the form values.\n   */\n  updateForm(form: ParsedForm): void {\n    this.form = form;\n  }\n}\n\n// =============================================================================\n// Tool Creation Options\n// =============================================================================\n\n/**\n * Options for creating Markform AI SDK tools.\n */\nexport interface CreateMarkformToolsOptions {\n  /**\n   * Session store managing the form state.\n   */\n  sessionStore: MarkformSessionStore;\n\n  /**\n   * Whether to include the markform_get_markdown tool.\n   * Defaults to true.\n   */\n  includeGetMarkdown?: boolean;\n}\n\n// =============================================================================\n// Tool Types (imported from toolTypes.ts)\n// =============================================================================\n\nimport type {\n  ApplyToolResult,\n  ExportToolResult,\n  GetMarkdownToolResult,\n  InspectToolResult,\n  MarkformTool,\n  MarkformToolSet,\n} from './toolTypes.js';\n\n// Re-export types for backwards compatibility\nexport type {\n  ApplyToolResult,\n  ExportToolResult,\n  GetMarkdownToolResult,\n  InspectToolResult,\n  MarkformTool,\n  MarkformToolSet,\n} from './toolTypes.js';\n\n// =============================================================================\n// Zod Schemas for Tool Inputs\n// =============================================================================\n\n/**\n * Input schema for markform_inspect tool (no parameters).\n */\nconst InspectInputSchema = z\n  .object({})\n  .describe('No input parameters required. Call this tool to inspect the current form state.');\n\n/**\n * Input schema for markform_apply tool.\n */\nconst ApplyInputSchema = z\n  .object({\n    patches: z\n      .array(PatchSchema)\n      .min(1)\n      .max(20)\n      .describe(\n        'Array of patches to apply to the form. Each patch sets or clears a field value. ' +\n          'Set operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, ' +\n          'set_checkboxes, set_url, set_url_list, set_date, set_year, set_table. ' +\n          'Incremental operations: append_table, delete_table, append_string_list, delete_string_list, append_url_list, delete_url_list. ' +\n          'Meta operations: clear_field, skip_field, abort_field. ' +\n          'Example: [{ \"op\": \"set_string\", \"fieldId\": \"name\", \"value\": \"Alice\" }]',\n      ),\n  })\n  .describe('Apply patches to update form field values.');\n\n/**\n * Input schema for markform_export tool (no parameters).\n */\nconst ExportInputSchema = z\n  .object({})\n  .describe(\n    'No input parameters required. Call this tool to export the form schema and current values as JSON.',\n  );\n\n/**\n * Input schema for markform_get_markdown tool (no parameters).\n */\nconst GetMarkdownInputSchema = z\n  .object({})\n  .describe(\n    'No input parameters required. Call this tool to get the canonical Markdown representation of the current form.',\n  );\n\n// =============================================================================\n// Issue Enrichment\n// =============================================================================\n\ninterface EnrichedFieldMeta {\n  kind: string;\n  label: string;\n  required: boolean;\n  options?: string[];\n  checkbox_mode?: string;\n  columns?: { id: string; type: string; required: boolean }[];\n}\n\nfunction buildFieldMeta(field: Field): EnrichedFieldMeta {\n  const meta: EnrichedFieldMeta = {\n    kind: field.kind,\n    label: field.label,\n    required: field.required,\n  };\n\n  if (field.kind === 'single_select' || field.kind === 'multi_select') {\n    meta.options = field.options.map((o) => o.id);\n  } else if (field.kind === 'checkboxes') {\n    meta.options = field.options.map((o) => o.id);\n    meta.checkbox_mode = field.checkboxMode;\n  } else if (field.kind === 'table') {\n    meta.columns = field.columns.map((c) => ({\n      id: c.id,\n      type: c.type,\n      required: c.required,\n    }));\n  }\n\n  return meta;\n}\n\nfunction generatePatchExample(field: Field): string {\n  const opts: {\n    fieldId: string;\n    columnIds?: string[];\n    checkboxMode?: 'simple' | 'multi' | 'explicit';\n    optionIds?: string[];\n  } = {\n    fieldId: field.id,\n  };\n\n  if (field.kind === 'table') {\n    opts.columnIds = field.columns.map((c) => c.id);\n  } else if (field.kind === 'checkboxes') {\n    opts.checkboxMode = field.checkboxMode;\n    opts.optionIds = field.options.map((o) => o.id);\n  }\n\n  return getPatchFormatHint(field.kind, opts);\n}\n\nfunction enrichIssue(\n  issue: InspectIssue,\n  form: ParsedForm,\n): InspectIssue & {\n  field?: EnrichedFieldMeta;\n  set_example?: string;\n  skip_example?: string | null;\n} {\n  const fieldId = getFieldIdFromRef(issue.ref, issue.scope);\n  const field = fieldId ? findFieldById(form, fieldId) : undefined;\n\n  if (!field) return issue;\n\n  return {\n    ...issue,\n    field: buildFieldMeta(field),\n    set_example: generatePatchExample(field),\n    skip_example: field.required\n      ? null\n      : `{ op: \"skip_field\", fieldId: \"${field.id}\", reason: \"Not applicable\" }`,\n  };\n}\n\n// =============================================================================\n// Tool Factory\n// =============================================================================\n\n/**\n * Create Markform AI SDK tools for agent-driven form filling.\n *\n * Returns a toolset compatible with Vercel AI SDK's generateText and streamText.\n *\n * @param options - Tool creation options including session store\n * @returns MarkformToolSet containing all tools\n *\n * @example\n * ```typescript\n * import { parseForm } from 'markform';\n * import { createMarkformTools, MarkformSessionStore } from 'markform/ai-sdk';\n *\n * const form = parseForm(markdownContent);\n * const store = new MarkformSessionStore(form);\n * const tools = createMarkformTools({ sessionStore: store });\n *\n * // Use with AI SDK\n * const result = await generateText({\n *   model: yourModel,\n *   tools,\n *   prompt: 'Fill out this form based on the user information...',\n * });\n * ```\n */\nexport function createMarkformTools(options: CreateMarkformToolsOptions): MarkformToolSet {\n  const { sessionStore, includeGetMarkdown = true } = options;\n\n  // markform_inspect - Get current form state with issues\n  const markform_inspect: MarkformTool<Record<string, never>, InspectToolResult> = {\n    description:\n      'Inspect the current form state. Returns structure summary, progress summary, validation issues, ' +\n      'and completion status. Use this to understand what fields need to be filled and what issues exist. ' +\n      \"Issues are sorted by priority (1 = highest). Focus on 'required' severity issues first.\",\n    inputSchema: InspectInputSchema,\n    execute: () => {\n      const form = sessionStore.getForm();\n      const result = inspect(form);\n\n      // Enrich issues with field metadata and patch examples\n      const enrichedIssues = result.issues.map((issue) => enrichIssue(issue, form));\n\n      const requiredCount = result.issues.filter((i) => i.severity === 'required').length;\n      const message = result.isComplete\n        ? 'Form is complete. All required fields are filled.'\n        : `Form has ${requiredCount} required issue(s) to resolve.`;\n\n      return Promise.resolve({\n        success: true,\n        data: { ...result, issues: enrichedIssues },\n        message,\n      });\n    },\n  };\n\n  // markform_apply - Apply patches to update form values\n  const markform_apply: MarkformTool<{ patches: Patch[] }, ApplyToolResult> = {\n    description:\n      'Apply patches to update form field values. Valid patches are applied even if some fail. ' +\n      'Single values are automatically coerced to arrays for list fields. ' +\n      'Returns applied patches, warnings for coerced values, and rejected patches separately. ' +\n      'Set operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, ' +\n      'set_checkboxes, set_url, set_url_list, set_date, set_year, set_table. ' +\n      'Incremental: append_table, delete_table, append_string_list, delete_string_list, append_url_list, delete_url_list. ' +\n      'Meta: clear_field, skip_field, abort_field.',\n    inputSchema: ApplyInputSchema,\n    execute: ({ patches }) => {\n      const form = sessionStore.getForm();\n      const result = applyPatches(form, patches);\n\n      // Update the store with the modified form\n      sessionStore.updateForm(form);\n\n      const warningNote = result.warnings.length > 0 ? ` (${result.warnings.length} coerced)` : '';\n      const remaining = result.issues.filter((i) => i.severity === 'required').length;\n\n      const message =\n        result.applyStatus === 'applied'\n          ? `Applied ${patches.length} patch(es)${warningNote}. ${\n              result.isComplete\n                ? 'Form is now complete!'\n                : `${remaining} required issue(s) remaining.`\n            }`\n          : result.applyStatus === 'partial'\n            ? `Applied ${result.appliedPatches.length}/${patches.length} patches${warningNote}. ` +\n              `${result.rejectedPatches.length} rejected.`\n            : `All patches rejected. Check field IDs and value types.`;\n\n      return Promise.resolve({\n        success: result.applyStatus !== 'rejected',\n        data: result,\n        message,\n      });\n    },\n  };\n\n  // markform_export - Export schema and values as JSON\n  const markform_export: MarkformTool<Record<string, never>, ExportToolResult> = {\n    description:\n      'Export the form schema and current values as JSON. Use this to get a machine-readable ' +\n      'representation of the form structure and all field values. Useful for processing or analysis.',\n    inputSchema: ExportInputSchema,\n    execute: () => {\n      const form = sessionStore.getForm();\n\n      // Count answered fields\n      const answeredCount = Object.values(form.responsesByFieldId).filter(\n        (response) => response.state === 'answered',\n      ).length;\n\n      return Promise.resolve({\n        success: true,\n        data: {\n          schema: form.schema,\n          values: form.responsesByFieldId,\n        },\n        message: `Exported form with ${form.schema.groups.length} group(s) and ${answeredCount} answered field(s).`,\n      });\n    },\n  };\n\n  // Build the toolset\n  const toolset: MarkformToolSet = {\n    markform_inspect,\n    markform_apply,\n    markform_export,\n  };\n\n  // Optionally include markform_get_markdown\n  if (includeGetMarkdown) {\n    const markform_get_markdown: MarkformTool<Record<string, never>, GetMarkdownToolResult> = {\n      description:\n        'Get the canonical Markdown representation of the current form. ' +\n        'Use this to see the complete form with all current values in Markform format. ' +\n        'The output is deterministic and round-trip safe.',\n      inputSchema: GetMarkdownInputSchema,\n      execute: () => {\n        const form = sessionStore.getForm();\n        const markdown = serializeForm(form);\n\n        return Promise.resolve({\n          success: true,\n          data: {\n            markdown,\n          },\n          message: `Generated Markdown (${markdown.length} characters).`,\n        });\n      },\n    };\n\n    toolset.markform_get_markdown = markform_get_markdown;\n  }\n\n  return toolset;\n}\n\n// =============================================================================\n// Convenience Exports\n// =============================================================================\n\nexport { PatchSchema } from '../engine/coreTypes.js';\n"],"mappings":"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"}

package/dist/bin.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { t as runCli } from "./cli-C8F9yDsv.mjs";
+import { t as runCli } from "./cli-B1DhFYBS.mjs";
 import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { config } from "dotenv";