@hexclave/shared 1.0.61 → 1.0.62

package/src/ai/unified-prompts/skill-site-prompt-parts/deployments-skill.ts

@@ -0,0 +1,128 @@
+import { deindent } from "../../../utils/strings";
+
+// The Deployments-specific addendum served at https://skill.hexclave.com/deployments.
+// It is appended verbatim after the full base skill, so this section assumes the
+// reader already has the general Hexclave skill (CLI auth, config format, SDKs) in
+// context and only teaches what is specific to the Deployments app.
+export const deploymentsSkillSection = deindent`
+  # Hexclave Deployments
+
+  The Deployments app makes deploying a service very easy. You select a type of service to deploy and provide your code, build instructions, run instructions, environment variables, and the code framework. You can set up multiple deployments per Hexclave project — for example, a backend service and a frontend service. Once a service is deployed, it is publicly accessible.
+
+  For this iteration of the Deployments app, only the \`vercel\` service type is available. It can be used to set up serverless deployments.
+
+  To use Hexclave Deployments, you must do a few things. First, the Deployments app must be enabled, by adding \`deployments-alpha\` under \`apps.installed\`. Second, you must edit your \`hexclave.config.ts\` file to add the relevant configuration, as specified below. Both keys are \`deployments-alpha\`, not \`deployments\` — the app is in alpha and its id says so. Because of the hyphen, quote it.
+
+  ## Config
+
+  \`\`\`ts title="hexclave.config.ts"
+  import type { HexclaveConfig } from "@hexclave/js/config"; // replace \`js\` with the correct framework SDK package
+
+  export const config: HexclaveConfig = {
+    apps: {
+      installed: {
+        authentication: { enabled: true },
+        "deployments-alpha": { enabled: true },
+      },
+    },
+    "deployments-alpha": {
+      services: {
+        web: {
+          type: "vercel",
+          rootDirectory: "./",
+          framework: "nextjs",
+          installCommand: "pnpm install",
+          buildCommand: "pnpm build",
+          outputDirectory: ".next",
+          env: {
+            "MY_ENV_VAR": { value: "true" },
+            "DATABASE_CONNECTION_STRING": { type: "secret", key: "db_connection" },
+            "NEXT_PUBLIC_HEXCLAVE_PROJECT_ID": { type: "connection", value: "hexclave.projectId" },
+          },
+        },
+      },
+    },
+  };
+  \`\`\`
+
+  Here, \`web\` is the name of your service. \`type\` refers to the type of service you want to set up; for now, as mentioned earlier, only \`vercel\` is supported. \`rootDirectory\` is the directory in which the install and build commands are run, and where the code for your service is found. \`installCommand\` is the command run to install your application's dependencies, and \`buildCommand\` is what is run to build the necessary packages and files. \`framework\` is the framework used by your service; from it and \`outputDirectory\`, the run command is inferred.
+
+  The \`HexclaveConfig\` annotation requires the SDK package it is imported from to be a dependency of the project. If it isn't, either install it or drop the annotation (the config is plain TypeScript — the CLI does not type-check it).
+
+  Note also that the config file usually sits inside \`rootDirectory\`, which means it is uploaded with your source and compiled by the remote build like any other file. If the deployed app doesn't depend on the Hexclave SDK, add \`hexclave.config.ts\` to \`.vercelignore\`: the CLI reads the config from disk before packaging, so the build itself never needs it, and excluding it keeps an SDK import in the config from breaking a build that is otherwise unrelated to Hexclave.
+
+  ## Domains
+
+  Every Vercel service gets a Vercel domain autoprovisioned. If you want to attach a custom domain, there are two ways to do so.
+
+  **Option 1 — the dashboard.** Visit \`https://app.hexclave.com/projects/<project-id>/deployments\`, click the service of choice, go to the Domains tab, add your domain, and then create the returned DNS records at your DNS provider.
+
+  **Option 2 — the CLI.** Here is an example of adding \`app.example.com\` to the service \`api\` and receiving the DNS records that then need to be set with your DNS provider:
+
+  \`\`\`sh title="Terminal"
+  npx @hexclave/cli@latest exec --cloud-project-id <project-id> \\
+    "const p = await hexclaveServerApp.getProject(); \\
+     await p.addDeploymentServiceDomain('api', 'app.example.com'); \\
+     return p.getDeploymentServiceDomain('api', 'app.example.com');"
+  \`\`\`
+
+  ## Deploying
+
+  Before deploying, run the service's \`installCommand\` and \`buildCommand\` locally and confirm they succeed. The remote build runs the same commands, but \`deploy\` exits before the build finishes, so a broken build does not fail the command — it surfaces only when you check the run afterwards.
+
+  From the directory containing your config file:
+
+  \`\`\`sh title="Terminal"
+  npx @hexclave/cli@latest deploy web --secret db_connection="$DATABASE_URL"
+  \`\`\`
+
+  The CLI packages the service's root directory (respecting \`.gitignore\` and \`.vercelignore\`, and always excluding \`node_modules\` and \`.git\`), uploads it, and starts a remote build. Without a config file, the configuration stored in Hexclave governs the deploy, with the root directory resolved against the current directory. It always deploys to production, never prompts, and exits as soon as the build is queued, printing the run id. Follow the build in the dashboard's Deployments tab.
+
+  Every secret defined in the service's \`env\` must be passed via \`--secret\` on every deploy — a missing (or misspelled) one fails the deploy before anything is uploaded.
+
+  Options: \`--config <path>\` (default: auto-discover \`hexclave.config.ts\` in the current directory, dashboard configuration otherwise), \`--cloud-project-id <id>\` (default: the \`HEXCLAVE_PROJECT_ID\` env var), and \`--secret KEY=VALUE\` (repeatable, see above).
+
+  You can also deploy through GitHub Actions, like so:
+
+  \`\`\`yaml title=".github/workflows/deploy.yaml"
+  - run: npm i -g @hexclave/cli
+  - run: hexclave deploy web --secret db_connection="$DATABASE_URL"
+    env:
+      HEXCLAVE_PROJECT_ID: \${{ secrets.HEXCLAVE_PROJECT_ID }}
+      HEXCLAVE_SECRET_SERVER_KEY: \${{ secrets.HEXCLAVE_SECRET_SERVER_KEY }}
+      DATABASE_URL: \${{ secrets.DATABASE_URL }}
+  \`\`\`
+
+  ## Checking status and debugging failures
+
+  Because \`deploy\` returns as soon as the build is queued, a successful exit does not mean the deploy succeeded. Check the service to find out:
+
+  \`\`\`sh title="Terminal"
+  npx @hexclave/cli@latest exec --cloud-project-id <project-id> \\
+    "const p = await hexclaveServerApp.getProject(); \\
+     const svc = (await p.listDeploymentServices()).find(s => s.id === 'web'); \\
+     return { status: svc.status, url: svc.url, run: svc.latest_run };"
+  \`\`\`
+
+  A service's \`status\` is one of \`not_deployed\`, \`queued\`, \`building\`, \`deployed\`, \`failed\`, or \`canceled\`; a run's is \`queued\`, \`building\`, \`ready\`, \`error\`, or \`canceled\`. Poll until the run leaves \`queued\`/\`building\`.
+
+  A failed run's \`error\` field is only a one-line summary (for example \`Command "npm run build" exited with 1\`). Do not try to guess the cause from it, and do not reproduce the build locally to find out — fetch the actual build output by run id:
+
+  \`\`\`sh title="Terminal"
+  npx @hexclave/cli@latest exec --cloud-project-id <project-id> \\
+    "const p = await hexclaveServerApp.getProject(); \\
+     return p.getDeploymentRunLogs('<run-id>');"
+  \`\`\`
+
+  \`deploy\` prints the run id it started. If you don't have one, \`listDeploymentRuns('web', { limit: 5 })\` returns the most recent runs, newest first — call it through \`exec\` like the snippets above.
+
+  ## Deleting a service
+
+  If you want to delete a deployed service, you can do so through the dashboard, or through the CLI like so:
+
+  \`\`\`sh title="Terminal"
+  npx @hexclave/cli@latest exec --cloud-project-id <project-id> \\
+    "const p = await hexclaveServerApp.getProject(); \\
+     await p.deleteDeploymentService('api');"
+  \`\`\`
+`;

package/src/ai/unified-prompts/skill-site-prompt.ts

@@ -6,6 +6,7 @@ import { cliHelpPrompt } from "./skill-site-prompt-parts/cli-help";
 import { configDocsPrompt } from "./skill-site-prompt-parts/config-docs";
 import { customComponentsInstructionsPrompt } from "./skill-site-prompt-parts/custom-components-instructions";
 import { dashboardInstructionsPrompt } from "./skill-site-prompt-parts/dashboard-instructions";
+import { deploymentsSkillSection } from "./skill-site-prompt-parts/deployments-skill";
 import { docsIndexPrompt } from "./skill-site-prompt-parts/docs-index";
 import { sdkInterfaceSourcePrompt } from "./skill-site-prompt-parts/sdk-interface-source";
 
@@ -73,3 +74,17 @@ export function buildSkillSitePrompt(docsIndexPromptValue = docsIndexPrompt) {
 }
 
 export const skillSitePrompt = buildSkillSitePrompt();
+
+// The /deployments variant of the skill: the entire base skill, followed by the
+// Deployments-specific addendum. Served at https://skill.hexclave.com/deployments
+// so an agent pointed at that URL gets the full Hexclave skill plus the deeper
+// Deployments material in one document.
+export function buildDeploymentsSkillSitePrompt(baseSkillPrompt = skillSitePrompt) {
+  return deindent`
+    ${baseSkillPrompt}
+
+    ${deploymentsSkillSection}
+  `;
+}
+
+export const deploymentsSkillSitePrompt = buildDeploymentsSkillSitePrompt();

package/src/apps/apps-config.ts

@@ -192,6 +192,15 @@ export const ALL_APPS = {
     tags: ["auth", "developers"],
     stage: "alpha",
   },
+  // The app id carries the `-alpha` suffix deliberately: it is the key users
+  // write in `apps.installed` and under the top-level config, so the stage is
+  // visible in every hexclave.config.ts. The display name stays "Deployments".
+  "deployments-alpha": {
+    displayName: "Deployments",
+    subtitle: "Configure and connect the services that run your app",
+    tags: ["developers", "operations"],
+    stage: "alpha",
+  },
 } as const satisfies Record<string, App>;
 
 export function getParentAppId(appId: AppId): AppId | null {

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,
+    );
+  }
+
 }