@spacefast/common 0.0.23 → 0.0.26

package/dist/contracts/sf-config-v1.d.ts

@@ -4,10 +4,31 @@ export declare const SF_CONFIG_V1_FILES: readonly ["sf.jsonc", "spacefast.jsonc"
 /** Published JSON Schema URL for the strict `sf.jsonc` v1 contract. */
 export declare const SF_CONFIG_V1_SCHEMA_URL: `${string}/schemas/sf.v1.json`;
 /**
- * How a redirect answers. Omitting it means 302. There is no 200: a rule that
- * serves other content under the requested URL is a `rewrites` entry.
+ * How a redirect answers. Omitting it means 302. There is no 200 and no 404:
+ * a rule that serves other content under the requested URL is a `rewrites`
+ * entry — with `notFound: true` when it should answer 404.
  */
 export type SfConfigV1RedirectStatus = 301 | 302 | 303 | 307 | 308;
+/**
+ * Query parameters a redirect or rewrite requires, as parameter name to
+ * capture name — `{ id: "id" }` is the `id=:id` token of a `_redirects` line,
+ * spelled the way the compiled rule (and the runtime matcher) carry it.
+ */
+export type SfConfigV1QueryMatch = Record<string, string>;
+/**
+ * One header operation: `{ key, value }` sets, `{ key, remove: true }` is the
+ * `!Name` line of a `_headers` block. The shape is what tells the two apart,
+ * so a remove entry carries no value.
+ */
+export type SfConfigV1HeaderEntry = {
+    key: string;
+    value: string;
+    remove?: never;
+} | {
+    key: string;
+    remove: true;
+    value?: never;
+};
 export type SfConfigV1 = {
     $schema?: typeof SF_CONFIG_V1_SCHEMA_URL;
     version: 1;
@@ -32,29 +53,36 @@ export type SfConfigV1 = {
         source: string;
         destination: string;
         status?: SfConfigV1RedirectStatus;
+        /** Answer even when the request path resolves to a committed file — the `!` of a `_redirects` rule. */
+        force?: boolean;
+        query?: SfConfigV1QueryMatch;
     }[];
     /**
      * Rewrite and proxy rules: the URL stays, the content comes from the
      * destination. A path destination rewrites, an absolute URL proxies — the
      * same 200 rules `_redirects` writes as `/from /to 200`, which is why they
-     * carry no status of their own.
+     * carry no status of their own. `notFound: true` answers 404 instead — the
+     * `/gone /404.html 404` rule, which is a rewrite in every way except the
+     * status; its destination must be a path.
      */
     rewrites?: {
         source: string;
         destination: string;
         /** Let shared caches store the proxy response. Absolute-URL destinations only. */
         cache?: "shared";
+        /** Rewrite even when the request path resolves to a committed file — the `!` of a `200!` / `404!` file rule. */
+        force?: boolean;
+        query?: SfConfigV1QueryMatch;
+        notFound?: boolean;
     }[];
     /**
-     * Response headers to set on matching requests. Headers are a list, not a
-     * map, so repeated names (Set-Cookie) survive.
+     * Response headers to set — or remove — on matching requests. Headers are a
+     * list, not a map, so repeated names (Set-Cookie) survive and operations
+     * keep their order.
      */
     headers?: {
         source: string;
-        headers: {
-            key: string;
-            value: string;
-        }[];
+        headers: SfConfigV1HeaderEntry[];
     }[];
     metadata?: {
         title?: string;
@@ -67,6 +95,15 @@ export type SfConfigV1 = {
     access?: {
         public: string[];
     };
+    /**
+     * Scheduled requests against this space's own paths. Declarations pass
+     * through verbatim — the compiled `__spacefast/crons.json` derives each
+     * entry's key from its path, and the schedule is never normalized here.
+     */
+    crons?: {
+        path: string;
+        schedule: string;
+    }[];
 };
 export type EffectiveConfigV1 = {
     version: 1;
@@ -88,6 +125,7 @@ export type EffectiveConfigV1 = {
     headers?: SfConfigV1["headers"];
     metadata?: SfConfigV1["metadata"];
     substitute?: SfConfigV1["substitute"];
+    crons?: SfConfigV1["crons"];
     grants?: Grant[];
 };
 /**
@@ -96,7 +134,7 @@ export type EffectiveConfigV1 = {
  * it is the same grammar and the same compiler.
  */
 export type SfConfigV1Issue = {
-    code: "config_alias" | "config_conflict" | "config_identity_moved" | "config_invalid" | "config_key_removed" | "config_unknown_key" | "header_basic_auth_unsupported" | "header_cache_control_platform_managed" | "header_cdn_cache_unsupported" | "header_name_invalid" | "header_name_unsupported" | "header_path_invalid" | "header_pattern_invalid" | "header_port_unsupported" | "header_value_invalid" | "redirect_cache_directive_invalid" | "redirect_cache_not_proxy" | "redirect_destination_invalid" | "redirect_destination_missing" | "redirect_host_invalid" | "redirect_loop_invalid" | "redirect_pattern_invalid" | "redirect_rewrite_destination_invalid" | "redirect_source_invalid" | "redirect_status_unsupported" | "redirect_status_use_rewrites" | "serve_index_required" | "template_syntax_retired";
+    code: "config_alias" | "config_conflict" | "config_cron_duplicate_path" | "config_cron_invalid_path" | "config_cron_invalid_schedule" | "config_cron_too_many" | "config_identity_moved" | "config_invalid" | "config_key_removed" | "config_unknown_key" | "header_basic_auth_unsupported" | "header_cache_control_platform_managed" | "header_cdn_cache_unsupported" | "header_name_invalid" | "header_name_unsupported" | "header_path_invalid" | "header_pattern_invalid" | "header_port_unsupported" | "header_value_invalid" | "redirect_cache_directive_invalid" | "redirect_cache_not_proxy" | "redirect_destination_invalid" | "redirect_destination_missing" | "redirect_host_invalid" | "redirect_loop_invalid" | "redirect_pattern_invalid" | "redirect_query_match_invalid" | "redirect_rewrite_destination_invalid" | "redirect_source_invalid" | "redirect_status_unsupported" | "redirect_status_use_rewrites" | "serve_index_required" | "template_syntax_retired";
     severity: "error" | "warning";
     path: string;
     line: number;

package/dist/contracts/space-config.d.ts

@@ -2,6 +2,13 @@ import { z } from "zod";
 export declare const SPACE_CONFIG_CANONICAL_FILE = "sf.jsonc";
 export declare const SPACE_CONFIG_ALIAS_FILES: readonly ["spacefast.jsonc", "spacefast.json", "sf.json", ".sf/sf.json", ".sf/config.jsonc", ".sf/config.json"];
 export declare const SPACE_CONFIG_ACCEPTED_FILES: readonly ["sf.jsonc", "spacefast.jsonc", "spacefast.json", "sf.json", ".sf/sf.json", ".sf/config.jsonc", ".sf/config.json"];
+/**
+ * Accepted config filenames in read precedence order, highest first. Kept in
+ * step with the finalizer's `CONFIG_ACCEPTED_FILES` (crates/stattic-runtime-core
+ * protocol.rs) — the runtime compile is the selection authority, and a local
+ * read choosing a different file than the publish serves is a split brain.
+ */
+export declare const SPACE_CONFIG_PRECEDENCE: readonly ["sf.jsonc", "spacefast.jsonc", "spacefast.json", "sf.json", ".sf/sf.json", ".sf/config.jsonc", ".sf/config.json"];
 export declare const SPACE_CONFIG_PRIVATE_FILES: readonly ["sf.jsonc", "spacefast.jsonc", "spacefast.json", "sf.json", ".sf/sf.json", ".sf/config.jsonc", ".sf/config.json"];
 export declare const SPACE_CONFIG_CAPS: {
     /** Max raw `sf.jsonc` size in bytes. */
@@ -12,6 +19,7 @@ export declare const SPACE_CONFIG_CAPS: {
     readonly templates: 100;
     readonly metaTitleChars: 300;
     readonly metaDescriptionChars: 1000;
+    /** Max OG image or favicon path/URL length; enough for signed URLs while staying request-safe. */
     readonly metaImageChars: 2000;
     /** Max bytes per `inject` snippet. */
     readonly injectSnippetBytes: number;
@@ -27,6 +35,10 @@ export declare const SPACE_CONFIG_CAPS: {
     readonly themeNameChars: 120;
     /** Max top-level `name` (space display name) length. Matches the stored column. */
     readonly nameChars: 255;
+    /** Max `crons` entries. One provider crontab slot each, so the cap is small and hard. */
+    readonly crons: 8;
+    /** Max `crons[].path` length. */
+    readonly cronPathChars: 512;
 };
 /** Published JSON Schema URL for `sf.jsonc` ($schema autocomplete). */
 export declare const SPACE_CONFIG_SCHEMA_URL: string;
@@ -53,15 +65,7 @@ export declare const spaceBuildSettingsSchema: z.ZodObject<{
     timeoutSeconds: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export type SpaceBuildSettings = z.infer<typeof spaceBuildSettingsSchema>;
-export declare const spacePlacementModeSchema: z.ZodEnum<{
-    shared: "shared";
-    dedicated: "dedicated";
-}>;
 export declare const spacePlacementConfigSchema: z.ZodObject<{
-    mode: z.ZodOptional<z.ZodEnum<{
-        shared: "shared";
-        dedicated: "dedicated";
-    }>>;
     burstable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type SpacePlacementConfig = z.infer<typeof spacePlacementConfigSchema>;
@@ -71,7 +75,6 @@ export declare const wordpressDataSourceSchema: z.ZodObject<{
     kind: z.ZodLiteral<"wordpress">;
     url: z.ZodString;
 }, z.core.$strict>;
-export type WordPressDataSource = z.infer<typeof wordpressDataSourceSchema>;
 export declare const spaceDataSourcesSchema: z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodObject<{
     kind: z.ZodLiteral<"wordpress">;
     url: z.ZodString;
@@ -88,6 +91,7 @@ export declare const spaceConfigSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         image: z.ZodOptional<z.ZodString>;
+        favicon: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     superpowers: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
@@ -140,10 +144,6 @@ export declare const spaceConfigSchema: z.ZodObject<{
         timeoutSeconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     placement: z.ZodOptional<z.ZodObject<{
-        mode: z.ZodOptional<z.ZodEnum<{
-            shared: "shared";
-            dedicated: "dedicated";
-        }>>;
         burstable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     markdownNegotiation: z.ZodOptional<z.ZodBoolean>;
@@ -169,7 +169,6 @@ export declare const spaceConfigFileAccessSchema: z.ZodUnion<readonly [z.ZodPipe
 }, "public">>, z.ZodObject<{
     public: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
 }, z.core.$strict>]>;
-export type SpaceConfigFileAccess = z.infer<typeof spaceConfigFileAccessSchema>;
 /**
  * Zero: a transactional app with its own database.
  *
@@ -196,6 +195,7 @@ export declare const spaceRuntimeFunctionsSchema: z.ZodObject<{
     kind: z.ZodLiteral<"functions">;
     entry: z.ZodOptional<z.ZodString>;
     database: z.ZodDefault<z.ZodBoolean>;
+    fetch: z.ZodOptional<z.ZodBoolean>;
     compatibilityDate: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
@@ -214,11 +214,60 @@ export declare const spaceRuntimeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"functions">;
     entry: z.ZodOptional<z.ZodString>;
     database: z.ZodDefault<z.ZodBoolean>;
+    fetch: z.ZodOptional<z.ZodBoolean>;
     compatibilityDate: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "kind">;
 export type SpaceRuntimeZeroConfig = z.infer<typeof spaceRuntimeZeroSchema>;
 export type SpaceRuntimeFunctionsConfig = z.infer<typeof spaceRuntimeFunctionsSchema>;
 export type SpaceRuntimeConfig = z.infer<typeof spaceRuntimeSchema>;
+/**
+ * Scheduled requests: the provider crontab asks this space for these paths on
+ * these schedules.
+ *
+ * File-only for the same reason `runtime` is: what runs on a schedule is a fact
+ * about the content of a version, so it rolls forward and back with the version
+ * instead of being set through the API config overlay.
+ *
+ * The Rust config compiler is the selection authority for both fields; this
+ * schema exists so an editor and an agent get the same answer before publish.
+ */
+export declare const SPACE_CRON_NAMED_SCHEDULES: readonly ["hourly", "daily", "twicedaily", "weekly"];
+/**
+ * The wp.cloud schedule grammar: a named interval, an `Nh`/`Nd`/`Nw` count, or
+ * a five-field crontab expression. No `@daily` macros and no month/day names —
+ * the provider does not accept them either.
+ */
+export declare function isSpaceCronSchedule(schedule: string): boolean;
+/**
+ * The artifact key for a cron path: lowercase, leading `/` stripped, every run
+ * of non-alphanumerics collapsed to one `-`, trimmed. Two paths that produce
+ * one key are rejected, so a key names exactly one schedule.
+ */
+export declare function spaceCronKey(path: string): string;
+/** Generated runtime file the serving engine reads, written only when a version declares a cron. */
+export declare const SPACE_CRONS_ARTIFACT_PATH = "__spacefast/crons.json";
+export declare const SPACE_CRONS_ARTIFACT_VERSION = 1;
+/** One compiled cron, as the artifact carries it. */
+export type SpaceCronEntry = {
+    /** Slug of `path`; unique within a version. */
+    key: string;
+    path: string;
+    /** Verbatim as declared — never normalized or expanded. */
+    schedule: string;
+};
+export type SpaceCronsArtifact = {
+    version: typeof SPACE_CRONS_ARTIFACT_VERSION;
+    crons: SpaceCronEntry[];
+};
+export declare const spaceCronSchema: z.ZodObject<{
+    path: z.ZodString;
+    schedule: z.ZodString;
+}, z.core.$strip>;
+export declare const spaceCronsSchema: z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    schedule: z.ZodString;
+}, z.core.$strip>>;
+export type SpaceCronConfig = z.infer<typeof spaceCronSchema>;
 export declare const spaceConfigFileSchema: z.ZodObject<{
     index: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
     fallback: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -231,6 +280,7 @@ export declare const spaceConfigFileSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         image: z.ZodOptional<z.ZodString>;
+        favicon: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     superpowers: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
@@ -283,10 +333,6 @@ export declare const spaceConfigFileSchema: z.ZodObject<{
         timeoutSeconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     placement: z.ZodOptional<z.ZodObject<{
-        mode: z.ZodOptional<z.ZodEnum<{
-            shared: "shared";
-            dedicated: "dedicated";
-        }>>;
         burstable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     markdownNegotiation: z.ZodOptional<z.ZodBoolean>;
@@ -313,8 +359,13 @@ export declare const spaceConfigFileSchema: z.ZodObject<{
         kind: z.ZodLiteral<"functions">;
         entry: z.ZodOptional<z.ZodString>;
         database: z.ZodDefault<z.ZodBoolean>;
+        fetch: z.ZodOptional<z.ZodBoolean>;
         compatibilityDate: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "kind">>;
+    crons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        schedule: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type SpaceConfigFile = z.infer<typeof spaceConfigFileSchema>;
 /**