@mapled/cli 0.6.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
@@ -127,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
@@ -155,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.7.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
@@ -175,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mapled/cli",
-  "version": "0.6.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": [