@spacefast/common 0.0.23 → 0.0.24

package/dist/docs/error-docs.js

@@ -49,26 +49,18 @@ export const ERROR_DOCS = {
         summary: "This anonymous space expired before it was claimed.",
         fix: "Publish a fresh space and share its claim link right away this time. If you meant to update a live space, check .spacefast/ (or your saved receipt) for its spaceId. Publish to that space with its credential instead of creating a new space.",
     },
-    anonymous_pool_unavailable: {
-        summary: "No pooled capacity is available for anonymous publishes right now.",
-        fix: "Retry shortly. Capacity replenishes automatically.",
-    },
     anonymous_publish_rate_limited: {
         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.",
+        summary: "This client already holds the maximum number of unclaimed Spaces.",
+        fix: "Sign in and publish into your account, or claim or delete one of the unclaimed Spaces you already have.",
     },
     api_key_scope_underivable: {
         summary: "A concrete access policy cannot be derived from the requested scope and permissions.",
         fix: "Point scope at a resource you can already reach (an existing space owned by a team). Request only permissions your credential already has.",
     },
-    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.",
-    },
     archive_too_large: {
         summary: "The uploaded archive exceeds the maximum allowed size.",
         fix: "Reduce the archive size or upload files individually through a version upload session.",
@@ -81,26 +73,6 @@ export const ERROR_DOCS = {
         summary: "The device login is not approved yet.",
         fix: "Keep polling at the advised interval until the user approves the request.",
     },
-    billing_receipt_invalid: {
-        summary: "The store receipt or notification cannot be verified with the payment provider.",
-        fix: "Re-check the transaction id or purchase token and retry. Contact support if it persists.",
-    },
-    billing_receipt_not_bound_to_team: {
-        summary: "The store purchase was made under a different account token than this team's.",
-        fix: "Verify the purchase from the team that initiated it, or contact support to rebind it.",
-    },
-    billing_store_not_configured: {
-        summary: "App Store or Google Play billing is not configured on this deployment.",
-        fix: "Use another billing method, or configure the store credentials on the server.",
-    },
-    billing_subscription_conflict: {
-        summary: "The team already has an active subscription with another payment provider.",
-        fix: "Cancel the existing subscription before subscribing through a different provider.",
-    },
-    billing_unknown_product: {
-        summary: "The purchased store product does not map to any plan sold by this deployment.",
-        fix: "Check the product id against the store catalog returned by the billing endpoints.",
-    },
     build_command_missing: {
         summary: "A build or install command cannot be found during the build run.",
         fix: "Check the command spelling and ensure its tool is declared in package.json or available in the build image.",
@@ -137,6 +109,14 @@ export const ERROR_DOCS = {
         summary: "The build exceeded its time limit before producing a version.",
         fix: "Speed up the build or raise the build timeout in the build settings, then start a new build.",
     },
+    blob_gate_record_missing: {
+        summary: "The file behind this download link no longer exists.",
+        fix: "Ask the owner for a fresh link; the underlying object was deleted.",
+    },
+    blob_gate_token_invalid: {
+        summary: "The download token is invalid or expired.",
+        fix: "Request a fresh download link and use it within its lifetime.",
+    },
     cache_purge_domain_required: {
         summary: "A purge request must name the domain to purge.",
         fix: "Pass the domain to purge in the request.",
@@ -173,10 +153,6 @@ export const ERROR_DOCS = {
         summary: "This CLI version is too old to talk to the API safely.",
         fix: "Upgrade the CLI to the latest release and retry.",
     },
-    comment_screenshot_rate_limited: {
-        summary: "Too many comment screenshot uploads were attempted.",
-        fix: "Wait for the one-minute window to reset, then retry the screenshot upload.",
-    },
     config_file_too_large: {
         summary: "The sf.jsonc configuration file exceeds the maximum size.",
         fix: "Keep the configuration file under the documented size limit (256 KB).",
@@ -210,11 +186,11 @@ export const ERROR_DOCS = {
         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 API key.",
-        fix: "If the space is claimed, ask its owner for an API key (dashboard: Account → API keys). 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.",
+        summary: "This space key can no longer be exchanged for an API key.",
+        fix: "If the space is claimed, ask its owner for an API key (dashboard: Account → API keys). If it is still unclaimed, keep using the space key 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 API key.",
+        summary: "This space key was already exchanged for a durable API key.",
         fix: "Authenticate with the exchanged API key (check .spacefast/state.json or wherever it was saved). If it was lost, ask the space owner to create a new API key.",
     },
     credential_expired: {
@@ -241,10 +217,6 @@ 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.",
     },
-    custom_certificates_require_dedicated_site: {
-        summary: "Custom certificates are unavailable while this space uses shared placement.",
-        fix: "Move the space to dedicated placement before managing custom certificates.",
-    },
     data_location_immutable: {
         summary: "This request tried to change data location through an immutable path.",
         fix: "Data location is fixed when the space is created and cannot be changed afterwards. Create a new space in the region you want.",
@@ -473,14 +445,6 @@ export const ERROR_DOCS = {
         summary: "The token is expired.",
         fix: "Request a new token and retry.",
     },
-    export_archive_not_ready: {
-        summary: "The export archive is still being prepared.",
-        fix: "Poll the export until its status is ready, then download the archive.",
-    },
-    export_version_not_found: {
-        summary: "The version requested for export was not found.",
-        fix: "List the space's versions and export an existing version id.",
-    },
     feature_unavailable: {
         summary: "This feature is not available on this deployment or plan.",
         fix: "Check the feature's availability and try again when it is enabled for your team.",
@@ -497,10 +461,6 @@ export const ERROR_DOCS = {
         summary: "Proxy routes to external upstreams are not available on the Free plan.",
         fix: "Remove the proxy rules before publishing. Still stuck? POST /v1/feedback with the error code and request id.",
     },
-    google_play_webhook_identity_not_configured: {
-        summary: "Google Play Pub/Sub push authentication is not configured on this deployment.",
-        fix: "Configure the exact push audience and dedicated Pub/Sub service-account email before enabling RTDN delivery.",
-    },
     idempotency_conflict_in_progress: {
         summary: "Another request with the same Idempotency-Key is still in flight.",
         fix: "Wait for the original request to finish. Its response will be replayed.",
@@ -509,18 +469,6 @@ export const ERROR_DOCS = {
         summary: "The Idempotency-Key was reused with a different request body.",
         fix: "Use a fresh key for new requests. Keys bind to one exact request body.",
     },
-    import_archive_not_uploaded: {
-        summary: "The import has no uploaded archive yet.",
-        fix: "Upload the archive to the import's upload target, then finalize.",
-    },
-    import_not_cancelable: {
-        summary: "The import is past the point where it can be canceled.",
-        fix: "Wait for the import to finish. Completed imports can be deleted as versions.",
-    },
-    import_not_waiting_for_archive: {
-        summary: "The import is not waiting for an archive upload.",
-        fix: "Check the import status. If the archive step is complete, continue to the next step.",
-    },
     incumbent_controls_dns: {
         summary: "Another team controls this domain's DNS, so the operation is blocked.",
         fix: "Prove control by completing domain verification, or coordinate with the incumbent.",
@@ -538,8 +486,8 @@ export const ERROR_DOCS = {
         fix: "Retry the request. If it persists, contact support with the requestId.",
     },
     invalid_claim_token: {
-        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.",
+        summary: "The space key is invalid or does not match this space.",
+        fix: "Use the exact space key or claim link returned by the publish that created the space.",
     },
     invalid_continuation_token: {
         summary: "The continuation token is invalid, expired, or already finished.",
@@ -565,10 +513,6 @@ export const ERROR_DOCS = {
         summary: "A file path in the request is not a valid space path.",
         fix: "Use forward-slash relative paths without traversal segments.",
     },
-    invalid_google_play_webhook_identity: {
-        summary: "The Google Play notification did not carry a valid Pub/Sub push identity.",
-        fix: "Send the notification through the configured authenticated Pub/Sub push subscription.",
-    },
     invalid_grant: {
         summary: "The authorization grant is invalid or was already used.",
         fix: "Restart the login flow to obtain a new grant.",
@@ -769,10 +713,6 @@ export const ERROR_DOCS = {
         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.",
@@ -781,10 +721,18 @@ export const ERROR_DOCS = {
         summary: "The requested key policy grants more than your own credential allows.",
         fix: "Request a policy that is a subset of the credential creating the key.",
     },
+    ingest_admission_exceeded: {
+        summary: "Too many concurrent uploads for this space.",
+        fix: "Wait for the Retry-After window, then resume; at most 4 uploads run per space at once.",
+    },
     principal_space_mismatch: {
         summary: "The space does not belong to the principal in the request.",
         fix: "Use the space's owning team or account in the request path.",
     },
+    promote_admission_exceeded: {
+        summary: "Too many archived files are being restored for this space right now.",
+        fix: "Retry shortly; restores are limited to protect the host.",
+    },
     provider_error: {
         summary: "The hosting provider reported an error.",
         fix: "Retry. If the error persists, contact support with the requestId.",
@@ -797,6 +745,10 @@ export const ERROR_DOCS = {
         summary: "A hosting-provider job timed out while processing this operation.",
         fix: "Retry the operation. If the provider is slow right now, wait and retry again.",
     },
+    provider_privilege: {
+        summary: "The hosting provider does not grant this client permission to change the setting.",
+        fix: "Leave the provider-owned setting unchanged or contact support to request the required provider capability.",
+    },
     provider_runtime_feature_unsupported: {
         summary: "The hosting provider does not support this runtime feature.",
         fix: "Check the feature's availability for this site's runtime.",
@@ -813,6 +765,10 @@ export const ERROR_DOCS = {
         summary: "The proxy upstream hostname cannot be resolved.",
         fix: "Verify the upstream DNS name resolves publicly, then publish again.",
     },
+    publish_session_expired: {
+        summary: "This publish session expired before it was finalized.",
+        fix: "Start a new publish; declared uploads are kept for 24 hours only.",
+    },
     publish_archive_compression_ratio_exceeded: {
         summary: "The archive's compression ratio is suspiciously high and was rejected.",
         fix: "Repackage the content without highly-compressible filler data.",
@@ -889,6 +845,14 @@ export const ERROR_DOCS = {
         summary: "The named job queue does not exist.",
         fix: "Check the queue name against the operator queue list.",
     },
+    response_headers_unservable: {
+        summary: "A file needs a response header that the platform cannot deliver for large files.",
+        fix: "Reduce the file below 100 MiB or drop the custom header.",
+    },
+    response_table_too_large: {
+        summary: "A compiled response table exceeded the 1 MiB per-file limit.",
+        fix: "This version has an unusually dense path set; contact support with the requestId.",
+    },
     rate_limited: {
         summary: "Too many requests were made in a short window.",
         fix: "Wait for the window in the Retry-After header to pass, then retry.",
@@ -905,6 +869,10 @@ export const ERROR_DOCS = {
         summary: "The resource changed after you loaded it, so the stale write was rejected.",
         fix: "Use the current resource returned in error.details.current, reapply the intended fields, and send its revision as expectedRevision.",
     },
+    review_item_claimed: {
+        summary: "Another reviewer already claimed this review item.",
+        fix: "Pick a different item, or ask the current assignee (error.details.assignedToUserId) to release it.",
+    },
     routing_rules_over_plan: {
         summary: "The published _redirects and _headers exceed the plan's routing-rule allowance.",
         fix: "Reduce the rule count. Still stuck? POST /v1/feedback with the error code and request id.",
@@ -925,10 +893,6 @@ export const ERROR_DOCS = {
         summary: "`sf dev` cannot run this runtime locally yet.",
         fix: "Run your framework's own dev server (`next dev`, `vite`, …) and publish with `sf publish` when you are ready.",
     },
-    runtime_engine_zip_missing: {
-        summary: "The runtime engine artifact is missing from this deployment.",
-        fix: "Rebuild the control plane so dist/runtime-engine.zip exists.",
-    },
     runtime_hostname_unassigned: {
         summary: "The hostname is not assigned to a runtime, so the request cannot be routed.",
         fix: `Verify the binding is active and DNS points at ${BRAND.productName}.`,
@@ -965,6 +929,10 @@ export const ERROR_DOCS = {
         summary: "The runtime operation referenced by this request was not found.",
         fix: "Re-request instructions and retry with a current operation id.",
     },
+    runtime_purge_failed: {
+        summary: "Content updated but the edge cache purge did not confirm.",
+        fix: "The runtime retries automatically; recent visitors may briefly see the previous version.",
+    },
     runtime_scope_forbidden: {
         summary: "The runtime token's scope does not cover this path or action.",
         fix: "Use the token minted for this exact session, space, and step.",
@@ -1059,19 +1027,15 @@ export const ERROR_DOCS = {
     },
     space_already_claimed: {
         summary: "The space was already claimed. A claim can only succeed once.",
-        fix: "If you published this space, exchange your claim token once at POST /v1/anonymous-claim/exchange. Keep publishing to the same spaceId with that durable API key. Otherwise ask the owner for access — do not publish a duplicate space.",
-    },
-    space_capacity_warming: {
-        summary: "This space is waiting on serving capacity that is being provisioned in the background.",
-        fix: "Wait for the Retry-After window, then send the same publish again. No version was created and no files were uploaded.",
+        fix: "If you published this space, exchange your space key once at POST /v1/claim/exchange. Keep publishing to the same spaceId with that durable API key. 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.",
+        fix: "Only anonymous, unexpired spaces with a valid space key 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 API key (e.g. .spacefast/state.json), then retry the request with it as Authorization: Bearer. Do not publish a new space.",
+        summary: "The space was claimed and its owner kept agent publishing enabled; this space key now works exactly once as an exchange voucher.",
+        fix: "POST /v1/claim/exchange with this space key as bearer auth. Save the returned API key (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.",
@@ -1093,30 +1057,6 @@ export const ERROR_DOCS = {
         summary: "The space is missing its persisted default hostname identity.",
         fix: "Contact support. Retrying cannot safely recreate a permanent hostname identity.",
     },
-    space_import_archive_invalid: {
-        summary: `The import archive is not a valid ${BRAND.productName} export.`,
-        fix: "Export the source space again and upload the unmodified archive.",
-    },
-    space_import_archive_too_large: {
-        summary: "The import archive exceeds the maximum allowed size.",
-        fix: "Reduce the export size, or import versions individually.",
-    },
-    space_import_config_only_archive: {
-        summary: "The archive contains only configuration and cannot be imported as content.",
-        fix: "Include files in the export, or apply the configuration directly.",
-    },
-    space_import_runtime_schema_unsupported: {
-        summary: "The export was produced by an unsupported runtime schema version.",
-        fix: "Re-export from a current runtime, or upgrade before exporting.",
-    },
-    space_move_would_strand_zero_data: {
-        summary: "The Space runs Zero, whose database and object storage live on the site the Space is placed on. Relocating it would strand that data on the old site, so the move is refused.",
-        fix: "Nothing was moved and no data was lost. Migrating Zero data between sites is not implemented. Contact support if the space genuinely has to be relocated.",
-    },
-    space_moving: {
-        summary: "The space is moving between sites, which blocks this operation.",
-        fix: "Wait for the move to finish, then retry.",
-    },
     space_no_live_version: {
         summary: "The space has no live version, so this operation has nothing to act on.",
         fix: "Publish a version to the space, then retry.",
@@ -1174,36 +1114,36 @@ export const ERROR_DOCS = {
         fix: "Target a static-runtime space.",
     },
     storage_auth_required: {
-        summary: "This storage operation requires an authenticated Zero user.",
-        fix: "Sign in to the hosted Zero app, then retry the storage operation.",
+        summary: "This storage operation requires an authenticated visitor.",
+        fix: "Sign in to the space, then retry the storage operation.",
     },
     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_content_blocked: {
-        summary: "The object contains executable or active web content that Zero storage does not serve.",
+        summary: "The object contains executable or active web content that Spacefast storage does not serve.",
         fix: "Upload a passive file type without HTML, script, SVG, PHP, or executable bytes.",
     },
     storage_delete_forbidden: {
-        summary: "The current Zero user did not upload this object.",
+        summary: "The current visitor did not upload this object.",
         fix: "Sign in as the original uploader before deleting the object.",
     },
     storage_empty_file: {
-        summary: "The Zero storage upload is empty.",
+        summary: "The storage upload is empty.",
         fix: "Upload a file containing at least 1 byte.",
     },
     storage_file_too_large: {
-        summary: "The Zero storage object exceeds the 5 MiB file limit.",
+        summary: "The storage object exceeds the 5 MiB file limit.",
         fix: "Upload a smaller object.",
     },
     storage_key_invalid: {
-        summary: "The Zero storage key is malformed.",
-        fix: "Use the public or private object key returned by storage.upload.",
+        summary: "The storage object id is malformed.",
+        fix: "Use the 32-character object id returned by storage.upload.",
     },
     storage_object_not_found: {
-        summary: "The requested Zero storage object does not exist.",
-        fix: "Check the object key or upload the object again.",
+        summary: "The requested storage object does not exist.",
+        fix: "Check the object id or upload the object again.",
     },
     storage_quota_already_unlimited: {
         summary: "The team already has unlimited storage.",
@@ -1215,16 +1155,12 @@ export const ERROR_DOCS = {
     },
     storage_quota_exceeded: {
         summary: "The operation would exceed its storage allowance.",
-        fix: "Delete unused Zero objects or old versions, reduce the upload size, then retry.",
+        fix: "Delete unused storage objects or old versions, reduce the upload size, then retry.",
     },
     storage_unavailable: {
-        summary: "The Zero runtime cannot read or persist object storage.",
+        summary: "The runtime cannot read or persist object storage.",
         fix: "Retry on a healthy runtime. Contact support if the failure persists.",
     },
-    storage_usage_unavailable: {
-        summary: "Storage usage cannot be computed right now.",
-        fix: "Retry shortly.",
-    },
     stripe_error: {
         summary: "The billing provider reported an error.",
         fix: "Retry. If it persists, check the team's billing settings.",
@@ -1305,10 +1241,6 @@ export const ERROR_DOCS = {
         summary: "Spaces cannot be transferred across tenants.",
         fix: "Export the space and import it under the target tenant instead.",
     },
-    transfer_move_failed: {
-        summary: "The space move backing this transfer failed.",
-        fix: "Retry the transfer. If it persists, contact support with the transfer id.",
-    },
     transfer_not_cancelable: {
         summary: "The transfer is past the point where it can be canceled.",
         fix: "Wait for the transfer to finish.",
@@ -1361,10 +1293,6 @@ export const ERROR_DOCS = {
         summary: "A request field failed validation.",
         fix: "Fix the field referenced by pointer and details, then retry.",
     },
-    variable_cascade_failed: {
-        summary: "Republishing spaces after a variable change failed.",
-        fix: "Check the operation's diagnostics. Live content keeps serving the previous values.",
-    },
     verification_required: {
         summary: "Domain verification is required before this operation.",
         fix: "Add the verification DNS record, then run verify on the domain.",
@@ -1461,10 +1389,6 @@ 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_ai_unavailable: {
         summary: "The local Zero AI service is not configured.",
         fix: "Configure an AI handler in the project, then restart `sf dev` before calling the AI service.",
@@ -1701,10 +1625,6 @@ export const ERROR_DOCS = {
         summary: "The Zero endpoints payload exceeds the supported endpoint count.",
         fix: "Reduce the project to at most 128 Zero endpoints, then publish again.",
     },
-    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 cannot encode the Zero runner request envelope.",
         fix: "Retry with valid request data. Report the issue if it persists.",
@@ -1877,14 +1797,6 @@ export const ERROR_DOCS = {
         summary: "The Zero run-handler payload exceeds the supported handler count.",
         fix: "Reduce the project to at most 128 Zero run handlers, then publish again.",
     },
-    zero_shopify_unavailable: {
-        summary: "The local Zero Shopify service is not configured.",
-        fix: "Configure a Shopify handler in the project, then restart `sf dev` before calling the Shopify service.",
-    },
-    wp_cloud_anonymous_pool_required: {
-        summary: "This operation requires an anonymous pool site.",
-        fix: "Target a pool-class site.",
-    },
     wp_cloud_assignment_kind_mismatch: {
         summary: "The domain assignment's kind does not match the site.",
         fix: "Verify the assignment against the site's hosting kind.",

package/dist/test-helpers/fetch-stub.d.ts

@@ -0,0 +1,16 @@
+/** The original fetch implementation captured before a test installs a stub. */
+export declare const realFetch: typeof fetch;
+export type FetchStubHandler = (request: Request) => Response | Promise<Response>;
+export declare function stubFetch(handler: FetchStubHandler): void;
+export declare function restoreFetch(): void;
+/** Build the RFC 9457 problem response served by Spacefast APIs. */
+export declare function problemResponse(input: {
+    code: string;
+    status: number;
+    detail: string;
+    pointer?: string;
+    details?: unknown;
+    suggestions?: readonly string[];
+    next?: readonly string[];
+    requestId?: string;
+}): Response;

package/dist/test-helpers/fetch-stub.js

@@ -0,0 +1,24 @@
+import { errorDocsUrl, errorTitle, PROBLEM_CONTENT_TYPE } from "../contracts/error-codes.js";
+/** The original fetch implementation captured before a test installs a stub. */
+export const realFetch = globalThis.fetch;
+export function stubFetch(handler) {
+    globalThis.fetch = (async (input, init) => handler(input instanceof Request && init === undefined ? input : new Request(input, init)));
+}
+export function restoreFetch() {
+    globalThis.fetch = realFetch;
+}
+/** Build the RFC 9457 problem response served by Spacefast APIs. */
+export function problemResponse(input) {
+    return new Response(JSON.stringify({
+        type: errorDocsUrl(input.code),
+        title: errorTitle(input.code),
+        status: input.status,
+        detail: input.detail,
+        code: input.code,
+        ...(input.pointer === undefined ? {} : { pointer: input.pointer }),
+        ...(input.details === undefined ? {} : { details: input.details }),
+        ...(input.suggestions === undefined ? {} : { suggestions: input.suggestions }),
+        ...(input.next === undefined ? {} : { next: input.next }),
+        requestId: input.requestId ?? "req_test",
+    }), { status: input.status, headers: { "content-type": PROBLEM_CONTENT_TYPE } });
+}

package/dist/utils/build-settings.js

@@ -8,6 +8,7 @@ const PACKAGE_MANAGER_ONLY_FILES = new Set([
     "pnpm-lock.yaml",
     "yarn.lock",
     "package-lock.json",
+    "npm-shrinkwrap.json",
     "Gemfile",
     "Gemfile.lock",
 ]);
@@ -711,7 +712,7 @@ function jekyllBuildCommand(files) {
 function frameworkInstallCommand(frameworkPreset, files) {
     return frameworkPreset === "jekyll" ? jekyllInstallCommand(files) : null;
 }
-function installCommandForManager(packageManager, packageJson) {
+function installCommandForManager(packageManager, packageJson, files) {
     switch (packageManager) {
         case "bun":
             return "bun install --frozen-lockfile";
@@ -720,7 +721,11 @@ function installCommandForManager(packageManager, packageJson) {
         case "yarn":
             return "corepack enable && (yarn install --immutable || yarn install --frozen-lockfile)";
         default:
-            return packageJson ? "npm ci" : null;
+            if (!packageJson)
+                return null;
+            return files.has("package-lock.json") || files.has("npm-shrinkwrap.json")
+                ? "npm ci"
+                : "npm install";
     }
 }
 function buildCommandForDefaults(packageJson, run, frameworkPreset, files) {
@@ -740,7 +745,7 @@ function packageDefaults(input, files) {
     const run = packageManager === "npm" ? "npm run" : packageManager === "bun" ? "bun run" : packageManager;
     const frameworkPreset = detectFrameworkPreset(files, dependencies);
     const installCommands = [
-        installCommandForManager(packageManager, packageJson),
+        installCommandForManager(packageManager, packageJson, files),
         frameworkInstallCommand(frameworkPreset, files),
     ].filter((command) => Boolean(command));
     const jekyllConfig = input.jekyllYaml
@@ -768,6 +773,7 @@ export function detectBuildSettings(input) {
             files.has("pnpm-lock.yaml") ? "pnpm-lock.yaml" : null,
             files.has("yarn.lock") ? "yarn.lock" : null,
             files.has("package-lock.json") ? "package-lock.json" : null,
+            files.has("npm-shrinkwrap.json") ? "npm-shrinkwrap.json" : null,
             files.has("Gemfile") ? "Gemfile" : null,
             files.has("Gemfile.lock") ? "Gemfile.lock" : null,
             files.has("_config.yml") ? "_config.yml" : null,

package/dist/utils/canonical-json.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Recursively key-sorted JSON, so a value round-tripped through Postgres jsonb
+ * (which canonicalizes key order) digests identically to one freshly built in
+ * JS. Arrays keep their original order since order is meaningful there.
+ *
+ * Every digest that has to agree across the control plane, the CLI and the
+ * capsule compiler is built on this exact spelling — change it and stored
+ * hashes stop matching freshly computed ones.
+ */
+export declare function canonicalJson(value: unknown): string;

package/dist/utils/canonical-json.js

@@ -0,0 +1,21 @@
+/**
+ * Recursively key-sorted JSON, so a value round-tripped through Postgres jsonb
+ * (which canonicalizes key order) digests identically to one freshly built in
+ * JS. Arrays keep their original order since order is meaningful there.
+ *
+ * Every digest that has to agree across the control plane, the CLI and the
+ * capsule compiler is built on this exact spelling — change it and stored
+ * hashes stop matching freshly computed ones.
+ */
+export function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}

package/dist/utils/cast-transport.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How a client addresses Cast over Phoenix. Both Spacefast clients — the
+ * dashboard's notice subscription and the injected Collab SDK — build their
+ * socket and their topics here, and nowhere else.
+ */
+/**
+ * The Phoenix topic a Cast room's messages travel on.
+ *
+ * Phoenix routes a broadcast by the *literal* topic string. Cast broadcasts
+ * anything computed outside a channel process — Space notices, REST-published
+ * room events — to the topic `Cast.RoomTopic.for/2` builds, so a client that
+ * encodes the room key any other way joins a real and permanently silent room.
+ * Both sides therefore encode exactly once, here and in that module: the `~n`
+ * table first (it survives round-tripping a key that itself contains `~` or
+ * `%`), then `encodeURIComponent`.
+ *
+ * Proven by delivery, not by inspection: `./cast-transport.test.ts` pins the
+ * strings, and on the other side `room_channel_notice_test.exs` and
+ * `spacefast_inbox_fanout_test.exs` join those literal topics and assert a real
+ * Cast broadcast arrives on them.
+ */
+export declare function castRoomTopic(resourceKey: string, roomKey: string): string;
+/**
+ * Phoenix's own `Socket` appends `/websocket` to whatever endpoint it is given,
+ * so a configured URL that already carries the suffix would otherwise become
+ * `/websocket/websocket`.
+ */
+export declare function phoenixEndpoint(url: string): string;

package/dist/utils/cast-transport.js

@@ -0,0 +1,52 @@
+/**
+ * How a client addresses Cast over Phoenix. Both Spacefast clients — the
+ * dashboard's notice subscription and the injected Collab SDK — build their
+ * socket and their topics here, and nowhere else.
+ */
+/**
+ * `~n` escapes, the inverse of `CastWeb.ApiContext.decode_path_segment/1`.
+ * `~` goes first in intent: the map is applied in one pass, so an already
+ * escaped marker can never be escaped twice.
+ */
+const ESCAPED = new Map([
+    ["~", "~0"],
+    ["/", "~1"],
+    [":", "~2"],
+    ["\\", "~3"],
+    ["%", "~4"],
+    ["\0", "~5"],
+]);
+/**
+ * The Phoenix topic a Cast room's messages travel on.
+ *
+ * Phoenix routes a broadcast by the *literal* topic string. Cast broadcasts
+ * anything computed outside a channel process — Space notices, REST-published
+ * room events — to the topic `Cast.RoomTopic.for/2` builds, so a client that
+ * encodes the room key any other way joins a real and permanently silent room.
+ * Both sides therefore encode exactly once, here and in that module: the `~n`
+ * table first (it survives round-tripping a key that itself contains `~` or
+ * `%`), then `encodeURIComponent`.
+ *
+ * Proven by delivery, not by inspection: `./cast-transport.test.ts` pins the
+ * strings, and on the other side `room_channel_notice_test.exs` and
+ * `spacefast_inbox_fanout_test.exs` join those literal topics and assert a real
+ * Cast broadcast arrives on them.
+ */
+export function castRoomTopic(resourceKey, roomKey) {
+    let escaped = "";
+    for (const character of roomKey)
+        escaped += ESCAPED.get(character) ?? character;
+    return `room:${resourceKey}:${encodeURIComponent(escaped)}`;
+}
+/**
+ * Phoenix's own `Socket` appends `/websocket` to whatever endpoint it is given,
+ * so a configured URL that already carries the suffix would otherwise become
+ * `/websocket/websocket`.
+ */
+export function phoenixEndpoint(url) {
+    const parsed = new URL(url);
+    if (parsed.pathname.endsWith("/websocket")) {
+        parsed.pathname = parsed.pathname.slice(0, -"/websocket".length);
+    }
+    return parsed.href.replace(/\/$/, "");
+}