@forumulate/cli 0.8.0 → 0.10.0

package/dist/help-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-commands.d.ts","sourceRoot":"","sources":["../src/help-commands.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,YAAY,+3IAmEN,CAAC;AAEpB,eAAO,MAAM,SAAS,u6BAYH,CAAC;AAEpB,eAAO,MAAM,QAAQ,4jBAQF,CAAC;AAEpB,eAAO,MAAM,UAAU,mxBAWJ,CAAC;AAEpB,eAAO,MAAM,WAAW,2dAOL,CAAC;AAEpB,eAAO,MAAM,aAAa,ueAMP,CAAC;AAEpB,eAAO,MAAM,gBAAgB,0hBAQV,CAAC;AAEpB,eAAO,MAAM,YAAY,i5BAYN,CAAC;AAEpB,eAAO,MAAM,WAAW,o7BAYL,CAAC;AAEpB,eAAO,MAAM,iBAAiB,gxCAkBX,CAAC;AAEpB,iFAAiF;AACjF,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkBzD,CAAC"}

package/dist/help-commands.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMAND_HELP = exports.TRANSLATIONS_HELP = exports.IMPORT_HELP = exports.CONTENT_HELP = exports.CONFORMANCE_HELP = exports.SNAPSHOT_HELP = exports.LOGOUT_HELP = exports.LOGIN_HELP = exports.DEV_HELP = exports.SYNC_HELP = exports.PUBLISH_HELP = void 0;
+const validate_1 = require("./validate");
+const command_1 = require("./doctor/command");
+const exit_codes_1 = require("./exit-codes");
+const whoami_1 = require("./whoami");
+const cache_command_1 = require("./cache-command");
+// `forumulate check links` — its help lives beside the command it documents.
+const command_2 = require("./check/command");
+/**
+ * Each top-level command's own `--help` (FMU-B14).
+ *
+ * `publish --help` and `doctor --help` printed the global help — a page about
+ * everything, saying almost nothing about the command asked for: not every
+ * flag, not the `forumulate.yaml` keys, not the exit codes, no example. The
+ * resource groups always printed their own; these are the commands that did
+ * not. `help-commands.test.ts` walks every top-level command and fails when one
+ * falls back to the global page again.
+ */
+const OUTPUT = `Output (every command):
+  --json          the result as JSON on stdout; progress and warnings go to stderr
+  --out <file>    write stdout to a file instead (never truncated, exit 1 if the write fails)`;
+exports.PUBLISH_HELP = `forumulate publish — publish a folder of Markdown into a space
+
+Usage:
+  forumulate publish <folder> --org <id|slug> --space <id|slug> [flags]
+
+  (org: and space: may come from forumulate.yaml, FORUMULATE_ORG / FORUMULATE_SPACE
+  or \`forumulate config set\` instead of the flags.)
+
+  One folder per collection, front matter for titles, slugs, order and SEO, assets
+  uploaded once by content hash. A re-run changes only what changed, then reads the
+  space back and fails if anything did not land.
+
+Flags:
+  --dry-run          print the plan; write nothing (no token needed for a public space)
+  --prune            move pages/posts/collections with no file to the trash
+  --only a,b         just these slugs, files, folders, or manifest parts
+                     (site, theme, settings, openapi, monitors)
+  --force            re-send every page even if it looks unchanged, AND overwrite pages
+                     edited in the studio since the last publish
+  --purge page|space|none
+                     what to drop from the cache when done (default page): page = every
+                     page this run changed; space = the whole space (a title in the
+                     navigation changed); none = leave the CDN alone. Reported per CDN.
+  --no-verify        skip the read-back           --pace <ms> gap between writes (250)
+  --manifest <file>  a forumulate.yaml somewhere else
+  --diff             print the changed paragraphs and fields of each update
+  --no-report        do not record this run (publish.completed is not sent)
+  --json             one JSON summary: {space, created, updated, unchanged, trashed,
+                     purged, verify, diffUrl, runId, lines, errors}
+  --out <file>       write that output to a file
+  --preview <name>   publish nothing: send the pages this run would add or change (and
+                     with --prune, remove) to a preview named <name> (pr-123) and print
+                     its link — the space as the change would publish it, on its own
+                     addresses, for 7 days (previews.ttl_days). Same name again: same
+                     link, renewed. --json adds previews[{urls, summary, comment}].
+  --preview-ttl <d>  a shorter life for the preview link, in days
+  --comment          with --preview in CI: post the link and diff table on the pull
+                     request (GitHub, Gitea, GitLab, Bitbucket; GITHUB_TOKEN /
+                     GITEA_TOKEN / GITLAB_TOKEN / BITBUCKET_TOKEN), editing it on re-runs
+
+Studio edits: a page edited in the studio (or through the API) since this folder was
+last published is not overwritten. The run stops before writing and prints
+  CONFLICT <slug> edited in studio by <name> at <time>
+Pull the change into the file, or re-run with --force to overwrite it.
+
+forumulate.yaml keys:
+  org, space            where to publish (one space), or
+  spaces: [{path, space, create: {type, name, visibility}, rootCollection,
+            theme, settings, tags, openapi: [{file|url, collection, ...}], monitors,
+            redirects: [{from, to, status?, type?}] or a CSV file name,
+                        redirects are merged into the space's table, never replaced
+            about: {...} | about.yaml (an ABOUT space's parts)}]
+  site: {...}           the site configuration (applied with PATCH semantics)
+  theme: {...}          the space theme
+  Guide: https://forumulate.com/guides/content-as-code
+
+Older forms (deprecated; they print a notice on stderr):
+  publish <orgId> <spaceId> <folder>   → publish <folder> --org … --space …
+  publish <orgId> <spaceId> <pageId>   → forumulate items publish <pageId> --space …
+
+Examples:
+  forumulate publish docs --org acme --space docs --dry-run
+  forumulate publish docs --org acme --space docs --purge space --json --out run.json
+  forumulate publish docs --org acme --space docs --preview pr-123 --comment
+
+${OUTPUT}
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+exports.SYNC_HELP = `forumulate sync — the same folder publish, plan by default
+
+Usage:
+  forumulate sync <folder> [--apply] [--prune] [--diff] [--org …] [--space …]
+
+  Without --apply it plans and writes nothing; with --apply it is \`publish\`.
+  Takes every publish flag (--only, --force, --purge, --no-verify, --pace,
+  --manifest, --json). See \`forumulate publish --help\` for them and the
+  forumulate.yaml keys.
+
+${OUTPUT}
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+exports.DEV_HELP = `forumulate dev — preview a folder of Markdown locally
+
+Usage:
+  forumulate dev <folder> --org <id|slug> --space <id|slug> [--port 4321] [--site <url>]
+
+  Renders with your space's own renderer and reloads on save. Nothing is written
+  to the space.
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+exports.LOGIN_HELP = `forumulate login — store a token for this API
+
+Usage:
+  forumulate login [--token <pat>]      (asks for it, hidden, when not given)
+
+  The token is checked against the API first, then stored in
+  ~/.config/forumulate/credentials.json (mode 0600), keyed by API base, so a
+  staging token is never sent to production. On every later command a
+  --token beats FORUMULATE_TOKEN, which beats the stored token.
+  Mint a token at https://forumulate.com/account/tokens
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+exports.LOGOUT_HELP = `forumulate logout — forget the stored token for this API
+
+Usage:
+  forumulate logout
+
+  Warns when FORUMULATE_TOKEN is still set, because it still wins.
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+exports.SNAPSHOT_HELP = `forumulate snapshot — save a version snapshot of a space
+
+Usage:
+  forumulate snapshot <orgId> <spaceId> <label…> [--json]
+  (also: forumulate snapshots --help)
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+exports.CONFORMANCE_HELP = `forumulate conformance — run the Content Sync Protocol suite
+
+Usage:
+  forumulate conformance <collectionUrl> [--json]
+
+  Runs against any platform's collection endpoint, ours included. Exit 1 when a
+  check fails.
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+exports.CONTENT_HELP = `forumulate content — a content library's model as code
+
+Usage:
+  forumulate content types --library <id|slug> [--org …] [--out forumulate.d.ts]
+                           [--preview] [--schema <file>] [--check]
+  forumulate content pull --library <id|slug> [--format json|payload] [--out <file>]
+  forumulate content push [file] [--library …] [--dry-run] [--yes] [--force]
+      [--rename type.field=new | block:hero.field=new | library:field=new]
+      [--rename-type old=new] [--rename-block old=new]
+
+  Here --out names the file the command writes (not a stdout redirect).
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+exports.IMPORT_HELP = `forumulate import — bring another CMS's content into a library
+
+Usage:
+  forumulate import <payload|contentful|sanity|strapi|wordpress> <export path>
+      --library <id|slug> [--org …] [--dry-run] [--yes]
+      [--config payload.config.ts] [--publish source|all|none]
+      [--allow-model-removals] [--pace <ms>] [--base-url <url>]
+
+  Always shows a dry run first; a re-run updates what a previous import made.
+
+${OUTPUT}
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+exports.TRANSLATIONS_HELP = `forumulate translations (alias i18n) — every translation capability
+
+Usage:
+  forumulate translations locales list|add|relabel|remove|set [--space …|--library …]
+  forumulate translations status [--locale es,fr] [--fail-on missing,outdated]
+  forumulate translations pull [--out translations] [--locale …] [--only …]
+  forumulate translations push [dir] [--dry-run]
+  forumulate translations auto --locale es [--state missing,outdated] [--publish]
+  forumulate translations labels|overrides pull|push [file] [--format json|xliff]
+  forumulate translations item-locale <itemId> <locale|none>
+  forumulate translations remove <pieceId> <locale> --yes
+  forumulate translations entry <entryId> <locale> [--fields f.json]
+  forumulate translations name <locale> <name…>
+  forumulate translations switcher get|set <f.json>
+  forumulate translations provider status|connect|disconnect
+
+  Here --out names the folder or file the command writes.
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+/** The command → its own help. A command missing here prints the global help. */
+exports.COMMAND_HELP = {
+    publish: exports.PUBLISH_HELP,
+    sync: exports.SYNC_HELP,
+    dev: exports.DEV_HELP,
+    doctor: command_1.DOCTOR_HELP,
+    validate: validate_1.VALIDATE_HELP,
+    login: exports.LOGIN_HELP,
+    logout: exports.LOGOUT_HELP,
+    whoami: whoami_1.WHOAMI_HELP,
+    auth: whoami_1.WHOAMI_HELP,
+    cache: cache_command_1.CACHE_HELP,
+    snapshot: exports.SNAPSHOT_HELP,
+    conformance: exports.CONFORMANCE_HELP,
+    content: exports.CONTENT_HELP,
+    import: exports.IMPORT_HELP,
+    translations: exports.TRANSLATIONS_HELP,
+    i18n: exports.TRANSLATIONS_HELP,
+    check: command_2.CHECK_HELP,
+};
+//# sourceMappingURL=help-commands.js.map

package/dist/help-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-commands.js","sourceRoot":"","sources":["../src/help-commands.ts"],"names":[],"mappings":";;;AAAA,yCAA2C;AAC3C,8CAA+C;AAC/C,6CAA+C;AAC/C,qCAAuC;AACvC,mDAA6C;AAC7C,6EAA6E;AAC7E,6CAAiE;AAEjE;;;;;;;;;GASG;AACH,MAAM,MAAM,GAAG;;8FAE+E,CAAC;AAElF,QAAA,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiE1B,MAAM;;EAEN,4BAAe,EAAE,CAAC;AAEP,QAAA,SAAS,GAAG;;;;;;;;;;EAUvB,MAAM;;EAEN,4BAAe,EAAE,CAAC;AAEP,QAAA,QAAQ,GAAG;;;;;;;;EAQtB,4BAAe,EAAE,CAAC;AAEP,QAAA,UAAU,GAAG;;;;;;;;;;;EAWxB,4BAAe,EAAE,CAAC;AAEP,QAAA,WAAW,GAAG;;;;;;;EAOzB,4BAAe,EAAE,CAAC;AAEP,QAAA,aAAa,GAAG;;;;;;EAM3B,4BAAe,EAAE,CAAC;AAEP,QAAA,gBAAgB,GAAG;;;;;;;;EAQ9B,4BAAe,EAAE,CAAC;AAEP,QAAA,YAAY,GAAG;;;;;;;;;;;;EAY1B,4BAAe,EAAE,CAAC;AAEP,QAAA,WAAW,GAAG;;;;;;;;;;EAUzB,MAAM;;EAEN,4BAAe,EAAE,CAAC;AAEP,QAAA,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;EAkB/B,4BAAe,EAAE,CAAC;AAEpB,iFAAiF;AACpE,QAAA,YAAY,GAAqC;IAC5D,OAAO,EAAE,oBAAY;IACrB,IAAI,EAAE,iBAAS;IACf,GAAG,EAAE,gBAAQ;IACb,MAAM,EAAE,qBAAW;IACnB,QAAQ,EAAE,wBAAa;IACvB,KAAK,EAAE,kBAAU;IACjB,MAAM,EAAE,mBAAW;IACnB,MAAM,EAAE,oBAAW;IACnB,IAAI,EAAE,oBAAW;IACjB,KAAK,EAAE,0BAAU;IACjB,QAAQ,EAAE,qBAAa;IACvB,WAAW,EAAE,wBAAgB;IAC7B,OAAO,EAAE,oBAAY;IACrB,MAAM,EAAE,mBAAW;IACnB,YAAY,EAAE,yBAAiB;IAC/B,IAAI,EAAE,yBAAiB;IACvB,KAAK,EAAE,oBAAgB;CACxB,CAAC"}

package/dist/help.d.ts

@@ -1,3 +1,3 @@
 /** `forumulate help`. The resource groups print their own (`forumulate spaces --help`). */
-export declare const HELP = "forumulate \u2014 Forumulate command-line interface\n\nUsage:\n  forumulate <command> [args]\n\nCommands:\n  login [--token <pat>]              Store a token for this API, so every other\n                                     command stops needing FORUMULATE_TOKEN in\n                                     the environment\n  logout                             Forget the stored token\n  whoami                             Show the authenticated user\n  config set|get|unset|list          Defaults: org, space, library, api-version\n                                     (`forumulate config set org acme`)\n\nEvery API operation:\n  api list [--tag t] [--search w]    Discover operations and their summaries\n  api describe <operationId>         Parameters and body schema, as flags\n  api <operationId> [args] [flags]   Call it: --<param> value, --data @f.json,\n  api <METHOD> <path> [flags]        --field a.b=v, --paginate, --json\n\nResources (each: <group> --help lists its verbs and the operation each calls):\n  Org:      orgs | members | invites | groups | roles | service-accounts (bots)\n            tokens (pats) | webhooks | extensions | audit\n  Spaces:   spaces | snapshots | shape | domains | assets | space-types (types)\n  Docs:     items (pages) | docs | collections | versions | change-requests (crs)\n            openapi | sdks | github (git)\n  Content:  blog | forum | changelog | roadmap | status | events | course\n            careers | forms   (blog/forum/changelog/status: translations \u2026)\n  CMS:      libraries | entries | media | releases | environments (envs)\n  Site:     theme | sites | reader\n  search <query...> [--org]          e.g. spaces create Docs --slug docs --type DOCS\n                                          items create --space docs --file a.md --publish\n                                          docs schedule set <pageId> <when> --space docs\n                                          webhooks deliveries <id>; webhooks replay <id> <d>\n      --out <file>  where a file answer goes (SDK archive, PDF, CSV export)\n  completion bash|zsh|fish           Shell completion script\n\nOlder forms, unchanged:\n  orgs                               List your organizations\n  spaces <orgId>                     List spaces in an org\n  items <orgId> <spaceId>            List what is in a space, with where each\n                                     piece's content lives\n  search <orgId> <query...>          Unified search across docs/forum/blog\n  publish <folder>                   Publish a folder of Markdown: one folder per\n                                     collection, front matter, assets, order,\n                                     and a forumulate.yaml manifest for space,\n                                     site, theme, OpenAPI and monitors. Re-runs\n                                     change only what changed, then read back.\n      --org <id|slug> --space <id|slug>   (or org:/space: in the manifest)\n      --dry-run   print the plan, write nothing (no token needed for a\n                  public space)\n      --prune     remove pages/posts/collections with no file (to the trash)\n      --only a,b  just these slugs, files, folders, or manifest parts\n                  (site, theme, settings, openapi, monitors)\n      --force     re-send every page even if it looks unchanged\n      --no-verify skip the read-back      --pace <ms> gap between writes\n      --manifest <file>  a manifest somewhere else\n  publish <orgId> <spaceId> <pageId> Publish a page\n  publish <orgId> <spaceId> <dir>    The folder form, with org and space given\n  domains <orgId> <spaceId>          List this space's domains and their state\n  domains verify <orgId> <spaceId> <hostname>\n                                     Re-run verification and say what is missing\n  snapshot <orgId> <spaceId> <label> Create a space version snapshot\n  content types --library <id|slug>  TypeScript for a content library's model:\n                                     collections, globals, the block union\n      [--org <id|slug>] [--out forumulate.d.ts] [--preview] [--schema <file>]\n      [--check]   fail (exit 1) when the file is out of date, write nothing\n  content pull --library <id|slug>   Write the model to forumulate.content.json\n      [--format json|payload] [--out <file>]   (payload: forumulate.payload.ts)\n  content push [file]                Show the diff against the library, then\n                                     apply it as a new model version\n      [--library \u2026] [--dry-run] [--yes] [--force]\n      [--rename type.field=new | block:hero.field=new | library:field=new]\n      [--rename-type old=new] [--rename-block old=new]\n  import <payload|contentful|sanity|strapi|wordpress> <export path>\n                                     Bring another CMS's content into a library:\n                                     model, media, entries, references (always\n                                     shows a dry run first)\n                                     Re-running updates entries a\n                                     previous import made. strapi takes a\n                                     folder or an unencrypted export .tar.gz\n      --library <id|slug> [--org \u2026] [--dry-run] [--yes]\n      [--config payload.config.ts]   (payload) the config that becomes the model\n      [--publish source|all|none]    what to publish (default: what was live)\n      [--allow-model-removals] [--pace <ms>] [--base-url <url>] (strapi uploads)\n  translations (alias i18n)          Every translation capability, one vocabulary\n      locales list|add|relabel|remove|set   a space's (--space) or library's\n                  (--library) languages; set es=Espa\u00F1ol fr [--prune] is exact\n      status      each piece \u00D7 language: missing/draft/published/outdated\n                  [--locale es,fr] [--fail-on missing,outdated] (exit 1)\n      pull        one Markdown file per piece per language \u2192 [--out translations]\n                  [--locale \u2026] [--only slug,\u2026] [--include-missing] (stubs)\n      push [dir]  diff the files against the API, write what changed [--dry-run]\n      auto        machine-translate with YOUR DeepL/AI key --locale es\n                  [--state missing,outdated] [--only \u2026] [--force] [--publish]\n                  [--library \u2026 --entry id,\u2026] [--dry-run]\n      labels pull|push [file]       chrome words (--site <id> | --space \u2026)\n      overrides pull|push [file]    org UI string overrides [--prune]\n                  [--format json|xliff] for labels and overrides\n      item-locale <itemId> <locale|none>  correct a piece's declared language\n      remove <pieceId> <locale>     one translation (--yes)\n      entry <entryId> <locale>      a library entry's twin [--fields f.json]\n      name <locale> <name\u2026>         a space's (or --collection's) name\n      switcher get|set <f.json>     the org's reader language switcher\n      provider status|connect|disconnect   your DeepL key (DEEPL_API_KEY)\n  conformance <collectionUrl>        Run the Content Sync Protocol suite against\n                                     any platform's collection endpoint\n  doctor <readerUrl>                 Check a live site from the outside: health,\n                                     public read, canonical, cache headers,\n                                     crawler access, feeds, HTML rewriting\n  help                               Show this help\n\nEnvironment:\n  FORUMULATE_TOKEN   Personal Access Token (Bearer). Overrides a stored one, so\n                     CI keeps working exactly as it did. Mint one at\n                     https://forumulate.com/account/tokens\n  FORUMULATE_URL     The site (default https://forumulate.com); the API is its\n                     /api, i.e. https://forumulate.com/api. A value already\n                     ending in /api is used as-is.\n  FORUMULATE_API_URL Exact API base, for a local API with no /api prefix\n                     (http://localhost:4000). Wins over FORUMULATE_URL.\n  FORUMULATE_ORG, FORUMULATE_SPACE, FORUMULATE_LIBRARY\n                     Defaults for --org, --space and --library; they beat\n                     `forumulate config set`, a flag beats both.\n  FORUMULATE_API_VERSION\n                     Forumulate-Version for api/resource commands\n                     (default 2026-12-01).\n\nThe SDK (ForumulateClient.fromEnv) and the MCP server (@forumulate/mcp) read\nthe same variables. Guide: https://forumulate.com/guides/api-tokens-and-scopes\n\nFlags:\n  --json          Emit raw JSON instead of a formatted summary\n  --dry-run       (api, resources) print the request instead of sending it\n  --dry-run       Plan the work and write nothing (publish of a directory)\n  --version       Print the CLI version\n";
+export declare const HELP = "forumulate \u2014 Forumulate command-line interface\n\nUsage:\n  forumulate <command> [args]\n\nCommands:\n  login [--token <pat>]              Store a token for this API, so every other\n                                     command stops needing FORUMULATE_TOKEN in\n                                     the environment\n  logout                             Forget the stored token\n  whoami [--json]                    Who you are, and WHICH token: its source (--token,\n                                     FORUMULATE_TOKEN or credentials.json), id, name,\n                                     last 4, expiry, narrowing and the API base\n  auth status [--json]               The same report, for scripts\n  config set|get|unset|list          Defaults: org, space, library, api-version\n                                     (`forumulate config set org acme`)\n\nEvery API operation:\n  api list [--tag t] [--search w]    Discover operations and their summaries\n           [--refresh]               ...from the live API's spec, not the bundled one\n  api describe <operationId>         Parameters and body schema, as flags\n  api <operationId> [args] [flags]   Call it: --<param> value, --data @f.json,\n  api <METHOD> <path> [flags]        --field a.b=v, --paginate, --json\n\nResources (each: <group> --help lists its verbs and the operation each calls):\n  Org:      orgs | members | invites | groups | roles | service-accounts (bots)\n            tokens (pats) | keys | integration-tokens (int-tokens)\n            webhooks | extensions | audit\n  Spaces:   spaces | snapshots | shape | domains | assets | space-types (types)\n  Docs:     items (pages) | docs | collections | versions | change-requests (crs)\n            openapi | sdks | github (git)\n  Content:  blog | forum | changelog | roadmap | status | events | course\n            careers | forms   (blog/forum/changelog/status: translations \u2026)\n  CMS:      libraries | entries | media | releases | environments (envs)\n  Site:     theme | sites | reader\n  Jobs:     jobs | backups | imports | manifest   (starters take --wait [--timeout s])\n  search <query...> [--org]          e.g. spaces create Docs --slug docs --type DOCS\n                                          items create --space docs --file a.md --publish\n                                          docs schedule set <pageId> <when> --space docs\n                                          webhooks deliveries <id>; webhooks replay <id> <d>\n      --out <file>  where a file answer goes (SDK archive, PDF, CSV export)\n  cache purge --space <s> [--page p] Drop cached copies (web tier + every CDN); deletes\n                                     nothing\n  completion bash|zsh|fish           Shell completion script\n\nOlder forms, unchanged:\n  orgs                               List your organizations\n  spaces <orgId>                     List spaces in an org\n  items <orgId> <spaceId>            List what is in a space, with where each\n                                     piece's content lives\n  search <orgId> <query...>          Unified search across docs/forum/blog\n  dev <folder>                       Preview a folder of Markdown locally, rendered\n                                     by your space's own renderer; reloads on save.\n      --org <id> --space <id> [--port 4321] [--site <your docs URL>]\n  publish <folder> --org <o> --space <s>\n                                     Publish a folder of Markdown: one folder per\n                                     collection, front matter, assets, order,\n                                     and a forumulate.yaml manifest for space,\n                                     site, theme, OpenAPI and monitors. Re-runs\n                                     change only what changed, then read back.\n      --org <id|slug> --space <id|slug>   (or org:/space: in the manifest)\n      --dry-run   print the plan, write nothing (no token needed for a\n                  public space)\n      --prune     remove pages/posts/collections with no file (to the trash)\n      --only a,b  just these slugs, files, folders, or manifest parts\n                  (site, theme, settings, openapi, monitors)\n      --force     re-send every page even if it looks unchanged\n      --no-verify skip the read-back      --pace <ms> gap between writes\n      --manifest <file>  a manifest somewhere else\n      --diff      print the changed paragraphs and fields of each update\n      --purge page|space|none   what to drop from the cache (default page),\n                  reported per CDN\n      --json      one summary: created, updated, unchanged, trashed, purged,\n                  verify, diffUrl (the run is recorded; publish.completed fires)\n      Pages edited in the studio since the last publish are not overwritten\n      without --force.   Full reference: forumulate publish --help\n  sync <folder>                      Content as code: the same folder publish,\n                                     PLAN BY DEFAULT. Posts (blog), pages\n                                     (docs, custom, legal), FAQ questions,\n                                     changelog releases and blog categories,\n                                     matched by slug; images uploaded once by\n                                     content hash; README, LICENSE, _drafts/,\n                                     dotfiles skipped. Guide:\n                                     https://forumulate.com/guides/content-as-code\n      --apply     write the plan (then read it back)\n      --prune     also remove what has no file (to the trash)\n      --diff      print the changed paragraphs and fields of each update\n      --org, --space, --only, --force, --no-verify, --pace, --manifest, --json\n                  as for publish\n  check links [folder]               Broken internal links, #anchors, pictures and\n                                     (--external) outside links in a folder, before\n                                     publishing; exit 1 when any is broken\n      --space <s> [--org <o>]        the same report for a published space\n      --allow-redirect <hosts>       --ignore <text>   --json\n  publish <folder> --preview <name>  Send the change to a preview link instead of\n                                     publishing it (--comment posts it on the PR)\n  publish <orgId> <spaceId> <pageId> (deprecated) Publish a page \u2014 use items publish\n  publish <orgId> <spaceId> <dir>    (deprecated) \u2014 use publish <dir> --org --space\n  domains <orgId> <spaceId>          List this space's domains and their state\n  domains verify <orgId> <spaceId> <hostname>\n                                     Re-run verification and say what is missing\n  snapshot <orgId> <spaceId> <label> Create a space version snapshot\n  content types --library <id|slug>  TypeScript for a content library's model:\n                                     collections, globals, the block union\n      [--org <id|slug>] [--out forumulate.d.ts] [--preview] [--schema <file>]\n      [--check]   fail (exit 1) when the file is out of date, write nothing\n  content pull --library <id|slug>   Write the model to forumulate.content.json\n      [--format json|payload] [--out <file>]   (payload: forumulate.payload.ts)\n  content push [file]                Show the diff against the library, then\n                                     apply it as a new model version\n      [--library \u2026] [--dry-run] [--yes] [--force]\n      [--rename type.field=new | block:hero.field=new | library:field=new]\n      [--rename-type old=new] [--rename-block old=new]\n  import <payload|contentful|sanity|strapi|wordpress> <export path>\n                                     Bring another CMS's content into a library:\n                                     model, media, entries, references (always\n                                     shows a dry run first)\n                                     Re-running updates entries a\n                                     previous import made. strapi takes a\n                                     folder or an unencrypted export .tar.gz\n      --library <id|slug> [--org \u2026] [--dry-run] [--yes]\n      [--config payload.config.ts]   (payload) the config that becomes the model\n      [--publish source|all|none]    what to publish (default: what was live)\n      [--allow-model-removals] [--pace <ms>] [--base-url <url>] (strapi uploads)\n  translations (alias i18n)          Every translation capability, one vocabulary\n      locales list|add|relabel|remove|set   a space's (--space) or library's\n                  (--library) languages; set es=Espa\u00F1ol fr [--prune] is exact\n      status      each piece \u00D7 language: missing/draft/published/outdated\n                  [--locale es,fr] [--fail-on missing,outdated] (exit 1)\n      pull        one Markdown file per piece per language \u2192 [--out translations]\n                  [--locale \u2026] [--only slug,\u2026] [--include-missing] (stubs)\n      push [dir]  diff the files against the API, write what changed [--dry-run]\n      auto        machine-translate with YOUR DeepL/AI key --locale es\n                  [--state missing,outdated] [--only \u2026] [--force] [--publish]\n                  [--library \u2026 --entry id,\u2026] [--dry-run]\n      labels pull|push [file]       chrome words (--site <id> | --space \u2026)\n      overrides pull|push [file]    org UI string overrides [--prune]\n                  [--format json|xliff] for labels and overrides\n      item-locale <itemId> <locale|none>  correct a piece's declared language\n      remove <pieceId> <locale>     one translation (--yes)\n      entry <entryId> <locale>      a library entry's twin [--fields f.json]\n      name <locale> <name\u2026>         a space's (or --collection's) name\n      switcher get|set <f.json>     the org's reader language switcher\n      provider status|connect|disconnect   your DeepL key (DEEPL_API_KEY)\n  conformance <collectionUrl>        Run the Content Sync Protocol suite against\n                                     any platform's collection endpoint\n  validate [dir]                     Check forumulate.yaml, front matter and $schema\n                                     files against the published schemas, with\n                                     did-you-mean hints. --json; exit 2 if invalid\n  doctor <readerUrl> | --site <s>    Check a live site from the outside: health,\n                                     canonical on both addresses, sitemap, cache\n                                     consistency, root redirect, descriptions,\n                                     llms.txt, favicon, consent tag, white-label\n                                     leaks. --json; exit 1 on any FAIL\n  help [command]                     Show this help, or a command's own\n                                     (every command also takes --help)\n\nEnvironment:\n  FORUMULATE_TOKEN   Personal Access Token (Bearer). Overrides a stored one, so\n                     CI keeps working exactly as it did; --token overrides it.\n                     Mint one at\n                     https://forumulate.com/account/tokens\n  FORUMULATE_URL     The site (default https://forumulate.com); the API is its\n                     /api, i.e. https://forumulate.com/api. A value already\n                     ending in /api is used as-is.\n  FORUMULATE_API_URL Exact API base, for a local API with no /api prefix\n                     (http://localhost:4000). Wins over FORUMULATE_URL.\n  FORUMULATE_ORG, FORUMULATE_SPACE, FORUMULATE_LIBRARY\n                     Defaults for --org, --space and --library; they beat\n                     `forumulate config set`, a flag beats both.\n  FORUMULATE_API_VERSION\n                     Forumulate-Version for api/resource commands\n                     (default 2026-12-01).\n\nThe SDK (ForumulateClient.fromEnv) and the MCP server (@forumulate/mcp) read\nthe same variables. Guide: https://forumulate.com/guides/api-tokens-and-scopes\n\nEvery FORUMULATE_* variable not listed above is reported (with the one you\nprobably meant) by `forumulate whoami` and on any authentication failure.\n\nFlags:\n  --json          Emit raw JSON instead of a formatted summary (stdout only;\n                  progress and warnings go to stderr)\n  --out <file>    Write stdout to a file (never truncated; non-zero exit if the\n                  write fails). content/translations use --out for their own file\n  --jsonl         With --paginate: one JSON row per line, streamed\n  --token <pat>   The token for this run, on every command. Precedence:\n                  --token, then FORUMULATE_TOKEN, then credentials.json. On an\n                  operation with a `token` parameter of its own (registries\n                  set, github connect, domains acme-challenge) the flag is that\n                  parameter; set FORUMULATE_TOKEN for the PAT there\n  --dry-run       (api, resources) print the request instead of sending it\n  --dry-run       Plan the work and write nothing (publish of a directory)\n  --version       Print the CLI version\n\nExit status:\n  0 ok   1 failed (verification mismatch, doctor FAIL)   2 usage\n  3 auth (no token, 401, token not allowed)   4 not found\n  5 conflict (409/412, edited in the studio since your last publish)\n";
 //# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,eAAO,MAAM,IAAI,ipRAwIhB,CAAC"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,eAAO,MAAM,IAAI,0iaAuMhB,CAAC"}

package/dist/help.js

@@ -12,19 +12,24 @@ Commands:
                                      command stops needing FORUMULATE_TOKEN in
                                      the environment
   logout                             Forget the stored token
-  whoami                             Show the authenticated user
+  whoami [--json]                    Who you are, and WHICH token: its source (--token,
+                                     FORUMULATE_TOKEN or credentials.json), id, name,
+                                     last 4, expiry, narrowing and the API base
+  auth status [--json]               The same report, for scripts
   config set|get|unset|list          Defaults: org, space, library, api-version
                                      (\`forumulate config set org acme\`)
 
 Every API operation:
   api list [--tag t] [--search w]    Discover operations and their summaries
+           [--refresh]               ...from the live API's spec, not the bundled one
   api describe <operationId>         Parameters and body schema, as flags
   api <operationId> [args] [flags]   Call it: --<param> value, --data @f.json,
   api <METHOD> <path> [flags]        --field a.b=v, --paginate, --json
 
 Resources (each: <group> --help lists its verbs and the operation each calls):
   Org:      orgs | members | invites | groups | roles | service-accounts (bots)
-            tokens (pats) | webhooks | extensions | audit
+            tokens (pats) | keys | integration-tokens (int-tokens)
+            webhooks | extensions | audit
   Spaces:   spaces | snapshots | shape | domains | assets | space-types (types)
   Docs:     items (pages) | docs | collections | versions | change-requests (crs)
             openapi | sdks | github (git)
@@ -32,11 +37,14 @@ Resources (each: <group> --help lists its verbs and the operation each calls):
             careers | forms   (blog/forum/changelog/status: translations …)
   CMS:      libraries | entries | media | releases | environments (envs)
   Site:     theme | sites | reader
+  Jobs:     jobs | backups | imports | manifest   (starters take --wait [--timeout s])
   search <query...> [--org]          e.g. spaces create Docs --slug docs --type DOCS
                                           items create --space docs --file a.md --publish
                                           docs schedule set <pageId> <when> --space docs
                                           webhooks deliveries <id>; webhooks replay <id> <d>
       --out <file>  where a file answer goes (SDK archive, PDF, CSV export)
+  cache purge --space <s> [--page p] Drop cached copies (web tier + every CDN); deletes
+                                     nothing
   completion bash|zsh|fish           Shell completion script
 
 Older forms, unchanged:
@@ -45,7 +53,11 @@ Older forms, unchanged:
   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 <folder>                   Publish a folder of Markdown: one folder per
+  dev <folder>                       Preview a folder of Markdown locally, rendered
+                                     by your space's own renderer; reloads on save.
+      --org <id> --space <id> [--port 4321] [--site <your docs URL>]
+  publish <folder> --org <o> --space <s>
+                                     Publish a folder of Markdown: one folder per
                                      collection, front matter, assets, order,
                                      and a forumulate.yaml manifest for space,
                                      site, theme, OpenAPI and monitors. Re-runs
@@ -59,8 +71,35 @@ Older forms, unchanged:
       --force     re-send every page even if it looks unchanged
       --no-verify skip the read-back      --pace <ms> gap between writes
       --manifest <file>  a manifest somewhere else
-  publish <orgId> <spaceId> <pageId> Publish a page
-  publish <orgId> <spaceId> <dir>    The folder form, with org and space given
+      --diff      print the changed paragraphs and fields of each update
+      --purge page|space|none   what to drop from the cache (default page),
+                  reported per CDN
+      --json      one summary: created, updated, unchanged, trashed, purged,
+                  verify, diffUrl (the run is recorded; publish.completed fires)
+      Pages edited in the studio since the last publish are not overwritten
+      without --force.   Full reference: forumulate publish --help
+  sync <folder>                      Content as code: the same folder publish,
+                                     PLAN BY DEFAULT. Posts (blog), pages
+                                     (docs, custom, legal), FAQ questions,
+                                     changelog releases and blog categories,
+                                     matched by slug; images uploaded once by
+                                     content hash; README, LICENSE, _drafts/,
+                                     dotfiles skipped. Guide:
+                                     https://forumulate.com/guides/content-as-code
+      --apply     write the plan (then read it back)
+      --prune     also remove what has no file (to the trash)
+      --diff      print the changed paragraphs and fields of each update
+      --org, --space, --only, --force, --no-verify, --pace, --manifest, --json
+                  as for publish
+  check links [folder]               Broken internal links, #anchors, pictures and
+                                     (--external) outside links in a folder, before
+                                     publishing; exit 1 when any is broken
+      --space <s> [--org <o>]        the same report for a published space
+      --allow-redirect <hosts>       --ignore <text>   --json
+  publish <folder> --preview <name>  Send the change to a preview link instead of
+                                     publishing it (--comment posts it on the PR)
+  publish <orgId> <spaceId> <pageId> (deprecated) Publish a page — use items publish
+  publish <orgId> <spaceId> <dir>    (deprecated) — use publish <dir> --org --space
   domains <orgId> <spaceId>          List this space's domains and their state
   domains verify <orgId> <spaceId> <hostname>
                                      Re-run verification and say what is missing
@@ -109,14 +148,21 @@ Older forms, unchanged:
       provider status|connect|disconnect   your DeepL key (DEEPL_API_KEY)
   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
+  validate [dir]                     Check forumulate.yaml, front matter and $schema
+                                     files against the published schemas, with
+                                     did-you-mean hints. --json; exit 2 if invalid
+  doctor <readerUrl> | --site <s>    Check a live site from the outside: health,
+                                     canonical on both addresses, sitemap, cache
+                                     consistency, root redirect, descriptions,
+                                     llms.txt, favicon, consent tag, white-label
+                                     leaks. --json; exit 1 on any FAIL
+  help [command]                     Show this help, or a command's own
+                                     (every command also takes --help)
 
 Environment:
   FORUMULATE_TOKEN   Personal Access Token (Bearer). Overrides a stored one, so
-                     CI keeps working exactly as it did. Mint one at
+                     CI keeps working exactly as it did; --token overrides it.
+                     Mint one at
                      https://forumulate.com/account/tokens
   FORUMULATE_URL     The site (default https://forumulate.com); the API is its
                      /api, i.e. https://forumulate.com/api. A value already
@@ -133,10 +179,27 @@ Environment:
 The SDK (ForumulateClient.fromEnv) and the MCP server (@forumulate/mcp) read
 the same variables. Guide: https://forumulate.com/guides/api-tokens-and-scopes
 
+Every FORUMULATE_* variable not listed above is reported (with the one you
+probably meant) by \`forumulate whoami\` and on any authentication failure.
+
 Flags:
-  --json          Emit raw JSON instead of a formatted summary
+  --json          Emit raw JSON instead of a formatted summary (stdout only;
+                  progress and warnings go to stderr)
+  --out <file>    Write stdout to a file (never truncated; non-zero exit if the
+                  write fails). content/translations use --out for their own file
+  --jsonl         With --paginate: one JSON row per line, streamed
+  --token <pat>   The token for this run, on every command. Precedence:
+                  --token, then FORUMULATE_TOKEN, then credentials.json. On an
+                  operation with a \`token\` parameter of its own (registries
+                  set, github connect, domains acme-challenge) the flag is that
+                  parameter; set FORUMULATE_TOKEN for the PAT there
   --dry-run       (api, resources) print the request instead of sending it
   --dry-run       Plan the work and write nothing (publish of a directory)
   --version       Print the CLI version
+
+Exit status:
+  0 ok   1 failed (verification mismatch, doctor FAIL)   2 usage
+  3 auth (no token, 401, token not allowed)   4 not found
+  5 conflict (409/412, edited in the studio since your last publish)
 `;
 //# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":";;;AAAA,2FAA2F;AAC9E,QAAA,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwInB,CAAC"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":";;;AAAA,2FAA2F;AAC9E,QAAA,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuMnB,CAAC"}

package/dist/io.d.ts

@@ -0,0 +1,33 @@
+import type { Writable } from 'node:stream';
+/**
+ * Where a command's output goes, and the promise that it got there (FMU-B02/D05).
+ *
+ * `--json` piped into another program stopped at exactly 65,536 or 131,072
+ * bytes: the CLI called `process.exit()` the moment the command returned, and
+ * on a pipe Node writes stdout asynchronously, so whatever was still queued
+ * was thrown away — `items list --json | wc -c` said 65536 while the same
+ * command into a file wrote 8 MB. A sink buffers nothing of its own; it writes
+ * through, counts what the stream has not yet flushed, and `finish()` waits for
+ * the stream to say every byte is handed to the OS before the process ends.
+ * A write the OS refuses (a closed pipe, a full disk) is remembered and turns
+ * into a non-zero exit, rather than a truncated file and an exit 0.
+ */
+export interface Sink {
+    line(text: string): void;
+    /** Resolves once everything written is flushed; the first write error, if any. */
+    finish(): Promise<Error | undefined>;
+}
+export declare function streamSink(stream: Writable, opts?: {
+    closeOnFinish?: boolean;
+}): Sink;
+/**
+ * `--out <file>`: stdout into a file, opened on the first line so a command
+ * that prints nothing leaves no empty file behind. The write errors (no such
+ * directory, permission) surface on `finish()` like a pipe's.
+ */
+export declare function fileSink(path: string): Sink;
+/** Commands whose own `--out` means "the file this command writes", not "my stdout". */
+export declare const OWNS_OUT: Set<string>;
+/** The `--out` value a global redirect should use, or undefined. */
+export declare function globalOut(argv: string[]): string | undefined;
+//# sourceMappingURL=io.d.ts.map

package/dist/io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../src/io.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kFAAkF;IAClF,MAAM,IAAI,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;CACtC;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,IAAI,CAoCzF;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAW3C;AAED,wFAAwF;AACxF,eAAO,MAAM,QAAQ,aAA+C,CAAC;AAErE,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAQ5D"}

package/dist/io.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OWNS_OUT = void 0;
+exports.streamSink = streamSink;
+exports.fileSink = fileSink;
+exports.globalOut = globalOut;
+const node_fs_1 = require("node:fs");
+function streamSink(stream, opts = {}) {
+    let failed;
+    stream.on('error', (e) => {
+        failed ??= e;
+    });
+    return {
+        line(text) {
+            if (failed)
+                return;
+            try {
+                stream.write(`${text}\n`);
+            }
+            catch (e) {
+                failed ??= e;
+            }
+        },
+        finish() {
+            return new Promise((resolve) => {
+                let settled = false;
+                const done = (e) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    resolve(failed ?? e ?? undefined);
+                };
+                if (failed)
+                    return done();
+                // A stream that errors never finishes: listen for both.
+                stream.once('error', (e) => done(e));
+                // `end`'s callback carries the error, and Node runs it BEFORE the
+                // 'error' event: dropping its argument resolved "no error" for an
+                // `--out` into a missing directory, and the CLI exited 0 having
+                // written nothing.
+                if (opts.closeOnFinish)
+                    stream.end((e) => done(e ?? undefined));
+                // An empty write's callback runs after every earlier write has flushed.
+                else
+                    stream.write('', (e) => done(e ?? undefined));
+            });
+        },
+    };
+}
+/**
+ * `--out <file>`: stdout into a file, opened on the first line so a command
+ * that prints nothing leaves no empty file behind. The write errors (no such
+ * directory, permission) surface on `finish()` like a pipe's.
+ */
+function fileSink(path) {
+    let inner;
+    return {
+        line(text) {
+            inner ??= streamSink((0, node_fs_1.createWriteStream)(path), { closeOnFinish: true });
+            inner.line(text);
+        },
+        finish() {
+            return inner ? inner.finish() : Promise.resolve(undefined);
+        },
+    };
+}
+/** Commands whose own `--out` means "the file this command writes", not "my stdout". */
+exports.OWNS_OUT = new Set(['content', 'translations', 'i18n']);
+/** The `--out` value a global redirect should use, or undefined. */
+function globalOut(argv) {
+    const cmd = argv.find((a) => !a.startsWith('-'));
+    if (cmd && exports.OWNS_OUT.has(cmd))
+        return undefined;
+    const inline = argv.find((a) => a.startsWith('--out='));
+    if (inline)
+        return inline.slice(6) || undefined;
+    const at = argv.indexOf('--out');
+    const v = at >= 0 ? argv[at + 1] : undefined;
+    return v && !v.startsWith('--') ? v : undefined;
+}
+//# sourceMappingURL=io.js.map

package/dist/io.js.map

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

package/dist/preview-comment.d.ts

@@ -0,0 +1,20 @@
+import { type PreviewResult } from './publish/preview';
+type Fetch = typeof fetch;
+/**
+ * `publish --preview <name> --comment` (FMU-F01): post the preview's link and
+ * diff on the pull request it was built for — and on the next push EDIT that
+ * comment rather than add another, found by the hidden
+ * `<!-- forumulate-preview:<name> -->` marker the API puts in it.
+ *
+ * Host-neutral: GitHub, Gitea/Forgejo (the same REST shape), GitLab and
+ * Bitbucket, each with the token its CI documents for writing comments
+ * (`GITHUB_TOKEN`, `GITEA_TOKEN`, `GITLAB_TOKEN`, `BITBUCKET_TOKEN`). Any other
+ * host: print the comment with `--json` (`previews[].comment`) and post it with
+ * that host's own tool — the recipes in docs/guides/docs-workflow.md do both.
+ *
+ * Answers the pull request's address, or null when there is nothing to
+ * comment on (not a PR build). Throws with a sentence when the host refuses.
+ */
+export declare function postPreviewComment(preview: PreviewResult, env: NodeJS.ProcessEnv, doFetch?: Fetch): Promise<string | null>;
+export {};
+//# sourceMappingURL=preview-comment.d.ts.map

package/dist/preview-comment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-comment.d.ts","sourceRoot":"","sources":["../src/preview-comment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEjE,KAAK,KAAK,GAAG,OAAO,KAAK,CAAC;AAE1B;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,GAAE,KAAa,GACrB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+DxB"}