@spacefast/common 0.0.3 → 0.0.6

package/dist/docs/error-docs.d.ts

@@ -8,5 +8,3 @@ export type ErrorDoc = {
 export declare const ERROR_DOCS: Record<ErrorCode, ErrorDoc>;
 /** One generated reference page per error code; the `.md` twin is this exact text. */
 export declare function errorDocMarkdown(code: ErrorCode): string;
-/** The generated `/docs/errors` index page; the `.md` twin is this exact text. */
-export declare function errorDocsIndexMarkdown(): string;

package/dist/docs/error-docs.js

@@ -5,7 +5,8 @@
 // and pages never go missing. apps/www renders the HTML pages and writes the
 // `.md` twins from the same entries.
 import { BRAND } from "../brand.js";
-import { ERROR_CODES, errorDocsUrl } from "../contracts/error-codes.js";
+import { ERROR_CODES, errorDocsUrl, } from "../contracts/error-codes.js";
+// Restore upgrade-oriented recovery copy here when paid plan checkout is live.
 export const ERROR_DOCS = {
     abuse_report_invalid_transition: {
         summary: "The abuse report cannot move to the requested status from its current status.",
@@ -33,7 +34,7 @@ export const ERROR_DOCS = {
     },
     anonymous_expired: {
         summary: "This anonymous space expired before it was claimed.",
-        fix: "Publish again to get a fresh space, or claim spaces before their expiry next time.",
+        fix: "Publish a fresh space and share its claim link right away this time. If you meant to update a space that is still live, check .spacefast/ (or your saved receipt) for its spaceId and publish to that with its credential instead of creating a new space.",
     },
     anonymous_pool_unavailable: {
         summary: "No pooled capacity is available for anonymous publishes right now.",
@@ -43,6 +44,10 @@ export const ERROR_DOCS = {
         summary: "Too many anonymous publishes came from this network in a short window.",
         fix: "Wait for the window to pass, or sign in with an API key for higher limits.",
     },
+    anonymous_space_limit_reached: {
+        summary: "Too many unclaimed anonymous spaces are already active for this client.",
+        fix: "Log in to publish into an authenticated space, or claim/delete an existing anonymous space before creating another.",
+    },
     archive_body_required: {
         summary: "This request must carry an archive body but none was provided.",
         fix: "Send the zip bytes as the request body with the matching content-type header.",
@@ -145,7 +150,7 @@ export const ERROR_DOCS = {
     },
     claimed_space_quota_exceeded: {
         summary: "Claiming this space would exceed the target team's space quota.",
-        fix: "Delete unused spaces or upgrade the plan, then claim again.",
+        fix: "Delete unused spaces, then claim again. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     cli_upgrade_required: {
         summary: "This CLI version is too old to talk to the API safely.",
@@ -165,7 +170,15 @@ export const ERROR_DOCS = {
     },
     config_templates_over_limit: {
         summary: "The configuration declares more template files than the plan allows.",
-        fix: "Reduce the number of template entries in sf.jsonc.",
+        fix: "Reduce the number of template entries in sf.jsonc. Still stuck? POST /v1/feedback with the error code and request id.",
+    },
+    continuation_unavailable: {
+        summary: "This claim token can no longer be exchanged for an access token.",
+        fix: "If the space is claimed, ask its owner for an access token (dashboard: Account → Access tokens). If it is still unclaimed, keep using the claim token as bearer auth instead of exchanging it. Still stuck? POST /v1/feedback with the error code and request id.",
+    },
+    continuation_used: {
+        summary: "This claim token was already exchanged for a durable access token.",
+        fix: "Authenticate with the exchanged access token (check .spacefast/state.json or wherever it was saved). If it was lost, ask the space owner to mint a new access token.",
     },
     credential_expired: {
         summary: "The credential used for this request has expired.",
@@ -191,9 +204,13 @@ export const ERROR_DOCS = {
         summary: "CSAM enforcement policy cannot be set below the mandatory account-suspend floor.",
         fix: "Set the CSAM category enforcement tier to account suspension.",
     },
+    datacenters_unavailable: {
+        summary: "Placement regions are temporarily unavailable.",
+        fix: "Retry after the datacenter list has synced.",
+    },
     data_location_immutable: {
-        summary: "A space's data location cannot be changed after placement.",
-        fix: "Create a new space in the desired region and transfer content into it.",
+        summary: "This request tried to change data location through an immutable path.",
+        fix: "Use PATCH /v1/spaces/{id} to queue a region move when region changes are supported for this space.",
     },
     device_authorization_failed: {
         summary: "The device login request failed and cannot be completed.",
@@ -373,7 +390,7 @@ export const ERROR_DOCS = {
     },
     domain_quota_exceeded: {
         summary: "Adding this domain would exceed the plan's external domain allowance.",
-        fix: "Remove unused domains or upgrade the plan.",
+        fix: "Remove unused domains. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     domain_registration_active: {
         summary: "The domain has an active registration, which blocks this operation.",
@@ -421,7 +438,7 @@ export const ERROR_DOCS = {
     },
     feature_unavailable: {
         summary: "This feature is not available on this deployment or plan.",
-        fix: "Check the feature's availability, or upgrade if it is plan-gated.",
+        fix: "Check the feature's availability and try again when it is enabled for your team.",
     },
     files_mode_does_not_support_spa: {
         summary: "SPA fallback cannot be combined with files-listing mode.",
@@ -433,11 +450,11 @@ export const ERROR_DOCS = {
     },
     free_external_proxy_disabled: {
         summary: "Proxy routes to external upstreams are not available on the Free plan.",
-        fix: "Remove the proxy rules or upgrade the plan to enable external proxying.",
+        fix: "Remove the proxy rules before publishing. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     free_headers_basic_auth_disabled: {
         summary: "Basic-Auth via _headers is not available on the Free plan.",
-        fix: "Use space password protection, or upgrade the plan for _headers Basic Auth.",
+        fix: "Use space password protection instead. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     idempotency_conflict_in_progress: {
         summary: "Another request with the same Idempotency-Key is still in flight.",
@@ -483,6 +500,10 @@ export const ERROR_DOCS = {
         summary: "The claim token is invalid or does not match this space.",
         fix: "Use the exact claim URL returned by the publish that created the space.",
     },
+    invalid_continuation_token: {
+        summary: "The continuation token is invalid, expired, or already finished.",
+        fix: "Restart the originating flow to obtain a fresh requiresAction envelope and continuation token.",
+    },
     invalid_data_location: {
         summary: "The requested data location is not a supported region.",
         fix: "Pick a region from the documented data locations, or use auto.",
@@ -571,6 +592,14 @@ export const ERROR_DOCS = {
         summary: "An invitation for this email already exists on the team.",
         fix: "Resend the existing invitation instead of creating a new one.",
     },
+    invitation_email_mismatch: {
+        summary: "This invitation was addressed to a different email than the accepting user.",
+        fix: "Sign in as the invited email, or ask an admin to invite your current address.",
+    },
+    invitation_expired: {
+        summary: "The invitation has expired and can no longer be accepted.",
+        fix: "Ask a team admin to send a fresh invitation, then accept the new one.",
+    },
     invitation_not_pending: {
         summary: "The invitation is no longer pending.",
         fix: "Create a new invitation if the member still needs to join.",
@@ -601,7 +630,7 @@ export const ERROR_DOCS = {
     },
     log_retention_clamped: {
         summary: "The requested log range exceeds the plan's retention and was clamped.",
-        fix: "Narrow the range, or upgrade the plan for longer retention.",
+        fix: "Narrow the range.",
     },
     lost_domain_control: {
         summary: `${BRAND.productName} no longer observes DNS control for this domain.`,
@@ -635,6 +664,10 @@ export const ERROR_DOCS = {
         summary: "A required route parameter is missing from the request path.",
         fix: "Check the endpoint path in the API reference and include every parameter.",
     },
+    move_target_capacity_lost: {
+        summary: "The selected move target no longer has capacity for the space.",
+        fix: "Retry the move with a different target or after capacity is freed.",
+    },
     nameserver_delegation_required: {
         summary: `This operation requires the domain to be delegated to ${BRAND.productName} nameservers.`,
         fix: "Update the domain's nameservers at the registrar, then retry once delegation propagates.",
@@ -671,6 +704,14 @@ export const ERROR_DOCS = {
         summary: "This plan grant was already revoked.",
         fix: "Nothing to do; create a new grant if the team should regain the plan.",
     },
+    placement_invalid_burstable: {
+        summary: "The placement burstable option was used with an unsupported placement mode.",
+        fix: 'Set placement.mode to "dedicated" before setting placement.burstable, or remove the burstable option.',
+    },
+    placement_mode_requires_plan: {
+        summary: "The requested placement mode requires a plan entitlement.",
+        fix: "Upgrade the team plan or choose shared placement.",
+    },
     platform_tenant_immutable_client: {
         summary: "The tenant's provider client cannot be changed.",
         fix: "Create a new tenant with the desired provider client instead.",
@@ -717,7 +758,7 @@ export const ERROR_DOCS = {
     },
     publish_archive_expanded_size_exceeded: {
         summary: "The archive expands beyond the maximum allowed total size.",
-        fix: "Reduce the content size or upgrade the plan for higher limits.",
+        fix: "Reduce the content size.",
     },
     publish_archive_file_count_exceeded: {
         summary: "The archive contains more files than the allowed ceiling.",
@@ -769,7 +810,7 @@ export const ERROR_DOCS = {
     },
     routing_rules_over_plan: {
         summary: "The published _redirects and _headers exceed the plan's routing-rule allowance.",
-        fix: "Reduce the rule count or upgrade the plan.",
+        fix: "Reduce the rule count. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     runtime_action_forbidden: {
         summary: "The runtime credential does not allow this action.",
@@ -777,7 +818,7 @@ export const ERROR_DOCS = {
     },
     runtime_api_not_found: {
         summary: "The runtime management endpoint was not found.",
-        fix: "Check the runtime API path against the runtime contract.",
+        fix: "Send the request with the management hostname as the Host header; management routes are not served on public hostnames.",
     },
     runtime_callback_forbidden: {
         summary: "The runtime callback could not be authenticated.",
@@ -888,13 +929,17 @@ export const ERROR_DOCS = {
         fix: "Increase the polling interval; aggressive polling invalidates the flow.",
     },
     space_already_claimed: {
-        summary: "The space was already claimed by someone else.",
-        fix: "Publish a new space; a claim can only succeed once.",
+        summary: "The space was already claimed; a claim can only succeed once.",
+        fix: "If you are the agent that published this space, exchange your claim token once at POST /v1/anonymous-claim/exchange for a durable access token and keep publishing to the same spaceId. Otherwise ask the owner for access — do not publish a duplicate space.",
     },
     space_claim_unavailable: {
         summary: "This space cannot be claimed.",
         fix: "Only anonymous, unexpired spaces with a valid claim token can be claimed.",
     },
+    space_claimed_credential_available: {
+        summary: "The space was claimed and its owner kept agent publishing enabled; this claim token now works exactly once as an exchange voucher.",
+        fix: "POST /v1/anonymous-claim/exchange with this claim token as bearer auth. Save the returned access token (e.g. .spacefast/state.json), then retry the request with it as Authorization: Bearer. Do not publish a new space.",
+    },
     space_disabled: {
         summary: "The space is disabled and cannot be served or modified.",
         fix: "Check the disabled reason on the space; it explains the path to restore it.",
@@ -971,9 +1016,13 @@ export const ERROR_DOCS = {
         summary: "This operation only applies to static-runtime spaces.",
         fix: "Target a static-runtime space.",
     },
+    storage_bucket_unavailable: {
+        summary: "No usable internal storage bucket is configured for this operation.",
+        fix: "Check the storage bucket registry and credential environment references, then retry.",
+    },
     storage_quota_exceeded: {
         summary: "The publish would exceed the plan's storage allowance.",
-        fix: "Delete old versions or upgrade the plan.",
+        fix: "Delete old versions. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     storage_usage_unavailable: {
         summary: "Storage usage could not be computed right now.",
@@ -991,6 +1040,10 @@ export const ERROR_DOCS = {
         summary: "The hostname was recently bound elsewhere; a takeover notice window applies.",
         fix: "Retry after the notice window, or have the current holder release the binding.",
     },
+    team_member_quota_exceeded: {
+        summary: "Inviting this person would exceed the team's seat limit.",
+        fix: "Remove a team member or cancel a pending invitation to free a seat; pending invitations count toward the limit.",
+    },
     team_ref_required: {
         summary: "A team reference is required for this operation.",
         fix: "Pass the team id or slug.",
@@ -1063,6 +1116,10 @@ export const ERROR_DOCS = {
         summary: "The transfer has progressed past the point where it can be canceled.",
         fix: "Wait for the transfer to finish.",
     },
+    transfer_push_failed: {
+        summary: "The source runtime could not push the space blobs into the transfer bucket.",
+        fix: "Retry the move; if it persists, check the source runtime and bucket configuration.",
+    },
     transfer_source_changed: {
         summary: "The space changed since the transfer was created, so it must be re-confirmed.",
         fix: "Review the space's current state and confirm the transfer again.",
@@ -1071,6 +1128,10 @@ export const ERROR_DOCS = {
         summary: "The transfer target is the same principal that already owns the space.",
         fix: "Pick a different target team or account.",
     },
+    transfer_verify_failed: {
+        summary: "The target runtime could not verify transferred blob content.",
+        fix: "Retry the move; if it persists, check the target runtime and bucket integrity.",
+    },
     unauthorized: {
         summary: "The request carried no valid credential.",
         fix: "Send a bearer access token, use an agent OAuth client, or sign in.",
@@ -1153,7 +1214,7 @@ export const ERROR_DOCS = {
     },
     version_file_too_large: {
         summary: "A file exceeds the plan's maximum file size.",
-        fix: "Reduce the file size or upgrade the plan.",
+        fix: "Reduce the file size.",
     },
     version_files_missing: {
         summary: "Declared files were never uploaded, so the version cannot finalize.",
@@ -1193,11 +1254,11 @@ export const ERROR_DOCS = {
     },
     version_quota_exceeded: {
         summary: "The space has reached its version quota.",
-        fix: "Delete old versions or upgrade the plan.",
+        fix: "Delete old versions. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     version_total_bytes_exceeded: {
         summary: "The version exceeds the maximum total size.",
-        fix: "Reduce the content size or upgrade the plan.",
+        fix: "Reduce the content size.",
     },
     webhook_delivery_budget_exceeded: {
         summary: "The webhook exhausted its delivery budget and was paused.",
@@ -1207,6 +1268,10 @@ export const ERROR_DOCS = {
         summary: "WHOIS data is unavailable for this domain right now.",
         fix: "Retry later.",
     },
+    zero_activating: {
+        summary: "Zero endpoints are activating.",
+        fix: "Wait for the dedicated runtime move to complete, then retry the request.",
+    },
     zero_artifact_abi_mismatch: {
         summary: "The Zero endpoint artifact was built for a different runner ABI.",
         fix: `Rebuild and republish the Zero project with the current ${BRAND.productName} CLI and runtime.`,
@@ -1363,6 +1428,10 @@ export const ERROR_DOCS = {
         summary: "No Zero endpoint artifact exists for this endpoint id.",
         fix: "Check the route path and rebuild the Zero endpoint index.",
     },
+    zero_requires_dedicated_plan: {
+        summary: "Zero endpoints require a plan with dedicated runtime isolation.",
+        fix: "Upgrade the team to a plan that includes Zero and dedicated runtime, then publish again.",
+    },
     zero_envelope_encode_failed: {
         summary: "The PHP bridge could not encode the Zero runner request envelope.",
         fix: "Retry with valid request data; report the issue if it persists.",
@@ -1584,18 +1653,3 @@ export function errorDocMarkdown(code) {
         "",
     ].join("\n");
 }
-/** The generated `/docs/errors` index page; the `.md` twin is this exact text. */
-export function errorDocsIndexMarkdown() {
-    return [
-        "# Error reference",
-        "",
-        `Every ${PRODUCT} API error response carries a stable \`code\` and a \`docsUrl\` that`,
-        "links to one of the pages below. Codes are never renamed or removed. Match on",
-        "`code` in clients; `message` text may improve over time.",
-        "",
-        "| Code | Meaning |",
-        "| --- | --- |",
-        ...ERROR_CODES.map((code) => `| [\`${code}\`](/docs/errors/${code}) | ${ERROR_DOCS[code].summary} |`),
-        "",
-    ].join("\n");
-}

package/dist/docs/index-build.d.ts

@@ -0,0 +1,17 @@
+import { type DocEntry } from "./catalog.js";
+/** Current on-disk index schema version; bump when the shape changes. */
+export declare const DOCS_INDEX_VERSION: 1;
+/** A catalog entry plus its precomputed search blob. */
+export interface DocIndexEntry extends DocEntry {
+    /** Lowercased haystack (slug + title + summary + kind + keywords) for offline search. */
+    readonly haystack: string;
+}
+/** The bundled, generated docs index. */
+export interface DocsIndex {
+    readonly version: typeof DOCS_INDEX_VERSION;
+    /** Provenance marker so a reader knows the artifact is generated. */
+    readonly generatedFrom: string;
+    readonly entries: readonly DocIndexEntry[];
+}
+/** Build the derived search index from a catalog (defaults to the bundled one). */
+export declare function buildDocsIndex(catalog?: readonly DocEntry[]): DocsIndex;

package/dist/docs/index-build.js

@@ -0,0 +1,24 @@
+// Pure transform from the curated docs catalog (catalog.ts) to a search index.
+// Both the CLI's generator script and its drift-guard test call buildDocsIndex,
+// and the control-plane builds the same index in memory for GET /v1/docs, so the
+// served index, the bundled artifact, and the source can never silently diverge.
+import { DOCS_CATALOG } from "./catalog.js";
+/** Current on-disk index schema version; bump when the shape changes. */
+export const DOCS_INDEX_VERSION = 1;
+/** Build the derived search index from a catalog (defaults to the bundled one). */
+export function buildDocsIndex(catalog = DOCS_CATALOG) {
+    const entries = catalog.map((entry) => ({
+        ...entry,
+        keywords: [...entry.keywords],
+        haystack: [entry.slug, entry.title, entry.summary, entry.kind, ...entry.keywords]
+            .join(" ")
+            .toLowerCase(),
+    }));
+    return {
+        version: DOCS_INDEX_VERSION,
+        // Provenance points at the CLI's re-export path, which the committed
+        // docs-index.generated.json artifact (and its drift-guard test) pin.
+        generatedFrom: "src/docs-catalog.ts",
+        entries,
+    };
+}

package/dist/docs/search.d.ts

@@ -0,0 +1,54 @@
+import { type CliDisclosureTier } from "../vocabulary.js";
+import type { DocIndexEntry, DocsIndex } from "./index-build.js";
+/** The public, machine-readable shape of a single matched doc. */
+export interface DocResult {
+    readonly slug: string;
+    readonly title: string;
+    readonly kind: DocIndexEntry["kind"];
+    readonly tier: CliDisclosureTier;
+    readonly summary: string;
+    readonly url: string;
+}
+/** A topic result additionally carries the printable body. */
+export interface DocTopic extends DocResult {
+    readonly body: string;
+}
+/** The exact `data` payload `sf docs` emits (drives both human + `--json` output). */
+export interface DocsCommandResult {
+    /** The trimmed query, or null when listing. */
+    readonly query: string | null;
+    /** The tier the listing/search ran at. */
+    readonly tier: CliDisclosureTier;
+    /** Present when the query resolved to an exact topic. */
+    readonly topic: DocTopic | null;
+    /** Matched docs (or the full tier listing when no query). */
+    readonly results: readonly DocResult[];
+}
+/** Entries visible at `viewTier`, in catalog order. */
+export declare function visibleEntries(index: DocsIndex, viewTier: CliDisclosureTier): DocIndexEntry[];
+/** Exact topic lookup by slug (case-insensitive). Ignores tier — explicit intent wins. */
+export declare function findTopic(index: DocsIndex, slug: string): DocIndexEntry | undefined;
+/**
+ * Ranked query results are capped so a broad term (e.g. one that hits a chunk
+ * of the ~390 generated error-reference entries) can never return the whole
+ * catalog in one response. Listing a tier with no query is unaffected — that's
+ * an intentional "show me everything at this tier" request, not a search.
+ */
+export declare const SEARCH_DOCS_RESULT_LIMIT = 25;
+/**
+ * Rank docs matching `query` within the tier. Empty query returns the full tier
+ * listing (catalog order), uncapped. A non-empty query ranks matches and caps
+ * the result count at {@link SEARCH_DOCS_RESULT_LIMIT}.
+ */
+export declare function searchDocs(index: DocsIndex, options: {
+    query?: string;
+    tier: CliDisclosureTier;
+}): DocIndexEntry[];
+/**
+ * Resolve the `sf docs [query]` request: an exact-slug query prints that topic;
+ * any other query searches; an empty query lists the tier. Pure + offline.
+ */
+export declare function resolveDocsCommand(index: DocsIndex, options: {
+    query?: string;
+    tier: CliDisclosureTier;
+}): DocsCommandResult;

package/dist/docs/search.js

@@ -0,0 +1,96 @@
+// Pure, offline search + tier filtering over a docs index. Shared by the CLI's
+// `sf docs` (offline, against the bundled JSON) and the control-plane's
+// GET /v1/docs (in memory, against the catalog-derived index) so both rank and
+// gate identically. Tier-aware — ESSENTIAL by default, widening to FULL
+// (`--full`) and REFERENCE (`--all`).
+import { tierVisibleAt } from "../vocabulary.js";
+function toResult(entry) {
+    return {
+        slug: entry.slug,
+        title: entry.title,
+        kind: entry.kind,
+        tier: entry.tier,
+        summary: entry.summary,
+        url: entry.url,
+    };
+}
+function toTopic(entry) {
+    return { ...toResult(entry), body: entry.body };
+}
+/** Entries visible at `viewTier`, in catalog order. */
+export function visibleEntries(index, viewTier) {
+    return index.entries.filter((entry) => tierVisibleAt(viewTier, entry.tier));
+}
+/** Exact topic lookup by slug (case-insensitive). Ignores tier — explicit intent wins. */
+export function findTopic(index, slug) {
+    const needle = slug.trim().toLowerCase();
+    if (!needle)
+        return undefined;
+    return index.entries.find((entry) => entry.slug.toLowerCase() === needle);
+}
+function scoreEntry(entry, tokens) {
+    const slug = entry.slug.toLowerCase();
+    const title = entry.title.toLowerCase();
+    const keywords = entry.keywords.map((keyword) => keyword.toLowerCase());
+    let total = 0;
+    for (const token of tokens) {
+        let tokenScore = 0;
+        if (slug === token)
+            tokenScore = Math.max(tokenScore, 5);
+        else if (slug.includes(token))
+            tokenScore = Math.max(tokenScore, 3);
+        if (title.includes(token))
+            tokenScore = Math.max(tokenScore, 3);
+        if (keywords.some((keyword) => keyword.includes(token)))
+            tokenScore = Math.max(tokenScore, 2);
+        if (tokenScore === 0 && entry.haystack.includes(token))
+            tokenScore = 1;
+        // AND semantics: every query token must match somewhere.
+        if (tokenScore === 0)
+            return 0;
+        total += tokenScore;
+    }
+    return total;
+}
+/**
+ * Ranked query results are capped so a broad term (e.g. one that hits a chunk
+ * of the ~390 generated error-reference entries) can never return the whole
+ * catalog in one response. Listing a tier with no query is unaffected — that's
+ * an intentional "show me everything at this tier" request, not a search.
+ */
+export const SEARCH_DOCS_RESULT_LIMIT = 25;
+/**
+ * Rank docs matching `query` within the tier. Empty query returns the full tier
+ * listing (catalog order), uncapped. A non-empty query ranks matches and caps
+ * the result count at {@link SEARCH_DOCS_RESULT_LIMIT}.
+ */
+export function searchDocs(index, options) {
+    const pool = visibleEntries(index, options.tier);
+    const tokens = (options.query ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return pool;
+    return pool
+        .map((entry) => ({ entry, score: scoreEntry(entry, tokens) }))
+        .filter((scored) => scored.score > 0)
+        .toSorted((a, b) => b.score - a.score || a.entry.slug.localeCompare(b.entry.slug))
+        .slice(0, SEARCH_DOCS_RESULT_LIMIT)
+        .map((scored) => scored.entry);
+}
+/**
+ * Resolve the `sf docs [query]` request: an exact-slug query prints that topic;
+ * any other query searches; an empty query lists the tier. Pure + offline.
+ */
+export function resolveDocsCommand(index, options) {
+    const trimmed = (options.query ?? "").trim();
+    const exact = trimmed ? findTopic(index, trimmed) : undefined;
+    if (exact) {
+        return {
+            query: trimmed || null,
+            tier: options.tier,
+            topic: toTopic(exact),
+            results: [toResult(exact)],
+        };
+    }
+    const results = searchDocs(index, { query: trimmed, tier: options.tier }).map(toResult);
+    return { query: trimmed || null, tier: options.tier, topic: null, results };
+}

package/dist/docs/skill-distribution.d.ts

@@ -3,10 +3,12 @@ export declare const spacefastSkillRepoOwner = "spacefast";
 export declare const spacefastSkillRepoName = "plugins";
 export declare const spacefastSkillRepoRef = "spacefast/plugins";
 export declare const spacefastSkillUrl: string;
-export declare const spacefastSkillInstallCommand: string;
+export declare const spacefastSkillFetchCommand: string;
+export declare const spacefastSkillInstallCommand = "npx -y skills add spacefast/plugins --skill spacefast -g -y";
 export declare const spacefastInstallCurlCommand: string;
 export declare const spacefastInstallPowerShellCommand: string;
 export declare const spacefastClaudePluginAddCommand = "claude plugin marketplace add spacefast/plugins";
 export declare const spacefastClaudePluginInstallCommand = "claude plugin install spacefast@spacefast";
-export declare const spacefastCodexSkillInstallCommand = "npx skills add spacefast/plugins --skill spacefast -g";
-export declare const spacefastAgentSetupPrompt: string;
+export declare const spacefastCodexPluginAddCommand = "codex plugin marketplace add spacefast/plugins";
+export declare const spacefastCodexPluginInstallCommand = "codex plugin add spacefast@spacefast";
+export declare const spacefastCodexSkillInstallCommand = "npx -y skills add spacefast/plugins --skill spacefast -g -a codex -y";

package/dist/docs/skill-distribution.js

@@ -4,15 +4,15 @@ export const spacefastSkillRepoOwner = "spacefast";
 export const spacefastSkillRepoName = "plugins";
 export const spacefastSkillRepoRef = `${spacefastSkillRepoOwner}/${spacefastSkillRepoName}`;
 export const spacefastSkillUrl = `${BRAND.apiOrigin}/skill`;
-export const spacefastSkillInstallCommand = `curl -fsSL ${spacefastSkillUrl}`;
+export const spacefastSkillFetchCommand = `curl -fsSL ${spacefastSkillUrl}`;
+export const spacefastSkillInstallCommand = `npx -y skills add ${spacefastSkillRepoRef} --skill ${spacefastSkillName} -g -y`;
 export const spacefastInstallCurlCommand = `curl -fsSL ${BRAND.websiteOrigin}/install.sh | bash`;
 export const spacefastInstallPowerShellCommand = `irm ${BRAND.websiteOrigin}/install.ps1 | iex`;
 export const spacefastClaudePluginAddCommand = `claude plugin marketplace add ${spacefastSkillRepoRef}`;
 export const spacefastClaudePluginInstallCommand = `claude plugin install ${spacefastSkillName}@${spacefastSkillName}`;
-export const spacefastCodexSkillInstallCommand = `npx skills add ${spacefastSkillRepoRef} --skill ${spacefastSkillName} -g`;
-export const spacefastAgentSetupPrompt = `I'd like you to set up ${BRAND.websiteOrigin}, the static host for AI agents.
-
-Install the ${BRAND.productName} CLI with: ${spacefastInstallCurlCommand}
-On Windows PowerShell, use: ${spacefastInstallPowerShellCommand}
-
-If your environment supports manual skill import, fetch the official ${BRAND.productName} skill from: ${spacefastSkillUrl}`;
+// Codex mirrors the Claude plugin commands (same marketplace repo, same
+// plugin name); the release workflow validates both installs against the
+// assembled dist/plugins tree.
+export const spacefastCodexPluginAddCommand = `codex plugin marketplace add ${spacefastSkillRepoRef}`;
+export const spacefastCodexPluginInstallCommand = `codex plugin add ${spacefastSkillName}@${spacefastSkillName}`;
+export const spacefastCodexSkillInstallCommand = `npx -y skills add ${spacefastSkillRepoRef} --skill ${spacefastSkillName} -g -a codex -y`;

package/dist/utils/access-match.d.ts

@@ -0,0 +1,39 @@
+export declare function filterGrantsByNamespace(grants: string[], namespaces: string[]): string[];
+export declare function grantGlobMatches(pattern: string, grant: string): boolean;
+export declare function grantsIntersect(grants: string[], requiredGrants: string[]): boolean;
+export declare function grantsSatisfyRule(input: {
+    grants: string[];
+    requiredGrants: string[];
+    grantNamespaces: string[];
+}): boolean;
+export declare function canonicalizeHost(host: string): string;
+export declare function hostGlobMatches(pattern: string, host: string): boolean;
+export declare function hostTemplateMatches(template: string, host: string): boolean;
+export declare function pathGlobMatches(pattern: string, path: string): boolean;
+export declare function agentMatches(needle: string, agent: string): boolean;
+export declare function ipInCidr(ip: string, cidr: string): boolean;
+export declare function ipInAnyCidr(ip: string, cidrs: string[]): boolean;
+export type RuleMatchContext = {
+    host: string;
+    path: string;
+    channel?: string | undefined;
+    ip?: string | undefined;
+    agent?: string | undefined;
+    country?: string | undefined;
+    headers?: Record<string, string> | undefined;
+};
+export type RuleMatchInput = {
+    host?: string | undefined;
+    hostPattern?: string | undefined;
+    hostTemplate?: string | undefined;
+    pathPattern?: string | undefined;
+    channel?: string | undefined;
+    ipCidrs?: string[] | undefined;
+    agent?: string | undefined;
+    country?: string | undefined;
+    header?: {
+        name: string;
+        value: string;
+    } | undefined;
+};
+export declare function ruleMatchApplies(match: RuleMatchInput, context: RuleMatchContext): boolean;