@microck/canonfig 2.0.0 → 2.1.0

package/dist/harness-configuration/core/compiler.js

@@ -0,0 +1,175 @@
+import path from "node:path";
+import { BUILTIN_ADAPTERS } from "../adapters/index.js";
+import { commonArtifacts, enabledMcpServerEntries } from "../adapters/shared.js";
+import { configuredTargets, findRepositoryRoot, loadConfig, targetOptions } from "./config.js";
+import { CanonfigError } from "./errors.js";
+import { sha256 } from "./hash.js";
+import { createPlan } from "./planner.js";
+import { validateProject } from "./validation.js";
+const FEATURE_LEVEL_WEIGHT = {
+    native: 0,
+    portable: 0,
+    translated: 1,
+    shim: 2,
+    lossy: 3,
+    unsupported: 4,
+};
+function usedFeatures(config) {
+    const used = ["instructions"];
+    if (config.instructions.rules.length > 0)
+        used.push("rules");
+    if (config.skills.roots.length > 0)
+        used.push("skills");
+    if (Object.keys(config.mcp.servers).length > 0)
+        used.push("mcp");
+    if (config.hooks.length > 0)
+        used.push("hooks");
+    if (config.agents.length > 0)
+        used.push("agents");
+    if (config.commands.length > 0)
+        used.push("commands");
+    if (config.permissions.rules.length > 0)
+        used.push("permissions");
+    return used;
+}
+function compatibilityDiagnostics(descriptor, features, strict) {
+    return features.flatMap((feature) => {
+        const support = descriptor.capabilities[feature];
+        if (support === "native" || support === "portable")
+            return [];
+        const strictFailure = strict && FEATURE_LEVEL_WEIGHT[support] >= FEATURE_LEVEL_WEIGHT.shim;
+        const unsupported = support === "unsupported";
+        return [{
+                level: unsupported || strictFailure ? "error" : support === "translated" ? "info" : "warning",
+                code: `FEATURE_${support.toUpperCase()}`,
+                target: descriptor.id,
+                message: `${descriptor.name}: ${feature} support is ${support}.`,
+            }];
+    });
+}
+function commonMcpProjectionDiagnostics(context) {
+    const diagnostics = [];
+    for (const [name, server] of enabledMcpServerEntries(context)) {
+        const omitted = [];
+        if (server.timeoutMs !== undefined)
+            omitted.push("timeoutMs");
+        if (server.enabledTools?.length)
+            omitted.push("enabledTools");
+        if (server.disabledTools?.length)
+            omitted.push("disabledTools");
+        if (omitted.length > 0) {
+            diagnostics.push({
+                level: "warning",
+                code: "MCP_OPTION_UNSUPPORTED",
+                path: ".mcp.json",
+                message: `.mcp.json cannot represent ${omitted.join(", ")} for MCP server ${name}; those options were omitted.`,
+            });
+        }
+    }
+    return diagnostics;
+}
+function deduplicateExactReplaceArtifacts(artifacts) {
+    const seen = new Set();
+    const result = [];
+    for (const artifact of artifacts) {
+        if (artifact.kind !== "replace") {
+            result.push(artifact);
+            continue;
+        }
+        const identity = [
+            artifact.owner,
+            artifact.path,
+            artifact.mode ?? "",
+            sha256(artifact.content),
+        ].join("\0");
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        result.push(artifact);
+    }
+    return result;
+}
+export class AdapterRegistry {
+    #adapters = new Map();
+    constructor(adapters = []) {
+        for (const adapter of adapters)
+            this.register(adapter);
+    }
+    register(adapter) {
+        if (this.#adapters.has(adapter.descriptor.id)) {
+            throw new CanonfigError("ADAPTER_DUPLICATE", `An adapter is already registered for ${adapter.descriptor.id}.`);
+        }
+        this.#adapters.set(adapter.descriptor.id, adapter);
+        return this;
+    }
+    replace(adapter) {
+        this.#adapters.set(adapter.descriptor.id, adapter);
+        return this;
+    }
+    get(id) {
+        const adapter = this.#adapters.get(id);
+        if (!adapter)
+            throw new CanonfigError("ADAPTER_MISSING", `No adapter is registered for ${id}.`);
+        return adapter;
+    }
+    list() {
+        return [...this.#adapters.values()].sort((left, right) => left.descriptor.id.localeCompare(right.descriptor.id));
+    }
+}
+export function createDefaultRegistry() {
+    return new AdapterRegistry(BUILTIN_ADAPTERS);
+}
+export class HarnessConfigurationCompiler {
+    registry;
+    constructor(registry = createDefaultRegistry()) {
+        this.registry = registry;
+    }
+    async build(options = {}) {
+        const root = options.root
+            ? path.resolve(options.root)
+            : await findRepositoryRoot(options.cwd ?? process.cwd());
+        const loaded = await loadConfig(root);
+        const targets = [...new Set(options.targets ?? configuredTargets(loaded.config))];
+        if (targets.length === 0)
+            throw new CanonfigError("TARGET_EMPTY", "No enabled targets were selected.");
+        const diagnostics = await validateProject(root, loaded.config);
+        const artifacts = [];
+        const commonContext = {
+            root,
+            canonfigDir: path.join(root, ".canonfig"),
+            config: loaded.config,
+            target: targets[0],
+            targetOptions: {},
+        };
+        if (options.includeCommon !== false) {
+            artifacts.push(...await commonArtifacts(commonContext));
+            diagnostics.push(...commonMcpProjectionDiagnostics(commonContext));
+        }
+        const features = usedFeatures(loaded.config);
+        for (const target of targets) {
+            const adapter = this.registry.get(target);
+            diagnostics.push(...compatibilityDiagnostics(adapter.descriptor, features, options.strict ?? false));
+            const context = {
+                root,
+                canonfigDir: path.join(root, ".canonfig"),
+                config: loaded.config,
+                target,
+                targetOptions: targetOptions(loaded.config, target),
+            };
+            const result = await adapter.build(context);
+            artifacts.push(...result.artifacts);
+            diagnostics.push(...result.diagnostics);
+        }
+        return {
+            root,
+            configPath: loaded.path,
+            targets,
+            artifacts: deduplicateExactReplaceArtifacts(artifacts),
+            diagnostics,
+        };
+    }
+    async plan(options = {}) {
+        const built = await this.build(options);
+        return createPlan(built.root, built.targets, built.artifacts, built.diagnostics, { force: options.force ?? false });
+    }
+}

package/dist/harness-configuration/core/config.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { CanonfigConfigSchema } from "./schema.js";
+import { CanonfigError } from "./errors.js";
+import { TARGET_IDS } from "./types.js";
+export const CANONFIG_DIR = ".canonfig";
+export const CONFIG_FILENAMES = ["harness.yaml", "harness.yml", "harness.json"];
+export const STATE_FILENAME = ".harness-state.json";
+export async function findRepositoryRoot(start = process.cwd()) {
+    let current = path.resolve(start);
+    while (true) {
+        for (const filename of CONFIG_FILENAMES) {
+            try {
+                await fs.access(path.join(current, CANONFIG_DIR, filename));
+                return current;
+            }
+            catch { /* continue */ }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new CanonfigError("CONFIG_NOT_FOUND", `No ${CANONFIG_DIR}/harness.yaml found from ${path.resolve(start)} upward. Run \"canonfig harness init\" first.`);
+        }
+        current = parent;
+    }
+}
+export async function findConfigFile(root) {
+    for (const filename of CONFIG_FILENAMES) {
+        const candidate = path.join(root, CANONFIG_DIR, filename);
+        try {
+            await fs.access(candidate);
+            return candidate;
+        }
+        catch { /* continue */ }
+    }
+    throw new CanonfigError("CONFIG_NOT_FOUND", `Missing ${CANONFIG_DIR}/harness.yaml in ${root}`);
+}
+export async function loadConfig(root) {
+    const configPath = await findConfigFile(root);
+    const raw = await fs.readFile(configPath, "utf8");
+    let parsed;
+    try {
+        parsed = configPath.endsWith(".json") ? JSON.parse(raw) : YAML.parse(raw);
+    }
+    catch (error) {
+        throw new CanonfigError("CONFIG_PARSE", `Could not parse ${configPath}: ${String(error)}`, error);
+    }
+    const result = CanonfigConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const details = result.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("\n");
+        throw new CanonfigError("CONFIG_INVALID", `Invalid ${path.relative(root, configPath)}:\n${details}`, result.error);
+    }
+    return { config: result.data, path: configPath };
+}
+export function configuredTargets(config) {
+    if (Array.isArray(config.targets))
+        return [...config.targets];
+    const targetMap = config.targets;
+    return TARGET_IDS.filter((id) => targetMap[id]?.enabled === true);
+}
+export function targetOptions(config, target) {
+    const targetMap = config.targets;
+    const direct = Array.isArray(config.targets) ? {} : (targetMap[target]?.options ?? {});
+    return { ...direct, ...(config.extensions[target] ?? {}) };
+}
+export function parseTargetList(input) {
+    if (!input)
+        return undefined;
+    const values = input.split(",").map((value) => value.trim()).filter(Boolean);
+    const invalid = values.filter((value) => !TARGET_IDS.includes(value));
+    if (invalid.length > 0)
+        throw new CanonfigError("TARGET_INVALID", `Unknown target(s): ${invalid.join(", ")}`);
+    return [...new Set(values)];
+}

package/dist/harness-configuration/core/diff.js

@@ -0,0 +1,60 @@
+function lineDiff(before, after) {
+    const left = before.split("\n");
+    const right = after.split("\n");
+    const cells = (left.length + 1) * (right.length + 1);
+    if (cells > 1_500_000) {
+        return [
+            ...left.map((text) => ({ prefix: "-", text })),
+            ...right.map((text) => ({ prefix: "+", text })),
+        ];
+    }
+    const table = Array.from({ length: left.length + 1 }, () => new Uint32Array(right.length + 1));
+    for (let i = left.length - 1; i >= 0; i -= 1) {
+        for (let j = right.length - 1; j >= 0; j -= 1) {
+            table[i][j] = left[i] === right[j]
+                ? table[i + 1][j + 1] + 1
+                : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    const lines = [];
+    let i = 0;
+    let j = 0;
+    while (i < left.length && j < right.length) {
+        if (left[i] === right[j]) {
+            lines.push({ prefix: " ", text: left[i] });
+            i += 1;
+            j += 1;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1]) {
+            lines.push({ prefix: "-", text: left[i] });
+            i += 1;
+        }
+        else {
+            lines.push({ prefix: "+", text: right[j] });
+            j += 1;
+        }
+    }
+    while (i < left.length)
+        lines.push({ prefix: "-", text: left[i++] });
+    while (j < right.length)
+        lines.push({ prefix: "+", text: right[j++] });
+    return lines;
+}
+function diffEntry(entry) {
+    const header = [`--- a/${entry.path}`, `+++ b/${entry.path}`];
+    if (entry.action === "create") {
+        return [...header, ...(entry.after ?? "").split("\n").map((line) => `+${line}`)].join("\n");
+    }
+    if (entry.action === "delete") {
+        return [...header, ...(entry.before ?? "").split("\n").map((line) => `-${line}`)].join("\n");
+    }
+    if (entry.binary)
+        return [...header, `Binary file ${entry.action}`].join("\n");
+    return [...header, ...lineDiff(entry.before ?? "", entry.after ?? "").map((line) => `${line.prefix}${line.text}`)].join("\n");
+}
+export function formatPlanDiff(plan) {
+    return plan.entries
+        .filter((entry) => entry.action !== "unchanged")
+        .map(diffEntry)
+        .join("\n\n");
+}

package/dist/harness-configuration/core/doctor.js

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+function firstLine(value) {
+    const line = value.split(/\r?\n/, 1)[0]?.trim();
+    return line ? line : undefined;
+}
+export function doctorTargets(registry, targets) {
+    const selected = targets ? new Set(targets) : undefined;
+    return registry.list()
+        .filter((adapter) => !selected || selected.has(adapter.descriptor.id))
+        .map((adapter) => {
+        const descriptor = adapter.descriptor;
+        let lastError;
+        for (const executable of descriptor.executables) {
+            const result = spawnSync(executable, ["--version"], {
+                encoding: "utf8",
+                timeout: 4_000,
+                windowsHide: true,
+            });
+            if (!result.error && result.status === 0) {
+                const version = firstLine(result.stdout) ?? firstLine(result.stderr);
+                return {
+                    id: descriptor.id,
+                    name: descriptor.name,
+                    found: true,
+                    executable,
+                    ...(version ? { version } : {}),
+                    descriptor,
+                };
+            }
+            lastError = result.error?.message ?? firstLine(result.stderr) ?? `exit ${result.status ?? "unknown"}`;
+        }
+        return {
+            id: descriptor.id,
+            name: descriptor.name,
+            found: false,
+            ...(lastError ? { error: lastError } : {}),
+            descriptor,
+        };
+    });
+}

package/dist/harness-configuration/core/errors.js

@@ -0,0 +1,13 @@
+export class CanonfigError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "CanonfigError";
+        this.code = code;
+        this.details = details;
+    }
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/harness-configuration/core/filesystem.js

@@ -0,0 +1,172 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CanonfigError } from "./errors.js";
+let temporarySequence = 0;
+function relativeInside(root, candidate) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedCandidate = path.resolve(candidate);
+    const relative = path.relative(resolvedRoot, resolvedCandidate);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new CanonfigError("PATH_ESCAPE", `Path escapes repository root: ${candidate}`);
+    }
+    return { root: resolvedRoot, relative };
+}
+async function lstatOptional(filePath) {
+    try {
+        return await fs.lstat(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function openExclusiveTemporary(filePath, mode) {
+    for (;;) {
+        const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${temporarySequence++}.tmp`);
+        try {
+            return { temporary, handle: await fs.open(temporary, "wx", mode) };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+}
+export async function assertNoSymlinkPathComponents(root, candidate) {
+    const confined = relativeInside(root, candidate);
+    if (!confined.relative)
+        return;
+    let current = confined.root;
+    for (const component of confined.relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, component);
+        const stats = await lstatOptional(current);
+        if (stats === undefined)
+            return;
+        if (stats.isSymbolicLink()) {
+            throw new CanonfigError("SYMLINK_ESCAPE", `Path component is a symbolic link: ${current}`);
+        }
+    }
+}
+export async function ensureDirectoryNoFollow(root, directory) {
+    const confined = relativeInside(root, directory);
+    if (!confined.relative)
+        return;
+    let current = confined.root;
+    for (const component of confined.relative.split(path.sep).filter(Boolean)) {
+        await assertNoSymlinkPathComponents(confined.root, current);
+        current = path.join(current, component);
+        let stats = await lstatOptional(current);
+        if (stats === undefined) {
+            try {
+                await fs.mkdir(current);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+            stats = await lstatOptional(current);
+        }
+        if (stats === undefined) {
+            throw new CanonfigError("PATH_CREATE_FAILED", `Failed to create directory: ${current}`);
+        }
+        if (stats.isSymbolicLink()) {
+            throw new CanonfigError("SYMLINK_ESCAPE", `Path component is a symbolic link: ${current}`);
+        }
+        if (!stats.isDirectory()) {
+            throw new CanonfigError("PATH_COMPONENT_NOT_DIRECTORY", `Path component is not a directory: ${current}`);
+        }
+    }
+}
+export async function readOptionalFile(filePath) {
+    try {
+        return await fs.readFile(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function walkFiles(root) {
+    const result = [];
+    async function visit(directory) {
+        const entries = await fs.readdir(directory, { withFileTypes: true });
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            const absolute = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                await visit(absolute);
+            else if (entry.isFile())
+                result.push(path.relative(root, absolute));
+        }
+    }
+    try {
+        await visit(root);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    return result;
+}
+export async function atomicWrite(filePath, content, mode, root) {
+    if (root === undefined)
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+    else
+        await ensureDirectoryNoFollow(root, path.dirname(filePath));
+    let temporary;
+    try {
+        if (root !== undefined)
+            await assertNoSymlinkPathComponents(root, path.dirname(filePath));
+        const opened = await openExclusiveTemporary(filePath, mode);
+        temporary = opened.temporary;
+        try {
+            await opened.handle.writeFile(content);
+            if (mode !== undefined)
+                await opened.handle.chmod(mode);
+        }
+        finally {
+            await opened.handle.close();
+        }
+        if (root !== undefined)
+            await assertNoSymlinkPathComponents(root, path.dirname(filePath));
+        await fs.rename(temporary, filePath);
+        temporary = undefined;
+    }
+    catch (error) {
+        if (temporary !== undefined) {
+            try {
+                if (root !== undefined)
+                    await assertNoSymlinkPathComponents(root, path.dirname(filePath));
+                await fs.rm(temporary, { force: true });
+            }
+            catch { /* Preserve the original write error. */ }
+        }
+        throw error;
+    }
+}
+export async function removeFileAndEmptyParents(filePath, stopAt) {
+    await assertNoSymlinkPathComponents(stopAt, path.dirname(filePath));
+    try {
+        await fs.unlink(filePath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    let current = path.dirname(filePath);
+    const stop = path.resolve(stopAt);
+    while (current !== stop) {
+        const relative = path.relative(stop, current);
+        if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+            break;
+        try {
+            await assertNoSymlinkPathComponents(stop, current);
+            await fs.rmdir(current);
+        }
+        catch {
+            break;
+        }
+        current = path.dirname(current);
+    }
+}

package/dist/harness-configuration/core/frontmatter.js

@@ -0,0 +1,49 @@
+import YAML from "yaml";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function parseMarkdownDocument(source) {
+    const normalized = source.replaceAll("\r\n", "\n");
+    if (!normalized.startsWith("---\n"))
+        return { data: {}, content: normalized.trim() };
+    const body = normalized.slice(4);
+    const match = /^---[ \t]*(?:\n|$)/mu.exec(body);
+    if (!match)
+        throw new Error("Unterminated YAML frontmatter block.");
+    const rawData = body.slice(0, match.index);
+    const parsed = rawData.trim() === "" ? {} : YAML.parse(rawData);
+    if (!isRecord(parsed))
+        throw new Error("YAML frontmatter must be an object.");
+    return { data: parsed, content: body.slice(match.index + match[0].length).trim() };
+}
+export function parseSkill(source) {
+    const parsed = parseMarkdownDocument(source);
+    const { data } = parsed;
+    if (typeof data.name !== "string" || data.name.length === 0)
+        throw new Error("Skill frontmatter requires a non-empty name.");
+    if (typeof data.description !== "string" || data.description.length === 0)
+        throw new Error("Skill frontmatter requires a non-empty description.");
+    if (data.license !== undefined && typeof data.license !== "string")
+        throw new Error("Skill license must be a string.");
+    if (data.compatibility !== undefined && typeof data.compatibility !== "string")
+        throw new Error("Skill compatibility must be a string.");
+    if (data.metadata !== undefined && !isRecord(data.metadata))
+        throw new Error("Skill metadata must be an object.");
+    const allowedTools = data["allowed-tools"];
+    if (allowedTools !== undefined && typeof allowedTools !== "string" && !(Array.isArray(allowedTools) && allowedTools.every((item) => typeof item === "string"))) {
+        throw new Error("Skill allowed-tools must be a string or an array of strings.");
+    }
+    const result = {
+        name: data.name,
+        description: data.description,
+        ...(typeof data.license === "string" ? { license: data.license } : {}),
+        ...(typeof data.compatibility === "string" ? { compatibility: data.compatibility } : {}),
+        ...(isRecord(data.metadata) ? { metadata: data.metadata } : {}),
+        ...(typeof allowedTools === "string" || Array.isArray(allowedTools) ? { "allowed-tools": allowedTools } : {}),
+    };
+    return { data: result, content: parsed.content };
+}
+export function markdownWithFrontmatter(data, content) {
+    const frontmatter = YAML.stringify(data, { lineWidth: 0 }).trimEnd();
+    return `---\n${frontmatter}\n---\n${content.trim()}\n`;
+}

package/dist/harness-configuration/core/hash.js

@@ -0,0 +1,4 @@
+import { createHash } from "node:crypto";
+export function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}

package/dist/harness-configuration/core/path.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { CanonfigError } from "./errors.js";
+export function toPosix(value) { return value.replaceAll("\\", "/").split(path.sep).join("/"); }
+export function assertSafeRelativePath(value) {
+    const normalized = path.posix.normalize(toPosix(value));
+    if (normalized === "."
+        || normalized === ".."
+        || normalized.startsWith("../")
+        || normalized.includes("/../")
+        || path.posix.isAbsolute(normalized)
+        || /^[A-Za-z]:\//u.test(normalized)) {
+        throw new CanonfigError("UNSAFE_PATH", `Unsafe repository-relative path: ${value}`);
+    }
+    return normalized;
+}
+export function resolveInside(root, relativePath) {
+    const safe = assertSafeRelativePath(relativePath);
+    const resolved = path.resolve(root, safe);
+    const relative = path.relative(root, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new CanonfigError("PATH_ESCAPE", `Path escapes repository root: ${relativePath}`);
+    return resolved;
+}
+function assertAbsoluteInside(realRoot, realCandidate, original) {
+    const relative = path.relative(realRoot, realCandidate);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new CanonfigError("SYMLINK_ESCAPE", `Path resolves outside repository root: ${original}`);
+    }
+}
+/** Verify an existing path, or its nearest existing ancestor, remains inside root after symlink resolution. */
+export async function assertRealPathInside(root, candidate) {
+    const rootReal = await fs.realpath(root);
+    let current = candidate;
+    while (true) {
+        try {
+            const resolved = await fs.realpath(current);
+            assertAbsoluteInside(rootReal, resolved, candidate);
+            return;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = path.dirname(current);
+            if (parent === current)
+                throw error;
+            current = parent;
+        }
+    }
+}