markform 0.1.23 → 0.1.25

package/README.md

@@ -1,9 +1,8 @@
 # Markform
 
-[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21980795343)
-[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21980795343)
+[![Follow @ojoshe on X](https://img.shields.io/badge/follow_%40ojoshe-black?logo=x&logoColor=white)](https://x.com/ojoshe)
+[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/workflows/ci.yml)
 [![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?
 
@@ -17,10 +16,10 @@ Humans can review or intervene at any point.
 
 ### 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.
+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
 
@@ -42,20 +41,24 @@ in one place.
 
 ### 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).
+- 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.)
+- 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.
+- Form-filling can scale to **hundreds of fields** in a form filled by **dozens of
+  concurrent LLM requests** which makes it possible to systemetize large, complex
+  research processes or workflows.
+  (And **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).
+- 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
 
@@ -302,11 +305,34 @@ See [the FAQ](#faq) for more on the design.
 
 ## Quick Start
 
+There are three ways to get started, from quickest to most thorough:
+
+**1. Run an example automatically** — copy bundled forms and let an LLM fill one:
+
 ```bash
-# Copy example forms to ./forms/ and run one interactively.
-# Set OPENAI_API_KEY or ANTHROPIC_API_KEY (or put in .env) for research examples
+# Set OPENAI_API_KEY or ANTHROPIC_API_KEY (or put in .env)
 npx markform@latest examples
+```
+
+Pick `movie-research-demo.form.md` for a quick demo.
+
+**2. Agent-guided tour** — ask a coding agent (like Claude Code) to walk you through a
+specific example step by step.
+The agent copies the form, explains the structure, fills fields, validates, and exports:
+
+```bash
+# List available examples
+markform examples --list
+# Copy one to work with
+markform examples --name movie-research-demo
+```
 
+**3. End-to-end walkthrough** — have a coding agent follow the
+[demo playbook](packages/markform/examples/markform-demo-playbook.md) to design a
+research form from scratch, fill it with real data, validate, export, and browse.
+This is the most thorough tour of all Markform features.
+
+```bash
 # Read the docs (tell your agents to run these; they are agent-friendly!)
 npx markform  # CLI help
 npx markform readme   # This file
@@ -314,10 +340,6 @@ npx markform docs  # Quick reference for writing Markforms
 npx markform spec  # Read the full spec
 ```
 
-The `markform examples` command copies some sample forms to `./forms` and prompts you to
-fill in a form interactively and then optionally have an agent complete it.
-Pick `movie-research-demo.form.md` for a quick example.
-
 ## Installation
 
 Requires Node.js 20+.
@@ -330,6 +352,24 @@ 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.
@@ -414,7 +454,7 @@ flowchart LR
         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<br/>(.session.yaml transcripts)"]
+        subgraph PARSER["<b>PARSER</b><br/>Markform language<br/>parser/serializer"]
         end
 
         CLI --> ENGINE
@@ -422,7 +462,7 @@ flowchart LR
         AGENT --> HARNESS
         AGENT --> ENGINE
         HARNESS --> ENGINE
-        ENGINE --> TEST
+        ENGINE --> PARSER
     end
 
     SPEC ~~~ IMPL
@@ -437,7 +477,7 @@ flowchart LR
     style CLI fill:#ffe8cc,stroke:#fb8500
     style AGENT fill:#ffe8cc,stroke:#fb8500
     style HARNESS fill:#ffe8cc,stroke:#fb8500
-    style TEST fill:#ffe8cc,stroke:#fb8500
+    style PARSER fill:#ffe8cc,stroke:#fb8500
 ```
 
 ## CLI Commands
@@ -571,8 +611,8 @@ If unsure, try `gpt-5-mini` first as it’s fast and supports web search.
 
 ## Programmatic Usage
 
-Markform exports a parsing engine, rendering functions, and AI SDK integration for use in
-your own applications.
+Markform exports a parsing engine, rendering functions, and AI SDK integration for use
+in your own applications.
 
 ### Basic Parsing
 

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-CxpqKpBA.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-KzQztrDV.mjs";
+import { R as PatchSchema } from "./coreTypes-DIv9Aabl.mjs";
+import { _ as inspect, m as applyPatches, p as findFieldById, s as getPatchFormatHint, u as getFieldIdFromRef, w as serializeForm } from "./prompts-DaPKumGY.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-ZcOC47KK.mjs";
+import { t as runCli } from "./cli-B1T8kMFt.mjs";
 import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { config } from "dotenv";