@mapled/cli 0.5.0 → 0.7.0

package/README.md

@@ -14,6 +14,8 @@ npx @mapled/cli doctor
 
 Node 18 or newer. No dependencies. Prefer a global install? `npm install -g @mapled/cli` puts `mapled` on your PATH, and every command below works as `mapled …`.
 
+Connecting a site without an AI agent? [Integrate by hand](https://www.npmjs.com/package/@mapled/next#integrate-by-hand) in the `@mapled/next` README walks through the whole integration — modeling the content, reading it, the publish webhook, preview, forms — and uses these commands along the way.
+
 ## Sign in
 
 ```bash
@@ -84,7 +86,9 @@ Articles (articles)
 4 breaking changes, 2 safe changes, judged for a site that reads the content. Update the site where needed, then run `mapled types generate` (it refreshes mapled/schema.json as well).
 ```
 
-Breaking: a collection, field or option the site may rely on disappears, a type changes, a required field becomes optional, a field becomes sensitive (it stops being delivered), a relation points elsewhere. Safe: additions, renamed labels, help texts, validation rules. `--json` for scripts and agents; `--exit-code` exits 1 when anything changed, for CI.
+Breaking: a collection, field or option the site may rely on disappears, a type changes, a required field becomes optional, a field becomes sensitive (it stops being delivered), a relation points elsewhere. Safe: additions, renamed labels, help texts, validation rules — and a renamed key while its old one is still an alias (`> price  renamed to “amount” — “price” still works as an alias`): the site keeps reading it, the rest of the field is compared under the new key, and `types generate` types the old key `@deprecated`. Once the alias is removed in Mapled the old key is a removed field. `--json` for scripts and agents; `--exit-code` exits 1 when anything changed, for CI.
+
+The pin keeps formulas of computed fields and previous keys. (A pin written by 0.5.0 lost the formulas, so its hash never matched a project that has computed fields — run `schema pull` once after upgrading.)
 
 ## Scan the code into a manifest
 
@@ -125,6 +129,23 @@ npx @mapled/cli bindings pull
 
 `bindings pull` writes the pushed manifest into `mapled/manifest.json` — say, after your agent pushed one from a chat and you want the repository's copy. It refuses to overwrite a local file that differs unless you pass `--force`.
 
+## Create a form
+
+```bash
+npx @mapled/cli forms create "Contact"
+npx @mapled/cli forms list
+```
+
+`forms create` makes a form the site can post submissions to — the same call your AI agent's `create_form` makes, so an integration done by hand needs no agent for it:
+
+```text
+Created the form “Contact” (contact) in Dolphin Landing.
+The site posts submissions to https://api.mapled.io/v1/delivery/forms/contact — flat JSON with the delivery key in X-Mapled-Key, an empty hidden _gotcha field, and the consent label as _consent when the form has a consent checkbox.
+Submissions show up in Mapled under Forms.
+```
+
+The key comes from the name; `--key <key>` chooses it (lowercase letters, digits and dashes), `--no-spam-protection` turns the honeypot off. Creating a form changes structure, so it needs the builder plan. `forms list` shows every form with the URL the site posts to (`--json` for scripts). The component that posts to it is in the [`@mapled/next` README](https://www.npmjs.com/package/@mapled/next#forms).
+
 ## Leave a guide for the next agent
 
 ```bash
@@ -153,8 +174,8 @@ Mapled doctor — Dolphin Landing
 ✓ MAPLED.md            MAPLED.md matches the schema (3f9a1c2b4d5e) and manifest v3
 ✓ Environment          MAPLED_KEY and MAPLED_WEBHOOK_SECRET in .env.local
 ✓ Secrets in git       No env files or Mapled secrets are tracked.
-✓ @mapled/next         0.6.0 (current)
-✓ mapled CLI           0.2.0 (current)
+✓ @mapled/next         0.7.1 (current)
+✓ mapled CLI           0.7.0 (current)
 ✓ Revalidation route   app/api/mapled/revalidate/route.ts
 ⚠ Preview route        app/api/mapled/preview/route.ts is missing — mount createPreviewHandler from "@mapled/next/server" so Preview from Mapled works.
 ✓ Site reads content   Last read 3m ago
@@ -173,7 +194,7 @@ Exit code 1 when something is marked ✗; `--json` prints the checks for scripts
 
 - `--api <origin>` — a Mapled API other than `https://api.mapled.io` (or set `MAPLED_API_URL`); `project link` remembers it in `mapled.json`
 - `--no-browser` — print the sign-in link instead of opening a browser
-- `--json` — machine-readable output (`doctor`, `schema diff`, `scan`, `manifest validate`)
+- `--json` — machine-readable output (`doctor`, `schema diff`, `scan`, `manifest validate`, `forms list`)
 - `MAPLED_CONFIG_DIR` — where credentials live (default: `$XDG_CONFIG_HOME/mapled` or `~/.config/mapled`)
 
 ## Files in the repository

package/dist/args.js

@@ -2,7 +2,7 @@ import { CliError } from "./errors.js";
 /** Minimal argument parsing: the leading words name the command;
     `--flag`, `--flag=value` and `--flag value` (for the flags that take
     one) follow. Nothing here is user content beyond the command line. */
-const VALUE_FLAGS = new Set(["api", "project", "out"]);
+const VALUE_FLAGS = new Set(["api", "project", "out", "key"]);
 export function parseArgs(argv) {
     const words = [];
     const flags = {};

package/dist/commands.d.ts

@@ -2,9 +2,9 @@ import { type ParsedArgs } from "./args.js";
 import { type FoundConfig } from "./config.js";
 import { type Connection } from "./credentials.js";
 import { type Fetch } from "./oauth.js";
-/** The commands of waves 1 and 2 (§31) and MAPLED.md (§21.3). Everything that talks to the
-    world comes in through `Ctx`, so the commands run in tests against a
-    fake API and a temp directory. */
+/** The commands of waves 1 and 2 (§31), MAPLED.md (§21.3) and forms.
+    Everything that talks to the world comes in through `Ctx`, so the
+    commands run in tests against a fake API and a temp directory. */
 export type Ctx = {
     cwd: string;
     env: NodeJS.ProcessEnv;
@@ -29,6 +29,11 @@ export declare function manifestValidate(ctx: Ctx, flags: Flags): Promise<number
 export declare function bindingsPush(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function bindingsPull(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function mdPull(ctx: Ctx, flags: Flags): Promise<void>;
+/** `mapled forms create "Contact"` — a form the site posts submissions to.
+    The same call an AI agent's `create_form` makes, so an integration
+    done by hand needs no agent for it. */
+export declare function formsCreate(ctx: Ctx, flags: Flags, words: string[]): Promise<void>;
+export declare function formsList(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function scan(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function doctor(ctx: Ctx, flags: Flags): Promise<number>;
 export {};

package/dist/commands.js

@@ -390,6 +390,61 @@ export async function mdPull(ctx, flags) {
     else
         ctx.out(`Updated ${MD_FILE} — ${summary}; the notes below the notes line were kept.`);
 }
+const FORM_KEY = /^[a-z][a-z0-9-]{0,63}$/;
+const submitUrl = (api, key) => `${api}/v1/delivery/forms/${key}`;
+/** `mapled forms create "Contact"` — a form the site posts submissions to.
+    The same call an AI agent's `create_form` makes, so an integration
+    done by hand needs no agent for it. */
+export async function formsCreate(ctx, flags, words) {
+    const displayName = words.join(" ").trim();
+    if (!displayName)
+        throw new CliError('Name the form: `mapled forms create "Contact"`.');
+    if (displayName.length > 80)
+        throw new CliError("A form name is up to 80 characters.");
+    const key = stringFlag(flags, "key");
+    if (flags.key !== undefined && (!key || !FORM_KEY.test(key))) {
+        throw new CliError("A form key is lowercase letters, digits and dashes, starting with a letter (up to 64 characters).");
+    }
+    const { session } = await openSession(ctx, flags);
+    let created;
+    try {
+        created = await session.send("POST", "/v1/agent/forms", {
+            displayName,
+            ...(key ? { key } : {}),
+            ...(flags["no-spam-protection"] ? { spamProtection: false } : {}),
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === "BUILDER_PLAN_REQUIRED") {
+            throw new CliError("Creating a form changes the project's structure, which needs a builder plan — ask the project owner to upgrade.");
+        }
+        throw err;
+    }
+    const form = created.form;
+    ctx.out(`Created the form “${form.displayName}” (${form.key}) in ${session.conn.projectName}.`);
+    ctx.out(`The site posts submissions to ${submitUrl(session.conn.api, form.key)} — flat JSON with the delivery key in X-Mapled-Key` +
+        `${form.spamProtection ? ", an empty hidden _gotcha field" : ""}, and the consent label as _consent when the form has a consent checkbox.`);
+    ctx.out("Submissions show up in Mapled under Forms.");
+}
+export async function formsList(ctx, flags) {
+    const { session } = await openSession(ctx, flags);
+    const { forms } = await session.get("/v1/agent/forms");
+    if (flags.json) {
+        ctx.out(JSON.stringify({ forms: forms.map((f) => ({ ...f, submitUrl: submitUrl(session.conn.api, f.key) })) }, null, 2));
+        return;
+    }
+    if (forms.length === 0) {
+        ctx.out(`No forms in ${session.conn.projectName} yet. Create one with \`mapled forms create "Contact"\`.`);
+        return;
+    }
+    const keyWidth = Math.max(...forms.map((f) => f.key.length));
+    const nameWidth = Math.max(...forms.map((f) => f.displayName.length));
+    ctx.out(`Forms of ${session.conn.projectName}`);
+    ctx.out("");
+    for (const f of forms) {
+        ctx.out(`${f.key.padEnd(keyWidth)}  ${f.displayName.padEnd(nameWidth)}  spam protection ${f.spamProtection ? "on " : "off"}  ${submitUrl(session.conn.api, f.key)}`);
+    }
+}
 /* ---- wave 2: the scanner ---- */
 function describeScan(result, schema) {
     const singles = new Set(schema.collections.filter((c) => c.kind === "single").map((c) => c.key));

package/dist/index.js

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "./args.js";
 import { openBrowser } from "./browser.js";
-import { bindingsPull, bindingsPush, doctor, generate, link, login, logout, manifestValidate, mdPull, scan, schemaDiff, schemaPull, } from "./commands.js";
+import { bindingsPull, bindingsPush, doctor, formsCreate, formsList, generate, link, login, logout, manifestValidate, mdPull, scan, schemaDiff, schemaPull, } from "./commands.js";
 import { credentialsPath } from "./credentials.js";
 import { CliError } from "./errors.js";
 /** `mapled` — sign in, link a repository to its project, generate types
@@ -24,6 +24,8 @@ Usage
   mapled bindings push [--dry-run]                    Push mapled/manifest.json so Mapled grades every binding
   mapled bindings pull [--force]                      Write the pushed manifest into mapled/manifest.json
   mapled md pull [--force]                            Write MAPLED.md, the guide for the next agent, from the project
+  mapled forms create <name> [--key <key>]            Create a form the site posts submissions to (--no-spam-protection to skip the honeypot)
+  mapled forms list [--json]                          List the project's forms and where the site posts to
   mapled doctor [--json]                              Check the integration end to end
 
 Options
@@ -108,6 +110,12 @@ async function main(argv) {
         case "md pull":
             await mdPull(ctx, flags);
             return 0;
+        case "forms create":
+            await formsCreate(ctx, flags, words.slice(2));
+            return 0;
+        case "forms list":
+            await formsList(ctx, flags);
+            return 0;
         case "doctor":
             return doctor(ctx, flags);
         case "auth":
@@ -117,6 +125,7 @@ async function main(argv) {
         case "manifest":
         case "bindings":
         case "md":
+        case "forms":
             console.log(HELP);
             return 2;
         default:

package/dist/manifest.d.ts

@@ -62,6 +62,8 @@ export type SchemaIndex = Map<string, {
         displayName: string;
         type: string;
     }>;
+    /** previous key → current key (§33.5): a binding on it still works, through the alias */
+    aliases: Map<string, string>;
 }>;
 export declare function indexSchema(schema: Schema): SchemaIndex;
 /** What a well-formed manifest still gets wrong: bindings the schema

package/dist/manifest.js

@@ -242,13 +242,16 @@ export function indexSchema(schema) {
     const index = new Map();
     for (const c of schema.collections) {
         const fields = new Map();
+        const aliases = new Map();
         // a computed field (§14.9) binds as a field of its result type
         const COMPUTED_AS = { number: "number", text: "short_text", boolean: "boolean", date: "date", datetime: "datetime" };
         for (const f of c.fields) {
             const type = f.type === "computed" && f.computed ? (COMPUTED_AS[f.computed.resultType] ?? f.type) : f.type;
             fields.set(f.key, { displayName: f.displayName, type });
+            for (const a of f.aliases ?? [])
+                aliases.set(a, f.key);
         }
-        index.set(c.key, { displayName: c.displayName, kind: c.kind, fields });
+        index.set(c.key, { displayName: c.displayName, kind: c.kind, fields, aliases });
     }
     return index;
 }
@@ -278,7 +281,11 @@ export async function checkManifest(manifest, opts) {
                 warn(`${at}.collection`, `${who}: no collection "${b.collection}" in the schema — Mapled marks it outdated.`);
             else if (b.field) {
                 const field = collection.fields.get(b.field);
-                if (!field) {
+                const renamedTo = collection.aliases.get(b.field);
+                if (!field && renamedTo) {
+                    warn(`${at}.field`, `${who}: "${b.field}" in "${collection.displayName}" was renamed to "${renamedTo}" — it still works through an alias, and Mapled marks the binding outdated. Read "${renamedTo}", then remove the alias.`);
+                }
+                else if (!field) {
                     warn(`${at}.field`, `${who}: no field "${b.field}" in "${collection.displayName}" — Mapled marks it outdated.`);
                 }
                 else {

package/dist/pin.d.ts

@@ -20,7 +20,7 @@ export declare function readPin(dir: string): Promise<{
 } | null>;
 export declare function writePin(dir: string, pin: SchemaPin): Promise<string>;
 export type Severity = "breaking" | "safe";
-export type ChangeOp = "added" | "removed" | "changed";
+export type ChangeOp = "added" | "removed" | "changed" | "renamed";
 export type SchemaChange = {
     scope: "collection" | "field" | "subfield";
     collection: string;
@@ -33,7 +33,10 @@ export type SchemaChange = {
 };
 /** What changed between two schemas, judged for a site that reads the
     content: anything that can make a read fail or a value disappear is
-    breaking; additions and renames of labels are safe. */
+    breaking; additions and renames of labels are safe. A renamed key
+    (§33.5) is safe while the old one is still an alias of the field —
+    the site keeps reading it — and the rest of the field is compared
+    under its new key; once the alias is removed it is a removed field. */
 export declare function diffSchema(before: SchemaCollection[], after: SchemaCollection[]): SchemaChange[];
 /** The diff as terminal lines: one heading per collection, one line per
     change, the severity in the last column. */

package/dist/pin.js

@@ -44,6 +44,11 @@ function pinField(f) {
         out.validation = f.validation;
     if (f.defaultValue !== undefined && f.defaultValue !== null)
         out.defaultValue = f.defaultValue;
+    // the formula is part of the schema hash: a pin without it would never match the live schema
+    if (f.type === "computed" && f.computed)
+        out.computed = { expression: f.computed.expression, resultType: f.computed.resultType };
+    if (f.aliases && f.aliases.length > 0)
+        out.aliases = [...f.aliases];
     return out;
 }
 /** The schema reduced to what the pin keeps — the live answer of
@@ -143,7 +148,10 @@ function sameJson(a, b) {
 }
 /** What changed between two schemas, judged for a site that reads the
     content: anything that can make a read fail or a value disappear is
-    breaking; additions and renames of labels are safe. */
+    breaking; additions and renames of labels are safe. A renamed key
+    (§33.5) is safe while the old one is still an alias of the field —
+    the site keeps reading it — and the rest of the field is compared
+    under its new key; once the alias is removed it is a removed field. */
 export function diffSchema(before, after) {
     const changes = [];
     const names = new Map();
@@ -171,13 +179,21 @@ export function diffSchema(before, after) {
             col(`name ${q(b.displayName)} → ${q(a.displayName)}`, "safe");
         const afterFields = new Map(a.fields.map((f) => [f.key, f]));
         const beforeFields = new Map(b.fields.map((f) => [f.key, f]));
+        const renamedTo = new Set();
         for (const bf of b.fields) {
-            const af = afterFields.get(bf.key);
+            let af = afterFields.get(bf.key);
             if (!af) {
-                changes.push({ ...base, scope: "field", field: bf.key, op: "removed", detail: `removed — ${describeType(bf, names)}`, severity: "breaking" });
-                continue;
+                const heir = a.fields.find((f) => !beforeFields.has(f.key) && !renamedTo.has(f.key) && f.aliases?.includes(bf.key));
+                if (!heir) {
+                    changes.push({ ...base, scope: "field", field: bf.key, op: "removed", detail: `removed — ${describeType(bf, names)}`, severity: "breaking" });
+                    continue;
+                }
+                renamedTo.add(heir.key);
+                changes.push({ ...base, scope: "field", field: bf.key, op: "renamed", detail: `renamed to ${q(heir.key)} — ${q(bf.key)} still works as an alias`, severity: "safe" });
+                af = heir;
             }
-            const push = (op, detail, severity) => changes.push({ ...base, scope: "field", field: bf.key, op, detail, severity });
+            const under = af.key;
+            const push = (op, detail, severity) => changes.push({ ...base, scope: "field", field: under, op, detail, severity });
             diffCommon(bf, af, names, push);
             if (bf.type === "relation" && af.type === "relation" && bf.relation && af.relation) {
                 if (bf.relation.target !== af.relation.target) {
@@ -209,7 +225,7 @@ export function diffSchema(before, after) {
                 const beforeSubs = new Map(bf.group.fields.map((s) => [s.key, s]));
                 for (const bs of bf.group.fields) {
                     const as = afterSubs.get(bs.key);
-                    const sub = `${bf.key}.${bs.key}`;
+                    const sub = `${under}.${bs.key}`;
                     if (!as) {
                         changes.push({ ...base, scope: "subfield", field: sub, op: "removed", detail: `removed — ${describeType(bs, names)}`, severity: "breaking" });
                         continue;
@@ -222,7 +238,7 @@ export function diffSchema(before, after) {
                     changes.push({
                         ...base,
                         scope: "subfield",
-                        field: `${bf.key}.${as.key}`,
+                        field: `${under}.${as.key}`,
                         op: "added",
                         detail: `added — ${describeType(as, names)}, ${as.required ? "required" : "optional"}`,
                         severity: "safe",
@@ -235,7 +251,7 @@ export function diffSchema(before, after) {
                 push("changed", "default value changed", "safe");
         }
         for (const af of a.fields) {
-            if (beforeFields.has(af.key))
+            if (beforeFields.has(af.key) || renamedTo.has(af.key))
                 continue;
             changes.push({
                 ...base,
@@ -261,7 +277,7 @@ export function diffSchema(before, after) {
     }
     return changes;
 }
-const GLYPH = { added: "+", removed: "-", changed: "~" };
+const GLYPH = { added: "+", removed: "-", changed: "~", renamed: ">" };
 /** The diff as terminal lines: one heading per collection, one line per
     change, the severity in the last column. */
 export function formatChanges(changes, paint = (_, t) => t) {

package/dist/schema.d.ts

@@ -37,6 +37,10 @@ export type SchemaField = {
         expression: string;
         resultType: string;
     } | null;
+    /** Previous keys (§33.5): the field was renamed, and Mapled serves and
+        accepts it under these too until they are removed. Not part of the
+        schema hash — a rename changes the key, which is. */
+    aliases?: string[];
 };
 export type SchemaCollection = {
     key: string;

package/dist/types.js

@@ -115,14 +115,26 @@ function fieldLine(key, displayName, required, rendered) {
 function renderSubField(sub) {
     return fieldLine(sub.key, sub.displayName, sub.required, scalarType(sub.type, sub.options));
 }
+/** The field's line, followed by one per previous key (§33.5): a
+    renamed field is still delivered under them, typed as the field, and
+    the editor strikes them through until the site stops reading them. */
 function renderField(field, owner, names, extras) {
+    const { required, rendered } = renderedField(field, owner, names, extras);
+    const lines = [fieldLine(field.key, field.displayName, required, rendered)];
+    for (const alias of field.aliases ?? []) {
+        lines.push(`  /** @deprecated Renamed to "${comment(field.key)}" — still delivered under this key until the alias is removed in Mapled. */\n` +
+            `  ${prop(alias)}?: ${rendered.type} | null;`);
+    }
+    return lines.join("\n");
+}
+function renderedField(field, owner, names, extras) {
     if (field.type === "relation" && field.relation) {
         const target = names.get(field.relation.target) ?? field.relation.target;
         const many = field.relation.cardinality === "many";
-        return fieldLine(field.key, field.displayName, field.required, {
-            type: many ? "MapledRecordId[]" : "MapledRecordId",
-            note: `relation to ${comment(target)}${many ? " (many)" : ""}`,
-        });
+        return {
+            required: field.required,
+            rendered: { type: many ? "MapledRecordId[]" : "MapledRecordId", note: `relation to ${comment(target)}${many ? " (many)" : ""}` },
+        };
     }
     if (field.type === "group" && field.group) {
         const itemName = `${owner}${pascal(wordsOf(field.key))}${field.group.repeatable ? "Item" : ""}`;
@@ -136,15 +148,12 @@ function renderField(field, owner, names, extras) {
         const note = field.group.repeatable
             ? `group${field.group.maxItems ? `, up to ${field.group.maxItems} items` : ""}`
             : "group";
-        return fieldLine(field.key, field.displayName, field.required, {
-            type: field.group.repeatable ? `${itemName}[]` : itemName,
-            note,
-        });
+        return { required: field.required, rendered: { type: field.group.repeatable ? `${itemName}[]` : itemName, note } };
     }
     if (field.type === "computed" && field.computed) {
-        return fieldLine(field.key, field.displayName, false, computedType(field.computed.resultType));
+        return { required: false, rendered: computedType(field.computed.resultType) };
     }
-    return fieldLine(field.key, field.displayName, field.required, scalarType(field.type, field.options));
+    return { required: field.required, rendered: scalarType(field.type, field.options) };
 }
 /** Unique type names: the singular PascalCase of the key; the raw
     PascalCase when two keys meet there; a numeric suffix as a last resort. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mapled/cli",
-  "version": "0.5.0",
-  "description": "Mapled CLI — sign in, link a project, generate TypeScript types for its content and check the site's integration.",
+  "version": "0.7.0",
+  "description": "Mapled CLI — sign in, link a project, generate TypeScript types for its content, create forms and check the site's integration.",
   "license": "MIT",
   "homepage": "https://mapled.io",
   "keywords": [