@intentius/chant 0.124.12 → 0.124.14

package/dist/cli/commands/update.js

@@ -0,0 +1,194 @@
+import { lexiconModulePath, lexiconNames } from "../../lexicon-module.js";
+import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync, statSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { createRequire } from "module";
+import { formatSuccess, formatWarning, formatError } from "../format.js";
+import { loadChantConfig } from "../../config.js";
+import { loadPlugins } from "../plugins.js";
+import { writeProjectMcpConfig } from "../mcp-config.js";
+/**
+ * Where `chant update` writes a lexicon skill, relative to the project. The
+ * workspace drift check (#2541) compares these files with what the skills
+ * render to, so both read the path from here.
+ */
+export function skillFilePath(skillName) {
+    return `skills/${skillName}/SKILL.md`;
+}
+/**
+ * Copy directory contents recursively, filtering to .ts and .d.ts files
+ */
+function copyTypeFiles(src, dest) {
+    if (!existsSync(src))
+        return 0;
+    mkdirSync(dest, { recursive: true });
+    let count = 0;
+    const entries = readdirSync(src);
+    for (const entry of entries) {
+        const srcPath = join(src, entry);
+        const destPath = join(dest, entry);
+        const stat = statSync(srcPath);
+        if (stat.isDirectory()) {
+            // Skip node_modules, tests, examples
+            if (entry === "node_modules" || entry === "__test__")
+                continue;
+            count += copyTypeFiles(srcPath, destPath);
+        }
+        else if (entry.endsWith(".d.ts") ||
+            entry.endsWith(".json")) {
+            cpSync(srcPath, destPath);
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Resolve the path to a package in node_modules
+ */
+function resolvePackagePath(packageName, projectDir) {
+    // Try resolve from project dir
+    try {
+        const _require = createRequire(join(projectDir, "package.json"));
+        const entryPoint = _require.resolve(packageName);
+        // Walk up from entry point to find package root
+        let dir = entryPoint;
+        while (dir !== "/") {
+            dir = join(dir, "..");
+            if (existsSync(join(dir, "package.json"))) {
+                const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+                if (pkg.name === packageName)
+                    return dir;
+            }
+        }
+    }
+    catch {
+        // Package not installed
+    }
+    // Fallback: check common node_modules locations
+    const candidates = [
+        join(projectDir, "node_modules", ...packageName.split("/")),
+        join(projectDir, "..", "node_modules", ...packageName.split("/")),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(join(candidate, "package.json"))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Execute the update command — sync lexicon types into .chant/
+ */
+export async function updateCommand(options) {
+    const projectDir = resolve(options.path);
+    const synced = [];
+    const warnings = [];
+    // Load config to get lexicons
+    const { config } = await loadChantConfig(projectDir);
+    const lexicons = lexiconNames(config.lexicons ?? []);
+    if (lexicons.length === 0) {
+        return {
+            success: false,
+            synced: [],
+            warnings: [],
+            error: "No lexicons configured. Add lexicons to chant.config.ts.",
+        };
+    }
+    const typesDir = join(projectDir, ".chant", "types");
+    // Sync core types
+    const corePkgPath = resolvePackagePath("@intentius/chant", projectDir);
+    if (corePkgPath) {
+        const coreDestDir = join(typesDir, "core");
+        const srcDir = join(corePkgPath, "src");
+        if (existsSync(srcDir)) {
+            const count = copyTypeFiles(srcDir, coreDestDir);
+            // Also copy package.json
+            if (existsSync(join(corePkgPath, "package.json"))) {
+                cpSync(join(corePkgPath, "package.json"), join(coreDestDir, "package.json"));
+            }
+            synced.push(`@intentius/chant (${count} files)`);
+        }
+    }
+    else {
+        warnings.push("@intentius/chant not found in node_modules");
+    }
+    // Sync each lexicon
+    for (const lexicon of lexicons) {
+        // chant #2520 — a lexicon declared by module path is project source, with
+        // no package to copy types from.
+        if (lexiconModulePath(lexicon) !== undefined)
+            continue;
+        const pkgName = `@intentius/chant-lexicon-${lexicon}`;
+        const pkgPath = resolvePackagePath(pkgName, projectDir);
+        if (!pkgPath) {
+            warnings.push(`${pkgName} not found in node_modules. Run "npm install" first.`);
+            continue;
+        }
+        const lexiconDestDir = join(typesDir, `lexicon-${lexicon}`);
+        const srcDir = join(pkgPath, "src");
+        if (existsSync(srcDir)) {
+            const count = copyTypeFiles(srcDir, lexiconDestDir);
+            if (existsSync(join(pkgPath, "package.json"))) {
+                cpSync(join(pkgPath, "package.json"), join(lexiconDestDir, "package.json"));
+            }
+            synced.push(`${pkgName} (${count} files)`);
+        }
+        else {
+            warnings.push(`${pkgName} has no src/ directory`);
+        }
+    }
+    // Install skills from plugins
+    try {
+        const plugins = await loadPlugins(lexicons);
+        for (const plugin of plugins) {
+            if (plugin.skills) {
+                const skills = plugin.skills();
+                if (skills.length > 0) {
+                    for (const skill of skills) {
+                        const file = join(projectDir, skillFilePath(skill.name));
+                        mkdirSync(dirname(file), { recursive: true });
+                        writeFileSync(file, skill.content);
+                    }
+                    synced.push(`${plugin.name} skills (${skills.length})`);
+                }
+            }
+        }
+    }
+    catch {
+        // Skills are optional — don't fail the update if plugin loading fails
+        warnings.push("Could not load plugins for skill installation");
+    }
+    // Restore the project's MCP registration if it went missing. This is what
+    // makes the doctor's `mcp-config` remediation runnable: `chant init`
+    // refuses a non-empty directory without --force, so an already scaffolded
+    // project needs some other command to put the file back, and this is the
+    // same command the doctor's skills check already points at (chant #2383).
+    const writtenMcp = writeProjectMcpConfig(projectDir);
+    if (writtenMcp)
+        synced.push(writtenMcp);
+    return {
+        success: true,
+        synced,
+        warnings,
+    };
+}
+/**
+ * Print update result
+ */
+export function printUpdateResult(result) {
+    if (!result.success) {
+        console.error(formatError({ message: result.error ?? "Update failed" }));
+        return;
+    }
+    for (const warning of result.warnings) {
+        console.error(formatWarning({ message: warning }));
+    }
+    if (result.synced.length > 0) {
+        console.log(formatSuccess("Synced types:"));
+        for (const item of result.synced) {
+            console.log(`  ${item}`);
+        }
+    }
+    else {
+        console.log("No types synced.");
+    }
+}

package/dist/cli/commands/vendor.js

@@ -0,0 +1,217 @@
+/**
+ * `chant vendor` — pull reusable patterns (composites as source, Ops, init
+ * templates, example skeletons) from a remote source into your own repo, pinned
+ * and auditable.
+ *
+ * This is for patterns you copy in and **own/adapt**, recorded in a manifest
+ * (`vendor.json`) with a checksum so provenance is verifiable. It is NOT a
+ * package manager: lexicons stay npm dependencies (the typed API you import,
+ * never edit). Vendoring exists for the source npm handles badly — code you want
+ * in-repo, reviewable in diffs, and adaptable.
+ *
+ * Reuses the existing fetch/extract infra (`codegen/fetch.ts`); the only new
+ * machinery is the manifest + copy-to-repo + checksum.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import { fetchWithRetry, extractFromTar, extractFromZip } from "../../codegen/fetch.js";
+// ── Manifest schema ─────────────────────────────────────────────────────────
+const SourceSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("local"), path: z.string().min(1) }),
+    z.object({ type: z.literal("archive"), url: z.string().url(), subpath: z.string().optional() }),
+]);
+const EntrySchema = z.object({
+    /** Stable identity for the vendored artifact (used by `pull <name>`). */
+    name: z.string().min(1),
+    source: SourceSchema,
+    /** Path in your repo to write the pulled content. */
+    target: z.string().min(1),
+    /** The pin — a git tag / version label, for provenance (informational). */
+    ref: z.string().optional(),
+    /** sha256 of the pulled content. Written by `pull`, verified by `check`. */
+    checksum: z.string().optional(),
+    /** Only "pin" (explicit-bump) is supported; floating refs are out of scope. */
+    updatePolicy: z.literal("pin").optional(),
+});
+export const VendorManifestSchema = z.object({
+    vendored: z.array(EntrySchema),
+});
+export const MANIFEST_FILE = "vendor.json";
+// ── Content hashing ───────────────────────────────────────────────────────��─
+/**
+ * Deterministic sha256 over a file set — independent of fetch/extract order.
+ * Hashes each `path\0content\0` in sorted-path order.
+ */
+export function contentHash(files) {
+    const h = createHash("sha256");
+    for (const path of [...files.keys()].sort()) {
+        h.update(path);
+        h.update("\0");
+        h.update(files.get(path));
+        h.update("\0");
+    }
+    return `sha256:${h.digest("hex")}`;
+}
+// ── Source resolution → a { relpath → bytes } file set ──────────────────────
+/** Walk a local directory into a relpath→bytes map (or a single file). */
+export function readLocal(absPath) {
+    const files = new Map();
+    const stat = statSync(absPath);
+    if (stat.isFile()) {
+        files.set(absPath.split(sep).pop(), readFileSync(absPath));
+        return files;
+    }
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile()) {
+                files.set(relative(absPath, full).split(sep).join("/"), readFileSync(full));
+            }
+        }
+    };
+    walk(absPath);
+    return files;
+}
+/** Fetch + extract an archive (tar.gz/tgz/zip), scoped to an optional subpath. */
+async function readArchive(url, subpath) {
+    const resp = await fetchWithRetry(url);
+    const bytes = new Uint8Array(await resp.arrayBuffer());
+    let raw;
+    if (url.endsWith(".zip")) {
+        raw = await extractFromZip(Buffer.from(bytes));
+    }
+    else {
+        // .tar.gz / .tgz — gunzip then untar (matches fetchAndExtractTar).
+        const { gunzipSync } = await import("fflate");
+        raw = extractFromTar(gunzipSync(bytes));
+    }
+    return scopeArchiveFiles(raw, subpath);
+}
+/**
+ * Normalize an extracted archive: strip the single top-level wrapper directory
+ * (e.g. "repo-main/") that archives commonly add, then scope to `subpath`.
+ * Pure — separated from the network fetch so the scoping is unit-testable.
+ */
+export function scopeArchiveFiles(raw, subpath) {
+    const prefix = subpath ? subpath.replace(/^\/+|\/+$/g, "") + "/" : "";
+    const files = new Map();
+    for (const [name, data] of raw) {
+        const slash = name.indexOf("/");
+        const rel = slash >= 0 ? name.slice(slash + 1) : name;
+        if (!rel || !rel.startsWith(prefix))
+            continue;
+        const local = rel.slice(prefix.length);
+        if (local)
+            files.set(local, data);
+    }
+    return files;
+}
+async function resolveSource(entry, manifestDir) {
+    return resolveVendorSource(entry.source, manifestDir);
+}
+/** Resolve a vendor source (a local path, or an archive URL) to its file set. */
+export async function resolveVendorSource(source, manifestDir) {
+    if (source.type === "local") {
+        const abs = resolve(manifestDir, source.path);
+        if (!existsSync(abs))
+            throw new Error(`local source not found: ${source.path}`);
+        return readLocal(abs);
+    }
+    return readArchive(source.url, source.subpath);
+}
+// ── File I/O ────────────────────────────────────────────────────────────────
+function writeFiles(targetDir, files) {
+    if (existsSync(targetDir))
+        rmSync(targetDir, { recursive: true });
+    for (const [rel, data] of files) {
+        const full = join(targetDir, rel);
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, data);
+    }
+}
+export function readTarget(targetDir) {
+    if (!existsSync(targetDir))
+        return new Map();
+    return readLocal(targetDir);
+}
+// ── Manifest load/save ────────────────────────────────────────────────────��─
+export function loadManifest(manifestDir) {
+    const path = join(manifestDir, MANIFEST_FILE);
+    if (!existsSync(path)) {
+        throw new Error(`no ${MANIFEST_FILE} found in ${manifestDir}`);
+    }
+    const parsed = VendorManifestSchema.safeParse(JSON.parse(readFileSync(path, "utf-8")));
+    if (!parsed.success) {
+        throw new Error(`invalid ${MANIFEST_FILE}: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+    }
+    return { manifest: parsed.data, path };
+}
+function saveManifest(path, manifest) {
+    writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n");
+}
+/**
+ * Pull each vendored entry (or just `only`): resolve the source, write it into
+ * `target`, and record the content checksum back into the manifest.
+ */
+export async function vendorPull(manifestDir, only) {
+    const { manifest, path } = loadManifest(manifestDir);
+    const entries = only ? manifest.vendored.filter((e) => e.name === only) : manifest.vendored;
+    if (only && entries.length === 0) {
+        return { success: false, pulled: [], output: `no vendored entry named "${only}"` };
+    }
+    const pulled = [];
+    for (const entry of entries) {
+        const files = await resolveSource(entry, manifestDir);
+        const checksum = contentHash(files);
+        writeFiles(resolve(manifestDir, entry.target), files);
+        entry.checksum = checksum;
+        pulled.push({ name: entry.name, target: entry.target, checksum, fileCount: files.size });
+    }
+    saveManifest(path, manifest);
+    const output = pulled
+        .map((p) => `  ${p.name} → ${p.target} (${p.fileCount} file(s), ${p.checksum.slice(0, 19)}…)`)
+        .join("\n");
+    return { success: true, pulled, output };
+}
+/**
+ * Verify each target's working copy against its recorded checksum. Editing
+ * vendored files is allowed — `check` only reports that they diverged from the
+ * pin. The caller decides whether drift is fatal (CI) or a warning (local).
+ */
+export function vendorCheck(manifestDir) {
+    const { manifest } = loadManifest(manifestDir);
+    const entries = [];
+    let drift = false;
+    for (const entry of manifest.vendored) {
+        const targetAbs = resolve(manifestDir, entry.target);
+        if (!entry.checksum) {
+            entries.push({ name: entry.name, status: "unpinned" });
+            continue;
+        }
+        if (!existsSync(targetAbs)) {
+            entries.push({ name: entry.name, status: "missing" });
+            drift = true;
+            continue;
+        }
+        const actual = contentHash(readTarget(targetAbs));
+        if (actual === entry.checksum) {
+            entries.push({ name: entry.name, status: "ok" });
+        }
+        else {
+            entries.push({ name: entry.name, status: "drifted" });
+            drift = true;
+        }
+    }
+    const label = {
+        ok: "ok",
+        drifted: "DRIFTED (working copy differs from the pin)",
+        unpinned: "unpinned — run `chant vendor pull` to record a checksum",
+        missing: "MISSING — target not found; run `chant vendor pull`",
+    };
+    const output = entries.map((e) => `  ${e.name}: ${label[e.status]}`).join("\n");
+    return { success: !drift, drift, entries, output };
+}

package/dist/cli/conflict-check.js

@@ -0,0 +1,104 @@
+import { RESERVED_COMMAND_NAMES } from "./command-group.js";
+/**
+ * Check loaded lexicon plugins for cross-lexicon conflicts.
+ *
+ * - Duplicate rule IDs are hard conflicts (should cause a throw at load time).
+ * - Duplicate skill, MCP tool, or MCP resource names are soft conflicts (warnings).
+ */
+export function checkConflicts(plugins) {
+    const conflicts = [];
+    const warnings = [];
+    // Check rule ID conflicts (hard conflict)
+    const ruleIds = new Map();
+    for (const plugin of plugins) {
+        const rules = plugin.lintRules?.() ?? [];
+        for (const rule of rules) {
+            const existing = ruleIds.get(rule.id) ?? [];
+            existing.push(plugin.name);
+            ruleIds.set(rule.id, existing);
+        }
+    }
+    for (const [id, owners] of ruleIds) {
+        if (owners.length > 1) {
+            conflicts.push({ type: "rule-id", key: id, plugins: owners });
+        }
+    }
+    // Check skill name conflicts (warning)
+    const skillNames = new Map();
+    for (const plugin of plugins) {
+        const skills = plugin.skills?.() ?? [];
+        for (const skill of skills) {
+            const existing = skillNames.get(skill.name) ?? [];
+            existing.push(plugin.name);
+            skillNames.set(skill.name, existing);
+        }
+    }
+    for (const [name, owners] of skillNames) {
+        if (owners.length > 1) {
+            warnings.push({ type: "skill-name", key: name, plugins: owners });
+        }
+    }
+    // Check MCP tool name conflicts (warning)
+    const mcpToolNames = new Map();
+    for (const plugin of plugins) {
+        const tools = plugin.mcpTools?.() ?? [];
+        for (const tool of tools) {
+            const existing = mcpToolNames.get(tool.name) ?? [];
+            existing.push(plugin.name);
+            mcpToolNames.set(tool.name, existing);
+        }
+    }
+    for (const [name, owners] of mcpToolNames) {
+        if (owners.length > 1) {
+            warnings.push({ type: "mcp-tool", key: name, plugins: owners });
+        }
+    }
+    // Check MCP resource URI conflicts (warning)
+    const mcpResourceUris = new Map();
+    for (const plugin of plugins) {
+        const resources = plugin.mcpResources?.() ?? [];
+        for (const resource of resources) {
+            const existing = mcpResourceUris.get(resource.uri) ?? [];
+            existing.push(plugin.name);
+            mcpResourceUris.set(resource.uri, existing);
+        }
+    }
+    for (const [uri, owners] of mcpResourceUris) {
+        if (owners.length > 1) {
+            warnings.push({ type: "mcp-resource", key: uri, plugins: owners });
+        }
+    }
+    // Check command-group name conflicts (hard, chant #1078). Two shapes:
+    // two lexicons claiming the same group name (only one would ever be
+    // reachable, silently), or one lexicon claiming a name core's own static
+    // registry already owns (permanently unreachable — core resolves its own
+    // registry first, unconditionally). Either is a silent-shadowing bug
+    // class, so both are hard conflicts rather than warnings.
+    const commandGroupNames = new Map();
+    for (const plugin of plugins) {
+        const group = plugin.commands?.();
+        if (!group)
+            continue;
+        const existing = commandGroupNames.get(group.name) ?? [];
+        existing.push(plugin.name);
+        commandGroupNames.set(group.name, existing);
+    }
+    for (const [name, owners] of commandGroupNames) {
+        if (owners.length > 1 || RESERVED_COMMAND_NAMES.has(name)) {
+            conflicts.push({ type: "command-group-name", key: name, plugins: owners });
+        }
+    }
+    return { conflicts, warnings };
+}
+/**
+ * One line of the load-time error for a conflict. A command-group name that
+ * core reserves says so and says what to do, since the lexicon author reading
+ * it may not know the word is core's (#2529).
+ */
+export function describeConflict(c) {
+    const line = `  ${c.type} "${c.key}" from: ${c.plugins.join(", ")}`;
+    if (c.type === "command-group-name" && RESERVED_COMMAND_NAMES.has(c.key)) {
+        return `${line} — "${c.key}" is a reserved chant command name, so no lexicon can register a command group with it. Rename the group.`;
+    }
+    return line;
+}

package/dist/cli/debug.js

@@ -0,0 +1,8 @@
+/**
+ * Debug logger — outputs to stderr when CHANT_DEBUG env var or --verbose/-v flag is set.
+ */
+export function debug(...args) {
+    if (process.env.CHANT_DEBUG || process.argv.includes("--verbose") || process.argv.includes("-v")) {
+        console.error("[chant:debug]", ...args);
+    }
+}

package/dist/cli/format.js

@@ -0,0 +1,104 @@
+/**
+ * ANSI color codes for terminal output
+ */
+const colors = {
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    green: "\x1b[32m",
+    cyan: "\x1b[36m",
+    gray: "\x1b[90m",
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+};
+/**
+ * Check if colors should be used (respects NO_COLOR env var)
+ */
+function useColors() {
+    return !process.env.NO_COLOR && process.stdout.isTTY !== false;
+}
+/**
+ * Apply color if colors are enabled
+ */
+function color(text, colorCode) {
+    if (!useColors())
+        return text;
+    return `${colorCode}${text}${colors.reset}`;
+}
+/**
+ * Format an error with ANSI colors
+ * Shows file:line:column in cyan, error in red
+ */
+export function formatError(error) {
+    const parts = [];
+    // Location prefix
+    if (error.file) {
+        let location = error.file;
+        if (error.line !== undefined) {
+            location += `:${error.line}`;
+            if (error.column !== undefined) {
+                location += `:${error.column}`;
+            }
+        }
+        parts.push(color(location, colors.cyan));
+        parts.push(" - ");
+    }
+    // Error type
+    parts.push(color("error", colors.red));
+    parts.push(": ");
+    // Message
+    parts.push(error.message);
+    // Hint
+    if (error.hint) {
+        parts.push("\n  ");
+        parts.push(color(error.hint, colors.gray));
+    }
+    return parts.join("");
+}
+/**
+ * Format a warning with ANSI colors
+ * Shows file:line:column in cyan, warning in yellow
+ */
+export function formatWarning(warning) {
+    const parts = [];
+    // Location prefix
+    if (warning.file) {
+        let location = warning.file;
+        if (warning.line !== undefined) {
+            location += `:${warning.line}`;
+            if (warning.column !== undefined) {
+                location += `:${warning.column}`;
+            }
+        }
+        parts.push(color(location, colors.cyan));
+        parts.push(" - ");
+    }
+    // Warning type
+    parts.push(color("warning", colors.yellow));
+    parts.push(": ");
+    // Message
+    parts.push(warning.message);
+    // Hint
+    if (warning.hint) {
+        parts.push("\n  ");
+        parts.push(color(warning.hint, colors.gray));
+    }
+    return parts.join("");
+}
+/**
+ * Format a success message in green
+ */
+export function formatSuccess(message) {
+    return color(message, colors.green);
+}
+/**
+ * Format an info message in gray
+ */
+export function formatInfo(message) {
+    return color(message, colors.gray);
+}
+/**
+ * Format a count/stat in bold
+ */
+export function formatBold(text) {
+    return color(text, colors.bold);
+}