@spacefast/common 0.0.2

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

@@ -0,0 +1,103 @@
+// Single source of truth for static-runtime content policy: PHP-like inert
+// classification, immutable-asset detection, 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
+// behavior here.
+export const PHP_LIKE_EXTENSIONS = ["php", "php3", "php4", "php5", "php7", "php8", "phtml", "phar"];
+// Rejected/platform-managed response headers (internal-docs/platform.md "Routing And
+// Headers"): user `_headers` rules can never set or remove these. The list includes the
+// internal-redirect/sendfile family (X-Accel-Redirect, X-Sendfile, X-LIGHTTPD-send-file,
+// X-Accel-Buffering) because under nginx+php-fpm those headers turn a response into a
+// server-side file read — a private-path disclosure primitive. The routing compiler
+// rejects them at publish; the PHP runtime refuses them again at apply time so a compiler
+// gap can never emit one.
+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",
+    "location",
+    "netlify-cdn-cache-control",
+    "server",
+    "set-cookie",
+    "strict-transport-security",
+    "surrogate-control",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "vary",
+    "x-accel-buffering",
+    "x-accel-redirect",
+    "x-lighttpd-send-file",
+    "x-sendfile",
+];
+export const NON_IMMUTABLE_EXTENSIONS = ["html", "htm", "php", "txt", "xml"];
+const PHP_LIKE_EXTENSION_SET = new Set(PHP_LIKE_EXTENSIONS);
+const NON_IMMUTABLE_EXTENSION_SET = new Set(NON_IMMUTABLE_EXTENSIONS);
+const FINGERPRINTED_ASSET_SEGMENT = /^[A-Za-z0-9_-]{8,}$/;
+function lastSegment(filePath) {
+    const slash = filePath.lastIndexOf("/");
+    return slash >= 0 ? filePath.slice(slash + 1) : filePath;
+}
+/** Lowercased extension without the leading dot, posix semantics. Dotfiles have no extension. */
+export function pathExtension(filePath) {
+    const base = lastSegment(filePath);
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
+}
+/** Basename without its extension (the "stem"), posix semantics. */
+export function pathStem(filePath) {
+    const base = lastSegment(filePath);
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(0, dot) : base;
+}
+export function isPhpLikeStaticPath(filePath) {
+    return PHP_LIKE_EXTENSION_SET.has(pathExtension(filePath));
+}
+export function looksLikeBundlerFingerprint(segment) {
+    return (FINGERPRINTED_ASSET_SEGMENT.test(segment) &&
+        (/\d/.test(segment) || /_/.test(segment) || (/[a-z]/.test(segment) && /[A-Z]/.test(segment))));
+}
+export function isImmutableAssetPath(filePath) {
+    if (NON_IMMUTABLE_EXTENSION_SET.has(pathExtension(filePath))) {
+        return false;
+    }
+    const stem = pathStem(filePath);
+    for (let index = 0; index < stem.length; index += 1) {
+        if (index > 0 && stem[index - 1] !== "." && stem[index - 1] !== "-") {
+            continue;
+        }
+        if (looksLikeBundlerFingerprint(stem.slice(index))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Forced inert serving policy for a committed static file. PHP-like files are never executable. */
+export function runtimeFileSafety(filePath) {
+    return {
+        executable: false,
+        forced_download_or_text: isPhpLikeStaticPath(filePath),
+    };
+}
+/** Forces a safe content type for PHP-like files; passes other MIME types through. */
+export function safeRuntimeContentType(filePath, mime) {
+    if (!isPhpLikeStaticPath(filePath)) {
+        return mime;
+    }
+    return pathExtension(filePath) === "phar"
+        ? "application/octet-stream"
+        : "text/plain; charset=utf-8";
+}

package/dist/utils/upload-session.d.ts

@@ -0,0 +1,34 @@
+import type { z } from "zod";
+import type { uploadInstructionsSchema, uploadTargetSchema } from "../contracts/internal.js";
+export type UploadSession = z.infer<typeof uploadInstructionsSchema>;
+export type UploadTarget = z.infer<typeof uploadTargetSchema>;
+export type UploadTargetBody = {
+    body: NonNullable<RequestInit["body"]>;
+    headers?: Record<string, string>;
+    contentLength?: number | undefined;
+    duplex?: "half";
+};
+export type UploadSessionEvent = {
+    type: "target-start";
+    target: UploadTarget;
+} | {
+    type: "target-done";
+    target: UploadTarget;
+} | {
+    type: "target-error";
+    target: UploadTarget;
+    error: unknown;
+};
+export declare class UploadTargetError extends Error {
+    readonly target: UploadTarget;
+    readonly status: number;
+    constructor(target: UploadTarget, status: number, message: string);
+}
+export declare function executeUploadSession(input: {
+    session: UploadSession;
+    targets?: readonly UploadTarget[] | undefined;
+    concurrency?: number | undefined;
+    fetch?: typeof fetch | undefined;
+    prepareTarget?: ((target: UploadTarget) => Promise<UploadTargetBody> | UploadTargetBody) | undefined;
+    onEvent?: ((event: UploadSessionEvent) => void) | undefined;
+}): Promise<void>;

package/dist/utils/upload-session.js

@@ -0,0 +1,69 @@
+export class UploadTargetError extends Error {
+    target;
+    status;
+    constructor(target, status, message) {
+        super(message);
+        this.target = target;
+        this.status = status;
+        this.name = "UploadTargetError";
+    }
+}
+async function runConcurrent(items, concurrency, fn) {
+    let nextIndex = 0;
+    const runWorker = async () => {
+        const item = items[nextIndex++];
+        if (item === undefined) {
+            return;
+        }
+        await fn(item);
+        return runWorker();
+    };
+    await Promise.all(Array.from({ length: Math.min(Math.max(concurrency, 1), items.length || 1) }).map(() => runWorker()));
+}
+export async function executeUploadSession(input) {
+    const targets = input.targets ?? input.session.targets;
+    if (targets.length === 0) {
+        return;
+    }
+    const fetchImpl = input.fetch ?? fetch;
+    await runConcurrent(targets, input.concurrency ?? 4, async (target) => {
+        input.onEvent?.({ type: "target-start", target });
+        try {
+            const prepared = input.prepareTarget
+                ? await input.prepareTarget(target)
+                : defaultUploadTargetBody(target);
+            const headers = {
+                ...target.headers,
+                ...prepared.headers,
+                ...(prepared.contentLength === undefined
+                    ? {}
+                    : { "content-length": String(prepared.contentLength) }),
+            };
+            const response = await fetchImpl(target.url, {
+                method: target.method,
+                headers,
+                body: prepared.body,
+                ...(prepared.duplex ? { duplex: prepared.duplex } : {}),
+            });
+            if (!response.ok) {
+                const details = await response.text().catch(() => "");
+                const suffix = details.trim() ? `: ${details.trim().slice(0, 1_000)}` : "";
+                throw new UploadTargetError(target, response.status, `Upload failed for ${target.path} with ${response.status} ${response.statusText}${suffix}.`);
+            }
+            input.onEvent?.({ type: "target-done", target });
+        }
+        catch (error) {
+            input.onEvent?.({ type: "target-error", target, error });
+            throw error;
+        }
+    });
+}
+function defaultUploadTargetBody(target) {
+    if (target.body?.kind === "url") {
+        return {
+            body: JSON.stringify({ url: target.body.url }),
+            headers: { "content-type": "application/json" },
+        };
+    }
+    throw new Error(`Upload target ${target.path} requires caller-provided bytes.`);
+}

package/dist/utils/urls.d.ts

@@ -0,0 +1,2 @@
+export declare function cleanBaseUrl(value: string | undefined, fallback: string): string;
+export declare function joinBaseUrl(baseUrl: string, path?: string): string;

package/dist/utils/urls.js

@@ -0,0 +1,7 @@
+export function cleanBaseUrl(value, fallback) {
+    return (value?.trim() || fallback).replace(/\/$/, "");
+}
+export function joinBaseUrl(baseUrl, path = "/") {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    return `${baseUrl}${normalizedPath}`;
+}

package/dist/utils/version-path.d.ts

@@ -0,0 +1,6 @@
+export declare function normalizeVersionPath(input: string): string;
+export declare function canonicalizeVersionPath(input: string): string;
+export declare function versionPathForFile(input: {
+    name: string;
+    webkitRelativePath?: string;
+}): string;

package/dist/utils/version-path.js

@@ -0,0 +1,51 @@
+// Canonical object-path form (internal-docs/platform.md "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.
+const CONTROL_CHARS_PATTERN = /[\u0000-\u001f\u007f]/;
+// Structural normalization shared by lookups and intake: forward slashes,
+// no leading slashes, no empty/"."/".." segments. Idempotent; safe to apply
+// to already-canonical stored paths (NFC is idempotent, no percent-decoding).
+export function normalizeVersionPath(input) {
+    const normalized = input.replace(/\\/g, "/").replace(/^\/+/, "").normalize("NFC");
+    const segments = [];
+    for (const segment of normalized.split("/")) {
+        if (!segment || segment === ".") {
+            continue;
+        }
+        if (segment === "..") {
+            throw new Error(`invalid_version_path:${input}`);
+        }
+        segments.push(segment);
+    }
+    const safePath = segments.join("/");
+    if (!safePath) {
+        throw new Error(`invalid_version_path:${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.
+export function canonicalizeVersionPath(input) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(input);
+    }
+    catch {
+        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.
+    if (CONTROL_CHARS_PATTERN.test(canonical) || canonical.includes("\\")) {
+        throw new Error(`invalid_version_path:${input}`);
+    }
+    return normalizeVersionPath(canonical);
+}
+export function versionPathForFile(input) {
+    return normalizeVersionPath(input.webkitRelativePath || input.name);
+}

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

@@ -0,0 +1,14 @@
+export type LoginIntentSearch = {
+    direct?: boolean | undefined;
+    returnTo?: string | undefined;
+};
+export declare function buildDashboardLoginPath(input: LoginIntentSearch): string;
+export declare function buildWpcomAuthStartPath(input: LoginIntentSearch): string;
+export declare function buildPostAuthPath(input: LoginIntentSearch): string;
+export declare function buildWpcomLoginUrl(authorizeUrl: string): string;
+export declare function buildWpcomSignInOptions(input: LoginIntentSearch, dashboardOrigin: string): {
+    readonly provider: "wpcom";
+    readonly callbackURL: string;
+    readonly errorCallbackURL: string;
+    readonly disableRedirect: true;
+};

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

@@ -0,0 +1,49 @@
+import { sanitizeDashboardReturnTo } from "@spacefast/common/utils/auth-redirect";
+export function buildDashboardLoginPath(input) {
+    const url = new URL("/sign-in", "http://dashboard.local");
+    if (input.direct) {
+        url.searchParams.set("direct", "1");
+    }
+    const returnTo = sanitizeDashboardReturnTo(input.returnTo);
+    if (returnTo) {
+        url.searchParams.set("returnTo", returnTo);
+    }
+    return `${url.pathname}${url.search}`;
+}
+export function buildWpcomAuthStartPath(input) {
+    const url = new URL("/v1/auth/wpcom/start", "http://api.local");
+    const returnTo = sanitizeDashboardReturnTo(input.returnTo);
+    if (returnTo) {
+        url.searchParams.set("returnTo", returnTo);
+    }
+    return `${url.pathname}${url.search}`;
+}
+export function buildPostAuthPath(input) {
+    const url = new URL("/sign-in", "http://dashboard.local");
+    url.searchParams.set("auth_callback", "1");
+    const returnTo = sanitizeDashboardReturnTo(input.returnTo);
+    if (returnTo) {
+        url.searchParams.set("returnTo", returnTo);
+    }
+    return `${url.pathname}${url.search}`;
+}
+export function buildWpcomLoginUrl(authorizeUrl) {
+    const authUrl = new URL(authorizeUrl);
+    const loginUrl = new URL("https://wordpress.com/log-in");
+    const clientId = authUrl.searchParams.get("client_id");
+    if (clientId) {
+        loginUrl.searchParams.set("client_id", clientId);
+    }
+    loginUrl.searchParams.set("redirect_to", authUrl.toString());
+    return loginUrl.toString();
+}
+export function buildWpcomSignInOptions(input, dashboardOrigin) {
+    const errorCallbackUrl = new URL(buildDashboardLoginPath(input), dashboardOrigin);
+    errorCallbackUrl.searchParams.set("claim_error", "login");
+    return {
+        provider: "wpcom",
+        callbackURL: new URL(buildPostAuthPath(input), dashboardOrigin).toString(),
+        errorCallbackURL: errorCallbackUrl.toString(),
+        disableRedirect: true,
+    };
+}

package/dist/utils/zero-realtime-signature.d.ts

@@ -0,0 +1,12 @@
+import { type ZeroRealtimeEvent } from "../contracts/zero.js";
+export declare const ZERO_REALTIME_EVENT_SIGNATURE_HEADER = "x-spacefast-zero-event-signature";
+export declare function canonicalZeroRealtimeEventPayload(event: ZeroRealtimeEvent): string;
+export declare function signZeroRealtimeEvent(input: {
+    event: ZeroRealtimeEvent;
+    secret: string | null | undefined;
+}): string | null;
+export declare function verifyZeroRealtimeEventSignature(input: {
+    event: ZeroRealtimeEvent;
+    secret: string | null | undefined;
+    signature: string | null | undefined;
+}): boolean;

package/dist/utils/zero-realtime-signature.js

@@ -0,0 +1,45 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { zeroRealtimeEventSchema } from "../contracts/zero.js";
+const ZERO_REALTIME_EVENT_SIGNATURE_PREFIX = "sha256=";
+export const ZERO_REALTIME_EVENT_SIGNATURE_HEADER = "x-spacefast-zero-event-signature";
+function canonicalize(value) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "number" ||
+        typeof value === "string") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalize(item));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => [key, canonicalize(item)]));
+    }
+    return null;
+}
+export function canonicalZeroRealtimeEventPayload(event) {
+    return JSON.stringify(canonicalize(zeroRealtimeEventSchema.parse(event)));
+}
+export function signZeroRealtimeEvent(input) {
+    const secret = input.secret?.trim();
+    if (!secret) {
+        return null;
+    }
+    return `${ZERO_REALTIME_EVENT_SIGNATURE_PREFIX}${createHmac("sha256", secret)
+        .update(canonicalZeroRealtimeEventPayload(input.event))
+        .digest("hex")}`;
+}
+export function verifyZeroRealtimeEventSignature(input) {
+    const expected = signZeroRealtimeEvent({ event: input.event, secret: input.secret });
+    const actual = input.signature?.trim();
+    if (!expected || !actual) {
+        return false;
+    }
+    const expectedBytes = Buffer.from(expected);
+    const actualBytes = Buffer.from(actual);
+    return (expectedBytes.byteLength === actualBytes.byteLength &&
+        timingSafeEqual(expectedBytes, actualBytes));
+}

package/dist/vocabulary.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Contexts in which an otherwise-discouraged external term is still allowed.
+ * A drift-guard uses these to tell a real leak from a sanctioned use.
+ */
+export type TermContext = 
+/** The public platform/tenant API surface (contracts, OpenAPI, SDK). */
+"platform-api"
+/** The GitHub integration vocabulary (push deploys, deployment status). */
+ | "github-integration"
+/** A fixed marketing phrase, spelled out verbatim in `allowedPhrases`. */
+ | "fixed-phrase";
+/** A single canonical product concept and the words allowed to express it. */
+export interface Concept {
+    /** Stable machine id for cross-referencing (never user-visible). */
+    readonly id: string;
+    /** The one noun to use on user surfaces (already cased for prose). */
+    readonly canonicalNoun: string;
+    /** The verb form, when the concept is also an action (e.g. publish). */
+    readonly verb?: string;
+    /** Equivalent words that are fine to use interchangeably on any surface. */
+    readonly aliases: readonly string[];
+    /**
+     * External-facing synonyms that are NOT allowed on general user surfaces but
+     * are sanctioned in specific contexts. Each appears in EXTERNAL_TERM_ALLOWLIST
+     * with its allowed contexts.
+     */
+    readonly externalTerms?: readonly string[];
+    /**
+     * Retired terms that must never appear on any surface. A drift-guard should
+     * flag these unconditionally and suggest `canonicalNoun`/`verb`.
+     */
+    readonly deprecated?: readonly string[];
+    /** One-line rationale, for humans reading the registry. */
+    readonly description: string;
+}
+export declare const CONCEPTS: {
+    readonly space: {
+        readonly id: "space";
+        readonly canonicalNoun: "space";
+        readonly aliases: readonly [];
+        readonly externalTerms: readonly ["site"];
+        readonly deprecated: readonly ["project"];
+        readonly description: string;
+    };
+    readonly publish: {
+        readonly id: "publish";
+        readonly canonicalNoun: "publish";
+        readonly verb: "publish";
+        readonly aliases: readonly ["go live"];
+        readonly externalTerms: readonly ["deployment", "deploy"];
+        readonly deprecated: readonly ["dep_", "dep_build_", "dep_version_"];
+        readonly description: string;
+    };
+    readonly version: {
+        readonly id: "version";
+        readonly canonicalNoun: "version";
+        readonly verb: "publish";
+        readonly aliases: readonly [];
+        readonly deprecated: readonly ["deployment"];
+        readonly description: string;
+    };
+    readonly channel: {
+        readonly id: "channel";
+        readonly canonicalNoun: "channel";
+        readonly aliases: readonly [];
+        readonly description: "A named serving lane a version is published to (e.g. production, preview).";
+    };
+    readonly build: {
+        readonly id: "build";
+        readonly canonicalNoun: "build";
+        readonly verb: "build";
+        readonly aliases: readonly [];
+        readonly externalTerms: readonly ["E2B"];
+        readonly description: string;
+    };
+    readonly apiKey: {
+        readonly id: "apiKey";
+        readonly canonicalNoun: "API key";
+        readonly aliases: readonly [];
+        readonly deprecated: readonly ["access token", "access-token", "accessToken"];
+        readonly description: "The credential users create to authenticate the API/CLI. Never 'access token'.";
+    };
+    readonly collab: {
+        readonly id: "collab";
+        readonly canonicalNoun: "Collab";
+        readonly aliases: readonly [];
+        readonly description: "The collaboration feature (the comment surface). Capital-C as a feature name.";
+    };
+    readonly comment: {
+        readonly id: "comment";
+        readonly canonicalNoun: "comment";
+        readonly aliases: readonly [];
+        readonly description: "A single unit posted within Collab. Lowercase as a common noun.";
+    };
+    readonly superpowers: {
+        readonly id: "superpowers";
+        readonly canonicalNoun: "Superpowers";
+        readonly aliases: readonly [];
+        readonly description: "The page-enhancement feature. Capital-S as a feature name.";
+    };
+    readonly infra: {
+        readonly id: "infra";
+        readonly canonicalNoun: "infra";
+        readonly aliases: readonly ["infrastructure"];
+        readonly externalTerms: readonly ["WP.Cloud"];
+        readonly deprecated: readonly ["code.storage", "Pierre"];
+        readonly description: string;
+    };
+};
+export type ConceptId = keyof typeof CONCEPTS;
+/** One sanctioned exception: a discouraged term that is OK in listed contexts. */
+export interface ExternalTermRule {
+    /** The discouraged external term (matched case-insensitively by guards). */
+    readonly term: string;
+    /** The concept this term is an external synonym of. */
+    readonly concept: ConceptId;
+    /** Contexts where the term is allowed. Anywhere else is a leak. */
+    readonly allowedContexts: readonly TermContext[];
+    /** For `fixed-phrase` contexts, the exact phrases that license the term. */
+    readonly allowedPhrases?: readonly string[];
+    /** The canonical replacement to suggest when the use is NOT allowed. */
+    readonly replacement: string;
+    readonly reason: string;
+}
+export declare const EXTERNAL_TERM_ALLOWLIST: readonly [{
+    readonly term: "deployment";
+    readonly concept: "publish";
+    readonly allowedContexts: readonly ["github-integration", "platform-api"];
+    readonly replacement: "version / publish";
+    readonly reason: string;
+}, {
+    readonly term: "deploy";
+    readonly concept: "publish";
+    readonly allowedContexts: readonly ["github-integration", "platform-api"];
+    readonly replacement: "publish";
+    readonly reason: "Push-deploys and the deploy status come from the GitHub integration.";
+}, {
+    readonly term: "site";
+    readonly concept: "space";
+    readonly allowedContexts: readonly ["platform-api"];
+    readonly replacement: "space";
+    readonly reason: string;
+}, {
+    readonly term: "WP.Cloud";
+    readonly concept: "infra";
+    readonly allowedContexts: readonly ["platform-api", "fixed-phrase"];
+    readonly allowedPhrases: readonly ["built on WP.Cloud"];
+    readonly replacement: "infra";
+    readonly reason: string;
+}];
+/** An internal provider name and how it must be referred to in public copy. */
+export interface ProviderHygieneRule {
+    /** Internal/vendor name that must not appear on public surfaces. */
+    readonly internalName: string;
+    /** What to say instead, externally. */
+    readonly replacement: string;
+    /** Contexts (if any) where the internal name is still permitted. */
+    readonly allowedContexts: readonly TermContext[];
+    /** Exact phrases that license the internal name in `fixed-phrase` contexts. */
+    readonly allowedPhrases?: readonly string[];
+    readonly reason: string;
+}
+export declare const PROVIDER_HYGIENE: {
+    readonly e2b: {
+        readonly internalName: "E2B";
+        readonly replacement: "Spacefast Builds / Spacefast CI";
+        readonly allowedContexts: readonly [];
+        readonly reason: "The build sandbox vendor is never named; it is 'Spacefast Builds'.";
+    };
+    readonly wpcloud: {
+        readonly internalName: "WP.Cloud";
+        readonly replacement: "infra";
+        readonly allowedContexts: readonly ["platform-api", "fixed-phrase"];
+        readonly allowedPhrases: readonly ["built on WP.Cloud"];
+        readonly reason: string;
+    };
+    readonly codeStorage: {
+        readonly internalName: "code.storage";
+        readonly replacement: "infra";
+        readonly allowedContexts: readonly [];
+        readonly reason: "Internal storage layer; never surfaced.";
+    };
+    readonly pierre: {
+        readonly internalName: "Pierre";
+        readonly replacement: "Spacefast Builds / Spacefast CI";
+        readonly allowedContexts: readonly [];
+        readonly reason: "Internal git/CI dependency; never surfaced.";
+    };
+};
+export type ProviderHygieneId = keyof typeof PROVIDER_HYGIENE;
+/**
+ * Canonical MCP tool naming. Tools are exposed under a namespaced canonical id
+ * (`spacefast_<verb>`) plus a bare alias (`<verb>`) for clients where per-server
+ * namespacing is already guaranteed.
+ *
+ * This replaces the current inverted form (`execute_spacefast`,
+ * `resume_spacefast`) and the un-namespaced verbs (`publish`, `prepare_publish`).
+ */
+export declare const MCP_TOOL_NAMING: {
+    /** Prefix that makes a tool id unambiguous across servers. */
+    readonly namespacePrefix: "spacefast_";
+    /** Canonical, namespaced tool id for a verb (e.g. "publish" → "spacefast_publish"). */
+    readonly canonical: (verb: string) => string;
+    /** Bare alias for a verb, valid only where per-server namespacing is guaranteed. */
+    readonly alias: (verb: string) => string;
+    /** Both names a verb should register under. */
+    readonly names: (verb: string) => {
+        readonly canonical: string;
+        readonly alias: string;
+    };
+};
+/**
+ * Verbs that have a locked canonical MCP tool name. Generators should emit
+ * `spacefast_<verb>` as the primary id and `<verb>` as the bare alias.
+ */
+export declare const MCP_CANONICAL_VERBS: readonly ["publish", "execute", "prepare_publish", "resume_publish", "finalize_publish"];
+export type McpCanonicalVerb = (typeof MCP_CANONICAL_VERBS)[number];
+/**
+ * Canonical CLI verb → accepted aliases. Reused across command groups so every
+ * `list`/`remove`/`create` command exposes the same shorthands. A command file
+ * spreads `CLI_ALIASES[canonical]` into its `aliases` array.
+ */
+export declare const CLI_ALIASES: {
+    readonly list: readonly ["ls"];
+    readonly remove: readonly ["rm", "delete"];
+    readonly create: readonly ["add"];
+};
+export type CliCanonicalVerb = keyof typeof CLI_ALIASES;
+/** Aliases registered for a canonical CLI verb (empty for unknown verbs). */
+export declare function cliAliasesFor(verb: CliCanonicalVerb): readonly string[];