@hexclave/shared 1.0.60 → 1.0.62

package/src/config/schema-fuzzer.test.ts

@@ -185,6 +185,43 @@ const branchSchemaFuzzerConfig = [{
   onboarding: [{
     requireEmailVerification: [true, false],
   }],
+  "deployments-alpha": [{
+    services: [{
+      "some-service-id": [{
+        type: ["vercel"] as const,
+        framework: ["nextjs", "vite", ""],
+        installCommand: ["pnpm install", ""],
+        buildCommand: ["pnpm build", ""],
+        outputDirectory: [".next", "dist", ""],
+        rootDirectory: ["./", "./apps/web", ""],
+        env: [{
+          "SOME_PLAIN_VAR": [{
+            type: [undefined] as ("secret" | "connection" | undefined)[],
+            value: ["some-value", ""],
+            key: [undefined] as (string | undefined)[],
+          }],
+          "SOME_CONNECTION_VAR": [{
+            type: ["connection"] as const,
+            // Stays valid even when the fuzzer drops `type`: without it, the
+            // entry reads as a plain env var whose literal value happens to be
+            // "hexclave.projectId".
+            value: ["hexclave.projectId", "some-other-service.url"],
+            key: [undefined] as (string | undefined)[],
+          }],
+          "SOME_SECRET_VAR": [{
+            type: ["secret"] as const,
+            value: [undefined] as (string | undefined)[],
+            // Kept undefined: `key` is only allowed when type is "secret", and
+            // the fuzzer randomizes each field independently so it cannot honor
+            // that coupling (same situation as oauth's customCallbackUrl). The
+            // accept path is covered by the schema unit tests and the
+            // deployments e2e tests.
+            key: [undefined] as (string | undefined)[],
+          }],
+        }],
+      }],
+    }],
+  }],
 }] satisfies FuzzerConfig<BranchConfigNormalizedOverride>;
 
 const environmentSchemaFuzzerConfig = [{

package/src/config/schema.ts

@@ -293,6 +293,127 @@ const branchOnboardingSchema = yupObject({
   requireEmailVerification: yupBoolean(),
 });
 
+// --- Deployments Schema ---
+// Service DEFINITIONS (type, framework, build config, env vars) live in the
+// branch config so they follow the project's config source: pushable from
+// hexclave.config.ts / GitHub, or editable in the dashboard when the config is
+// unlinked. Operational state (Vercel project id, deployment runs, custom
+// domains and their verification) lives in the backend database instead, keyed
+// by the service id.
+export const DEPLOYMENT_ENV_VAR_KEY_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const DEPLOYMENT_SECRET_KEY_REGEX = /^[a-zA-Z0-9_-]+$/;
+// A connection value is `<serviceId>.<outputKey>` — a typed pointer to another
+// service's output (e.g. "hexclave.projectId") that the backend resolves at
+// deploy time. This is deliberately its own env var TYPE rather than a
+// `{serviceId.outputKey}` interpolation syntax inside plain values: with
+// interpolation, a literal value that happens to contain `{...}` would be
+// misinterpreted as a reference, so plain values must stay entirely literal.
+export const DEPLOYMENT_CONNECTION_VALUE_REGEX = /^[a-zA-Z0-9_-]+\.[A-Za-z0-9_]+$/;
+
+// One env var, discriminated by `type`:
+// - absent (plain): a literal `value`, committed to the config.
+// - "secret": only the secret's name (`key`) is in the config; its value must
+//   be supplied at deploy time via `hexclave deploy --secret <key>=<value>`
+//   and is never persisted by Hexclave.
+// - "connection": `value` names another service's output (see the regex
+//   comment above); resolved server-side at deploy time.
+// Exported so the backend's deployments API routes validate request bodies
+// with the exact same rules as pushed configs.
+export const deploymentEnvVarSchema = yupObject({
+  type: yupString().oneOf(["secret", "connection"]).optional(),
+  value: yupString().when("type", ([type], schema) => {
+    switch (type) {
+      case "secret": {
+        return schema.oneOf([undefined], 'deployment env vars with type "secret" must not have a value — the value is supplied at deploy time via `hexclave deploy --secret <key>=<value>`');
+      }
+      case "connection": {
+        return schema.defined().matches(DEPLOYMENT_CONNECTION_VALUE_REGEX, 'deployment env vars with type "connection" must reference a service output like "hexclave.projectId"');
+      }
+      default: {
+        return schema.defined();
+      }
+    }
+  }),
+  key: yupString().when("type", ([type], schema) => type === "secret"
+    ? schema.defined().matches(DEPLOYMENT_SECRET_KEY_REGEX, "deployment secret keys must contain only letters, numbers, underscores, and hyphens")
+    : schema.oneOf([undefined], 'deployment env vars may only have a key when their type is "secret"')),
+});
+
+const branchDeploymentsSchema = yupObject({
+  services: yupRecord(
+    // "hexclave" is the managed backend's slot on the deployments board; a
+    // config entry must never shadow it, so it's rejected at the schema level
+    // (not just in the dashboard-create route — pushed configs go through
+    // validation too).
+    userSpecifiedIdSchema("serviceId").notOneOf(["hexclave"], 'The service id "hexclave" is reserved for the managed Hexclave service'),
+    yupObject({
+      // Which platform runs the service. Only Vercel-backed services exist
+      // today, but the field is required so configs stay unambiguous once more
+      // types are added (every write path must state what it's creating).
+      type: yupString().oneOf(["vercel"]).defined(),
+      framework: yupString().optional(),
+      installCommand: yupString().optional(),
+      buildCommand: yupString().optional(),
+      outputDirectory: yupString().optional(),
+      rootDirectory: yupString().optional(),
+      env: yupRecord(
+        yupString().matches(DEPLOYMENT_ENV_VAR_KEY_REGEX, "deployment env var keys must start with a letter or underscore and contain only letters, digits, and underscores"),
+        deploymentEnvVarSchema,
+      ),
+    }),
+  ),
+});
+
+import.meta.vitest?.test("branchDeploymentsSchema accepts all three env var types", async ({ expect }) => {
+  await expect(branchDeploymentsSchema.validate({
+    services: {
+      web: {
+        type: "vercel",
+        rootDirectory: "./",
+        framework: "nextjs",
+        env: {
+          MY_ENV_VAR: { value: "true" },
+          DATABASE_CONNECTION_STRING: { type: "secret", key: "db_connection" },
+          NEXT_PUBLIC_HEXCLAVE_PROJECT_ID: { type: "connection", value: "hexclave.projectId" },
+        },
+      },
+    },
+  }, { abortEarly: false })).resolves.toBeDefined();
+});
+
+import.meta.vitest?.test("branchDeploymentsSchema rejects services without a type", async ({ expect }) => {
+  await expect(branchDeploymentsSchema.validate({
+    services: {
+      web: { framework: "nextjs" },
+    },
+  }, { abortEarly: false })).rejects.toThrow(/type/);
+});
+
+import.meta.vitest?.test("branchDeploymentsSchema rejects invalid env var shapes", async ({ expect }) => {
+  // A secret with an inline value would defeat the whole point of secrets.
+  await expect(branchDeploymentsSchema.validate({
+    services: { web: { type: "vercel", env: { A: { type: "secret", key: "a", value: "leaked" } } } },
+  }, { abortEarly: false })).rejects.toThrow(/must not have a value/);
+  // A secret without a key can never be filled at deploy time.
+  await expect(branchDeploymentsSchema.validate({
+    services: { web: { type: "vercel", env: { A: { type: "secret" } } } },
+  }, { abortEarly: false })).rejects.toThrow(/key/);
+  // Plain values may not carry a secret key.
+  await expect(branchDeploymentsSchema.validate({
+    services: { web: { type: "vercel", env: { A: { value: "x", key: "a" } } } },
+  }, { abortEarly: false })).rejects.toThrow(/only have a key/);
+  // Connections must point at `<serviceId>.<outputKey>` — braces in particular
+  // are the OLD interpolation syntax and must not validate.
+  await expect(branchDeploymentsSchema.validate({
+    services: { web: { type: "vercel", env: { A: { type: "connection", value: "{hexclave.projectId}" } } } },
+  }, { abortEarly: false })).rejects.toThrow(/service output/);
+  // Env var keys must be valid POSIX-ish env var names.
+  await expect(branchDeploymentsSchema.validate({
+    services: { web: { type: "vercel", env: { "1BAD": { value: "x" } } } },
+  }, { abortEarly: false })).rejects.toThrow(/env var keys/);
+});
+// --- END Deployments Schema ---
+
 
 export const branchConfigSchema = canNoLongerBeOverridden(projectConfigSchema, [
   "sourceOfTruth",
@@ -327,6 +448,7 @@ export const branchConfigSchema = canNoLongerBeOverridden(projectConfigSchema, [
 
   payments: branchPaymentsSchema,
 
+  "deployments-alpha": branchDeploymentsSchema,
 
   dataVault: yupObject({
     stores: yupRecord(
@@ -574,6 +696,16 @@ export function migrateConfigOverride(type: "project" | "branch" | "environment"
   }
   // END
 
+  // BEGIN 2026-07-24: the deployments app is now `deployments-alpha`, both as its
+  // `apps.installed` key and as its top-level config section, so the alpha stage is
+  // visible in every hexclave.config.ts that opts into it. Both renames are needed:
+  // an installed entry without the config section (or vice versa) is a valid state.
+  if (isBranchOrHigher) {
+    res = renameProperty(res, "deployments", "deployments-alpha");
+    res = renameProperty(res, "apps.installed.deployments", "deployments-alpha");
+  }
+  // END
+
   // return the result
   return res;
 };
@@ -608,6 +740,51 @@ import.meta.vitest?.test("migrateConfigOverride removes legacy branch-level dbSy
   expect(migrateConfigOverride("environment", { dbSync })).toEqual({ dbSync });
 });
 
+import.meta.vitest?.test("migrateConfigOverride renames the deployments app to deployments-alpha", ({ expect }) => {
+  const services = { web: { type: "vercel", rootDirectory: "./" } };
+
+  // Fully nested overrides.
+  expect(migrateConfigOverride("branch", {
+    deployments: { services },
+    apps: { installed: { deployments: { enabled: true } } },
+  })).toEqual({
+    "deployments-alpha": { services },
+    apps: { installed: { "deployments-alpha": { enabled: true } } },
+  });
+
+  // Dot-notation overrides, which is how the dashboard and the Deployments app
+  // itself write single keys. The flat key form is preserved — only the renamed
+  // segment changes — so the override keeps overriding exactly one leaf rather
+  // than being widened into a whole subtree.
+  expect(migrateConfigOverride("branch", {
+    "deployments.services.web.buildCommand": "pnpm build",
+    "apps.installed.deployments.enabled": true,
+  })).toEqual({
+    "deployments-alpha.services.web.buildCommand": "pnpm build",
+    "apps.installed.deployments-alpha.enabled": true,
+  });
+
+  // A service literally named "deployments" sits below the renamed section and
+  // must survive untouched — only the top-level section and the installed-apps
+  // entry are renamed.
+  expect(migrateConfigOverride("branch", {
+    deployments: { services: { deployments: { type: "vercel" } } },
+  })).toEqual({
+    "deployments-alpha": { services: { deployments: { type: "vercel" } } },
+  });
+
+  // Already-migrated configs are left alone (the migration must be idempotent,
+  // since it re-runs on every read).
+  expect(migrateConfigOverride("branch", {
+    "deployments-alpha": { services },
+  })).toEqual({
+    "deployments-alpha": { services },
+  });
+
+  // Project level is not branch-or-higher, so nothing is renamed there.
+  expect(migrateConfigOverride("project", { deployments: { services } })).toEqual({ deployments: { services } });
+});
+
 function removeProperty(obj: Record<string, any>, pathCond: (path: (string | symbol)[]) => boolean): any {
   return mapProperty(obj, pathCond, () => undefined);
 }
@@ -875,6 +1052,22 @@ const organizationConfigDefaults = {
     }),
   },
 
+  "deployments-alpha": {
+    services: (key: string) => ({
+      type: undefined,
+      framework: undefined,
+      installCommand: undefined,
+      buildCommand: undefined,
+      outputDirectory: undefined,
+      rootDirectory: undefined,
+      env: (envVarKey: string) => ({
+        type: undefined,
+        value: undefined,
+        key: undefined,
+      }),
+    }),
+  },
+
   dataVault: {
     stores: (key: string) => ({
       displayName: "Unnamed Vault",

package/src/interface/admin-interface.ts

@@ -36,6 +36,74 @@ export type ChatContent = Array<
   | { type: "tool-call", toolName: string, toolCallId: string, args: any, argsText: string, result: any }
 >;
 
+export type AdminDeploymentRunJson = {
+  id: string,
+  service_id: string,
+  status: "queued" | "building" | "ready" | "error" | "canceled",
+  target: string,
+  triggered_by: string,
+  url: string | null,
+  error: string | null,
+  created_at_millis: number,
+  finished_at_millis: number | null,
+};
+
+// One env var of a deployment service, normalized from the config-side
+// definition: "plain" vars carry their literal `value`, "connection" vars
+// carry the "serviceId.outputKey" reference they resolve to at deploy time,
+// and "secret" vars carry only the `secret_key` whose value is supplied via
+// `hexclave deploy --secret <key>=<value>` (never stored).
+export type AdminDeploymentEnvVarJson = {
+  key: string,
+  type: "plain" | "secret" | "connection",
+  value: string | null,
+  secret_key: string | null,
+};
+
+// The config-side shape of one env var, mirroring
+// `deployments-alpha.services.<id>.env.<KEY>` in hexclave.config.ts: no type means a
+// plain value, "secret" requires `key`, "connection" requires a
+// "serviceId.outputKey" `value`.
+export type AdminDeploymentEnvVarOptions =
+  | { type?: undefined, value: string }
+  | { type: "secret", key: string }
+  | { type: "connection", value: string };
+
+export type AdminDeploymentServiceJson = {
+  id: string,
+  type: "vercel",
+  framework: string | null,
+  install_command: string | null,
+  build_command: string | null,
+  output_directory: string | null,
+  root_directory: string | null,
+  provisioned: boolean,
+  status: "not_deployed" | "queued" | "building" | "deployed" | "failed" | "canceled",
+  has_successful_deploy: boolean,
+  url: string | null,
+  env: AdminDeploymentEnvVarJson[],
+  domains: { hostname: string, is_primary: boolean, verified: boolean }[],
+  latest_run: AdminDeploymentRunJson | null,
+};
+
+// null means "unset this field" (falls back to platform auto-detection);
+// undefined means "leave unchanged".
+export type AdminDeploymentServiceBuildOptions = {
+  framework?: string | null,
+  install_command?: string | null,
+  build_command?: string | null,
+  output_directory?: string | null,
+  root_directory?: string | null,
+};
+
+export type AdminDeploymentDomainJson = {
+  hostname: string,
+  is_primary: boolean,
+  verified: boolean,
+  pending_first_deploy: boolean,
+  dns_records: { type: string, name: string, value: string }[],
+};
+
 export type AdminAuthApplicationOptions = ServerAuthApplicationOptions &(
   | {
     superSecretAdminKey: string,
@@ -1204,4 +1272,109 @@ export class HexclaveAdminInterface extends HexclaveServerInterface {
     return await response.json();
   }
 
+  // ---- Deployments app ------------------------------------------------------
+
+  async listDeploymentServices(): Promise<AdminDeploymentServiceJson[]> {
+    const response = await this.sendAdminRequest(
+      "/deployments/services",
+      { method: "GET" },
+      null,
+    );
+    return (await response.json()).items;
+  }
+
+  async createDeploymentService(id: string, build: AdminDeploymentServiceBuildOptions): Promise<AdminDeploymentServiceJson> {
+    const response = await this.sendAdminRequest(
+      "/deployments/services",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ id, ...build }),
+      },
+      null,
+    );
+    return await response.json();
+  }
+
+  async updateDeploymentService(serviceId: string, update: AdminDeploymentServiceBuildOptions & {
+    // Replaces the service's whole env var set (config-side definition shape).
+    env?: Record<string, AdminDeploymentEnvVarOptions>,
+  }): Promise<AdminDeploymentServiceJson> {
+    const response = await this.sendAdminRequest(
+      urlString`/deployments/services/${serviceId}`,
+      {
+        method: "PATCH",
+        headers: {
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(update),
+      },
+      null,
+    );
+    return await response.json();
+  }
+
+  async deleteDeploymentService(serviceId: string): Promise<void> {
+    await this.sendAdminRequest(
+      urlString`/deployments/services/${serviceId}`,
+      { method: "DELETE" },
+      null,
+    );
+  }
+
+  async listDeploymentRuns(serviceId: string, options?: { limit?: number }): Promise<AdminDeploymentRunJson[]> {
+    const response = await this.sendAdminRequest(
+      urlString`/deployments/services/${serviceId}/runs` + (options?.limit !== undefined ? `?limit=${options.limit}` : ""),
+      { method: "GET" },
+      null,
+    );
+    return (await response.json()).items;
+  }
+
+  async getDeploymentRunLogs(runId: string, options?: { signal?: AbortSignal }): Promise<string> {
+    // The endpoint streams chunked plain text until the run is terminal (or a
+    // server-side cap); reading the full body gives "the logs so far". Pass a
+    // signal so an abandoned view can abort — otherwise the server keeps
+    // following the build for minutes.
+    const response = await this.sendAdminRequest(
+      urlString`/deployments/runs/${runId}/logs`,
+      { method: "GET", signal: options?.signal },
+      null,
+    );
+    return await response.text();
+  }
+
+  async addDeploymentServiceDomain(serviceId: string, hostname: string, options?: { isPrimary?: boolean }): Promise<void> {
+    await this.sendAdminRequest(
+      urlString`/deployments/services/${serviceId}/domains`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ hostname, ...(options?.isPrimary ? { is_primary: true } : {}) }),
+      },
+      null,
+    );
+  }
+
+  async getDeploymentServiceDomain(serviceId: string, hostname: string): Promise<AdminDeploymentDomainJson> {
+    const response = await this.sendAdminRequest(
+      urlString`/deployments/services/${serviceId}/domains/${hostname}`,
+      { method: "GET" },
+      null,
+    );
+    return await response.json();
+  }
+
+  async deleteDeploymentServiceDomain(serviceId: string, hostname: string): Promise<void> {
+    await this.sendAdminRequest(
+      urlString`/deployments/services/${serviceId}/domains/${hostname}`,
+      { method: "DELETE" },
+      null,
+    );
+  }
+
 }