corporateai 0.0.1

package/server/src/ui-branding.ts

@@ -0,0 +1,217 @@
+const FAVICON_BLOCK_START = "<!-- PAPERCLIP_FAVICON_START -->";
+const FAVICON_BLOCK_END = "<!-- PAPERCLIP_FAVICON_END -->";
+const RUNTIME_BRANDING_BLOCK_START = "<!-- PAPERCLIP_RUNTIME_BRANDING_START -->";
+const RUNTIME_BRANDING_BLOCK_END = "<!-- PAPERCLIP_RUNTIME_BRANDING_END -->";
+
+const DEFAULT_FAVICON_LINKS = [
+  '<link rel="icon" href="/favicon.ico" sizes="48x48" />',
+  '<link rel="icon" href="/favicon.svg" type="image/svg+xml" />',
+  '<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />',
+  '<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />',
+].join("\n");
+
+export type WorktreeUiBranding = {
+  enabled: boolean;
+  name: string | null;
+  color: string | null;
+  textColor: string | null;
+  faviconHref: string | null;
+};
+
+function isTruthyEnvValue(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
+function nonEmpty(value: string | undefined): string | null {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizeHexColor(value: string | undefined): string | null {
+  const raw = nonEmpty(value);
+  if (!raw) return null;
+  const hex = raw.startsWith("#") ? raw.slice(1) : raw;
+  if (/^[0-9a-fA-F]{3}$/.test(hex)) {
+    return `#${hex.split("").map((char) => `${char}${char}`).join("").toLowerCase()}`;
+  }
+  if (/^[0-9a-fA-F]{6}$/.test(hex)) {
+    return `#${hex.toLowerCase()}`;
+  }
+  return null;
+}
+
+function hslComponentToHex(n: number): string {
+  return Math.round(Math.max(0, Math.min(255, n)))
+    .toString(16)
+    .padStart(2, "0");
+}
+
+function hslToHex(hue: number, saturation: number, lightness: number): string {
+  const s = Math.max(0, Math.min(100, saturation)) / 100;
+  const l = Math.max(0, Math.min(100, lightness)) / 100;
+  const c = (1 - Math.abs((2 * l) - 1)) * s;
+  const h = ((hue % 360) + 360) % 360;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - (c / 2);
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+
+  if (h < 60) {
+    r = c;
+    g = x;
+  } else if (h < 120) {
+    r = x;
+    g = c;
+  } else if (h < 180) {
+    g = c;
+    b = x;
+  } else if (h < 240) {
+    g = x;
+    b = c;
+  } else if (h < 300) {
+    r = x;
+    b = c;
+  } else {
+    r = c;
+    b = x;
+  }
+
+  return `#${hslComponentToHex((r + m) * 255)}${hslComponentToHex((g + m) * 255)}${hslComponentToHex((b + m) * 255)}`;
+}
+
+function deriveColorFromSeed(seed: string): string {
+  let hash = 0;
+  for (const char of seed) {
+    hash = ((hash * 33) + char.charCodeAt(0)) >>> 0;
+  }
+  return hslToHex(hash % 360, 68, 56);
+}
+
+function hexToRgb(color: string): { r: number; g: number; b: number } {
+  const normalized = normalizeHexColor(color) ?? "#000000";
+  return {
+    r: Number.parseInt(normalized.slice(1, 3), 16),
+    g: Number.parseInt(normalized.slice(3, 5), 16),
+    b: Number.parseInt(normalized.slice(5, 7), 16),
+  };
+}
+
+function relativeLuminanceChannel(value: number): number {
+  const normalized = value / 255;
+  return normalized <= 0.03928 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
+}
+
+function relativeLuminance(color: string): number {
+  const { r, g, b } = hexToRgb(color);
+  return (
+    (0.2126 * relativeLuminanceChannel(r)) +
+    (0.7152 * relativeLuminanceChannel(g)) +
+    (0.0722 * relativeLuminanceChannel(b))
+  );
+}
+
+function pickReadableTextColor(background: string): string {
+  const backgroundLuminance = relativeLuminance(background);
+  const whiteContrast = 1.05 / (backgroundLuminance + 0.05);
+  const blackContrast = (backgroundLuminance + 0.05) / 0.05;
+  return whiteContrast >= blackContrast ? "#f8fafc" : "#111827";
+}
+
+function escapeHtmlAttribute(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+function createFaviconDataUrl(background: string, foreground: string): string {
+  const svg = [
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">',
+    `<rect width="24" height="24" rx="6" fill="${background}"/>`,
+    `<path stroke="${foreground}" stroke-linecap="round" stroke-linejoin="round" stroke-width="2.15" d="m16 6-8.414 8.586a2 2 0 0 0 2.829 2.829l8.414-8.586a4 4 0 1 0-5.657-5.657l-8.379 8.551a6 6 0 1 0 8.485 8.485l8.379-8.551"/>`,
+    "</svg>",
+  ].join("");
+  return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}
+
+export function isWorktreeUiBrandingEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return isTruthyEnvValue(env.PAPERCLIP_IN_WORKTREE);
+}
+
+export function getWorktreeUiBranding(env: NodeJS.ProcessEnv = process.env): WorktreeUiBranding {
+  if (!isWorktreeUiBrandingEnabled(env)) {
+    return {
+      enabled: false,
+      name: null,
+      color: null,
+      textColor: null,
+      faviconHref: null,
+    };
+  }
+
+  const name = nonEmpty(env.PAPERCLIP_WORKTREE_NAME) ?? nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? "worktree";
+  const color = normalizeHexColor(env.PAPERCLIP_WORKTREE_COLOR) ?? deriveColorFromSeed(name);
+  const textColor = pickReadableTextColor(color);
+
+  return {
+    enabled: true,
+    name,
+    color,
+    textColor,
+    faviconHref: createFaviconDataUrl(color, textColor),
+  };
+}
+
+export function renderFaviconLinks(branding: WorktreeUiBranding): string {
+  if (!branding.enabled || !branding.faviconHref) return DEFAULT_FAVICON_LINKS;
+
+  const href = escapeHtmlAttribute(branding.faviconHref);
+  return [
+    `<link rel="icon" href="${href}" type="image/svg+xml" sizes="any" />`,
+    `<link rel="shortcut icon" href="${href}" type="image/svg+xml" />`,
+  ].join("\n");
+}
+
+export function renderRuntimeBrandingMeta(branding: WorktreeUiBranding): string {
+  if (!branding.enabled || !branding.name || !branding.color || !branding.textColor) return "";
+
+  return [
+    '<meta name="paperclip-worktree-enabled" content="true" />',
+    `<meta name="paperclip-worktree-name" content="${escapeHtmlAttribute(branding.name)}" />`,
+    `<meta name="paperclip-worktree-color" content="${escapeHtmlAttribute(branding.color)}" />`,
+    `<meta name="paperclip-worktree-text-color" content="${escapeHtmlAttribute(branding.textColor)}" />`,
+  ].join("\n");
+}
+
+function replaceMarkedBlock(html: string, startMarker: string, endMarker: string, content: string): string {
+  const start = html.indexOf(startMarker);
+  const end = html.indexOf(endMarker);
+  if (start === -1 || end === -1 || end < start) return html;
+
+  const before = html.slice(0, start + startMarker.length);
+  const after = html.slice(end);
+  const indentedContent = content
+    ? `\n${content
+      .split("\n")
+      .map((line) => `    ${line}`)
+      .join("\n")}\n    `
+    : "\n    ";
+  return `${before}${indentedContent}${after}`;
+}
+
+export function applyUiBranding(html: string, env: NodeJS.ProcessEnv = process.env): string {
+  const branding = getWorktreeUiBranding(env);
+  const withFavicon = replaceMarkedBlock(html, FAVICON_BLOCK_START, FAVICON_BLOCK_END, renderFaviconLinks(branding));
+  return replaceMarkedBlock(
+    withFavicon,
+    RUNTIME_BRANDING_BLOCK_START,
+    RUNTIME_BRANDING_BLOCK_END,
+    renderRuntimeBrandingMeta(branding),
+  );
+}

package/server/src/version.ts

@@ -0,0 +1,10 @@
+import { createRequire } from "node:module";
+
+type PackageJson = {
+  version?: string;
+};
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json") as PackageJson;
+
+export const serverVersion = pkg.version ?? "0.0.0";

package/server/src/worktree-config.ts

@@ -0,0 +1,468 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { PaperclipConfig } from "@corporateai/shared";
+import { resolvePaperclipConfigPath, resolvePaperclipEnvPath } from "./paths.js";
+
+function nonEmpty(value: string | null | undefined): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function expandHomePrefix(value: string): string {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
+  return value;
+}
+
+function resolveHomeAwarePath(value: string): string {
+  return path.resolve(expandHomePrefix(value));
+}
+
+function sanitizeWorktreeInstanceId(rawValue: string): string {
+  const trimmed = rawValue.trim().toLowerCase();
+  const normalized = trimmed
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-_]+|[-_]+$/g, "");
+  return normalized || "worktree";
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  const value = hostname.trim().toLowerCase();
+  return value === "127.0.0.1" || value === "localhost" || value === "::1";
+}
+
+function rewriteLocalUrlPort(rawUrl: string | undefined, port: number): string | undefined {
+  if (!rawUrl) return undefined;
+  try {
+    const parsed = new URL(rawUrl);
+    if (!isLoopbackHost(parsed.hostname)) return rawUrl;
+    parsed.port = String(port);
+    return parsed.toString();
+  } catch {
+    return rawUrl;
+  }
+}
+
+function parseEnvFile(contents: string): Record<string, string> {
+  const entries: Record<string, string> = {};
+
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const match = rawLine.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+    if (!match) continue;
+
+    const [, key, rawValue] = match;
+    const value = rawValue.trim();
+    if (!value) {
+      entries[key] = "";
+      continue;
+    }
+
+    if (
+      (value.startsWith("\"") && value.endsWith("\"")) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      entries[key] = value.slice(1, -1);
+      continue;
+    }
+
+    entries[key] = value.replace(/\s+#.*$/, "").trim();
+  }
+
+  return entries;
+}
+
+function readEnvEntries(envPath: string): Record<string, string> {
+  if (!fs.existsSync(envPath)) return {};
+  return parseEnvFile(fs.readFileSync(envPath, "utf8"));
+}
+
+function formatEnvEntries(entries: Record<string, string>): string {
+  return [
+    "# Paperclip environment variables",
+    "# Generated by Paperclip worktree repair",
+    ...Object.entries(entries).map(([key, value]) => `${key}=${JSON.stringify(value)}`),
+    "",
+  ].join("\n");
+}
+
+function isPathInside(candidatePath: string, rootPath: string): boolean {
+  const candidate = path.resolve(candidatePath);
+  const root = path.resolve(rootPath);
+  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+
+type WorktreeRuntimeContext = {
+  configPath: string;
+  envPath: string;
+  worktreeName: string;
+  instanceId: string;
+  homeDir: string;
+  instanceRoot: string;
+  contextPath: string;
+  embeddedPostgresDataDir: string;
+  backupDir: string;
+  logDir: string;
+  storageDir: string;
+  secretsKeyFilePath: string;
+};
+
+function resolveWorktreeRuntimeContext(
+  env: NodeJS.ProcessEnv,
+  overrideConfigPath?: string,
+): WorktreeRuntimeContext | null {
+  if (env.PAPERCLIP_IN_WORKTREE !== "true") return null;
+
+  const configPath = resolvePaperclipConfigPath(overrideConfigPath);
+  const envPath = resolvePaperclipEnvPath(configPath);
+  const worktreeRoot = path.resolve(path.dirname(configPath), "..");
+  const worktreeName = nonEmpty(env.PAPERCLIP_WORKTREE_NAME) ?? path.basename(worktreeRoot);
+  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? sanitizeWorktreeInstanceId(worktreeName);
+  const homeDir = resolveHomeAwarePath(
+    nonEmpty(env.PAPERCLIP_HOME) ??
+      nonEmpty(env.PAPERCLIP_WORKTREES_DIR) ??
+      "~/.paperclip-worktrees",
+  );
+  const instanceRoot = path.resolve(homeDir, "instances", instanceId);
+
+  return {
+    configPath,
+    envPath,
+    worktreeName,
+    instanceId,
+    homeDir,
+    instanceRoot,
+    contextPath: path.resolve(homeDir, "context.json"),
+    embeddedPostgresDataDir: path.resolve(instanceRoot, "db"),
+    backupDir: path.resolve(instanceRoot, "data", "backups"),
+    logDir: path.resolve(instanceRoot, "logs"),
+    storageDir: path.resolve(instanceRoot, "data", "storage"),
+    secretsKeyFilePath: path.resolve(instanceRoot, "secrets", "master.key"),
+  };
+}
+
+function writeConfigFile(configPath: string, config: PaperclipConfig): void {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}
+
+function resolveRepoManagedWorktreesRoot(worktreeRoot: string): string | null {
+  const normalized = path.resolve(worktreeRoot);
+  const marker = `${path.sep}.paperclip${path.sep}worktrees${path.sep}`;
+  const index = normalized.indexOf(marker);
+  if (index === -1) return null;
+  const repoRoot = normalized.slice(0, index);
+  return path.resolve(repoRoot, ".paperclip", "worktrees");
+}
+
+function collectSiblingWorktreePorts(context: WorktreeRuntimeContext): {
+  serverPorts: Set<number>;
+  databasePorts: Set<number>;
+} {
+  const serverPorts = new Set<number>();
+  const databasePorts = new Set<number>();
+  const siblingConfigPaths = new Set<string>();
+  const instancesDir = path.resolve(context.homeDir, "instances");
+  if (fs.existsSync(instancesDir)) {
+    for (const entry of fs.readdirSync(instancesDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === context.instanceId) continue;
+
+      const siblingConfigPath = path.resolve(instancesDir, entry.name, "config.json");
+      if (fs.existsSync(siblingConfigPath)) {
+        siblingConfigPaths.add(siblingConfigPath);
+      }
+    }
+  }
+
+  const repoManagedWorktreesRoot = resolveRepoManagedWorktreesRoot(path.dirname(context.configPath));
+  if (repoManagedWorktreesRoot && fs.existsSync(repoManagedWorktreesRoot)) {
+    for (const entry of fs.readdirSync(repoManagedWorktreesRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+
+      const siblingConfigPath = path.resolve(repoManagedWorktreesRoot, entry.name, ".paperclip", "config.json");
+      if (path.resolve(siblingConfigPath) === path.resolve(context.configPath)) continue;
+      if (fs.existsSync(siblingConfigPath)) {
+        siblingConfigPaths.add(siblingConfigPath);
+      }
+    }
+  }
+
+  for (const siblingConfigPath of siblingConfigPaths) {
+    try {
+      const siblingConfig = JSON.parse(fs.readFileSync(siblingConfigPath, "utf8")) as PaperclipConfig;
+      if (Number.isInteger(siblingConfig.server.port) && siblingConfig.server.port > 0) {
+        serverPorts.add(siblingConfig.server.port);
+      }
+      if (
+        siblingConfig.database.mode === "embedded-postgres" &&
+        Number.isInteger(siblingConfig.database.embeddedPostgresPort) &&
+        siblingConfig.database.embeddedPostgresPort > 0
+      ) {
+        databasePorts.add(siblingConfig.database.embeddedPostgresPort);
+      }
+    } catch {
+      // Ignore sibling configs that are missing or malformed.
+    }
+  }
+
+  return { serverPorts, databasePorts };
+}
+
+function findNextUnclaimedPort(preferredPort: number, claimedPorts: Set<number>): number {
+  let port = Math.max(1, Math.trunc(preferredPort));
+  while (claimedPorts.has(port)) {
+    port += 1;
+  }
+  return port;
+}
+
+function buildIsolatedWorktreeConfig(
+  config: PaperclipConfig,
+  context: WorktreeRuntimeContext,
+  portOverrides?: {
+    serverPort?: number;
+    databasePort?: number;
+  },
+): PaperclipConfig {
+  const serverPort = portOverrides?.serverPort ?? config.server.port;
+  const databasePort =
+    config.database.mode === "embedded-postgres"
+      ? portOverrides?.databasePort ?? config.database.embeddedPostgresPort
+      : undefined;
+  const nextConfig: PaperclipConfig = {
+    ...config,
+    database: {
+      ...config.database,
+      ...(config.database.mode === "embedded-postgres"
+        ? {
+            embeddedPostgresDataDir: context.embeddedPostgresDataDir,
+            embeddedPostgresPort: databasePort ?? config.database.embeddedPostgresPort,
+            backup: {
+              ...config.database.backup,
+              dir: context.backupDir,
+            },
+          }
+        : {}),
+    },
+    server: {
+      ...config.server,
+      port: serverPort,
+    },
+    logging: {
+      ...config.logging,
+      logDir: context.logDir,
+    },
+    storage: {
+      ...config.storage,
+      localDisk: {
+        ...config.storage.localDisk,
+        baseDir: context.storageDir,
+      },
+    },
+    secrets: {
+      ...config.secrets,
+      localEncrypted: {
+        ...config.secrets.localEncrypted,
+        keyFilePath: context.secretsKeyFilePath,
+      },
+    },
+  };
+
+  if (config.auth.baseUrlMode === "explicit" && config.auth.publicBaseUrl) {
+    nextConfig.auth = {
+      ...config.auth,
+      publicBaseUrl: rewriteLocalUrlPort(config.auth.publicBaseUrl, serverPort),
+    };
+  }
+
+  return nextConfig;
+}
+
+function needsWorktreeConfigRepair(
+  config: PaperclipConfig,
+  context: WorktreeRuntimeContext,
+): boolean {
+  if (config.database.mode === "embedded-postgres") {
+    if (!isPathInside(config.database.embeddedPostgresDataDir, context.instanceRoot)) {
+      return true;
+    }
+    if (!isPathInside(config.database.backup.dir, context.instanceRoot)) {
+      return true;
+    }
+  }
+
+  if (!isPathInside(config.logging.logDir, context.instanceRoot)) {
+    return true;
+  }
+  if (!isPathInside(config.storage.localDisk.baseDir, context.instanceRoot)) {
+    return true;
+  }
+  if (!isPathInside(config.secrets.localEncrypted.keyFilePath, context.instanceRoot)) {
+    return true;
+  }
+
+  return false;
+}
+
+export function applyRuntimePortSelectionToConfig(
+  config: PaperclipConfig,
+  input: {
+    serverPort: number;
+    databasePort?: number | null;
+    allowServerPortWrite?: boolean;
+    allowDatabasePortWrite?: boolean;
+  },
+): { config: PaperclipConfig; changed: boolean } {
+  let changed = false;
+  let nextConfig = config;
+
+  if (input.allowServerPortWrite !== false && config.server.port !== input.serverPort) {
+    nextConfig = {
+      ...nextConfig,
+      server: {
+        ...nextConfig.server,
+        port: input.serverPort,
+      },
+    };
+    changed = true;
+  }
+
+  if (
+    input.allowDatabasePortWrite !== false &&
+    nextConfig.database.mode === "embedded-postgres" &&
+    typeof input.databasePort === "number" &&
+    nextConfig.database.embeddedPostgresPort !== input.databasePort
+  ) {
+    nextConfig = {
+      ...nextConfig,
+      database: {
+        ...nextConfig.database,
+        embeddedPostgresPort: input.databasePort,
+      },
+    };
+    changed = true;
+  }
+
+  if (nextConfig.auth.baseUrlMode === "explicit" && nextConfig.auth.publicBaseUrl) {
+    const rewritten = rewriteLocalUrlPort(nextConfig.auth.publicBaseUrl, input.serverPort);
+    if (rewritten && rewritten !== nextConfig.auth.publicBaseUrl) {
+      nextConfig = {
+        ...nextConfig,
+        auth: {
+          ...nextConfig.auth,
+          publicBaseUrl: rewritten,
+        },
+      };
+      changed = true;
+    }
+  }
+
+  return { config: nextConfig, changed };
+}
+
+export function maybeRepairLegacyWorktreeConfigAndEnvFiles(): {
+  repairedConfig: boolean;
+  repairedEnv: boolean;
+} {
+  const context = resolveWorktreeRuntimeContext(process.env);
+  if (!context) {
+    return { repairedConfig: false, repairedEnv: false };
+  }
+
+  process.env.PAPERCLIP_HOME = context.homeDir;
+  process.env.PAPERCLIP_INSTANCE_ID = context.instanceId;
+  process.env.PAPERCLIP_CONFIG = context.configPath;
+  process.env.PAPERCLIP_CONTEXT = context.contextPath;
+  process.env.PAPERCLIP_WORKTREE_NAME = context.worktreeName;
+
+  let repairedConfig = false;
+  if (fs.existsSync(context.configPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(context.configPath, "utf8")) as PaperclipConfig;
+      const siblingPorts = collectSiblingWorktreePorts(context);
+      const hasSiblingPortCollision =
+        siblingPorts.serverPorts.has(parsed.server.port) ||
+        (parsed.database.mode === "embedded-postgres" &&
+          siblingPorts.databasePorts.has(parsed.database.embeddedPostgresPort));
+
+      if (needsWorktreeConfigRepair(parsed, context) || hasSiblingPortCollision) {
+        const selectedServerPort = findNextUnclaimedPort(
+          parsed.server.port === 3100 ? 3101 : parsed.server.port,
+          siblingPorts.serverPorts,
+        );
+        const selectedDatabasePort =
+          parsed.database.mode === "embedded-postgres"
+            ? findNextUnclaimedPort(
+                parsed.database.embeddedPostgresPort === 54329
+                  ? 54330
+                  : parsed.database.embeddedPostgresPort,
+                new Set([...siblingPorts.databasePorts, selectedServerPort]),
+              )
+            : undefined;
+
+        writeConfigFile(
+          context.configPath,
+          buildIsolatedWorktreeConfig(parsed, context, {
+            serverPort: selectedServerPort,
+            databasePort: selectedDatabasePort,
+          }),
+        );
+        repairedConfig = true;
+      }
+    } catch {
+      // Leave invalid configs to the normal startup validation path.
+    }
+  }
+
+  const existingEnvEntries = readEnvEntries(context.envPath);
+  const desiredEnvEntries: Record<string, string> = {
+    ...existingEnvEntries,
+    PAPERCLIP_HOME: context.homeDir,
+    PAPERCLIP_INSTANCE_ID: context.instanceId,
+    PAPERCLIP_CONFIG: context.configPath,
+    PAPERCLIP_CONTEXT: context.contextPath,
+    PAPERCLIP_IN_WORKTREE: "true",
+    PAPERCLIP_WORKTREE_NAME: context.worktreeName,
+  };
+
+  const repairedEnv = Object.entries(desiredEnvEntries).some(
+    ([key, value]) => existingEnvEntries[key] !== value,
+  );
+
+  if (repairedEnv) {
+    fs.mkdirSync(path.dirname(context.envPath), { recursive: true });
+    fs.writeFileSync(context.envPath, formatEnvEntries(desiredEnvEntries), { mode: 0o600 });
+  }
+
+  return { repairedConfig, repairedEnv };
+}
+
+export function maybePersistWorktreeRuntimePorts(input: {
+  serverPort: number;
+  databasePort?: number | null;
+}): void {
+  const context = resolveWorktreeRuntimeContext(process.env);
+  if (!context || !fs.existsSync(context.configPath)) return;
+
+  let fileConfig: PaperclipConfig;
+  try {
+    fileConfig = JSON.parse(fs.readFileSync(context.configPath, "utf8")) as PaperclipConfig;
+  } catch {
+    return;
+  }
+
+  const { config, changed } = applyRuntimePortSelectionToConfig(fileConfig, {
+    serverPort: input.serverPort,
+    databasePort: input.databasePort,
+    allowServerPortWrite: !nonEmpty(process.env.PORT),
+    allowDatabasePortWrite: !nonEmpty(process.env.DATABASE_URL),
+  });
+
+  if (changed) {
+    writeConfigFile(context.configPath, config);
+  }
+}
+

package/server/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}