@microck/canonfig 2.0.0 → 2.1.0

package/dist/harness-configuration/core/render-utils.js

@@ -0,0 +1,202 @@
+export function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function deepEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (Array.isArray(left) && Array.isArray(right)) {
+        return left.length === right.length
+            && left.every((value, index) => deepEqual(value, right[index]));
+    }
+    if (isRecord(left) && isRecord(right)) {
+        const leftKeys = Object.keys(left).sort();
+        const rightKeys = Object.keys(right).sort();
+        return deepEqual(leftKeys, rightKeys)
+            && leftKeys.every((key) => deepEqual(left[key], right[key]));
+    }
+    return false;
+}
+function stripJsonComments(text) {
+    let output = "";
+    let index = 0;
+    let inString = false;
+    let escaped = false;
+    while (index < text.length) {
+        const character = text[index];
+        const next = text[index + 1];
+        if (inString) {
+            output += character;
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (character === '"')
+                inString = false;
+            index += 1;
+            continue;
+        }
+        if (character === '"') {
+            inString = true;
+            output += character;
+            index += 1;
+            continue;
+        }
+        if (character === "/" && next === "/") {
+            while (index < text.length && text[index] !== "\n")
+                index += 1;
+            output += "\n";
+            index += 1;
+            continue;
+        }
+        if (character === "/" && next === "*") {
+            index += 2;
+            while (index + 1 < text.length
+                && !(text[index] === "*" && text[index + 1] === "/")) {
+                if (text[index] === "\n")
+                    output += "\n";
+                index += 1;
+            }
+            index += 2;
+            continue;
+        }
+        output += character;
+        index += 1;
+    }
+    return output;
+}
+function removeTrailingCommas(text) {
+    let output = "";
+    let inString = false;
+    let escaped = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const character = text[index];
+        if (inString) {
+            output += character;
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (character === '"')
+                inString = false;
+            continue;
+        }
+        if (character === '"') {
+            inString = true;
+            output += character;
+            continue;
+        }
+        if (character === ",") {
+            let cursor = index + 1;
+            while (cursor < text.length && /\s/u.test(text[cursor]))
+                cursor += 1;
+            if (text[cursor] === "}" || text[cursor] === "]")
+                continue;
+        }
+        output += character;
+    }
+    return output;
+}
+export function parseJsonDocument(text, conflicts) {
+    try {
+        const parsed = JSON.parse(removeTrailingCommas(stripJsonComments(text)));
+        if (!isRecord(parsed)) {
+            conflicts.push("JSON/JSONC root must be an object.");
+            return {};
+        }
+        return parsed;
+    }
+    catch (error) {
+        conflicts.push(`Invalid JSON/JSONC: ${error instanceof Error ? error.message : String(error)}`);
+        return {};
+    }
+}
+export function serializeJsonDocument(document) {
+    return `${JSON.stringify(document, undefined, 2)}\n`;
+}
+export function getAtPath(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (!isRecord(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+export function setAtPath(root, path, value) {
+    if (path.length === 0) {
+        if (!isRecord(value))
+            throw new TypeError("JSON root replacement must be an object");
+        for (const key of Object.keys(root))
+            delete root[key];
+        Object.assign(root, value);
+        return;
+    }
+    let parent = root;
+    for (const segment of path.slice(0, -1)) {
+        const current = parent[segment];
+        if (!isRecord(current))
+            parent[segment] = {};
+        parent = parent[segment];
+    }
+    const key = path[path.length - 1];
+    if (value === undefined)
+        delete parent[key];
+    else
+        parent[key] = value;
+}
+export function commentMarkers(marker, style) {
+    const prefix = style === "html" ? "<!-- " : style === "slash" ? "// " : "# ";
+    const suffix = style === "html" ? " -->" : "";
+    return {
+        begin: `${prefix}canonfig:begin ${marker}${suffix}`,
+        end: `${prefix}canonfig:end ${marker}${suffix}`,
+    };
+}
+export function locateBlock(text, begin, end) {
+    const start = text.indexOf(begin);
+    if (start < 0)
+        return undefined;
+    const endStart = text.indexOf(end, start + begin.length);
+    if (endStart < 0)
+        return undefined;
+    let endOffset = endStart + end.length;
+    if (text[endOffset] === "\r" && text[endOffset + 1] === "\n")
+        endOffset += 2;
+    else if (text[endOffset] === "\n")
+        endOffset += 1;
+    return { start, end: endOffset, block: text.slice(start, endOffset) };
+}
+export function identityOf(value, identity) {
+    return identity === undefined || !isRecord(value) ? value : value[identity];
+}
+export function containsMarker(value, marker) {
+    if (typeof value === "string")
+        return value.includes(marker);
+    if (Array.isArray(value))
+        return value.some((item) => containsMarker(item, marker));
+    return isRecord(value)
+        && Object.values(value).some((item) => containsMarker(item, marker));
+}
+export function tomlBlockMarkers(marker) {
+    return {
+        begin: `# canonfig:begin ${marker}`,
+        end: `# canonfig:end ${marker}`,
+    };
+}
+export function findTomlSection(lines, section) {
+    const escaped = section.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const target = new RegExp(`^\\s*\\[${escaped}\\]\\s*(?:#.*)?$`, "u");
+    for (let index = 0; index < lines.length; index += 1) {
+        if (!target.test(lines[index] ?? ""))
+            continue;
+        let end = lines.length;
+        for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+            if (/^\s*\[\[?.+?\]\]?\s*(?:#.*)?$/u.test(lines[cursor] ?? "")) {
+                end = cursor;
+                break;
+            }
+        }
+        return { header: index, end };
+    }
+    return undefined;
+}

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

@@ -0,0 +1,54 @@
+import { sha256 } from "./hash.js";
+import { unapplyPrevious } from "./render-cleanup.js";
+import { applyJsonArtifact } from "./render-json.js";
+import { appendManagedText, applyTomlArtifact } from "./render-text.js";
+export function renderArtifacts(artifacts, current, previous, force = false) {
+    const conflicts = [];
+    const output = unapplyPrevious(current, previous, force, conflicts);
+    const cleanup = [];
+    if (artifacts.length === 0)
+        return { content: output, cleanup, conflicts };
+    const replacements = artifacts.filter((artifact) => artifact.kind === "replace");
+    if (replacements.length > 0) {
+        if (artifacts.length !== 1) {
+            conflicts.push("A replace artifact cannot share a path with merge artifacts.");
+        }
+        const replacement = replacements[0];
+        if (replacement === undefined)
+            return { content: output, cleanup, conflicts };
+        if (previous === undefined
+            && current !== undefined
+            && sha256(current) !== sha256(replacement.content)
+            && !force) {
+            conflicts.push("File already exists and is not owned by Canonfig.");
+        }
+        return {
+            content: replacement.content,
+            cleanup: [{ kind: "replace" }],
+            conflicts,
+        };
+    }
+    if (output instanceof Uint8Array) {
+        conflicts.push("Cannot merge text configuration into an existing binary file.");
+        return { content: output, cleanup, conflicts };
+    }
+    let text = output ?? "";
+    for (const artifact of artifacts) {
+        if (artifact.kind === "managed-text") {
+            const result = appendManagedText(text, artifact, force, conflicts);
+            text = result.text;
+            cleanup.push(result.cleanup);
+        }
+        else if (artifact.kind === "json") {
+            const result = applyJsonArtifact(text, artifact, force, conflicts);
+            text = result.text;
+            cleanup.push(...result.cleanup);
+        }
+        else if (artifact.kind === "toml") {
+            const result = applyTomlArtifact(text, artifact, force, conflicts);
+            text = result.text;
+            cleanup.push(...result.cleanup);
+        }
+    }
+    return { content: text, cleanup, conflicts };
+}

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

@@ -0,0 +1,103 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { TARGET_IDS } from "./types.js";
+import { CanonfigError } from "./errors.js";
+import { assertRealPathInside, resolveInside } from "./path.js";
+const ROOT_INSTRUCTIONS = `# Repository instructions
+
+Describe the project, architecture, validation commands, constraints, and definition of done here.
+`;
+const EXAMPLE_RULE = `# Source-code rules
+
+- Keep changes scoped.
+- Run the smallest relevant validation command before finishing.
+`;
+const EXAMPLE_AGENT = `Review the requested change for correctness, security, regressions, and missing tests.
+Return concrete findings before general commentary.
+`;
+const EXAMPLE_COMMAND = `Inspect the current changes, run relevant checks, and produce a release-readiness report.
+`;
+const EXAMPLE_SKILL = `---
+name: repository-checks
+description: Discover and run the repository's relevant validation commands.
+---
+
+# Repository checks
+
+1. Inspect package and build metadata.
+2. Select the narrowest relevant checks.
+3. Report commands, results, and unresolved failures.
+`;
+async function writeNew(root, relativePath, content, force) {
+    const filePath = resolveInside(root, relativePath);
+    await assertRealPathInside(root, filePath);
+    try {
+        await fs.access(filePath);
+        if (!force)
+            return false;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await assertRealPathInside(root, filePath);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await assertRealPathInside(root, filePath);
+    await fs.writeFile(filePath, content, "utf8");
+    return true;
+}
+export async function scaffoldProject(root, options = {}) {
+    const targets = [...new Set(options.targets ?? TARGET_IDS)];
+    if (targets.length === 0)
+        throw new CanonfigError("TARGET_EMPTY", "At least one target is required for init.");
+    const force = options.force ?? false;
+    const config = {
+        version: 1,
+        project: { name: path.basename(path.resolve(root)) },
+        targets: Object.fromEntries(targets.map((target) => [target, { enabled: true, options: {} }])),
+        instructions: {
+            root: "instructions/AGENTS.md",
+            rules: [{
+                    id: "source",
+                    file: "rules/source.md",
+                    paths: ["src/**", "tests/**"],
+                    activation: "path",
+                    description: "Rules for source and test files",
+                }],
+        },
+        skills: { roots: ["skills"] },
+        mcp: { servers: {} },
+        hooks: [],
+        agents: [{
+                id: "reviewer",
+                file: "agents/reviewer.md",
+                description: "Reviews changes for correctness and regressions",
+                model: "inherit",
+                tools: ["read", "search", "test", "git"],
+                writable: false,
+            }],
+        commands: [{
+                id: "release-check",
+                file: "commands/release-check.md",
+                description: "Run a release-readiness review",
+                argumentHint: "[scope]",
+            }],
+        permissions: { rules: [] },
+        extensions: {},
+    };
+    const files = [
+        [".canonfig/harness.yaml", YAML.stringify(config, { lineWidth: 120 })],
+        [".canonfig/instructions/AGENTS.md", ROOT_INSTRUCTIONS],
+        [".canonfig/rules/source.md", EXAMPLE_RULE],
+        [".canonfig/agents/reviewer.md", EXAMPLE_AGENT],
+        [".canonfig/commands/release-check.md", EXAMPLE_COMMAND],
+        [".canonfig/skills/repository-checks/SKILL.md", EXAMPLE_SKILL],
+    ];
+    const written = [];
+    for (const [relativePath, content] of files) {
+        if (await writeNew(root, relativePath, content, force))
+            written.push(relativePath);
+    }
+    return written;
+}

package/dist/harness-configuration/core/schema-components.js

@@ -0,0 +1,167 @@
+import { TARGET_IDS } from "./types.js";
+import { booleanValue, enumValue, idValue, objectValue, optionalString, positiveInteger, relativePath, secretRecord, stringArray, stringValue, } from "./schema-runtime.js";
+import { CAPABILITIES, HOOK_EVENTS, } from "./schema-types.js";
+export const MCP_NAME_PATTERN = /^[A-Za-z0-9._-]+$/u;
+export function parseMcpServer(input, validator, path) {
+    const value = objectValue(input, validator, path);
+    const transport = enumValue(value.transport, ["stdio", "streamable-http", "sse"], validator, [...path, "transport"], "stdio");
+    const enabled = booleanValue(value.enabled, validator, [...path, "enabled"], true);
+    const timeoutMs = positiveInteger(value.timeoutMs, validator, [...path, "timeoutMs"]);
+    const enabledTools = value.enabledTools === undefined
+        ? undefined
+        : stringArray(value.enabledTools, validator, [...path, "enabledTools"]);
+    const disabledTools = value.disabledTools === undefined
+        ? undefined
+        : stringArray(value.disabledTools, validator, [...path, "disabledTools"]);
+    const common = {
+        enabled,
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(enabledTools === undefined ? {} : { enabledTools }),
+        ...(disabledTools === undefined ? {} : { disabledTools }),
+    };
+    if (transport === "stdio") {
+        const cwd = optionalString(value.cwd, validator, [...path, "cwd"]);
+        return {
+            ...common,
+            transport,
+            command: stringValue(value.command, validator, [...path, "command"], {
+                min: 1,
+            }),
+            args: stringArray(value.args, validator, [...path, "args"]),
+            ...(cwd === undefined ? {} : { cwd }),
+            env: secretRecord(value.env, validator, [...path, "env"]),
+        };
+    }
+    const url = stringValue(value.url, validator, [...path, "url"], { min: 1 });
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            validator.issue([...path, "url"], "Expected an HTTP(S) URL.");
+        }
+    }
+    catch {
+        validator.issue([...path, "url"], "Expected a valid URL.");
+    }
+    return {
+        ...common,
+        transport,
+        url,
+        headers: secretRecord(value.headers, validator, [...path, "headers"]),
+    };
+}
+export function parseHook(input, validator, path) {
+    const value = objectValue(input, validator, path);
+    const matcherValue = value.matcher === undefined
+        ? {}
+        : objectValue(value.matcher, validator, [...path, "matcher"]);
+    const inputRegex = optionalString(matcherValue.inputRegex, validator, [...path, "matcher", "inputRegex"]);
+    let capabilities = [];
+    if (matcherValue.capabilities !== undefined) {
+        if (!Array.isArray(matcherValue.capabilities)) {
+            validator.issue([...path, "matcher", "capabilities"], "Expected an array.");
+        }
+        else {
+            capabilities = matcherValue.capabilities.map((item, index) => enumValue(item, CAPABILITIES, validator, [...path, "matcher", "capabilities", index], "read"));
+        }
+    }
+    const matcher = {
+        capabilities,
+        tools: stringArray(matcherValue.tools, validator, [...path, "matcher", "tools"]),
+        ...(inputRegex === undefined ? {} : { inputRegex }),
+    };
+    const run = stringArray(value.run, validator, [...path, "run"]);
+    if (run.length === 0) {
+        validator.issue([...path, "run"], "Expected at least one command argument.");
+    }
+    return {
+        id: idValue(value.id, validator, [...path, "id"]),
+        event: enumValue(value.event, HOOK_EVENTS, validator, [...path, "event"], "before_tool"),
+        enabled: booleanValue(value.enabled, validator, [...path, "enabled"], true),
+        matcher,
+        run,
+        timeoutMs: positiveInteger(value.timeoutMs, validator, [...path, "timeoutMs"], 600_000) ?? 10_000,
+        onFailure: value.onFailure === undefined
+            ? "block"
+            : enumValue(value.onFailure, ["block", "warn", "ignore"], validator, [...path, "onFailure"], "block"),
+    };
+}
+export function parseRule(input, validator, path) {
+    const value = objectValue(input, validator, path);
+    const activation = value.activation === undefined
+        ? undefined
+        : enumValue(value.activation, ["always", "path", "manual", "model"], validator, [...path, "activation"], "always");
+    const description = optionalString(value.description, validator, [...path, "description"]);
+    return {
+        id: idValue(value.id, validator, [...path, "id"]),
+        file: relativePath(value.file, validator, [...path, "file"]),
+        paths: stringArray(value.paths, validator, [...path, "paths"]),
+        ...(activation === undefined ? {} : { activation }),
+        ...(description === undefined ? {} : { description }),
+    };
+}
+export function parseAgent(input, validator, path) {
+    const value = objectValue(input, validator, path);
+    const toolInput = value.tools === undefined ? ["read", "search"] : value.tools;
+    let tools = [];
+    if (!Array.isArray(toolInput)) {
+        validator.issue([...path, "tools"], "Expected an array.");
+    }
+    else {
+        tools = toolInput.map((item, index) => enumValue(item, CAPABILITIES, validator, [...path, "tools", index], "read"));
+    }
+    return {
+        id: idValue(value.id, validator, [...path, "id"]),
+        file: relativePath(value.file, validator, [...path, "file"]),
+        description: stringValue(value.description, validator, [...path, "description"], { min: 1 }),
+        model: value.model === undefined
+            ? "inherit"
+            : stringValue(value.model, validator, [...path, "model"]),
+        tools,
+        writable: booleanValue(value.writable, validator, [...path, "writable"], false),
+    };
+}
+export function parseCommand(input, validator, path) {
+    const value = objectValue(input, validator, path);
+    const argumentHint = optionalString(value.argumentHint, validator, [...path, "argumentHint"]);
+    return {
+        id: idValue(value.id, validator, [...path, "id"]),
+        file: relativePath(value.file, validator, [...path, "file"]),
+        description: stringValue(value.description, validator, [...path, "description"], { min: 1 }),
+        ...(argumentHint === undefined ? {} : { argumentHint }),
+    };
+}
+export function parsePermissionRule(input, validator, path) {
+    const value = objectValue(input, validator, path);
+    const reason = optionalString(value.reason, validator, [...path, "reason"]);
+    return {
+        pattern: stringValue(value.pattern, validator, [...path, "pattern"], {
+            min: 1,
+        }),
+        action: enumValue(value.action, ["allow", "ask", "deny"], validator, [...path, "action"], "ask"),
+        ...(reason === undefined ? {} : { reason }),
+    };
+}
+export function parseTargetEntry(input, validator, path) {
+    const value = objectValue(input, validator, path);
+    return {
+        enabled: booleanValue(value.enabled, validator, [...path, "enabled"], true),
+        options: value.options === undefined
+            ? {}
+            : objectValue(value.options, validator, [...path, "options"]),
+    };
+}
+export function parseTargets(input, validator, path) {
+    if (Array.isArray(input)) {
+        return input.map((value, index) => enumValue(value, TARGET_IDS, validator, [...path, index], "codex"));
+    }
+    const value = objectValue(input, validator, path);
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (!TARGET_IDS.includes(key)) {
+            validator.issue([...path, key], `Unknown target. Expected one of: ${TARGET_IDS.join(", ")}.`);
+            continue;
+        }
+        output[key] = parseTargetEntry(entry, validator, [...path, key]);
+    }
+    return output;
+}

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

@@ -0,0 +1,98 @@
+import { TARGET_IDS } from "./types.js";
+import { objectValue, optionalString, relativePath, } from "./schema-runtime.js";
+import { MCP_NAME_PATTERN, parseAgent, parseCommand, parseHook, parseMcpServer, parsePermissionRule, parseRule, parseTargets, } from "./schema-components.js";
+function parsedArray(input, validator, path, parser) {
+    if (input === undefined)
+        return [];
+    if (!Array.isArray(input)) {
+        validator.issue(path, "Expected an array.");
+        return [];
+    }
+    return input.map((item, index) => parser(item, validator, [...path, index]));
+}
+function duplicateIds(validator, label, items) {
+    const seen = new Set();
+    for (const item of items) {
+        if (seen.has(item.id))
+            validator.issue([], `Duplicate ${label} id: ${item.id}`);
+        seen.add(item.id);
+    }
+}
+export function parseConfig(input, validator, path) {
+    const value = objectValue(input, validator, path);
+    if (value.version !== 1)
+        validator.issue(["version"], "Expected literal value 1.");
+    const projectValue = value.project === undefined
+        ? {}
+        : objectValue(value.project, validator, ["project"]);
+    const projectName = optionalString(projectValue.name, validator, ["project", "name"]);
+    const instructionsValue = value.instructions === undefined
+        ? {}
+        : objectValue(value.instructions, validator, ["instructions"]);
+    const rules = parsedArray(instructionsValue.rules, validator, ["instructions", "rules"], parseRule);
+    const skillsValue = value.skills === undefined
+        ? {}
+        : objectValue(value.skills, validator, ["skills"]);
+    const rootsInput = skillsValue.roots === undefined ? ["skills"] : skillsValue.roots;
+    let roots = [];
+    if (!Array.isArray(rootsInput)) {
+        validator.issue(["skills", "roots"], "Expected an array.");
+    }
+    else {
+        roots = rootsInput.map((item, index) => relativePath(item, validator, ["skills", "roots", index]));
+    }
+    const mcpValue = value.mcp === undefined
+        ? {}
+        : objectValue(value.mcp, validator, ["mcp"]);
+    const serversValue = mcpValue.servers === undefined
+        ? {}
+        : objectValue(mcpValue.servers, validator, ["mcp", "servers"]);
+    const servers = {};
+    for (const [name, server] of Object.entries(serversValue)) {
+        if (!MCP_NAME_PATTERN.test(name)) {
+            validator.issue(["mcp", "servers", name], "Invalid MCP server name.");
+        }
+        servers[name] = parseMcpServer(server, validator, ["mcp", "servers", name]);
+    }
+    const hooks = parsedArray(value.hooks, validator, ["hooks"], parseHook);
+    const agents = parsedArray(value.agents, validator, ["agents"], parseAgent);
+    const commands = parsedArray(value.commands, validator, ["commands"], parseCommand);
+    const permissionsValue = value.permissions === undefined
+        ? {}
+        : objectValue(value.permissions, validator, ["permissions"]);
+    const permissionRules = parsedArray(permissionsValue.rules, validator, ["permissions", "rules"], parsePermissionRule);
+    const extensionsValue = value.extensions === undefined
+        ? {}
+        : objectValue(value.extensions, validator, ["extensions"]);
+    const extensions = {};
+    for (const [key, extension] of Object.entries(extensionsValue)) {
+        if (!TARGET_IDS.includes(key)) {
+            validator.issue(["extensions", key], `Unknown target. Expected one of: ${TARGET_IDS.join(", ")}.`);
+            continue;
+        }
+        extensions[key] = objectValue(extension, validator, ["extensions", key]);
+    }
+    duplicateIds(validator, "rule", rules);
+    duplicateIds(validator, "hook", hooks);
+    duplicateIds(validator, "agent", agents);
+    duplicateIds(validator, "command", commands);
+    const targets = value.targets === undefined
+        ? (validator.issue(["targets"], "Required."), [])
+        : parseTargets(value.targets, validator, ["targets"]);
+    return {
+        version: 1,
+        project: projectName === undefined ? {} : { name: projectName },
+        targets,
+        instructions: {
+            root: relativePath(instructionsValue.root, validator, ["instructions", "root"], "instructions/AGENTS.md"),
+            rules,
+        },
+        skills: { roots },
+        mcp: { servers },
+        hooks,
+        agents,
+        commands,
+        permissions: { rules: permissionRules },
+        extensions,
+    };
+}