@openpalm/lib 0.9.4

package/src/control-plane/connection-profiles.ts

@@ -0,0 +1,317 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { PROVIDER_KEY_MAP } from '../provider-constants.js';
+import type {
+  CapabilityAssignments,
+  CanonicalConnectionProfile,
+  CanonicalConnectionsDocument,
+  ConnectionKind,
+} from './types.js';
+
+const CONNECTIONS_DIRNAME = 'connections';
+const CONNECTION_PROFILES_FILENAME = 'profiles.json';
+
+const LOCAL_PROVIDERS = new Set(['ollama', 'lmstudio', 'model-runner']);
+const INSTACK_PROVIDERS = new Set(['ollama-instack']);
+
+function normalizeConnectionKind(provider: string): ConnectionKind {
+  if (INSTACK_PROVIDERS.has(provider)) return 'ollama_local';
+  if (LOCAL_PROVIDERS.has(provider)) return 'openai_compatible_local';
+  return 'openai_compatible_remote';
+}
+
+export function getConnectionProfilesDir(configDir: string): string {
+  return `${configDir}/${CONNECTIONS_DIRNAME}`;
+}
+
+export function getConnectionProfilesPath(configDir: string): string {
+  return `${getConnectionProfilesDir(configDir)}/${CONNECTION_PROFILES_FILENAME}`;
+}
+
+// ── Validation helpers ──────────────────────────────────────────────────
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isValidProfile(value: unknown): value is CanonicalConnectionProfile {
+  if (!isRecord(value)) return false;
+  if (!isNonEmptyString(value.id)) return false;
+  if (!isNonEmptyString(value.name)) return false;
+  if (value.kind !== 'openai_compatible_remote' && value.kind !== 'openai_compatible_local' && value.kind !== 'ollama_local') return false;
+  if (!isNonEmptyString(value.provider)) return false;
+  if (typeof value.baseUrl !== 'string') return false;
+  if (!isRecord(value.auth)) return false;
+  if (value.auth.mode !== 'api_key' && value.auth.mode !== 'none') return false;
+  if (value.auth.mode === 'api_key' && !isNonEmptyString(value.auth.apiKeySecretRef)) return false;
+  return true;
+}
+
+function isValidConnectionDocument(value: unknown): value is CanonicalConnectionsDocument {
+  if (!isRecord(value)) return false;
+  if (value.version !== 1) return false;
+  if (!Array.isArray(value.profiles) || value.profiles.length === 0) return false;
+  if (!isRecord(value.assignments)) return false;
+
+  if (!value.profiles.every(isValidProfile)) return false;
+
+  const llm = value.assignments.llm;
+  const embeddings = value.assignments.embeddings;
+  if (!isRecord(llm) || !isRecord(embeddings)) return false;
+  if (!isNonEmptyString(llm.connectionId) || !isNonEmptyString(llm.model)) return false;
+  if (!isNonEmptyString(embeddings.connectionId) || !isNonEmptyString(embeddings.model)) return false;
+  const embeddingDims = embeddings.embeddingDims;
+  if (
+    embeddingDims !== undefined
+    && (typeof embeddingDims !== 'number' || !Number.isInteger(embeddingDims) || embeddingDims <= 0)
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+// ── Read / Write ────────────────────────────────────────────────────────
+
+export function writeConnectionProfilesDocument(
+  configDir: string,
+  document: CanonicalConnectionsDocument
+): void {
+  const dir = getConnectionProfilesDir(configDir);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    getConnectionProfilesPath(configDir),
+    JSON.stringify(document, null, 2) + '\n'
+  );
+}
+
+export function readConnectionProfilesDocument(configDir: string): CanonicalConnectionsDocument {
+  const path = getConnectionProfilesPath(configDir);
+  if (!existsSync(path)) {
+    return {
+      version: 1,
+      profiles: [],
+      assignments: {
+        llm: { connectionId: '', model: '' },
+        embeddings: { connectionId: '', model: '' },
+      },
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+  } catch {
+    throw new Error('connections/profiles.json is invalid JSON');
+  }
+
+  if (!isValidConnectionDocument(parsed)) {
+    throw new Error('connections/profiles.json is invalid: expected CanonicalConnectionsDocument v1');
+  }
+
+  return parsed;
+}
+
+export function ensureConnectionProfilesStore(configDir: string): void {
+  mkdirSync(getConnectionProfilesDir(configDir), { recursive: true });
+}
+
+// ── Multi-connection write ──────────────────────────────────────────────
+
+export type WriteConnectionsInput = {
+  profiles: Array<{
+    id: string;
+    name: string;
+    provider: string;
+    baseUrl: string;
+    hasApiKey: boolean;
+    apiKeyEnvVar: string;
+  }>;
+  assignments: CapabilityAssignments;
+};
+
+export function writeConnectionsDocument(
+  configDir: string,
+  input: WriteConnectionsInput
+): CanonicalConnectionsDocument {
+  if (input.profiles.length === 0) {
+    throw new Error('writeConnectionsDocument: profiles must not be empty');
+  }
+
+  const profileIds = new Set(input.profiles.map((p) => p.id));
+  if (!profileIds.has(input.assignments.llm.connectionId)) {
+    throw new Error(`writeConnectionsDocument: llm.connectionId "${input.assignments.llm.connectionId}" not found in profiles`);
+  }
+  if (!profileIds.has(input.assignments.embeddings.connectionId)) {
+    throw new Error(`writeConnectionsDocument: embeddings.connectionId "${input.assignments.embeddings.connectionId}" not found in profiles`);
+  }
+
+  const document: CanonicalConnectionsDocument = {
+    version: 1,
+    profiles: input.profiles.map((p) => ({
+      id: p.id,
+      name: p.name,
+      kind: normalizeConnectionKind(p.provider),
+      provider: p.provider,
+      baseUrl: p.baseUrl,
+      auth: {
+        mode: p.hasApiKey ? 'api_key' as const : 'none' as const,
+        ...(p.hasApiKey ? { apiKeySecretRef: `env:${p.apiKeyEnvVar}` } : {}),
+      },
+    })),
+    assignments: input.assignments,
+  };
+
+  writeConnectionProfilesDocument(configDir, document);
+  return document;
+}
+
+// ── CRUD operations ─────────────────────────────────────────────────────
+
+type MutationResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; status: 400 | 404 | 409; message: string };
+
+function validateProfile(profile: CanonicalConnectionProfile): MutationResult<CanonicalConnectionProfile> {
+  if (!profile.id.trim()) {
+    return { ok: false, status: 400, message: 'profile.id is required' };
+  }
+  if (!profile.name.trim()) {
+    return { ok: false, status: 400, message: 'profile.name is required' };
+  }
+  if (!profile.provider.trim()) {
+    return { ok: false, status: 400, message: 'profile.provider is required' };
+  }
+  if (profile.auth.mode !== 'api_key' && profile.auth.mode !== 'none') {
+    return { ok: false, status: 400, message: 'profile.auth.mode must be api_key or none' };
+  }
+  if (profile.auth.mode === 'api_key' && !profile.auth.apiKeySecretRef?.trim()) {
+    return { ok: false, status: 400, message: 'profile.auth.apiKeySecretRef is required when auth.mode is api_key' };
+  }
+  return { ok: true, value: profile };
+}
+
+function validateAssignments(
+  assignments: CapabilityAssignments,
+  profileIds: Set<string>
+): MutationResult<CapabilityAssignments> {
+  if (!isRecord(assignments.llm)) {
+    return { ok: false, status: 400, message: 'assignments.llm must be an object' };
+  }
+  if (!isRecord(assignments.embeddings)) {
+    return { ok: false, status: 400, message: 'assignments.embeddings must be an object' };
+  }
+  if (!isNonEmptyString(assignments.llm.connectionId) || !isNonEmptyString(assignments.llm.model)) {
+    return { ok: false, status: 400, message: 'assignments.llm requires connectionId and model' };
+  }
+  if (!isNonEmptyString(assignments.embeddings.connectionId) || !isNonEmptyString(assignments.embeddings.model)) {
+    return { ok: false, status: 400, message: 'assignments.embeddings requires connectionId and model' };
+  }
+  if (!profileIds.has(assignments.llm.connectionId)) {
+    return { ok: false, status: 409, message: `assignments.llm.connectionId not found: ${assignments.llm.connectionId}` };
+  }
+  if (!profileIds.has(assignments.embeddings.connectionId)) {
+    return { ok: false, status: 409, message: `assignments.embeddings.connectionId not found: ${assignments.embeddings.connectionId}` };
+  }
+  if (
+    assignments.embeddings.embeddingDims !== undefined
+    && (!Number.isInteger(assignments.embeddings.embeddingDims) || assignments.embeddings.embeddingDims <= 0)
+  ) {
+    return { ok: false, status: 400, message: 'assignments.embeddings.embeddingDims must be a positive integer' };
+  }
+  return { ok: true, value: assignments };
+}
+
+export function listConnectionProfiles(configDir: string): CanonicalConnectionProfile[] {
+  return readConnectionProfilesDocument(configDir).profiles;
+}
+
+export function getCapabilityAssignments(configDir: string): CapabilityAssignments {
+  return readConnectionProfilesDocument(configDir).assignments;
+}
+
+export function createConnectionProfile(
+  configDir: string,
+  profile: CanonicalConnectionProfile
+): MutationResult<CanonicalConnectionProfile> {
+  const validated = validateProfile(profile);
+  if (!validated.ok) return validated;
+
+  const document = readConnectionProfilesDocument(configDir);
+  if (document.profiles.some((existing) => existing.id === profile.id)) {
+    return { ok: false, status: 409, message: `profile already exists: ${profile.id}` };
+  }
+
+  const updated: CanonicalConnectionsDocument = {
+    ...document,
+    profiles: [...document.profiles, profile],
+  };
+  writeConnectionProfilesDocument(configDir, updated);
+  return { ok: true, value: profile };
+}
+
+export function updateConnectionProfile(
+  configDir: string,
+  profile: CanonicalConnectionProfile
+): MutationResult<CanonicalConnectionProfile> {
+  const validated = validateProfile(profile);
+  if (!validated.ok) return validated;
+
+  const document = readConnectionProfilesDocument(configDir);
+  const index = document.profiles.findIndex((existing) => existing.id === profile.id);
+  if (index < 0) {
+    return { ok: false, status: 404, message: `profile not found: ${profile.id}` };
+  }
+
+  const profiles = [...document.profiles];
+  profiles[index] = profile;
+  writeConnectionProfilesDocument(configDir, { ...document, profiles });
+  return { ok: true, value: profile };
+}
+
+export function deleteConnectionProfile(
+  configDir: string,
+  id: string
+): MutationResult<{ id: string }> {
+  if (!id.trim()) {
+    return { ok: false, status: 400, message: 'profile id is required' };
+  }
+
+  const document = readConnectionProfilesDocument(configDir);
+  const existing = document.profiles.find((profile) => profile.id === id);
+  if (!existing) {
+    return { ok: false, status: 404, message: `profile not found: ${id}` };
+  }
+  const assignmentFields = ['llm', 'embeddings', 'reranking', 'tts', 'stt'] as const;
+  for (const field of assignmentFields) {
+    const assignment = document.assignments[field];
+    if (assignment && 'connectionId' in assignment && assignment.connectionId === id) {
+      return { ok: false, status: 409, message: `Cannot delete profile: it is assigned to ${field}` };
+    }
+  }
+
+  writeConnectionProfilesDocument(configDir, {
+    ...document,
+    profiles: document.profiles.filter((profile) => profile.id !== id),
+  });
+  return { ok: true, value: { id } };
+}
+
+export function saveCapabilityAssignments(
+  configDir: string,
+  assignments: CapabilityAssignments
+): MutationResult<CapabilityAssignments> {
+  const document = readConnectionProfilesDocument(configDir);
+  const profileIds = new Set(document.profiles.map((profile) => profile.id));
+  const validated = validateAssignments(assignments, profileIds);
+  if (!validated.ok) return validated;
+
+  writeConnectionProfilesDocument(configDir, {
+    ...document,
+    assignments,
+  });
+  return { ok: true, value: assignments };
+}

package/src/control-plane/core-asset-provider.ts

@@ -0,0 +1,20 @@
+/**
+ * CoreAssetProvider interface — dependency injection for bundled assets.
+ *
+ * Admin implements this with Vite $assets imports (ViteAssetProvider).
+ * CLI/lib implements this by reading from DATA_HOME (FilesystemAssetProvider).
+ */
+
+export interface CoreAssetProvider {
+  coreCompose(): string;
+  caddyfile(): string;
+  ollamaCompose(): string;
+  agentsMd(): string;
+  opencodeConfig(): string;
+  adminOpencodeConfig(): string;
+  secretsSchema(): string;
+  stackSchema(): string;
+  cleanupLogs(): string;
+  cleanupData(): string;
+  validateConfig(): string;
+}

package/src/control-plane/core-assets.ts

@@ -0,0 +1,292 @@
+/**
+ * Core asset management for the OpenPalm control plane.
+ *
+ * Manages DATA_HOME source-of-truth files: Caddyfile and docker-compose.yml.
+ * All asset content is provided by a CoreAssetProvider (injected), not by
+ * Vite $assets imports — making this module portable across Bun/Node/Vite.
+ */
+import { mkdirSync, writeFileSync, readFileSync, existsSync, copyFileSync, renameSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { resolveDataHome } from "./paths.js";
+import { createLogger } from "../logger.js";
+import type { CoreAssetProvider } from "./core-asset-provider.js";
+
+const logger = createLogger("core-assets");
+
+// ── Constants ──────────────────────────────────────────────────────────
+
+const PUBLIC_ACCESS_IMPORT = "import public_access";
+const LAN_ONLY_IMPORT = "import lan_only";
+
+/** IP ranges for each access scope mode */
+const HOST_ONLY_IPS = "127.0.0.0/8 ::1";
+const LAN_IPS = "10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 127.0.0.0/8 ::1 fc00::/7 fe80::/10";
+const REMOTE_IP_LINE_RE = /@denied not remote_ip [^\n]+/;
+
+// Re-export for use by staging.ts Caddyfile staging
+export { PUBLIC_ACCESS_IMPORT, LAN_ONLY_IMPORT };
+
+/** SHA-256 hex digest of a string. */
+function sha256(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+/**
+ * Write content to a file if it has changed, backing up the old version.
+ */
+function writeIfChanged(path: string, content: string): void {
+  if (!existsSync(path)) {
+    writeFileSync(path, content);
+    return;
+  }
+  const existing = readFileSync(path, "utf-8");
+  if (sha256(existing) === sha256(content)) return;
+
+  const backupDir = join(dirname(path), "backups");
+  mkdirSync(backupDir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const basename = path.split("/").pop()!;
+  copyFileSync(path, join(backupDir, `${basename}.${ts}`));
+  writeFileSync(path, content);
+}
+
+// ── Core Caddyfile (DATA_HOME source of truth) ─────────────────────────
+
+function coreCaddyfilePath(): string {
+  return `${resolveDataHome()}/caddy/Caddyfile`;
+}
+
+/**
+ * Ensure the system-managed core Caddyfile exists in DATA_HOME.
+ * Seeds the bundled asset on first run. On subsequent runs, leaves the
+ * existing file intact (user may have customized access scope).
+ */
+export function ensureCoreCaddyfile(assets: CoreAssetProvider): string {
+  const path = coreCaddyfilePath();
+  mkdirSync(dirname(path), { recursive: true });
+  if (!existsSync(path)) {
+    writeFileSync(path, assets.caddyfile());
+  }
+  return path;
+}
+
+export function readCoreCaddyfile(assets: CoreAssetProvider): string {
+  const path = ensureCoreCaddyfile(assets);
+  return readFileSync(path, "utf-8");
+}
+
+// ── Env Schema Files (DATA_HOME root) ────────────────────────────────
+
+export function ensureSecretsSchema(assets: CoreAssetProvider): string {
+  const path = `${resolveDataHome()}/secrets.env.schema`;
+  if (!existsSync(path)) {
+    writeFileSync(path, assets.secretsSchema());
+  }
+  return path;
+}
+
+export function ensureStackSchema(assets: CoreAssetProvider): string {
+  const path = `${resolveDataHome()}/stack.env.schema`;
+  if (!existsSync(path)) {
+    writeFileSync(path, assets.stackSchema());
+  }
+  return path;
+}
+
+export function detectAccessScope(rawCaddyfile: string): "host" | "lan" | "custom" {
+  const match = rawCaddyfile.match(REMOTE_IP_LINE_RE);
+  if (!match) return "custom";
+  const ips = match[0].replace("@denied not remote_ip", "").trim();
+  if (ips === HOST_ONLY_IPS) return "host";
+  if (ips === LAN_IPS) return "lan";
+  return "custom";
+}
+
+export function setCoreCaddyAccessScope(
+  scope: "host" | "lan",
+  assets: CoreAssetProvider
+): { ok: true } | { ok: false; error: string } {
+  const path = ensureCoreCaddyfile(assets);
+  const raw = readFileSync(path, "utf-8");
+  if (!REMOTE_IP_LINE_RE.test(raw)) {
+    return { ok: false, error: "core Caddyfile missing '@denied not remote_ip' line" };
+  }
+  const ips = scope === "host" ? HOST_ONLY_IPS : LAN_IPS;
+  const updated = raw.replace(REMOTE_IP_LINE_RE, `@denied not remote_ip ${ips}`);
+  writeFileSync(path, updated);
+  return { ok: true };
+}
+
+// ── Memory data directory (DATA_HOME) ────────────────────────────────────
+
+export function ensureMemoryDir(): string {
+  const dataHome = resolveDataHome();
+  const dir = `${dataHome}/memory`;
+  const legacyDir = `${dataHome}/openmemory`;
+
+  if (!existsSync(dir) && existsSync(legacyDir)) {
+    try {
+      renameSync(legacyDir, dir);
+    } catch (error) {
+      const code = error instanceof Error && "code" in error ? String(error.code) : "unknown";
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn("failed to migrate legacy memory dir", { legacyDir, dir, code, message });
+    }
+  }
+
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// ── Core Compose (DATA_HOME source of truth) ──────────────────────────
+
+function coreComposePath(): string {
+  return `${resolveDataHome()}/docker-compose.yml`;
+}
+
+export function ensureCoreCompose(assets: CoreAssetProvider): string {
+  const path = coreComposePath();
+  const content = assets.coreCompose();
+  mkdirSync(dirname(path), { recursive: true });
+  if (!existsSync(path)) {
+    writeFileSync(path, content);
+  } else if (sha256(readFileSync(path, "utf-8")) !== sha256(content)) {
+    const backupDir = join(dirname(path), "backups");
+    mkdirSync(backupDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    copyFileSync(path, join(backupDir, `docker-compose.${ts}.yml`));
+    writeFileSync(path, content);
+  }
+  return path;
+}
+
+export function readCoreCompose(assets: CoreAssetProvider): string {
+  const path = ensureCoreCompose(assets);
+  return readFileSync(path, "utf-8");
+}
+
+// ── Ollama Compose Overlay (DATA_HOME source of truth) ──────────────
+
+function ollamaComposePath(): string {
+  return `${resolveDataHome()}/ollama.yml`;
+}
+
+export function ensureOllamaCompose(assets: CoreAssetProvider): string {
+  const path = ollamaComposePath();
+  const content = assets.ollamaCompose();
+  mkdirSync(dirname(path), { recursive: true });
+  if (!existsSync(path)) {
+    writeFileSync(path, content);
+  } else if (sha256(readFileSync(path, "utf-8")) !== sha256(content)) {
+    const backupDir = join(dirname(path), "backups");
+    mkdirSync(backupDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    copyFileSync(path, join(backupDir, `ollama.${ts}.yml`));
+    writeFileSync(path, content);
+  }
+  return path;
+}
+
+export function readOllamaCompose(assets: CoreAssetProvider): string {
+  const path = ensureOllamaCompose(assets);
+  return readFileSync(path, "utf-8");
+}
+
+// ── OpenCode System Config (DATA_HOME source of truth) ──────────────
+
+export function ensureOpenCodeSystemConfig(assets: CoreAssetProvider): void {
+  const dir = `${resolveDataHome()}/assistant`;
+  mkdirSync(dir, { recursive: true });
+  writeIfChanged(`${dir}/opencode.jsonc`, assets.opencodeConfig());
+  writeIfChanged(`${dir}/AGENTS.md`, assets.agentsMd());
+}
+
+export function ensureAdminOpenCodeConfig(assets: CoreAssetProvider): void {
+  const dir = `${resolveDataHome()}/admin`;
+  mkdirSync(dir, { recursive: true });
+  writeIfChanged(`${dir}/opencode.jsonc`, assets.adminOpencodeConfig());
+  writeIfChanged(`${dir}/AGENTS.md`, assets.agentsMd());
+}
+
+// ── Core Automations (DATA_HOME source of truth) ────────────────────
+
+export function ensureCoreAutomations(assets: CoreAssetProvider): void {
+  const dir = `${resolveDataHome()}/automations`;
+  mkdirSync(dir, { recursive: true });
+
+  const coreAutomations = [
+    { filename: "cleanup-logs.yml", content: assets.cleanupLogs() },
+    { filename: "cleanup-data.yml", content: assets.cleanupData() },
+    { filename: "validate-config.yml", content: assets.validateConfig() },
+  ];
+
+  for (const { filename, content } of coreAutomations) {
+    writeIfChanged(join(dir, filename), content);
+  }
+}
+
+// ── Asset Refresh (GitHub download) ──────────────────────────────────
+
+const REPO = "itlackey/openpalm";
+const VERSION = process.env.OPENPALM_ASSET_VERSION ?? "main";
+
+const MANAGED_ASSETS: { dataRelPath: string; githubFilename: string }[] = [
+  { dataRelPath: "docker-compose.yml", githubFilename: "docker-compose.yml" },
+  { dataRelPath: "caddy/Caddyfile", githubFilename: "Caddyfile" },
+  { dataRelPath: "assistant/opencode.jsonc", githubFilename: "opencode.jsonc" },
+  { dataRelPath: "admin/opencode.jsonc", githubFilename: "admin-opencode.jsonc" },
+  { dataRelPath: "assistant/AGENTS.md", githubFilename: "AGENTS.md" },
+  { dataRelPath: "ollama.yml", githubFilename: "ollama.yml" },
+  { dataRelPath: "secrets.env.schema", githubFilename: "secrets.env.schema" },
+  { dataRelPath: "stack.env.schema", githubFilename: "stack.env.schema" }
+];
+
+async function downloadAsset(filename: string): Promise<string> {
+  const releaseUrl = `https://github.com/${REPO}/releases/download/${VERSION}/${filename}`;
+  const rawUrl = `https://raw.githubusercontent.com/${REPO}/${VERSION}/assets/${filename}`;
+
+  for (const url of [releaseUrl, rawUrl]) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) return await res.text();
+    } catch {
+      // try next URL
+    }
+  }
+  throw new Error(`Failed to download ${filename} from GitHub (tried release and raw URLs for version "${VERSION}")`);
+}
+
+export async function refreshCoreAssets(): Promise<{
+  backupDir: string | null;
+  updated: string[];
+}> {
+  const dataHome = resolveDataHome();
+  const updated: string[] = [];
+  let backupDir: string | null = null;
+
+  for (const asset of MANAGED_ASSETS) {
+    const freshContent = await downloadAsset(asset.githubFilename);
+    const targetPath = join(dataHome, asset.dataRelPath);
+
+    if (existsSync(targetPath)) {
+      const currentContent = readFileSync(targetPath, "utf-8");
+      if (sha256(currentContent) === sha256(freshContent)) {
+        continue;
+      }
+
+      if (!backupDir) {
+        backupDir = join(dataHome, "backups", new Date().toISOString().replace(/[:.]/g, "-"));
+      }
+      const backupPath = join(backupDir, asset.dataRelPath);
+      mkdirSync(dirname(backupPath), { recursive: true });
+      copyFileSync(targetPath, backupPath);
+    }
+
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, freshContent);
+    updated.push(asset.dataRelPath);
+  }
+
+  return { backupDir, updated };
+}