markform 0.1.8 → 0.1.10

package/README.md

@@ -1,5 +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)
+
 **Markform** is a text format for defining structured forms that humans can read,
 machines can parse, and agents can fill via tool calls.
 
@@ -113,21 +117,23 @@ 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
+````jinja
 {% 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 %}
+- [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
 user, or a `role="agent"` to indicate an agent should fill them in.
@@ -283,7 +289,10 @@ Enter the movie title (add year or details for disambiguation).
 {% /field %}
 
 {% instructions ref="ratings_table" %}
-Fill in scores and vote counts from each source:IMDB: Rating (1.0-10.0 scale), vote countRT Critics: Tomatometer (0-100%), review countRT Audience: Audience Score (0-100%), rating count
+Fill in scores and vote counts from each source:
+- IMDB: Rating (1.0-10.0 scale), vote count
+- RT Critics: Tomatometer (0-100%), review count
+- RT Audience: Audience Score (0-100%), rating count
 {% /instructions %}
 
 {% /group %}
@@ -371,14 +380,37 @@ View them with `markform examples --list`, copy with `markform examples`, and ru
 - [`movie-research-demo.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-demo.form.md)
   \- The quick example above.
 
-- [`movie-research-basic.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-basic.form.md)
-  \- Standard movie research with IMDB, Rotten Tomatoes, Metacritic.
+- [`movie-deep-research.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-deep-research.form.md)
+  \- Comprehensive movie analysis with streaming, box office, technical specs.
 
-- [`movie-research-deep.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-deep.form.md)
-  \- Comprehensive movie analysis with streaming, box office, analysis.
+### Why a New Format?
+
+The closest alternatives I’ve seen are:
+
+- Plain Markdown docs can be used as templates and filled in by agents.
+  These are more expressive, but it is hard to edit them programmatically or use LLMs to
+  update them reliably.
+
+- JSON + JSON Schema which are good for struture but terrible for additional
+  unstructured context like instructions Markdown.
+
+- Agent to-do lists are part of many chat or coding interfaces and are programmatically
+  edited by agents. But these are limited to simple checklists, not forms with other
+  fields.
+
+- Numerous tools like Typeform, Google Forms, PDF forms, and Docusign offer
+  human-friendly UI. But these do not have a human-friendly text format for use by
+  agents as well as humans.
+
+| Approach | Usable GUI editor | Human-readable source format | Agent-editable | APIs and validation rules |
+| --- | :---: | :---: | :---: | :---: |
+| Plain Markdown | ✅<br>IDEs/editors | ✅ | ⚠️<br>fragile | ❌ |
+| JSON + JSON Schema | ✅<br>IDEs/editors | ⚠️<br>no free text | ✅ | ✅ |
+| SaaS tools (Typeform, Docusign, PDF forms) | ✅ | ⚠️<br>rarely | ⚠️<br>sometimes | ⚠️<br>sometimes |
+| HTML/web Forms | ✅<br>IDEs/editors | ⚠️<br>HTML+code | ⚠️<br>coding agent | ✅ |
+| Excel/Google Sheets | ✅<br>app | ❌<br>.csv/.xlsx | ⚠️<br>with tools | ✅<br>with some coding |
+| **Markform** | ✅<br>IDEs/editors | ✅ | ✅<br>with this package | ✅<br>with this package |
 
-- [`earnings-analysis.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/earnings-analysis/earnings-analysis.form.md)
-  \- Financial analysis form.
 ## Architecture
 
 This repo has a specification and an implementation.
@@ -453,10 +485,8 @@ flowchart LR
 ```bash
 # Copy all bundled examples to ./forms/
 markform examples
-
 # List available examples
 markform examples --list
-
 # Copy a specific example
 markform examples --name movie-research-demo
 ```
@@ -466,7 +496,6 @@ markform examples --name movie-research-demo
 ```bash
 # Browse forms in ./forms/ and run one interactively
 markform run
-
 # Run a specific form directly
 markform run forms/movie-research-demo.form.md
 ```
@@ -483,7 +512,6 @@ markform status my-form.form.md
 ```bash
 # View form structure, progress, and validation issues
 markform inspect my-form.form.md
-
 # Output as JSON
 markform inspect my-form.form.md --format=json
 ```
@@ -493,10 +521,8 @@ markform inspect my-form.form.md --format=json
 ```bash
 # Interactive mode: fill user-role fields via prompts
 markform fill my-form.form.md --interactive
-
 # Agent mode: use an LLM to fill agent-role fields
 markform fill my-form.form.md --model=anthropic/claude-sonnet-4-5
-
 # Mock agent for testing (uses pre-filled form as source)
 markform fill my-form.form.md --mock --mock-source filled.form.md
 ```
@@ -506,13 +532,10 @@ markform fill my-form.form.md --mock --mock-source filled.form.md
 ```bash
 # Export as readable markdown (strips Markdoc tags)
 markform export my-form.form.md --format=markdown
-
 # Export values as JSON
 markform export my-form.form.md --format=json
-
 # Export values as YAML
 markform export my-form.form.md --format=yaml
-
 # Dump just the current values
 markform dump my-form.form.md
 ```
@@ -522,10 +545,8 @@ markform dump my-form.form.md
 ```bash
 # Export form structure as JSON Schema (for validation, code generation, etc.)
 markform schema my-form.form.md
-
 # Pure JSON Schema without Markform extensions
 markform schema my-form.form.md --pure
-
 # Specify JSON Schema draft version
 markform schema my-form.form.md --draft draft-07
 ```
@@ -549,19 +570,14 @@ markform serve my-form.form.md
 ```bash
 # Quick reference for writing forms (agent-friendly)
 markform docs
-
 # Full specification
 markform spec
-
 # TypeScript and AI SDK API documentation
 markform apis
-
 # This README
 markform readme
-
 # See supported AI providers and example models
 markform models
-
 # See all commands
 markform --help
 ```
@@ -594,17 +610,17 @@ applications.
 ### Basic Parsing
 
 ```typescript
-import { parseForm, serializeForm } from "markform";
+import { parseForm, serialize } from "markform";
 
 // Parse a .form.md file
 const form = parseForm(markdownContent);
 
 // Access schema and values
 console.log(form.schema.title);
-console.log(form.values);
+console.log(form.responsesByFieldId);
 
 // Serialize back to markdown
-const output = serializeForm(form);
+const output = serialize(form);
 ```
 
 ### AI SDK Integration
@@ -763,32 +779,6 @@ This enables powerful AI workflows that assemble information in a defined struct
 - An **agent execution harness** for step-by-step form filling, enabling deep research
   agents that assemble validated output in a structured format.
 
-### Does anything like this already exist?
-
-Not that I have seen.
-The closest alternatives are:
-
-- Plain Markdown docs can be used as templates and filled in by agents.
-  These are more expressive, but it is hard to edit them programmatically or use LLMs to
-  update them reliably.
-
-- Agent to-do lists are part of many chat or coding interfaces and are programmatically
-  edited by agents. But these are limited to simple checklists, not forms with other
-  fields.
-
-- Numerous tools like Typeform, Google Forms, PDF forms, and Docusign offer
-  human-friendly UI. But these do not have a human-friendly text format for use by
-  agents as well as humans.
-
-| Approach | Usable GUI editor | Human-readable source format | Agent-editable | APIs and validation rules |
-| --- | :---: | :---: | :---: | :---: |
-| Plain Markdown | ✅ IDEs/editors | ✅ | ⚠️ fragile | ❌ |
-| JSON + JSON Schema | ✅ IDEs/editors | ⚠️ no free text | ✅ | ✅ |
-| SaaS tools (Typeform, Docusign, PDF forms) | ✅ | ⚠️ rarely | ⚠️ sometimes | ⚠️ sometimes |
-| HTML/web Forms | ✅ IDEs/editors | ⚠️ HTML+code | ⚠️ coding agent | ✅ |
-| Excel/Google Sheets | ✅ app | ❌ .csv/.xlsx | ⚠️ with tools | ✅ with some coding |
-| **Markform** | ✅ IDEs/editors | ✅ | ✅ with this package | ✅ with this package |
-
 ### What are example use cases?
 
 - Deep research tools where agents need to follow codified processes to assemble

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-BSPJ9H27.mjs";
+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-JCPm418M.mjs";
 import { z } from "zod";
 
 //#region src/integrations/toolTypes.d.ts

package/dist/ai-sdk.mjs

@@ -1,6 +1,6 @@
 
-import { L as PatchSchema } from "./coreTypes-DJtu8OOp.mjs";
-import { d as serialize, i as inspect, t as applyPatches } from "./apply-BUU2QcJ2.mjs";
+import { L as PatchSchema } from "./coreTypes-B1oI7qvV.mjs";
+import { d as serialize, i as inspect, t as applyPatches } from "./apply-BTFCHpYV.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts