howtofixcli 0.7.13 → 0.7.15

package/dist/preset-command.js

@@ -1,227 +0,0 @@
-/**
- * `howtofix preset <new|check|pack>` — the authoring half of a preset.
- *
- * Installing a preset was covered; writing one was not, so the only way to make
- * one was to read `presets/` in this repo and copy the shape. That works for us
- * and not for anyone else, and the registry's rules — a `preset.json` that
- * validates, a `SKILL.md` whose frontmatter the loader accepts, a name the
- * installer will not reject — are exactly the rules an author needs told while
- * writing, not after publishing.
- *
- * `check` runs the *same* `validatePreset` the installer runs, so a preset that
- * passes here cannot be refused at install for a reason this could have named.
- * That is the point: a separate authoring validator would drift, and the drift
- * would only be discovered by the person installing.
- *
- * No preset runs code, and nothing here changes that: `pack` writes an archive,
- * it does not execute anything inside one.
- */
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
-import { readPreset, validatePreset } from "./presets.js";
-/** The scaffold written by `preset new`, with the name already filled in. */
-function scaffold(name) {
-    const title = name.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-    return [
-        {
-            path: "preset.json",
-            body: `${JSON.stringify({
-                name,
-                title,
-                description: "One line saying what this preset is for.",
-                category: "engineering",
-                version: "1.0.0",
-                skills: [`${name}-skill`],
-            }, null, 2)}\n`,
-        },
-        {
-            path: "prompt.md",
-            body: [
-                "Rules the model should follow while this preset is active.",
-                "",
-                "This text is appended to the system prompt, never substituted for it, so it",
-                "adds to the agent's own rules rather than replacing them. Delete this file if",
-                "the preset only needs skills.",
-                "",
-            ].join("\n"),
-        },
-        {
-            path: join("skills", `${name}-skill`, "SKILL.md"),
-            body: [
-                "---",
-                `name: ${name}-skill`,
-                "description: When the model should reach for this skill. This line is what",
-                "  the model reads when deciding, so say when to use it, not what it contains.",
-                "---",
-                "",
-                `# ${title}`,
-                "",
-                "What the model should do, as instructions. A skill is read on demand: only the",
-                "frontmatter above is in every request, so the body costs nothing until used.",
-                "",
-                "Do not add `disable-model-invocation: true` unless the skill must only ever run",
-                "from `/skill:<name>` — it keeps the skill out of the model's catalogue entirely.",
-                "",
-            ].join("\n"),
-        },
-    ];
-}
-function usage() {
-    return [
-        "usage:",
-        "  howtofix preset new <name> [dir]   write a preset skeleton",
-        "  howtofix preset check [dir]        validate a preset with the installer's rules",
-        "  howtofix preset pack [dir]         build <name>-<version>.tar.gz for publishing",
-        "",
-        "A preset is a directory holding preset.json, an optional prompt.md, and a",
-        "skills/ tree. `check` runs the same validation the installer runs, so a preset",
-        "that passes here will not be refused at install.",
-    ].join("\n");
-}
-/** Every file under `dir`, relative, sorted — for the packed listing. */
-function walk(dir) {
-    const out = [];
-    const visit = (d) => {
-        for (const entry of readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-            const full = join(d, entry.name);
-            if (entry.isDirectory())
-                visit(full);
-            else
-                out.push(relative(dir, full).split("\\").join("/"));
-        }
-    };
-    visit(dir);
-    return out;
-}
-/**
- * Validate and report. Returns true when the preset is installable.
- *
- * `readPreset` and `validatePreset` are the installer's own functions, imported
- * rather than reimplemented — a second validator would agree with this one and
- * disagree with the installer, which is the failure that matters.
- */
-function check(dir) {
-    const { manifest, problems } = readPreset(dir);
-    if (!manifest) {
-        console.log(`not installable: ${dir}`);
-        for (const problem of problems)
-            console.log(`  - ${problem}`);
-        return false;
-    }
-    const extra = validatePreset(dir, manifest);
-    if (extra.length > 0) {
-        console.log(`not installable: ${dir}`);
-        for (const problem of extra)
-            console.log(`  - ${problem}`);
-        return false;
-    }
-    const skills = manifest.skills ?? [];
-    let invocable = 0;
-    let invokeOnly = 0;
-    for (const skill of skills) {
-        const file = join(dir, "skills", skill, "SKILL.md");
-        const frontmatter = existsSync(file) ? /^---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(file, "utf8")) : null;
-        const flag = frontmatter && /^disable-model-invocation:\s*(.*)$/m.exec(frontmatter[1]);
-        const on = flag &&
-            flag[1]
-                .trim()
-                .replace(/^["']|["']$/g, "")
-                .toLowerCase() === "true";
-        if (on)
-            invokeOnly += 1;
-        else
-            invocable += 1;
-    }
-    const files = walk(dir);
-    const bytes = files.reduce((sum, f) => sum + statSync(join(dir, f)).size, 0);
-    console.log(`installable: ${manifest.name} ${manifest.version ?? ""}`.trim());
-    console.log(`  ${files.length} files, ${(bytes / 1024).toFixed(1)} KB`);
-    console.log(`  ${skills.length} skill(s): ${invocable} the model can choose`);
-    if (invokeOnly > 0) {
-        console.log(`  ${invokeOnly} invoke-only — reachable only as /skill:<name>`);
-    }
-    return true;
-}
-/**
- * Pack the directory as a gzipped tar, using `tar` rather than writing one.
- *
- * An archive format is not something to hand-roll: `tar` is present on every
- * platform this ships to, and a subtly wrong archive is discovered by the person
- * downloading it. The command is given the file list explicitly so the archive
- * cannot pick up whatever happens to sit in the directory.
- */
-function pack(dir) {
-    const { manifest, problems } = readPreset(dir);
-    if (!manifest) {
-        console.log(`cannot pack: ${dir}`);
-        for (const problem of problems)
-            console.log(`  - ${problem}`);
-        return false;
-    }
-    const extra = validatePreset(dir, manifest);
-    if (extra.length > 0) {
-        console.log(`cannot pack: the preset does not validate`);
-        for (const problem of extra)
-            console.log(`  - ${problem}`);
-        return false;
-    }
-    const version = manifest.version ?? "1.0.0";
-    const archive = resolve(`${manifest.name}-${version}.tar.gz`);
-    const files = walk(dir);
-    execFileSync("tar", ["-czf", archive, "-C", dir, ...files]);
-    const size = statSync(archive).size;
-    console.log(`packed ${archive}`);
-    console.log(`  ${files.length} files, ${(size / 1024).toFixed(1)} KB`);
-    console.log("");
-    console.log("to offer it to the community registry, open a pull request adding an entry");
-    console.log("that names the repo, a pinned commit, and the skill directory inside it.");
-    return true;
-}
-/** Entry point for `howtofix preset ...`. Returns the process exit code. */
-export function runPresetCommand(argv) {
-    const [sub, target] = argv;
-    if (!sub || sub === "--help" || sub === "-h") {
-        console.log(usage());
-        return sub ? 0 : 2;
-    }
-    if (sub === "new") {
-        if (!target) {
-            console.log("preset new: a name is required\n");
-            console.log(usage());
-            return 2;
-        }
-        if (!/^[a-z0-9][a-z0-9-]*$/.test(target)) {
-            console.log(`preset new: "${target}" is not a usable name.`);
-            console.log("  lower-case letters, digits and hyphens; must start with a letter or digit.");
-            console.log("  The installer refuses anything else, and it refuses at install time.");
-            return 2;
-        }
-        const parent = argv[2] ? resolve(argv[2]) : resolve(".");
-        const dir = join(parent, target);
-        if (existsSync(dir)) {
-            console.log(`preset new: ${dir} already exists.`);
-            return 1;
-        }
-        for (const file of scaffold(target)) {
-            const full = join(dir, file.path);
-            mkdirSync(join(full, ".."), { recursive: true });
-            writeFileSync(full, file.body);
-            console.log(`  wrote ${relative(dir, full)}`);
-        }
-        console.log(`\nwrote ${dir}`);
-        console.log(`  edit preset.json and the skill, then: howtofix preset check ${target}`);
-        return 0;
-    }
-    if (sub === "check" || sub === "pack") {
-        const dir = resolve(target ?? ".");
-        if (!existsSync(join(dir, "preset.json"))) {
-            console.log(`${sub}: no preset.json in ${dir}`);
-            return 2;
-        }
-        return (sub === "check" ? check(dir) : pack(dir)) ? 0 : 1;
-    }
-    console.log(`preset: unknown subcommand "${sub}"\n`);
-    console.log(usage());
-    return 2;
-}

package/dist/preset-extension.js

@@ -1,35 +0,0 @@
-import { readMessageText, writeMessageText } from "./prompt-text.js";
-import { installedPresetPrompts, installedPresetSkillPaths } from "./presets.js";
-/** Render the installed presets' prompt text as one labelled block. */
-export function renderPresetPrompts(cwd) {
-    const prompts = installedPresetPrompts(cwd);
-    if (prompts.length === 0)
-        return "";
-    const blocks = prompts.map((preset) => `<preset name="${preset.name}">\n${preset.text}\n</preset>`);
-    return ["The user installed the following presets. Their rules apply to this session.", "", ...blocks].join("\n");
-}
-export function createPresetExtension(cwd) {
-    return (hxf) => {
-        // `resources_discover` is the SDK's own channel for an extension to hand the
-        // resource loader extra skill directories, and it is re-emitted on
-        // `session.reload()` — which is what makes a preset installed mid-session
-        // visible without restarting the CLI. Registering the paths here rather than
-        // only through `additionalSkillPaths` also means the loader owns them, so a
-        // removed preset's skills disappear on the next reload instead of lingering.
-        hxf.on("resources_discover", async () => {
-            const skillPaths = installedPresetSkillPaths(cwd);
-            return skillPaths.length > 0 ? { skillPaths } : undefined;
-        });
-        hxf.on("context_with_system", async (event) => {
-            const block = renderPresetPrompts(cwd);
-            if (!block)
-                return undefined;
-            const head = event.messages[0];
-            if (!head || head.role !== "system")
-                return undefined;
-            const combined = `${readMessageText(head.content)}\n\n${block}`;
-            const messages = event.messages.map((message) => (message === head ? { ...head, content: writeMessageText(head.content, combined) } : message));
-            return { messages };
-        });
-    };
-}

package/dist/preset-mcp.js

@@ -1,292 +0,0 @@
-/**
- * MCP servers contributed by a preset.
- *
- * A preset was skills and prompt text only. That covers knowledge, not
- * capability: a preset that needs a tool — a filesystem server, a docs server —
- * could do nothing but tell the user to go and configure one by hand, and the
- * command for that lives in the SDK's own CLI (`hxf mcp add`), which the product
- * does not expose. A catalogue entry that can install the server it needs is the
- * difference between "here is how you would do this" and it working.
- *
- * So `preset.json` may carry an `mcp` object in the same `mcpServers` shape every
- * other MCP client uses. Installing the preset merges those servers into the
- * agent's `mcp.json`; removing it takes back exactly the ones it added.
- *
- * Three rules, because this writes configuration that starts processes:
- *
- *   - **Never overwrite a server the user already has.** A preset that replaces
- *     an existing entry could silently repoint a server at another binary or
- *     another URL. A name that is taken is reported and skipped, never merged.
- *   - **Never remove a server someone else still claims.** Removal only drops a
- *     name when no other installed preset declares it.
- *   - **Never run anything at install time.** The entry is written, not executed;
- *     the SDK connects it on the next session, and the user can see it with `/mcp`
- *     before it ever starts.
- */
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { writeFileAtomicSync } from "./fs-atomic.js";
-import { AGENT_DIR } from "./paths.js";
-/** Where the agent's servers live. The same file the SDK's own MCP support reads. */
-export function mcpConfigPath(agentDir = AGENT_DIR) {
-    return join(agentDir, "mcp.json");
-}
-/**
- * Validate the `mcp` block of a manifest.
- *
- * Returns every problem rather than the first, like the rest of the preset
- * validator: an author fixing one at a time is an author making several attempts.
- */
-export function validateMcpBlock(value) {
-    const problems = [];
-    if (value === undefined)
-        return problems;
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return ["mcp must be an object of server names"];
-    }
-    for (const [name, raw] of Object.entries(value)) {
-        // The SDK's own rule: letters, digits, `_` and `-`. A name outside it would be
-        // rejected when the config is read, which is a failure at session start
-        // rather than at install — exactly the kind of thing this check exists to
-        // catch while the author is still looking.
-        if (!/^[A-Za-z0-9_-]+$/.test(name)) {
-            problems.push(`mcp server "${name}" must use only letters, digits, _ and -`);
-            continue;
-        }
-        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-            problems.push(`mcp server "${name}" must be an object`);
-            continue;
-        }
-        const entry = raw;
-        const hasCommand = typeof entry.command === "string" && entry.command.trim() !== "";
-        const hasUrl = typeof entry.url === "string" && entry.url.trim() !== "";
-        if (!hasCommand && !hasUrl) {
-            problems.push(`mcp server "${name}" needs either a command or a url`);
-        }
-        if (entry.args !== undefined && !Array.isArray(entry.args)) {
-            problems.push(`mcp server "${name}": args must be an array`);
-        }
-        for (const key of ["env", "headers"]) {
-            const map = entry[key];
-            if (map === undefined)
-                continue;
-            if (typeof map !== "object" || map === null || Array.isArray(map)) {
-                problems.push(`mcp server "${name}": ${key} must be an object of strings`);
-                continue;
-            }
-            for (const [k, v] of Object.entries(map)) {
-                if (typeof v !== "string")
-                    problems.push(`mcp server "${name}": ${key}.${k} must be a string`);
-            }
-        }
-    }
-    return problems;
-}
-/** Read `mcp.json`, or an empty config when it is missing or unreadable. */
-function readConfig(path) {
-    if (!existsSync(path))
-        return { mcpServers: {} };
-    try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            return { mcpServers: {} };
-        const servers = parsed.mcpServers;
-        if (!servers || typeof servers !== "object" || Array.isArray(servers))
-            return { mcpServers: {} };
-        return { mcpServers: servers };
-    }
-    catch {
-        // A corrupt file is left alone rather than replaced: it may hold servers the
-        // user configured, and overwriting it to add one would lose them all. The
-        // install reports that it could not read the config.
-        return { mcpServers: {} };
-    }
-}
-/**
- * Add a preset's servers to `mcp.json`.
- *
- * An existing name is skipped and reported, never replaced. Returns what was
- * added and what was already there, so the install message can name both.
- */
-export function addMcpServers(servers, agentDir = AGENT_DIR) {
-    const names = Object.keys(servers);
-    if (names.length === 0)
-        return { added: [], skipped: [], problems: [] };
-    const path = mcpConfigPath(agentDir);
-    const problems = [];
-    if (existsSync(path)) {
-        // Distinguish "no file yet" from "a file this cannot parse": the first is a
-        // normal install, the second must not be silently overwritten.
-        try {
-            JSON.parse(readFileSync(path, "utf8"));
-        }
-        catch {
-            return { added: [], skipped: [], problems: [`${path} is not valid JSON; leaving it alone`] };
-        }
-    }
-    const config = readConfig(path);
-    const added = [];
-    const skipped = [];
-    for (const name of names) {
-        if (config.mcpServers[name] !== undefined) {
-            skipped.push(name);
-            continue;
-        }
-        config.mcpServers[name] = servers[name];
-        added.push(name);
-    }
-    if (added.length > 0) {
-        try {
-            writeFileAtomicSync(path, `${JSON.stringify(config, null, 2)}\n`);
-        }
-        catch (err) {
-            return { added: [], skipped, problems: [`could not write ${path}: ${err instanceof Error ? err.message : String(err)}`] };
-        }
-    }
-    return { added, skipped, problems };
-}
-/**
- * Take back the named servers, but only the ones nothing else claims.
- *
- * `claimed` is every server name any *other* installed preset still declares.
- * Dropping one of those would break the preset that still needs it, which is a
- * silent failure the next time that preset is used.
- */
-export function removeMcpServers(names, claimed = new Set(), agentDir = AGENT_DIR) {
-    const path = mcpConfigPath(agentDir);
-    const problems = [];
-    if (names.length === 0 || !existsSync(path))
-        return { removed: [], kept: [], problems };
-    const config = readConfig(path);
-    const removed = [];
-    const kept = [];
-    for (const name of names) {
-        if (config.mcpServers[name] === undefined)
-            continue;
-        if (claimed.has(name)) {
-            kept.push(name);
-            continue;
-        }
-        delete config.mcpServers[name];
-        removed.push(name);
-    }
-    if (removed.length > 0) {
-        try {
-            writeFileAtomicSync(path, `${JSON.stringify(config, null, 2)}\n`);
-        }
-        catch (err) {
-            return { removed: [], kept, problems: [`could not write ${path}: ${err instanceof Error ? err.message : String(err)}`] };
-        }
-    }
-    return { removed, kept, problems };
-}
-/** A one-line summary of a server entry, for a menu or a `show`. */
-export function describeMcpServer(spec) {
-    if (typeof spec.url === "string" && spec.url)
-        return `http: ${spec.url}`;
-    const command = typeof spec.command === "string" ? spec.command : "";
-    const args = Array.isArray(spec.args) ? spec.args.filter((a) => typeof a === "string") : [];
-    return `stdio: ${[command, ...args].join(" ")}`.trim();
-}
-/** Where the catalogue lives, next to the bundled presets. */
-export function mcpHubPath() {
-    return join(dirname(fileURLToPath(import.meta.url)), "presets", "mcp-hub.json");
-}
-/**
- * Read the catalogue.
- *
- * Never throws: a missing or malformed document is an empty catalogue with a
- * reason, because the menu that calls this is not a place that can fail to open.
- */
-export function readMcpHub(path = mcpHubPath()) {
-    const problems = [];
-    if (!existsSync(path))
-        return { entries: [], problems: [`no MCP catalogue at ${path}`] };
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch (err) {
-        return { entries: [], problems: [`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`] };
-    }
-    const raw = parsed?.entries;
-    if (!Array.isArray(raw))
-        return { entries: [], problems: [`${path} has no entries array`] };
-    const entries = [];
-    for (const item of raw) {
-        if (typeof item !== "object" || item === null || Array.isArray(item))
-            continue;
-        const record = item;
-        const name = typeof record.name === "string" ? record.name.trim() : "";
-        if (!name) {
-            problems.push("an entry has no name");
-            continue;
-        }
-        // The same rule the SDK enforces when it reads `mcp.json`. A name that fails
-        // it here would fail at connect time, in a session, with no hint that the
-        // catalogue was the source.
-        if (!/^[A-Za-z0-9_-]+$/.test(name)) {
-            problems.push(`"${name}" is not a usable server name`);
-            continue;
-        }
-        const hasCommand = typeof record.command === "string" && record.command.trim() !== "";
-        const hasUrl = typeof record.url === "string" && record.url.trim() !== "";
-        if (!hasCommand && !hasUrl) {
-            problems.push(`"${name}" has neither a command nor a url`);
-            continue;
-        }
-        entries.push({
-            name,
-            title: typeof record.title === "string" ? record.title : name,
-            description: typeof record.description === "string" ? record.description : "",
-            category: typeof record.category === "string" ? record.category : "other",
-            preset: typeof record.preset === "string" ? record.preset : undefined,
-            command: typeof record.command === "string" ? record.command : undefined,
-            url: typeof record.url === "string" ? record.url : undefined,
-            args: Array.isArray(record.args) ? record.args.filter((a) => typeof a === "string") : undefined,
-            env: record.env && typeof record.env === "object" && !Array.isArray(record.env) ? record.env : undefined,
-            needs: Array.isArray(record.needs) ? record.needs.filter((n) => typeof n === "string") : undefined,
-            docs: typeof record.docs === "string" ? record.docs : undefined,
-        });
-    }
-    return { entries, problems };
-}
-/** Categories present in the catalogue, sorted. */
-export function mcpHubCategories(entries) {
-    return [...new Set(entries.map((entry) => entry.category))].sort();
-}
-/** Entries in one category, sorted by title. */
-export function mcpHubIn(entries, category) {
-    return entries.filter((entry) => entry.category === category).sort((a, b) => a.title.localeCompare(b.title));
-}
-/** The catalogue entry for a name, or undefined. */
-export function mcpHubFind(entries, name) {
-    return entries.find((entry) => entry.name === name);
-}
-/** The server definition an entry describes, in the shape `mcp.json` holds. */
-export function serverSpecFromEntry(entry) {
-    const spec = {};
-    if (entry.command)
-        spec.command = entry.command;
-    if (entry.url)
-        spec.url = entry.url;
-    if (entry.args && entry.args.length > 0)
-        spec.args = [...entry.args];
-    if (entry.env && Object.keys(entry.env).length > 0)
-        spec.env = { ...entry.env };
-    if (entry.description)
-        spec.description = entry.description;
-    return spec;
-}
-/**
- * The environment variables an entry needs that are not set in this process.
- *
- * Reported rather than refused: the server is configured with `${NAME}` and the
- * SDK reads it at connect time, so a user who sets the variable in their shell
- * profile before the next session is fine. Saying which are missing turns a
- * server that connects and then fails every call into a sentence.
- */
-export function missingEnvFor(entry, env = process.env) {
-    return (entry.needs ?? []).filter((name) => !env[name]);
-}