@mapled/cli 0.11.0 → 0.12.0

package/dist/manifest.d.ts

@@ -22,12 +22,21 @@ export type ManifestPage = {
     route: string;
     file?: string;
 };
+/** What the site can do beyond reading (§21.2): `realtime` — open tabs
+    follow Publish (§18.8), through `releaseRoute` when the site answers
+    the release itself. Not part of the integration hash: Mapled grades
+    nothing by it, it only tells the next agent (MAPLED.md). */
+export type ManifestCapabilities = {
+    realtime?: boolean;
+    releaseRoute?: string;
+};
 export type Manifest = {
     framework?: string;
     integrationMode?: string;
     pages?: ManifestPage[];
     bindings: ManifestBinding[];
     notes?: string[];
+    capabilities?: ManifestCapabilities;
 };
 export declare const KEY_PATTERN: RegExp;
 export declare const LIMITS: {
@@ -48,6 +57,7 @@ export type Problem = {
     path: string;
     message: string;
 };
+export declare const CAPABILITY_KEYS: readonly ["realtime", "releaseRoute"];
 /** Parses the file's text into a manifest with only the known fields,
     reporting every shape problem the API would refuse (as errors) and the
     parts it would silently drop (as warnings). */
@@ -83,15 +93,19 @@ export declare function readManifestFile(dir: string): Promise<{
     the order they came in. */
 export declare function writeManifestFile(dir: string, manifest: Manifest): Promise<string>;
 export declare function orderManifest(manifest: Manifest): Manifest;
+/** Whether two manifests declare the same capabilities (missing and empty are the same). */
+export declare function sameCapabilities(a: ManifestCapabilities | undefined, b: ManifestCapabilities | undefined): boolean;
 export declare function orderBinding(b: ManifestBinding): ManifestBinding;
 export declare function plural(n: number, word: string, pluralWord?: string): string;
 export declare function manifestSummary(manifest: Manifest): string;
 /** Bindings that mean the same thing to Mapled (what a push stores). */
 export declare function sameBinding(a: ManifestBinding, b: ManifestBinding): boolean;
+/** `same` is about the bindings; `capabilitiesDiffer` says whether the capabilities do. */
 export type ManifestComparison = {
     same: boolean;
     onlyLocal: string[];
     onlyRemote: string[];
     changed: string[];
+    capabilitiesDiffer: boolean;
 };
 export declare function compareManifests(local: Manifest, remote: Manifest): ManifestComparison;

package/dist/manifest.js

@@ -91,7 +91,8 @@ export function typeLabel(type) {
 }
 const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 const isText = (v, max, min = 1) => typeof v === "string" && v.length >= min && v.length <= max;
-const TOP_KEYS = new Set(["framework", "integrationMode", "pages", "bindings", "notes"]);
+const TOP_KEYS = new Set(["framework", "integrationMode", "pages", "bindings", "notes", "capabilities"]);
+export const CAPABILITY_KEYS = ["realtime", "releaseRoute"];
 const BINDING_KEYS = new Set(["key", "page", "component", "file", "collection", "field", "target", "required"]);
 /** Parses the file's text into a manifest with only the known fields,
     reporting every shape problem the API would refuse (as errors) and the
@@ -236,6 +237,40 @@ export function parseManifest(raw, file) {
             manifest.notes = data.notes;
         }
     }
+    if (data.capabilities !== undefined) {
+        const caps = data.capabilities;
+        if (!isObject(caps)) {
+            error("capabilities", `"capabilities" must be an object — { realtime, releaseRoute }.`);
+        }
+        else {
+            const kept = {};
+            let ok = true;
+            for (const key of Object.keys(caps)) {
+                if (!CAPABILITY_KEYS.includes(key)) {
+                    error(`capabilities.${key}`, `capabilities.${key} isn't a capability Mapled knows — only ${CAPABILITY_KEYS.join(" and ")}; Mapled refuses the push.`);
+                    ok = false;
+                }
+            }
+            if (caps.realtime !== undefined) {
+                if (typeof caps.realtime === "boolean")
+                    kept.realtime = caps.realtime;
+                else {
+                    error("capabilities.realtime", "capabilities.realtime must be true or false.");
+                    ok = false;
+                }
+            }
+            if (caps.releaseRoute !== undefined) {
+                if (isText(caps.releaseRoute, 200) && caps.releaseRoute.startsWith("/"))
+                    kept.releaseRoute = caps.releaseRoute;
+                else {
+                    error("capabilities.releaseRoute", `capabilities.releaseRoute must be the route's path on the site, e.g. "/api/mapled/release".`);
+                    ok = false;
+                }
+            }
+            if (ok)
+                manifest.capabilities = kept;
+        }
+    }
     return { manifest, problems };
 }
 export function indexSchema(schema) {
@@ -345,8 +380,19 @@ export function orderManifest(manifest) {
         ...(manifest.pages ? { pages: manifest.pages.map((p) => ({ route: p.route, ...(p.file !== undefined ? { file: p.file } : {}) })) } : {}),
         bindings: manifest.bindings.map(orderBinding),
         ...(manifest.notes && manifest.notes.length > 0 ? { notes: [...manifest.notes] } : {}),
+        ...(manifest.capabilities ? { capabilities: orderCapabilities(manifest.capabilities) } : {}),
     };
 }
+function orderCapabilities(c) {
+    return {
+        ...(c.realtime !== undefined ? { realtime: c.realtime } : {}),
+        ...(c.releaseRoute !== undefined ? { releaseRoute: c.releaseRoute } : {}),
+    };
+}
+/** Whether two manifests declare the same capabilities (missing and empty are the same). */
+export function sameCapabilities(a, b) {
+    return (a?.realtime ?? null) === (b?.realtime ?? null) && (a?.releaseRoute ?? null) === (b?.releaseRoute ?? null);
+}
 export function orderBinding(b) {
     const out = { key: b.key, page: b.page, collection: b.collection, target: b.target };
     if (b.field !== undefined)
@@ -382,5 +428,11 @@ export function compareManifests(local, remote) {
     const onlyLocal = local.bindings.filter((b) => !remoteByKey.has(b.key)).map((b) => b.key);
     const onlyRemote = remote.bindings.filter((b) => !localByKey.has(b.key)).map((b) => b.key);
     const changed = local.bindings.filter((b) => remoteByKey.has(b.key) && !sameBinding(b, remoteByKey.get(b.key))).map((b) => b.key);
-    return { same: onlyLocal.length === 0 && onlyRemote.length === 0 && changed.length === 0, onlyLocal, onlyRemote, changed };
+    return {
+        same: onlyLocal.length === 0 && onlyRemote.length === 0 && changed.length === 0,
+        onlyLocal,
+        onlyRemote,
+        changed,
+        capabilitiesDiffer: !sameCapabilities(local.capabilities, remote.capabilities),
+    };
 }

package/dist/pin.js

@@ -47,6 +47,9 @@ function pinField(f) {
     // 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 };
+    // translation is part of the schema hash too (§28.2)
+    if (f.localized === true)
+        out.localized = true;
     if (f.aliases && f.aliases.length > 0)
         out.aliases = [...f.aliases];
     return out;
@@ -195,6 +198,10 @@ export function diffSchema(before, after) {
             const under = af.key;
             const push = (op, detail, severity) => changes.push({ ...base, scope: "field", field: under, op, detail, severity });
             diffCommon(bf, af, names, push);
+            // §28.2: the site reads the default language either way until it asks for a locale
+            if ((bf.localized === true) !== (af.localized === true)) {
+                push("changed", af.localized === true ? "now translated — the site still reads the default language" : "no longer translated — the default language's value stays", "safe");
+            }
             if (bf.type === "relation" && af.type === "relation" && bf.relation && af.relation) {
                 if (bf.relation.target !== af.relation.target) {
                     push("changed", `relation to ${names.get(bf.relation.target) ?? bf.relation.target} → ${names.get(af.relation.target) ?? af.relation.target}`, "breaking");

package/dist/scan.d.ts

@@ -1,5 +1,5 @@
 import type * as TS from "typescript";
-import { type Manifest, type ManifestBinding, type ManifestPage } from "./manifest.js";
+import { type Manifest, type ManifestBinding, type ManifestCapabilities, type ManifestPage } from "./manifest.js";
 import type { Schema } from "./schema.js";
 /** `mapled scan` (§19.5, §21.4 — the standalone scanner of wave 2): reads
     the site's source and writes down what the code reads from Mapled —
@@ -37,22 +37,40 @@ export type ScanResult = {
     pages: ManifestPage[];
     bindings: ManifestBinding[];
     notes: string[];
+    /** what the code says the site can do (live updates of a Next.js site); undefined keeps the manifest's */
+    capabilities?: ManifestCapabilities;
 };
 export declare const SDK_METHODS: Set<string>;
 /** The repository's TypeScript, when it has one; the CLI ships none. */
 export declare function loadTypeScript(dir: string): TypeScriptModule | null;
+export declare function listFiles(dir: string, max: number): Promise<{
+    files: string[];
+    truncated: boolean;
+}>;
 export type RouteMap = {
     pages: Map<string, string>;
     layouts: Map<string, string>;
 };
+/** Next.js App Router segments: groups and slots vanish, params keep
+    the [param] form the manifest uses. */
+export declare function appRoute(segments: string[]): string | null;
 export declare function detectRoutes(files: string[], framework: string | null): RouteMap;
+/** `nl`: a line break comes before the token — a `return` followed by one returns nothing. */
+/** `nl`: a line break stands before the token; `escaped`: a string written
+    with a backslash escape, or an identifier with a `\u` escape in its
+    name; `unclosed`: a quoted string a line break (or the end) cut off
+    before its closing quote — JSX lets an attribute run on. */
 export type Token = {
     kind: "ident" | "string" | "punct";
     value: string;
+    nl?: true;
+    escaped?: true;
+    unclosed?: true;
 };
 /** JavaScript tokens: identifiers, string literals and punctuation, with
     comments and template bodies dropped. A regex literal after an
-    operator is skipped; JSX text is read as code, so an apostrophe in
+    operator is skipped — only one that closes on its line, and never the
+    `/>` after a JSX attribute's `}`; JSX text is read as code, so an apostrophe in
     prose can swallow a stretch — a false negative, never a crash. */
 export declare function tokenize(text: string): Token[];
 export declare function routeKey(route: string): string;
@@ -65,6 +83,8 @@ export type MergeResult = {
     /** Bindings the scan didn't produce: kept (or dropped with prune). */
     kept: string[];
     dropped: string[];
+    /** the scan changed what an existing manifest says the site can do */
+    capabilitiesChanged: boolean;
 };
 /** The scan's bindings replace the ones with the same key; bindings the
     scanner can't see (an agent's, hand-written) stay unless pruned. */

package/dist/scan.js

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { targetFor } from "./manifest.js";
+import { sameCapabilities, targetFor } from "./manifest.js";
 const SKIP_DIRS = new Set([
     "node_modules",
     ".git",
@@ -33,7 +33,7 @@ export function loadTypeScript(dir) {
         return null;
     }
 }
-async function listFiles(dir, max) {
+export async function listFiles(dir, max) {
     const files = [];
     let truncated = false;
     const walk = async (rel) => {
@@ -73,7 +73,7 @@ async function listFiles(dir, max) {
 const PAGE_EXT = /\.(tsx|jsx|ts|js|mjs|mdx|md|astro|svelte|vue)$/;
 /** Next.js App Router segments: groups and slots vanish, params keep
     the [param] form the manifest uses. */
-function appRoute(segments) {
+export function appRoute(segments) {
     const kept = [];
     for (const s of segments) {
         if (s.startsWith("_"))
@@ -753,18 +753,88 @@ function scopeOf(ts, id) {
     }
     return id.getSourceFile();
 }
+// what JavaScript reads as an identifier: Unicode letters and digits, `$`, `_`, and the two joiners inside one
+const ID_START = /^[\p{ID_Start}$_]$/u;
+const ID_PART = /^[\p{ID_Continue}$\p{Join_Control}]$/u;
+/** The identifier character at `at` as JavaScript reads it — itself, or a
+    `\u` escape that reads as one — and the index after it; null when none
+    is there. */
+function identCharAt(text, at, start) {
+    const c = text.charCodeAt(at);
+    if (Number.isNaN(c))
+        return null;
+    const test = start ? ID_START : ID_PART;
+    if (c === 92) {
+        if (text[at + 1] !== "u")
+            return null;
+        const [read, next] = unescapeAt(text, at);
+        // `\u` without its hex digits is no escape
+        return next > at + 2 && test.test(read) ? [read, next] : null;
+    }
+    // ASCII by its code: letters, `$`, `_`, and digits after the first
+    if (c < 128)
+        return (c >= 97 && c <= 122) || (c >= 65 && c <= 90) || c === 36 || c === 95 || (!start && c >= 48 && c <= 57) ? [text[at], at + 1] : null;
+    const ch = String.fromCodePoint(text.codePointAt(at));
+    return test.test(ch) ? [ch, at + ch.length] : null;
+}
+// `\n`, `\t` … by the letter, as character codes
+const SIMPLE_ESCAPES = { n: 10, r: 13, t: 9, b: 8, f: 12, v: 11 };
+/** The escape at `at` (a backslash) as JavaScript reads it in a string —
+    `\x6c`, `l`, `\u{6c}`, `\154`, `\n`, a line continuation, any other
+    character as itself — and the index after it. */
+function unescapeAt(text, at) {
+    const e = text[at + 1];
+    if (e === undefined)
+        return ["", at + 1];
+    const simple = SIMPLE_ESCAPES[e];
+    if (simple !== undefined)
+        return [String.fromCharCode(simple), at + 2];
+    const code = e.charCodeAt(0);
+    // a line continuation: the backslash and the line break read as nothing
+    if (e === "\r")
+        return ["", text[at + 2] === "\n" ? at + 3 : at + 2];
+    if (e === "\n" || code === 0x2028 || code === 0x2029)
+        return ["", at + 2];
+    if (e === "x" && /^[\da-f]{2}$/i.test(text.slice(at + 2, at + 4)))
+        return [String.fromCharCode(parseInt(text.slice(at + 2, at + 4), 16)), at + 4];
+    if (e === "u") {
+        if (text[at + 2] === "{") {
+            const close = text.indexOf("}", at + 3);
+            const hex = close === -1 ? "" : text.slice(at + 3, close);
+            if (/^[\da-f]{1,6}$/i.test(hex) && parseInt(hex, 16) <= 0x10ffff)
+                return [String.fromCodePoint(parseInt(hex, 16)), close + 1];
+        }
+        else if (/^[\da-f]{4}$/i.test(text.slice(at + 2, at + 6)))
+            return [String.fromCharCode(parseInt(text.slice(at + 2, at + 6), 16)), at + 6];
+    }
+    // a legacy octal escape: up to three digits, the value under 256
+    const octal = /^[0-3][0-7]{0,2}|^[4-7][0-7]?/.exec(text.slice(at + 1, at + 4));
+    if (octal)
+        return [String.fromCharCode(parseInt(octal[0], 8)), at + 1 + octal[0].length];
+    return [e, at + 2];
+}
 /** JavaScript tokens: identifiers, string literals and punctuation, with
     comments and template bodies dropped. A regex literal after an
-    operator is skipped; JSX text is read as code, so an apostrophe in
+    operator is skipped — only one that closes on its line, and never the
+    `/>` after a JSX attribute's `}`; JSX text is read as code, so an apostrophe in
     prose can swallow a stretch — a false negative, never a crash. */
 export function tokenize(text) {
     const out = [];
     let i = 0;
     const n = text.length;
     const REGEX_BEFORE = new Set(["(", ",", "=", ":", "[", "!", "&", "|", "?", "{", "}", ";", "return", "typeof", "=>"]);
+    let nl = false;
+    const push = (token) => {
+        if (nl)
+            token.nl = true;
+        nl = false;
+        out.push(token);
+    };
     while (i < n) {
         const c = text[i];
         if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+            if (c === "\n" || c === "\r")
+                nl = true;
             i++;
             continue;
         }
@@ -775,16 +845,22 @@ export function tokenize(text) {
         }
         if (c === "/" && text[i + 1] === "*") {
             const end = text.indexOf("*/", i + 2);
+            // a comment across lines is a line break
+            if (/[\n\r]/.test(text.slice(i + 2, end === -1 ? n : end)))
+                nl = true;
             i = end === -1 ? n : end + 2;
             continue;
         }
         if (c === '"' || c === "'" || c === "`") {
             let j = i + 1;
             let value = "";
+            let escaped = false;
             while (j < n && text[j] !== c) {
                 if (text[j] === "\\") {
-                    value += text[j + 1] ?? "";
-                    j += 2;
+                    const [read, next] = unescapeAt(text, j);
+                    value += read;
+                    j = next;
+                    escaped = true;
                     continue;
                 }
                 if (c === "`" && text[j] === "$" && text[j + 1] === "{") {
@@ -801,29 +877,51 @@ export function tokenize(text) {
                     value += "${}";
                     continue;
                 }
-                if (c !== "`" && text[j] === "\n")
+                if (c !== "`" && (text[j] === "\n" || text[j] === "\r"))
                     break;
                 value += text[j];
                 j++;
             }
-            out.push({ kind: "string", value: c === "`" && value.includes("${}") ? "${}" : value });
+            const token = { kind: "string", value: c === "`" && value.includes("${}") ? "${}" : value };
+            if (escaped)
+                token.escaped = true;
+            push(token);
+            // cut off by a line break: the break stays the next token's
+            if (text[j] !== c) {
+                token.unclosed = true;
+                i = j;
+                continue;
+            }
             i = j + 1;
             continue;
         }
-        if (/[A-Za-z_$]/.test(c)) {
-            let j = i + 1;
-            while (j < n && /[A-Za-z0-9_$]/.test(text[j]))
-                j++;
-            out.push({ kind: "ident", value: text.slice(i, j) });
+        // an identifier, escapes decoded: `end\u0070oint` is `endpoint`
+        const first = identCharAt(text, i, true);
+        if (first) {
+            let value = first[0];
+            let escaped = c === "\\";
+            let j = first[1];
+            for (let part = identCharAt(text, j, false); part; part = identCharAt(text, j, false)) {
+                if (text[j] === "\\")
+                    escaped = true;
+                value += part[0];
+                j = part[1];
+            }
+            const token = { kind: "ident", value };
+            if (escaped)
+                token.escaped = true;
+            push(token);
             i = j;
             continue;
         }
         if (c === "/") {
             const prev = out[out.length - 1];
-            if (!prev || (prev.kind === "punct" && REGEX_BEFORE.has(prev.value)) || (prev.kind === "ident" && REGEX_BEFORE.has(prev.value))) {
+            // `/>` after `}` closes a JSX element whose last attribute is an expression
+            const selfClosing = prev?.kind === "punct" && prev.value === "}" && text[i + 1] === ">";
+            if (!selfClosing && (!prev || (prev.kind === "punct" && REGEX_BEFORE.has(prev.value)) || (prev.kind === "ident" && REGEX_BEFORE.has(prev.value)))) {
                 let j = i + 1;
                 let inClass = false;
-                while (j < n && (inClass || text[j] !== "/") && text[j] !== "\n") {
+                while (j < n && (inClass || text[j] !== "/") && text[j] !== "\n" && text[j] !== "\r") {
                     if (text[j] === "\\")
                         j++;
                     else if (text[j] === "[")
@@ -832,19 +930,22 @@ export function tokenize(text) {
                         inClass = false;
                     j++;
                 }
-                j++;
-                while (j < n && /[a-z]/.test(text[j]))
-                    j++; // flags
-                i = j;
-                continue;
+                // a regex closes on its own line; a `/` that doesn't is the code's
+                if (text[j] === "/") {
+                    j++;
+                    while (j < n && /[a-z]/.test(text[j]))
+                        j++; // flags
+                    i = j;
+                    continue;
+                }
             }
         }
         if (c === "=" && text[i + 1] === ">") {
-            out.push({ kind: "punct", value: "=>" });
+            push({ kind: "punct", value: "=>" });
             i += 2;
             continue;
         }
-        out.push({ kind: "punct", value: c });
+        push({ kind: "punct", value: c });
         i++;
     }
     return out;
@@ -1293,6 +1394,8 @@ export function mergeManifest(existing, scan, opts) {
         pages: scan.pages,
         bindings: out,
         ...(existing?.notes && existing.notes.length > 0 ? { notes: existing.notes } : {}),
+        ...(scan.capabilities ? { capabilities: scan.capabilities } : existing?.capabilities ? { capabilities: existing.capabilities } : {}),
     };
-    return { manifest, added, changed, unchanged, kept, dropped };
+    const capabilitiesChanged = existing !== null && !sameCapabilities(existing.capabilities, manifest.capabilities);
+    return { manifest, added, changed, unchanged, kept, dropped, capabilitiesChanged };
 }

package/dist/schema.d.ts

@@ -41,6 +41,9 @@ export type SchemaField = {
         accepts it under these too until they are removed. Not part of the
         schema hash — a rename changes the key, which is. */
     aliases?: string[];
+    /** Translated (§28.2): the field holds a value per language; the site
+        reads the default language's. Absent on older servers. */
+    localized?: boolean;
 };
 export type SchemaCollection = {
     key: string;

package/dist/schema.js

@@ -31,6 +31,8 @@ export function schemaHash(schema) {
                 : null,
             // present only for computed fields, so schemas without formulas hash as before
             ...(f.type === "computed" && f.computed ? { computed: { expression: f.computed.expression, resultType: f.computed.resultType } } : {}),
+            // present only for translated fields, so schemas without translations hash as before
+            ...(f.localized === true ? { localized: true } : {}),
         })),
     }));
     return createHash("sha256").update(JSON.stringify(projection)).digest("hex").slice(0, 12);

package/package.json

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