@spacefast/common 0.0.23 → 0.0.26

package/dist/docs/skills.d.ts

@@ -23,13 +23,13 @@ export interface SpacefastSkillDefinition {
 export declare const SPACEFAST_SKILLS: readonly [{
     readonly name: "create-and-publish-site";
     readonly title: "Create and publish a polished website";
-    readonly description: "Turn a brief into a responsive static website, review the result, publish it to Spacefast, and verify the live version.";
+    readonly description: "Turn a brief into a responsive website, review the result, publish it to Spacefast, and verify the live version.";
     readonly whenToUse: "Use when the user wants an agent to design, build, improve, or launch a new website rather than only upload an existing build.";
     readonly keywords: readonly ["create", "website", "design", "build", "responsive", "launch", "publish"];
     readonly runtimes: readonly ["local", "hosted"];
     readonly tools: readonly ["publish", "execute"];
     readonly docs: readonly ["quickstart", "publishing"];
-    readonly instructions: readonly ["Clarify the audience, goal, required content, brand constraints, and desired call to action. If the visual direction is open, propose two or three distinct directions and choose one with the user.", "Inspect the existing workspace before editing. Reuse its framework, package manager, components, assets, and build conventions when they are sound.", "Build a focused, accessible static experience with a clear hierarchy, real content, responsive layouts, useful interaction states, and no placeholder copy. Keep the main path simple and put secondary detail behind progressive disclosure.", "Run the real build and inspect the result at mobile and desktop widths. Fix overflow, illegible contrast, broken links, missing assets, keyboard traps, and avoidable layout shift.", "Review the workspace diff and summarize material design or content judgments before publishing. Never include API keys, claim credentials, upload credentials, or local auth state in the artifact.", "Publish the built output with `publish`. Present Open as the reusable access link and Claim as the one-time ownership link. Treat live and immutable-version URLs as receipt metadata, not extra actions."];
+    readonly instructions: readonly ["Clarify the audience, goal, required content, brand constraints, and desired call to action. If the visual direction is open, propose two or three distinct directions and choose one with the user.", "Inspect the existing workspace before editing. Reuse its framework, package manager, components, assets, and build conventions when they are sound.", "Build a focused, accessible experience with a clear hierarchy, real content, responsive layouts, useful interaction states, and no placeholder copy. Keep the main path simple and put secondary detail behind progressive disclosure.", "Run the real build and inspect the result at mobile and desktop widths. Fix overflow, illegible contrast, broken links, missing assets, keyboard traps, and avoidable layout shift.", "Review the workspace diff and summarize material design or content judgments before publishing. Never include API keys, claim credentials, upload credentials, or local auth state in the artifact.", "Publish the built output with `publish`. Present Open as the reusable access link and Claim as the one-time ownership link. Treat live and immutable-version URLs as receipt metadata, not extra actions."];
     readonly verification: readonly ["Call `status` after publishing and confirm the intended version is live; use `diagnose` if serving is stalled or failed.", "Open the live URL and verify the primary page, navigation, assets, responsive layout, and main call to action before claiming success."];
     readonly runtimeNotes: {
         readonly local: "On-Device can work directly inside the configured local workspace root and publish a local build path.";
@@ -44,13 +44,13 @@ export declare const SPACEFAST_SKILLS: readonly [{
 }, {
     readonly name: "publish-and-verify";
     readonly title: "Publish and verify";
-    readonly description: "Publish an existing static build, confirm the new version is actually live, and return the useful URLs without leaking credentials.";
+    readonly description: "Publish an existing build, confirm the new version is actually live, and return the useful URLs without leaking credentials.";
     readonly whenToUse: "Use when the artifact already exists and the user wants it published or updated.";
     readonly keywords: readonly ["publish", "deploy", "live", "verify", "version", "claim"];
     readonly runtimes: readonly ["local", "hosted"];
     readonly tools: readonly ["publish", "status", "diagnose"];
     readonly docs: readonly ["publishing", "workflow/publish-receipt", "workflow/secret-handling"];
-    readonly instructions: readonly ["Identify the actual publish root or build output. Run the real build first when the source tree is not itself the static artifact.", "Publish with `publish`. For an anonymous On-Device publish, keep the claim credential in local custody and return only the claim URL and expiry; never expose or ask the user to paste the raw token.", "Report the bare Live URL, private Access URL when present, immutable Version URL when present, anonymous Claim URL and expiry when present, plus actionable diagnostics."];
+    readonly instructions: readonly ["Identify the actual publish root or build output. Run the real build first when the source tree is not itself the artifact to publish.", "Publish with `publish`. For an anonymous On-Device publish, keep the claim credential in local custody and return only the claim URL and expiry; never expose or ask the user to paste the raw token.", "Report the bare Live URL, private Access URL when present, immutable Version URL when present, anonymous Claim URL and expiry when present, plus actionable diagnostics."];
     readonly verification: readonly ["Call `status` and confirm the intended version is live. Use `diagnose` for a failed or stalled publish.", "Open the live URL and verify representative content and assets rather than treating a successful upload or health check as serving proof."];
     readonly runtimeNotes: {
         readonly local: "Publish a bounded local path; locally custodied claim credentials are reused automatically.";
@@ -196,13 +196,13 @@ export declare const SPACEFAST_SKILLS: readonly [{
 export declare const SPACEFAST_PROMPT_SKILLS: ({
     readonly name: "create-and-publish-site";
     readonly title: "Create and publish a polished website";
-    readonly description: "Turn a brief into a responsive static website, review the result, publish it to Spacefast, and verify the live version.";
+    readonly description: "Turn a brief into a responsive website, review the result, publish it to Spacefast, and verify the live version.";
     readonly whenToUse: "Use when the user wants an agent to design, build, improve, or launch a new website rather than only upload an existing build.";
     readonly keywords: readonly ["create", "website", "design", "build", "responsive", "launch", "publish"];
     readonly runtimes: readonly ["local", "hosted"];
     readonly tools: readonly ["publish", "execute"];
     readonly docs: readonly ["quickstart", "publishing"];
-    readonly instructions: readonly ["Clarify the audience, goal, required content, brand constraints, and desired call to action. If the visual direction is open, propose two or three distinct directions and choose one with the user.", "Inspect the existing workspace before editing. Reuse its framework, package manager, components, assets, and build conventions when they are sound.", "Build a focused, accessible static experience with a clear hierarchy, real content, responsive layouts, useful interaction states, and no placeholder copy. Keep the main path simple and put secondary detail behind progressive disclosure.", "Run the real build and inspect the result at mobile and desktop widths. Fix overflow, illegible contrast, broken links, missing assets, keyboard traps, and avoidable layout shift.", "Review the workspace diff and summarize material design or content judgments before publishing. Never include API keys, claim credentials, upload credentials, or local auth state in the artifact.", "Publish the built output with `publish`. Present Open as the reusable access link and Claim as the one-time ownership link. Treat live and immutable-version URLs as receipt metadata, not extra actions."];
+    readonly instructions: readonly ["Clarify the audience, goal, required content, brand constraints, and desired call to action. If the visual direction is open, propose two or three distinct directions and choose one with the user.", "Inspect the existing workspace before editing. Reuse its framework, package manager, components, assets, and build conventions when they are sound.", "Build a focused, accessible experience with a clear hierarchy, real content, responsive layouts, useful interaction states, and no placeholder copy. Keep the main path simple and put secondary detail behind progressive disclosure.", "Run the real build and inspect the result at mobile and desktop widths. Fix overflow, illegible contrast, broken links, missing assets, keyboard traps, and avoidable layout shift.", "Review the workspace diff and summarize material design or content judgments before publishing. Never include API keys, claim credentials, upload credentials, or local auth state in the artifact.", "Publish the built output with `publish`. Present Open as the reusable access link and Claim as the one-time ownership link. Treat live and immutable-version URLs as receipt metadata, not extra actions."];
     readonly verification: readonly ["Call `status` after publishing and confirm the intended version is live; use `diagnose` if serving is stalled or failed.", "Open the live URL and verify the primary page, navigation, assets, responsive layout, and main call to action before claiming success."];
     readonly runtimeNotes: {
         readonly local: "On-Device can work directly inside the configured local workspace root and publish a local build path.";
@@ -217,13 +217,13 @@ export declare const SPACEFAST_PROMPT_SKILLS: ({
 } | {
     readonly name: "publish-and-verify";
     readonly title: "Publish and verify";
-    readonly description: "Publish an existing static build, confirm the new version is actually live, and return the useful URLs without leaking credentials.";
+    readonly description: "Publish an existing build, confirm the new version is actually live, and return the useful URLs without leaking credentials.";
     readonly whenToUse: "Use when the artifact already exists and the user wants it published or updated.";
     readonly keywords: readonly ["publish", "deploy", "live", "verify", "version", "claim"];
     readonly runtimes: readonly ["local", "hosted"];
     readonly tools: readonly ["publish", "status", "diagnose"];
     readonly docs: readonly ["publishing", "workflow/publish-receipt", "workflow/secret-handling"];
-    readonly instructions: readonly ["Identify the actual publish root or build output. Run the real build first when the source tree is not itself the static artifact.", "Publish with `publish`. For an anonymous On-Device publish, keep the claim credential in local custody and return only the claim URL and expiry; never expose or ask the user to paste the raw token.", "Report the bare Live URL, private Access URL when present, immutable Version URL when present, anonymous Claim URL and expiry when present, plus actionable diagnostics."];
+    readonly instructions: readonly ["Identify the actual publish root or build output. Run the real build first when the source tree is not itself the artifact to publish.", "Publish with `publish`. For an anonymous On-Device publish, keep the claim credential in local custody and return only the claim URL and expiry; never expose or ask the user to paste the raw token.", "Report the bare Live URL, private Access URL when present, immutable Version URL when present, anonymous Claim URL and expiry when present, plus actionable diagnostics."];
     readonly verification: readonly ["Call `status` and confirm the intended version is live. Use `diagnose` for a failed or stalled publish.", "Open the live URL and verify representative content and assets rather than treating a successful upload or health check as serving proof."];
     readonly runtimeNotes: {
         readonly local: "Publish a bounded local path; locally custodied claim credentials are reused automatically.";
@@ -369,13 +369,13 @@ export declare const SPACEFAST_PROMPT_SKILLS: ({
 export declare const SPACEFAST_RECIPE_SKILLS: (({
     readonly name: "create-and-publish-site";
     readonly title: "Create and publish a polished website";
-    readonly description: "Turn a brief into a responsive static website, review the result, publish it to Spacefast, and verify the live version.";
+    readonly description: "Turn a brief into a responsive website, review the result, publish it to Spacefast, and verify the live version.";
     readonly whenToUse: "Use when the user wants an agent to design, build, improve, or launch a new website rather than only upload an existing build.";
     readonly keywords: readonly ["create", "website", "design", "build", "responsive", "launch", "publish"];
     readonly runtimes: readonly ["local", "hosted"];
     readonly tools: readonly ["publish", "execute"];
     readonly docs: readonly ["quickstart", "publishing"];
-    readonly instructions: readonly ["Clarify the audience, goal, required content, brand constraints, and desired call to action. If the visual direction is open, propose two or three distinct directions and choose one with the user.", "Inspect the existing workspace before editing. Reuse its framework, package manager, components, assets, and build conventions when they are sound.", "Build a focused, accessible static experience with a clear hierarchy, real content, responsive layouts, useful interaction states, and no placeholder copy. Keep the main path simple and put secondary detail behind progressive disclosure.", "Run the real build and inspect the result at mobile and desktop widths. Fix overflow, illegible contrast, broken links, missing assets, keyboard traps, and avoidable layout shift.", "Review the workspace diff and summarize material design or content judgments before publishing. Never include API keys, claim credentials, upload credentials, or local auth state in the artifact.", "Publish the built output with `publish`. Present Open as the reusable access link and Claim as the one-time ownership link. Treat live and immutable-version URLs as receipt metadata, not extra actions."];
+    readonly instructions: readonly ["Clarify the audience, goal, required content, brand constraints, and desired call to action. If the visual direction is open, propose two or three distinct directions and choose one with the user.", "Inspect the existing workspace before editing. Reuse its framework, package manager, components, assets, and build conventions when they are sound.", "Build a focused, accessible experience with a clear hierarchy, real content, responsive layouts, useful interaction states, and no placeholder copy. Keep the main path simple and put secondary detail behind progressive disclosure.", "Run the real build and inspect the result at mobile and desktop widths. Fix overflow, illegible contrast, broken links, missing assets, keyboard traps, and avoidable layout shift.", "Review the workspace diff and summarize material design or content judgments before publishing. Never include API keys, claim credentials, upload credentials, or local auth state in the artifact.", "Publish the built output with `publish`. Present Open as the reusable access link and Claim as the one-time ownership link. Treat live and immutable-version URLs as receipt metadata, not extra actions."];
     readonly verification: readonly ["Call `status` after publishing and confirm the intended version is live; use `diagnose` if serving is stalled or failed.", "Open the live URL and verify the primary page, navigation, assets, responsive layout, and main call to action before claiming success."];
     readonly runtimeNotes: {
         readonly local: "On-Device can work directly inside the configured local workspace root and publish a local build path.";
@@ -390,13 +390,13 @@ export declare const SPACEFAST_RECIPE_SKILLS: (({
 } | {
     readonly name: "publish-and-verify";
     readonly title: "Publish and verify";
-    readonly description: "Publish an existing static build, confirm the new version is actually live, and return the useful URLs without leaking credentials.";
+    readonly description: "Publish an existing build, confirm the new version is actually live, and return the useful URLs without leaking credentials.";
     readonly whenToUse: "Use when the artifact already exists and the user wants it published or updated.";
     readonly keywords: readonly ["publish", "deploy", "live", "verify", "version", "claim"];
     readonly runtimes: readonly ["local", "hosted"];
     readonly tools: readonly ["publish", "status", "diagnose"];
     readonly docs: readonly ["publishing", "workflow/publish-receipt", "workflow/secret-handling"];
-    readonly instructions: readonly ["Identify the actual publish root or build output. Run the real build first when the source tree is not itself the static artifact.", "Publish with `publish`. For an anonymous On-Device publish, keep the claim credential in local custody and return only the claim URL and expiry; never expose or ask the user to paste the raw token.", "Report the bare Live URL, private Access URL when present, immutable Version URL when present, anonymous Claim URL and expiry when present, plus actionable diagnostics."];
+    readonly instructions: readonly ["Identify the actual publish root or build output. Run the real build first when the source tree is not itself the artifact to publish.", "Publish with `publish`. For an anonymous On-Device publish, keep the claim credential in local custody and return only the claim URL and expiry; never expose or ask the user to paste the raw token.", "Report the bare Live URL, private Access URL when present, immutable Version URL when present, anonymous Claim URL and expiry when present, plus actionable diagnostics."];
     readonly verification: readonly ["Call `status` and confirm the intended version is live. Use `diagnose` for a failed or stalled publish.", "Open the live URL and verify representative content and assets rather than treating a successful upload or health check as serving proof."];
     readonly runtimeNotes: {
         readonly local: "Publish a bounded local path; locally custodied claim credentials are reused automatically.";

package/dist/docs/skills.js

@@ -5,7 +5,7 @@ export const SPACEFAST_SKILLS = [
     {
         name: "create-and-publish-site",
         title: "Create and publish a polished website",
-        description: "Turn a brief into a responsive static website, review the result, publish it to Spacefast, and verify the live version.",
+        description: "Turn a brief into a responsive website, review the result, publish it to Spacefast, and verify the live version.",
         whenToUse: "Use when the user wants an agent to design, build, improve, or launch a new website rather than only upload an existing build.",
         keywords: ["create", "website", "design", "build", "responsive", "launch", "publish"],
         runtimes: BOTH_RUNTIMES,
@@ -14,7 +14,7 @@ export const SPACEFAST_SKILLS = [
         instructions: [
             "Clarify the audience, goal, required content, brand constraints, and desired call to action. If the visual direction is open, propose two or three distinct directions and choose one with the user.",
             "Inspect the existing workspace before editing. Reuse its framework, package manager, components, assets, and build conventions when they are sound.",
-            "Build a focused, accessible static experience with a clear hierarchy, real content, responsive layouts, useful interaction states, and no placeholder copy. Keep the main path simple and put secondary detail behind progressive disclosure.",
+            "Build a focused, accessible experience with a clear hierarchy, real content, responsive layouts, useful interaction states, and no placeholder copy. Keep the main path simple and put secondary detail behind progressive disclosure.",
             "Run the real build and inspect the result at mobile and desktop widths. Fix overflow, illegible contrast, broken links, missing assets, keyboard traps, and avoidable layout shift.",
             "Review the workspace diff and summarize material design or content judgments before publishing. Never include API keys, claim credentials, upload credentials, or local auth state in the artifact.",
             "Publish the built output with `publish`. Present Open as the reusable access link and Claim as the one-time ownership link. Treat live and immutable-version URLs as receipt metadata, not extra actions.",
@@ -37,14 +37,14 @@ export const SPACEFAST_SKILLS = [
     {
         name: "publish-and-verify",
         title: "Publish and verify",
-        description: "Publish an existing static build, confirm the new version is actually live, and return the useful URLs without leaking credentials.",
+        description: "Publish an existing build, confirm the new version is actually live, and return the useful URLs without leaking credentials.",
         whenToUse: "Use when the artifact already exists and the user wants it published or updated.",
         keywords: ["publish", "deploy", "live", "verify", "version", "claim"],
         runtimes: BOTH_RUNTIMES,
         tools: ["publish", "status", "diagnose"],
         docs: ["publishing", "workflow/publish-receipt", "workflow/secret-handling"],
         instructions: [
-            "Identify the actual publish root or build output. Run the real build first when the source tree is not itself the static artifact.",
+            "Identify the actual publish root or build output. Run the real build first when the source tree is not itself the artifact to publish.",
             "Publish with `publish`. For an anonymous On-Device publish, keep the claim credential in local custody and return only the claim URL and expiry; never expose or ask the user to paste the raw token.",
             "Report the bare Live URL, private Access URL when present, immutable Version URL when present, anonymous Claim URL and expiry when present, plus actionable diagnostics.",
         ],

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,25 @@
+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) {
+    // SAFETY: The wrapper accepts fetch's parameter types and always resolves to the handler's Response.
+    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.d.ts

@@ -1,3 +1,4 @@
+import { type SpaceCronConfig } from "../contracts/space-config.js";
 export type BuildSettingsInput = {
     fileNames: Iterable<string>;
     packageJson?: string | null | undefined;
@@ -24,7 +25,7 @@ export type BuildAnalyzerCandidateRankInput = {
     rootDirectory: string | null;
     fileNames: Iterable<string>;
 };
-export declare function hasWorkspaceSignal(fileNames: Iterable<string>, packageJsonText?: string | null): unknown;
+export declare function hasWorkspaceSignal(fileNames: Iterable<string>, packageJsonText?: string | null): boolean;
 export declare function rankBuildAnalyzerCandidate(input: BuildAnalyzerCandidateRankInput): {
     confidence: number;
     reasons: string[];
@@ -43,6 +44,7 @@ export type PlatformConfig = {
     redirects: Array<Record<string, unknown>>;
     rewrites: Array<Record<string, unknown>>;
     headers: Array<Record<string, unknown>>;
+    crons: Array<Record<string, unknown>>;
     unsupportedFeatures: string[];
 };
 export declare function stringField(value: Record<string, unknown> | null, key: string): string | null;
@@ -51,7 +53,9 @@ export declare function detectPlatformConfigs(input: Omit<BuildSettingsInput, "f
 export type PlatformRoutingConversion = {
     redirectLines: string[];
     headerBlocks: string[];
+    crons: SpaceCronConfig[];
     notes: string[];
 };
 export declare function convertPlatformRouting(configs: PlatformConfig[]): PlatformRoutingConversion;
+export declare const BUILD_MARKER_FILE_NAMES: Set<string>;
 export declare function detectBuildSettings(input: BuildSettingsInput): DetectedBuildSettings;

package/dist/utils/build-settings.js

@@ -1,5 +1,6 @@
 import { load as parseYaml } from "js-yaml";
 import { parse as parseToml } from "smol-toml";
+import { SPACE_CONFIG_CAPS, spaceCronKey, spaceCronSchema, } from "../contracts/space-config.js";
 export const BUILD_ANALYZER_CANDIDATE_ROOTS = ["apps", "packages", "sites", "docs"];
 const PACKAGE_MANAGER_ONLY_FILES = new Set([
     "package.json",
@@ -8,15 +9,19 @@ const PACKAGE_MANAGER_ONLY_FILES = new Set([
     "pnpm-lock.yaml",
     "yarn.lock",
     "package-lock.json",
+    "npm-shrinkwrap.json",
     "Gemfile",
     "Gemfile.lock",
 ]);
+const WORKSPACE_ROOT_FILES = new Set([
+    "pnpm-workspace.yaml",
+    "turbo.json",
+    "nx.json",
+    "lerna.json",
+]);
 export function hasWorkspaceSignal(fileNames, packageJsonText) {
     const names = new Set(fileNames);
-    if (names.has("pnpm-workspace.yaml") ||
-        names.has("turbo.json") ||
-        names.has("nx.json") ||
-        names.has("lerna.json")) {
+    if ([...WORKSPACE_ROOT_FILES].some((file) => names.has(file))) {
         return true;
     }
     if (!packageJsonText) {
@@ -24,10 +29,14 @@ export function hasWorkspaceSignal(fileNames, packageJsonText) {
     }
     try {
         const parsed = JSON.parse(packageJsonText);
-        return (Array.isArray(parsed.workspaces) ||
-            (parsed.workspaces &&
-                typeof parsed.workspaces === "object" &&
-                Array.isArray(parsed.workspaces.packages)));
+        if (Array.isArray(parsed.workspaces)) {
+            return true;
+        }
+        if (!parsed.workspaces || typeof parsed.workspaces !== "object") {
+            return false;
+        }
+        // SAFETY: The preceding non-null object check proves workspaces can carry an optional packages property.
+        return Array.isArray(parsed.workspaces.packages);
     }
     catch {
         return false;
@@ -77,6 +86,7 @@ function parseJsonObject(value) {
     }
     try {
         const parsed = JSON.parse(value);
+        // SAFETY: The conditional establishes parsed is a non-null, non-array object before returning it as a dictionary.
         return parsed && typeof parsed === "object" && !Array.isArray(parsed)
             ? parsed
             : null;
@@ -97,6 +107,7 @@ function parseTomlObject(value) {
     }
     try {
         const parsed = parseToml(value);
+        // SAFETY: The conditional establishes parsed is a non-null, non-array object before returning it as a dictionary.
         return parsed && typeof parsed === "object" && !Array.isArray(parsed)
             ? parsed
             : null;
@@ -111,6 +122,7 @@ function parseYamlObject(value) {
     }
     try {
         const parsed = parseYaml(value);
+        // SAFETY: The conditional establishes parsed is a non-null, non-array object before returning it as a dictionary.
         return parsed && typeof parsed === "object" && !Array.isArray(parsed)
             ? parsed
             : null;
@@ -129,6 +141,7 @@ export function numberField(value, key) {
 }
 function objectField(value, key) {
     const field = value?.[key];
+    // SAFETY: The conditional establishes field is a non-null, non-array object before returning it as a dictionary.
     return field && typeof field === "object" && !Array.isArray(field)
         ? field
         : null;
@@ -154,11 +167,11 @@ function vercelConfig(value) {
         redirects: arrayField(config, "redirects"),
         rewrites: arrayField(config, "rewrites"),
         headers: arrayField(config, "headers"),
+        crons: arrayField(config, "crons"),
         unsupportedFeatures: [
             ...("functions" in config ? ["Vercel functions are not converted."] : []),
             ...("middleware" in config ? ["Vercel middleware is not converted."] : []),
             ...("images" in config ? ["Vercel image optimization config is not converted."] : []),
-            ...("crons" in config ? ["Vercel cron jobs are not converted."] : []),
         ],
     };
 }
@@ -178,6 +191,9 @@ function netlifyConfig(value) {
         redirects: arrayField(config, "redirects"),
         rewrites: [],
         headers: arrayField(config, "headers"),
+        // Netlify has no scheduled-request config: its scheduled functions are
+        // declared in function code, which this importer does not read.
+        crons: [],
         unsupportedFeatures: [
             ...("functions" in config ? ["Netlify functions are not converted."] : []),
             ...("edge_functions" in config ? ["Netlify edge functions are not converted."] : []),
@@ -223,6 +239,7 @@ function cloudflarePagesConfig(input) {
         redirects: [],
         rewrites: [],
         headers: [],
+        crons: [],
         unsupportedFeatures,
     };
 }
@@ -386,6 +403,7 @@ function convertVercelHeaderRule(rule, out) {
     const entries = rule.headers;
     const headers = (Array.isArray(entries) ? entries : [])
         .map((entry) => {
+        // SAFETY: The conditional establishes entry is a non-null object before reading dictionary properties.
         const header = entry && typeof entry === "object" ? entry : null;
         const key = stringField(header, "key");
         const value = header && typeof header.value === "string" ? header.value : null;
@@ -424,8 +442,47 @@ function convertNetlifyHeaderRule(rule, out) {
     }
     out.headerBlocks.push(headerBlock(matcher, headers));
 }
+/**
+ * One `vercel.json` cron entry into an `sf.jsonc` `crons` entry.
+ *
+ * Both sides are `{ path, schedule }` over a literal path and a five-field
+ * crontab expression, so a valid Vercel cron converts verbatim — there is no
+ * translation to get wrong. What this guards is the tail: Vercel accepts paths
+ * and schedules our grammar does not, and it has no per-project cap the way we
+ * do. Every rejection names the entry, because a scheduled job that silently
+ * stops existing is the one migration failure nobody notices until the work
+ * has not run for a week.
+ */
+function convertVercelCron(rule, out) {
+    const path = stringField(rule, "path");
+    const schedule = stringField(rule, "schedule");
+    const label = `vercel.json cron ${path ?? "(missing path)"}`;
+    if (!path || !schedule) {
+        out.notes.push(`${label}: skipped — missing path or schedule.`);
+        return;
+    }
+    const parsed = spaceCronSchema.safeParse({ path, schedule });
+    if (!parsed.success) {
+        out.notes.push(`${label}: skipped — ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return;
+    }
+    if (out.crons.some((entry) => spaceCronKey(entry.path) === spaceCronKey(path))) {
+        out.notes.push(`${label}: skipped — another cron already schedules this path.`);
+        return;
+    }
+    if (out.crons.length >= SPACE_CONFIG_CAPS.crons) {
+        out.notes.push(`${label}: skipped — at most ${SPACE_CONFIG_CAPS.crons} crons are supported.`);
+        return;
+    }
+    out.crons.push(parsed.data);
+}
 export function convertPlatformRouting(configs) {
-    const out = { redirectLines: [], headerBlocks: [], notes: [] };
+    const out = {
+        redirectLines: [],
+        headerBlocks: [],
+        crons: [],
+        notes: [],
+    };
     for (const config of configs) {
         if (config.platform === "vercel") {
             for (const rule of config.redirects) {
@@ -437,6 +494,9 @@ export function convertPlatformRouting(configs) {
             for (const rule of config.headers) {
                 convertVercelHeaderRule(rule, out);
             }
+            for (const rule of config.crons) {
+                convertVercelCron(rule, out);
+            }
         }
         if (config.platform === "netlify") {
             // Netlify expresses rewrites as 200-status redirects; both arrive in
@@ -670,6 +730,19 @@ const FRAMEWORKS = [
         defaultBuildCommand: "bundle exec middleman build",
     },
 ];
+// Every file name the build analyzer keys on: package manifests, lockfiles,
+// workspace roots, and the platform and framework configs it detects a build
+// from. An archive carrying any of them is a project to build, not a website.
+export const BUILD_MARKER_FILE_NAMES = new Set([
+    ...PACKAGE_MANAGER_ONLY_FILES,
+    ...WORKSPACE_ROOT_FILES,
+    "vercel.json",
+    "netlify.toml",
+    "wrangler.toml",
+    "wrangler.json",
+    "wrangler.jsonc",
+    ...FRAMEWORKS.flatMap((framework) => framework.configFiles ?? []),
+]);
 function frameworkForPreset(frameworkPreset) {
     return FRAMEWORKS.find((framework) => framework.preset === frameworkPreset) ?? null;
 }
@@ -711,7 +784,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 +793,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 +817,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 +845,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,22 @@
+/**
+ * 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") {
+        // SAFETY: This branch establishes value is a non-null object before enumerating its entries.
+        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(/\/$/, "");
+}

package/dist/utils/claim-token.d.ts

@@ -1,9 +1 @@
-export type ClaimCredential = {
-    kind: "token";
-    claimToken: string;
-} | {
-    kind: "nonce";
-    nonce: string;
-};
-export declare function classifyClaimCredential(raw: string | null | undefined): ClaimCredential | undefined;
 export declare function normalizeClaimToken(token: string | null | undefined): string | undefined;

package/dist/utils/claim-token.js

@@ -1,18 +1,6 @@
-const LEGACY_WORD_TOKEN_SHAPE = /^[a-z]+(?:-[a-z]+){2,}$/;
-export function classifyClaimCredential(raw) {
-    const trimmed = raw?.trim();
-    if (!trimmed) {
-        return undefined;
-    }
-    if (trimmed.startsWith("sfc_")) {
-        return { kind: "token", claimToken: trimmed };
-    }
-    const normalized = normalizeClaimToken(trimmed);
-    if (normalized && LEGACY_WORD_TOKEN_SHAPE.test(normalized)) {
-        return { kind: "token", claimToken: normalized };
-    }
-    return { kind: "nonce", nonce: trimmed };
-}
+// The space key (`sfc_…`, or the legacy five-word form) is the one claim
+// credential; it authenticates as a `Bearer` header and rides claim-link
+// fragments verbatim.
 export function normalizeClaimToken(token) {
     const trimmed = token?.trim();
     if (!trimmed) {

package/dist/utils/concurrency.js

@@ -10,6 +10,7 @@ export async function mapConcurrent(items, limit, mapper) {
         if (index >= items.length) {
             return;
         }
+        // SAFETY: the bounds check above proves this index addresses an item in the input array.
         results[index] = await mapper(items[index], index);
         await worker();
     }

package/dist/utils/credential-policy.d.ts

@@ -16,7 +16,7 @@ export type PolicyAuthorizeInput = {
     resource: string | readonly string[];
     conditions?: RequestCondition;
 };
-export declare const publishActions: ("spaces:read" | "spaces:write" | "spaces:create" | "spaces:publish" | "versions:read" | "versions:promote" | "versions:download" | "builds:read" | "builds:trigger" | "builds:create")[];
+export declare const publishActions: ("spaces:read" | "spaces:write" | "spaces:publish" | "builds:trigger" | "spaces:create" | "versions:read" | "versions:promote" | "versions:download" | "builds:read" | "builds:create")[];
 export declare function compileApiKeyPreset(preset: ApiKeyPreset, input: PolicyCompileInput): ApiCredentialPolicy;
 /** Expand a named API-key preset into the finite permissions sent on the public wire contract. */
 export declare function apiKeyPresetPermissions(preset: ApiKeyPreset): StatticAction[];