@dyyz1993/codenomad 0.15.0

package/dist/server/routes/worktrees.js

@@ -0,0 +1,156 @@
+import { z } from "zod";
+import { resolveRepoRoot, listWorktrees, isValidWorktreeSlug, createManagedWorktree, removeWorktree, } from "../../workspaces/git-worktrees";
+import { ensureCodenomadGitExclude, readWorktreeMap, writeWorktreeMap } from "../../workspaces/worktree-map";
+const WorktreeMapSchema = z.object({
+    version: z.literal(1),
+    defaultWorktreeSlug: z.string().min(1).default("root"),
+    parentSessionWorktreeSlug: z.record(z.string(), z.string()).default({}),
+});
+const WorktreeCreateSchema = z.object({
+    slug: z.string().trim().min(1),
+    branch: z.string().trim().min(1).optional(),
+});
+export function registerWorktreeRoutes(app, deps) {
+    app.get("/api/workspaces/:id/worktrees", async (request, reply) => {
+        const workspace = deps.workspaceManager.get(request.params.id);
+        if (!workspace) {
+            reply.code(404);
+            return { error: "Workspace not found" };
+        }
+        const { repoRoot, isGitRepo } = await resolveRepoRoot(workspace.path, request.log);
+        const worktrees = await listWorktrees({ repoRoot, workspaceFolder: workspace.path, logger: request.log });
+        const response = { worktrees, isGitRepo };
+        return response;
+    });
+    app.post("/api/workspaces/:id/worktrees", async (request, reply) => {
+        const workspace = deps.workspaceManager.get(request.params.id);
+        if (!workspace) {
+            reply.code(404);
+            return { error: "Workspace not found" };
+        }
+        try {
+            const body = WorktreeCreateSchema.parse(request.body ?? {});
+            const slug = body.slug;
+            if (!isValidWorktreeSlug(slug) || slug === "root") {
+                reply.code(400);
+                return { error: "Invalid worktree slug" };
+            }
+            if (body.branch) {
+                if (!isValidWorktreeSlug(body.branch) || body.branch === "root") {
+                    reply.code(400);
+                    return { error: "Invalid worktree branch" };
+                }
+                if (body.branch !== slug) {
+                    reply.code(400);
+                    return { error: "Branch must match slug" };
+                }
+            }
+            const { repoRoot, isGitRepo } = await resolveRepoRoot(workspace.path, request.log);
+            if (!isGitRepo) {
+                reply.code(400);
+                return { error: "Workspace is not a Git repository" };
+            }
+            await ensureCodenomadGitExclude(workspace.path, request.log).catch(() => undefined);
+            const created = await createManagedWorktree({
+                repoRoot,
+                workspaceFolder: workspace.path,
+                slug,
+                logger: request.log,
+            });
+            reply.code(201);
+            return created;
+        }
+        catch (error) {
+            return handleError(error, reply);
+        }
+    });
+    app.delete("/api/workspaces/:id/worktrees/:slug", async (request, reply) => {
+        const workspace = deps.workspaceManager.get(request.params.id);
+        if (!workspace) {
+            reply.code(404);
+            return { error: "Workspace not found" };
+        }
+        const slug = (request.params.slug ?? "").trim();
+        if (!isValidWorktreeSlug(slug) || slug === "root") {
+            reply.code(400);
+            return { error: "Invalid worktree slug" };
+        }
+        const { repoRoot, isGitRepo } = await resolveRepoRoot(workspace.path, request.log);
+        if (!isGitRepo) {
+            reply.code(400);
+            return { error: "Workspace is not a Git repository" };
+        }
+        const force = (request.query?.force ?? "").toString().toLowerCase() === "true";
+        try {
+            const worktrees = await listWorktrees({ repoRoot, workspaceFolder: workspace.path, logger: request.log });
+            const match = worktrees.find((wt) => wt.slug === slug);
+            if (!match || match.kind === "root") {
+                reply.code(404);
+                return { error: "Worktree not found" };
+            }
+            await removeWorktree({ workspaceFolder: workspace.path, directory: match.directory, force, logger: request.log });
+            // Best-effort: prune any mappings that point at the deleted worktree.
+            const current = await readWorktreeMap(workspace.path, request.log);
+            let changed = false;
+            const nextMapping = { ...(current.parentSessionWorktreeSlug ?? {}) };
+            for (const [sessionId, mapped] of Object.entries(nextMapping)) {
+                if (mapped === slug) {
+                    delete nextMapping[sessionId];
+                    changed = true;
+                }
+            }
+            const nextDefault = current.defaultWorktreeSlug === slug ? "root" : current.defaultWorktreeSlug;
+            if (nextDefault !== current.defaultWorktreeSlug) {
+                changed = true;
+            }
+            if (changed) {
+                await writeWorktreeMap(workspace.path, {
+                    version: 1,
+                    defaultWorktreeSlug: nextDefault,
+                    parentSessionWorktreeSlug: nextMapping,
+                }, request.log);
+            }
+            reply.code(204);
+        }
+        catch (error) {
+            return handleError(error, reply);
+        }
+    });
+    app.get("/api/workspaces/:id/worktrees/map", async (request, reply) => {
+        const workspace = deps.workspaceManager.get(request.params.id);
+        if (!workspace) {
+            reply.code(404);
+            return { error: "Workspace not found" };
+        }
+        return await readWorktreeMap(workspace.path, request.log);
+    });
+    app.put("/api/workspaces/:id/worktrees/map", async (request, reply) => {
+        const workspace = deps.workspaceManager.get(request.params.id);
+        if (!workspace) {
+            reply.code(404);
+            return { error: "Workspace not found" };
+        }
+        try {
+            const parsed = WorktreeMapSchema.parse(request.body ?? {});
+            if (!isValidWorktreeSlug(parsed.defaultWorktreeSlug)) {
+                reply.code(400);
+                return { error: "Invalid defaultWorktreeSlug" };
+            }
+            for (const slug of Object.values(parsed.parentSessionWorktreeSlug ?? {})) {
+                if (!isValidWorktreeSlug(slug)) {
+                    reply.code(400);
+                    return { error: "Invalid worktree slug in mapping" };
+                }
+            }
+            await writeWorktreeMap(workspace.path, parsed, request.log);
+            reply.code(204);
+        }
+        catch (error) {
+            return handleError(error, reply);
+        }
+    });
+}
+function handleError(error, reply) {
+    reply.code(400);
+    return { error: error instanceof Error ? error.message : "Unable to fulfill request" };
+}

package/dist/server/tls.js

@@ -0,0 +1,224 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+function loadForge() {
+    // node-forge is CJS in many installs; require keeps this compatible with our ESM output.
+    return require("node-forge");
+}
+const LEAF_VALIDITY_DAYS = 30;
+const ROTATE_IF_EXPIRES_WITHIN_DAYS = 3;
+const CA_VALIDITY_DAYS = 365;
+export function resolveHttpsOptions(args) {
+    if (!args.enabled) {
+        return null;
+    }
+    const hasProvided = Boolean(args.tlsKeyPath && args.tlsCertPath);
+    if (hasProvided) {
+        const key = fs.readFileSync(args.tlsKeyPath, "utf-8");
+        const cert = fs.readFileSync(args.tlsCertPath, "utf-8");
+        const ca = args.tlsCaPath ? fs.readFileSync(args.tlsCaPath, "utf-8") : undefined;
+        return {
+            httpsOptions: { key, cert, ca },
+            caCertPath: args.tlsCaPath,
+            mode: "provided",
+        };
+    }
+    return ensureGeneratedTls(args);
+}
+function ensureGeneratedTls(args) {
+    const tlsDir = path.join(args.configDir, "tls");
+    const caKeyPath = path.join(tlsDir, "ca-key.pem");
+    const caCertPath = path.join(tlsDir, "ca-cert.pem");
+    const keyPath = path.join(tlsDir, "server-key.pem");
+    const certPath = path.join(tlsDir, "server-cert.pem");
+    fs.mkdirSync(tlsDir, { recursive: true });
+    const shouldRotateLeaf = () => {
+        try {
+            if (!fs.existsSync(certPath))
+                return true;
+            const pem = fs.readFileSync(certPath, "utf-8");
+            const x509 = new crypto.X509Certificate(pem);
+            const validToMs = Date.parse(x509.validTo);
+            if (!Number.isFinite(validToMs))
+                return true;
+            const rotateAt = validToMs - ROTATE_IF_EXPIRES_WITHIN_DAYS * 24 * 60 * 60 * 1000;
+            return Date.now() >= rotateAt;
+        }
+        catch {
+            return true;
+        }
+    };
+    const shouldRotateCa = () => {
+        try {
+            if (!fs.existsSync(caCertPath))
+                return true;
+            const pem = fs.readFileSync(caCertPath, "utf-8");
+            const x509 = new crypto.X509Certificate(pem);
+            const validToMs = Date.parse(x509.validTo);
+            if (!Number.isFinite(validToMs))
+                return true;
+            // CA rotates only when expired.
+            return Date.now() >= validToMs;
+        }
+        catch {
+            return true;
+        }
+    };
+    if (shouldRotateCa() || !fs.existsSync(caKeyPath)) {
+        const { caKeyPem, caCertPem } = generateCaCertificate();
+        writePemFile(caKeyPath, caKeyPem, 0o600);
+        writePemFile(caCertPath, caCertPem, 0o644);
+        args.logger.info({ caCertPath }, "Generated self-signed CodeNomad CA certificate");
+    }
+    if (shouldRotateLeaf() || !fs.existsSync(keyPath)) {
+        const caKeyPem = fs.readFileSync(caKeyPath, "utf-8");
+        const caCertPem = fs.readFileSync(caCertPath, "utf-8");
+        const { keyPem, certPem } = generateServerCertificate({
+            host: args.host,
+            tlsSANs: args.tlsSANs,
+            caKeyPem,
+            caCertPem,
+        });
+        writePemFile(keyPath, keyPem, 0o600);
+        writePemFile(certPath, certPem, 0o644);
+        args.logger.info({ certPath }, "Generated CodeNomad HTTPS certificate");
+    }
+    const key = fs.readFileSync(keyPath, "utf-8");
+    const cert = fs.readFileSync(certPath, "utf-8");
+    const ca = fs.readFileSync(caCertPath, "utf-8");
+    // Present the CA as part of the chain.
+    const chainedCert = `${cert.trim()}\n${ca.trim()}\n`;
+    return {
+        httpsOptions: {
+            key,
+            cert: chainedCert,
+        },
+        caCertPath,
+        mode: "generated",
+    };
+}
+function writePemFile(filePath, content, mode) {
+    fs.writeFileSync(filePath, content, { encoding: "utf-8", mode });
+    try {
+        fs.chmodSync(filePath, mode);
+    }
+    catch {
+        // best effort on platforms that ignore chmod
+    }
+}
+function generateCaCertificate() {
+    const forge = loadForge();
+    const keys = forge.pki.rsa.generateKeyPair(2048);
+    const cert = forge.pki.createCertificate();
+    cert.publicKey = keys.publicKey;
+    cert.serialNumber = crypto.randomBytes(16).toString("hex");
+    const now = new Date();
+    const notBefore = new Date(now.getTime() - 60000);
+    const notAfter = new Date(now.getTime() + CA_VALIDITY_DAYS * 24 * 60 * 60 * 1000);
+    cert.validity.notBefore = notBefore;
+    cert.validity.notAfter = notAfter;
+    const attrs = [{ name: "commonName", value: "CodeNomad Local CA" }];
+    cert.setSubject(attrs);
+    cert.setIssuer(attrs);
+    cert.setExtensions([
+        { name: "basicConstraints", cA: true },
+        { name: "keyUsage", keyCertSign: true, cRLSign: true, digitalSignature: true },
+        { name: "subjectKeyIdentifier" },
+    ]);
+    cert.sign(keys.privateKey, forge.md.sha256.create());
+    return {
+        caKeyPem: forge.pki.privateKeyToPem(keys.privateKey),
+        caCertPem: forge.pki.certificateToPem(cert),
+    };
+}
+function generateServerCertificate(args) {
+    const forge = loadForge();
+    const caKey = forge.pki.privateKeyFromPem(args.caKeyPem);
+    const caCert = forge.pki.certificateFromPem(args.caCertPem);
+    const keys = forge.pki.rsa.generateKeyPair(2048);
+    const cert = forge.pki.createCertificate();
+    cert.publicKey = keys.publicKey;
+    cert.serialNumber = crypto.randomBytes(16).toString("hex");
+    const now = new Date();
+    const notBefore = new Date(now.getTime() - 60000);
+    const notAfter = new Date(now.getTime() + LEAF_VALIDITY_DAYS * 24 * 60 * 60 * 1000);
+    cert.validity.notBefore = notBefore;
+    cert.validity.notAfter = notAfter;
+    const commonName = pickCommonName(args.host);
+    cert.setSubject([{ name: "commonName", value: commonName }]);
+    cert.setIssuer(caCert.subject.attributes);
+    const san = buildSubjectAltNames(args.host, args.tlsSANs);
+    cert.setExtensions([
+        { name: "basicConstraints", cA: false },
+        { name: "keyUsage", digitalSignature: true, keyEncipherment: true },
+        { name: "extKeyUsage", serverAuth: true },
+        { name: "subjectAltName", altNames: san },
+        { name: "subjectKeyIdentifier" },
+    ]);
+    cert.sign(caKey, forge.md.sha256.create());
+    return {
+        keyPem: forge.pki.privateKeyToPem(keys.privateKey),
+        certPem: forge.pki.certificateToPem(cert),
+    };
+}
+function pickCommonName(host) {
+    if (!host || host === "0.0.0.0") {
+        return "localhost";
+    }
+    if (host === "127.0.0.1") {
+        return "localhost";
+    }
+    return host;
+}
+function buildSubjectAltNames(host, tlsSANs) {
+    const dns = new Set();
+    const ips = new Set();
+    dns.add("localhost");
+    ips.add("127.0.0.1");
+    if (host && host !== "0.0.0.0") {
+        if (isIPv4(host)) {
+            ips.add(host);
+        }
+        else {
+            dns.add(host);
+        }
+    }
+    for (const token of splitList(tlsSANs)) {
+        if (isIPv4(token)) {
+            ips.add(token);
+        }
+        else if (token) {
+            dns.add(token);
+        }
+    }
+    const altNames = [];
+    // 2 = DNS, 7 = IP
+    for (const name of Array.from(dns)) {
+        altNames.push({ type: 2, value: name });
+    }
+    for (const ip of Array.from(ips)) {
+        altNames.push({ type: 7, ip });
+    }
+    return altNames;
+}
+function splitList(input) {
+    if (!input)
+        return [];
+    return input
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+function isIPv4(value) {
+    const parts = value.split(".");
+    if (parts.length !== 4)
+        return false;
+    return parts.every((part) => {
+        if (!/^[0-9]+$/.test(part))
+            return false;
+        const num = Number(part);
+        return Number.isInteger(num) && num >= 0 && num <= 255;
+    });
+}

package/dist/settings/binaries.js

@@ -0,0 +1,37 @@
+function prettyLabel(p) {
+    const parts = p.split(/[\\/]/);
+    const last = parts[parts.length - 1] || p;
+    return last || p;
+}
+function readUiBinaries(settings) {
+    const ui = settings.getOwner("state", "ui");
+    const list = ui?.opencodeBinaries;
+    if (!Array.isArray(list))
+        return [];
+    return list.filter((item) => item && typeof item === "object" && typeof item.path === "string");
+}
+function readDefaultBinaryPath(settings) {
+    const server = settings.getOwner("config", "server");
+    const value = server?.opencodeBinary;
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+export class BinaryResolver {
+    constructor(settings) {
+        this.settings = settings;
+    }
+    list() {
+        return readUiBinaries(this.settings);
+    }
+    resolveDefault() {
+        const binaries = this.list();
+        const configuredDefault = readDefaultBinaryPath(this.settings);
+        const fallback = binaries[0]?.path;
+        const path = configuredDefault ?? fallback ?? "opencode";
+        const entry = binaries.find((b) => b.path === path);
+        return {
+            path,
+            label: entry?.label ?? prettyLabel(path),
+            version: entry?.version,
+        };
+    }
+}

package/dist/settings/merge-patch.js

@@ -0,0 +1,33 @@
+export function isPlainObject(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * RFC 7396-ish merge patch with explicit null deletes.
+ * - Objects merge recursively
+ * - Arrays/scalars replace
+ * - null deletes keys
+ */
+export function applyMergePatch(current, patch) {
+    if (!isPlainObject(patch)) {
+        return patch;
+    }
+    const base = isPlainObject(current) ? { ...current } : {};
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete base[key];
+            continue;
+        }
+        const existing = base[key];
+        if (isPlainObject(value) && isPlainObject(existing)) {
+            base[key] = applyMergePatch(existing, value);
+            continue;
+        }
+        base[key] = value;
+    }
+    return base;
+}

package/dist/settings/migrate.js

@@ -0,0 +1,238 @@
+import fs from "fs";
+import path from "path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { isPlainObject } from "./merge-patch";
+function ensureTrailingNewline(content) {
+    if (!content)
+        return "\n";
+    return content.endsWith("\n") ? content : `${content}\n`;
+}
+function safeReadYaml(filePath, logger) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return parseYaml(content);
+    }
+    catch (error) {
+        logger.warn({ err: error, filePath }, "Failed to read YAML file during migration");
+        return null;
+    }
+}
+function safeReadJson(filePath, logger) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch (error) {
+        logger.warn({ err: error, filePath }, "Failed to read JSON file during migration");
+        return null;
+    }
+}
+function writeYaml(filePath, doc, logger) {
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const yaml = stringifyYaml(doc);
+        fs.writeFileSync(filePath, ensureTrailingNewline(yaml), "utf-8");
+    }
+    catch (error) {
+        logger.warn({ err: error, filePath }, "Failed to write YAML file during migration");
+    }
+}
+function pickBackupPath(filePath) {
+    const preferred = `${filePath}.bak`;
+    if (!fs.existsSync(preferred)) {
+        return preferred;
+    }
+    return `${filePath}.bak.${Date.now()}`;
+}
+function normalizeDoc(value) {
+    return isPlainObject(value) ? value : {};
+}
+function looksLikeNewOwnerDoc(value) {
+    const doc = normalizeDoc(value);
+    // Heuristic: owner-bucket docs have at least one of these roots.
+    return Boolean(doc.ui || doc.server || doc.app || doc.legacy);
+}
+function looksLikeLegacyConfig(value) {
+    const doc = normalizeDoc(value);
+    return Boolean(doc.preferences || doc.opencodeBinaries || doc.theme || doc.recentFolders);
+}
+function looksLikeLegacyState(value) {
+    const doc = normalizeDoc(value);
+    return Boolean(doc.recentFolders);
+}
+function omitKeys(source, keys) {
+    const out = {};
+    for (const [k, v] of Object.entries(source)) {
+        if (keys.has(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+function mapLegacyToOwnerDocs(legacyConfig, legacyState) {
+    const cfg = normalizeDoc(legacyConfig);
+    const st = normalizeDoc(legacyState);
+    const outConfig = {};
+    const outState = {};
+    const uiConfig = {};
+    const uiSettings = {};
+    const serverConfig = {};
+    const uiState = {};
+    // theme -> config.ui.theme
+    if (typeof cfg.theme === "string") {
+        uiConfig.theme = cfg.theme;
+    }
+    const preferences = normalizeDoc(cfg.preferences);
+    if (Object.keys(preferences).length > 0) {
+        // Server-owned stable keys
+        const envVars = preferences.environmentVariables;
+        if (isPlainObject(envVars)) {
+            serverConfig.environmentVariables = envVars;
+        }
+        const listeningMode = preferences.listeningMode;
+        if (typeof listeningMode === "string") {
+            serverConfig.listeningMode = listeningMode;
+        }
+        const logLevel = preferences.logLevel;
+        if (typeof logLevel === "string") {
+            serverConfig.logLevel = logLevel;
+        }
+        const lastUsedBinary = preferences.lastUsedBinary;
+        if (typeof lastUsedBinary === "string") {
+            serverConfig.opencodeBinary = lastUsedBinary;
+        }
+        // UI-owned state keys (drop preferences)
+        const modelRecents = preferences.modelRecents;
+        const modelFavorites = preferences.modelFavorites;
+        const modelThinkingSelections = preferences.modelThinkingSelections;
+        const models = {};
+        if (Array.isArray(modelRecents)) {
+            models.recents = modelRecents;
+        }
+        if (Array.isArray(modelFavorites)) {
+            models.favorites = modelFavorites;
+        }
+        if (isPlainObject(modelThinkingSelections)) {
+            models.thinkingSelections = modelThinkingSelections;
+        }
+        if (Object.keys(models).length > 0) {
+            uiState.models = models;
+        }
+        // Remaining preferences are treated as stable UI settings.
+        const moved = new Set([
+            "environmentVariables",
+            "listeningMode",
+            "logLevel",
+            "lastUsedBinary",
+            "modelRecents",
+            "modelFavorites",
+            "modelThinkingSelections",
+        ]);
+        Object.assign(uiSettings, omitKeys(preferences, moved));
+    }
+    // recentFolders lives in legacy state (yaml) or legacy config.json
+    const recentFolders = (st.recentFolders ?? cfg.recentFolders);
+    if (Array.isArray(recentFolders)) {
+        uiState.recentFolders = recentFolders;
+    }
+    // opencodeBinaries -> state.ui.opencodeBinaries
+    if (Array.isArray(cfg.opencodeBinaries)) {
+        uiState.opencodeBinaries = cfg.opencodeBinaries;
+    }
+    if (Object.keys(uiSettings).length > 0) {
+        uiConfig.settings = uiSettings;
+    }
+    if (Object.keys(uiConfig).length > 0) {
+        outConfig.ui = uiConfig;
+    }
+    if (Object.keys(serverConfig).length > 0) {
+        outConfig.server = serverConfig;
+    }
+    if (Object.keys(uiState).length > 0) {
+        outState.ui = uiState;
+    }
+    // Unknown top-level keys -> legacy.unknown
+    const knownConfigKeys = new Set(["preferences", "opencodeBinaries", "theme", "recentFolders"]);
+    const unknownConfig = omitKeys(cfg, knownConfigKeys);
+    if (Object.keys(unknownConfig).length > 0) {
+        outConfig.legacy = { unknown: unknownConfig };
+    }
+    const knownStateKeys = new Set(["recentFolders"]);
+    const unknownState = omitKeys(st, knownStateKeys);
+    if (Object.keys(unknownState).length > 0) {
+        outState.legacy = { unknown: unknownState };
+    }
+    return { config: outConfig, state: outState };
+}
+/**
+ * Migrate older config/state layouts into owner-bucket YAML docs.
+ *
+ * Legacy inputs supported:
+ * - config.yaml with { preferences, opencodeBinaries, theme }
+ * - state.yaml with { recentFolders }
+ * - legacy config.json with full ConfigFile schema
+ */
+export function migrateSettingsLayout(location, logger) {
+    const configYamlPath = location.configYamlPath;
+    const stateYamlPath = location.stateYamlPath;
+    const legacyJsonPath = location.legacyJsonPath;
+    const configExists = fs.existsSync(configYamlPath);
+    const stateExists = fs.existsSync(stateYamlPath);
+    const configDoc = configExists ? safeReadYaml(configYamlPath, logger) : null;
+    const stateDoc = stateExists ? safeReadYaml(stateYamlPath, logger) : null;
+    const configIsNew = configExists && looksLikeNewOwnerDoc(configDoc) && !looksLikeLegacyConfig(configDoc);
+    const stateIsNew = stateExists && looksLikeNewOwnerDoc(stateDoc) && !looksLikeLegacyState(stateDoc);
+    if (configIsNew && stateIsNew) {
+        return;
+    }
+    const legacyJsonExists = fs.existsSync(legacyJsonPath);
+    const hasLegacyYaml = (configExists && looksLikeLegacyConfig(configDoc)) || (stateExists && looksLikeLegacyState(stateDoc));
+    const shouldMigrateFromJson = !configExists && legacyJsonExists;
+    if (!hasLegacyYaml && !shouldMigrateFromJson) {
+        // Either fresh install or partially written docs; let stores create on first write.
+        return;
+    }
+    const sourceConfig = shouldMigrateFromJson ? safeReadJson(legacyJsonPath, logger) : configDoc;
+    const sourceState = shouldMigrateFromJson ? sourceConfig : stateDoc;
+    const { config, state } = mapLegacyToOwnerDocs(sourceConfig, sourceState);
+    try {
+        fs.mkdirSync(location.baseDir, { recursive: true });
+    }
+    catch (error) {
+        logger.warn({ err: error, baseDir: location.baseDir }, "Failed to create base directory during migration");
+    }
+    // Backup legacy files before rewriting.
+    if (configExists) {
+        try {
+            const bak = pickBackupPath(configYamlPath);
+            fs.renameSync(configYamlPath, bak);
+            logger.info({ configYamlPath, bak }, "Backed up legacy config.yaml");
+        }
+        catch (error) {
+            logger.warn({ err: error, configYamlPath }, "Failed to backup legacy config.yaml");
+        }
+    }
+    if (stateExists) {
+        try {
+            const bak = pickBackupPath(stateYamlPath);
+            fs.renameSync(stateYamlPath, bak);
+            logger.info({ stateYamlPath, bak }, "Backed up legacy state.yaml");
+        }
+        catch (error) {
+            logger.warn({ err: error, stateYamlPath }, "Failed to backup legacy state.yaml");
+        }
+    }
+    if (shouldMigrateFromJson) {
+        try {
+            const bak = pickBackupPath(legacyJsonPath);
+            fs.renameSync(legacyJsonPath, bak);
+            logger.info({ legacyJsonPath, bak }, "Moved legacy config.json to backup");
+        }
+        catch (error) {
+            logger.warn({ err: error, legacyJsonPath }, "Failed to move legacy config.json to backup");
+        }
+    }
+    writeYaml(configYamlPath, config, logger);
+    writeYaml(stateYamlPath, state, logger);
+    logger.info({ configYamlPath, stateYamlPath }, "Migrated settings docs to owner-bucket layout");
+}