markform 0.1.19 → 0.1.21

package/README.md

@@ -1,7 +1,7 @@
 # Markform
 
-[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21506874671)
-[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21506874671)
+[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21611973252)
+[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21611973252)
 [![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)
 
@@ -529,7 +529,10 @@ markform --help
 ## API Key Setup
 
 Set the appropriate environment variable for your provider before running
-`markform fill`:
+`markform fill`. The CLI automatically loads from `.env.local` and `.env` files in the
+current directory.
+
+Supported providers:
 
 | Provider | Env Variable | Native Web Search |
 | --- | --- | :---: |
@@ -587,7 +590,8 @@ if (result.status.ok) {
 }
 ```
 
-See the [API documentation](https://github.com/jlevy/markform/blob/main/docs/markform-apis.md)
+See the
+[API documentation](https://github.com/jlevy/markform/blob/main/docs/markform-apis.md)
 for options like parallel execution, callbacks, and checkpointing.
 
 ### AI SDK Integration
@@ -768,12 +772,14 @@ more on the philosophy behind “docs-as-data” that Markform extends to “for
 We could use XML tags, but Markdoc has some niceties like tagging Markdown AST nodes
 (`{% #some-id %}`) so I decided to go with this.
 
-### Is there a VSCode plugin for Markform or Markdoc?
+### What editor settings work best?
+
+**HTML comment syntax (recommended):** Regular Markdown mode works perfectly since
+`<!-- tag -->` comments are standard Markdown.
 
-For quick syntax highlighting of `{% tag %}` syntax, install
+**Markdoc syntax (`{% tag %}`):** Install
 [Better Jinja](https://marketplace.visualstudio.com/items?itemName=samuelcolvin.jinjahtml)
-and associate `.form.md` files with the `jinja-md` language mode in your VS Code
-settings:
+and associate `.form.md` files with `jinja-md` mode:
 
 ```json
 "files.associations": {
@@ -781,8 +787,6 @@ settings:
 }
 ```
 
-Or see [markdoc/language-server](https://github.com/markdoc/language-server).
-
 ## License
 
 This project uses a dual licensing approach:

package/dist/ai-sdk.d.mts

@@ -1,5 +1,5 @@
 
-import { At as Patch, Mt as PatchSchema, U as FieldResponse, Y as FormSchema, at as InspectResult, et as Id, kt as ParsedForm, mr as ValidatorRegistry, r as ApplyResult } from "./coreTypes-CkxML8g2.mjs";
+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-BQrWf_Wt.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-CPKXf2dc.mjs";
-import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-Dalpt-D6.mjs";
+import { R as PatchSchema } from "./coreTypes-CTLr-NGd.mjs";
+import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-CD-t7ovb.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts

package/dist/{apply-Dalpt-D6.mjs → apply-CD-t7ovb.mjs}

@@ -2,7 +2,7 @@
 import YAML from "yaml";
 
 //#region src/errors.ts
-const VERSION = "0.1.19";
+const VERSION = "0.1.21";
 /**
 * Base error class for all markform errors.
 * Consumers can catch this to handle any markform error.
@@ -359,6 +359,56 @@ const MAX_FORMS_IN_MENU = 30;
 */
 const DEFAULT_PORT = 3344;
 /**
+* Default line width for YAML output.
+* Long strings will wrap at this column for readability.
+* 88 is a common line width that works well with most editors.
+*/
+const DEFAULT_YAML_LINE_WIDTH = 88;
+/**
+* YAML stringify options for readable output.
+* - No forced quoting (YAML only quotes when necessary)
+* - lineWidth provides reasonable wrapping for long strings
+* - Plain keys without quotes
+*/
+const YAML_STRINGIFY_OPTIONS = {
+	lineWidth: DEFAULT_YAML_LINE_WIDTH,
+	defaultKeyType: "PLAIN"
+};
+/**
+* Mapping between YAML snake_case keys and TypeScript camelCase keys
+* for harness configuration. Single source of truth for all transformations.
+*/
+const HARNESS_CONFIG_MAPPING = {
+	max_turns: "maxTurns",
+	max_patches_per_turn: "maxPatchesPerTurn",
+	max_issues_per_turn: "maxIssuesPerTurn",
+	max_parallel_agents: "maxParallelAgents"
+};
+/**
+* Transform harness config from YAML snake_case to TypeScript camelCase.
+* Used by the parser when reading frontmatter.
+*/
+function transformHarnessConfigToTs(yaml) {
+	const result = {};
+	for (const [snakeKey, camelKey] of Object.entries(HARNESS_CONFIG_MAPPING)) {
+		const value = yaml[snakeKey];
+		if (value !== void 0) result[camelKey] = value;
+	}
+	return result;
+}
+/**
+* Transform harness config from TypeScript camelCase to YAML snake_case.
+* Used by the serializer when writing frontmatter.
+*/
+function transformHarnessConfigToYaml(ts) {
+	const result = {};
+	for (const [snakeKey, camelKey] of Object.entries(HARNESS_CONFIG_MAPPING)) {
+		const value = ts[camelKey];
+		if (value !== void 0) result[snakeKey] = value;
+	}
+	return result;
+}
+/**
 * Default maximum turns for the fill harness.
 * Prevents runaway loops during agent execution.
 */
@@ -413,6 +463,24 @@ const REPORT_EXTENSION = ".report.md";
 */
 const SCHEMA_EXTENSION = ".schema.json";
 /**
+* Fill record extension - sidecar file containing execution metadata.
+* Generated by `markform fill --record-fill` and read by `markform serve`.
+*
+* **Recommended naming convention:**
+* - Form file: `document.form.md` → Fill record: `document.fill.json`
+* - Form file: `document.md` → Fill record: `document.fill.json`
+*
+* Using `.form.md` for forms and `.fill.json` for fill records helps tools
+* discover related files automatically. The CLI enforces this convention.
+*
+* The fill record contains:
+* - Session timing and duration
+* - LLM token usage (input/output)
+* - Tool call timeline with results
+* - Form progress at completion
+*/
+const FILL_RECORD_EXTENSION = ".fill.json";
+/**
 * All recognized markform file extensions.
 * Combines export formats with report and schema formats.
 */
@@ -471,6 +539,22 @@ function deriveSchemaPath(basePath) {
 	}
 	return base + SCHEMA_EXTENSION;
 }
+/**
+* Derive fill record sidecar path from a form file path.
+*
+* **Convention:**
+* - `document.form.md` → `document.fill.json`
+* - `document.md` → `document.fill.json`
+*
+* Priority: strips `.form.md` first, then falls back to `.md`.
+* This ensures the recommended `.form.md` extension is handled correctly
+* while also supporting plain `.md` files.
+*/
+function deriveFillRecordPath(formPath) {
+	if (formPath.endsWith(EXPORT_EXTENSIONS.form)) return formPath.slice(0, -EXPORT_EXTENSIONS.form.length) + FILL_RECORD_EXTENSION;
+	if (formPath.endsWith(".md")) return formPath.slice(0, -3) + FILL_RECORD_EXTENSION;
+	return formPath + FILL_RECORD_EXTENSION;
+}
 
 //#endregion
 //#region src/engine/parseHelpers.ts
@@ -2083,27 +2167,17 @@ function serializeFormSchema(schema, responses, docs, notes) {
 	return lines.join("\n");
 }
 /**
-* Build harness config object for YAML output (camelCase to snake_case).
-*/
-function buildHarnessConfig(config) {
-	const result = {};
-	if (config.maxTurns !== void 0) result.max_turns = config.maxTurns;
-	if (config.maxPatchesPerTurn !== void 0) result.max_patches_per_turn = config.maxPatchesPerTurn;
-	if (config.maxIssuesPerTurn !== void 0) result.max_issues_per_turn = config.maxIssuesPerTurn;
-	if (config.maxParallelAgents !== void 0) result.max_parallel_agents = config.maxParallelAgents;
-	return result;
-}
-/**
 * Build frontmatter YAML from form metadata.
-* Preserves roles, role_instructions, harness config, and run_mode.
+* Preserves title, description, roles, role_instructions, harness config, and run_mode.
 */
 function buildFrontmatter(metadata, specVersion) {
 	const markformSection = { spec: specVersion };
+	if (metadata?.title) markformSection.title = metadata.title;
+	if (metadata?.description) markformSection.description = metadata.description;
 	if (metadata?.runMode) markformSection.run_mode = metadata.runMode;
-	if (metadata?.harnessConfig && Object.keys(metadata.harnessConfig).length > 0) markformSection.harness = buildHarnessConfig(metadata.harnessConfig);
-	const frontmatterObj = { markform: markformSection };
+	if (metadata?.harnessConfig && Object.keys(metadata.harnessConfig).length > 0) markformSection.harness = transformHarnessConfigToYaml(metadata.harnessConfig);
 	const defaultRoles = ["user", "agent"];
-	if (metadata?.roles && (metadata.roles.length !== defaultRoles.length || !metadata.roles.every((r, i) => r === defaultRoles[i]))) frontmatterObj.roles = metadata.roles;
+	if (metadata?.roles && (metadata.roles.length !== defaultRoles.length || !metadata.roles.every((r, i) => r === defaultRoles[i]))) markformSection.roles = metadata.roles;
 	const defaultInstructions = {
 		user: "",
 		agent: ""
@@ -2111,13 +2185,10 @@ function buildFrontmatter(metadata, specVersion) {
 	if (metadata?.roleInstructions) {
 		if (Object.entries(metadata.roleInstructions).some(([role, instruction]) => {
 			return instruction !== (defaultInstructions[role] ?? "") && instruction.trim() !== "";
-		})) frontmatterObj.role_instructions = metadata.roleInstructions;
+		})) markformSection.role_instructions = metadata.roleInstructions;
 	}
-	return `---\n${YAML.stringify(frontmatterObj, {
-		lineWidth: 0,
-		defaultStringType: "QUOTE_DOUBLE",
-		defaultKeyType: "PLAIN"
-	})}---`;
+	const frontmatterObj = { markform: markformSection };
+	return `---\n${YAML.stringify(frontmatterObj, YAML_STRINGIFY_OPTIONS)}---`;
 }
 /**
 * Serialize a ParsedForm to canonical Markdoc markdown format.
@@ -4259,5 +4330,5 @@ function applyPatches(form, patches) {
 }
 
 //#endregion
-export { WEB_SEARCH_CONFIG as $, parseOptionText as A, DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN as B, extractTableContent as C, getStringAttr as D, getStringArrayAttr as E, DEFAULT_MAX_PATCHES_PER_TURN as F, REPORT_EXTENSION as G, DEFAULT_ROLES as H, DEFAULT_MAX_STEPS_PER_TURN as I, deriveReportPath as J, USER_ROLE as K, DEFAULT_MAX_TURNS as L, DEFAULT_FORMS_DIR as M, DEFAULT_MAX_ISSUES_PER_TURN as N, getValidateAttr as O, DEFAULT_MAX_PARALLEL_AGENTS as P, SUGGESTED_LLMS as Q, DEFAULT_PORT as R, extractOptionItems as S, getNumberAttr as T, DEFAULT_ROLE_INSTRUCTIONS as U, DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN as V, MAX_FORMS_IN_MENU as W, detectFileType as X, deriveSchemaPath as Y, parseRolesFlag as Z, preprocessCommentSyntax as _, isPatchError as _t, validate as a, MarkformConfigError as at, CHECKBOX_MARKERS as b, computeProgressSummary as c, MarkformParseError as ct, serializeForm as d, ParseError as dt, formatSuggestedLlms as et, serializeRawMarkdown as f, isAbortError as ft, detectSyntaxStyle as g, isParseError as gt, friendlyUrlAbbrev as h, isMarkformError as ht, inspect as i, MarkformAbortError as it, AGENT_ROLE as j, isTagNode as k, computeStructureSummary as l, MarkformPatchError as lt, formatBareUrlsAsHtmlLinks as m, isLlmError as mt, getAllFields as n, hasWebSearchSupport as nt, computeAllSummaries as o, MarkformError as ot, serializeReport as p, isConfigError as pt, deriveExportPath as q, getFieldsForRoles as r, parseModelIdForDisplay as rt, computeFormState as s, MarkformLlmError as st, applyPatches as t, getWebSearchConfig as tt, isFormComplete as u, MarkformValidationError as ut, validateSyntaxConsistency as v, isRetryableError as vt, getBooleanAttr as w, extractFenceValue as x, tryParseSentinelResponse as y, isValidationError as yt, DEFAULT_PRIORITY as z };
-//# sourceMappingURL=apply-Dalpt-D6.mjs.map
+export { transformHarnessConfigToTs as $, parseOptionText as A, DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN as B, extractTableContent as C, getStringAttr as D, getStringArrayAttr as E, DEFAULT_MAX_PATCHES_PER_TURN as F, REPORT_EXTENSION as G, DEFAULT_ROLES as H, DEFAULT_MAX_STEPS_PER_TURN as I, deriveFillRecordPath as J, USER_ROLE as K, DEFAULT_MAX_TURNS as L, DEFAULT_FORMS_DIR as M, DEFAULT_MAX_ISSUES_PER_TURN as N, getValidateAttr as O, DEFAULT_MAX_PARALLEL_AGENTS as P, parseRolesFlag as Q, DEFAULT_PORT as R, extractOptionItems as S, getNumberAttr as T, DEFAULT_ROLE_INSTRUCTIONS as U, DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN as V, MAX_FORMS_IN_MENU as W, deriveSchemaPath as X, deriveReportPath as Y, detectFileType as Z, preprocessCommentSyntax as _, isMarkformError as _t, validate as a, parseModelIdForDisplay as at, CHECKBOX_MARKERS as b, isRetryableError as bt, computeProgressSummary as c, MarkformError as ct, serializeForm as d, MarkformPatchError as dt, SUGGESTED_LLMS as et, serializeRawMarkdown as f, MarkformValidationError as ft, detectSyntaxStyle as g, isLlmError as gt, friendlyUrlAbbrev as h, isConfigError as ht, inspect as i, hasWebSearchSupport as it, AGENT_ROLE as j, isTagNode as k, computeStructureSummary as l, MarkformLlmError as lt, formatBareUrlsAsHtmlLinks as m, isAbortError as mt, getAllFields as n, formatSuggestedLlms as nt, computeAllSummaries as o, MarkformAbortError as ot, serializeReport as p, ParseError as pt, deriveExportPath as q, getFieldsForRoles as r, getWebSearchConfig as rt, computeFormState as s, MarkformConfigError as st, applyPatches as t, WEB_SEARCH_CONFIG as tt, isFormComplete as u, MarkformParseError as ut, validateSyntaxConsistency as v, isParseError as vt, getBooleanAttr as w, extractFenceValue as x, isValidationError as xt, tryParseSentinelResponse as y, isPatchError as yt, DEFAULT_PRIORITY as z };
+//# sourceMappingURL=apply-CD-t7ovb.mjs.map