@spacefast/common 0.0.6 → 0.0.8

package/dist/contracts/error-codes.js

@@ -25,6 +25,7 @@ export const ERROR_CODES = [
     "anonymous_pool_unavailable",
     "anonymous_publish_rate_limited",
     "anonymous_space_limit_reached",
+    "api_key_scope_underivable",
     "archive_body_required",
     "archive_too_large",
     "auth_code_required",
@@ -119,6 +120,7 @@ export const ERROR_CODES = [
     "domain_wildcard_not_enabled",
     "download_required",
     "duplicate_version_path",
+    "enforcement_policy_overlap",
     "event_payload_too_large",
     "event_rate_limited",
     "expired_token",
@@ -207,6 +209,7 @@ export const ERROR_CODES = [
     "publish_archive_expanded_size_exceeded",
     "publish_archive_file_count_exceeded",
     "publish_archive_too_large",
+    "publish_base_changed",
     "publish_config_unsupported",
     "publish_failed",
     "publish_file_missing",
@@ -247,12 +250,16 @@ export const ERROR_CODES = [
     "site_required",
     "site_suspended",
     "slow_down",
+    "slug_invalid",
+    "slug_reserved",
+    "slug_unavailable",
     "space_already_claimed",
     "space_claim_unavailable",
     "space_claimed_credential_available",
     "space_disabled",
     "space_expired",
     "space_has_active_version",
+    "space_hostname_identity_missing",
     "space_import_archive_invalid",
     "space_import_archive_too_large",
     "space_import_config_only_archive",
@@ -340,11 +347,14 @@ export const ERROR_CODES = [
     "wp_cloud_team_shared_site_exists",
     "wp_cloud_webhook_secret_not_configured",
     "zero_activating",
+    "zero_ai_unavailable",
     "zero_artifact_abi_mismatch",
     "zero_artifact_invalid",
     "zero_artifact_malformed",
+    "zero_artifact_missing",
     "zero_artifact_path_invalid",
     "zero_artifact_unreadable",
+    "zero_artifact_untrusted",
     "zero_auth_unavailable",
     "zero_blob_key_invalid",
     "zero_blob_store_full",
@@ -355,6 +365,7 @@ export const ERROR_CODES = [
     "zero_bytecode_invalid",
     "zero_bytecode_path_invalid",
     "zero_bytecode_unreadable",
+    "zero_capabilities_encode_failed",
     "zero_client_bundle_not_loaded",
     "zero_db_connect_failed",
     "zero_db_execute_failed",
@@ -373,12 +384,19 @@ export const ERROR_CODES = [
     "zero_db_url_missing",
     "zero_dev_endpoint_failed",
     "zero_dump_query_invalid",
+    "zero_endpoint_compile_failed",
+    "zero_endpoint_conflict",
+    "zero_endpoint_duplicate",
+    "zero_endpoint_id_duplicate",
     "zero_endpoint_index_invalid",
     "zero_endpoint_index_malformed",
     "zero_endpoint_index_path_invalid",
     "zero_endpoint_index_unreadable",
+    "zero_endpoint_invalid",
     "zero_endpoint_mismatch",
     "zero_endpoint_not_found",
+    "zero_endpoints_invalid",
+    "zero_endpoints_too_many",
     "zero_envelope_encode_failed",
     "zero_js_context_init_failed",
     "zero_js_execution_failed",
@@ -387,7 +405,9 @@ export const ERROR_CODES = [
     "zero_js_response_malformed",
     "zero_js_runtime_init_failed",
     "zero_log_query_invalid",
+    "zero_lookup_invalid",
     "zero_method_not_allowed",
+    "zero_migration_failed",
     "zero_query_name_missing",
     "zero_realtime_forbidden",
     "zero_realtime_message_invalid",
@@ -402,6 +422,10 @@ export const ERROR_CODES = [
     "zero_request_body_too_large",
     "zero_requires_dedicated_plan",
     "zero_response_too_large",
+    "zero_routes_invalid",
+    "zero_run_compile_failed",
+    "zero_run_duplicate",
+    "zero_run_invalid",
     "zero_run_operation_unsupported",
     "zero_runner_envelope_invalid",
     "zero_runner_failed",
@@ -413,6 +437,10 @@ export const ERROR_CODES = [
     "zero_runner_stdin_invalid",
     "zero_runner_stdin_too_large",
     "zero_runner_unavailable",
+    "zero_runs_invalid",
+    "zero_runs_require_runtime_compiler",
+    "zero_runs_too_many",
+    "zero_shopify_unavailable",
     "zero_source_compile_failed",
     "zero_source_hash_mismatch",
     "zero_source_invalid",

package/dist/contracts/feature-lifecycle-core.d.ts

@@ -0,0 +1,36 @@
+export declare const FEATURE_STAGES: readonly ["internal", "private_beta", "ga"];
+export type FeatureStage = (typeof FEATURE_STAGES)[number];
+export declare const FEATURE_ASSIGNMENT_SCOPES: readonly ["user", "team", "global"];
+export type FeatureAssignmentScope = (typeof FEATURE_ASSIGNMENT_SCOPES)[number];
+export declare const FEATURE_EXECUTION_ACTOR_POLICIES: readonly ["request_actor", "persisted_request_actor", "resource_team", "global_policy"];
+export type FeatureExecutionActorPolicy = (typeof FEATURE_EXECUTION_ACTOR_POLICIES)[number];
+export declare const FEATURE_OWNER_IDS: readonly ["team:access", "team:build-platform", "team:collaboration", "team:commerce", "team:domains", "team:publishing", "team:runtime", "team:spaces", "team:tag-manager", "team:zero"];
+export type FeatureOwnerId = (typeof FEATURE_OWNER_IDS)[number];
+export type FeatureRegistryEntry<K extends string = string, DependencyKey extends string = K> = {
+    readonly cohort: "launch";
+    readonly key: K;
+    readonly name: string;
+    readonly description: string;
+    readonly stage: FeatureStage;
+    readonly surface: boolean;
+    readonly defaultEnabled: boolean;
+    readonly assignmentScopes: readonly FeatureAssignmentScope[];
+    readonly docs: {
+        readonly channel: "public" | "handbook";
+        readonly slug: string;
+        readonly feedbackUrl: string | null;
+    } | null;
+    readonly owner: FeatureOwnerId;
+    readonly requires: readonly DependencyKey[];
+    readonly lifecycleAdoptedAt: string;
+    readonly reviewAfter: string | null;
+    readonly removeAfter: string | null;
+    readonly gaAt: string | null;
+    readonly allowedActorPolicies: readonly FeatureExecutionActorPolicy[];
+    readonly downRamp: {
+        readonly code: string;
+        readonly summary: string;
+    };
+};
+export declare function freezeFeatureRegistryEntry<K extends string, DependencyKey extends string>(definition: FeatureRegistryEntry<K, DependencyKey>): FeatureRegistryEntry<K, DependencyKey>;
+export declare function validateFeatureLifecycleRegistry(registry: readonly FeatureRegistryEntry[]): readonly string[];

package/dist/contracts/feature-lifecycle-core.js

@@ -0,0 +1,220 @@
+export const FEATURE_STAGES = ["internal", "private_beta", "ga"];
+export const FEATURE_ASSIGNMENT_SCOPES = ["user", "team", "global"];
+export const FEATURE_EXECUTION_ACTOR_POLICIES = [
+    "request_actor",
+    "persisted_request_actor",
+    "resource_team",
+    "global_policy",
+];
+export const FEATURE_OWNER_IDS = [
+    "team:access",
+    "team:build-platform",
+    "team:collaboration",
+    "team:commerce",
+    "team:domains",
+    "team:publishing",
+    "team:runtime",
+    "team:spaces",
+    "team:tag-manager",
+    "team:zero",
+];
+export function freezeFeatureRegistryEntry(definition) {
+    return Object.freeze({
+        ...definition,
+        assignmentScopes: Object.freeze([...definition.assignmentScopes]),
+        docs: definition.docs === null ? null : Object.freeze({ ...definition.docs }),
+        requires: Object.freeze([...definition.requires]),
+        allowedActorPolicies: Object.freeze([...definition.allowedActorPolicies]),
+        downRamp: Object.freeze({ ...definition.downRamp }),
+    });
+}
+function isStrictLifecycleDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const date = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+function hasCanonicalDocsSlug(channel, slug) {
+    const prefix = channel === "public" ? "/docs/" : "/features/";
+    return (slug.startsWith(prefix) &&
+        slug
+            .slice(prefix.length)
+            .split("/")
+            .every((segment) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(segment)));
+}
+function hasRequiredMetadata(value) {
+    const normalized = value.trim();
+    return normalized.length > 0 && normalized.toUpperCase() !== "TBD";
+}
+function duplicateValues(values) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            duplicates.add(value);
+        seen.add(value);
+    }
+    return [...duplicates].toSorted();
+}
+function isValidUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" || url.protocol === "http:";
+    }
+    catch {
+        return false;
+    }
+}
+export function validateFeatureLifecycleRegistry(registry) {
+    const errors = [];
+    const keys = new Set(registry.map(({ key }) => key));
+    const downRampCodes = new Set(registry.map(({ downRamp }) => downRamp.code));
+    if (keys.size !== registry.length)
+        errors.push("registry: duplicate feature key");
+    if (downRampCodes.size !== registry.length)
+        errors.push("registry: duplicate down-ramp code");
+    const byKey = new Map(registry.map((definition) => [definition.key, definition]));
+    for (const [index, definition] of registry.entries()) {
+        const lifecycleAdoptedAtValid = isStrictLifecycleDate(definition.lifecycleAdoptedAt);
+        const reviewAfterValid = definition.reviewAfter === null || isStrictLifecycleDate(definition.reviewAfter);
+        const removeAfterValid = definition.removeAfter === null || isStrictLifecycleDate(definition.removeAfter);
+        const gaAtValid = definition.gaAt === null || isStrictLifecycleDate(definition.gaAt);
+        if (!lifecycleAdoptedAtValid)
+            errors.push(`${definition.key}: lifecycleAdoptedAt must be a real YYYY-MM-DD date`);
+        if (!reviewAfterValid)
+            errors.push(`${definition.key}: reviewAfter must be a real YYYY-MM-DD date`);
+        if (!removeAfterValid)
+            errors.push(`${definition.key}: removeAfter must be a real YYYY-MM-DD date`);
+        if (!gaAtValid)
+            errors.push(`${definition.key}: gaAt must be a real YYYY-MM-DD date`);
+        if (!hasRequiredMetadata(definition.name))
+            errors.push(`${definition.key}: name must not be blank or TBD`);
+        if (!hasRequiredMetadata(definition.description))
+            errors.push(`${definition.key}: description must not be blank or TBD`);
+        if (!hasRequiredMetadata(definition.owner))
+            errors.push(`${definition.key}: owner must not be blank or TBD`);
+        if (!hasRequiredMetadata(definition.downRamp.code))
+            errors.push(`${definition.key}: downRamp.code must not be blank or TBD`);
+        if (!hasRequiredMetadata(definition.downRamp.summary))
+            errors.push(`${definition.key}: downRamp.summary must not be blank or TBD`);
+        if (!hasRequiredMetadata(definition.key))
+            errors.push(`registry[${index}]: feature key must not be blank or TBD`);
+        else if (!/^[a-z][a-z0-9]*(?:[._][a-z][a-z0-9]*)*$/.test(definition.key))
+            errors.push(`${definition.key}: feature key must use canonical lowercase segments`);
+        if (hasRequiredMetadata(definition.downRamp.code) &&
+            !/^[a-z][a-z0-9]*(?:_[a-z][a-z0-9]*)*$/.test(definition.downRamp.code))
+            errors.push(`${definition.key}: downRamp.code must use canonical snake_case`);
+        if (definition.assignmentScopes.length === 0 || !definition.assignmentScopes.includes("global"))
+            errors.push(`${definition.key}: assignmentScopes must include global`);
+        if (definition.allowedActorPolicies.length === 0)
+            errors.push(`${definition.key}: allowedActorPolicies must not be empty`);
+        for (const [field, values] of [
+            ["assignmentScopes", definition.assignmentScopes],
+            ["allowedActorPolicies", definition.allowedActorPolicies],
+            ["requires", definition.requires],
+        ]) {
+            for (const duplicate of duplicateValues(values))
+                errors.push(`${definition.key}: ${field} contains duplicate ${duplicate}`);
+        }
+        if (definition.allowedActorPolicies.includes("global_policy") &&
+            (definition.assignmentScopes.length !== 1 || definition.assignmentScopes[0] !== "global"))
+            errors.push(`${definition.key}: global policy requires exactly global assignment scope`);
+        if (definition.stage !== "ga" && definition.surface && definition.defaultEnabled)
+            errors.push(`${definition.key}: non-GA features default off`);
+        if (definition.stage === "ga" && definition.surface && !definition.defaultEnabled)
+            errors.push(`${definition.key}: GA surface features default on`);
+        if (!definition.surface && definition.docs !== null)
+            errors.push(`${definition.key}: non-surface features must not have docs`);
+        if (definition.docs !== null &&
+            !hasCanonicalDocsSlug(definition.docs.channel, definition.docs.slug))
+            errors.push(`${definition.key}: docs slug must be a canonical ${definition.docs.channel} path`);
+        if (definition.docs !== null &&
+            definition.docs.feedbackUrl !== null &&
+            !isValidUrl(definition.docs.feedbackUrl))
+            errors.push(`${definition.key}: docs feedbackUrl must be a valid URL`);
+        if (definition.stage === "internal" && definition.docs?.channel === "public")
+            errors.push(`${definition.key}: internal features must not have public docs`);
+        if (definition.stage === "private_beta" && definition.docs?.channel !== "public")
+            errors.push(`${definition.key}: private beta requires public docs`);
+        if (definition.stage === "ga" && definition.surface && definition.docs?.channel !== "public")
+            errors.push(`${definition.key}: GA surface features require public docs`);
+        if (definition.stage !== "ga" && definition.surface && definition.reviewAfter === null)
+            errors.push(`${definition.key}: non-GA surface features require reviewAfter`);
+        if (definition.surface && definition.removeAfter === null)
+            errors.push(`${definition.key}: surface features require removeAfter`);
+        if (lifecycleAdoptedAtValid &&
+            reviewAfterValid &&
+            definition.reviewAfter !== null &&
+            definition.lifecycleAdoptedAt > definition.reviewAfter)
+            errors.push(`${definition.key}: lifecycleAdoptedAt must not follow reviewAfter`);
+        if (reviewAfterValid &&
+            removeAfterValid &&
+            definition.reviewAfter !== null &&
+            definition.removeAfter !== null &&
+            definition.reviewAfter > definition.removeAfter)
+            errors.push(`${definition.key}: reviewAfter must not follow removeAfter`);
+        if (lifecycleAdoptedAtValid &&
+            removeAfterValid &&
+            definition.removeAfter !== null &&
+            definition.lifecycleAdoptedAt > definition.removeAfter)
+            errors.push(`${definition.key}: lifecycleAdoptedAt must not follow removeAfter`);
+        if (definition.gaAt !== null && definition.stage !== "ga")
+            errors.push(`${definition.key}: only GA features may set gaAt`);
+        if (definition.stage === "ga" && definition.gaAt === null)
+            errors.push(`${definition.key}: GA features require gaAt`);
+        if (lifecycleAdoptedAtValid &&
+            gaAtValid &&
+            definition.gaAt !== null &&
+            definition.gaAt < definition.lifecycleAdoptedAt)
+            errors.push(`${definition.key}: gaAt must not precede lifecycleAdoptedAt`);
+        if (gaAtValid &&
+            removeAfterValid &&
+            definition.gaAt !== null &&
+            definition.removeAfter !== null &&
+            definition.gaAt > definition.removeAfter)
+            errors.push(`${definition.key}: gaAt must not follow removeAfter`);
+        if (definition.assignmentScopes.includes("user") &&
+            !definition.allowedActorPolicies.some((policy) => policy === "request_actor" || policy === "persisted_request_actor"))
+            errors.push(`${definition.key}: user scope requires an actor-aware policy`);
+        for (const dependency of definition.requires) {
+            const dependencyDefinition = byKey.get(dependency);
+            if (!dependencyDefinition) {
+                errors.push(`${definition.key}: unknown dependency ${dependency}`);
+                continue;
+            }
+            if (definition.allowedActorPolicies.some((policy) => !dependencyDefinition.allowedActorPolicies.includes(policy)))
+                errors.push(`${definition.key}: actor policies must be allowed by dependency ${dependency}`);
+            if (definition.assignmentScopes.some((scope) => !dependencyDefinition.assignmentScopes.includes(scope)))
+                errors.push(`${definition.key}: assignment scopes must be supported by dependency ${dependency}`);
+            if (FEATURE_STAGES.indexOf(dependencyDefinition.stage) <
+                FEATURE_STAGES.indexOf(definition.stage))
+                errors.push(`${definition.key}: dependency ${dependency} must be at least as mature as its dependent`);
+            if (definition.defaultEnabled && !dependencyDefinition.defaultEnabled)
+                errors.push(`${definition.key}: default-enabled feature requires default-enabled dependency ${dependency}`);
+            if (removeAfterValid &&
+                dependencyDefinition.removeAfter !== null &&
+                isStrictLifecycleDate(dependencyDefinition.removeAfter) &&
+                (definition.removeAfter === null ||
+                    dependencyDefinition.removeAfter < definition.removeAfter))
+                errors.push(`${definition.key}: dependency ${dependency} retires before its dependent`);
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (key) => {
+        if (visiting.has(key)) {
+            errors.push(`${key}: dependency cycle`);
+            return;
+        }
+        if (visited.has(key))
+            return;
+        visiting.add(key);
+        for (const dependency of byKey.get(key)?.requires ?? [])
+            visit(dependency);
+        visiting.delete(key);
+        visited.add(key);
+    };
+    for (const key of keys)
+        visit(key);
+    return errors;
+}

package/dist/contracts/feature-lifecycle.d.ts

@@ -0,0 +1,7 @@
+import type { FeatureRegistryEntry } from "./feature-lifecycle-core.js";
+import { launchEntries as compiledLaunchEntries } from "./generated-feature-launch-entries.js";
+export { FEATURE_ASSIGNMENT_SCOPES, FEATURE_EXECUTION_ACTOR_POLICIES, FEATURE_OWNER_IDS, FEATURE_STAGES, freezeFeatureRegistryEntry, validateFeatureLifecycleRegistry, } from "./feature-lifecycle-core.js";
+export type { FeatureAssignmentScope, FeatureExecutionActorPolicy, FeatureOwnerId, FeatureRegistryEntry, FeatureStage, } from "./feature-lifecycle-core.js";
+export type LifecycleFeatureKey = (typeof compiledLaunchEntries)[number]["key"];
+export declare const FEATURE_LIFECYCLE_REGISTRY: readonly FeatureRegistryEntry<LifecycleFeatureKey>[];
+export declare const FEATURE_LIFECYCLE_BY_KEY: ReadonlyMap<LifecycleFeatureKey, FeatureRegistryEntry<LifecycleFeatureKey>>;

package/dist/contracts/feature-lifecycle.js

@@ -0,0 +1,31 @@
+import { launchEntries as compiledLaunchEntries } from "./generated-feature-launch-entries.js";
+export { FEATURE_ASSIGNMENT_SCOPES, FEATURE_EXECUTION_ACTOR_POLICIES, FEATURE_OWNER_IDS, FEATURE_STAGES, freezeFeatureRegistryEntry, validateFeatureLifecycleRegistry, } from "./feature-lifecycle-core.js";
+export const FEATURE_LIFECYCLE_REGISTRY = compiledLaunchEntries;
+const featureLifecycleByKey = new Map(FEATURE_LIFECYCLE_REGISTRY.map((definition) => [definition.key, definition]));
+export const FEATURE_LIFECYCLE_BY_KEY = Object.freeze({
+    get size() {
+        return featureLifecycleByKey.size;
+    },
+    get(key) {
+        return featureLifecycleByKey.get(key);
+    },
+    has(key) {
+        return featureLifecycleByKey.has(key);
+    },
+    entries() {
+        return featureLifecycleByKey.entries();
+    },
+    keys() {
+        return featureLifecycleByKey.keys();
+    },
+    values() {
+        return featureLifecycleByKey.values();
+    },
+    forEach(callback, thisArg) {
+        for (const [key, value] of featureLifecycleByKey)
+            callback.call(thisArg, value, key, this);
+    },
+    [Symbol.iterator]() {
+        return featureLifecycleByKey[Symbol.iterator]();
+    },
+});

package/dist/contracts/generated-feature-launch-entries.d.ts

@@ -0,0 +1,2 @@
+export declare const launchEntries: readonly import("./feature-lifecycle-core.js").FeatureRegistryEntry<"zero" | "plans.paid.available" | "anonymous.publishing" | "domains.registration" | "domains.dns_management" | "domains.wpcom_dns" | "domains.domain_connect" | "domains.proxy_bindings" | "annotations.preview_loader" | "annotations.comments" | "annotations.notices" | "annotations.published_comments" | "sites.dedicated_runtime" | "tags" | "access.invites" | "access.sso_connections" | "access.byo_issuers" | "domains.catalog" | "build.content_pipeline" | "spaces.slug_rename", "annotations.comments" | "sites.dedicated_runtime">[];
+export declare const registryHash = "sha256:bb171bdc1b4815eae685a2c97c5ab5042faf5b1fa0a99ad9ac4406d14210381d";