@mapled/cli 0.10.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/report.d.ts

@@ -0,0 +1,127 @@
+import { type Check } from "./doctor.js";
+/** `mapled integration report` (§29.9, §31.2): the last setup run Mapled
+    holds for the project with its Verification checklist — the lines,
+    statuses and fix hints of S-42 — and what the agent reported. Nearly
+    every string here was typed by an agent or a member: it is cleaned of
+    control characters, and anything shaped like a Mapled key or token is
+    masked before it reaches the terminal or the JSON (§36.12 — the report
+    carries no secret, whatever an agent wrote into it). */
+export type RunStatus = "awaiting_approval" | "approved" | "rejected" | "applying" | "verifying" | "checks_failed" | "completed" | "completed_with_warnings" | "failed";
+/** A run as `GET /v1/agent/runs` lists it. */
+export type RunSummary = {
+    id: string;
+    clientName: string;
+    status: RunStatus;
+    summary: string;
+    createdAt: string;
+    appliedAt: string | null;
+    verifiedAt: string | null;
+    completedAt: string | null;
+};
+/** A run as `GET /v1/agent/runs/:id` shows it. */
+export type RunDetail = RunSummary & {
+    result: {
+        collections?: {
+            key: string;
+            displayName: string;
+            kind: string;
+            fieldKeys?: string[];
+            recordsCreated?: number;
+        }[];
+        warnings?: string[];
+        report?: {
+            filesChanged?: string[];
+            stillHardcoded?: string[];
+            warnings?: string[];
+            previewUrl?: string | null;
+        };
+        checks?: Check[];
+    } | null;
+};
+export type IntegrationReport = {
+    project: {
+        id: string;
+        name: string;
+    };
+    run: {
+        id: string;
+        client: string;
+        status: RunStatus;
+        summary: string;
+        createdAt: string;
+        appliedAt: string | null;
+        verifiedAt: string | null;
+    } | null;
+    /** A later plan than the one reported, not applied (yet). */
+    newer: {
+        id: string;
+        client: string;
+        status: RunStatus;
+        createdAt: string;
+    } | null;
+    checks: Check[];
+    collections: {
+        key: string;
+        displayName: string;
+        kind: string;
+        fields: number;
+        records: number;
+    }[];
+    filesChanged: string[];
+    stillHardcoded: string[];
+    warnings: string[];
+    previewUrl: string | null;
+};
+export declare const isChecked: (status: RunStatus) => boolean;
+/** Mapled's keys and tokens, with the length and alphabet of the random
+    part Mapled issues: delivery and server keys — 16 bytes in hex
+    (`lib/deliveryKeys.ts`); agent, OAuth and code tokens — 32 bytes in
+    base64url (`generateToken`); preview links, draft sessions and the
+    webhook secret — 24 bytes in hex. The webhook secret's prefix is the
+    one of Standard Webhooks, and other issuers (Polar, Svix) write it
+    before base64 of 24 bytes or more, `+`, `/` and the `=` padding
+    included: the last kind, read up to its shortest length, so a site's
+    own secret doesn't show either. Mapled doesn't issue that one, so
+    behind a prefix written wholly in look-alikes it reads as text
+    (`keyLike`). */
+export declare const KEYS: readonly (readonly [prefix: string, length: number, alphabet: "hex" | "base64url" | "base64"])[];
+/** One line of text fit for a terminal: no control, blank-looking or
+    invisible characters, nothing that reads as a Mapled key. */
+export declare function clean(text: unknown, max?: number): string;
+/** The page an agent reported as its preview, without what may carry a
+    credential: no query, no fragment, no user info. The path is shown
+    decoded, so a key written in percent escapes is masked like any other;
+    a path that doesn't decode cleanly — malformed, or still escaped after
+    one decoding (encoded twice) — is dropped, and only the origin shows. */
+export declare function reportedPage(url: unknown): string | null;
+/** The run to report: the one applied last (an older plan can be applied
+    after a newer one); before any was applied, the newest there is. The
+    newer plan is the newest one proposed after it and not applied. */
+export declare function pickRun(runs: RunSummary[]): {
+    shown: RunSummary | null;
+    newer: RunSummary | null;
+};
+export declare function buildReport(project: {
+    id: string;
+    name: string;
+}, run: RunDetail | null, newer: RunSummary | null): IntegrationReport;
+/** The closing line: what to do next. */
+export declare function reportSummary(report: IntegrationReport): string;
+export declare function formatReport(report: IntegrationReport, color: boolean): string[];
+/** What `POST /v1/agent/preview` answers. */
+export type PreviewAnswer = {
+    status: "ok";
+    url: string;
+    expiresAt?: string;
+    path: string | null;
+} | {
+    status: "not_deployed";
+    origin: string;
+    path: string | null;
+} | {
+    status: "not_set_up";
+    origin: string;
+    path: string | null;
+};
+/** "5 minutes" until the link stops working, or null when unknown. */
+export declare function linkLifetime(expiresAt: string | undefined, now?: number): string | null;