markform 0.1.2 → 0.1.4

package/README.md

@@ -41,7 +41,7 @@ npx markform examples
 This walks you through an example form interactively, with optional AI agent filling.
 You’ll need at least one [API key](#supported-providers) to have LLMs fill in forms.
 
-### A Simple Form
+### A Minimal Form
 
 A `.form.md` file is simply a Markdoc file.
 It combines YAML frontmatter with Markdoc-tagged content:
@@ -50,71 +50,115 @@ It combines YAML frontmatter with Markdoc-tagged content:
 ---
 markform:
   spec: MF/0.1
-  title: Movie Research (Simple)
-  roles:              # Who can fill fields
+  title: Movie Research (Minimal)
+  description: Quick movie lookup with just the essentials (title, year, ratings, summary).
+  roles:
     - user
     - agent
-  role_instructions:  # Instructions shown to each role
+  role_instructions:
     user: "Enter the movie title."
-    agent: "Research the movie and fill in the details from IMDB."
+    agent: |
+      Quickly identify the movie and fill in basic info from IMDB.
+      This is a minimal lookup - just get the core facts.
 ---
+{% form id="movie_research_minimal" title="Movie Research (Minimal)" %}
 
-{% form id="movie_research" title="Movie Research" %}
+## Movie Research Example
 
-{% field-group id="input" title="Input" %}
+{% field-group id="movie_input" title="Movie Identification" %}
 
-<!-- User fills this field -->
+What movie do you want to research? \[*This field is filled in by the user (`role="user"`).*\]
 
-{% 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 year or details for disambiguation).{% /instructions %}
 
-{% instructions ref="movie" %}
+{% /field-group %}
 
-<!-- Guidance for filling the field -->
+## About the Movie
 
-Enter the movie title (add any details to help identify, like "Barbie 2023" or "the Batman movie with Robert Pattinson").
-{% /instructions %}
+{% field-group id="about_the_movie" title="About the Movie" %}
 
-{% /field-group %}
+**Title:**
+
+{% field kind="string" id="full_title" label="Full Title" role="agent" required=true %}{% /field %}
+{% instructions ref="full_title" %}Official title, including subtitle if any.{% /instructions %}
 
-{% field-group id="details" title="Movie Details" %}
+**Release year:**
 
-<!-- Agent researches and fills these fields -->
+{% field kind="number" id="year" label="Release Year" role="agent" required=true min=1888 max=2030 %}{% /field %}
 
-{% string-field id="full_title" label="Full Title" role="agent" required=true %}{% /string-field %}
+**IMDB:**
 
-{% number-field id="year" label="Release Year" role="agent" min=1888 max=2030 %}{% /number-field %}
+{% field kind="url" id="imdb_url" label="IMDB URL" role="agent" required=true %}{% /field %}
 
-{% single-select id="mpaa_rating" label="MPAA Rating" role="agent" %}
+**MPAA rating:**
+
+{% 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 %}
+
+**IMDB rating:**
 
-{% url-field id="imdb_url" label="IMDB URL" role="agent" %}{% /url-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_rating" label="IMDB Rating" role="agent" min=1.0 max=10.0 %}{% /number-field %}
+**Summary:**
 
-{% string-field id="logline" label="Summary" role="agent" maxLength=200 %}{% /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 %}
 
 {% /field-group %}
 
 {% /form %}
 ```
 
-This is a simplified version of the [full movie research
-form](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research.form.md),
-which includes multiple rating sources (IMDB, Rotten Tomatoes, Metacritic), detailed
-instructions, and harness configuration.
+Run the `npx markform examples` and select the `Movie Research (Minimal)` example and
+view the report:
+
+```markdown
+# Movie Research (Minimal)
+
+## Movie Identification
+
+Movie:
+shawshank redemption
+
+## About the Movie
+
+Full Title:
+The Shawshank Redemption
+
+Release Year:
+1994
+
+IMDB URL:
+https://www.imdb.com/title/tt0111161/
+
+MPAA Rating:
+R
+
+IMDB Rating:
+9.3
+
+One-Line Summary:
+Convicted banker Andy Dufresne is sent to Shawshank State Penitentiary, where he forms an unexpected friendship with inmate Red while holding onto hope and striving to maintain his dignity in a corrupt prison system.
+```
+
+See the
+[examples/](https://github.com/jlevy/markform/tree/main/packages/markform/examples)
+directory for a few more complex form examples.
 
 **Key concepts:**
 
 - **Roles**: Define who fills what (`user` for humans, `agent` for AI)
 
-- **Field types**: `string-field`, `number-field`, `url-field`, `string-list`,
-  `single-select`, `multi-select`, `checkboxes`
+- **Field kinds**: `string-field`, `number-field`, `date-field`, `year-field`,
+  `url-field`, `url-list`, `string-list`, `single-select`, `multi-select`, `checkboxes`
 
 - **Validation**: `required`, `min/max`, `minLength/maxLength`, `pattern`
 
@@ -137,7 +181,7 @@ The package includes example forms in
   \- Comprehensive analysis with streaming, box office
 
 - [`simple/simple.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/simple/simple.form.md)
-  \- Basic form demonstrating all field types
+  \- Basic form demonstrating all field kinds
 
 - [`earnings-analysis/earnings-analysis.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/earnings-analysis/earnings-analysis.form.md)
   \- Financial analysis form
@@ -250,9 +294,12 @@ markform serve my-form.form.md
 # Quick reference for writing forms (agent-friendly)
 markform docs
 
-# Full specification (SPEC.md)
+# Full specification
 markform spec
 
+# TypeScript and AI SDK API documentation
+markform apis
+
 # This README
 markform readme
 
@@ -282,7 +329,9 @@ flowchart LR
         subgraph L4["<b>LAYER 4: TOOL API & INTERFACES</b><br/>Abstract API for agents and humans (TypeScript and AI SDK integration)"]
         end
 
-        L4 --> L3 --> L2 --> L1
+        L4 -->
+
+L3 --> L2 --> L1
     end
 
     subgraph IMPL["<b>THIS IMPLEMENTATION</b>"]
@@ -389,7 +438,8 @@ But it’s been useful for me already.
 
 It’s all written by LLMs but using a strongly spec-driven process, using rules from
 [Speculate](https://github.com/jlevy/speculate).
-See [the spec](SPEC.md) and the architecture docs and specs in [docs/](docs/).
+See [the spec](docs/markform-spec.md) and the architecture docs and specs in
+[docs/](docs/).
 
 ### What are the goals of Markform?
 
@@ -444,12 +494,13 @@ Not really. The closest alternatives are:
   human-friendly UI. But these do not have a human-friendly text format for use by
   agents as well as humans.
 
-| Approach | Human-readable | Agent-editable | Custom validations |
-| --- | :---: | :---: | :---: |
-| Plain Markdown | ✅ | ⚠️ fragile | ❌ |
-| JSON Schema | ❌ | ✅ | ✅ |
-| PDF Forms, SaaS tools | ⚠️ | ❌ | ⚠️ |
-| **Markform** | ✅ | ✅ | ✅ |
+| Approach | Has GUI | Human-readable text format | Agent-editable | APIs and validation rules |
+| --- | :---: | :---: | :---: | :---: |
+| Plain Markdown | ☑️ existing tools | ✅ | ⚠️ fragile | ❌ |
+| JSON with schema | ☑️ existing tools | ⚠️ hey it’s JSON | ✅ | ✅ |
+| SaaS tools (Typeform, Docusign, PDF forms) | ✅ | ⚠️ rarely | ⚠️ if they add it | ⚠️ if they add it |
+| Excel/Google Sheets | ✅ | ❌ .xlsx | ⚠️ with tools | ✅ |
+| **Markform** | ☑️ existing tools | ✅ | ✅ | ✅ |
 
 ### What are example use cases?
 
@@ -494,11 +545,15 @@ Or see [markdoc/language-server](https://github.com/markdoc/language-server).
 ## Documentation
 
 - **[Quick
-  Reference](https://github.com/jlevy/markform/blob/main/packages/markform/DOCS.md)**
+  Reference](https://github.com/jlevy/markform/blob/main/docs/markform-reference.md)**
   (or run `markform docs`) - Concise syntax reference (agent-friendly)
 
-- **[Markform Spec](https://github.com/jlevy/markform/blob/main/SPEC.md)** (or run
-  `markform spec`) - Complete syntax and semantics
+- **[Markform Spec](https://github.com/jlevy/markform/blob/main/docs/markform-spec.md)**
+  (or run `markform spec`) - Complete syntax and semantics
+
+- **[API
+  Documentation](https://github.com/jlevy/markform/blob/main/docs/markform-apis.md)**
+  (or run `markform apis`) - TypeScript and AI SDK APIs
 
 - **[Design
   Doc](https://github.com/jlevy/markform/blob/main/docs/project/architecture/current/arch-markform-design.md)**

package/dist/ai-sdk.d.mts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { H as Id, L as FormSchema, Sn as ValidatorRegistry, _t as ParsedForm, j as FieldResponse, q as InspectResult, r as ApplyResult, vt as Patch, yt as PatchSchema } from "./coreTypes-BXhhz9Iq.mjs";
+import { Dt as PatchSchema, Et as Patch, G as FormSchema, Tt as ParsedForm, X as Id, ar as ValidatorRegistry, r as ApplyResult, tt as InspectResult, z as FieldResponse } from "./coreTypes-cbNTYAcb.mjs";
 import { z } from "zod";
 
 //#region src/integrations/toolTypes.d.ts
@@ -62,7 +62,7 @@ interface MarkformToolSet {
   markform_get_markdown?: MarkformTool<Record<string, never>, GetMarkdownToolResult>;
 }
 //#endregion
-//#region src/integrations/ai-sdk.d.ts
+//#region src/integrations/vercelAiSdkTools.d.ts
 /**
  * Session store for managing form state during AI interactions.
  *

package/dist/ai-sdk.mjs

@@ -1,8 +1,8 @@
-import { N as PatchSchema } from "./coreTypes-Dful87E0.mjs";
-import { r as inspect, t as applyPatches, u as serialize } from "./apply-BfAGTHMh.mjs";
+import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
+import { r as inspect, t as applyPatches, u as serialize } from "./apply-C54EMAJ1.mjs";
 import { z } from "zod";
 
-//#region src/integrations/ai-sdk.ts
+//#region src/integrations/vercelAiSdkTools.ts
 /**
 * AI SDK Integration for Markform.
 *
@@ -63,7 +63,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, clear_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. 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.");
 /**
 * Input schema for markform_export tool (no parameters).
 */
@@ -115,7 +115,7 @@ function createMarkformTools(options) {
 			}
 		},
 		markform_apply: {
-			description: "Apply patches to update form field values. Use this after inspecting the form to set values for fields that need to be filled. Patches are applied as a transaction - all succeed or all fail. Returns the updated form state and any remaining issues. Patch operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, clear_field.",
+			description: "Apply patches to update form field values. Use this after inspecting the form to set values for fields that need to be filled. Patches are applied as a transaction - all succeed or all fail. Returns the updated form state and any remaining issues. 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.",
 			inputSchema: ApplyInputSchema,
 			execute: ({ patches }) => {
 				const form = sessionStore.getForm();