@forumulate/cli 0.8.0 → 0.10.0

package/dist/credentials.d.ts

@@ -10,8 +10,10 @@
  * Keyed by API base URL, so a token for staging cannot be sent to production by
  * forgetting to change one variable.
  *
- * `FORUMULATE_TOKEN` still wins when it is set. CI sets it, and a file on disk
- * silently overriding what a pipeline passed in would be the worse surprise.
+ * `FORUMULATE_TOKEN` still wins over the file when it is set. CI sets it, and a
+ * file on disk silently overriding what a pipeline passed in would be the worse
+ * surprise. A `--token` on the command line wins over both: it is the most
+ * specific thing the caller said.
  */
 export interface Credentials {
     /** baseUrl → token. */
@@ -19,8 +21,45 @@ export interface Credentials {
 }
 export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
 export declare function readCredentials(env?: NodeJS.ProcessEnv): Credentials;
-/** The token for a base URL: the environment first, then what `login` stored. */
-export declare function resolveToken(baseUrl: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** Where a token came from (FMU-D06): the answer `whoami` prints first. */
+export type TokenSource = 'flag' | 'env' | 'credentials' | 'none';
+/**
+ * The token for a base URL, and where it was found: `--token` beats
+ * `FORUMULATE_TOKEN` beats `credentials.json`. An integrator with one PAT in
+ * the shell, another in the file and a third in CI could not tell which one a
+ * 401 was about; this is the precedence, said once.
+ */
+export declare function resolveTokenSource(baseUrl: string, env?: NodeJS.ProcessEnv, flagToken?: string): {
+    token?: string;
+    source: TokenSource;
+    path?: string;
+};
+/**
+ * The token for a base URL, by the same precedence as `resolveTokenSource`:
+ * `--token`, then the environment, then what `login` stored.
+ *
+ * This used to skip the flag. `cli.ts` read `--token` for the SDK client only,
+ * so `whoami --token x` used x while `items list --token x`, `api …`, `doctor
+ * --site` and `validate` (each building its own transport through here) sent
+ * `FORUMULATE_TOKEN` or the stored token instead: the documented precedence
+ * held for two commands (FMU-DOC01). One resolver, every caller.
+ */
+export declare function resolveToken(baseUrl: string, env?: NodeJS.ProcessEnv, flagToken?: string): string | undefined;
+/**
+ * Take the global `--token <pat>` / `--token=<pat>` out of an argument list.
+ *
+ * The older commands in `run.ts` parse against a fixed list of value flags,
+ * so the flag and its value are removed before they see the arguments. The
+ * `api` and resource commands get the arguments as given: there an operation
+ * that declares a `token` parameter (a registry's, a GitHub connection's)
+ * owns the flag, and `api/request.ts` keeps it out of the query string
+ * everywhere else. Nothing after `--` is touched; the last `--token` wins, as
+ * with every other repeated flag.
+ */
+export declare function takeTokenFlag(argv: string[]): {
+    argv: string[];
+    token?: string;
+};
 export declare function storeToken(baseUrl: string, token: string, env?: NodeJS.ProcessEnv): string;
 export declare function forgetToken(baseUrl: string, env?: NodeJS.ProcessEnv): boolean;
 /** One spelling per host: a trailing slash is not a different server. */

package/dist/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC1B,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAO5E;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,WAAW,CASjF;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAUR;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAiB1F;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW;IAC1B,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAO5E;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,WAAW,CASjF;AAED,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,aAAa,GAAG,MAAM,CAAC;AAElE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,SAAS,CAAC,EAAE,MAAM,GACjB;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAMxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAEpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAqBhF;AAED,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAUR;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAiB1F;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/credentials.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.credentialsPath = credentialsPath;
 exports.readCredentials = readCredentials;
+exports.resolveTokenSource = resolveTokenSource;
 exports.resolveToken = resolveToken;
+exports.takeTokenFlag = takeTokenFlag;
 exports.storeToken = storeToken;
 exports.forgetToken = forgetToken;
 exports.normalizeBase = normalizeBase;
@@ -27,11 +29,72 @@ function readCredentials(env = process.env) {
         return { tokens: {} };
     }
 }
-/** The token for a base URL: the environment first, then what `login` stored. */
-function resolveToken(baseUrl, env = process.env) {
+/**
+ * The token for a base URL, and where it was found: `--token` beats
+ * `FORUMULATE_TOKEN` beats `credentials.json`. An integrator with one PAT in
+ * the shell, another in the file and a third in CI could not tell which one a
+ * 401 was about; this is the precedence, said once.
+ */
+function resolveTokenSource(baseUrl, env = process.env, flagToken) {
+    if (flagToken?.trim())
+        return { token: flagToken.trim(), source: 'flag' };
     if (env.FORUMULATE_TOKEN)
-        return env.FORUMULATE_TOKEN;
-    return readCredentials(env).tokens[normalizeBase(baseUrl)];
+        return { token: env.FORUMULATE_TOKEN, source: 'env' };
+    const stored = readCredentials(env).tokens[normalizeBase(baseUrl)];
+    if (stored)
+        return { token: stored, source: 'credentials', path: credentialsPath(env) };
+    return { source: 'none' };
+}
+/**
+ * The token for a base URL, by the same precedence as `resolveTokenSource`:
+ * `--token`, then the environment, then what `login` stored.
+ *
+ * This used to skip the flag. `cli.ts` read `--token` for the SDK client only,
+ * so `whoami --token x` used x while `items list --token x`, `api …`, `doctor
+ * --site` and `validate` (each building its own transport through here) sent
+ * `FORUMULATE_TOKEN` or the stored token instead: the documented precedence
+ * held for two commands (FMU-DOC01). One resolver, every caller.
+ */
+function resolveToken(baseUrl, env = process.env, flagToken) {
+    return resolveTokenSource(baseUrl, env, flagToken).token;
+}
+/**
+ * Take the global `--token <pat>` / `--token=<pat>` out of an argument list.
+ *
+ * The older commands in `run.ts` parse against a fixed list of value flags,
+ * so the flag and its value are removed before they see the arguments. The
+ * `api` and resource commands get the arguments as given: there an operation
+ * that declares a `token` parameter (a registry's, a GitHub connection's)
+ * owns the flag, and `api/request.ts` keeps it out of the query string
+ * everywhere else. Nothing after `--` is touched; the last `--token` wins, as
+ * with every other repeated flag.
+ */
+function takeTokenFlag(argv) {
+    const rest = [];
+    let token;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--') {
+            rest.push(...argv.slice(i));
+            break;
+        }
+        if (a.startsWith('--token='))
+            token = a.slice('--token='.length);
+        else if (a === '--token') {
+            const next = argv[i + 1];
+            // `--token --json` is a missing value, not a token called "--json".
+            if (next !== undefined && !next.startsWith('-')) {
+                token = next;
+                i += 1;
+            }
+            else
+                token = '';
+        }
+        else
+            rest.push(a);
+    }
+    const trimmed = token?.trim();
+    return { argv: rest, token: trimmed ? trimmed : undefined };
 }
 function storeToken(baseUrl, token, env = process.env) {
     const path = credentialsPath(env);

package/dist/credentials.js.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"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"}

package/dist/dev/command.d.ts

@@ -0,0 +1,41 @@
+import type { ForumulateClient } from '@forumulate/sdk';
+/**
+ * `forumulate dev <folder> --space <spaceId> [--org <orgId>] [--port 4321] [--site <url>]`
+ * — a local preview of a docs folder, reloading as you save (Mintlify's
+ * `mint dev`, Docusaurus's `start`; DOCS #244).
+ *
+ * Every page is rendered by the API's own renderer (`POST …/docs/render`),
+ * not by a second one shipped in the CLI, so what you see is what readers
+ * will get. `--site` (your published docs address) lends the preview its
+ * look: the stylesheets that page links and the theme it inlines are copied
+ * once into each preview page. Nothing is written anywhere.
+ */
+export interface DevOptions {
+    folder: string;
+    org?: string;
+    space?: string;
+    port: number;
+    site?: string;
+}
+export interface DevDeps {
+    client: ForumulateClient;
+    out: (line: string) => void;
+    err: (line: string) => void;
+    /** Injected so tests can stop it; production keeps the process alive. */
+    onListening?: (close: () => void) => void;
+}
+/** Every Markdown file under the folder, as `/`-separated relative paths, sorted. */
+export declare function markdownFiles(folder: string, dir?: string): string[];
+/** The stylesheet links and inline theme of a published page, to dress the preview in. */
+export declare function themeOf(html: string, site: string): string;
+/** One preview document: the nav of files, the rendered body, and the reload hook. */
+export declare function previewPage(opts: {
+    title: string;
+    heading?: string | null;
+    body: string;
+    files: string[];
+    current: string | null;
+    theme: string;
+}): string;
+export declare function runDev(opts: DevOptions, deps: DevDeps): Promise<number>;
+//# sourceMappingURL=command.d.ts.map

package/dist/dev/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/dev/command.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,yEAAyE;IACzE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CAC3C;AAID,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,MAAM,EAAE,CAShE;AAED,0FAA0F;AAC1F,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAKD,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAWT;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAwH7E"}

package/dist/dev/command.js

@@ -0,0 +1,158 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.markdownFiles = markdownFiles;
+exports.themeOf = themeOf;
+exports.previewPage = previewPage;
+exports.runDev = runDev;
+const node_http_1 = require("node:http");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const frontmatter_1 = require("../publish/frontmatter");
+const PAGE = /\.(md|mdx|markdown)$/i;
+/** Every Markdown file under the folder, as `/`-separated relative paths, sorted. */
+function markdownFiles(folder, dir = '') {
+    const out = [];
+    for (const name of (0, node_fs_1.readdirSync)(node_path_1.default.join(folder, dir))) {
+        if (name.startsWith('.') || name === 'node_modules')
+            continue;
+        const rel = dir ? `${dir}/${name}` : name;
+        if ((0, node_fs_1.statSync)(node_path_1.default.join(folder, rel)).isDirectory())
+            out.push(...markdownFiles(folder, rel));
+        else if (PAGE.test(name))
+            out.push(rel);
+    }
+    return out.sort();
+}
+/** The stylesheet links and inline theme of a published page, to dress the preview in. */
+function themeOf(html, site) {
+    const links = [...html.matchAll(/<link[^>]+rel="stylesheet"[^>]*>/gi)].map((m) => m[0].replace(/href="(\/[^"]*)"/, (_x, href) => `href="${new URL(href, site).href}"`));
+    const styles = [...html.matchAll(/<style[^>]*>[\s\S]*?<\/style>/gi)].map((m) => m[0]);
+    return [...links, ...styles].join('\n');
+}
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+/** One preview document: the nav of files, the rendered body, and the reload hook. */
+function previewPage(opts) {
+    const nav = opts.files
+        .map((f) => `<li><a href="/${esc(f)}"${f === opts.current ? ' aria-current="page" style="font-weight:600"' : ''}>${esc(f)}</a></li>`)
+        .join('');
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(opts.title)} · preview</title>${opts.theme}
+<style>.fm-dev{display:flex;gap:2rem;max-width:72rem;margin:0 auto;padding:2rem 1rem}.fm-dev nav{flex:0 0 14rem;font:14px/1.6 system-ui,sans-serif}.fm-dev nav ul{list-style:none;padding:0;margin:0}.fm-dev main{flex:1;min-width:0}</style></head>
+<body class="forumulate-reader"><div class="fm-dev"><nav aria-label="Files"><ul>${nav}</ul></nav><main><article class="forumulate-prose">${opts.heading ? `<h1>${esc(opts.heading)}</h1>` : ''}${opts.body}</article></main></div>
+<script>new EventSource('/__forumulate/live').onmessage=function(){location.reload()};</script></body></html>`;
+}
+async function runDev(opts, deps) {
+    if (!opts.space || !opts.org) {
+        deps.err('dev needs --org <orgId> and --space <spaceId> (the space whose renderer previews it).');
+        return 2;
+    }
+    const folder = node_path_1.default.resolve(opts.folder);
+    let theme = '';
+    if (opts.site) {
+        try {
+            theme = themeOf(await (await fetch(opts.site)).text(), opts.site);
+        }
+        catch {
+            deps.err(`Could not read ${opts.site}; the preview will be unstyled.`);
+        }
+    }
+    const clients = new Set();
+    const render = async (rel) => {
+        const { data, body } = (0, frontmatter_1.splitFront)((0, node_fs_1.readFileSync)(node_path_1.default.join(folder, rel), 'utf8'));
+        const r = await deps.client.request('POST', `/orgs/${opts.org}/spaces/${opts.space}/docs/render`, { body: { markdown: body } });
+        const declared = typeof data.title === 'string' ? data.title : null;
+        // A body that opens with its own `# Title` already carries it; a front-matter
+        // title is drawn as the heading only when the body has none.
+        return {
+            title: declared ?? r.title ?? rel,
+            heading: declared && !r.title ? declared : null,
+            html: r.html,
+        };
+    };
+    const server = (0, node_http_1.createServer)((req, res) => {
+        void (async () => {
+            const url = decodeURIComponent((req.url ?? '/').split('?')[0]);
+            if (url === '/__forumulate/live') {
+                res.writeHead(200, {
+                    'content-type': 'text/event-stream',
+                    'cache-control': 'no-store',
+                    connection: 'keep-alive',
+                });
+                res.write(': live\n\n');
+                clients.add(res);
+                req.on('close', () => clients.delete(res));
+                return;
+            }
+            const files = markdownFiles(folder);
+            const rel = url === '/'
+                ? (files.find((f) => /(^|\/)(index|readme)\.mdx?$/i.test(f)) ?? files[0] ?? null)
+                : url.slice(1);
+            // Only a file the listing holds — never a path that climbs out of the folder.
+            if (!rel || !files.includes(rel)) {
+                res.writeHead(404, { 'content-type': 'text/html; charset=utf-8' });
+                res.end(previewPage({
+                    title: 'Not found',
+                    body: '<p>No such page in this folder.</p>',
+                    files,
+                    current: null,
+                    theme,
+                }));
+                return;
+            }
+            try {
+                const page = await render(rel);
+                res.writeHead(200, {
+                    'content-type': 'text/html; charset=utf-8',
+                    'cache-control': 'no-store',
+                });
+                res.end(previewPage({
+                    title: page.title,
+                    heading: page.heading,
+                    body: page.html,
+                    files,
+                    current: rel,
+                    theme,
+                }));
+            }
+            catch (e) {
+                res.writeHead(502, { 'content-type': 'text/html; charset=utf-8' });
+                res.end(previewPage({
+                    title: 'Could not render',
+                    body: `<pre>${esc(String(e.message ?? e))}</pre>`,
+                    files,
+                    current: rel,
+                    theme,
+                }));
+            }
+        })();
+    });
+    // Saved a file: every open preview reloads (a burst of writes is one reload).
+    let timer = null;
+    const watcher = (0, node_fs_1.watch)(folder, { recursive: true }, (_e, name) => {
+        if (!name || !PAGE.test(String(name)))
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            for (const c of clients)
+                c.write('data: reload\n\n');
+        }, 120);
+    });
+    await new Promise((resolve) => server.listen(opts.port, '127.0.0.1', resolve));
+    deps.out(`Previewing ${folder} at http://127.0.0.1:${opts.port}/ — Ctrl+C to stop.`);
+    const close = () => {
+        watcher.close();
+        for (const c of clients)
+            c.end();
+        server.close();
+    };
+    if (deps.onListening) {
+        deps.onListening(close);
+        return 0;
+    }
+    await new Promise((resolve) => server.on('close', resolve));
+    return 0;
+}
+//# sourceMappingURL=command.js.map

package/dist/dev/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/dev/command.ts"],"names":[],"mappings":"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"}

package/dist/doctor/address-checks.d.ts

@@ -0,0 +1,56 @@
+import type { Check } from '../conformance';
+import { type Get } from './probe';
+/**
+ * Checks about a page that lives at more than one address.
+ *
+ * A hosted docs platform serves every published page twice: on its own host
+ * (`platform.example/p/<org>/<space>/<page>`) and on the customer's domain.
+ * Search engines must be told, by BOTH copies, that the customer's address is
+ * the real one. The platform copy of a LEGAL page redirected to a third
+ * address that named itself canonical (FMU-B01), so the customer's legal pages
+ * competed with a copy on our host. Nothing on the customer's domain showed it.
+ */
+/** One page at its several addresses: the primary (canonical) one first when known. */
+export interface AddressSet {
+    /** What the canonical of every copy should be, when it is known. */
+    expected?: string;
+    urls: string[];
+}
+export declare function canonicalBothAddresses(get: Get, sets: AddressSet[]): Promise<Check>;
+/**
+ * Strip what a browser does not show and a reader cannot click: scripts,
+ * styles, and `<link>` tags (preloads, stylesheets). A white-label site may
+ * well load its JavaScript from the platform's CDN — that is infrastructure,
+ * not branding — so only the markup a person sees, and the links they follow,
+ * are judged.
+ */
+export declare function visibleMarkup(html: string): string;
+/** Platform URLs with a path: a bare-origin link is a "powered by" badge, which is a setting, not a leak. */
+export declare function platformMentions(text: string, platformHost: string): string[];
+/**
+ * `white-label-leaks`: a page on the customer's domain does not send its
+ * readers, or its agents, back to the platform's host.
+ *
+ * The Markdown twin of a reference page on a white-label domain ended with a
+ * "For AI agents" block pointing at the platform's API host for llms-full.txt
+ * and MCP, while the same files existed on the customer's domain (FMU-B15).
+ * The HTML looked clean; the agent-facing copy was the leak. Both are read.
+ */
+export declare function whiteLabelLeaks(get: Get, pageUrl: string, html: string, platformHost: string): Promise<Check>;
+export declare function findCmps(html: string): {
+    name: string;
+    at: number[];
+}[];
+export declare function languageHints(html: string, at: number[]): string[];
+/**
+ * `consent-tag`: the cookie banner speaks the page's language.
+ *
+ * The CMP tag carried no culture, so the banner followed the BROWSER's
+ * language rather than the page's (FMU-B17, S05): a German reader on the
+ * English page got a German banner over English text, and on a translated
+ * page the banner and the page disagree for everyone whose browser is set to
+ * anything else. Consent shown in a language the page is not in is a consent
+ * a regulator can question. No CMP on the page is a skip, not a pass.
+ */
+export declare function consentTag(html: string): Check;
+//# sourceMappingURL=address-checks.d.ts.map

package/dist/doctor/address-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-checks.d.ts","sourceRoot":"","sources":["../../src/doctor/address-checks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAQL,KAAK,GAAG,EACT,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;GASG;AAEH,uFAAuF;AACvF,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CA4CzF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED,6GAA6G;AAC7G,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ7E;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,KAAK,CAAC,CA+BhB;AA4CD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,CAWvE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQlE;AAID;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAuC9C"}

package/dist/doctor/address-checks.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalBothAddresses = canonicalBothAddresses;
+exports.visibleMarkup = visibleMarkup;
+exports.platformMentions = platformMentions;
+exports.whiteLabelLeaks = whiteLabelLeaks;
+exports.findCmps = findCmps;
+exports.languageHints = languageHints;
+exports.consentTag = consentTag;
+const probe_1 = require("./probe");
+async function canonicalBothAddresses(get, sets) {
+    const title = 'Every address of a page names the same canonical';
+    const usable = sets.filter((s) => s.urls.length >= 2 || s.expected);
+    if (usable.length === 0)
+        return (0, probe_1.check)('canonical-both-addresses', title, 'skip', 'Only one address of this page is known. Pass --also <the other address>, or --site <slug> to have them looked up.', '');
+    const bad = [];
+    const good = [];
+    for (const set of usable) {
+        const before = bad.length;
+        const seen = [];
+        for (const url of [...new Set(set.urls)]) {
+            const { hops, final } = await (0, probe_1.follow)(get, url, { accept: 'text/html' });
+            const landed = hops.length > 1 && final.ok ? final.url : url;
+            if (!final.ok || final.status !== 200) {
+                bad.push(`${url} → ${(0, probe_1.describeProbe)(final)}`);
+                continue;
+            }
+            seen.push({ url, final: landed, canonical: (0, probe_1.canonicalOf)(final.text, landed) });
+        }
+        const expected = set.expected ?? seen.find((s) => s.canonical)?.canonical;
+        for (const s of seen) {
+            const via = s.final !== s.url ? ` (via ${s.final})` : '';
+            if (!s.canonical)
+                bad.push(`${s.url}${via} declares no canonical`);
+            else if (expected && !(0, probe_1.sameUrl)(s.canonical, expected))
+                bad.push(`${s.url}${via} names ${s.canonical}, expected ${expected}`);
+        }
+        if (seen.length && bad.length === before)
+            good.push(`${seen.map((s) => s.url).join(' and ')} → ${expected}`);
+    }
+    return (0, probe_1.check)('canonical-both-addresses', title, bad.length ? 'fail' : 'pass', bad.length ? (0, probe_1.some)(bad) : (0, probe_1.some)(good), bad.length
+        ? 'Two copies with different canonicals compete in search, and the platform copy can outrank the customer’s own domain.'
+        : '');
+}
+/**
+ * Strip what a browser does not show and a reader cannot click: scripts,
+ * styles, and `<link>` tags (preloads, stylesheets). A white-label site may
+ * well load its JavaScript from the platform's CDN — that is infrastructure,
+ * not branding — so only the markup a person sees, and the links they follow,
+ * are judged.
+ */
+function visibleMarkup(html) {
+    return html
+        .replace(/<script\b[\s\S]*?<\/script>/gi, '')
+        .replace(/<style\b[\s\S]*?<\/style>/gi, '')
+        .replace(/<link\b[^>]*>/gi, '')
+        .replace(/<meta\b[^>]*>/gi, '');
+}
+/** Platform URLs with a path: a bare-origin link is a "powered by" badge, which is a setting, not a leak. */
+function platformMentions(text, platformHost) {
+    const host = platformHost.replace(/[.]/g, '\\.');
+    const re = new RegExp(`https?://(?:www\\.)?${host}(/[^\\s"'<>)\\]\`]+)`, 'gi');
+    return [
+        ...new Set([...text.matchAll(re)].map((m) => m[0]).filter((u) => !/^https?:\/\/[^/]+\/?$/.test(u))),
+    ];
+}
+/**
+ * `white-label-leaks`: a page on the customer's domain does not send its
+ * readers, or its agents, back to the platform's host.
+ *
+ * The Markdown twin of a reference page on a white-label domain ended with a
+ * "For AI agents" block pointing at the platform's API host for llms-full.txt
+ * and MCP, while the same files existed on the customer's domain (FMU-B15).
+ * The HTML looked clean; the agent-facing copy was the leak. Both are read.
+ */
+async function whiteLabelLeaks(get, pageUrl, html, platformHost) {
+    const title = 'No platform URLs on a custom-domain page';
+    const host = (0, probe_1.hostOf)(pageUrl);
+    if (!host || host === platformHost.toLowerCase() || host === `www.${platformHost.toLowerCase()}`)
+        return (0, probe_1.check)('white-label-leaks', title, 'skip', `${pageUrl} is on the platform host itself.`, '');
+    const leaks = platformMentions(visibleMarkup(html), platformHost).map((u) => `HTML: ${u}`);
+    const u = new URL(pageUrl);
+    const mdUrl = `${u.origin}${u.pathname.replace(/\/+$/, '')}.md`;
+    const md = await get(mdUrl, { accept: 'text/markdown,text/plain' });
+    const isMd = md.ok && md.status === 200 && !/text\/html/i.test(md.headers.get('content-type') ?? '');
+    if (isMd)
+        for (const m of platformMentions(md.text, platformHost))
+            leaks.push(`${mdUrl}: ${m}`);
+    return (0, probe_1.check)('white-label-leaks', title, leaks.length ? 'fail' : 'pass', leaks.length
+        ? (0, probe_1.some)(leaks)
+        : `No ${platformHost} links in the page${isMd ? ' or its Markdown twin' : ''}.`, leaks.length
+        ? `A white-label site that links readers or agents to ${platformHost} exposes the platform behind it and splits its traffic; serve the same resources under the customer's domain.`
+        : '');
+}
+/**
+ * Consent managers, and where each one is told which language to speak.
+ *
+ * Matched on the vendor's loader host or global, so a CMP is recognised
+ * whether it is a `<script>` in the HTML, a preload of a script a framework
+ * injects later, or a config object in a serialized payload. The language
+ * hints are each vendor's documented attribute or query parameter; a vendor
+ * not listed here is still found by the generic hints below.
+ */
+const CMPS = [
+    { name: 'Cookie Munch', match: /cookiemunch\.(?:net|com)/i },
+    { name: 'Cookiebot', match: /consent\.cookiebot\.(?:com|eu)|uc\.js/i },
+    { name: 'OneTrust', match: /otSDKStub|cdn\.cookielaw\.org|onetrust\.com/i },
+    { name: 'Osano', match: /cmp\.osano\.com/i },
+    { name: 'Termly', match: /app\.termly\.io/i },
+    { name: 'Usercentrics', match: /usercentrics\.eu/i },
+    { name: 'Didomi', match: /sdk\.privacy-center\.org|didomi/i },
+    { name: 'iubenda', match: /cdn\.iubenda\.com/i },
+    { name: 'Complianz', match: /complianz/i },
+    { name: 'TCF CMP', match: /__tcfapi/ },
+];
+/**
+ * Where a CMP's language is stated, across vendors: `data-culture` (Cookie
+ * Munch, Cookiebot), `data-language` (OneTrust's `data-document-language`,
+ * Usercentrics), `data-lang`, a `culture`/`language` key in a serialized
+ * config, or a `?culture=`/`?language=`/`?lang=`/`?hl=` loader parameter.
+ */
+const LANGUAGE_HINTS = [
+    /data-(?:document-)?(?:culture|language|lang)\s*=\s*\\?["']([A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})?)/g,
+    /\\?["'](?:culture|language|lang|uiLanguage)\\?["']\s*:\s*\\?["']([A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})?)/g,
+    /[?&](?:culture|language|lang|hl)=([A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})?)/g,
+];
+/**
+ * How far around a vendor mention a language hint still belongs to it. Small
+ * on purpose: a framework's serialized payload also carries the PAGE's
+ * language a few kilobytes away, and reading that as the banner's would pass
+ * exactly the page this check exists to fail.
+ */
+const HINT_WINDOW = 600;
+function findCmps(html) {
+    const out = [];
+    for (const cmp of CMPS) {
+        const re = new RegExp(cmp.match.source, cmp.match.flags.includes('g') ? cmp.match.flags : `${cmp.match.flags}g`);
+        const at = [...html.matchAll(re)].map((m) => m.index ?? 0);
+        if (at.length)
+            out.push({ name: cmp.name, at });
+    }
+    return out;
+}
+function languageHints(html, at) {
+    const found = new Set();
+    for (const i of at) {
+        const win = html.slice(Math.max(0, i - HINT_WINDOW), i + HINT_WINDOW);
+        for (const re of LANGUAGE_HINTS)
+            for (const m of win.matchAll(new RegExp(re.source, re.flags)))
+                found.add(m[1].toLowerCase());
+    }
+    return [...found];
+}
+const primary = (tag) => tag.toLowerCase().split(/[-_]/)[0];
+/**
+ * `consent-tag`: the cookie banner speaks the page's language.
+ *
+ * The CMP tag carried no culture, so the banner followed the BROWSER's
+ * language rather than the page's (FMU-B17, S05): a German reader on the
+ * English page got a German banner over English text, and on a translated
+ * page the banner and the page disagree for everyone whose browser is set to
+ * anything else. Consent shown in a language the page is not in is a consent
+ * a regulator can question. No CMP on the page is a skip, not a pass.
+ */
+function consentTag(html) {
+    const title = 'The consent banner is told the page language';
+    const cmps = findCmps(html);
+    if (cmps.length === 0)
+        return (0, probe_1.check)('consent-tag', title, 'skip', 'No consent manager found on this page.', '');
+    const lang = /<html\b[^>]*\blang\s*=\s*["']?([A-Za-z-]+)/i.exec(html)?.[1]?.toLowerCase();
+    const names = cmps.map((c) => c.name).join(', ');
+    const matters = 'A banner that follows the browser rather than the page asks for consent in a language the page is not written in.';
+    if (!lang)
+        return (0, probe_1.check)('consent-tag', title, 'fail', `${names} found, but the page declares no <html lang>.`, matters);
+    const hints = languageHints(html, cmps.flatMap((c) => c.at));
+    if (hints.length === 0)
+        return (0, probe_1.check)('consent-tag', title, 'fail', `${names} is given no language (no data-culture / data-language / language parameter); the banner will follow the browser, while the page is "${lang}".`, matters);
+    const wrong = hints.filter((h) => primary(h) !== primary(lang));
+    return (0, probe_1.check)('consent-tag', title, wrong.length ? 'fail' : 'pass', wrong.length
+        ? `${names} is told "${wrong.join(', ')}" on a "${lang}" page.`
+        : `${names} is told "${hints.join(', ')}", matching the page ("${lang}").`, wrong.length ? matters : '');
+}
+//# sourceMappingURL=address-checks.js.map