knodin 0.8.6 → 0.8.7

package/dist/src/skill-management.js

@@ -0,0 +1,149 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const KNODIN_SKILLS = [
+    "knodin-explore",
+    "knodin-debug",
+    "knodin-impact",
+    "knodin-refactor",
+    "knodin-review",
+    "knodin-systems",
+    "knodin-lifecycle",
+];
+const MANIFEST = ".knodin-managed.json";
+function canonicalRoot() {
+    const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(moduleDirectory, "..", "skills"),
+        path.resolve(moduleDirectory, "..", "..", "skills"),
+    ];
+    const root = candidates.find((candidate) => fs.existsSync(candidate));
+    if (!root)
+        throw new Error("knodin packaged skills are missing");
+    return root;
+}
+function destinationRoot(client, scope, repo, home) {
+    if (scope === "team") {
+        if (client === "codex")
+            return path.join(repo, ".agents", "skills");
+        if (client === "claude")
+            return path.join(repo, ".claude", "skills");
+        return path.join(repo, ".gemini", "skills");
+    }
+    if (client === "codex")
+        return path.join(home, ".agents", "skills");
+    if (client === "claude")
+        return path.join(home, ".claude", "skills");
+    return path.join(home, ".gemini", "skills");
+}
+function sourceDigest(source) {
+    const hash = crypto.createHash("sha256");
+    for (const relative of ["SKILL.md", path.join("agents", "openai.yaml")])
+        hash.update(fs.readFileSync(path.join(source, relative)));
+    return hash.digest("hex");
+}
+function managedState(target) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(target, MANIFEST), "utf8"));
+        if (manifest.owner !== "knodin")
+            return "unmanaged";
+        return manifest.digest === sourceDigest(target) ? "managed" : "modified";
+    }
+    catch {
+        return "unmanaged";
+    }
+}
+export function installKnodinSkills(options) {
+    const result = {
+        scope: options.scope,
+        installed: [],
+        removed: [],
+        unchanged: [],
+        issues: [],
+    };
+    if (options.scope === "cli-only")
+        return result;
+    const home = options.home ?? os.homedir();
+    for (const client of options.clients) {
+        const root = destinationRoot(client, options.scope, path.resolve(options.repo), home);
+        for (const name of KNODIN_SKILLS) {
+            const source = path.join(canonicalRoot(), name);
+            const target = path.join(root, name);
+            const digest = sourceDigest(source);
+            if (fs.existsSync(target)) {
+                const state = managedState(target);
+                if (state !== "managed") {
+                    result.issues.push({
+                        path: target,
+                        message: `${state} skill collision; left unchanged`,
+                    });
+                    continue;
+                }
+            }
+            try {
+                const current = JSON.parse(fs.readFileSync(path.join(target, MANIFEST), "utf8"));
+                if (current.digest === digest) {
+                    result.unchanged.push(target);
+                    continue;
+                }
+            }
+            catch {
+                // Missing managed version is installed below.
+            }
+            result.installed.push(target);
+            if (options.dryRun)
+                continue;
+            fs.mkdirSync(root, { recursive: true });
+            const temporary = path.join(root, `.${name}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`);
+            fs.cpSync(source, temporary, { recursive: true, errorOnExist: true });
+            fs.writeFileSync(path.join(temporary, MANIFEST), `${JSON.stringify({ owner: "knodin", digest, client }, null, 2)}\n`);
+            if (fs.existsSync(target))
+                fs.renameSync(target, `${temporary}.old`);
+            fs.renameSync(temporary, target);
+            fs.rmSync(`${temporary}.old`, { recursive: true, force: true });
+        }
+    }
+    return result;
+}
+export function removeKnodinSkills(options) {
+    const result = {
+        scope: options.scope,
+        installed: [],
+        removed: [],
+        unchanged: [],
+        issues: [],
+    };
+    const home = options.home ?? os.homedir();
+    for (const client of options.clients) {
+        const root = destinationRoot(client, options.scope, path.resolve(options.repo), home);
+        for (const name of KNODIN_SKILLS) {
+            const target = path.join(root, name);
+            if (!fs.existsSync(target))
+                continue;
+            const state = managedState(target);
+            if (state !== "managed") {
+                result.issues.push({ path: target, message: `${state} skill collision; left unchanged` });
+                continue;
+            }
+            result.removed.push(target);
+            if (!options.dryRun)
+                fs.rmSync(target, { recursive: true });
+        }
+        if (!options.dryRun) {
+            try {
+                fs.rmdirSync(root);
+                fs.rmdirSync(path.dirname(root));
+            }
+            catch (error) {
+                if (!["ENOENT", "ENOTEMPTY"].includes(error.code ?? ""))
+                    throw error;
+            }
+        }
+    }
+    return result;
+}
+export function inspectKnodinSkills(options) {
+    return installKnodinSkills({ ...options, dryRun: true });
+}

package/dist/src/system-config.js

@@ -190,6 +190,113 @@ function applyPersonalMappings(repositories, xdgConfigHome) {
         repository.pathSource = "personal-config";
     }
 }
+function personalSystemDocuments(repo, xdgConfigHome) {
+    const knodin = path.join(xdgConfigHome, "knodin");
+    const personal = asRecord(optionalYaml(path.join(knodin, "repositories.yaml")));
+    const mappings = asRecord(personal.repositories);
+    const localIds = new Set(Object.entries(mappings)
+        .filter(([, checkout]) => typeof checkout === "string" && path.resolve(checkout) === repo)
+        .map(([id]) => id));
+    if (localIds.size === 0)
+        return [];
+    let names;
+    try {
+        names = fs.readdirSync(path.join(knodin, "systems"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const systemRoot = path.join(knodin, "systems");
+    const manifestPaths = names.flatMap((name) => {
+        const candidate = path.join(systemRoot, name);
+        if (name.endsWith(".yaml") || name.endsWith(".yml"))
+            return [candidate];
+        try {
+            if (!fs.statSync(candidate).isDirectory())
+                return [];
+            const nested = path.join(candidate, "knodin.yaml");
+            return fs.existsSync(nested) ? [nested] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    const sortedManifestPaths = [...manifestPaths];
+    sortedManifestPaths.sort(compareBytes);
+    return sortedManifestPaths
+        .flatMap((manifest) => {
+        try {
+            return [asRecord(readYaml(manifest))];
+        }
+        catch (error) {
+            const source = fs.readFileSync(manifest, "utf8");
+            if ([...localIds].some((id) => source.includes(id)))
+                throw error;
+            return [];
+        }
+    })
+        .filter((document) => {
+        const repositories = Array.isArray(document.repositories) ? document.repositories : [];
+        return repositories.some((value) => localIds.has(String(asRecord(value).id ?? "")));
+    });
+}
+function registeredSystemDocuments(repo, xdgConfigHome) {
+    const personal = asRecord(optionalYaml(path.join(xdgConfigHome, "knodin", "repositories.yaml")));
+    const mappings = asRecord(personal.repositories);
+    const localIds = new Set(Object.entries(mappings)
+        .filter(([, checkout]) => typeof checkout === "string" && path.resolve(checkout) === repo)
+        .map(([id]) => id));
+    if (localIds.size === 0)
+        return [];
+    const manifests = asRecord(personal.systemManifests);
+    const documents = [];
+    for (const registration of Object.values(manifests)) {
+        const record = asRecord(registration);
+        const paths = Array.isArray(record.manifests) ? record.manifests : [];
+        for (const manifest of paths) {
+            if (typeof manifest !== "string" || !path.isAbsolute(manifest) || !fs.existsSync(manifest))
+                continue;
+            const document = asRecord(readYaml(manifest));
+            const participates = (Array.isArray(document.repositories) ? document.repositories : []).some((value) => localIds.has(String(asRecord(value).id ?? "")));
+            if (participates)
+                documents.push(document);
+        }
+    }
+    return documents;
+}
+function availableTeamFragments(team, repo, xdgConfigHome) {
+    const systemIds = new Set((Array.isArray(team.systems) ? team.systems : []).map((value) => String(asRecord(value).id ?? "")));
+    if (systemIds.size === 0)
+        return [];
+    const personal = asRecord(optionalYaml(path.join(xdgConfigHome, "knodin", "repositories.yaml")));
+    const mappings = asRecord(personal.repositories);
+    const documents = [];
+    for (const checkout of Object.values(mappings)) {
+        if (typeof checkout !== "string" || path.resolve(checkout) === repo)
+            continue;
+        const manifest = path.join(checkout, "knodin.yaml");
+        if (!fs.existsSync(manifest))
+            continue;
+        const document = asRecord(readYaml(manifest));
+        const overlaps = (Array.isArray(document.systems) ? document.systems : []).some((value) => systemIds.has(String(asRecord(value).id ?? "")));
+        if (overlaps)
+            documents.push(document);
+    }
+    return documents;
+}
+function deduplicateDeclarations(values, kind) {
+    const unique = new Map();
+    for (const value of values) {
+        const existing = unique.get(value.id);
+        if (!existing)
+            unique.set(value.id, value);
+        else if (JSON.stringify(existing) !== JSON.stringify(value))
+            throw new Error(`conflicting ${kind} identity ${value.id} across available system fragments`);
+    }
+    return [...unique.values()];
+}
 function configuredCheckout(repository, repositories, repo) {
     if (repository.path)
         return repository.path;
@@ -313,6 +420,11 @@ function declaredRelationship(value, index) {
     const from = stringValue(record.from, `relationships[${index}].from`);
     const to = stringValue(record.to, `relationships[${index}].to`);
     const source = asRecord(record.evidence);
+    const evidenceRepository = typeof source.repository === "string" && source.repository ? source.repository : undefined;
+    const evidencePath = typeof source.path === "string" && source.path ? source.path : undefined;
+    const evidenceLine = typeof source.line === "number" && Number.isSafeInteger(source.line) && source.line > 0
+        ? source.line
+        : undefined;
     const confidence = typeof source.confidence === "number" && source.confidence >= 0 && source.confidence <= 1
         ? source.confidence
         : 1;
@@ -322,7 +434,14 @@ function declaredRelationship(value, index) {
         to,
         targetIdentity: to,
         evidence: {
-            location: typeof source.location === "string" && source.location ? source.location : "knodin.yaml",
+            location: typeof source.location === "string" && source.location
+                ? source.location
+                : evidencePath
+                    ? `${evidenceRepository ? `${evidenceRepository}:` : ""}${evidencePath}${evidenceLine ? `:${evidenceLine}` : ""}`
+                    : "knodin.yaml",
+            ...(evidenceRepository ? { repository: evidenceRepository } : {}),
+            ...(evidencePath ? { path: evidencePath } : {}),
+            ...(evidenceLine ? { line: evidenceLine } : {}),
             adapter: "knodin-yaml",
             kind: "declared",
             confidence,
@@ -337,11 +456,31 @@ export function loadSystemConfiguration(repoPath, options = {}) {
     if (team.schemaVersion !== undefined && team.schemaVersion !== 1) {
         throw new Error("knodin.yaml: schemaVersion must be 1");
     }
-    const repositories = (Array.isArray(team.repositories) ? team.repositories : []).map((value, index) => configuredRepository(value, index));
-    const systems = (Array.isArray(team.systems) ? team.systems : []).map((value, index) => configuredSystem(value, index));
-    const relationships = (Array.isArray(team.relationships) ? team.relationships : []).map((value, index) => declaredRelationship(value, index));
-    const initialization = repositoryInitialization(team.repositoryInitialization);
     const xdgConfigHome = options.xdgConfigHome ?? process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+    const documents = [
+        team,
+        ...availableTeamFragments(team, repo, xdgConfigHome),
+        ...registeredSystemDocuments(repo, xdgConfigHome),
+        ...personalSystemDocuments(repo, xdgConfigHome),
+    ];
+    const repositories = deduplicateDeclarations(documents
+        .flatMap((document) => (Array.isArray(document.repositories) ? document.repositories : []))
+        .map((value, index) => configuredRepository(value, index)), "repository");
+    const systems = deduplicateDeclarations(documents
+        .flatMap((document) => (Array.isArray(document.systems) ? document.systems : []))
+        .map((value, index) => configuredSystem(value, index)), "system");
+    const relationships = documents
+        .flatMap((document) => (Array.isArray(document.relationships) ? document.relationships : []))
+        .map((value, index) => declaredRelationship(value, index));
+    const declaredIdentities = new Map();
+    for (const relationship of relationships) {
+        const identity = `${relationship.type}\0${relationship.from}\0${relationship.to}`;
+        const existing = declaredIdentities.get(identity);
+        if (existing && JSON.stringify(existing.evidence) !== JSON.stringify(relationship.evidence))
+            throw new Error(`conflicting relationship ${relationship.type} ${relationship.from} -> ${relationship.to} across available system fragments`);
+        declaredIdentities.set(identity, relationship);
+    }
+    const initialization = repositoryInitialization(team.repositoryInitialization);
     applyPersonalMappings(repositories, xdgConfigHome);
     const legacyFederation = applyLegacyFederation(repo, repositories, relationships);
     for (const repository of repositories) {
@@ -485,34 +624,55 @@ export async function validateSystemHealth(config, systemId, status, defaultRepo
     }
     return { valid: issues.length === 0, requiresPartial: issues.length > 0, issues };
 }
-export function queryConfiguredSystem(config, systemId, allowPartial = false, healthValidation) {
+export function queryConfiguredSystem(config, systemId, requireComplete = false, healthValidation) {
     const system = config.systems.find(({ id }) => id === systemId);
     if (!system) {
         return { status: "not-found", systemId, available: config.systems.map(({ id }) => id) };
     }
     const validation = healthValidation ?? validateSystemConfiguration(config);
-    if (!validation.valid && !allowPartial) {
+    const componentRepository = new Map(system.components.flatMap(({ id, repository }) => repository ? [[id, repository]] : []));
+    const unavailableRepositories = new Set(validation.issues.flatMap(({ code, identity }) => {
+        if (code === "unresolved-repository" || code === "missing-checkout")
+            return [identity];
+        if (code === "unavailable-component") {
+            const repository = componentRepository.get(identity);
+            return repository ? [repository] : [];
+        }
+        return [];
+    }));
+    if (!validation.valid && requireComplete) {
         return {
             status: "unavailable",
             systemId,
             relationships: [],
+            omittedRelationships: [],
+            unavailableRepositories: [...unavailableRepositories].sort(compareBytes),
             omissions: validation.issues,
         };
     }
-    const unavailableRepositories = new Set(validation.issues
-        .filter(({ code }) => code === "unresolved-repository" || code === "missing-checkout")
-        .map(({ identity }) => identity));
-    const omittedComponents = new Set(system.components
-        .filter(({ repository }) => repository !== undefined && unavailableRepositories.has(repository))
-        .map(({ id }) => id));
+    const omittedComponents = new Set([
+        ...system.components
+            .filter(({ repository }) => repository !== undefined && unavailableRepositories.has(repository))
+            .map(({ id }) => id),
+        ...validation.issues
+            .filter(({ code }) => code === "unavailable-component")
+            .map(({ identity }) => identity),
+    ]);
     const componentIds = new Set(system.components.map(({ id }) => id));
-    const relationships = config.relationships.filter(({ from, to }) => (componentIds.has(from) || componentIds.has(to)) &&
-        !omittedComponents.has(from) &&
-        !omittedComponents.has(to));
+    const relevantRelationships = config.relationships.filter(({ from, to }) => componentIds.has(from) || componentIds.has(to));
+    const invalidRelationships = new Set(validation.issues
+        .filter(({ code }) => ["invalid-relationship", "low-confidence-relationship", "configuration-drift"].includes(code))
+        .map(({ identity }) => identity));
+    const relationships = relevantRelationships.filter(({ from, to }) => !omittedComponents.has(from) &&
+        !omittedComponents.has(to) &&
+        !invalidRelationships.has(`${from}->${to}`));
+    const returned = new Set(relationships);
     return {
         status: validation.valid ? "ok" : "partial",
         systemId,
         relationships,
+        omittedRelationships: relevantRelationships.filter((relationship) => !returned.has(relationship)),
+        unavailableRepositories: [...unavailableRepositories].sort(compareBytes),
         omissions: validation.issues,
     };
 }