@forumulate/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forumulate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @forumulate/cli
+
+Command-line interface for [Forumulate](https://github.com/alphajew420/forumulate) — manage orgs, spaces, docs, and search from your terminal, built on `@forumulate/sdk`.
+
+## Install
+
+```sh
+npm install -g @forumulate/cli
+```
+
+## Usage
+
+```sh
+export FORUMULATE_URL=https://your-forumulate.example.com   # default http://localhost:4000
+export FORUMULATE_TOKEN=cfo_...                           # a Personal Access Token
+
+forumulate whoami
+forumulate orgs
+forumulate spaces <orgId>
+forumulate search <orgId> how to deploy
+forumulate publish <orgId> <spaceId> <pageId>
+forumulate snapshot <orgId> <spaceId> "Before the big migration"
+```
+
+Add `--json` to any command for raw JSON output, `--version` for the version, and `forumulate help` for the full list.
+
+## `forumulate doctor`
+
+Check a live site from the outside, the way a reader and a crawler see it:
+
+```sh
+forumulate doctor https://your-domain.example.com/docs
+```
+
+It needs no token, because none of this is private. Each check is something
+customers have found out about after their readers did:
+
+| Check | What a failure means |
+|---|---|
+| `health` | The health endpoint answered something other than JSON. A plain-text 500 during a deploy reads as a permanent bug, so a careful client stops retrying a few-minute outage. |
+| `public-read` | A logged-out reader is redirected to sign-in. Public docs behind a login are invisible to readers and to crawlers — and invisible from inside a signed-in session, which is why this is worth a command. |
+| `canonical` | The `rel=canonical` names another host. Search engines credit the canonical host, so a platform URL here hands your authority to the platform. |
+| `html-untouched` | Something in the path is rewriting your markup. Cloudflare's Email Obfuscation is the usual one: it injects a decoder script with no CSP nonce, so the script is refused and every address on the page renders as `[email protected]` with a dead link. |
+| `cache-headers` | The document is served `no-store` or with no `Cache-Control`, so every reader pays full origin latency and a CDN in front of it does nothing. |
+| `robots` / `sitemap` | `robots.txt` disallows the path, or names no sitemap. A `Disallow` here means the page is never indexed, however good it is. Only the `User-agent: *` group counts — a rule aimed at one named crawler is a deliberate choice. |
+| `crawler-access` | A crawler gets a different status from a reader. A WAF rule or bot challenge that answers crawlers differently removes the site from search with nothing in any log to say so. |
+| `feeds` | No feed beside the page. Readers and aggregators look next to the content, not at an API URL. |
+
+Exit code is non-zero when anything failed, so it works in a deploy pipeline.
+`--json` gives the full report. The checks speak plain HTTP and assume nothing
+about the server, so pointing it at a staging mount — or at a competitor —
+produces the same report: a doctor that only passes on its author's deployment
+is a checklist with extra steps.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const sdk_1 = require("@forumulate/sdk");
+const run_1 = require("./run");
+async function main() {
+    const baseUrl = process.env.FORUMULATE_URL ?? 'http://localhost:4000';
+    const token = process.env.FORUMULATE_TOKEN;
+    const client = new sdk_1.ForumulateClient({ baseUrl, token });
+    const code = await (0, run_1.run)(process.argv.slice(2), {
+        client,
+        out: (l) => process.stdout.write(l + '\n'),
+        err: (l) => process.stderr.write(l + '\n'),
+    });
+    process.exit(code);
+}
+void main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;AACA,yCAAmD;AACnD,+BAA4B;AAE5B,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,uBAAuB,CAAC;IACtE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,sBAAgB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,MAAM,IAAA,SAAG,EAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QAC5C,MAAM;QACN,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC;QAC1C,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC;KAC3C,CAAC,CAAC;IACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,KAAK,IAAI,EAAE,CAAC"}

package/dist/conformance.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The Content Sync Protocol, as a suite anything can be run against.
+ *
+ * What this checks is not "is it Forumulate" — it is a set of properties any
+ * documentation platform can have and most do not: a findable description, one
+ * envelope, a cursor that walks a collection without dropping or repeating a
+ * row, an incremental window with a server-defined watermark, explicit
+ * tombstones, a per-item hash, conditional requests, and rate limits that name
+ * their window.
+ *
+ * It uses plain fetch and no SDK on purpose. A conformance suite that only runs
+ * against the platform that wrote it proves nothing and convinces nobody.
+ */
+export declare const PROTOCOL_VERSION = "2026-09-01";
+export interface Check {
+    id: string;
+    title: string;
+    state: 'pass' | 'fail' | 'skip';
+    detail: string;
+    /** Why a client is worse off when this fails. */
+    matters: string;
+}
+export interface ConformanceInput {
+    /** The collection to walk, absolute. e.g. https://api.example.com/orgs/1/spaces/2/items */
+    collection: string;
+    token?: string;
+    /** The key the collection is under, if it is not derivable from the path. */
+    key?: string;
+    fetchImpl?: typeof fetch;
+    /** The version header a client states. Absent means the platform has none. */
+    versionHeader?: {
+        name: string;
+        value: string;
+    };
+}
+export interface ConformanceReport {
+    protocol: string;
+    collection: string;
+    checks: Check[];
+    passed: number;
+    failed: number;
+}
+export declare function runConformance(input: ConformanceInput): Promise<ConformanceReport>;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,2FAA2F;IAC3F,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,8EAA8E;IAC9E,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAOD,wBAAsB,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2KxF"}

package/dist/conformance.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_VERSION = void 0;
+exports.runConformance = runConformance;
+/**
+ * The Content Sync Protocol, as a suite anything can be run against.
+ *
+ * What this checks is not "is it Forumulate" — it is a set of properties any
+ * documentation platform can have and most do not: a findable description, one
+ * envelope, a cursor that walks a collection without dropping or repeating a
+ * row, an incremental window with a server-defined watermark, explicit
+ * tombstones, a per-item hash, conditional requests, and rate limits that name
+ * their window.
+ *
+ * It uses plain fetch and no SDK on purpose. A conformance suite that only runs
+ * against the platform that wrote it proves nothing and convinces nobody.
+ */
+exports.PROTOCOL_VERSION = '2026-09-01';
+const nounOf = (url) => {
+    const path = new URL(url).pathname.split('/').filter(Boolean);
+    return path[path.length - 1] ?? 'items';
+};
+async function runConformance(input) {
+    const doFetch = input.fetchImpl ?? fetch;
+    const key = input.key ?? nounOf(input.collection);
+    const checks = [];
+    const headers = { accept: 'application/json' };
+    if (input.token)
+        headers.authorization = `Bearer ${input.token}`;
+    if (input.versionHeader)
+        headers[input.versionHeader.name] = input.versionHeader.value;
+    const get = async (url, extra = {}) => {
+        const res = await doFetch(url, { headers: { ...headers, ...extra } });
+        const text = await res.text();
+        let body = {};
+        try {
+            body = text ? JSON.parse(text) : {};
+        }
+        catch {
+            body = {};
+        }
+        return { res, body };
+    };
+    const add = (id, title, state, detail, matters) => checks.push({ id, title, state, detail, matters });
+    // 1 — the description is findable from the collection itself.
+    const first = await get(withQuery(input.collection, { limit: '2' }));
+    const serviceDesc = first.res.headers.get('link') ?? '';
+    add('CSP-1', 'The description is findable from any response', /rel="?service-desc"?/.test(serviceDesc) ? 'pass' : 'fail', serviceDesc ? `link: ${serviceDesc.slice(0, 120)}` : 'no Link header', 'Without it an integrator probes five paths, finds nothing, and writes a defensive parser instead of generating a client.');
+    // 2 — one envelope, keyed after the path.
+    const rows = Array.isArray(body(first.body, key)) ? body(first.body, key) : null;
+    add('CSP-2', `The collection is keyed after its path (\`${key}\`)`, rows ? 'pass' : 'fail', rows ? `${rows.length} row(s)` : `keys were: ${Object.keys(first.body).join(', ') || 'none'}`, 'A key that does not match its path makes every other endpoint a guess.');
+    const page = first.body.page;
+    add('CSP-3', 'The page carries limit, has_more, next_cursor and total', page && 'has_more' in page && 'next_cursor' in page ? 'pass' : 'fail', page ? JSON.stringify(page) : 'no `page` object', 'A caller cannot tell a short page from the last page, so a sync silently stops early.');
+    // 3 — the walk visits every row exactly once.
+    if (rows && page) {
+        const seen = [];
+        let cursor = page.next_cursor ?? null;
+        let guard = 0;
+        for (const row of rows)
+            seen.push(String(row.id));
+        while (cursor && guard++ < 50) {
+            const next = await get(withQuery(input.collection, { limit: '2', cursor }));
+            const nextRows = body(next.body, key) ?? [];
+            for (const row of nextRows)
+                seen.push(String(row.id));
+            cursor = next.body.page?.next_cursor ?? null;
+        }
+        const unique = new Set(seen);
+        add('CSP-4', 'A cursor walk visits every row exactly once', unique.size === seen.length ? 'pass' : 'fail', `${seen.length} row(s), ${unique.size} distinct`, 'A cursor that repeats or skips rows corrupts a corpus without ever erroring.');
+        const total = page.total;
+        add('CSP-5', 'The walk agrees with the reported total', typeof total === 'number' ? (unique.size === total ? 'pass' : 'fail') : 'skip', typeof total === 'number' ? `walked ${unique.size}, total says ${total}` : 'no total reported', 'A total nobody can reconcile against is a number that hides a truncated sync.');
+    }
+    // 4 — the incremental window, and the watermark that drives it.
+    const sync = first.body.sync;
+    add('CSP-6', 'A server-defined checkpoint comes back with the page', sync?.checkpoint ? 'pass' : 'fail', sync?.checkpoint ?? 'no `sync.checkpoint`', 'Without one, every client invents its own watermark out of its own clock and loses rows to skew.');
+    if (sync?.checkpoint) {
+        const since = await get(withQuery(input.collection, { updated_since: sync.checkpoint }));
+        const sinceRows = body(since.body, key) ?? [];
+        add('CSP-7', 'The checkpoint narrows the answer', sinceRows.length <= (rows?.length ?? 0) + 1 ? 'pass' : 'fail', `${sinceRows.length} row(s) changed since the checkpoint`, 'An incremental sync that returns everything is a full sync wearing a parameter.');
+        const bad = await get(withQuery(input.collection, { updated_since: 'yesterday-ish' }));
+        add('CSP-8', 'An unparseable window is refused, not ignored', bad.res.status >= 400 && bad.res.status < 500 ? 'pass' : 'fail', `answered ${bad.res.status}`, 'Silently ignoring it hands back a full list that looks like a successful incremental sync.');
+    }
+    // 5 — tombstones.
+    const deleted = await get(withQuery(input.collection, { include_deleted: 'true', limit: '50' }));
+    const deletedRows = body(deleted.body, key) ?? [];
+    add('CSP-9', 'Removals are explicit, not inferred from absence', deleted.res.ok && deletedRows.some((r) => 'deleted' in r) ? 'pass' : deleted.res.ok ? 'skip' : 'fail', deleted.res.ok
+        ? deletedRows.some((r) => 'deleted' in r)
+            ? 'tombstones present'
+            : 'nothing has been removed in the retention window'
+        : `answered ${deleted.res.status}`, 'Absence means "archived" on a full sync and "not on this page" on an incremental one. Conflating them deletes a corpus.');
+    // 6 — a hash per item, and conditional requests.
+    const withContent = await get(withQuery(input.collection, { include: 'body', limit: '1' }));
+    const item = (body(withContent.body, key) ?? [])[0];
+    add('CSP-10', 'Each item carries a content hash', item && typeof item.contentHash === 'string' ? 'pass' : 'fail', item ? Object.keys(item).join(', ').slice(0, 120) : 'no rows to inspect', 'Without it a client re-embeds everything to discover that nothing changed.');
+    const etag = first.res.headers.get('etag');
+    if (etag) {
+        const again = await doFetch(withQuery(input.collection, { limit: '2' }), {
+            headers: { ...headers, 'if-none-match': etag },
+        });
+        add('CSP-11', 'A conditional request answers 304', again.status === 304 ? 'pass' : 'fail', `answered ${again.status}`, 'Polling costs a full transfer to learn nothing moved.');
+    }
+    else {
+        add('CSP-11', 'A conditional request answers 304', 'skip', 'no ETag on the collection', 'Polling costs a full transfer to learn nothing moved.');
+    }
+    // 7 — limits that name their window.
+    const limit = first.res.headers.get('ratelimit-limit');
+    const policy = first.res.headers.get('ratelimit-policy');
+    add('CSP-12', 'Rate limits are stated, with their window', limit && policy ? 'pass' : limit ? 'fail' : 'fail', [limit && `limit ${limit}`, policy && `policy ${policy}`].filter(Boolean).join(', ') || 'neither header', 'A limit with no period is a number per something, and a client that guesses wrong either crawls or is refused.');
+    const failed = checks.filter((c) => c.state === 'fail').length;
+    return {
+        protocol: exports.PROTOCOL_VERSION,
+        collection: input.collection,
+        checks,
+        passed: checks.filter((c) => c.state === 'pass').length,
+        failed,
+    };
+}
+function withQuery(url, params) {
+    const u = new URL(url);
+    for (const [k, v] of Object.entries(params))
+        u.searchParams.set(k, v);
+    return u.toString();
+}
+function body(payload, key) {
+    return payload[key] ?? payload[key.replace(/s$/, '')] ?? undefined;
+}
+//# sourceMappingURL=conformance.js.map

package/dist/conformance.js.map

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

package/dist/doctor.d.ts

@@ -0,0 +1,33 @@
+import type { Check } from './conformance';
+/**
+ * Everything that is wrong with a live site, from the outside.
+ *
+ * A customer putting their docs on a custom domain has to verify by hand that
+ * the health endpoint answers JSON, that the canonical link points at their
+ * host rather than ours, that a logged-out reader gets the page rather than a
+ * sign-in, that the feeds exist where their readers will look, that redirects
+ * actually redirect, and that nothing in the path is rewriting their HTML.
+ * Each of those is a sentence in a checklist somebody reads once and forgets,
+ * and all of them were things this customer discovered after going live.
+ *
+ * So they are a command. It takes a URL and nothing else, speaks plain HTTP, and
+ * is the same report whether it is pointed at us, at a staging mount, or at a
+ * competitor — a doctor that only works on its author's deployment is a
+ * checklist with extra steps.
+ */
+export interface DoctorInput {
+    /** A reader URL on the site to examine, e.g. https://example.com/docs */
+    url: string;
+    /** The API base, when it is not the same origin (defaults to the site's). */
+    apiBase?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface DoctorReport {
+    url: string;
+    checks: Check[];
+    passed: number;
+    failed: number;
+    warnings: number;
+}
+export declare function runDoctor(input: DoctorInput): Promise<DoctorReport>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAKD,wBAAsB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CA2JzE"}

package/dist/doctor.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctor = runDoctor;
+/** A crawler-ish UA: some CDNs answer bots differently, which is the point. */
+const CRAWLER_UA = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)';
+async function runDoctor(input) {
+    const doFetch = input.fetchImpl ?? fetch;
+    const site = new URL(input.url);
+    const origin = site.origin;
+    const apiBase = (input.apiBase ?? origin).replace(/\/$/, '');
+    const checks = [];
+    const add = (id, title, state, detail, matters) => checks.push({ id, title, state, detail, matters });
+    const get = async (url, headers = {}) => {
+        try {
+            const res = await doFetch(url, { headers, redirect: 'manual' });
+            const text = res.status < 400 || res.status >= 500 ? await res.text() : await res.text();
+            return { ok: true, res, text };
+        }
+        catch (e) {
+            return { ok: false, error: e instanceof Error ? e.message : String(e) };
+        }
+    };
+    // 1. Health answers JSON, in every state.
+    const health = await get(`${apiBase}/api/health`, { accept: 'application/json' });
+    if (!health.ok) {
+        add('health', 'Health endpoint answers', 'fail', health.error, 'A caller cannot tell an outage from a bug.');
+    }
+    else {
+        let parsed = null;
+        try {
+            parsed = JSON.parse(health.text);
+        }
+        catch {
+            parsed = null;
+        }
+        if (parsed && typeof parsed === 'object') {
+            add('health', 'Health endpoint answers JSON', 'pass', `${health.res.status} with a JSON body.`, '');
+        }
+        else {
+            add('health', 'Health endpoint answers JSON', 'fail', `${health.res.status} with a non-JSON body: ${health.text.slice(0, 80)}`, 'A plain-text 500 reads as a permanent bug, so a careful client stops retrying a few-minute outage.');
+        }
+    }
+    // 2. A logged-out reader gets the page, not a sign-in.
+    const anon = await get(site.toString(), { accept: 'text/html' });
+    const html = anon.ok ? anon.text : '';
+    if (!anon.ok) {
+        add('public-read', 'A logged-out reader can read the page', 'fail', anon.error, 'Public docs behind a login are invisible to readers and to crawlers.');
+    }
+    else if (anon.res.status >= 300 && anon.res.status < 400) {
+        const to = anon.res.headers.get('location') ?? '';
+        const login = /sign-?in|login|auth/i.test(to);
+        add('public-read', 'A logged-out reader can read the page', login ? 'fail' : 'pass', `${anon.res.status} → ${to}`, login ? 'A public page that redirects to sign-in is a login wall; crawlers index nothing.' : '');
+    }
+    else {
+        add('public-read', 'A logged-out reader can read the page', anon.res.status === 200 ? 'pass' : 'fail', `${anon.res.status}`, 'Public docs must answer an anonymous GET.');
+    }
+    // 3. The canonical link names THIS host.
+    const canonical = /<link[^>]+rel=["']canonical["'][^>]+href=["']([^"']+)["']/i.exec(html)?.[1]
+        ?? /<link[^>]+href=["']([^"']+)["'][^>]+rel=["']canonical["']/i.exec(html)?.[1];
+    if (!html) {
+        add('canonical', 'Canonical link points at this host', 'skip', 'No HTML to read.', '');
+    }
+    else if (!canonical) {
+        add('canonical', 'Canonical link points at this host', 'fail', 'No rel=canonical in the document.', 'Without one, two hosts serving the same page compete, and the wrong one can win.');
+    }
+    else {
+        const same = safeHost(canonical) === site.host;
+        add('canonical', 'Canonical link points at this host', same ? 'pass' : 'fail', canonical, same ? '' : 'Search engines credit the canonical host, so a platform URL here hands your authority to the platform.');
+    }
+    // 4. Nothing in the path is rewriting the HTML.
+    if (html) {
+        const rewritten = html.includes('/cdn-cgi/scripts/') && html.includes('email-decode');
+        const scrambled = html.includes('data-cfemail');
+        add('html-untouched', 'No proxy is rewriting the markup', rewritten || scrambled ? 'fail' : 'pass', rewritten || scrambled
+            ? 'Cloudflare Email Obfuscation is rewriting addresses on this page.'
+            : 'No rewritten email addresses.', 'The injected decoder has no CSP nonce, so it is refused and every address renders as [email protected] with a dead link. Turn Email Obfuscation off for these paths.');
+    }
+    // 5. The document is cacheable, and says so.
+    if (anon.ok) {
+        const cc = anon.res.headers.get('cache-control') ?? '';
+        const bad = /no-store/i.test(cc) || cc === '';
+        add('cache-headers', 'The document carries a usable Cache-Control', bad ? 'fail' : 'pass', cc || '(none)', 'Without one, every reader pays full origin latency and a CDN in front of it does nothing.');
+    }
+    // 6. Crawlers are let in, and told where to look.
+    const robots = await get(`${origin}/robots.txt`, { 'user-agent': CRAWLER_UA });
+    if (!robots.ok || robots.res.status !== 200) {
+        add('robots', 'robots.txt is served', 'fail', robots.ok ? `${robots.res.status}` : robots.error, 'Without it a crawler guesses, and some guess "do not index".');
+    }
+    else {
+        const blocked = blocksPath(robots.text, site.pathname);
+        add('robots', 'robots.txt allows this path', blocked ? 'fail' : 'pass', blocked ? `Disallowed by robots.txt: ${site.pathname}` : `Allows ${site.pathname || '/'}`, 'A Disallow here means the page is never indexed, however good it is.');
+        add('sitemap', 'robots.txt names a sitemap', /^\s*sitemap:/im.test(robots.text) ? 'pass' : 'fail', /^\s*sitemap:/im.test(robots.text) ? 'Declared.' : 'No Sitemap: line.', 'A crawler finds pages faster when it is handed the list.');
+    }
+    // 7. As a crawler, the same page.
+    const asBot = await get(site.toString(), { accept: 'text/html', 'user-agent': CRAWLER_UA });
+    if (asBot.ok) {
+        add('crawler-access', 'A crawler gets the same answer as a reader', asBot.res.status === (anon.ok ? anon.res.status : 200) ? 'pass' : 'fail', `reader ${anon.ok ? anon.res.status : '?'}, crawler ${asBot.res.status}`, 'A WAF rule or bot challenge that answers crawlers differently removes the site from search without telling anybody.');
+    }
+    // 8. The feeds exist where a reader will look for them.
+    const feed = await get(`${origin}${site.pathname.replace(/\/$/, '')}/rss.xml`, { accept: 'application/rss+xml' });
+    if (feed.ok) {
+        add('feeds', 'A feed is served under this path', feed.res.status === 200 ? 'pass' : 'skip', `${feed.res.status} for ${site.pathname.replace(/\/$/, '')}/rss.xml`, 'Readers and aggregators look beside the page, not at an API URL.');
+    }
+    return {
+        url: input.url,
+        checks,
+        passed: checks.filter((c) => c.state === 'pass').length,
+        failed: checks.filter((c) => c.state === 'fail').length,
+        warnings: checks.filter((c) => c.state === 'skip').length,
+    };
+}
+function safeHost(href) {
+    try {
+        return new URL(href).host;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Does robots.txt disallow this path for everyone?
+ *
+ * Only the `User-agent: *` group is read: a rule aimed at one named crawler is
+ * a deliberate choice, and reporting it as a fault would train people to
+ * ignore the report.
+ */
+function blocksPath(robots, pathname) {
+    const path = pathname || '/';
+    let inStar = false;
+    for (const raw of robots.split(/\r?\n/)) {
+        const line = raw.replace(/#.*$/, '').trim();
+        if (!line)
+            continue;
+        const [field, ...rest] = line.split(':');
+        const value = rest.join(':').trim();
+        const key = (field ?? '').trim().toLowerCase();
+        if (key === 'user-agent')
+            inStar = value === '*';
+        else if (inStar && key === 'disallow' && value && path.startsWith(value))
+            return true;
+        else if (inStar && key === 'allow' && value && path.startsWith(value))
+            return false;
+    }
+    return false;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

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

package/dist/run.d.ts

@@ -0,0 +1,14 @@
+import type { ForumulateClient } from '@forumulate/sdk';
+export declare const VERSION = "0.1.0";
+export interface RunDeps {
+    /** The API client. Injected so the CLI is testable without a live server. */
+    client: ForumulateClient;
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+/**
+ * Parse and execute a CLI invocation. Pure w.r.t. I/O (uses the injected deps),
+ * so it can be unit-tested with a fake client. Returns a process exit code.
+ */
+export declare function run(argv: string[], deps: RunDeps): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIxD,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,MAAM,WAAW,OAAO;IACtB,6EAA6E;IAC7E,MAAM,EAAE,gBAAgB,CAAC;IACzB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAgCD;;;GAGG;AACH,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAwKxE"}

package/dist/run.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+exports.run = run;
+const conformance_1 = require("./conformance");
+const doctor_1 = require("./doctor");
+exports.VERSION = '0.1.0';
+const HELP = `forumulate — Forumulate command-line interface
+
+Usage:
+  forumulate <command> [args]
+
+Commands:
+  whoami                              Show the authenticated user
+  orgs                               List your organizations
+  spaces <orgId>                     List spaces in an org
+  items <orgId> <spaceId>            List what is in a space, with where each
+                                     piece's content lives
+  search <orgId> <query...>          Unified search across docs/forum/blog
+  publish <orgId> <spaceId> <pageId> Publish a page
+  snapshot <orgId> <spaceId> <label> Create a space version snapshot
+  conformance <collectionUrl>        Run the Content Sync Protocol suite against
+                                     any platform's collection endpoint
+  doctor <readerUrl>                 Check a live site from the outside: health,
+                                     public read, canonical, cache headers,
+                                     crawler access, feeds, HTML rewriting
+  help                               Show this help
+
+Environment:
+  FORUMULATE_URL     API base URL (default http://localhost:4000)
+  FORUMULATE_TOKEN   Personal Access Token (Bearer)
+
+Flags:
+  --json          Emit raw JSON instead of a formatted summary
+  --version       Print the CLI version
+`;
+/**
+ * Parse and execute a CLI invocation. Pure w.r.t. I/O (uses the injected deps),
+ * so it can be unit-tested with a fake client. Returns a process exit code.
+ */
+async function run(argv, deps) {
+    const args = argv.filter((a) => !a.startsWith('--'));
+    const flags = new Set(argv.filter((a) => a.startsWith('--')));
+    const json = flags.has('--json');
+    const [cmd, ...rest] = args;
+    if (flags.has('--version')) {
+        deps.out(exports.VERSION);
+        return 0;
+    }
+    if (!cmd || cmd === 'help' || flags.has('--help')) {
+        deps.out(HELP);
+        return cmd && cmd !== 'help' ? 1 : 0;
+    }
+    const dump = (v) => deps.out(JSON.stringify(v, null, 2));
+    try {
+        switch (cmd) {
+            case 'whoami': {
+                const { user } = await deps.client.auth.me();
+                if (json)
+                    dump(user);
+                else
+                    deps.out(`${user.name} <${user.email}> (${user.id})`);
+                return 0;
+            }
+            case 'orgs': {
+                const { orgs } = await deps.client.orgs.list();
+                if (json)
+                    dump(orgs);
+                else
+                    for (const o of orgs)
+                        deps.out(`${o.id}  ${o.slug}  ${o.name}`);
+                return 0;
+            }
+            case 'spaces': {
+                const [orgId] = rest;
+                if (!orgId)
+                    return usage(deps, 'spaces <orgId>');
+                const { spaces } = await deps.client.spaces.list(orgId);
+                if (json)
+                    dump(spaces);
+                else
+                    for (const s of spaces)
+                        deps.out(`${s.id}  ${s.slug}  [${s.type}]  ${s.name}`);
+                return 0;
+            }
+            /*
+             * Enumerate a space, and say where the content is.
+             *
+             * `spaces` tells you a space holds 1,226 pieces; nothing told you how to
+             * walk them. The flag that matters is `contentIn`: `sections` is filled
+             * only for a piece written against a shape, so a space of free-form pages
+             * answers `include=sections` with empty objects and a sync reports
+             * success having carried nothing. This asks for `body` as well, and
+             * prints the per-row answer so the distinction is visible from a
+             * terminal rather than discovered a week later.
+             */
+            case 'items': {
+                const [orgId, spaceId] = rest;
+                if (!orgId || !spaceId)
+                    return usage(deps, 'items <orgId> <spaceId>');
+                const res = await deps.client.items.list(orgId, spaceId, {
+                    limit: 50,
+                    include: ['sections', 'body'],
+                });
+                if (json)
+                    dump(res);
+                else {
+                    for (const i of res.items) {
+                        const where = i.contentIn ? `[${i.contentIn}]` : '[no content]';
+                        deps.out(`${i.id}  ${where}  ${i.title}`);
+                    }
+                    // `page.total` against what we actually printed: the check that would
+                    // have caught a sync that quietly carried 6 of 1,226 pieces.
+                    if (res.page) {
+                        const total = res.page.total;
+                        deps.out(`-- ${res.items.length} shown${total === undefined ? '' : ` of ${total}`}` +
+                            (res.page.has_more ? `, more available (cursor: ${res.page.next_cursor ?? ''})` : ''));
+                    }
+                }
+                return 0;
+            }
+            case 'search': {
+                const [orgId, ...q] = rest;
+                if (!orgId || q.length === 0)
+                    return usage(deps, 'search <orgId> <query...>');
+                const { hits } = await deps.client.search.unified(orgId, q.join(' '));
+                if (json)
+                    dump(hits);
+                else
+                    for (const h of hits)
+                        deps.out(`[${h.sourceType}] ${h.title}  ${h.url}`);
+                return 0;
+            }
+            case 'publish': {
+                const [orgId, spaceId, pageId] = rest;
+                if (!orgId || !spaceId || !pageId)
+                    return usage(deps, 'publish <orgId> <spaceId> <pageId>');
+                await deps.client.spaces.publishPage(orgId, spaceId, pageId);
+                deps.out(`Published ${pageId}.`);
+                return 0;
+            }
+            case 'snapshot': {
+                const [orgId, spaceId, ...label] = rest;
+                if (!orgId || !spaceId || label.length === 0)
+                    return usage(deps, 'snapshot <orgId> <spaceId> <label>');
+                const { snapshot } = await deps.client.snapshots.create(orgId, spaceId, label.join(' '));
+                if (json)
+                    dump(snapshot);
+                else
+                    deps.out(`Snapshot created.`);
+                return 0;
+            }
+            /*
+             * The suite that says whether a platform can be synced correctly, run
+             * against whichever one you point it at. Ours passes; publishing a
+             * conformance suite that only runs against its author proves nothing.
+             */
+            case 'conformance': {
+                const [collection] = rest;
+                if (!collection) {
+                    deps.err('Usage: forumulate conformance <collectionUrl>');
+                    return 1;
+                }
+                const report = await (0, conformance_1.runConformance)({
+                    collection,
+                    token: process.env.FORUMULATE_TOKEN,
+                    versionHeader: { name: 'forumulate-version', value: '2026-09-01' },
+                });
+                if (json) {
+                    dump(report);
+                }
+                else {
+                    deps.out(`Content Sync Protocol ${report.protocol} — ${report.collection}`);
+                    for (const check of report.checks) {
+                        const mark = check.state === 'pass' ? 'PASS' : check.state === 'fail' ? 'FAIL' : 'SKIP';
+                        deps.out(`  ${mark}  ${check.id}  ${check.title}`);
+                        deps.out(`        ${check.detail}`);
+                        if (check.state === 'fail')
+                            deps.out(`        why it matters: ${check.matters}`);
+                    }
+                    deps.out(`${report.passed} passed, ${report.failed} failed`);
+                }
+                return report.failed > 0 ? 1 : 0;
+            }
+            /*
+             * The going-live checklist, as something that runs.
+             *
+             * Every item here is one a customer found out about after readers did:
+             * health answering plain text during a deploy, a canonical link pointing
+             * at our host instead of theirs, a CDN rewriting their email addresses
+             * into a script the CSP then refused, feeds that existed only at an API
+             * URL. Read once, forgotten, discovered live. It takes a reader URL and
+             * speaks plain HTTP, so it works against a staging mount or a competitor
+             * just as well — a doctor that only passes on its author's deployment is
+             * a checklist with extra steps.
+             */
+            case 'doctor': {
+                const [url] = rest;
+                if (!url)
+                    return usage(deps, 'doctor <readerUrl>');
+                const report = await (0, doctor_1.runDoctor)({ url, apiBase: process.env.FORUMULATE_URL });
+                if (json) {
+                    dump(report);
+                }
+                else {
+                    deps.out(`Checking ${report.url}`);
+                    for (const check of report.checks) {
+                        const mark = check.state === 'pass' ? 'PASS' : check.state === 'fail' ? 'FAIL' : 'SKIP';
+                        deps.out(`  ${mark}  ${check.id}  ${check.title}`);
+                        deps.out(`        ${check.detail}`);
+                        if (check.state === 'fail' && check.matters)
+                            deps.out(`        why it matters: ${check.matters}`);
+                    }
+                    deps.out(`${report.passed} passed, ${report.failed} failed, ${report.warnings} skipped`);
+                }
+                return report.failed > 0 ? 1 : 0;
+            }
+            default:
+                deps.err(`Unknown command: ${cmd}`);
+                deps.out(HELP);
+                return 1;
+        }
+    }
+    catch (e) {
+        const err = e;
+        deps.err(`Error${err.status ? ` ${err.status}` : ''}${err.code ? ` (${err.code})` : ''}: ${err.message ?? String(e)}`);
+        return 1;
+    }
+}
+function usage(deps, form) {
+    deps.err(`Usage: forumulate ${form}`);
+    return 1;
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@forumulate/cli",
+  "version": "0.1.0",
+  "description": "Command-line interface for Forumulate — manage orgs, spaces, docs, and search from your terminal.",
+  "license": "MIT",
+  "homepage": "https://forumulate.com/guides",
+  "bugs": {
+    "url": "https://forumulate.com/community"
+  },
+  "keywords": [
+    "forumulate",
+    "cli",
+    "docs",
+    "documentation",
+    "publish",
+    "static-site",
+    "knowledge-base",
+    "doctor"
+  ],
+  "bin": {
+    "forumulate": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@forumulate/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "author": "Forumulate",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}