@spacefast/common 0.0.12 → 0.0.17

package/dist/contracts/runtime-db.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { dataEnvelope, mutationEnvelope } from "./common.js";
+import { executionIdentifierSchema, executionSha256Schema } from "./execution.js";
+import { ZERO_RUNTIME_KIND, zeroMigrationOperationSchema, zeroTableSchema } from "./zero.js";
+/**
+ * The database surface, for whichever runtime a space is carrying.
+ *
+ * There is one database per space — the site's own MySQL — and at most one
+ * runtime with a claim on it, so these contracts are runtime-neutral by
+ * default. The two exceptions are stated explicitly: a migration plan is a
+ * capsule's declaration and no worker has one, and the console hand-off is a
+ * property of the wp.cloud site rather than of anything a version declared.
+ *
+ * The reads answer in the capsule's declaration shapes (`zeroTableSchema`,
+ * `zeroMigrationOperationSchema`) because a capsule's declared schema is the
+ * richest answer either runtime can give and a worker's is the same answer with
+ * the declaration-shaped fields empty. Those shapes stay Zero-named and stay in
+ * `./zero.js`: a declared table is the capsule's own statement about itself.
+ */
+export const runtimeDbInspectResponseSchema = z
+    .object({
+    versionId: z.string().min(1).nullable(),
+    artifactId: z.string().min(1).nullable(),
+    backend: z.literal("wpcloud-mysql").nullable(),
+    migrationMode: z.enum(["safe", "drop", "rename"]).nullable(),
+    schemaHash: executionSha256Schema.nullable(),
+    tables: z.array(zeroTableSchema).default([]),
+    migrations: z.array(zeroMigrationOperationSchema).default([]),
+})
+    .strict();
+export const runtimeDbInspectPublicResponseSchema = dataEnvelope(runtimeDbInspectResponseSchema);
+export const runtimeDbDumpQuerySchema = z
+    .object({
+    table: executionIdentifierSchema.optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(25),
+})
+    .strict();
+export const runtimeDbDumpTableSchema = z
+    .object({
+    name: executionIdentifierSchema,
+    rows: z.array(z.record(z.string(), z.unknown())).default([]),
+})
+    .strict();
+export const runtimeDbDumpResponseSchema = z
+    .object({
+    versionId: z.string().min(1).nullable(),
+    artifactId: z.string().min(1).nullable(),
+    schemaHash: executionSha256Schema.nullable(),
+    tables: z.array(runtimeDbDumpTableSchema).default([]),
+})
+    .strict();
+export const runtimeDbDumpPublicResponseSchema = dataEnvelope(runtimeDbDumpResponseSchema);
+export const runtimeDbExportOrderingSchema = z
+    .object({
+    tables: z.literal("name_asc"),
+    rows: z.literal("created_at_id_asc"),
+})
+    .strict();
+export const runtimeDbExportMetadataSchema = z
+    .object({
+    spaceId: z.string().min(1).nullable(),
+    versionId: z.string().min(1).nullable(),
+    schemaHash: executionSha256Schema,
+    consistency: z.literal("per_page"),
+    ordering: runtimeDbExportOrderingSchema,
+    tables: z.array(executionIdentifierSchema),
+})
+    .strict();
+export const runtimeDbExportMetadataPublicResponseSchema = dataEnvelope(runtimeDbExportMetadataSchema);
+export const runtimeDbExportPageQuerySchema = z
+    .object({
+    schemaHash: executionSha256Schema,
+    cursor: z.string().min(1).max(4_096).optional(),
+    limit: z.coerce.number().int().min(1).max(1_000).default(500),
+})
+    .strict();
+export const runtimeDbExportPageSchema = z
+    .object({
+    rows: z.array(z.record(z.string(), z.unknown())),
+    cursor: z.string().nullable(),
+})
+    .strict();
+export const runtimeDbExportPagePublicResponseSchema = dataEnvelope(runtimeDbExportPageSchema);
+export const runtimeDbMigrateResultSchema = z
+    .object({
+    versionId: z.string().min(1).describe("Live version whose migration plan this is."),
+    runtimeKind: z.literal(ZERO_RUNTIME_KIND),
+    schemaHash: executionSha256Schema.nullable(),
+    mode: z.enum(["safe", "drop", "rename"]).nullable(),
+    operations: z
+        .array(zeroMigrationOperationSchema)
+        .describe("The plan the live capsule declared, in the order it applies."),
+    queued: z
+        .boolean()
+        .describe("Whether runtime finalize was queued to apply the plan. `false` when the plan is empty because there is nothing to run."),
+})
+    .strict();
+export const runtimeDbMigrateResponseSchema = mutationEnvelope(runtimeDbMigrateResultSchema);
+export const runtimeDbConsoleSchema = z
+    .object({
+    provider: z.literal("wpcloud-phpmyadmin"),
+    url: z
+        .string()
+        .url()
+        .describe("Short-lived, single-use phpMyAdmin sign-in URL for the space MySQL. Treat it as a credential."),
+})
+    .strict();
+export const runtimeDbConsoleResponseSchema = dataEnvelope(runtimeDbConsoleSchema);

package/dist/contracts/runtime-storage.d.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+export declare const runtimeStorageVisibilitySchema: z.ZodEnum<{
+    public: "public";
+    private: "private";
+}>;
+export type RuntimeStorageVisibility = z.infer<typeof runtimeStorageVisibilitySchema>;
+export declare const runtimeStorageObjectIdSchema: z.ZodString;
+export declare const runtimeStorageObjectKeySchema: z.ZodString;
+export declare const runtimeStorageListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>>;
+}, z.core.$strict>;
+export declare const runtimeStorageObjectSchema: z.ZodObject<{
+    key: z.ZodString;
+    visibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    contentType: z.ZodString;
+    createdAt: z.ZodString;
+    size: z.ZodNumber;
+    uploaderId: z.ZodString;
+    sha256: z.ZodString;
+}, z.core.$strict>;
+export type RuntimeStorageObject = z.infer<typeof runtimeStorageObjectSchema>;
+export declare const runtimeStorageListResponseSchema: z.ZodObject<{
+    objects: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        visibility: z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>;
+        contentType: z.ZodString;
+        createdAt: z.ZodString;
+        size: z.ZodNumber;
+        uploaderId: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    cursor: z.ZodNullable<z.ZodString>;
+    hasMore: z.ZodBoolean;
+    usedBytes: z.ZodNumber;
+    quotaBytes: z.ZodNumber;
+}, z.core.$strict>;
+export type RuntimeStorageListResponse = z.infer<typeof runtimeStorageListResponseSchema>;
+export declare const runtimeStorageListPublicResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        objects: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            visibility: z.ZodEnum<{
+                public: "public";
+                private: "private";
+            }>;
+            contentType: z.ZodString;
+            createdAt: z.ZodString;
+            size: z.ZodNumber;
+            uploaderId: z.ZodString;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+        cursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+        usedBytes: z.ZodNumber;
+        quotaBytes: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strip>;
+export declare const runtimeStorageDeleteResponseSchema: z.ZodObject<{
+    key: z.ZodString;
+    deleted: z.ZodBoolean;
+}, z.core.$strict>;
+export type RuntimeStorageDeleteResponse = z.infer<typeof runtimeStorageDeleteResponseSchema>;
+export declare const runtimeStorageDeletePublicResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        key: z.ZodString;
+        deleted: z.ZodBoolean;
+    }, z.core.$strict>;
+    operation: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            canceled: "canceled";
+            queued: "queued";
+            running: "running";
+            succeeded: "succeeded";
+        }>;
+        resources: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>>;
+        progress: z.ZodOptional<z.ZodObject<{
+            total: z.ZodNumber;
+            completed: z.ZodNumber;
+            failed: z.ZodNumber;
+        }, z.core.$strip>>;
+        diagnostics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            severity: z.ZodEnum<{
+                info: "info";
+                error: "error";
+                warning: "warning";
+            }>;
+            message: z.ZodString;
+            path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                registrar: "registrar";
+                wpcloud: "wpcloud";
+                dns: "dns";
+                runtime: "runtime";
+            }>>>;
+            details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodString;
+        finishedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/contracts/runtime-storage.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { dataEnvelope, mutationEnvelope } from "./common.js";
+export const runtimeStorageVisibilitySchema = z.enum(["public", "private"]);
+export const runtimeStorageObjectIdSchema = z.string().regex(/^[a-f0-9]{32}$/);
+export const runtimeStorageObjectKeySchema = z.string().regex(/^(public|private)\/[a-f0-9]{32}$/);
+export const runtimeStorageListQuerySchema = z
+    .object({
+    cursor: z.string().min(1).max(2_048).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    visibility: runtimeStorageVisibilitySchema.optional(),
+})
+    .strict();
+export const runtimeStorageObjectSchema = z
+    .object({
+    key: runtimeStorageObjectKeySchema,
+    visibility: runtimeStorageVisibilitySchema,
+    contentType: z.string().min(1).max(255),
+    createdAt: z.string().datetime(),
+    size: z.number().int().nonnegative(),
+    uploaderId: z.string().min(1).max(255),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+})
+    .strict();
+export const runtimeStorageListResponseSchema = z
+    .object({
+    objects: z.array(runtimeStorageObjectSchema),
+    cursor: z.string().nullable(),
+    hasMore: z.boolean(),
+    usedBytes: z.number().int().nonnegative(),
+    quotaBytes: z.number().int().positive(),
+})
+    .strict();
+export const runtimeStorageListPublicResponseSchema = dataEnvelope(runtimeStorageListResponseSchema);
+export const runtimeStorageDeleteResponseSchema = z
+    .object({
+    key: runtimeStorageObjectKeySchema,
+    deleted: z.boolean(),
+})
+    .strict();
+export const runtimeStorageDeletePublicResponseSchema = mutationEnvelope(runtimeStorageDeleteResponseSchema);

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

@@ -1,7 +1,13 @@
+import type { Grant } from "./grants.js";
 export declare const SF_CONFIG_V1_CANONICAL_FILE = "sf.jsonc";
 export declare const SF_CONFIG_V1_FILES: readonly ["sf.jsonc", "spacefast.jsonc", "spacefast.json", "sf.json", ".sf/sf.json", ".sf/config.jsonc", ".sf/config.json"];
 /** 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.
+ */
+export type SfConfigV1RedirectStatus = 301 | 302 | 303 | 307 | 308;
 export type SfConfigV1 = {
     $schema?: typeof SF_CONFIG_V1_SCHEMA_URL;
     version: 1;
@@ -18,6 +24,38 @@ export type SfConfigV1 = {
         cleanUrls?: boolean;
         directoryListing?: boolean;
     };
+    /**
+     * Browser redirect rules, in the same matcher grammar as `_redirects`. The
+     * files match first; config rules add behavior where the files are silent.
+     */
+    redirects?: {
+        source: string;
+        destination: string;
+        status?: SfConfigV1RedirectStatus;
+    }[];
+    /**
+     * 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.
+     */
+    rewrites?: {
+        source: string;
+        destination: string;
+        /** Let shared caches store the proxy response. Absolute-URL destinations only. */
+        cache?: "shared";
+    }[];
+    /**
+     * Response headers to set on matching requests. Headers are a list, not a
+     * map, so repeated names (Set-Cookie) survive.
+     */
+    headers?: {
+        source: string;
+        headers: {
+            key: string;
+            value: string;
+        }[];
+    }[];
     metadata?: {
         title?: string;
         description?: string;
@@ -26,6 +64,9 @@ export type SfConfigV1 = {
     substitute?: {
         files: string[];
     };
+    access?: {
+        public: string[];
+    };
 };
 export type EffectiveConfigV1 = {
     version: 1;
@@ -39,11 +80,23 @@ export type EffectiveConfigV1 = {
         cleanUrls: boolean;
         directoryListing: boolean;
     };
+    /** Every rule states its status; an omitted one resolves to 302. */
+    redirects?: (NonNullable<SfConfigV1["redirects"]>[number] & {
+        status: SfConfigV1RedirectStatus;
+    })[];
+    rewrites?: SfConfigV1["rewrites"];
+    headers?: SfConfigV1["headers"];
     metadata?: SfConfigV1["metadata"];
     substitute?: SfConfigV1["substitute"];
+    grants?: Grant[];
 };
+/**
+ * Config-shape problems use the `config_*` codes; a bad routing rule reports
+ * the same code the `_redirects` / `_headers` compiler would give it, because
+ * 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" | "serve_index_required" | "template_syntax_retired";
+    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";
     severity: "error" | "warning";
     path: string;
     line: number;

package/dist/contracts/sf-config-v1.js

@@ -1,6 +1,6 @@
-import { BRAND } from "../brand.js";
+import { serviceOrigin } from "../config/domains.js";
 import { SPACE_CONFIG_ACCEPTED_FILES, SPACE_CONFIG_CANONICAL_FILE } from "./space-config.js";
 export const SF_CONFIG_V1_CANONICAL_FILE = SPACE_CONFIG_CANONICAL_FILE;
 export const SF_CONFIG_V1_FILES = SPACE_CONFIG_ACCEPTED_FILES;
 /** Published JSON Schema URL for the strict `sf.jsonc` v1 contract. */
-export const SF_CONFIG_V1_SCHEMA_URL = `${BRAND.websiteOrigin}/schemas/sf.v1.json`;
+export const SF_CONFIG_V1_SCHEMA_URL = `${serviceOrigin("www", "prod")}/schemas/sf.v1.json`;

package/dist/contracts/sites.d.ts

@@ -104,6 +104,7 @@ export declare const operatorSiteProvisioningSchema: z.ZodOptional<z.ZodObject<{
 }, z.core.$strip>>;
 export declare const tenantSiteProvisioningSchema: z.ZodOptional<z.ZodObject<{}, z.core.$strict>>;
 export declare const siteCreateSchema: z.ZodObject<{
+    teamId: z.ZodOptional<z.ZodString>;
     kind: z.ZodDefault<z.ZodEnum<{
         static_runtime: "static_runtime";
     }>>;
@@ -407,4 +408,9 @@ export declare const SiteRebalanceResultSchema: z.ZodObject<{
         spaceId: z.ZodString;
         operationId: z.ZodString;
     }, z.core.$strip>>;
+    warning: z.ZodString;
+    domainsRequiringReverification: z.ZodArray<z.ZodObject<{
+        spaceId: z.ZodString;
+        hostname: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/contracts/sites.js

@@ -11,7 +11,7 @@ export const SiteCapacitySchema = z
         .int()
         .nonnegative()
         .optional()
-        .describe("Maximum spaces this site may host."),
+        .describe("Maximum number of spaces this site can host."),
     usedSpaces: z
         .number()
         .int()
@@ -56,8 +56,8 @@ export const SitePressureSchema = z
 // Provider linkage (`providerClientId`, `providerRef`) is operator-only and
 // never appears in this tenant-facing shape.
 export const SiteSchema = z.object({
-    id: z.string().describe("Site id (`site_...`)."),
-    tenantId: z.string().describe("Owning tenant id (`ten_...`)."),
+    id: z.string().describe("The site id (`site_...`)."),
+    tenantId: z.string().describe("The owning tenant id (`ten_...`)."),
     principal: PrincipalRefSchema.nullable().describe("Owning principal within the tenant; null for tenant-level and pool sites."),
     kind: siteKind.describe("Runtime kind. Only the Spacefast static runtime exists today."),
     isolation: siteIsolation.describe("Whether settings/access default to the site or to each space."),
@@ -67,7 +67,7 @@ export const SiteSchema = z.object({
         .string()
         .nullable()
         .describe("Hostname the control plane manages the site runtime through."),
-    runtimeInstanceId: z.string().nullable().describe("Runtime instance identity for this site."),
+    runtimeInstanceId: z.string().nullable().describe("Runtime instance id for this site."),
     provider: z.literal("wpcloud").describe("Hosting provider."),
     capacity: SiteCapacitySchema.nullable().describe("Capacity accounting; null when the site has no explicit budget."),
     operation: AsyncOperationSchema.nullable(),
@@ -84,7 +84,7 @@ export const operatorSiteProvisioningSchema = z
         .trim()
         .min(1)
         .optional()
-        .describe("Import an existing WP.Cloud site by its atomic_site_id (operator flows)."),
+        .describe("Import an existing WP.Cloud site by its `atomic_site_id` (operator flows)."),
 })
     .optional();
 // An explicit empty object requests fresh provider provisioning while keeping
@@ -92,9 +92,15 @@ export const operatorSiteProvisioningSchema = z
 export const tenantSiteProvisioningSchema = z.object({}).strict().optional();
 export const siteCreateSchema = z
     .object({
+    teamId: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Team id or slug that will own the site. If omitted, the server infers it from the principal."),
     kind: siteKind.default("static_runtime"),
     isolation: siteIsolation.default("site"),
-    region: z.string().trim().min(1).optional().describe('Placement region; defaults to `"auto"`.'),
+    region: z.string().trim().min(1).optional().describe('Placement region. Defaults to `"auto"`.'),
     provisioning: tenantSiteProvisioningSchema,
 })
     .strict();
@@ -113,14 +119,16 @@ export const SuperadminSiteSchema = SiteSchema.extend({
         .string()
         .nullable()
         .describe("WP.Cloud client identity (`pvc_...`) the site is provisioned under."),
-    providerRef: z.string().nullable().describe("WP.Cloud atomic_site_id."),
+    providerRef: z.string().nullable().describe("WP.Cloud `atomic_site_id`."),
 });
 export const SuperadminSiteListSchema = z.object({
     sites: z.array(SuperadminSiteSchema),
 });
 // Superadmin site create targets an explicit tenant (the tenant-facing
 // `siteCreateSchema` derives the tenant from the principal).
-export const superadminSiteCreateSchema = siteCreateSchema.omit({ provisioning: true }).extend({
+export const superadminSiteCreateSchema = siteCreateSchema
+    .omit({ provisioning: true, teamId: true })
+    .extend({
     tenantId: z.string().trim().min(1),
     provisioning: operatorSiteProvisioningSchema,
 });
@@ -133,17 +141,28 @@ export const siteRebalanceRequestSchema = z
         .array(z.string().trim().min(1))
         .max(100)
         .optional()
-        .describe("Limit the rebalance to these space ids; omitted means every live space on the site."),
+        .describe("Limit the rebalance to these space ids. If omitted, the server rebalances every live space on the site."),
 })
-    .describe("Operator-only rebalance trigger: move spaces off this site.");
+    .describe("Operator-only rebalance trigger: move spaces off this site. This is the ONLY path that relocates an existing Space, and it is not free — see the reverification warning on the result.");
 export const SiteRebalanceResultSchema = z
     .object({
-    siteId: z.string().describe("The site spaces are being moved off."),
+    siteId: z.string().describe("The site id that spaces are being moved off."),
     moves: z
         .array(z.object({
         spaceId: z.string().describe("Space queued to move."),
         operationId: z.string().describe("The queued `space_move` operation id (`op_...`)."),
     }))
         .describe("One queued move operation per affected space."),
+    warning: z
+        .string()
+        .describe("Consequence of relocating these spaces. Each hostname moves to another provider site. The provider re-runs its domain-exclusivity check and rejects the move unless the ownership TXT record is still live in DNS."),
+    domainsRequiringReverification: z
+        .array(z.object({
+        spaceId: z.string().describe("Space the hostname serves."),
+        hostname: z
+            .string()
+            .describe("Custom hostname whose provider ownership check re-runs during the move."),
+    }))
+        .describe("Live custom hostnames on the moved spaces. Empty means no customer-visible hostname is at risk."),
 })
     .describe("Queued rebalance moves; track each operation for completion.");