@builder.io/ai-utils 0.86.1 → 0.87.0

package/src/projects.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { EnvironmentVariableSchema, } from "./common-schemas";
+import { EnvironmentVariableSchema, SetupDependencySchema, } from "./common-schemas";
+import { AutoPushModeSchema, CustomInstructionSchema, CustomAgentDefinitionSchema, ExitStateSchema, FileOverrideSchema, } from "./codegen";
 /**
  * Detect git provider from a repository URL (HTTPS or SSH).
  * Used by both error diagnostics and connectivity checks for consistent provider labeling.
@@ -59,6 +60,82 @@ export const EXAMPLE_OR_STARTER_REPOS = [
     AGENT_NATIVE_STARTER_REPO,
 ];
 export const EXAMPLE_OR_STARTER_REPOS_URLS = EXAMPLE_OR_STARTER_REPOS.map((repo) => `https://github.com/${repo}`);
+/** Fields shared by every {@link ProjectSkill} variant. */
+const ProjectSkillBaseShape = {
+    key: z.string().meta({
+        description: "Stable identifier for the entry (used for logs/dedup, not by the CLI).",
+    }),
+    skills: z.array(z.string()).optional().meta({
+        description: "Specific skill names to install (--skill). Omit to install all.",
+    }),
+    agents: z.array(z.string()).optional().meta({
+        description: 'Target agents (--agent). Defaults to ["claude-code"].',
+    }),
+};
+/**
+ * A skill source passed directly to `skills add`. Supports GitHub shorthand,
+ * Git/GitHub URLs, local paths, npm: sources, etc.
+ */
+export const ProjectSkillSourceSchema = z
+    .object({
+    ...ProjectSkillBaseShape,
+    source: z.string(),
+})
+    .meta({ title: "ProjectSkillSource" });
+/**
+ * A skill sourced from an npm package. The package must contain a SKILL.md at
+ * its root (or a skills/<name>/SKILL.md).
+ */
+export const ProjectSkillNpmSchema = z
+    .object({
+    ...ProjectSkillBaseShape,
+    type: z.literal("npm"),
+    package: z.string(),
+    version: z.string().optional(),
+})
+    .meta({ title: "ProjectSkillNpm" });
+/**
+ * A skill sourced from a GitHub repository following the Claude Code plugin
+ * layout (skills/<name>/SKILL.md) or containing a SKILL.md at root.
+ */
+export const ProjectSkillGithubSchema = z
+    .object({
+    ...ProjectSkillBaseShape,
+    type: z.literal("github"),
+    repo: z.string().meta({ description: '"owner/repo"' }),
+    ref: z
+        .string()
+        .optional()
+        .meta({ description: "Branch, tag, or commit SHA." }),
+    path: z.string().optional().meta({
+        description: "Sub-path inside the repo to treat as the plugin root (default: repo root).",
+    }),
+})
+    .meta({ title: "ProjectSkillGithub" });
+/**
+ * A skill sourced from a URL supported by `skills add`, such as a GitHub/GitLab
+ * tree URL, a direct git URL, or a well-known skills index URL.
+ */
+export const ProjectSkillUrlSchema = z
+    .object({
+    ...ProjectSkillBaseShape,
+    type: z.literal("url"),
+    url: z.string(),
+})
+    .meta({ title: "ProjectSkillUrl" });
+/**
+ * A project-level skill to install during Fusion initialization. A plain
+ * `z.union` (not `discriminatedUnion`) because the `source` variant has no
+ * `type` tag to discriminate on.
+ */
+export const ProjectSkillSchema = z
+    .union([
+    ProjectSkillSourceSchema,
+    ProjectSkillNpmSchema,
+    ProjectSkillGithubSchema,
+    ProjectSkillUrlSchema,
+])
+    .meta({ title: "ProjectSkill" });
 export const checkIsNewBranch = (branch) => {
     return "projectId" in branch;
 };
@@ -147,6 +224,524 @@ export const ListBranchesOptionsSchema = z.object({
         description: "Superuser-only: list branches for a different owner/org.",
     }),
 });
+export const ProjectRolePermissionsSchema = z
+    .object({
+    view: z.boolean().optional(),
+    editCode: z.boolean().optional(),
+    sendPullRequests: z.boolean().optional(),
+    createBranches: z.boolean().optional(),
+    modifyMcpServers: z.boolean().optional(),
+    modifyWorkflowIntegrations: z.boolean().optional(),
+    modifyProjectSettings: z.boolean().optional(),
+    fusionHostingPublish: z.boolean().optional(),
+})
+    .meta({ title: "ProjectRolePermissions" });
+export const ProjectAccessControlSchema = z
+    .object({
+    roles: z.record(z.string(), ProjectRolePermissionsSchema.nullable()),
+    users: z.record(z.string(), ProjectRolePermissionsSchema),
+})
+    .meta({ title: "ProjectAccessControl" });
+/**
+ * Runtime schema for {@link Project.settings} — the full stored shape, including
+ * `@internal` (system/agent-managed) fields. Plain `z.object` strips unknown
+ * keys on parse.
+ *
+ * For client-writable payloads use {@link ProjectSettingsExternalSchema}, which
+ * is derived from this schema with the internal fields omitted so external
+ * callers can't set them through the public update API.
+ */
+export const ProjectSettingsSchema = z
+    .object({
+    isNativeApp: z.boolean().optional().meta({
+        description: "When true, this is a native (mobile/desktop) app with no web dev server.",
+    }),
+    autoDetectDevServer: z.boolean().optional().meta({
+        description: "When true, automatically detect the dev server URL from command output (Desktop app only).",
+    }),
+    autoDetectDevServerPatterns: z.array(z.string()).optional().meta({
+        description: "Regex patterns matched against dev command output to detect the server URL.",
+    }),
+    fusionEnvironment: z
+        .enum(["containerized", "container-less", "cloud", "cloud-v2"])
+        .optional()
+        .meta({
+        description: "Execution environment for the Fusion runtime (cloud, containerized, container-less).",
+    }),
+    devServerPort: z.number().optional().meta({
+        description: "Port the dev server listens on inside the container. Use 0 for auto-assign. Default: 3000.",
+    }),
+    devServerUrl: z.string().optional().meta({
+        description: "@internal Explicit dev server URL; overrides auto-detection. Set by the system, not user-configurable.",
+    }),
+    refreshPreview: z.boolean().optional().meta({
+        description: "@internal Whether to reload the preview when files change. Managed by the app UI.",
+    }),
+    installCommand: z.string().optional().meta({
+        description: 'Commands to install dependencies before starting the dev server (e.g. "npm install").',
+    }),
+    installNpmrc: z.string().nullish().meta({
+        description: "Contents of an .npmrc file written before installCommand runs (e.g. private registry auth).",
+    }),
+    validateCommand: z.string().optional().meta({
+        description: "@internal Command to run validation checks. Used internally by the setup agent.",
+    }),
+    proxyOrigin: z.string().optional().meta({
+        description: "@internal URL origin used for the dev server proxy. Related to Electron proxy configuration. Exposed via specific UI; not a free-text field.",
+    }),
+    proxyDefaultOrigin: z.string().optional().meta({
+        description: "@internal Default proxy origin, resolved at runtime.",
+    }),
+    defaultAutoPush: AutoPushModeSchema.optional().meta({
+        description: "@internal Mode for automatically pushing AI commits. Managed by the app.",
+    }),
+    gitBranchNamingStrategy: z
+        .enum(["ai-session", "branch-name", "custom"])
+        .optional()
+        .meta({
+        description: "How branch names are generated: ai-session ID, descriptive name, or a custom pattern.",
+    }),
+    setupDependencies: z.array(SetupDependencySchema).optional().meta({
+        description: "@internal Mise tools and custom scripts run before the setup command. Managed via builder.config.json.",
+    }),
+    hostRequirements: z
+        .array(z.object({
+        name: z.string().meta({ description: "Requirement name." }),
+        checkScript: z.string().meta({
+            description: "Script that checks whether it's satisfied.",
+        }),
+        installScript: z.string().nullish().meta({
+            description: "Script that installs the requirement, if available.",
+        }),
+        installLink: z.string().nullish().meta({
+            description: "Link with install instructions, if available.",
+        }),
+        platform: z
+            .enum(["macos", "windows", "linux"])
+            .nullish()
+            .meta({ description: "Platform this requirement applies to." }),
+        description: z
+            .string()
+            .optional()
+            .meta({ description: "Human-readable description." }),
+    }))
+        .optional()
+        .meta({
+        description: "Host tool requirements checked/installed for desktop-app projects.",
+    }),
+    skills: z.array(ProjectSkillSchema).optional().meta({
+        description: "Project-level skills to install during Fusion initialization.",
+    }),
+    gitBranchNamingCustom: z.string().optional(),
+    askUserForBranchName: z.boolean().optional().meta({
+        description: "When true, the user is prompted to provide a branch name before a new branch is created.",
+    }),
+    allowBranchFromRemote: z.boolean().optional().meta({
+        description: "When true, the user is prompted to branch from a remote branch when creating a new branch.",
+    }),
+    devServerCommand: z.string().optional().meta({
+        description: 'Command to start the dev server (e.g. "npm run dev").',
+    }),
+    screenshotCommand: z.string().optional().meta({
+        description: "Command used to capture a screenshot of the running app.",
+    }),
+    interactCommand: z.string().optional().meta({
+        description: "Command used to drive interact mode against the running app.",
+    }),
+    serverTimeout: z.number().optional().meta({
+        description: "Max time (ms) to wait for the dev server to become ready. Default: 600000.",
+    }),
+    cpuKind: z.enum(["performance", "standard", "shared"]).optional().meta({
+        description: 'CPU tier for the container: "performance", "standard", or "shared".',
+    }),
+    cpus: z
+        .union([z.literal(1), z.literal(2), z.literal(4)])
+        .optional()
+        .meta({
+        description: "Number of vCPUs allocated to the container: 1, 2, or 4.",
+    }),
+    memory: z
+        .union([
+        z.literal(2048),
+        z.literal(4096),
+        z.literal(8192),
+        z.literal(16384),
+    ])
+        .optional()
+        .meta({
+        description: "RAM allocated to the container in MB. Higher values (8192/16384) are enterprise-only. Default: 4096.",
+    }),
+    memoryLimit: z
+        .union([
+        z.literal(1024),
+        z.literal(2048),
+        z.literal(4096),
+        z.literal(8192),
+        z.literal(16384),
+    ])
+        .optional()
+        .meta({ description: "@deprecated Use {@link memory} instead." }),
+    autoStop: z.enum(["stop", "off", "suspend"]).optional().meta({
+        description: 'Idle behavior for the container: stop, suspend, or stay on. Default: "suspend".',
+    }),
+    mainBranchName: z.string().optional().meta({
+        description: 'Base branch used when cloning and creating new branches. Default: "main".',
+    }),
+    minMachinesRunning: z.number().optional().meta({
+        description: "Minimum number of machines kept alive at all times. Default: 0.",
+    }),
+    volumeSize: z
+        .union([
+        z.literal(5),
+        z.literal(10),
+        z.literal(12),
+        z.literal(15),
+        z.literal(20),
+        z.literal(25),
+        z.literal(30),
+        z.literal(50),
+    ])
+        .optional()
+        .meta({ description: "Persistent disk size in GB. Default: 5." }),
+    includePath: z.string().optional().meta({
+        description: "@internal Subpath within the repository to use as the working root.",
+    }),
+    includePatterns: z.array(z.string()).optional().meta({
+        description: "Glob patterns limiting which paths are included when cloning or processing.",
+    }),
+    errorIgnorePatterns: z.array(z.string()).optional().meta({
+        description: "Patterns for client-side runtime errors the preview should ignore.",
+    }),
+    environmentVariables: z.array(EnvironmentVariableSchema).optional().meta({
+        description: "Environment variables injected into the dev container.",
+    }),
+    requiredEnvironmentVariables: z
+        .array(z.object({
+        key: z.string().meta({ description: "Env var name." }),
+        description: z
+            .string()
+            .optional()
+            .meta({ description: "Human-readable purpose of the variable." }),
+        optional: z.boolean().nullish().meta({
+            description: "When true, the variable is not required to be set.",
+        }),
+    }))
+        .optional()
+        .meta({
+        description: "Declared env vars the project expects, surfaced in the UI for the user to fill in.",
+    }),
+    fileOverrides: z.array(FileOverrideSchema).optional().meta({
+        description: "Files injected into the container during setup, written before installCommand runs.",
+    }),
+    customInstructions: z.array(CustomInstructionSchema).optional().meta({
+        description: "Structured instruction rules applied to AI sessions (name, content, scope, tool allowlists).",
+    }),
+    customAgents: z.array(CustomAgentDefinitionSchema).optional().meta({
+        description: "Definitions for specialized sub-agents with custom system prompts, tools, and model overrides.",
+    }),
+    mcpServers: z
+        .record(z.string(), 
+    // Mirrors the client-writable subset of `MCPServerDefinition`. `scope`
+    // and `pluginName` are deliberately excluded: the loader sets them from
+    // where a server was discovered, so they aren't config a caller writes.
+    z.object({
+        command: z.string().meta({ description: "Executable to launch." }),
+        args: z
+            .array(z.string())
+            .optional()
+            .meta({ description: "Arguments passed to the command." }),
+        env: z
+            .record(z.string(), z.string())
+            .optional()
+            .meta({ description: "Environment variables for the server." }),
+        envFile: z.string().optional().meta({
+            description: "Path to a .env file to load environment variables from, resolved against the project root when relative.",
+        }),
+        retries: z.number().optional().meta({
+            description: "How many times to retry connecting to the server before giving up. Default: 0.",
+        }),
+    }))
+        .optional()
+        .meta({
+        description: "MCP servers to make available to AI sessions, keyed by server name.",
+    }),
+    commitMode: z.enum(["commits", "draft-prs", "prs"]).optional().meta({
+        description: 'How the AI commits changes: direct commits, draft PRs, or ready-for-review PRs. Default: "draft-prs".',
+    }),
+    autoCloseBranchOnMerge: z.boolean().optional().meta({
+        description: "@internal Default for new branches' autoCloseBranchOnMerge. When false, merging a PR does not archive the branch. Read only at branch-creation time. Default: true.",
+    }),
+    enableMergePR: z.boolean().optional().meta({
+        description: "Whether merging the PR from the editor is enabled.",
+    }),
+    minRequiredApprovals: z.number().optional().meta({
+        description: "Minimum number of approvals required before a PR can be sent/merged. Default: 0.",
+    }),
+    requireApprovalBeforePR: z.boolean().optional().meta({
+        description: "When true, block sending a PR until the required approvals are met.",
+    }),
+    requiredApproverRoleIds: z.array(z.string()).optional().meta({
+        description: "Role IDs whose members can satisfy the approval requirement.",
+    }),
+    requiredApproverRoleId: z.string().optional().meta({
+        description: "@deprecated Use {@link requiredApproverRoleIds}. Single approver role ID.",
+    }),
+    defaultBranchType: z.enum(["shared", "private"]).optional().meta({
+        description: 'Default visibility for new branches: shared (team-visible) or private. Default: "private".',
+    }),
+    dockerImagePath: z.string().optional().meta({
+        description: "Custom container image path (e.g. ghcr.io/org/image:tag). Overrides nodeVersion when set.",
+    }),
+    ghcrUsername: z.string().nullish().meta({
+        description: "GitHub Container Registry username used to pull a private dockerImagePath.",
+    }),
+    ghcrToken: z.string().nullish().meta({
+        description: "GitHub Container Registry token/password used to pull a private dockerImagePath. Sensitive.",
+    }),
+    nodeVersion: z.string().optional().meta({
+        description: 'Node.js version to use in the container (e.g. "22"). Ignored when dockerImagePath is set.',
+    }),
+    designSystems: z.array(z.string()).optional().meta({
+        description: "Named design systems to expose for AI assistance.",
+    }),
+    designTokenStrictMode: z.boolean().optional().meta({
+        description: "When true, enforce strict design-token usage during code generation.",
+    }),
+    designModeSelector: z.string().optional().meta({
+        description: "CSS selector marking the region editable in design mode.",
+    }),
+    useNI: z.boolean().optional().meta({
+        description: "@internal Use @antfu/ni for package management instead of direct npm/yarn/pnpm commands.",
+    }),
+    folders: z
+        .array(z.object({
+        name: z.string().meta({
+            description: "Identifier for this workspace folder (kebab/snake case recommended).",
+        }),
+        remoteUrl: z.string().meta({
+            description: "Full clone URL of the repository (must end in .git for GitHub/GitLab).",
+        }),
+        mainBranchName: z
+            .string()
+            .optional()
+            .meta({ description: 'Base branch to clone. Default: "main".' }),
+        includePath: z.string().optional().meta({
+            description: "Subpath within this repo to use as the working root.",
+        }),
+        addedBy: z
+            .string()
+            .optional()
+            .meta({ description: "User ID of whoever added this folder." }),
+        repoProvider: z
+            .string()
+            .optional()
+            .meta({ description: "Detected or specified git provider." }),
+        repoProtocol: z
+            .string()
+            .optional()
+            .meta({ description: 'Clone protocol: "https" or "ssh".' }),
+        enableGit: z.boolean().optional().meta({
+            description: "Whether to track git history for this folder.",
+        }),
+    }))
+        .optional()
+        .meta({
+        description: "Additional repositories cloned alongside the main repo for extra AI context.",
+    }),
+    agentsMD: z.string().optional().meta({
+        description: "Freeform workspace-level AI instructions, equivalent to an AGENTS.md file.",
+    }),
+    initializationCommand: z.string().optional().meta({
+        description: "One-time command run after the repo is first cloned, before installCommand.",
+    }),
+    repoSubpath: z.string().optional().meta({
+        description: "@internal Subpath within the repo recommended by auto-detection as the project root.",
+    }),
+    recommendedRoot: z.string().optional().meta({
+        description: "@internal Workspace root recommended by auto-setup analysis; not user-configurable.",
+    }),
+    https: z.boolean().optional().meta({
+        description: "Enable HTTPS for the dev server proxy. Default: false.",
+    }),
+    localHttpsDomain: z.string().optional().meta({
+        description: 'Custom local domain for HTTPS (e.g. "myapp.local").',
+    }),
+    browserAutomation: z
+        .object({
+        backgroundAgents: z.boolean().optional().meta({
+            description: "Run browser automation tasks as background agents.",
+        }),
+        builderApp: z.boolean().optional().meta({
+            description: "Use the Builder desktop app for browser automation.",
+        }),
+        instructions: z
+            .string()
+            .optional()
+            .meta({ description: "Custom instructions for the browser agent." }),
+        authUser: z.string().optional().meta({
+            description: "Username for sites requiring authentication.",
+        }),
+        authPassword: z.string().optional().meta({
+            description: "Password for sites requiring authentication.",
+        }),
+    })
+        .optional()
+        .meta({
+        description: "Browser automation configuration for AI-driven end-to-end testing and visual verification.",
+    }),
+    prReviewer: z
+        .object({
+        enabled: z
+            .boolean()
+            .meta({ description: "Whether the automated reviewer is enabled." }),
+        instructions: z
+            .string()
+            .optional()
+            .meta({ description: "Custom review guidelines for the reviewer." }),
+        reviewEffort: z.enum(["medium", "high", "low"]).optional().meta({
+            description: 'How deeply to review: "low", "medium" (default), or "high".',
+        }),
+        model: z
+            .string()
+            .optional()
+            .meta({ description: "Model override for the automated reviewer." }),
+    })
+        .optional()
+        .meta({ description: "Automated PR reviewer configuration." }),
+    enableSnapshots: z.boolean().optional().meta({
+        description: "Enable volume snapshots so session state can be saved and restored.",
+    }),
+    postMergeMemories: z.boolean().optional().meta({
+        description: "When true, the AI captures memories after a branch is merged for use in future sessions.",
+    }),
+    commitInstructions: z.string().optional().meta({
+        description: "@internal Custom instructions for AI-generated commit messages.",
+    }),
+    maxAgentCompletions: z.number().optional().meta({
+        description: "Maximum number of AI completions allowed per agent session.",
+    }),
+    enableAgentMode: z.boolean().optional().meta({
+        description: "When true, the agent-mode tab is enabled in the editor.",
+    }),
+    allowPreviewAutoSubmit: z.boolean().optional().meta({
+        description: "When true, the preview may auto-submit forms/prompts.",
+    }),
+    enforceDesktopAppOnly: z.boolean().optional().meta({
+        description: "When true, the project can only be opened in the desktop app.",
+    }),
+    disableDesktopProxying: z.boolean().optional().meta({
+        description: "When true, disable the desktop app's dev-server proxy.",
+    }),
+    previewUrl: z.string().nullish().meta({
+        description: "Template/preview URL shown for the project.",
+    }),
+    recentUrls: z
+        .array(z.object({
+        url: z.string().meta({ description: "Navigated preview URL." }),
+        timestamp: z
+            .number()
+            .meta({ description: "Last-visited time (ms since epoch)." }),
+        starred: z
+            .boolean()
+            .meta({ description: "Whether the user starred this URL." }),
+    }))
+        .optional()
+        .meta({
+        description: "Recently navigated preview URLs (history + starred), maintained by the editor.",
+    }),
+    skipCommandSecurity: z.boolean().optional().meta({
+        description: "@internal Bypass command security restrictions. Admin use only.",
+    }),
+    httpsServerKeyPath: z
+        .string()
+        .optional()
+        .meta({ description: "File path to the HTTPS private key." }),
+    httpsServerCertPath: z
+        .string()
+        .optional()
+        .meta({ description: "File path to the HTTPS certificate." }),
+    httpsServerCaPath: z
+        .string()
+        .optional()
+        .meta({ description: "File path to the HTTPS CA certificate." }),
+    httpsServerKeyContent: z.string().optional().meta({
+        description: "HTTPS private key content as a string (alternative to httpsServerKeyPath).",
+    }),
+    httpsServerCertContent: z.string().optional().meta({
+        description: "HTTPS certificate content as a string (alternative to httpsServerCertPath).",
+    }),
+    httpsServerCaContent: z.string().optional().meta({
+        description: "HTTPS CA certificate content as a string (alternative to httpsServerCaPath).",
+    }),
+    httpsServerPfx: z
+        .string()
+        .optional()
+        .meta({ description: "PFX/PKCS12 bundle for HTTPS." }),
+    httpsServerPassphrase: z.string().optional().meta({
+        description: "Passphrase for an encrypted HTTPS private key or PFX.",
+    }),
+    httpsServerSecureProtocol: z.string().optional().meta({
+        description: 'Secure protocol string passed to Node.js https.createServer (e.g. "TLSv1_2_method").',
+    }),
+    httpsServerSecureOptions: z.number().optional().meta({
+        description: "Numeric TLS options bitmask passed to Node.js https.createServer.",
+    }),
+    httpsServerCiphers: z.string().optional().meta({
+        description: "Cipher suite string (OpenSSL format) for the HTTPS server.",
+    }),
+    httpsServerHonorCipherOrder: z.boolean().optional().meta({
+        description: "When true, the server's cipher order takes precedence over the client's.",
+    }),
+    httpsServerRequestCert: z.boolean().optional().meta({
+        description: "When true, the server requests a client certificate.",
+    }),
+    httpsServerRejectUnauthorized: z.boolean().optional().meta({
+        description: "When false, self-signed or untrusted client certificates are accepted.",
+    }),
+    isPreferredForRepo: z.boolean().optional().meta({
+        description: "When true, this project is the preferred project for its connected repository. Agents will pick this project when asked to do something with the connected repository.",
+    }),
+    singleTenancyConfig: z.string().optional().meta({
+        description: "Single tenancy config ID for this project. Overrides the space-level defaultSingleTenancyConfig. References a document in the singleTenancyConfigurations collection.",
+    }),
+    previewPasswordProtection: z
+        .object({
+        enabled: z.boolean(),
+        password: z.string().optional(),
+    })
+        .optional()
+        .meta({ description: "Password-protect the preview URL." }),
+})
+    .meta({ title: "ProjectSettings" });
+/**
+ * Mask of internal, system/agent-managed settings keys. These fields live in
+ * {@link ProjectSettingsSchema} but are omitted from
+ * {@link ProjectSettingsExternalSchema} so external callers can't set them
+ * through the public update API.
+ */
+const INTERNAL_PROJECT_SETTINGS_MASK = {
+    devServerUrl: true,
+    refreshPreview: true,
+    validateCommand: true,
+    proxyOrigin: true,
+    proxyDefaultOrigin: true,
+    defaultAutoPush: true,
+    setupDependencies: true,
+    includePath: true,
+    useNI: true,
+    repoSubpath: true,
+    recommendedRoot: true,
+    commitInstructions: true,
+    skipCommandSecurity: true,
+    autoCloseBranchOnMerge: true,
+};
+/**
+ * Runtime schema for the client-writable subset of {@link Project.settings},
+ * derived from {@link ProjectSettingsSchema} by omitting the `@internal`
+ * (system/agent-managed) fields. Use this for public update/PATCH payloads so
+ * external callers can't set internal-only fields.
+ */
+export const ProjectSettingsExternalSchema = ProjectSettingsSchema.omit(INTERNAL_PROJECT_SETTINGS_MASK).meta({ title: "ProjectSettingsExternal" });
 /** Grace period before scheduled Neon deletions run (reconciler + schedule APIs). */
 export const NEON_DELETION_GRACE_PERIOD_MS = 30 * 24 * 60 * 60 * 1000;
 /**
@@ -437,19 +1032,37 @@ export const ProjectHostingSchema = z.object({
      * and this field, so they never disagree.
      */
     unpublishTrigger: z.enum(["system", "user"]).optional().meta({
-        description: "Who last unpublished the site. Absent === user. 'system' lets the reconciler auto-restore a usage-cap takedown; 'user' does not.",
+        description: "Who last unpublished the site. Absent === user. 'system' lets the reconciler auto-restore a credit-based takedown; 'user' does not.",
     }),
     /**
      * Why the system unpublished the site. Set iff `unpublishTrigger === "system"`;
      * drives the projects-grid "suspended" card and takedown observability.
      */
-    systemUnpublishReason: z
-        .enum(["bandwidth-cap", "web-request-cap"])
-        .optional(),
+    systemUnpublishReason: z.enum(["zero-credits"]).optional(),
     domainIds: z.array(z.string()).optional().meta({
         description: "Doc keys (normalized domains) in `hosting-domains` attached to this project. The domain docs are the source of truth; this is only the back-pointer.",
     }),
 });
+/**
+ * Mask of the hosting sub-fields a client may write via `PATCH`. Everything
+ * else on {@link ProjectHostingSchema} is owned by the slug-reservation /
+ * publish / deploy / custom-domain flows.
+ *
+ * Deliberately an allowlist rather than a denylist of system-owned fields: a
+ * new field added to `ProjectHostingSchema` must be opted *in* to be writable,
+ * so the default for anything we add later is "not client-writable".
+ */
+const PROJECT_UPDATABLE_HOSTING_FIELDS_MASK = {
+    enabled: true,
+    buildConfig: true,
+    environment: true,
+    autoDeploy: true,
+};
+/**
+ * Client-writable subset of {@link ProjectHostingSchema}. Used for `PATCH`
+ * payloads so external callers can't write system-owned hosting fields.
+ */
+export const ProjectHostingExternalSchema = ProjectHostingSchema.pick(PROJECT_UPDATABLE_HOSTING_FIELDS_MASK).meta({ title: "ProjectHostingExternal" });
 /**
  * Canonical "is this project hostable" predicate. Keys off the explicit
  * `hosting.enabled` flag rather than inferring from build-config presence.
@@ -457,6 +1070,82 @@ export const ProjectHostingSchema = z.object({
 export const isProjectHostable = (hosting) => {
     return (hosting === null || hosting === void 0 ? void 0 : hosting.enabled) === true;
 };
+/**
+ * Validates the body of `PATCH /projects/:projectId`. The schema's field set is
+ * the allowlist of client-writable fields: unknown keys are stripped on parse,
+ * so callers can't write arbitrary `Project` fields. `settings` and `hosting`
+ * are partial — a PATCH can touch a subset of sub-fields.
+ */
+export const UpdateProjectOptionsSchema = z.object({
+    projectId: z.string(),
+    name: z.string().optional(),
+    settings: z
+        .object({
+        ...ProjectSettingsExternalSchema.partial().shape,
+        // Deliberately looser than the stored shape, which requires `enabled`.
+        previewPasswordProtection: z
+            .object({
+            enabled: z.boolean().optional(),
+            password: z.string().optional(),
+        })
+            .optional()
+            .meta({
+            description: 'Password protection for the preview URL. A PATCH may change the password without resending `enabled`: a missing `enabled` means "preserve the existing value" rather than "disable".',
+        }),
+    })
+        .optional(),
+    hosting: ProjectHostingExternalSchema.partial().nullish(),
+    deleteEnvironmentVariableKeys: z.array(z.string()).optional().meta({
+        description: "Keys to delete from `settings.environmentVariables`. Without this list, keys missing from the incoming payload are preserved (additive merge) to protect against stale clients overwriting concurrent edits.",
+    }),
+    deleteHostingEnvironmentVariableKeys: z
+        .object({
+        build: z.array(z.string()).optional(),
+        prod: z.array(z.string()).optional(),
+    })
+        .optional()
+        .meta({
+        description: "Keys to delete from hosting env vars, per scope. Without an entry for a scope, keys missing from that scope are preserved (additive merge).",
+    }),
+    snapshotVolume: z
+        .object({
+        volumeId: z.string(),
+        appName: z.string(),
+        createdAt: z.number(),
+    })
+        .optional(),
+    pinned: z.boolean().optional(),
+    pinOrder: z.number().optional(),
+    archived: z.boolean().optional(),
+    needSetup: z.boolean().optional(),
+    repoFullName: z.string().optional(),
+    repoUrl: z.string().optional(),
+    repoAddedBy: z.string().optional().meta({
+        description: "User ID of whoever added the repository connection. Only changeable alongside `repoUrl` — it records who connected the current repo, so re-attributing it on its own would be inaccurate.",
+    }),
+    templateRepoUrl: z.string().optional(),
+    repoProvider: z.string().optional(),
+    repoPrivate: z.boolean().optional(),
+    repoDescription: z.string().optional(),
+    screenshot: z.string().nullish(),
+    isExample: z.boolean().optional(),
+    isPublic: z.boolean().optional(),
+    localPath: z.string().nullish(),
+    domains: z.array(z.string()).optional(),
+    accessMode: z.enum(["public", "private"]).optional(),
+    projectAccess: ProjectAccessControlSchema.optional(),
+    codeOnlyMode: z.boolean().optional(),
+    codeOnlyReason: ExitStateSchema.exclude(["verified"]).nullish().meta({
+        description: 'Setup-agent exit state that put the project in code-only mode. `null` clears it. Excludes "verified", which by definition is not a code-only outcome.',
+    }),
+    mobileOnlyDetected: z.boolean().optional(),
+    autoSetupStatus: z
+        .enum(["idle", "running", "needs-input", "completed", "error"])
+        .optional(),
+    userInitiatedAutoSetup: z.boolean().optional(),
+    autoApplySetup: z.boolean().optional(),
+    hidden: z.boolean().optional(),
+});
 /**
  * A single deploy record, stored at `deploys/{deployId}`. The Deploy.id is the document key.
  */