@mapled/cli 0.7.1 → 0.8.0

package/README.md

@@ -175,7 +175,7 @@ Mapled doctor — Dolphin Landing
 ✓ Environment          MAPLED_KEY and MAPLED_WEBHOOK_SECRET in .env.local
 ✓ Secrets in git       No env files or Mapled secrets are tracked.
 ✓ @mapled/next         0.8.0 (current)
-✓ mapled CLI           0.7.1 (current)
+✓ mapled CLI           0.8.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
@@ -188,6 +188,8 @@ Mapled doctor — Dolphin Landing
 
 The repository side: the link, the sign-in, the generated types, the schema pin, the site manifest (and whether it matches what was pushed), the integration hash — one line saying whether the pin and the manifest here describe the same integration Mapled holds, and if not, what moved (the schema, the bindings, or edits made in Mapled) and which command catches up — `MAPLED.md` (and whether it is what Mapled would render now), `MAPLED_KEY` and `MAPLED_WEBHOOK_SECRET` in your env files (names only — values are never read out), env files or Mapled secrets tracked by git, the installed `@mapled/next` and CLI versions, the revalidation and preview routes of a Next.js site. The Mapled side, from the same status the AI agent's `check_integration` tool reads: whether the site has read content with the delivery key, the publish webhook and its last delivery, the preview route on the deployed site, the bindings health.
 
+A site rendered in the visitor's browser — a React single-page app (Vite and the like), plain HTML — is checked for what it has: the package line is `@mapled/react` (or `@mapled/client`), Environment wants `VITE_MAPLED_KEY` and no webhook secret, and the routes and the webhook read ○ «Not needed» — such a site shows a publish on its next load and trades Mapled's preview link on the page itself. doctor takes the framework from `mapled.json`, or works it out from `package.json`. Whatever the framework, a server key or a signing secret under a public prefix (`VITE_…`, `NEXT_PUBLIC_…`) is a ✗: it would ship to every visitor.
+
 Exit code 1 when something is marked ✗; `--json` prints the checks for scripts and agents.
 
 ## Options

package/dist/commands.js

@@ -142,7 +142,8 @@ async function openSession(ctx, flags) {
 export async function generate(ctx, flags) {
     const { found, session } = await openSession(ctx, flags);
     const schema = await session.get("/v1/agent/schema");
-    const generated = generateTypes(schema, { projectName: session.conn.projectName });
+    const framework = found.config.framework ?? (await dr.detectFramework(found.dir));
+    const generated = generateTypes(schema, { projectName: session.conn.projectName, sdk: dr.sdkOf(framework) });
     const out = stringFlag(flags, "out") ?? found.config.types ?? DEFAULT_TYPES_PATH;
     const file = path.resolve(found.dir, out);
     await writeFile(file, generated.text);
@@ -582,7 +583,7 @@ export async function doctor(ctx, flags) {
     checks.push(dr.checkAuth({ conn: conn ?? null, status, error: authError }));
     const typesPath = found?.config.types ?? DEFAULT_TYPES_PATH;
     const existing = await readFile(path.join(dir, typesPath), "utf8").catch(() => null);
-    checks.push(dr.checkTypes(existing, schema ? generateTypes(schema, { projectName: status?.project.name }) : null, typesPath));
+    checks.push(dr.checkTypes(existing, schema ? generateTypes(schema, { projectName: status?.project.name, sdk: dr.sdkOf(found?.config.framework ?? (await dr.detectFramework(dir))) }) : null, typesPath));
     const pin = found ? await readPin(dir).catch(() => null) : null;
     const livePin = schema && found ? pinSchema(schema, found.config.project) : null;
     const pinChanges = pin && livePin ? diffSchema(pin.pin.collections, livePin.collections) : null;
@@ -600,16 +601,19 @@ export async function doctor(ctx, flags) {
     checks.push(dr.checkManifestFile(localManifest ? { manifest: localManifest.manifest, problems: localManifest.problems } : null, remoteManifest));
     checks.push(dr.checkIntegration({ pin: pin?.pin ?? null, manifest: localManifest?.manifest ?? null }, conn && status ? { integration: status.integration, manifest: remoteManifest } : null));
     checks.push(checkMapledMd(await readFile(path.join(dir, MD_FILE), "utf8").catch(() => null), guide));
-    checks.push(dr.checkEnv(await dr.envNames(dir), ctx.env));
+    const framework = found?.config.framework ?? (await dr.detectFramework(dir));
+    // a site rendered in the browser has no webhook, no routes and no secret to check
+    const browser = dr.rendersInBrowser(framework);
+    const sdk = dr.sdkOf(framework);
+    checks.push(dr.checkEnv(await dr.envNames(dir), ctx.env, framework));
     checks.push(dr.checkSecrets(await dr.gitFacts(dir)));
-    checks.push(dr.checkSdk(await dr.installedVersion(dir, "@mapled/next"), status?.sdk["@mapled/next"]));
+    checks.push(dr.checkSdk(await dr.installedVersion(dir, sdk), status?.sdk[sdk], sdk));
     checks.push(dr.checkCli(ctx.version, status?.sdk["@mapled/cli"]));
-    const framework = found?.config.framework ?? (await dr.detectFramework(dir));
     checks.push(dr.checkRoute("revalidate", await dr.findRoute(dir, "revalidate"), framework));
     checks.push(dr.checkRoute("preview", await dr.findRoute(dir, "preview"), framework));
     if (status) {
         checks.push(dr.checkReads(status.delivery.lastReadAt));
-        checks.push(dr.checkWebhook(status.webhook));
+        checks.push(dr.checkWebhook(status.webhook, { local: browser, remote: status.site }));
         let origin = null;
         try {
             origin = status.webhook.url ? new URL(status.webhook.url).origin : null;
@@ -617,8 +621,15 @@ export async function doctor(ctx, flags) {
         catch {
             origin = null;
         }
-        const probe = origin ? await dr.probePreview(origin, status.previewPath, ctx.fetch) : null;
-        checks.push(dr.checkPreviewOnSite(origin, status.previewPath, probe));
+        if (browser) {
+            // no route to probe: the page itself, where Mapled knows the site to live
+            origin = origin ?? status.site?.url ?? null;
+            checks.push(dr.checkPreviewOnSite(origin, status.previewPath, origin ? await dr.probeSite(origin, ctx.fetch) : null, true));
+        }
+        else {
+            const probe = origin ? await dr.probePreview(origin, status.previewPath, ctx.fetch) : null;
+            checks.push(dr.checkPreviewOnSite(origin, status.previewPath, probe));
+        }
         checks.push(dr.checkBindings(status.bindings));
     }
     else {

package/dist/doctor.d.ts

@@ -51,6 +51,12 @@ export type IntegrationStatus = {
     };
     /** the integration hash (§21.4); missing from an API older than the hash */
     integration?: IntegrationState;
+    /** what Mapled takes the site for, and where Preview opens it; missing from an older API */
+    site?: {
+        framework: string;
+        rendering: "server" | "browser";
+        url: string | null;
+    };
     previewPath: string;
     sdk: Record<string, string>;
 };
@@ -87,6 +93,13 @@ export type PackageVersion = {
     declared: string | null;
 };
 export declare function installedVersion(dir: string, pkg: string): Promise<PackageVersion>;
+/** A site rendered in the visitor's browser — a React single-page app,
+    plain HTML — reads Mapled from the page: a publish shows on the next
+    load, so it has no webhook, no routes to mount and no secret. The two
+    keys are the ones Mapled knows by (lib/siteStack.ts of the API). */
+export declare const rendersInBrowser: (framework: string | null | undefined) => boolean;
+/** The first-party package a site of this framework reads through. */
+export declare const sdkOf: (framework: string | null | undefined) => string;
 export declare function detectFramework(dir: string): Promise<string | undefined>;
 /** -1, 0 or 1 comparing dotted numeric versions; anything else compares by number. */
 export declare function compareVersions(a: string, b: string): number;
@@ -101,6 +114,11 @@ export declare function findRoute(dir: string, kind: RouteKind): Promise<RouteFi
 export declare function probePreview(origin: string, previewPath: string, f: Fetch): Promise<{
     status: number | null;
 }>;
+/** A page of a site rendered in the browser: any answer means it is
+    deployed (a single-page app's host may say 404 and serve the app anyway). */
+export declare function probeSite(origin: string, f: Fetch): Promise<{
+    status: number | null;
+}>;
 export declare function checkLink(found: {
     path: string;
 } | null, projectName: string | null): Check;
@@ -110,16 +128,19 @@ export declare function checkAuth(state: {
     error: string | null;
 }): Check;
 export declare function checkTypes(existing: string | null, generated: Generated | null, typesPath: string): Check;
-export declare function checkEnv(names: Map<string, string>, env: NodeJS.ProcessEnv): Check;
+export declare function checkEnv(names: Map<string, string>, env: NodeJS.ProcessEnv, framework?: string | null): Check;
 export declare function checkSecrets(facts: GitFacts): Check;
-export declare function checkSdk(pkg: PackageVersion, latest: string | undefined): Check;
+export declare function checkSdk(pkg: PackageVersion, latest: string | undefined, name?: string): Check;
 export declare function checkCli(current: string, latest: string | undefined): Check;
 export declare function checkRoute(kind: RouteKind, found: RouteFile | null, framework: string | undefined): Check;
 export declare function checkReads(lastReadAt: string | null): Check;
-export declare function checkWebhook(webhook: IntegrationStatus["webhook"]): Check;
+export declare function checkWebhook(webhook: IntegrationStatus["webhook"], site?: {
+    local: boolean;
+    remote: IntegrationStatus["site"];
+}): Check;
 export declare function checkPreviewOnSite(origin: string | null, previewPath: string, probe: {
     status: number | null;
-} | null): Check;
+} | null, browser?: boolean): Check;
 export declare function checkBindings(bindings: IntegrationStatus["bindings"]): Check;
 export declare function checkSchemaPin(pin: SchemaPin | null, liveHash: string | null, changes: SchemaChange[] | null): Check;
 /** The pushed manifest as `GET /v1/agent/manifest` answers it. */

package/dist/doctor.js

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { readFile } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { integrationHash } from "./integrationHash.js";
@@ -102,26 +102,43 @@ export async function installedVersion(dir, pkg) {
     }
     return { installed, declared };
 }
+/** A site rendered in the visitor's browser — a React single-page app,
+    plain HTML — reads Mapled from the page: a publish shows on the next
+    load, so it has no webhook, no routes to mount and no secret. The two
+    keys are the ones Mapled knows by (lib/siteStack.ts of the API). */
+export const rendersInBrowser = (framework) => framework === "react-spa" || framework === "plain-html";
+/** The first-party package a site of this framework reads through. */
+export const sdkOf = (framework) => !framework || framework === "nextjs" ? "@mapled/next" : framework === "react-spa" ? "@mapled/react" : "@mapled/client";
 export async function detectFramework(dir) {
+    const hasIndexHtml = () => access(path.join(dir, "index.html")).then(() => true, () => false);
+    let deps;
     try {
         const raw = await readFile(path.join(dir, "package.json"), "utf8");
         const p = JSON.parse(raw);
-        const deps = { ...p.devDependencies, ...p.dependencies };
-        if (deps.next)
-            return "nextjs";
-        if (deps.astro)
-            return "astro";
-        if (deps.nuxt)
-            return "nuxt";
-        if (deps["@sveltejs/kit"])
-            return "sveltekit";
-        if (deps["@remix-run/react"] || deps["react-router"])
-            return "remix";
-        return undefined;
+        deps = { ...p.devDependencies, ...p.dependencies };
     }
     catch {
-        return undefined;
-    }
+        // no package.json at all: pages written by hand
+        return (await hasIndexHtml()) ? "plain-html" : undefined;
+    }
+    if (deps.next)
+        return "nextjs";
+    if (deps.astro)
+        return "astro";
+    if (deps.nuxt)
+        return "nuxt";
+    if (deps["@sveltejs/kit"])
+        return "sveltekit";
+    // react-router alone is a library a single-page app routes with; its framework mode brings @react-router/dev
+    if (deps["@remix-run/react"] || deps["@react-router/dev"])
+        return "remix";
+    if (deps.react && (deps.vite || deps["@vitejs/plugin-react"] || deps["@vitejs/plugin-react-swc"] || deps["react-scripts"] || deps["@mapled/react"])) {
+        return "react-spa";
+    }
+    if (!deps.react && !deps.vue && !deps.svelte && !deps["solid-js"] && !deps.express && !deps.fastify && (await hasIndexHtml())) {
+        return "plain-html";
+    }
+    return undefined;
 }
 /** -1, 0 or 1 comparing dotted numeric versions; anything else compares by number. */
 export function compareVersions(a, b) {
@@ -186,6 +203,17 @@ export async function probePreview(origin, previewPath, f) {
     }
 }
 /* ---- the checks ---- */
+/** A page of a site rendered in the browser: any answer means it is
+    deployed (a single-page app's host may say 404 and serve the app anyway). */
+export async function probeSite(origin, f) {
+    try {
+        const res = await f(`${origin}/`, { method: "GET", redirect: "manual", signal: AbortSignal.timeout(5000) });
+        return { status: res.status };
+    }
+    catch {
+        return { status: null };
+    }
+}
 export function checkLink(found, projectName) {
     const label = "Project link";
     if (!found)
@@ -218,9 +246,36 @@ export function checkTypes(existing, generated, typesPath) {
     }
     return { key: "types", label, status: "warning", detail: `${typesPath} is out of date — run \`mapled types generate\`.` };
 }
-export function checkEnv(names, env) {
+/** Prefixes that put an env var into the browser's bundle. */
+const PUBLIC_ENV = /^(VITE_|REACT_APP_|NEXT_PUBLIC_|NUXT_PUBLIC_|PUBLIC_|GATSBY_)/;
+export function checkEnv(names, env, framework) {
     const label = "Environment";
     const where = (name) => names.get(name) ?? (env[name] ? "the environment" : null);
+    // whatever the framework: a server key or a signing secret under a public prefix ships to every visitor
+    const exposed = [...names.keys()].filter((n) => PUBLIC_ENV.test(n) && /MAPLED/.test(n) && /(SERVER_KEY|SECRET)/.test(n));
+    if (exposed.length > 0) {
+        return {
+            key: "env",
+            label,
+            status: "failed",
+            detail: `${exposed.join(", ")} in ${names.get(exposed[0])} is bundled into the browser. Only the delivery key may be: rename it and rotate the value in Integrations.`,
+        };
+    }
+    if (framework === "plain-html") {
+        return { key: "env", label, status: "skipped", detail: "No env files: the delivery key sits in the page — the one key that is safe there." };
+    }
+    if (framework === "react-spa") {
+        const name = ["VITE_MAPLED_KEY", "REACT_APP_MAPLED_KEY"].find((n) => where(n));
+        if (!name) {
+            return {
+                key: "env",
+                label,
+                status: "failed",
+                detail: "VITE_MAPLED_KEY isn't set. Put the delivery key (Integrations → Your site) in .env — it is the one key that is safe in a browser.",
+            };
+        }
+        return { key: "env", label, status: "passed", detail: `${name} in ${where(name)} — no webhook secret needed: the site reads in the browser` };
+    }
     const key = where("MAPLED_KEY");
     const secret = where("MAPLED_WEBHOOK_SECRET");
     if (!key) {
@@ -268,10 +323,10 @@ export function checkSecrets(facts) {
     }
     return { key: "secrets", label, status: "passed", detail: "No env files or Mapled secrets are tracked." };
 }
-export function checkSdk(pkg, latest) {
-    const label = "@mapled/next";
+export function checkSdk(pkg, latest, name = "@mapled/next") {
+    const label = name;
     if (!pkg.installed && !pkg.declared) {
-        return { key: "sdk", label, status: "failed", detail: "Not installed. Run `npm install @mapled/next`." };
+        return { key: "sdk", label, status: "failed", detail: `Not installed. Run \`npm install ${name}\`.` };
     }
     if (!pkg.installed) {
         return { key: "sdk", label, status: "warning", detail: `${pkg.declared} is declared but not installed — run npm install.` };
@@ -283,7 +338,7 @@ export function checkSdk(pkg, latest) {
             key: "sdk",
             label,
             status: "warning",
-            detail: `${pkg.installed} installed, ${latest} available — npm install @mapled/next@latest.`,
+            detail: `${pkg.installed} installed, ${latest} available — npm install ${name}@latest.`,
         };
     }
     return { key: "sdk", label, status: "passed", detail: `${pkg.installed} (current)` };
@@ -299,6 +354,16 @@ export function checkRoute(kind, found, framework) {
     const key = `route_${kind}`;
     const label = kind === "revalidate" ? "Revalidation route" : "Preview route";
     const handler = ROUTE_HANDLER[kind];
+    if (rendersInBrowser(framework)) {
+        return {
+            key,
+            label,
+            status: "skipped",
+            detail: kind === "revalidate"
+                ? "Not needed: the site reads in the browser, so a publish shows on the next load."
+                : "Not needed: the client trades Mapled's preview link on the page itself.",
+        };
+    }
     if (framework && framework !== "nextjs") {
         return { key, label, status: "skipped", detail: `No ${kind} route check for ${framework} sites yet.` };
     }
@@ -334,8 +399,20 @@ export function checkReads(lastReadAt) {
     }
     return { key: "reads", label, status: "passed", detail: `Last read ${ago(lastReadAt)}` };
 }
-export function checkWebhook(webhook) {
+export function checkWebhook(webhook, site) {
     const label = "Publish webhook";
+    if (!webhook.url && site?.local) {
+        // the repository renders in the browser; does Mapled know?
+        if (site.remote && site.remote.rendering !== "browser") {
+            return {
+                key: "webhook",
+                label,
+                status: "warning",
+                detail: `Mapled takes this site for ${site.remote.framework} and will ask for a webhook: run \`mapled scan --write\` and \`mapled bindings push\` so it knows the site renders in the browser.`,
+            };
+        }
+        return { key: "webhook", label, status: "skipped", detail: "Not needed: the site reads in the browser, so a publish shows on the next load." };
+    }
     if (!webhook.url) {
         return {
             key: "webhook",
@@ -377,8 +454,21 @@ export function checkWebhook(webhook) {
         detail: `The last delivery to ${host} ${reason}. Check the route and MAPLED_WEBHOOK_SECRET, then send a test ping.`,
     };
 }
-export function checkPreviewOnSite(origin, previewPath, probe) {
+export function checkPreviewOnSite(origin, previewPath, probe, browser = false) {
     const label = "Preview on the site";
+    if (browser) {
+        if (!origin || !probe) {
+            return {
+                key: "preview_site",
+                label,
+                status: "warning",
+                detail: "Mapled doesn't know where the site is deployed — set Production domain in Project settings, or ask your agent (set_site_url).",
+            };
+        }
+        return probe.status === null
+            ? { key: "preview_site", label, status: "warning", detail: `${origin} is unreachable from here.` }
+            : { key: "preview_site", label, status: "passed", detail: `Opens at ${origin} — the client trades the link in the browser` };
+    }
     if (!origin || !probe) {
         return { key: "preview_site", label, status: "skipped", detail: "Needs the webhook URL to know where the site lives." };
     }

package/dist/types.d.ts

@@ -21,6 +21,7 @@ export declare function typeName(key: string, kind: "collection" | "single"): st
 export declare function typeNames(collections: SchemaCollection[]): Map<string, string>;
 export declare function generateTypes(schema: Schema, opts?: {
     projectName?: string;
+    sdk?: string;
 }): Generated;
 /** Splits a generated file into its header and body, with the hash the
     header names when it has one. */

package/dist/types.js

@@ -177,14 +177,18 @@ export function typeNames(collections) {
     return out;
 }
 export function generateTypes(schema, opts = {}) {
+    // the package the site reads through: "@mapled/next" unless the framework says otherwise
+    const sdk = opts.sdk ?? "@mapled/next";
+    // a React app's assetUrl comes from the client its hooks are built on
+    const assets = sdk === "@mapled/react" ? "@mapled/client" : sdk;
     const hash = schemaHash(schema);
     const names = typeNames(schema.collections);
     const blocks = [];
     blocks.push([
-        "// Types of the published content this site reads through @mapled/next.",
+        `// Types of the published content this site reads through ${sdk}.`,
         "// Sensitive fields never reach the site and are left out.",
         "",
-        '/** An asset id — pass it to assetUrl(id, { width }) from "@mapled/next". */',
+        `/** An asset id — pass it to assetUrl(id, { width }) from "${assets}". */`,
         "export type MapledAssetId = string;",
         '/** The id of a record in another collection — attach it with { expand: ["field"] }. */',
         "export type MapledRecordId = string;",

package/package.json

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