@spacefast/common 0.0.26 → 0.2.2

package/dist/utils/static-runtime-policy.d.ts

@@ -1,15 +1,12 @@
+import { INTERNAL_REDIRECT_RESPONSE_HEADERS, PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES, PLATFORM_MANAGED_RESPONSE_HEADERS } from "./static-runtime-policy.generated.js";
+export { INTERNAL_REDIRECT_RESPONSE_HEADERS, PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES, PLATFORM_MANAGED_RESPONSE_HEADERS, };
 export declare const PHP_LIKE_EXTENSIONS: string[];
-export declare const INTERNAL_REDIRECT_RESPONSE_HEADERS: string[];
-export declare const PLATFORM_MANAGED_RESPONSE_HEADERS: string[];
-/** Reserved response-header namespaces owned by the platform's own serving signature. */
-export declare const PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES: string[];
 /** True when user rules may neither set nor remove this response header. */
 export declare function isPlatformManagedResponseHeader(name: string): boolean;
 /**
- * The token grammar a `_headers` rule accepts for a header NAME. The routing
- * compiler enforces it; anything that GENERATES `_headers` rules (the Next
- * materializer's framework sections) must gate on the same pattern, so a
- * generated rule can never fail the author's publish.
+ * The token grammar a `_headers` rule accepts for a header NAME. Anything that
+ * GENERATES `_headers` rules must gate on it too, so a generated rule can
+ * never fail the author's publish.
  */
 export declare const HEADER_RULE_NAME_PATTERN: RegExp;
 /** `content-type` → `Content-Type`: the casing compiled rules and generated `_headers` carry. */

package/dist/utils/static-runtime-policy.generated.d.ts

@@ -0,0 +1,16 @@
+/** Reserved response-header namespaces carrying the platform's own serving signature. */
+export declare const PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES: readonly string[];
+/**
+ * The internal-redirect/sendfile family, every vendor spelling: headers that make the web
+ * server produce a different response instead of describing this one. Factored out of the
+ * managed set below so the proxy relay can drop exactly these from an untrusted upstream
+ * while still relaying ordinary response headers the managed set also lists.
+ */
+export declare const INTERNAL_REDIRECT_RESPONSE_HEADERS: readonly string[];
+/**
+ * Rejected/platform-managed response headers: user `_headers` rules can never set or remove
+ * these. The internal-redirect family above is a strict subset — anything the proxy lane
+ * refuses to relay is also refused from `_headers`. Ask isPlatformManagedResponseHeader(),
+ * not this list alone: the reserved prefixes are the other half of the policy.
+ */
+export declare const PLATFORM_MANAGED_RESPONSE_HEADERS: readonly string[];

package/dist/utils/static-runtime-policy.generated.js

@@ -0,0 +1,70 @@
+// @generated by `cargo run -p stattic-runtime-compiler --bin protocol-codegen -- --policy-ts`.
+// `crates/stattic-runtime-policy/src/lib.rs` is the only editable authority.
+/** Reserved response-header namespaces carrying the platform's own serving signature. */
+export const PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES = [
+    "x-spacefast-",
+    "x-stattic-",
+];
+/**
+ * The internal-redirect/sendfile family, every vendor spelling: headers that make the web
+ * server produce a different response instead of describing this one. Factored out of the
+ * managed set below so the proxy relay can drop exactly these from an untrusted upstream
+ * while still relaying ordinary response headers the managed set also lists.
+ */
+export const INTERNAL_REDIRECT_RESPONSE_HEADERS = [
+    "x-accel-buffering",
+    "x-accel-charset",
+    "x-accel-expires",
+    "x-accel-limit-rate",
+    "x-accel-redirect",
+    "x-lighttpd-send-file",
+    "x-lighttpd-sendfile",
+    "x-lighttpd-sendfile2",
+    "x-reproxy-url",
+    "x-sendfile",
+];
+/**
+ * Rejected/platform-managed response headers: user `_headers` rules can never set or remove
+ * these. The internal-redirect family above is a strict subset — anything the proxy lane
+ * refuses to relay is also refused from `_headers`. Ask isPlatformManagedResponseHeader(),
+ * not this list alone: the reserved prefixes are the other half of the policy.
+ */
+export const PLATFORM_MANAGED_RESPONSE_HEADERS = [
+    "accept-ranges",
+    "age",
+    "allow",
+    "alt-svc",
+    "cdn-cache-control",
+    "cloudflare-cdn-cache-control",
+    "connection",
+    "content-encoding",
+    "content-length",
+    "content-range",
+    "cookie",
+    "date",
+    "host",
+    "keep-alive",
+    "location",
+    "netlify-cdn-cache-control",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "server",
+    "set-cookie",
+    "strict-transport-security",
+    "surrogate-control",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "vary",
+    "x-accel-buffering",
+    "x-accel-charset",
+    "x-accel-expires",
+    "x-accel-limit-rate",
+    "x-accel-redirect",
+    "x-lighttpd-send-file",
+    "x-lighttpd-sendfile",
+    "x-lighttpd-sendfile2",
+    "x-reproxy-url",
+    "x-sendfile",
+];

package/dist/utils/static-runtime-policy.js

@@ -1,85 +1,21 @@
 // Single source of truth for static-runtime content policy: PHP-like inert
 // classification and safe content-type forcing.
 //
-// This module is intentionally pure (no node:path, no I/O) so the exact same
-// rules can be mechanically code-generated into the PHP runtime (runtime
-// policies) and exercised by both TypeScript and PHP against one shared fixture
-// (static-runtime-policy.fixtures.json). Do not add platform/filesystem
+// Pure by design (no node:path, no I/O) so the same rules can be code-generated
+// into the PHP runtime and exercised against one shared fixture
+// (static-runtime-policy.fixtures.json). Do not add platform or filesystem
 // behavior here.
-export const PHP_LIKE_EXTENSIONS = ["php", "php3", "php4", "php5", "php7", "php8", "phtml", "phar"];
-// The internal-redirect/sendfile family: headers that do not describe a response, they
-// instruct the web server to produce a different one. Under nginx+php-fpm
-// X-Accel-Redirect (and every vendor spelling of it) turns a response into a server-side
-// read of an arbitrary internal path — a private-path disclosure primitive — while
-// X-Accel-Limit-Rate pins the serving worker for the length of the transfer.
-//
-// These are dangerous from ANY origin we do not control, so this family is factored out
-// of the platform-managed list below: a relay lane (runtime/engine/runtime/proxy.php)
-// must drop exactly this set from an untrusted upstream while still relaying the
-// ordinary response headers (location, content-encoding, content-range, allow) that the
-// rest of the managed list contains.
-export const INTERNAL_REDIRECT_RESPONSE_HEADERS = [
-    "x-accel-buffering",
-    "x-accel-charset",
-    "x-accel-expires",
-    "x-accel-limit-rate",
-    "x-accel-redirect",
-    "x-lighttpd-send-file",
-    "x-lighttpd-sendfile",
-    "x-lighttpd-sendfile2",
-    "x-reproxy-url",
-    "x-sendfile",
-];
-// Rejected/platform-managed response headers (the platform spec "Routing And
-// Headers"): user `_headers` rules can never set or remove these. The
-// internal-redirect/sendfile family above is spread in, so it stays a strict subset —
-// anything the proxy lane refuses to relay is also refused from `_headers`. The rest is
-// the connection and transport surface: hop-by-hop names (Connection, Keep-Alive, TE,
-// Trailer, Transfer-Encoding, Upgrade, Proxy-*), framing, and the edge-cache trio.
+// The platform-managed response-header policy is authored in Rust
+// (crates/stattic-runtime-policy) and generated into the .generated.ts beside
+// this file and into runtime/engine/shared/safety.php, so every managed header
+// name is written down exactly once.
 //
-// `isPlatformManagedResponseHeader` — not this list alone — is the policy: the reserved
-// `x-spacefast-*` / `x-stattic-*` namespaces below carry the platform's own response
-// signature (X-Spacefast-Runtime, X-Spacefast-Version, X-Spacefast-Reason, …), so user
-// rules can never forge or clobber them.
-//
-// Every enforcement point derives from here: the `_headers` compiler in
-// @spacefast/routing imports it directly, the PHP runtime maps and prefixes are
-// generated from it into runtime/engine/shared/safety.php, and the Rust authorities
-// (crates/stattic-runtime-core policy.rs, crates/stattic-zero-runner
-// response_headers.rs) are drift-guarded against it by
-// apps/control-plane/src/runtime/php-policy-parity.test.ts.
-export const PLATFORM_MANAGED_RESPONSE_HEADERS = [
-    "accept-ranges",
-    "age",
-    "allow",
-    "alt-svc",
-    "cdn-cache-control",
-    "cloudflare-cdn-cache-control",
-    "connection",
-    "content-encoding",
-    "content-length",
-    "content-range",
-    "cookie",
-    "date",
-    "host",
-    "keep-alive",
-    "location",
-    "netlify-cdn-cache-control",
-    "proxy-authenticate",
-    "proxy-authorization",
-    "server",
-    "set-cookie",
-    "strict-transport-security",
-    "surrogate-control",
-    "te",
-    "trailer",
-    "transfer-encoding",
-    "upgrade",
-    "vary",
-    ...INTERNAL_REDIRECT_RESPONSE_HEADERS,
-];
-/** Reserved response-header namespaces owned by the platform's own serving signature. */
-export const PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES = ["x-spacefast-", "x-stattic-"];
+// To change it: edit the Rust crate, run
+// `bun scripts/check-finalizer-protocol.mjs --write`, then
+// `bun --filter @spacefast/control-plane runtime:codegen-policy`.
+import { INTERNAL_REDIRECT_RESPONSE_HEADERS, PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES, PLATFORM_MANAGED_RESPONSE_HEADERS, } from "./static-runtime-policy.generated.js";
+export { INTERNAL_REDIRECT_RESPONSE_HEADERS, PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES, PLATFORM_MANAGED_RESPONSE_HEADERS, };
+export const PHP_LIKE_EXTENSIONS = ["php", "php3", "php4", "php5", "php7", "php8", "phtml", "phar"];
 const PLATFORM_MANAGED_RESPONSE_HEADER_SET = new Set(PLATFORM_MANAGED_RESPONSE_HEADERS);
 /** True when user rules may neither set nor remove this response header. */
 export function isPlatformManagedResponseHeader(name) {
@@ -88,10 +24,9 @@ export function isPlatformManagedResponseHeader(name) {
         PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES.some((prefix) => lower.startsWith(prefix)));
 }
 /**
- * The token grammar a `_headers` rule accepts for a header NAME. The routing
- * compiler enforces it; anything that GENERATES `_headers` rules (the Next
- * materializer's framework sections) must gate on the same pattern, so a
- * generated rule can never fail the author's publish.
+ * The token grammar a `_headers` rule accepts for a header NAME. Anything that
+ * GENERATES `_headers` rules must gate on it too, so a generated rule can
+ * never fail the author's publish.
  */
 export const HEADER_RULE_NAME_PATTERN = /^[A-Za-z0-9-]+$/;
 /** `content-type` → `Content-Type`: the casing compiled rules and generated `_headers` carry. */
@@ -105,9 +40,7 @@ export function canonicalHeaderName(input) {
 }
 const PHP_LIKE_EXTENSION_SET = new Set(PHP_LIKE_EXTENSIONS);
 // Immutable-asset detection is NOT decided here: `compiled_cache_class` in
-// crates/stattic-runtime-core (responses.rs) is the one implementation, at
-// finalize. A TS re-implementation lived here once, drifted from the
-// enforcer, and was deleted rather than re-synced.
+// crates/stattic-runtime-core (responses.rs) is the one implementation.
 function lastSegment(filePath) {
     const slash = filePath.lastIndexOf("/");
     return slash >= 0 ? filePath.slice(slash + 1) : filePath;

package/dist/utils/storage-policy.js

@@ -156,8 +156,7 @@ function storageHttpDateTimestamp(weekday, day, month, year, hour, minute, secon
     return date.getTime() + (second === 60 ? 1_000 : 0);
 }
 // HTTP-date has exactly three accepted wire forms (RFC 9110 §5.6.7). General
-// date parsers also accept relative/free-form input such as `tomorrow`, so
-// validators must parse the grammar and validate its calendar components.
+// date parsers also accept `tomorrow`, so this parses the grammar itself.
 export function storageParseHttpDate(value) {
     const input = value.trim();
     let match = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat), (\d{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/.exec(input);

package/dist/utils/upload-session.js

@@ -58,24 +58,18 @@ function parseUploadTargetServerError(raw) {
         ...(requestId ? { requestId } : {}),
     };
 }
-// Manifest paging policy — ONE definition, shared by every uploader (the CLI
-// and the control plane's inline uploader).
+// Manifest paging policy, shared by every uploader.
 //
-// `targets` is a single instruction page, bounded by the instruction payload
-// budget; `summary.upload` counts the whole declared manifest. A short page
-// therefore means a remainder that only `resume` hands out, and an uploader
-// that stops at the first page finalizes a version the runtime rejects with
-// `version_upload_incomplete`. A complete page means there is nothing left to
-// ask for — don't re-resume to double-check the uploads, since the runtime
-// verifies size and sha256 on every PUT and finalize independently enumerates
-// anything still missing.
+// `targets` is one instruction page; `summary.upload` counts the whole
+// manifest. A short page means a remainder only `resume` hands out, and an
+// uploader that stops there finalizes a version the runtime rejects with
+// `version_upload_incomplete`. Don't re-resume a complete page: finalize
+// enumerates anything still missing.
 export function uploadPageHasRemainder(page) {
     return page.summary.upload > page.targets.length;
 }
-// Resume mints the next page from runtime session truth, so a converging
-// session always hands back different work. A page that repeats the previous
-// one is a session that is not draining; retry it a bounded number of times,
-// then fail loudly rather than page forever.
+// An active session always hands back different work. A page that repeats
+// the previous one is not draining, so retry boundedly rather than page forever.
 export const UPLOAD_STALLED_RESUME_MAX_ATTEMPTS = 3;
 export function uploadQueueAdvanced(before, after) {
     if (!after || after.targets.length === 0) {

package/dist/utils/version-path.js

@@ -1,19 +1,14 @@
-// Canonical object-path form (the platform spec "Upload Contract"):
-// UTF-8, Unicode NFC, percent-decoded exactly once. This canonical form is
-// what manifest paths, finalize's normalized paths, route-map keys, and dedup
-// keys all mean. The PHP runtime applies the same transform (rawurldecode once
-// + Normalizer::normalize) at upload and serve time.
+// Canonical object-path form (spec "Upload Contract"): UTF-8, Unicode NFC,
+// percent-decoded exactly once. Manifest paths, route-map keys and dedup keys
+// all mean this form. The PHP runtime applies the same transform.
 // oxlint-disable-next-line no-control-regex -- matching control characters is the point: they are never part of a servable path.
 const CONTROL_CHARS_PATTERN = /[\u0000-\u001f\u007f]/;
-// Structural normalization shared by lookups and intake: forward slashes,
-// no leading slashes, no control characters, no empty/"."/".." segments.
-// Idempotent; safe to apply to already-canonical stored paths (NFC is
-// idempotent, no percent-decoding).
+// Structural normalization shared by lookups and intake. Idempotent, so it is
+// safe on already-canonical stored paths (no percent-decoding here).
 export function normalizeVersionPath(input) {
     const normalized = input.replace(/\\/g, "/").replace(/^\/+/, "").normalize("NFC");
-    // Here rather than only in canonicalizeVersionPath: publish-policy's
-    // staticUploadPathViolation validates with this function, so a control
-    // character in an uploaded path used to pass the policy unclassified.
+    // Here, not only in canonicalizeVersionPath: staticUploadPathViolation
+    // validates with this function.
     if (CONTROL_CHARS_PATTERN.test(normalized)) {
         throw new Error(`invalid_version_path:${input}`);
     }
@@ -34,10 +29,8 @@ export function normalizeVersionPath(input) {
     return safePath;
 }
 // Intake canonicalization: percent-decode EXACTLY once, then NFC, then the
-// structural rules. Applied wherever paths enter the system (manifest intake,
-// archive extraction, runtime upload, serve-time lookup) and never to paths
-// that are already canonical — decode-once is not idempotent. Throws on
-// malformed percent sequences, control characters, traversal, and empty paths.
+// structural rules. Applied wherever paths enter the system, never to paths
+// that are already canonical, because decode-once is not idempotent.
 export function canonicalizeVersionPath(input) {
     let decoded;
     try {
@@ -47,9 +40,8 @@ export function canonicalizeVersionPath(input) {
         throw new Error(`invalid_version_path:${input}`);
     }
     const canonical = decoded.normalize("NFC");
-    // Backslashes as separators are denied at intake (spec "Static path
-    // policy"); only client-side helpers translate Windows separators.
-    // Control characters are rejected by normalizeVersionPath below.
+    // Backslashes are denied at intake (spec "Static path policy"); only
+    // client-side helpers translate Windows separators.
     if (canonical.includes("\\")) {
         throw new Error(`invalid_version_path:${input}`);
     }

package/dist/utils/wpcom-auth-redirects.d.ts

@@ -3,31 +3,22 @@ export type LoginIntentSearch = {
     returnTo?: string | undefined;
 };
 /**
- * Optional query params WordPress.com's OAuth2 authorize endpoint understands
- * (wpcom `wp-content/mu-plugins/oauth2/oauth2.php`). All are cosmetic/flow
- * hints — dropping them never breaks the OAuth handshake.
+ * Optional query params WordPress.com's OAuth2 authorize endpoint understands.
+ * All are cosmetic hints, so dropping them never breaks the handshake.
  */
 export type WpcomAuthorizeExtras = {
     /** Prefills the email field on the WP.com login screen (`user_email`). */
     userEmail?: string | undefined;
     /** Localizes the WP.com login/consent/signup screens (`locale`). */
     locale?: string | undefined;
-    /**
-     * `implicit=false`: WP.com signs the user out of WordPress.com and shows a
-     * fresh login instead of silently reusing the current WP.com session. The
-     * only way to let a user switch WP.com accounts — without it, sign-out on
-     * our side loops them straight back into the same account.
-     */
-    switchAccount?: boolean | undefined;
 };
 export declare function decorateWpcomAuthorizeUrl(authorizeUrl: string, extras?: WpcomAuthorizeExtras): string;
 export declare function buildDashboardLoginPath(input: LoginIntentSearch): string;
 export declare function buildWpcomAuthStartPath(input: LoginIntentSearch & {
     /**
-     * A signed OAuth authorize query (Better Auth's login-page redirect).
-     * Carried through the WordPress.com round trip so the auth server can
-     * resume the authorization flow the moment the session exists. Opaque
-     * here — the auth server verifies its signature.
+     * A signed OAuth authorize query, carried through the WordPress.com round
+     * trip so the auth server can resume the flow once the session exists.
+     * Opaque here; the auth server verifies its signature.
      */
     oauthQuery?: string | undefined;
 }): string;

package/dist/utils/wpcom-auth-redirects.js

@@ -6,14 +6,11 @@ export function decorateWpcomAuthorizeUrl(authorizeUrl, extras = {}) {
         url.searchParams.set("user_email", email);
     }
     // WP.com validates locales against its own list and falls back to English,
-    // so a light shape check is enough here. English is the default — omit it.
+    // so a light shape check is enough here. English is the default, so omit it.
     const locale = extras.locale?.trim().toLowerCase().replace("_", "-");
     if (locale && /^[a-z]{2}(-[a-z]{2})?$/.test(locale) && locale !== "en") {
         url.searchParams.set("locale", locale);
     }
-    if (extras.switchAccount) {
-        url.searchParams.set("implicit", "false");
-    }
     return url.toString();
 }
 export function buildDashboardLoginPath(input) {

package/dist/vocabulary.d.ts

@@ -146,13 +146,13 @@ export declare const EXTERNAL_TERM_ALLOWLIST: readonly [{
     readonly term: "WP Cloud";
     readonly concept: "infra";
     readonly allowedContexts: readonly ["fixed-phrase"];
-    readonly allowedPhrases: readonly ["the same infra as Automattic, WP Cloud, Pressable, and WordPress.com"];
+    readonly allowedPhrases: readonly ["the same infra as Automattic, WP Cloud, Pressable, and WordPress.com", "the same infrastructure as WordPress.com, Tumblr, WordPress VIP and WP Cloud"];
     readonly replacement: "infra";
     readonly reason: string;
 }];
 /**
  * AMENDMENT (DECIDED 2026-07-02): the deploy vocabulary stays, as documented,
- * first-class ALIASES of the canonical vocabulary — `deploy` is an exact alias of
+ * first-class ALIASES of the canonical vocabulary. `deploy` is an exact alias of
  * `publish` (the verb) and `deployments` is an alias of `versions` (the noun).
  * The canonical lifecycle nouns are unchanged: version / channel / build.
  *
@@ -164,7 +164,7 @@ export declare const EXTERNAL_TERM_ALLOWLIST: readonly [{
  *   - Wherever the alias is introduced, attach DEPLOY_ALIAS_DISAMBIGUATION
  *     (the one sanctioned disambiguation sentence) so readers land on the
  *     canonical nouns.
- *   - A bare "deployment" noun in FRESH prose is still discouraged — write
+ *   - A bare "deployment" noun in FRESH prose is still discouraged. Write
  *     "version" (the thing) or "publish" (the act) unless deliberately using
  *     the alias, in which case disambiguate.
  */
@@ -211,7 +211,7 @@ export declare const PROVIDER_HYGIENE: {
         readonly internalName: "WP Cloud";
         readonly replacement: "infra";
         readonly allowedContexts: readonly ["fixed-phrase"];
-        readonly allowedPhrases: readonly ["the same infra as Automattic, WP Cloud, Pressable, and WordPress.com"];
+        readonly allowedPhrases: readonly ["the same infra as Automattic, WP Cloud, Pressable, and WordPress.com", "the same infrastructure as WordPress.com, Tumblr, WordPress VIP and WP Cloud"];
         readonly reason: string;
     };
     readonly codeStorage: {
@@ -247,10 +247,10 @@ export type CliCanonicalVerb = keyof typeof CLI_ALIASES;
  * Disclosure tiers gate how much of a surface (CLI help, `sf docs`) shows by
  * default, so neither humans nor agents are overwhelmed:
  *
- *   - `essential` — the handful of commands/docs a new user or agent needs to
+ *   - `essential`: the handful of commands/docs a new user or agent needs to
  *     make a first publish and manage a space. The default everywhere.
- *   - `full` — the complete product CLI surface (everything not hidden).
- *   - `reference` — absolutely everything, including hidden/advanced commands.
+ *   - `full`: the complete product CLI surface (everything not hidden).
+ *   - `reference`: absolutely everything, including hidden/advanced commands.
  *
  * Tiers are cumulative for ranked surfaces (`reference` ⊇ `full` ⊇ `essential`);
  * see {@link tierVisibleAt}. This is THE source of truth for tier ids + labels.

package/dist/vocabulary.js

@@ -5,29 +5,29 @@
 // dashboard label, or "E2B" in marketing copy).
 //
 // This module is intentionally pure data + types: no side effects, no imports.
-// It is additive — wiring consumers (CLI, MCP, dashboard, docs generators) onto
+// It is additive. Wiring consumers (CLI, MCP, dashboard, docs generators) onto
 // it happens in later chunks. The decisions encoded here are LOCKED:
 //
-//   - `space` is the primitive noun everywhere, user surfaces and platform API
+//   - `space` is the primitive noun everywhere, user surfaces and the Spacefast API
 //     alike. A space IS a site: there is no second host entity to name. `site`
 //     survives only as WP Cloud's own word for the box, in operator surfaces
 //     and the warm-pool inventory.
 //   - `publish` is the verb. AMENDED 2026-07-02: `deploy` / `deployments` are
-//     first-class ALIASES of `publish` / `versions` (see DEPLOY_ALIASES) — they
+//     first-class ALIASES of `publish` / `versions` (see DEPLOY_ALIASES). They
 //     stay listed and documented, always with the sanctioned disambiguation
 //     line (DEPLOY_ALIAS_DISAMBIGUATION) and with the canonical command named
 //     first. A bare "deployment" noun in fresh prose is still discouraged (say
 //     "version"), and the `dep_*` id framing stays retired.
 //   - `version` / `channel` / `build` are the lifecycle nouns.
-//   - `API key` — never "access token".
+//   - `API key`, never "access token".
 //   - `Collab` is the feature; `comment` is the unit.
 //   - `Superpowers` is the page-enhancement feature.
 //   - Provider names stay off public surfaces by default: never "E2B" (say
 //     "Spacefast Builds" / "Spacefast CI"), never "code.storage" / "Pierre".
-//     The infra brand is "WP Cloud" — never "WP.Cloud"/"wp-cloud" (AMENDED
+//     The infra brand is "WP Cloud", never "WP.Cloud"/"wp-cloud" (AMENDED
 //     2026-08-13). Prefer "infra"; when an external reference is genuinely
 //     necessary (provider identity fields, domain conflicts), name WP Cloud
-//     outright — NEVER the euphemism "the hosting provider". Marketing may use
+//     outright, NEVER the euphemism "the hosting provider". Marketing may use
 //     the family line "the same infra as Automattic, WP Cloud, Pressable, and
 //     WordPress.com" (see PROVIDER_HYGIENE).
 export const CONCEPTS = {
@@ -37,7 +37,7 @@ export const CONCEPTS = {
         aliases: [],
         externalTerms: [],
         deprecated: ["project", "site"],
-        description: "The primitive noun everywhere, user surfaces and platform API alike. A " +
+        description: "The primitive noun everywhere, user surfaces and the Spacefast API alike. A " +
             "space IS a site, so 'site' names nothing of ours; 'project' is never " +
             "the primitive.",
     },
@@ -109,7 +109,7 @@ export const CONCEPTS = {
         externalTerms: ["WP Cloud"],
         deprecated: ["code.storage", "Pierre", "the hosting provider"],
         description: "The hosting substrate. Prefer 'infra'; when an external reference is " +
-            "necessary, name 'WP Cloud' (its real spelling) — never the euphemism " +
+            "necessary, name 'WP Cloud' (its real spelling), never the euphemism " +
             "'the hosting provider'. Never 'code.storage'/'Pierre'.",
     },
 };
@@ -119,7 +119,7 @@ export const EXTERNAL_TERM_ALLOWLIST = [
         concept: "publish",
         allowedContexts: ["github-integration", "platform-api"],
         replacement: "version / publish",
-        reason: "GitHub speaks 'deployment'; the platform API keeps it for contract " +
+        reason: "GitHub speaks 'deployment'; the Spacefast API keeps it for contract " +
             "stability. Elsewhere it is a sanctioned alias of 'version' when paired " +
             "with DEPLOY_ALIAS_DISAMBIGUATION (see DEPLOY_ALIASES); bare fresh prose " +
             "still says 'publish a version'.",
@@ -138,7 +138,7 @@ export const EXTERNAL_TERM_ALLOWLIST = [
         concept: "space",
         allowedContexts: ["operator"],
         replacement: "space",
-        reason: "A space IS a site, so 'site' is no longer a Spacefast noun — it is only " +
+        reason: "A space IS a site, so 'site' is no longer a Spacefast noun. It is only " +
             "WP Cloud's word for the box, which operator surfaces and warm-pool " +
             "inventory may use. Every customer-facing surface says 'space'.",
     },
@@ -146,11 +146,18 @@ export const EXTERNAL_TERM_ALLOWLIST = [
         term: "WP Cloud",
         concept: "infra",
         allowedContexts: ["fixed-phrase"],
-        allowedPhrases: ["the same infra as Automattic, WP Cloud, Pressable, and WordPress.com"],
+        allowedPhrases: [
+            "the same infra as Automattic, WP Cloud, Pressable, and WordPress.com",
+            // The product-positioning line every agent-facing surface leads with
+            // (`SPACEFAST_POSITIONING` in brand.ts). Same licence as the family
+            // line above: WP Cloud is named as one of several sibling platforms,
+            // never as "the hosting provider" and never on its own.
+            "the same infrastructure as WordPress.com, Tumblr, WordPress VIP and WP Cloud",
+        ],
         replacement: "infra",
         reason: "AMENDED 2026-08-13: prefer 'infra'. Same day: the platform-api " +
-            "carve-out is revoked — API values say mysql/phpmyadmin/infra, never " +
-            "wpcloud. Name WP Cloud (its real spelling — never 'WP.Cloud') only " +
+            "carve-out is revoked. API values say mysql/phpmyadmin/infra, never " +
+            "wpcloud. Name WP Cloud (its real spelling, never 'WP.Cloud') only " +
             "where the external reference is necessary: domain-conflict copy and " +
             "the marketing family line in allowedPhrases. Never the euphemism " +
             "'the hosting provider'.",
@@ -179,11 +186,18 @@ export const PROVIDER_HYGIENE = {
         internalName: "WP Cloud",
         replacement: "infra",
         allowedContexts: ["fixed-phrase"],
-        allowedPhrases: ["the same infra as Automattic, WP Cloud, Pressable, and WordPress.com"],
+        allowedPhrases: [
+            "the same infra as Automattic, WP Cloud, Pressable, and WordPress.com",
+            // The product-positioning line every agent-facing surface leads with
+            // (`SPACEFAST_POSITIONING` in brand.ts). Same licence as the family
+            // line above: WP Cloud is named as one of several sibling platforms,
+            // never as "the hosting provider" and never on its own.
+            "the same infrastructure as WordPress.com, Tumblr, WordPress VIP and WP Cloud",
+        ],
         reason: "Hosting substrate; prefer 'infra' (AMENDED 2026-08-13, same day: the " +
-            "platform-api carve-out is revoked — API values say mysql/phpmyadmin/" +
+            "platform-api carve-out is revoked. API values say mysql/phpmyadmin/" +
             "infra, never wpcloud). Necessary external references name WP Cloud " +
-            "outright — never 'the hosting provider'.",
+            "outright, never 'the hosting provider'.",
     },
     codeStorage: {
         internalName: "code.storage",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacefast/common",
-  "version": "0.0.26",
+  "version": "0.2.2",
   "license": "MIT",
   "description": "Shared TypeScript contracts and utilities for Spacefast packages.",
   "repository": {
@@ -36,6 +36,11 @@
       "import": "./dist/brand-assets-build.js",
       "default": "./dist/brand-assets-build.js"
     },
+    "./og-template": {
+      "types": "./dist/og-template.d.ts",
+      "import": "./dist/og-template.js",
+      "default": "./dist/og-template.js"
+    },
     "./brand-assets/spacefast-wordmark.svg": "./brand-assets/spacefast-wordmark.svg",
     "./brand-assets/spacefast-sf-full-bleed.svg": "./brand-assets/spacefast-sf-full-bleed.svg",
     "./brand-assets/spacefast-favicon.svg": "./brand-assets/spacefast-favicon.svg",
@@ -96,7 +101,6 @@
     }
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.101.4",
     "culori": "^4.0.2",
     "js-yaml": "^4.1.1",
     "mime": "^4.1.0",
@@ -104,5 +108,13 @@
     "parse5": "^7.3.0",
     "smol-toml": "^1.7.0",
     "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.101.4"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    }
   }
 }

package/dist/agents/client-registry.d.ts

@@ -1,22 +0,0 @@
-export declare const MACHINE_AGENT_CLIENT_IDS: readonly ["universal", "claude-code", "codex", "opencode", "github-copilot", "factory-droid", "cursor", "vscode", "gemini-cli", "windsurf", "cline", "continue"];
-export declare const CONNECT_TARGET_IDS: readonly ["claude-code", "cursor", "vscode", "codex", "claude", "chatgpt"];
-export type MachineAgentClientId = (typeof MACHINE_AGENT_CLIENT_IDS)[number];
-export type ConnectTargetId = (typeof CONNECT_TARGET_IDS)[number];
-export type AgentProductId = MachineAgentClientId | ConnectTargetId;
-export declare const AGENT_PRODUCT_NAMES: {
-    readonly universal: "Universal (.agents)";
-    readonly "claude-code": "Claude Code";
-    readonly codex: "Codex";
-    readonly cursor: "Cursor";
-    readonly vscode: "VS Code";
-    readonly "github-copilot": "GitHub Copilot";
-    readonly "factory-droid": "Factory Droid";
-    readonly opencode: "OpenCode";
-    readonly "gemini-cli": "Gemini CLI";
-    readonly windsurf: "Windsurf";
-    readonly cline: "Cline";
-    readonly continue: "Continue";
-    readonly claude: "Claude";
-    readonly chatgpt: "ChatGPT";
-};
-export declare function agentProductName(id: AgentProductId): string;