markform 0.1.3 → 0.1.5

package/docs/markform-apis.md

@@ -0,0 +1,194 @@
+# Markform APIs
+
+Markform provides TypeScript APIs for parsing, validating, and manipulating forms
+programmatically.
+
+## CLI
+
+The `markform` CLI is self-documenting:
+
+```bash
+markform --help              # List all commands
+markform <command> --help    # Help for specific command
+markform docs                # Form syntax quick reference
+markform spec                # Full specification
+markform apis                # This document
+```
+
+**Form syntax:** See [markform-reference.md](markform-reference.md) for the quick
+reference on form syntax, field kinds, and attributes.
+
+## Project Installation
+
+```bash
+npm install markform
+```
+
+## Core Engine API
+
+Import from the main package:
+
+```typescript
+import {
+  parseForm,
+  serialize,
+  validate,
+  inspect,
+  applyPatches,
+} from 'markform';
+```
+
+### parseForm(content: string): ParsedForm
+
+Parse a `.form.md` file into a structured form object.
+
+### serialize(form: ParsedForm, options?: SerializeOptions): string
+
+Convert a parsed form back to Markdown.
+
+### validate(form: ParsedForm, options?: ValidateOptions): ValidateResult
+
+Validate form syntax and constraints.
+
+### inspect(form: ParsedForm, options?: InspectOptions): InspectResult
+
+Get form state including structure, progress, and validation issues.
+
+### applyPatches(form: ParsedForm, patches: Patch[]): ApplyResult
+
+Apply value changes to a form.
+Modifies the form in place.
+
+## Vercel AI SDK Integration
+
+Import from the ai-sdk subpath:
+
+```typescript
+import {
+  createMarkformTools,
+  MarkformSessionStore
+} from 'markform/ai-sdk';
+```
+
+### MarkformSessionStore
+
+Session store for managing form state during AI interactions.
+
+```typescript
+const store = new MarkformSessionStore(parsedForm);
+```
+
+### createMarkformTools(options): MarkformToolSet
+
+Create AI SDK compatible tools for agent-driven form filling.
+
+```typescript
+import { generateText } from 'ai';
+
+const tools = createMarkformTools({ sessionStore: store });
+const { text } = await generateText({
+  model: yourModel,
+  tools,
+  prompt: 'Fill out this form...',
+});
+```
+
+**Available tools:**
+
+| Tool | Description |
+| --- | --- |
+| `markform_inspect` | Get form state, structure, progress, issues |
+| `markform_apply` | Apply patches to update field values |
+| `markform_export` | Export schema and values as JSON |
+| `markform_get_markdown` | Get canonical Markdown representation |
+
+See [vercelAiSdkTools.ts](../packages/markform/src/integrations/vercelAiSdkTools.ts) for
+full details.
+
+### Patch Operations
+
+Use `markform_apply` with an array of patches.
+Each patch has an `op` and `fieldId`.
+
+| Operation | Fields | Value Format |
+| --- | --- | --- |
+| `set_string` | string | `{ "op": "set_string", "fieldId": "name", "value": "Alice" }` |
+| `set_number` | number | `{ "op": "set_number", "fieldId": "age", "value": 25 }` |
+| `set_string_list` | string_list | `{ "op": "set_string_list", "fieldId": "tags", "items": ["a", "b"] }` |
+| `set_single_select` | single_select | `{ "op": "set_single_select", "fieldId": "rating", "selected": "high" }` |
+| `set_multi_select` | multi_select | `{ "op": "set_multi_select", "fieldId": "cats", "selected": ["a", "b"] }` |
+| `set_checkboxes` | checkboxes | `{ "op": "set_checkboxes", "fieldId": "tasks", "values": {"item1": "done"} }` |
+| `set_url` | url | `{ "op": "set_url", "fieldId": "website", "value": "https://..." }` |
+| `set_url_list` | url_list | `{ "op": "set_url_list", "fieldId": "sources", "items": ["https://..."] }` |
+| `set_date` | date | `{ "op": "set_date", "fieldId": "deadline", "value": "2024-06-15" }` |
+| `set_year` | year | `{ "op": "set_year", "fieldId": "founded", "value": 2015 }` |
+| `clear_field` | any | `{ "op": "clear_field", "fieldId": "name" }` |
+| `skip_field` | optional | `{ "op": "skip_field", "fieldId": "notes", "reason": "Not applicable" }` |
+| `abort_field` | any | `{ "op": "abort_field", "fieldId": "data", "reason": "Unable to find" }` |
+
+### Checkbox Values
+
+For `set_checkboxes`, values depend on the checkbox mode:
+
+- **multi** (default): `todo`, `done`, `incomplete`, `active`, `na`
+
+- **simple**: `todo`, `done`
+
+- **explicit**: `unfilled`, `yes`, `no`
+
+## Form Harness API
+
+The harness manages step-by-step form filling sessions.
+
+```typescript
+import { FormHarness, createHarness, fillForm } from 'markform';
+```
+
+### fillForm(options: FillOptions): Promise<FillResult>
+
+High-level API for filling a form with an AI model.
+
+```typescript
+const result = await fillForm({
+  form: parsedForm,
+  model: 'anthropic/claude-sonnet-4-5',
+  roles: ['agent'],
+});
+```
+
+### createHarness(form, config?): FormHarness
+
+Create a harness for manual control over the fill loop.
+
+See [harness.ts](../packages/markform/src/harness/harness.ts) for full details.
+
+## Research API
+
+For research-type forms that run extended data gathering sessions.
+
+```typescript
+import { runResearch, isResearchForm } from 'markform';
+```
+
+### runResearch(options: ResearchOptions): Promise<ResearchResult>
+
+Run a research session on a research-type form.
+
+See [runResearch.ts](../packages/markform/src/research/runResearch.ts) for full details.
+
+## Type Exports
+
+All Zod schemas and TypeScript types are exported from the main package:
+
+```typescript
+import type {
+  ParsedForm,
+  Field,
+  FieldValue,
+  Patch,
+  InspectResult,
+  // ... many more
+} from 'markform';
+```
+
+See [src/index.ts](../packages/markform/src/index.ts) for the complete list of exports.

package/{DOCS.md → docs/markform-reference.md}

@@ -7,8 +7,8 @@ Files combine YAML frontmatter with [Markdoc](https://markdoc.dev/) tags to defi
 typed, validated fields.
 
 **More info:** [Project README](https://github.com/jlevy/markform) |
-[Full Specification](https://github.com/jlevy/markform/blob/main/SPEC.md) (`markform
-spec`)
+[Full Specification](markform-spec.md) (`markform spec`) |
+[API Documentation](markform-apis.md) (`markform apis`)
 
 ## Installation
 
@@ -39,11 +39,11 @@ markform:
 
 {% form id="form_id" title="Form Title" %}
 
-{% field-group id="group_id" title="Group Title" %}
+{% group id="group_id" title="Group Title" %}
 
 <!-- fields go here -->
 
-{% /field-group %}
+{% /group %}
 
 {% /form %}
 ```
@@ -53,20 +53,24 @@ markform:
 Use `.form.md` for Markform files.
 They are Markdoc syntax, which is a superset of Markdown.
 
-## Field Types
+## Field Kinds
+
+Markform uses the term **field kind** to refer to the type of a field (e.g., `string`,
+`number`, `checkboxes`). The term **data type** refers to the underlying value
+representation. See the Type System section in SPEC.md for full details.
 
 ### String Field
 
 Single-line or multi-line text.
 
 ````markdown
-{% string-field id="name" label="Name" required=true minLength=2 maxLength=100 %}{% /string-field %}
+{% field kind="string" id="name" label="Name" required=true minLength=2 maxLength=100 %}{% /field %}
 
-{% string-field id="bio" label="Biography" pattern="^[A-Z].*" %}
+{% field kind="string" id="bio" label="Biography" pattern="^[A-Z].*" %}
 ```value
 Existing value here
 ````
-{% /string-field %}
+{% /field %}
 ````
 
 | Attribute | Type | Description |
@@ -80,13 +84,13 @@ Existing value here
 Numeric values with optional constraints.
 
 ```markdown
-{% number-field id="age" label="Age" required=true min=0 max=150 integer=true %}{% /number-field %}
+{% field kind="number" id="age" label="Age" required=true min=0 max=150 integer=true %}{% /field %}
 
-{% number-field id="price" label="Price" min=0.01 max=999999.99 %}
+{% field kind="number" id="price" label="Price" min=0.01 max=999999.99 %}
 ```value
 49.99
 ````
-{% /number-field %}
+{% /field %}
 ````
 
 | Attribute | Type | Description |
@@ -100,15 +104,15 @@ Numeric values with optional constraints.
 Array of strings, one per line.
 
 ```markdown
-{% string-list id="tags" label="Tags" required=true minItems=1 maxItems=10 uniqueItems=true %}{% /string-list %}
+{% field kind="string_list" id="tags" label="Tags" required=true minItems=1 maxItems=10 uniqueItems=true %}{% /field %}
 
-{% string-list id="features" label="Key Features" minItems=3 itemMinLength=10 %}
+{% field kind="string_list" id="features" label="Key Features" minItems=3 itemMinLength=10 %}
 ```value
 Feature one description
 Feature two description
 Feature three description
 ````
-{% /string-list %}
+{% /field %}
 ````
 
 | Attribute | Type | Description |
@@ -124,11 +128,11 @@ Feature three description
 Choose exactly one option.
 
 ```markdown
-{% single-select id="rating" label="Rating" required=true %}
+{% field kind="single_select" id="rating" label="Rating" required=true %}
 - [ ] Low {% #low %}
 - [ ] Medium {% #medium %}
 - [x] High {% #high %}
-{% /single-select %}
+{% /field %}
 ````
 
 Options use `[ ]` (unselected) or `[x]` (selected).
@@ -139,12 +143,12 @@ Each option needs `{% #id %}`.
 Choose multiple options.
 
 ```markdown
-{% multi-select id="categories" label="Categories" required=true minSelections=1 maxSelections=3 %}
+{% field kind="multi_select" id="categories" label="Categories" required=true minSelections=1 maxSelections=3 %}
 - [x] Frontend {% #frontend %}
 - [x] Backend {% #backend %}
 - [ ] Database {% #database %}
 - [ ] DevOps {% #devops %}
-{% /multi-select %}
+{% /field %}
 ```
 
 | Attribute | Type | Description |
@@ -159,13 +163,13 @@ Stateful checklists with three modes.
 **Multi Mode** (default) - 5 states for workflow tracking:
 
 ```markdown
-{% checkboxes id="tasks" label="Tasks" required=true checkboxMode="multi" %}
+{% field kind="checkboxes" id="tasks" label="Tasks" required=true checkboxMode="multi" %}
 - [ ] Research {% #research %}
 - [x] Design {% #design %}
 - [/] Implementation {% #impl %}
 - [*] Testing {% #test %}
 - [-] N/A item {% #na %}
-{% /checkboxes %}
+{% /field %}
 ```
 
 | Token | State | Meaning |
@@ -179,20 +183,20 @@ Stateful checklists with three modes.
 **Simple Mode** - 2 states (GFM compatible):
 
 ```markdown
-{% checkboxes id="agreements" label="Agreements" checkboxMode="simple" required=true %}
+{% field kind="checkboxes" id="agreements" label="Agreements" checkboxMode="simple" required=true %}
 - [x] I agree to terms {% #terms %}
 - [ ] Subscribe to newsletter {% #news %}
-{% /checkboxes %}
+{% /field %}
 ```
 
 **Explicit Mode** - Requires yes/no for each:
 
 ```markdown
-{% checkboxes id="confirmations" label="Confirmations" checkboxMode="explicit" required=true %}
+{% field kind="checkboxes" id="confirmations" label="Confirmations" checkboxMode="explicit" required=true %}
 - [y] Backup completed {% #backup %}
 - [n] Stakeholders notified {% #notify %}
 - [ ] Deployment ready {% #deploy %}
-{% /checkboxes %}
+{% /field %}
 ```
 
 | Token | Value | Meaning |
@@ -206,13 +210,13 @@ Stateful checklists with three modes.
 Single URL with format validation.
 
 ````markdown
-{% url-field id="website" label="Website" required=true %}{% /url-field %}
+{% field kind="url" id="website" label="Website" required=true %}{% /field %}
 
-{% url-field id="repo" label="Repository" %}
+{% field kind="url" id="repo" label="Repository" %}
 ```value
 https://github.com/example/repo
 ````
-{% /url-field %}
+{% /field %}
 ````
 
 ### URL List
@@ -220,14 +224,52 @@ https://github.com/example/repo
 Array of URLs.
 
 ```markdown
-{% url-list id="sources" label="Sources" required=true minItems=1 maxItems=10 uniqueItems=true %}
+{% field kind="url_list" id="sources" label="Sources" required=true minItems=1 maxItems=10 uniqueItems=true %}
 ```value
 https://example.com/source1
 https://example.com/source2
 ````
-{% /url-list %}
+{% /field %}
+`````
+
+### Date Field
+
+Date value in ISO 8601 format (YYYY-MM-DD).
+
+````markdown
+{% field kind="date" id="deadline" label="Deadline" required=true %}{% /field %}
+
+{% field kind="date" id="start_date" label="Start Date" min="2020-01-01" max="2030-12-31" %}
+```value
+2024-06-15
+`````
+{% /field %}
+`````
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `min` | string | Minimum date (ISO 8601: YYYY-MM-DD) |
+| `max` | string | Maximum date (ISO 8601: YYYY-MM-DD) |
+
+### Year Field
+
+Integer year with optional constraints.
+
+````markdown
+{% field kind="year" id="release_year" label="Release Year" required=true min=1888 max=2030 %}{% /field %}
+
+{% field kind="year" id="founded" label="Year Founded" %}
+```value
+2015
+`````
+{% /field %}
 ````
 
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `min` | number | Minimum year (inclusive) |
+| `max` | number | Maximum year (inclusive) |
+
 ## Common Attributes
 
 All fields support these attributes:
@@ -240,6 +282,20 @@ All fields support these attributes:
 | `role` | string | - | Target actor (`user`, `agent`) |
 | `priority` | string | medium | `high`, `medium`, `low` |
 
+**Text-entry fields only** (string, number, string-list, url, url-list):
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `placeholder` | string | Hint text shown in empty fields |
+| `examples` | string[] | Example values (helps LLMs understand expected format) |
+
+```markdown
+{% field kind="string" id="name" label="Name" placeholder="Enter your name" examples=["John Doe", "Jane Smith"] %}{% /field %}
+{% field kind="number" id="revenue" label="Revenue" placeholder="1000000" examples=["500000", "1000000"] %}{% /field %}
+```
+
+Note: `placeholder` and `examples` are NOT valid on chooser fields (single-select, multi-select, checkboxes).
+
 ## Documentation Blocks
 
 Add context to fields, groups, or the form.
@@ -283,8 +339,8 @@ roles:
 ```
 
 ```markdown
-{% string-field id="query" label="Search Query" role="user" %}{% /string-field %}
-{% string-field id="summary" label="AI Summary" role="agent" %}{% /string-field %}
+{% field kind="string" id="query" label="Search Query" role="user" %}{% /field %}
+{% field kind="string" id="summary" label="AI Summary" role="agent" %}{% /field %}
 ```
 
 ## Value Encoding
@@ -292,17 +348,17 @@ roles:
 Values use fenced code blocks with language `value`:
 
 ````markdown
-{% string-field id="name" label="Name" %}
+{% field kind="string" id="name" label="Name" %}
 ```value
 John Smith
 ````
-{% /string-field %}
+{% /field %}
 ````
 
 Empty fields omit the value block entirely:
 
 ```markdown
-{% string-field id="name" label="Name" %}{% /string-field %}
+{% field kind="string" id="name" label="Name" %}{% /field %}
 ````
 
 ## Complete Example
@@ -343,124 +399,124 @@ A focused research form for gathering ratings and key statistics for any film.
 Pulls from IMDB, Rotten Tomatoes, and Metacritic.
 {% /description %}
 
-{% field-group id="movie_input" title="Movie Identification" %}
+{% group id="movie_input" title="Movie Identification" %}
 
-{% string-field id="movie" label="Movie" role="user" required=true minLength=1 maxLength=300 %}{% /string-field %}
+{% field kind="string" id="movie" label="Movie" role="user" required=true minLength=1 maxLength=300 %}{% /field %}
 
 {% instructions ref="movie" %}
 Enter the movie title (add any details to help identify, like "Barbie 2023" or "the Batman movie with Robert Pattinson")
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="title_identification" title="Title Identification" %}
+{% group id="title_identification" title="Title Identification" %}
 
-{% string-field id="full_title" label="Full Title" role="agent" required=true %}{% /string-field %}
+{% field kind="string" id="full_title" label="Full Title" role="agent" required=true %}{% /field %}
 
 {% instructions ref="full_title" %}
 Look up what film the user had in mind and fill in the official title including subtitle if any (e.g., "The Lord of the Rings: The Fellowship of the Ring").
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="sources" title="Sources" %}
+{% group id="sources" title="Sources" %}
 
-{% url-field id="imdb_url" label="IMDB URL" role="agent" required=true %}{% /url-field %}
+{% field kind="url" id="imdb_url" label="IMDB URL" role="agent" required=true %}{% /field %}
 
 {% instructions ref="imdb_url" %}
 Direct link to the movie's IMDB page (e.g., https://www.imdb.com/title/tt0111161/).
 {% /instructions %}
 
-{% url-field id="rt_url" label="Rotten Tomatoes URL" role="agent" %}{% /url-field %}
+{% field kind="url" id="rt_url" label="Rotten Tomatoes URL" role="agent" %}{% /field %}
 
 {% instructions ref="rt_url" %}
 Direct link to the movie's Rotten Tomatoes page.
 {% /instructions %}
 
-{% url-field id="metacritic_url" label="Metacritic URL" role="agent" %}{% /url-field %}
+{% field kind="url" id="metacritic_url" label="Metacritic URL" role="agent" %}{% /field %}
 
 {% instructions ref="metacritic_url" %}
 Direct link to the movie's Metacritic page.
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="basic_details" title="Basic Details" %}
+{% group id="basic_details" title="Basic Details" %}
 
-{% number-field id="year" label="Release Year" role="agent" required=true min=1888 max=2030 %}{% /number-field %}
+{% field kind="number" id="year" label="Release Year" role="agent" required=true min=1888 max=2030 %}{% /field %}
 
-{% string-list id="directors" label="Director(s)" role="agent" required=true %}{% /string-list %}
+{% field kind="string_list" id="directors" label="Director(s)" role="agent" required=true %}{% /field %}
 
 {% instructions ref="directors" %}
 One director per line. Most films have one; some have two or more co-directors.
 {% /instructions %}
 
-{% number-field id="runtime_minutes" label="Runtime (minutes)" role="agent" min=1 max=1000 %}{% /number-field %}
+{% field kind="number" id="runtime_minutes" label="Runtime (minutes)" role="agent" min=1 max=1000 %}{% /field %}
 
-{% single-select id="mpaa_rating" label="MPAA Rating" role="agent" %}
+{% field kind="single_select" id="mpaa_rating" label="MPAA Rating" role="agent" %}
 - [ ] G {% #g %}
 - [ ] PG {% #pg %}
 - [ ] PG-13 {% #pg_13 %}
 - [ ] R {% #r %}
 - [ ] NC-17 {% #nc_17 %}
 - [ ] NR/Unrated {% #nr %}
-{% /single-select %}
+{% /field %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="imdb_ratings" title="IMDB Ratings" %}
+{% group id="imdb_ratings" title="IMDB Ratings" %}
 
-{% number-field id="imdb_rating" label="IMDB Rating" role="agent" min=1.0 max=10.0 %}{% /number-field %}
+{% field kind="number" id="imdb_rating" label="IMDB Rating" role="agent" min=1.0 max=10.0 %}{% /field %}
 
 {% instructions ref="imdb_rating" %}
 IMDB user rating (1.0-10.0 scale).
 {% /instructions %}
 
-{% number-field id="imdb_votes" label="IMDB Vote Count" role="agent" min=0 %}{% /number-field %}
+{% field kind="number" id="imdb_votes" label="IMDB Vote Count" role="agent" min=0 %}{% /field %}
 
 {% instructions ref="imdb_votes" %}
 Number of IMDB user votes (e.g., 2800000 for a popular film).
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="rotten_tomatoes_ratings" title="Rotten Tomatoes Ratings" %}
+{% group id="rotten_tomatoes_ratings" title="Rotten Tomatoes Ratings" %}
 
-{% number-field id="rt_critics_score" label="Tomatometer (Critics)" role="agent" min=0 max=100 %}{% /number-field %}
+{% field kind="number" id="rt_critics_score" label="Tomatometer (Critics)" role="agent" min=0 max=100 %}{% /field %}
 
 {% instructions ref="rt_critics_score" %}
 Tomatometer percentage (0-100).
 {% /instructions %}
 
-{% number-field id="rt_critics_count" label="Critics Review Count" role="agent" min=0 %}{% /number-field %}
+{% field kind="number" id="rt_critics_count" label="Critics Review Count" role="agent" min=0 %}{% /field %}
 
-{% number-field id="rt_audience_score" label="Audience Score" role="agent" min=0 max=100 %}{% /number-field %}
+{% field kind="number" id="rt_audience_score" label="Audience Score" role="agent" min=0 max=100 %}{% /field %}
 
 {% instructions ref="rt_audience_score" %}
 Audience Score percentage (0-100).
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="metacritic_ratings" title="Metacritic Ratings" %}
+{% group id="metacritic_ratings" title="Metacritic Ratings" %}
 
-{% number-field id="metacritic_score" label="Metacritic Score" role="agent" min=0 max=100 %}{% /number-field %}
+{% field kind="number" id="metacritic_score" label="Metacritic Score" role="agent" min=0 max=100 %}{% /field %}
 
 {% instructions ref="metacritic_score" %}
 Metascore (0-100 scale). Leave empty if not available.
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="summary" title="Summary" %}
+{% group id="summary" title="Summary" %}
 
-{% string-field id="logline" label="One-Line Summary" role="agent" maxLength=300 %}{% /string-field %}
+{% field kind="string" id="logline" label="One-Line Summary" role="agent" maxLength=300 %}{% /field %}
 
 {% instructions ref="logline" %}
 Brief plot summary in 1-2 sentences, no spoilers.
 {% /instructions %}
 
-{% string-list id="notable_awards" label="Notable Awards" role="agent" %}{% /string-list %}
+{% field kind="string_list" id="notable_awards" label="Notable Awards" role="agent" %}{% /field %}
 
 {% instructions ref="notable_awards" %}
 Major awards won. One per line.
@@ -468,7 +524,7 @@ Format: Award | Category | Year
 Example: "Oscar | Best Picture | 1995"
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
 {% /form %}
 ```
@@ -539,8 +595,13 @@ markform fill template.form.md --mock --mock-source filled.form.md
 
 3. **Set constraints**: Use `min`, `max`, `minLength`, `pattern` to validate
 
-4. **Group logically**: Related fields in the same `field-group`
+4. **Group logically**: Related fields in the same `group`
 
 5. **Assign roles**: Separate user input from agent research
 
 6. **Document thoroughly**: Use `{% instructions %}` for complex fields
+
+## Programmatic API
+
+For TypeScript and AI SDK integration, run `markform apis` or see
+[markform-apis.md](markform-apis.md).