knodin 0.8.6 → 0.8.7

package/dist/src/system-management.js

@@ -0,0 +1,508 @@
+import child_process from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseDocument, stringify } from "yaml";
+import { loadSystemConfiguration, RELATIONSHIP_TYPES, } from "./system-config.js";
+function fileDigest(filePath) {
+    try {
+        return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function protectPlan(plan) {
+    const protectedPlan = {
+        ...plan,
+        status: "planned",
+        files: plan.files.map((file) => ({ ...file, expectedDigest: fileDigest(file.path) })),
+    };
+    return {
+        ...protectedPlan,
+        planDigest: crypto.createHash("sha256").update(JSON.stringify(protectedPlan)).digest("hex"),
+    };
+}
+function configHome(value) {
+    return value ?? process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+}
+function safeId(value, field) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(value))
+        throw new Error(`${field} must contain only letters, digits, dot, underscore, and hyphen`);
+    return value;
+}
+function checkoutId(checkout) {
+    const value = path
+        .basename(path.resolve(checkout))
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-");
+    return safeId(value, "derived repository id");
+}
+function repositoryOverride(overrides, checkout) {
+    return (overrides[checkout] ?? overrides[path.resolve(checkout)] ?? overrides[path.basename(checkout)]);
+}
+function assertCheckout(checkout) {
+    const resolved = path.resolve(checkout);
+    if (!fs.statSync(resolved).isDirectory())
+        throw new Error(`${resolved}: repository is not a directory`);
+    return resolved;
+}
+function yamlForSystem(systemId, repositories, relationships = []) {
+    return stringify({
+        schemaVersion: 1,
+        repositories: repositories.map(({ id }) => ({ id, role: "source" })),
+        systems: [
+            {
+                id: systemId,
+                components: repositories.map(({ id, componentId, componentType }) => ({
+                    id: componentId,
+                    repository: id,
+                    type: componentType,
+                })),
+            },
+        ],
+        relationships,
+    }, { lineWidth: 0 });
+}
+function teamYamlForSystem(filePath, systemId, repositories) {
+    let document;
+    try {
+        document = parseDocument(fs.readFileSync(filePath, "utf8"), { uniqueKeys: true });
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        document = parseDocument("schemaVersion: 1\n");
+    }
+    if (document.errors.length)
+        throw new Error(`${filePath}: ${document.errors[0]?.message}`);
+    if (document.get("schemaVersion") === undefined)
+        document.set("schemaVersion", 1);
+    if (document.get("schemaVersion") !== 1)
+        throw new Error(`${filePath}: schemaVersion must be 1`);
+    const root = document.toJS();
+    const existingRepositories = new Map((root.repositories ?? []).map((repository) => [String(repository.id ?? ""), repository]));
+    for (const repository of repositories)
+        if (!existingRepositories.has(repository.id))
+            existingRepositories.set(repository.id, { id: repository.id, role: "source" });
+    const declaration = {
+        id: systemId,
+        components: repositories.map(({ id, componentId, componentType }) => ({
+            id: componentId,
+            repository: id,
+            type: componentType,
+        })),
+    };
+    const systems = root.systems ?? [];
+    const systemIndex = systems.findIndex(({ id }) => id === systemId);
+    if (systemIndex >= 0)
+        systems[systemIndex] = { ...systems[systemIndex], ...declaration };
+    else
+        systems.push(declaration);
+    document.set("repositories", [...existingRepositories.values()]);
+    document.set("systems", systems);
+    return document.toString({ lineWidth: 0 });
+}
+function mappingsYaml(repositories, existingPath, system) {
+    let document;
+    try {
+        document = parseDocument(fs.readFileSync(existingPath, "utf8"), { uniqueKeys: true });
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        document = parseDocument("schemaVersion: 1\nrepositories: {}\n");
+    }
+    if (document.errors.length)
+        throw new Error(`${existingPath}: ${document.errors[0]?.message}`);
+    if (!document.hasIn(["repositories"]))
+        document.setIn(["repositories"], {});
+    for (const repository of repositories)
+        document.setIn(["repositories", repository.id], repository.path);
+    if (system)
+        document.setIn(["systemManifests", system.id], {
+            layout: system.layout,
+            manifests: system.manifests,
+        });
+    return document.toString({ lineWidth: 0 });
+}
+export function planSystemLink(options) {
+    const systemId = safeId(options.systemId, "system id");
+    if (options.repositories.length === 0)
+        throw new Error("system link requires at least one repository");
+    const overrides = options.repositoryIds ?? {};
+    const repositories = options.repositories.map((value) => {
+        const checkout = assertCheckout(value);
+        const id = safeId(repositoryOverride(overrides, value) ?? checkoutId(checkout), "repository id");
+        const component = options.components?.[id] ?? {};
+        return {
+            id,
+            path: checkout,
+            componentId: safeId(component.id ?? id, "component id"),
+            componentType: component.type ?? "component",
+        };
+    });
+    const collisions = repositories.filter((repository, index) => repositories.findIndex(({ id }) => id === repository.id) !== index);
+    if (collisions.length)
+        throw new Error(`repository id collision for ${collisions[0]?.id}; provide an explicit override`);
+    const scope = options.scope ?? "personal";
+    const files = [];
+    if (scope === "personal") {
+        const root = path.join(configHome(options.xdgConfigHome), "knodin");
+        files.push({
+            path: path.join(root, "systems", `${systemId}.yaml`),
+            content: yamlForSystem(systemId, repositories),
+            change: `declare personal system ${systemId}`,
+        });
+        const mappings = path.join(root, "repositories.yaml");
+        files.push({
+            path: mappings,
+            content: mappingsYaml(repositories, mappings),
+            change: "register personal checkout paths",
+        });
+    }
+    else if (options.distributed) {
+        for (const repository of repositories)
+            files.push({
+                path: path.join(repository.path, "knodin.yaml"),
+                content: teamYamlForSystem(path.join(repository.path, "knodin.yaml"), systemId, repositories),
+                change: `declare distributed fragment ${systemId}`,
+            });
+        const registry = path.join(configHome(options.xdgConfigHome), "knodin", "repositories.yaml");
+        files.push({
+            path: registry,
+            content: mappingsYaml(repositories, registry, {
+                id: systemId,
+                layout: "distributed",
+                manifests: repositories.map(({ path: checkout }) => path.join(checkout, "knodin.yaml")),
+            }),
+            change: `register distributed team system ${systemId}`,
+        });
+    }
+    else {
+        const central = repositories[0];
+        if (!central)
+            throw new Error("system link requires a central repository");
+        const target = path.join(central.path, "knodin.yaml");
+        files.push({
+            path: target,
+            content: teamYamlForSystem(target, systemId, repositories),
+            change: `declare central team system ${systemId}`,
+        });
+        const registry = path.join(configHome(options.xdgConfigHome), "knodin", "repositories.yaml");
+        files.push({
+            path: registry,
+            content: mappingsYaml(repositories, registry, {
+                id: systemId,
+                layout: "central",
+                manifests: [target],
+            }),
+            change: `register central team system ${systemId}`,
+        });
+    }
+    return protectPlan({
+        applied: false,
+        action: "link",
+        systemId,
+        files,
+        changes: files.map(({ change }) => change),
+    });
+}
+function assertSafeWrite(filePath) {
+    // Refuse the mutable destination and its managed parent. Platform paths may
+    // legitimately contain aliases above the caller-selected config/repository
+    // root (for example macOS /var -> /private/var), so do not reject ancestors
+    // outside knodin's ownership boundary.
+    try {
+        if (fs.lstatSync(path.dirname(filePath)).isSymbolicLink())
+            throw new Error(`${filePath}: refusing symbolic-link target`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    try {
+        if (fs.lstatSync(filePath).isSymbolicLink())
+            throw new Error(`${filePath}: refusing symbolic-link target`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+export function applySystemPlan(plan) {
+    for (const file of plan.files)
+        assertSafeWrite(file.path);
+    for (const file of plan.files)
+        if (file.expectedDigest !== undefined && fileDigest(file.path) !== file.expectedDigest)
+            throw new Error(`${file.path}: changed after preview; create a new plan`);
+    for (const file of plan.files) {
+        if (file.remove) {
+            fs.rmSync(file.path, { force: true });
+            continue;
+        }
+        fs.mkdirSync(path.dirname(file.path), { recursive: true });
+        const temporary = `${file.path}.tmp-${process.pid}-${crypto.randomUUID()}`;
+        fs.writeFileSync(temporary, file.content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        fs.renameSync(temporary, file.path);
+    }
+    return { ...plan, status: "applied", applied: true };
+}
+function parseEvidence(value) {
+    const match = /^([^:]+):(.+):(\d+)$/.exec(value);
+    if (!match)
+        throw new Error("evidence must be <repo-id>:<repository-relative-path>:<line>");
+    const line = Number(match[3]);
+    if (!Number.isSafeInteger(line) || line < 1)
+        throw new Error("evidence line must be a positive integer");
+    const repository = match[1];
+    const file = match[2];
+    if (!repository || !file)
+        throw new Error("evidence must name a repository and path");
+    if (path.isAbsolute(file) || file.split(/[\\/]/).includes(".."))
+        throw new Error("evidence path must be repository-relative");
+    return { repository: safeId(repository, "evidence repository id"), file, line };
+}
+function tracked(checkout, relative) {
+    const result = child_process.spawnSync("git", ["-C", checkout, "ls-files", "--error-unmatch", "--", relative], { stdio: "ignore" });
+    return result.status === 0;
+}
+export function planSystemRelate(options) {
+    if (!RELATIONSHIP_TYPES.includes(options.type))
+        throw new Error(`unsupported relationship type: ${options.type}`);
+    const evidence = parseEvidence(options.evidence);
+    const root = path.resolve(options.repoPath);
+    const config = loadSystemConfiguration(root, { xdgConfigHome: options.xdgConfigHome });
+    const system = config.systems.find(({ id }) => id === options.systemId);
+    if (!system)
+        throw new Error(`system was not found: ${options.systemId}`);
+    const evidenceRepository = config.repositories.find(({ id }) => id === evidence.repository);
+    if (!evidenceRepository)
+        throw new Error(`evidence repository is not a system member: ${evidence.repository}`);
+    const evidenceRoot = path.resolve(evidenceRepository.path ?? root);
+    const evidencePath = path.join(evidenceRoot, evidence.file);
+    const relative = path.relative(evidenceRoot, evidencePath);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error("evidence escapes repository");
+    const lines = fs.readFileSync(evidencePath, "utf8").split(/\r?\n/);
+    if (evidence.line > lines.length || (evidence.line === lines.length && lines.at(-1) === ""))
+        throw new Error(`evidence line ${evidence.line} does not exist in ${evidence.file}`);
+    if (!tracked(evidenceRoot, evidence.file))
+        throw new Error(`evidence file is not tracked: ${evidence.file}`);
+    const componentIds = new Set(system.components.map(({ id }) => id));
+    if (!componentIds.has(options.from) || !componentIds.has(options.to))
+        throw new Error("relationship direction must reference two declared components");
+    const personalTarget = personalSystemPath(options.systemId, options.xdgConfigHome);
+    const evidenceFragment = path.join(evidenceRoot, "knodin.yaml");
+    let target = path.join(root, "knodin.yaml");
+    if (fs.existsSync(personalTarget))
+        target = personalTarget;
+    else if (evidenceRoot !== root && fs.existsSync(evidenceFragment)) {
+        const fragment = parseDocument(fs.readFileSync(evidenceFragment, "utf8"), { uniqueKeys: true });
+        const fragmentSystems = fragment.toJS().systems ?? [];
+        if (fragmentSystems.some(({ id }) => id === options.systemId))
+            target = evidenceFragment;
+    }
+    const document = parseDocument(fs.readFileSync(target, "utf8"), { uniqueKeys: true });
+    if (document.errors.length)
+        throw new Error(`${target}: ${document.errors[0]?.message}`);
+    const relationships = document.get("relationships", true);
+    const relation = {
+        type: options.type,
+        from: safeId(options.from, "from component"),
+        to: safeId(options.to, "to component"),
+        evidence: { repository: evidence.repository, path: evidence.file, line: evidence.line },
+    };
+    if (relationships)
+        relationships.add(relation);
+    else
+        document.set("relationships", [relation]);
+    return protectPlan({
+        applied: false,
+        action: "relate",
+        systemId: options.systemId,
+        files: [
+            {
+                path: target,
+                content: document.toString({ lineWidth: 0 }),
+                change: `${options.type} ${options.from} -> ${options.to}`,
+            },
+        ],
+        changes: [
+            `add ${options.type} ${options.from} -> ${options.to} evidenced by ${options.evidence}`,
+        ],
+    });
+}
+function personalSystemPath(systemId, xdgConfigHome) {
+    return path.join(configHome(xdgConfigHome), "knodin", "systems", `${safeId(systemId, "system id")}.yaml`);
+}
+function writableSystemPath(systemId, repoPath, xdgConfigHome) {
+    const personal = personalSystemPath(systemId, xdgConfigHome);
+    if (fs.existsSync(personal) || !repoPath)
+        return personal;
+    return path.join(path.resolve(repoPath), "knodin.yaml");
+}
+export function planSystemUnlink(options) {
+    const target = writableSystemPath(options.systemId, options.repoPath, options.xdgConfigHome);
+    const personal = target === personalSystemPath(options.systemId, options.xdgConfigHome);
+    const document = parseDocument(fs.readFileSync(target, "utf8"), { uniqueKeys: true });
+    if (document.errors.length)
+        throw new Error(`${target}: ${document.errors[0]?.message}`);
+    const selected = new Set(options.repositories ?? []);
+    if (selected.size === 0) {
+        if (!personal) {
+            const root = document.toJS();
+            const removed = root.systems?.find(({ id }) => id === options.systemId);
+            if (!removed)
+                throw new Error(`system was not found: ${options.systemId}`);
+            const removedComponents = new Set((removed.components ?? []).map(({ id }) => id));
+            root.systems = (root.systems ?? []).filter(({ id }) => id !== options.systemId);
+            root.relationships = (root.relationships ?? []).filter(({ from, to }) => !removedComponents.has(from) && !removedComponents.has(to));
+            const usedRepositories = new Set(root.systems.flatMap(({ components }) => (components ?? []).flatMap(({ repository }) => (repository ? [repository] : []))));
+            root.repositories = (root.repositories ?? []).filter(({ id }) => id !== undefined && usedRepositories.has(id));
+            document.set("systems", root.systems);
+            document.set("relationships", root.relationships);
+            document.set("repositories", root.repositories);
+            return protectPlan({
+                applied: false,
+                action: "unlink",
+                systemId: options.systemId,
+                files: [
+                    {
+                        path: target,
+                        content: document.toString({ lineWidth: 0 }),
+                        change: `remove team system ${options.systemId}`,
+                    },
+                ],
+                changes: [`remove team system ${options.systemId}`],
+            });
+        }
+        return protectPlan({
+            applied: false,
+            action: "unlink",
+            systemId: options.systemId,
+            files: [
+                {
+                    path: target,
+                    content: "",
+                    change: `remove personal system ${options.systemId}`,
+                    remove: true,
+                },
+            ],
+            changes: [`remove personal system ${options.systemId}`],
+        });
+    }
+    const root = document.toJS();
+    const system = (root.systems ?? []).find(({ id }) => id === options.systemId);
+    if (!system)
+        throw new Error(`system was not found: ${options.systemId}`);
+    const removedComponents = new Set((system.components ?? [])
+        .filter(({ repository }) => repository !== undefined && selected.has(repository))
+        .flatMap(({ id }) => (id ? [id] : [])));
+    system.components = (system.components ?? []).filter(({ repository }) => repository === undefined || !selected.has(repository));
+    root.relationships = (root.relationships ?? []).filter(({ from, to }) => (from === undefined || !removedComponents.has(from)) &&
+        (to === undefined || !removedComponents.has(to)));
+    const usedRepositories = new Set((root.systems ?? []).flatMap(({ components }) => (components ?? []).flatMap(({ repository }) => (repository ? [repository] : []))));
+    root.repositories = (root.repositories ?? []).filter(({ id }) => id !== undefined && usedRepositories.has(id));
+    document.set("repositories", root.repositories);
+    document.set("systems", root.systems ?? []);
+    document.set("relationships", root.relationships ?? []);
+    return protectPlan({
+        applied: false,
+        action: "unlink",
+        systemId: options.systemId,
+        files: [
+            {
+                path: target,
+                content: document.toString({ lineWidth: 0 }),
+                change: `unlink ${[...selected].join(", ")}`,
+            },
+        ],
+        changes: [`unlink repositories ${[...selected].join(", ")}`],
+    });
+}
+export function planSystemUnrelate(options) {
+    const target = writableSystemPath(options.systemId, options.repoPath, options.xdgConfigHome);
+    const document = parseDocument(fs.readFileSync(target, "utf8"), { uniqueKeys: true });
+    const root = document.toJS();
+    const before = root.relationships ?? [];
+    const after = before.filter((relationship) => relationship.type !== options.type ||
+        relationship.from !== options.from ||
+        relationship.to !== options.to);
+    if (after.length === before.length)
+        throw new Error("relationship was not found");
+    document.set("relationships", after);
+    return protectPlan({
+        applied: false,
+        action: "unrelate",
+        systemId: options.systemId,
+        files: [
+            {
+                path: target,
+                content: document.toString({ lineWidth: 0 }),
+                change: `remove ${options.type} ${options.from} -> ${options.to}`,
+            },
+        ],
+        changes: [`remove ${options.type} ${options.from} -> ${options.to}`],
+    });
+}
+export function planSystemImport(options) {
+    const source = path.resolve(options.manifestPath);
+    const document = parseDocument(fs.readFileSync(source, "utf8"), { uniqueKeys: true });
+    if (document.errors.length)
+        throw new Error(`${source}: ${document.errors[0]?.message}`);
+    const systems = document.toJS().systems ?? [];
+    if (systems.length !== 1 || !systems[0]?.id)
+        throw new Error("system import requires exactly one named system");
+    const systemId = safeId(systems[0].id, "system id");
+    const target = options.scope === "team"
+        ? path.join(path.resolve(options.repoPath), "knodin.yaml")
+        : personalSystemPath(systemId, options.xdgConfigHome);
+    let content = document.toString({ lineWidth: 0 });
+    if (options.scope === "team") {
+        let targetDocument;
+        try {
+            targetDocument = parseDocument(fs.readFileSync(target, "utf8"), { uniqueKeys: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            targetDocument = parseDocument("schemaVersion: 1\n");
+        }
+        if (targetDocument.errors.length)
+            throw new Error(`${target}: ${targetDocument.errors[0]?.message}`);
+        const imported = document.toJS();
+        const current = targetDocument.toJS();
+        const mergeByIdentity = (existing, incoming, identity) => {
+            const values = new Map(existing.map((value) => [identity(value), value]));
+            for (const value of incoming) {
+                const key = identity(value);
+                const prior = values.get(key);
+                if (prior && JSON.stringify(prior) !== JSON.stringify(value))
+                    throw new Error(`${target}: conflicting imported declaration ${key}`);
+                values.set(key, value);
+            }
+            return [...values.values()];
+        };
+        targetDocument.set("repositories", mergeByIdentity(current.repositories ?? [], imported.repositories ?? [], (value) => String(value.id)));
+        targetDocument.set("systems", mergeByIdentity(current.systems ?? [], imported.systems ?? [], (value) => String(value.id)));
+        targetDocument.set("relationships", mergeByIdentity(current.relationships ?? [], imported.relationships ?? [], (value) => `${value.type}:${value.from}:${value.to}`));
+        content = targetDocument.toString({ lineWidth: 0 });
+    }
+    return protectPlan({
+        applied: false,
+        action: "import",
+        systemId,
+        files: [
+            {
+                path: target,
+                content,
+                change: `import system ${systemId}`,
+            },
+        ],
+        changes: [`import system ${systemId} from ${source}`],
+    });
+}