markform 0.1.14 → 0.1.16

package/README.md

@@ -1,8 +1,9 @@
 # Markform
 
-[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/workflows/ci.yml)
-![Coverage](./badges/packages/markform/coverage-total.svg) [![X (formerly Twitter)
-Follow](https://img.shields.io/twitter/follow/ojoshe)](https://x.com/ojoshe)
+[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21077282678)
+[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21077282678)
+[![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)
 
 **Markform** is a text format for defining structured forms that humans can read,
 machines can parse, and agents can fill via tool calls.
@@ -33,8 +34,8 @@ in one place.
 
 Markform syntax is a good source format: token-efficient text you can read, diff, and
 version control.
-It is built with [Markdoc](https://github.com/markdoc/markdoc), which is
-a Markdown extension from Stripe with Jinja-style `{% tag %}` annotations.
+Structure is defined with HTML comment tags (`<!-- field -->`) that render invisibly
+on GitHub, so forms look like regular Markdown.
 
 ## Why Do Agents Need Forms?
 
@@ -53,8 +54,8 @@ or dependent on model whims (changes unpredictably with model updates).
 
 Forms solve this. Forms codify operational excellence.
 They’re easy to read, easy to edit, and enforce standards.
-Because LLMs handle Markdown and Jinja-style tags well, agents can also help create and
-improve the forms themselves—closing the meta-loop.
+Because LLMs handle Markdown well, agents can also help create and improve the forms
+themselves—closing the meta-loop.
 
 It’s time to bring bureaucracy to the agents!
 See [the FAQ](#faq) for more on the design.
@@ -93,46 +94,44 @@ npm install markform
 
 ### Form Definition
 
-A `.form.md` file is simply a Markdoc file.
-It combines YAML frontmatter with Markdoc-tagged content.
-
+A `.form.md` file combines YAML frontmatter with HTML comment tags that define structure.
 The text can be any Markdown.
 The tags define things like fields:
 
-```jinja
-{% field kind="string" id="movie" label="Movie" role="user"
-   required=true minLength=1 maxLength=300 %}{% /field %}
-
-{% field kind="single_select" id="mpaa_rating" role="agent" label="MPAA Rating" %}
-- [ ] G {% #g %}
-- [ ] PG {% #pg %}
-- [ ] PG-13 {% #pg_13 %}
-- [ ] R {% #r %}
-- [ ] NC-17 {% #nc_17 %}
-- [ ] NR/Unrated {% #nr %}
-{% /field %}
+```markdown
+<!-- field kind="string" id="movie" label="Movie" role="user"
+   required=true minLength=1 maxLength=300 --><!-- /field -->
+
+<!-- field kind="single_select" id="mpaa_rating" role="agent" label="MPAA Rating" -->
+- [ ] G <!-- #g -->
+- [ ] PG <!-- #pg -->
+- [ ] PG-13 <!-- #pg_13 -->
+- [ ] R <!-- #r -->
+- [ ] NC-17 <!-- #nc_17 -->
+- [ ] NR/Unrated <!-- #nr -->
+<!-- /field -->
 ```
 
 Fields have types defined by the attributes.
 Values are filled in incrementally, just like any form.
 Once filled in, values appear directly inside the tags, in Markdown format:
 
-````jinja
-{% field kind="string" id="movie" label="Movie" role="user"
-   required=true minLength=1 maxLength=300 %}
+````markdown
+<!-- field kind="string" id="movie" label="Movie" role="user"
+   required=true minLength=1 maxLength=300 -->
 ```value
 The Shawshank Redemption
 ```
-{% /field %}
-
-{% field kind="single_select" id="mpaa_rating" role="agent" label="MPAA Rating" %}
-- [ ] G {% #g %}
-- [ ] PG {% #pg %}
-- [ ] PG-13 {% #pg_13 %}
-- [x] R {% #r %}
-- [ ] NC-17 {% #nc_17 %}
-- [ ] NR/Unrated {% #nr %}
-{% /field %}
+<!-- /field -->
+
+<!-- field kind="single_select" id="mpaa_rating" role="agent" label="MPAA Rating" -->
+- [ ] G <!-- #g -->
+- [ ] PG <!-- #pg -->
+- [ ] PG-13 <!-- #pg_13 -->
+- [x] R <!-- #r -->
+- [ ] NC-17 <!-- #nc_17 -->
+- [ ] NR/Unrated <!-- #nr -->
+<!-- /field -->
 ````
 
 Note fields can have a `role="user"` to indicate they are filled interactively by the
@@ -144,13 +143,13 @@ grouping of forms.
 Checkboxes and tables as values are supported!
 Checkboxes can be single-select or multi-select.
 
-Here’s a full example:
+Here's a full example (using the alternative Markdoc tag syntax, which also works):
 
 <details>
 
 <summary>Markform for Movie Research Demo (click to expand)</summary>
 
-```jinja
+```markdown
 ---
 markform:
   spec: MF/0.1
@@ -821,8 +820,18 @@ Or see [markdoc/language-server](https://github.com/markdoc/language-server).
 
 ## License
 
-AGPL-3.0-or-later. [Contact me](https://github.com/jlevy) for additional licensing
-options.
+This project uses a dual licensing approach:
+
+- **Markform Specification** ([`docs/markform-spec.md`](docs/markform-spec.md),
+  [`docs/markform-reference.md`](docs/markform-reference.md)):
+  [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).
+  You may freely implement this specification in your own software under any license.
+
+- **Reference Implementation** (all code in this repository):
+  [AGPL-3.0-or-later](./LICENSE).
+  [Contact me](https://github.com/jlevy) for commercial licensing options.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution terms.
 
 [markdoc-overview]: https://markdoc.dev/docs/overview
 [stripe-markdoc]: https://stripe.com/blog/markdoc

package/dist/ai-sdk.d.mts

@@ -1,5 +1,5 @@
 
-import { At as PatchSchema, Dt as ParsedForm, Ot as Patch, Q as Id, V as FieldResponse, dr as ValidatorRegistry, q as FormSchema, r as ApplyResult, rt as InspectResult } from "./coreTypes-CnKsB1H3.mjs";
+import { At as PatchSchema, Dt as ParsedForm, Ot as Patch, Q as Id, V as FieldResponse, fr as ValidatorRegistry, q as FormSchema, r as ApplyResult, rt as InspectResult } from "./coreTypes-DE6Giau5.mjs";
 import { z } from "zod";
 
 //#region src/integrations/toolTypes.d.ts
@@ -126,4 +126,5 @@ interface CreateMarkformToolsOptions {
  */
 declare function createMarkformTools(options: CreateMarkformToolsOptions): MarkformToolSet;
 //#endregion
-export { type ApplyToolResult, CreateMarkformToolsOptions, type ExportToolResult, type GetMarkdownToolResult, type InspectToolResult, MarkformSessionStore, type MarkformTool, type MarkformToolSet, PatchSchema, createMarkformTools };
+export { type ApplyToolResult, CreateMarkformToolsOptions, type ExportToolResult, type GetMarkdownToolResult, type InspectToolResult, MarkformSessionStore, type MarkformTool, type MarkformToolSet, PatchSchema, createMarkformTools };
+//# sourceMappingURL=ai-sdk.d.mts.map

package/dist/ai-sdk.mjs

@@ -1,6 +1,6 @@
 
 import { L as PatchSchema } from "./coreTypes-DiCddBKu.mjs";
-import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-CUH_16RD.mjs";
+import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-CXsI5N9x.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts
@@ -165,4 +165,5 @@ function createMarkformTools(options) {
 }
 
 //#endregion
-export { MarkformSessionStore, PatchSchema, createMarkformTools };
+export { MarkformSessionStore, PatchSchema, createMarkformTools };
+//# sourceMappingURL=ai-sdk.mjs.map

package/dist/ai-sdk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.mjs","names":["toolset: MarkformToolSet"],"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,MAAMA,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"}