@danneillouven/remote-workspace 0.0.0-stage → 0.1.0

package/runtime/server/src/services.js

@@ -0,0 +1,35 @@
+import { AuthService } from "./modules/auth/auth-service.js";
+import { LoginLimiter } from "./modules/auth/login-limiter.js";
+import { SessionTokens } from "./modules/auth/session-tokens.js";
+import { CommitMessageGenerator } from "./modules/commit-message/commit-message-generator.js";
+import { LocalCommandRunner } from "./modules/exec/command-runner.js";
+import { HostService } from "./modules/hosts/host-service.js";
+import { TerminalManager } from "./modules/terminal/terminal-manager.js";
+import { WorkspaceRegistry } from "./modules/workspace/workspace-registry.js";
+export function createServices(config, store, logger, overrides = {}) {
+    const tokens = new SessionTokens(store, config.auth.sessionTtlMs, config.auth.sessionIdleMs);
+    const hosts = new HostService(store, config.ssh, logger);
+    // The terminal manager asks the registry for each project's PTY provider.
+    let workspaces = null;
+    const terminals = new TerminalManager((workspaceId) => {
+        if (!workspaces)
+            throw new Error('workspace registry not initialised');
+        return workspaces.ptyProvider(workspaceId);
+    }, config.terminal, logger);
+    workspaces = new WorkspaceRegistry(store, hosts, terminals, { limits: config.limits, workspace: config.workspace, term: config.terminal.term, ptyOverride: overrides.ptyProvider }, logger);
+    return {
+        store,
+        auth: new AuthService(store, tokens, logger, () => terminals.terminateAll()),
+        tokens,
+        limiter: new LoginLimiter(),
+        hosts,
+        workspaces,
+        terminals,
+        // AI CLIs run where the server runs, not on the project's host.
+        commitMessages: new CommitMessageGenerator(new LocalCommandRunner(), logger, undefined, config.aiCommitEnabled),
+        dispose() {
+            terminals.terminateAll();
+            hosts.dispose();
+        },
+    };
+}

package/runtime/src/schema/api.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+export const apiErrorCodeSchema = z.enum([
+    'BAD_REQUEST',
+    'UNAUTHORIZED',
+    'FORBIDDEN',
+    'NOT_FOUND',
+    'CONFLICT',
+    'SETUP_REQUIRED',
+    'PATH_OUTSIDE_WORKSPACE',
+    'PERMISSION_DENIED',
+    'NOT_A_DIRECTORY',
+    'NOT_A_FILE',
+    'REMOTE_UNAVAILABLE',
+    'TIMEOUT',
+    'NOT_A_REPOSITORY',
+    'GIT_ERROR',
+    'GENERATION_FAILED',
+    'TERMINAL_UNAVAILABLE',
+    'TERMINAL_LIMIT',
+    'SESSION_NOT_FOUND',
+    'TOO_MANY_REQUESTS',
+    'INTERNAL',
+]);
+// `code` stays a plain string on the client so unknown future codes still parse.
+export const apiErrorResponseSchema = z.looseObject({
+    error: z.looseObject({
+        code: z.string(),
+        message: z.string(),
+    }),
+});

package/runtime/src/schema/auth.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+const newPasswordSchema = z.string().min(12, 'Use at least 12 characters').max(1024);
+export const loginRequestSchema = z.object({
+    password: z.string().min(1, 'Password is required').max(1024),
+});
+export const sessionResponseSchema = z.looseObject({
+    authenticated: z.boolean(),
+    // True until the first password has been created (first-run onboarding).
+    setupRequired: z.boolean(),
+});
+export const setupRequestSchema = z.object({
+    // One-time token printed by the server on first start.
+    token: z.string().trim().min(1, 'Setup token is required').max(256),
+    password: newPasswordSchema,
+});
+export const changePasswordRequestSchema = z.object({
+    currentPassword: z.string().min(1, 'Current password is required').max(1024),
+    newPassword: newPasswordSchema,
+});
+export const signOutAllRequestSchema = z.object({ password: loginRequestSchema.shape.password });

package/runtime/src/schema/git.js

@@ -0,0 +1,233 @@
+import { z } from 'zod';
+import { workspacePathSchema } from "./workspace.js";
+export const gitChangeAreaSchema = z.enum(['staged', 'unstaged', 'untracked', 'conflicted']);
+export const gitChangeKindSchema = z.enum([
+    'modified',
+    'added',
+    'deleted',
+    'renamed',
+    'copied',
+    'type-changed',
+    'untracked',
+    'conflicted',
+]);
+export const gitChangeSchema = z.looseObject({
+    // Repository-root-relative path.
+    path: z.string(),
+    // Source path for renames and copies.
+    origPath: z.string().nullable(),
+    area: gitChangeAreaSchema,
+    kind: gitChangeKindSchema,
+    // Workspace-relative path (nested repositories included), or null when the file lies outside the project folder.
+    workspacePath: z.string().nullable(),
+    additions: z.number().nullable(),
+    deletions: z.number().nullable(),
+});
+export const gitRepositoryStatusSchema = z.looseObject({
+    // Workspace-relative path of the repository's top level; '' for the repository that contains the project folder.
+    path: z.string(),
+    branch: z.string().nullable(),
+    detached: z.boolean(),
+    commit: z.string().nullable(),
+    upstream: z.string().nullable(),
+    ahead: z.number(),
+    behind: z.number(),
+    changes: z.array(gitChangeSchema),
+    truncated: z.boolean(),
+    // Set when this repository could not be read; the other repositories are still reported.
+    error: z.string().nullable(),
+});
+export const gitStatusSchema = z.looseObject({
+    // The project's own repository first (if any), then nested repositories by path. Empty: no Git here.
+    repositories: z.array(gitRepositoryStatusSchema),
+    // More nested repositories exist than are reported.
+    repositoriesTruncated: z.boolean(),
+});
+export const gitDiffQuerySchema = z.object({
+    // Repository (GitRepositoryStatus.path); paths below are relative to it.
+    repo: workspacePathSchema.default(''),
+    path: workspacePathSchema.min(1),
+    area: gitChangeAreaSchema,
+    origPath: workspacePathSchema.min(1).optional(),
+});
+export const gitDiffSchema = z.looseObject({
+    repo: z.string(),
+    path: z.string(),
+    area: gitChangeAreaSchema,
+    diff: z.string(),
+    binary: z.boolean(),
+    truncated: z.boolean(),
+});
+// --- history (graph) ------------------------------------------------------------
+const commitHashSchema = z.string().regex(/^[0-9a-f]{7,64}$/, 'Invalid commit');
+export const gitLogQuerySchema = z.object({
+    repo: workspacePathSchema.default(''),
+    limit: z.coerce.number().int().min(1).max(1000).default(50),
+    // false: the current branch and its upstream (VS Code's "Auto"); true: all branches, remotes, and tags.
+    all: z
+        .enum(['true', 'false'])
+        .default('false')
+        .transform((value) => value === 'true'),
+});
+export const gitHistoryRefSchema = z.looseObject({
+    // Full ref name, e.g. refs/heads/main ("HEAD" when detached).
+    id: z.string(),
+    name: z.string(),
+    // head: the checked-out branch (or detached HEAD).
+    kind: z.enum(['head', 'branch', 'remote', 'tag']),
+});
+export const gitHistoryItemSchema = z.looseObject({
+    id: z.string(),
+    parentIds: z.array(z.string()),
+    subject: z.string(),
+    message: z.string(),
+    author: z.string(),
+    email: z.string(),
+    // Author date, Unix seconds.
+    timestamp: z.number(),
+    refs: z.array(gitHistoryRefSchema),
+});
+export const gitLogSchema = z.looseObject({
+    items: z.array(gitHistoryItemSchema),
+    hasMore: z.boolean(),
+    // Checked-out commit, its branch ref, and that branch's upstream ref (for graph colours).
+    head: z.string().nullable(),
+    headRef: z.string().nullable(),
+    upstreamRef: z.string().nullable(),
+});
+export const gitCommitQuerySchema = z.object({
+    repo: workspacePathSchema.default(''),
+    commit: commitHashSchema,
+});
+export const gitCommitFileSchema = z.looseObject({
+    path: z.string(),
+    origPath: z.string().nullable(),
+    kind: gitChangeKindSchema,
+    additions: z.number().nullable(),
+    deletions: z.number().nullable(),
+});
+export const gitCommitSchema = gitHistoryItemSchema.extend({
+    // Changes against the first parent (everything, for a root commit).
+    files: z.array(gitCommitFileSchema),
+    truncated: z.boolean(),
+});
+export const gitCommitDiffQuerySchema = gitCommitQuerySchema.extend({
+    path: workspacePathSchema.min(1),
+    origPath: workspacePathSchema.min(1).optional(),
+});
+export const gitCommitDiffSchema = z.looseObject({
+    repo: z.string(),
+    commit: z.string(),
+    path: z.string(),
+    diff: z.string(),
+    binary: z.boolean(),
+    truncated: z.boolean(),
+});
+// --- staging and committing ------------------------------------------------------
+export const gitRepoRequestSchema = z.object({
+    repo: workspacePathSchema.default(''),
+});
+export const gitPathsRequestSchema = gitRepoRequestSchema.extend({
+    // Repository-relative paths (include both sides of a rename).
+    paths: z.array(workspacePathSchema.min(1)).min(1).max(5000),
+});
+export const gitDiscardHunkRequestSchema = gitRepoRequestSchema.extend({
+    path: workspacePathSchema.min(1),
+    // One hunk of the file's working-tree diff, exactly as shown; it must still be part of the current diff.
+    hunk: z.string().min(1).max(1_000_000),
+});
+export const gitCommitRequestSchema = gitRepoRequestSchema
+    .extend({
+    // May be empty only when amending: the previous message is kept.
+    message: z.string().trim().max(20_000).default(''),
+    // Nothing staged: stage every change (tracked and untracked) first, like VS Code's smart commit.
+    stageAll: z.boolean().default(false),
+    // Stage every change first, even when something is already staged ("Commit All").
+    all: z.boolean().default(false),
+    amend: z.boolean().default(false),
+    signoff: z.boolean().default(false),
+})
+    .refine((request) => request.amend || request.message !== '', { message: 'Enter a commit message', path: ['message'] });
+export const gitCommitResultSchema = z.looseObject({
+    repo: z.string(),
+    commit: z.string(),
+});
+export const gitCommitMessageSchema = z.looseObject({
+    message: z.string(),
+    // AI CLI that wrote the message (codex, opencode, claude).
+    backend: z.string(),
+});
+// --- branches, remotes, stashes, tags (the "..." menu) ------------------------------
+// Branch and tag names: never option-like and nothing Git forbids in a ref (the server also runs check-ref-format).
+export const gitRefNameSchema = z
+    .string()
+    .trim()
+    .min(1, 'Enter a name')
+    .max(250)
+    .regex(/^(?!-)(?!.*(?:\.\.|@\{|\/\/|\.lock$|\/$|\.$|^\/))[^\s~^:?*[\\\u0000-\u001f\u007f]+$/, 'Not a valid Git name');
+export const gitRemoteNameSchema = z
+    .string()
+    .trim()
+    .min(1, 'Enter a remote name')
+    .max(100)
+    .regex(/^(?!-)[A-Za-z0-9._-]+$/, 'Use letters, digits, ".", "_" or "-"');
+// Network URLs or scp-like user@host:path; never Git's command-running transports (ext::, fd::).
+export const gitRemoteUrlSchema = z
+    .string()
+    .trim()
+    .max(2000)
+    .regex(/^(?:(?:https?|ssh|git):\/\/[^\s]+|[A-Za-z0-9._~-]+@[A-Za-z0-9.-]+:[^\s]+)$/, 'Enter an https://, ssh://, git:// or user@host:path URL');
+const stashIndexSchema = z.number().int().min(0).max(100_000);
+export const gitRefsSchema = z.looseObject({
+    branches: z.array(z.looseObject({
+        // Short name: main, origin/main.
+        name: z.string(),
+        remote: z.boolean(),
+        current: z.boolean(),
+        upstream: z.string().nullable(),
+    })),
+    // URLs have any user:password part removed.
+    remotes: z.array(z.looseObject({ name: z.string(), url: z.string().nullable() })),
+    tags: z.array(z.string()),
+    stashes: z.array(z.looseObject({ index: z.number(), hash: z.string(), message: z.string() })),
+});
+const repoShape = { repo: workspacePathSchema.default('') };
+/** One repository operation; every name is validated here and again by Git on the server. */
+export const gitOperationRequestSchema = z.discriminatedUnion('op', [
+    z.object({ ...repoShape, op: z.literal('fetch'), mode: z.enum(['default', 'prune', 'all']).default('default') }),
+    z.object({ ...repoShape, op: z.literal('pull'), rebase: z.boolean().default(false), remote: gitRemoteNameSchema.optional(), branch: gitRefNameSchema.optional() }),
+    // Without a remote: the upstream. With one: push the current branch there ("Push to...").
+    z.object({ ...repoShape, op: z.literal('push'), remote: gitRemoteNameSchema.optional() }),
+    z.object({ ...repoShape, op: z.literal('publish'), remote: gitRemoteNameSchema }),
+    // Pull, then push.
+    z.object({ ...repoShape, op: z.literal('sync') }),
+    // remote: `ref` is a remote branch (origin/x); a local tracking branch is created or reused.
+    z.object({ ...repoShape, op: z.literal('checkout'), ref: gitRefNameSchema, remote: z.boolean().default(false) }),
+    z.object({ ...repoShape, op: z.literal('createBranch'), name: gitRefNameSchema, from: gitRefNameSchema.optional() }),
+    z.object({ ...repoShape, op: z.literal('renameBranch'), name: gitRefNameSchema }),
+    z.object({ ...repoShape, op: z.literal('deleteBranch'), name: gitRefNameSchema, force: z.boolean().default(false) }),
+    z.object({ ...repoShape, op: z.literal('deleteRemoteBranch'), remote: gitRemoteNameSchema, name: gitRefNameSchema }),
+    z.object({ ...repoShape, op: z.literal('merge'), ref: gitRefNameSchema }),
+    z.object({ ...repoShape, op: z.literal('rebase'), ref: gitRefNameSchema }),
+    z.object({ ...repoShape, op: z.literal('abortRebase') }),
+    z.object({ ...repoShape, op: z.literal('undoCommit') }),
+    z.object({ ...repoShape, op: z.literal('stageAll') }),
+    z.object({ ...repoShape, op: z.literal('unstageAll') }),
+    // Working-tree changes and untracked files; staged changes are kept.
+    z.object({ ...repoShape, op: z.literal('discardAll') }),
+    z.object({ ...repoShape, op: z.literal('addRemote'), name: gitRemoteNameSchema, url: gitRemoteUrlSchema }),
+    z.object({ ...repoShape, op: z.literal('removeRemote'), name: gitRemoteNameSchema }),
+    z.object({ ...repoShape, op: z.literal('stash'), mode: z.enum(['default', 'untracked', 'staged']).default('default'), message: z.string().trim().max(500).default('') }),
+    // Without an index: the latest stash.
+    z.object({ ...repoShape, op: z.literal('stashApply'), index: stashIndexSchema.optional(), pop: z.boolean().default(false) }),
+    z.object({ ...repoShape, op: z.literal('stashDrop'), index: stashIndexSchema }),
+    z.object({ ...repoShape, op: z.literal('stashClear') }),
+    // With a message: an annotated tag.
+    z.object({ ...repoShape, op: z.literal('createTag'), name: gitRefNameSchema, message: z.string().trim().max(5000).default('') }),
+    z.object({ ...repoShape, op: z.literal('deleteTag'), name: gitRefNameSchema }),
+    z.object({ ...repoShape, op: z.literal('deleteRemoteTag'), remote: gitRemoteNameSchema, name: gitRefNameSchema }),
+]);
+export const gitOperationResultSchema = z.looseObject({
+    // "Undo Last Commit": the undone commit's message, to put back into the message box.
+    commitMessage: z.string().nullable(),
+});

package/runtime/src/schema/hosts.js

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+import { connectionStatusSchema } from "./workspace.js";
+// --- inputs -------------------------------------------------------------------
+export const hostAddressSchema = z
+    .string()
+    .trim()
+    .min(1, 'Host is required')
+    .max(253)
+    .regex(/^[A-Za-z0-9._:%-]+$/, 'Use a host name, MagicDNS name, or IP address')
+    .refine((value) => !value.startsWith('-'), 'Host must not start with "-"');
+export const sshPortSchema = z.number().int().min(1).max(65_535);
+export const sshUsernameSchema = z
+    .string()
+    .trim()
+    .min(1, 'Username is required')
+    .max(64)
+    .regex(/^[A-Za-z0-9._][A-Za-z0-9._@-]*$/, 'Invalid username');
+export const hostNameSchema = z.string().trim().min(1, 'Name is required').max(60);
+export const hostProbeRequestSchema = z.object({
+    host: hostAddressSchema,
+    port: sshPortSchema.default(22),
+});
+/** A host public key the user has explicitly chosen to trust (from a probe). Public data, not a secret. */
+export const trustedHostKeySchema = z.object({
+    keyType: z.string().regex(/^[a-z0-9@.-]{3,64}$/),
+    key: z.string().max(8192).regex(/^[A-Za-z0-9+/]+={0,2}$/, 'Invalid host key'),
+});
+export const hostAuthInputSchema = z.discriminatedUnion('type', [
+    // The SSH password, used once to sign in and install a generated key; never stored.
+    z.object({ type: z.literal('password'), password: z.string().min(1, 'Enter the SSH password').max(1024) }),
+    // A new ed25519 key generated and stored by the server; only the public half is ever returned.
+    z.object({ type: z.literal('generate') }),
+    // An existing unencrypted private key, sent once and stored server-side (never returned).
+    z.object({ type: z.literal('import'), privateKey: z.string().min(1, 'Paste a private key').max(16_384) }),
+    // A key file that already exists on the machine running the server.
+    z.object({
+        type: z.literal('key-file'),
+        path: z
+            .string()
+            .trim()
+            .max(4096)
+            .refine((value) => value.startsWith('/') || value.startsWith('~/'), 'Use an absolute path or ~/…'),
+    }),
+    // The ssh-agent available to the server process (SSH_AUTH_SOCK).
+    z.object({ type: z.literal('agent') }),
+]);
+export const createHostRequestSchema = z.object({
+    name: hostNameSchema,
+    host: hostAddressSchema,
+    port: sshPortSchema.default(22),
+    username: sshUsernameSchema,
+    hostKey: trustedHostKeySchema,
+    auth: hostAuthInputSchema,
+});
+export const updateHostRequestSchema = z.object({
+    name: hostNameSchema.optional(),
+    host: hostAddressSchema.optional(),
+    port: sshPortSchema.optional(),
+    username: sshUsernameSchema.optional(),
+    // Required whenever host or port changes.
+    hostKey: trustedHostKeySchema.optional(),
+    // Omit to keep the current credentials.
+    auth: hostAuthInputSchema.optional(),
+});
+export const hostIdParamsSchema = z.object({
+    hostId: z.uuid(),
+});
+export const browseQuerySchema = z.object({
+    // A host id, or "local" for the machine running the server.
+    host: z.union([z.literal('local'), z.uuid()]),
+    // Absolute directory; defaults to the home directory.
+    path: z
+        .string()
+        .max(4096)
+        .refine((value) => value.startsWith('/') && !value.includes('\0'), 'Use an absolute path')
+        .optional(),
+});
+// --- responses ----------------------------------------------------------------
+export const hostKeyStatusSchema = z.enum(['trusted', 'unknown', 'mismatch', 'revoked']);
+export const hostKeyProbeSchema = z.looseObject({
+    keyType: z.string(),
+    key: z.string(),
+    fingerprint: z.string(),
+    // What the server's known_hosts file says about this key.
+    knownHosts: hostKeyStatusSchema,
+});
+export const hostAuthSummarySchema = z.discriminatedUnion('type', [
+    // source "password": generated and installed automatically using the SSH password.
+    z.looseObject({ type: z.literal('managed-key'), source: z.enum(['generated', 'imported', 'password']), publicKey: z.string() }),
+    z.looseObject({ type: z.literal('key-file'), path: z.string() }),
+    z.looseObject({ type: z.literal('agent') }),
+]);
+export const hostSummarySchema = z.looseObject({
+    id: z.string(),
+    name: z.string(),
+    host: z.string(),
+    port: z.number(),
+    username: z.string(),
+    auth: hostAuthSummarySchema,
+    hostKey: z.looseObject({ keyType: z.string(), fingerprint: z.string() }),
+    connection: z.looseObject({ status: connectionStatusSchema, error: z.string().nullable() }),
+    createdAt: z.string(),
+});
+export const hostListSchema = z.looseObject({
+    hosts: z.array(hostSummarySchema),
+    // Whether the server process can use an ssh-agent.
+    agentAvailable: z.boolean(),
+});
+export const browseResponseSchema = z.looseObject({
+    roots: z.array(z.string()).optional(),
+    path: z.string(),
+    parent: z.string().nullable(),
+    entries: z.array(z.looseObject({ name: z.string(), path: z.string() })),
+    truncated: z.boolean(),
+});

package/runtime/src/schema/terminal.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+// Terminal WebSocket protocol. Control messages are JSON text frames;
+// terminal output is sent server → client as raw binary frames.
+const dimensionsShape = {
+    cols: z.number().int().min(2).max(1000),
+    rows: z.number().int().min(1).max(500),
+};
+export const terminalClientMessageSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('create'), workspaceId: z.uuid(), ...dimensionsShape }),
+    z.object({ type: z.literal('attach'), sessionId: z.uuid(), ...dimensionsShape }),
+    z.object({ type: z.literal('input'), data: z.string().max(65_536) }),
+    z.object({ type: z.literal('resize'), ...dimensionsShape }),
+    // Explicitly terminate the remote shell (tab closed by the user).
+    z.object({ type: z.literal('terminate') }),
+]);
+export const terminalServerMessageSchema = z.discriminatedUnion('type', [
+    z.looseObject({
+        type: z.literal('ready'),
+        sessionId: z.string(),
+        // True when buffered output follows; the client should reset its screen first.
+        replay: z.boolean(),
+    }),
+    z.looseObject({
+        type: z.literal('exit'),
+        exitCode: z.number().nullable(),
+        signal: z.string().nullable(),
+    }),
+    z.looseObject({
+        type: z.literal('error'),
+        code: z.string(),
+        message: z.string(),
+    }),
+    // Another client attached to this session; this socket is about to close.
+    z.looseObject({ type: z.literal('detached') }),
+]);
+export const terminalSessionSchema = z.looseObject({
+    id: z.string(),
+    workspaceId: z.string(),
+    status: z.enum(['running', 'exited']),
+    attached: z.boolean(),
+    createdAt: z.string(),
+});
+export const terminalSessionListSchema = z.looseObject({
+    sessions: z.array(terminalSessionSchema),
+});
+export const terminalSessionParamsSchema = z.object({
+    id: z.uuid(),
+});

package/runtime/src/schema/workspace.js

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+// Workspace-relative POSIX path; '' is the workspace root. The server
+// normalizes and enforces containment — this only rejects malformed input.
+export const workspacePathSchema = z
+    .string()
+    .max(4096)
+    .refine((value) => !value.includes('\0'), 'Path must not contain NUL bytes');
+export const connectionStatusSchema = z.enum(['idle', 'connecting', 'connected', 'error']);
+export const absolutePathSchema = z
+    .string()
+    .trim()
+    .min(1, 'Path is required')
+    .max(4096)
+    .refine((value) => value.startsWith('/') && !value.includes('\0'), 'Use an absolute path');
+export const workspaceIdParamsSchema = z.object({
+    workspaceId: z.uuid(),
+});
+export const MAX_PORT_LINKS = 20;
+// A web server port on the project's host, opened in a new browser tab.
+export const portLinkSchema = z.object({
+    port: z.number().int().min(1, 'Use a port from 1 to 65535').max(65535, 'Use a port from 1 to 65535'),
+    label: z.string().trim().max(40),
+    https: z.boolean().default(false),
+});
+export const portLinksSchema = z
+    .array(portLinkSchema)
+    .max(MAX_PORT_LINKS)
+    .refine((links) => new Set(links.map((link) => link.port)).size === links.length, 'Each port can be saved once');
+export const workspaceSummarySchema = z.looseObject({
+    id: z.string(),
+    name: z.string(),
+    // null: the machine running the server (file operations only).
+    hostId: z.string().nullable(),
+    root: z.string(),
+    ports: z.array(portLinkSchema.loose()).default([]),
+    createdAt: z.string(),
+});
+export const workspaceListSchema = z.looseObject({
+    workspaces: z.array(workspaceSummarySchema),
+});
+export const createWorkspaceRequestSchema = z.object({
+    name: z.string().trim().max(60).optional(),
+    hostId: z.uuid().nullable(),
+    root: absolutePathSchema,
+});
+export const updateWorkspaceRequestSchema = z.object({
+    name: z.string().trim().min(1, 'Name is required').max(60).optional(),
+    root: absolutePathSchema.optional(),
+    ports: portLinksSchema.optional(),
+});
+export const workspaceInfoSchema = z.looseObject({
+    id: z.string(),
+    name: z.string(),
+    root: z.string(),
+    backend: z.enum(['ssh', 'local']),
+    hostId: z.string().nullable(),
+    // Display name of the host and its user@address label.
+    hostName: z.string().nullable(),
+    host: z.string().nullable(),
+    // Bare host address (no user or SSH port) for links to web servers on it; null: the machine running the server.
+    address: z.string().nullable(),
+    ports: z.array(portLinkSchema.loose()).default([]),
+    connection: z.looseObject({
+        status: connectionStatusSchema,
+        error: z.string().nullable(),
+    }),
+    terminalsAvailable: z.boolean(),
+    limits: z.looseObject({
+        maxFileBytes: z.number(),
+    }),
+});
+export const pathQuerySchema = z.object({
+    path: workspacePathSchema.default(''),
+});
+export const dirEntrySchema = z.looseObject({
+    name: z.string(),
+    path: z.string(),
+    // For symlinks, `type` describes the link target ('other' when broken).
+    type: z.enum(['file', 'directory', 'other']),
+    isSymlink: z.boolean(),
+    size: z.number().nullable(),
+    mtimeMs: z.number().nullable(),
+});
+export const directoryListingSchema = z.looseObject({
+    path: z.string(),
+    entries: z.array(dirEntrySchema),
+    truncated: z.boolean(),
+});
+export const fileContentSchema = z.discriminatedUnion('kind', [
+    z.looseObject({
+        kind: z.literal('text'),
+        path: z.string(),
+        content: z.string(),
+        size: z.number(),
+        mtimeMs: z.number().nullable(),
+        // True when the file was not valid UTF-8 and was decoded with replacements.
+        hasDecodingErrors: z.boolean(),
+    }),
+    z.looseObject({
+        kind: z.literal('binary'),
+        path: z.string(),
+        size: z.number(),
+        mtimeMs: z.number().nullable(),
+    }),
+    z.looseObject({
+        kind: z.literal('too-large'),
+        path: z.string(),
+        size: z.number(),
+        mtimeMs: z.number().nullable(),
+        limit: z.number(),
+    }),
+]);
+export const writeFileRequestSchema = z.object({
+    path: workspacePathSchema.min(1),
+    content: z.string(),
+    // mtimeMs of the version the edit started from; a mismatch is a CONFLICT. null skips the check (overwrite).
+    expectedMtimeMs: z.number().nullable(),
+});
+/** Download a file instead of previewing it (any regular file; previews are limited to media types). */
+export const rawFileQuerySchema = pathQuerySchema.extend({
+    download: z.enum(['0', '1']).optional(),
+});
+// A single file or folder name, as typed when creating or renaming.
+export const entryNameSchema = z
+    .string()
+    .trim()
+    .min(1, 'Name is required')
+    .max(255, 'Name is too long')
+    .refine((value) => !value.includes('/') && !value.includes('\0'), 'Name must not contain "/"')
+    .refine((value) => value !== '.' && value !== '..', 'Name must not be "." or ".."');
+export const createEntryRequestSchema = z.object({
+    // May include missing parent folders ("src/new/file.ts").
+    path: workspacePathSchema.min(1),
+    type: z.enum(['file', 'directory']),
+});
+// Copy or move `path` into the folder `destination` ('' = the project root).
+export const transferEntryRequestSchema = z.object({
+    path: workspacePathSchema.min(1),
+    destination: workspacePathSchema,
+});
+export const renameEntryRequestSchema = z.object({
+    path: workspacePathSchema.min(1),
+    name: entryNameSchema,
+});
+export const deleteEntryRequestSchema = z.object({
+    path: workspacePathSchema.min(1),
+});
+/** Where the entry ended up (copies get a free name like "file copy.txt"). */
+export const entryResultSchema = z.looseObject({
+    path: z.string(),
+});