@bridge_gpt/mcp-server 0.2.0 → 0.2.2

package/build/command-catalog.js

@@ -0,0 +1,376 @@
+/**
+ * Local command catalog discovery for the generalized `schedule-run` CLI
+ * (BAPI-351). Turns the user's `.claude/commands/*.md` slash-command files into
+ * validated, schedulable command payloads.
+ *
+ * Design constraints (locked in the ticket):
+ *  - `.claude/commands` is the canonical catalog for BOTH Claude and Cursor; we
+ *    never scan the Cursor commands directory (a local spike confirmed
+ *    cursor-agent resolves the same `.claude/commands` catalog).
+ *  - Commands are schedulable by default; an explicit `schedulable: false`
+ *    frontmatter marker is the only opt-out.
+ *  - The per-command `arguments:` frontmatter block must be valid JSON (a strict
+ *    subset of YAML) parsed with native `JSON.parse()` — NO new YAML/frontmatter
+ *    parser dependency is added. The parsed shape is validated with Zod, which is
+ *    already a dependency.
+ *  - Malformed command files surface as structured errors; discovery never
+ *    silently falls back to unvalidated freeform scheduling for a broken file.
+ */
+import { promises as nodeFs } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+/** Default fs deps backed by `node:fs/promises`. */
+export function createDefaultCommandCatalogFsDeps() {
+    return {
+        readdir: (dir) => nodeFs.readdir(dir),
+        readFile: (file) => nodeFs.readFile(file, "utf-8"),
+    };
+}
+const PositionalZ = z.object({
+    name: z.string().min(1),
+    type: z.string().default("string"),
+    required: z.boolean().default(false),
+    variadic: z.boolean().default(false),
+    default: z.unknown().optional(),
+});
+const FlagZ = z.object({
+    name: z.string().min(1),
+    // A flag MUST be written in its long form (e.g. `--auto`); `flag: "auto"` is a
+    // common authoring mistake and is rejected so it fails fast at schedule time.
+    flag: z.string().regex(/^--[A-Za-z0-9][A-Za-z0-9-]*$/, "flag must start with '--'"),
+    type: z.string().default("string"),
+    required: z.boolean().default(false),
+    repeatable: z.boolean().default(false),
+    default: z.unknown().optional(),
+});
+const ArgumentSchemaZ = z.object({
+    positionals: z.array(PositionalZ).default([]),
+    flags: z.array(FlagZ).default([]),
+    allowExtraPositionals: z.boolean().default(false),
+});
+/**
+ * Parse a raw `arguments:` value as JSON and validate it with Zod. Non-JSON
+ * input (e.g. a YAML block) produces a controlled error — there is no YAML
+ * fallback.
+ */
+export function parseArgumentsSchema(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: `invalid JSON in 'arguments:' frontmatter (must be valid JSON, not YAML): ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const validated = ArgumentSchemaZ.safeParse(parsed);
+    if (!validated.success) {
+        return {
+            ok: false,
+            error: `invalid 'arguments:' schema: ${validated.error.issues
+                .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+                .join("; ")}`,
+        };
+    }
+    return { ok: true, schema: validated.data };
+}
+/**
+ * Split a command markdown file into (optional) leading frontmatter and the body.
+ * A file with no leading `---` fence is valid: it has no metadata and the whole
+ * file is the body (freeform, schedulable by default). A file that opens a `---`
+ * fence but never closes it is malformed and surfaces a structured error.
+ */
+function splitFrontmatter(raw) {
+    const lines = raw.split(/\r?\n/);
+    if (lines.length === 0 || lines[0].trim() !== "---") {
+        return { ok: true, frontmatter: null, body: raw };
+    }
+    let closeIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === "---") {
+            closeIndex = i;
+            break;
+        }
+    }
+    if (closeIndex === -1) {
+        return { ok: false, error: "unterminated frontmatter: opening '---' has no closing '---'" };
+    }
+    const frontmatterText = lines.slice(1, closeIndex).join("\n");
+    const body = lines.slice(closeIndex + 1).join("\n");
+    const parsed = parseFrontmatterText(frontmatterText);
+    if (!parsed.ok)
+        return parsed;
+    return { ok: true, frontmatter: parsed.frontmatter, body };
+}
+/**
+ * Parse the simple `key: value` frontmatter lines we recognize. `schedulable`
+ * and `interactive` are scalar booleans read with a narrow line match;
+ * `arguments:` is a single-line JSON value validated via {@link parseArgumentsSchema}.
+ * Unknown keys are ignored so command files can carry other frontmatter (e.g.
+ * Claude Code's own `description:`/`argument-hint:`) without breaking discovery.
+ */
+function parseFrontmatterText(text) {
+    let schedulable = true;
+    let interactive = false;
+    let argumentSchema;
+    for (const rawLine of text.split("\n")) {
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const schedulableMatch = line.match(/^schedulable:\s*(true|false)\s*$/);
+        if (schedulableMatch) {
+            schedulable = schedulableMatch[1] === "true";
+            continue;
+        }
+        const interactiveMatch = line.match(/^interactive:\s*(true|false)\s*$/);
+        if (interactiveMatch) {
+            interactive = interactiveMatch[1] === "true";
+            continue;
+        }
+        const argsMatch = rawLine.match(/^\s*arguments:\s*(.*)$/);
+        if (argsMatch) {
+            const value = argsMatch[1].trim();
+            if (value === "") {
+                return { ok: false, error: "'arguments:' frontmatter key has no JSON value" };
+            }
+            const schemaResult = parseArgumentsSchema(value);
+            if (!schemaResult.ok)
+                return schemaResult;
+            argumentSchema = schemaResult.schema;
+            continue;
+        }
+        // Unknown frontmatter key: ignore (forward-compatible).
+    }
+    return { ok: true, frontmatter: { schedulable, interactive, argumentSchema } };
+}
+/** Command names must be a single safe token derived from the filename. */
+const COMMAND_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/** Absolute path to the `.claude/commands` directory under a repo. */
+export function commandsDirForRepo(repoPath, platform) {
+    const pathApi = platform === "win32" ? path.win32 : path.posix;
+    return pathApi.join(repoPath, ".claude", "commands");
+}
+/**
+ * Discover every `.claude/commands/*.md` command under `repoPath`. Returns a
+ * deterministic (name-sorted) list of valid commands plus a parallel list of
+ * structured errors for malformed files. A missing `.claude/commands` directory
+ * yields an empty catalog (no error) — the caller decides whether that is fatal.
+ *
+ * The Cursor commands directory is intentionally never scanned.
+ */
+export async function discoverCommandCatalog(repoPath, platform, fsDeps = createDefaultCommandCatalogFsDeps()) {
+    const pathApi = platform === "win32" ? path.win32 : path.posix;
+    const dir = commandsDirForRepo(repoPath, platform);
+    let entries;
+    try {
+        entries = await fsDeps.readdir(dir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { commands: [], errors: [] };
+        }
+        throw error;
+    }
+    const commands = [];
+    const errors = [];
+    for (const entry of [...entries].sort()) {
+        if (!entry.endsWith(".md"))
+            continue;
+        const name = entry.slice(0, -".md".length);
+        const filePath = pathApi.join(dir, entry);
+        if (!COMMAND_NAME_PATTERN.test(name)) {
+            errors.push({
+                name,
+                filePath,
+                error: `unsafe command name '${name}' (must match ${COMMAND_NAME_PATTERN.source})`,
+            });
+            continue;
+        }
+        let raw;
+        try {
+            raw = await fsDeps.readFile(filePath);
+        }
+        catch (error) {
+            errors.push({
+                name,
+                filePath,
+                error: `could not read command file: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            continue;
+        }
+        const split = splitFrontmatter(raw);
+        if (!split.ok) {
+            errors.push({ name, filePath, error: split.error });
+            continue;
+        }
+        const fm = split.frontmatter;
+        commands.push({
+            name,
+            filePath,
+            schedulable: fm?.schedulable ?? true,
+            interactive: fm?.interactive ?? false,
+            body: split.body,
+            argumentSchema: fm?.argumentSchema,
+        });
+    }
+    commands.sort((a, b) => a.name.localeCompare(b.name));
+    return { commands, errors };
+}
+/**
+ * Resolve a requested command name against a discovered catalog for
+ * `schedule-run create`: reject unknown commands, commands that failed to parse
+ * (malformed frontmatter / invalid schema), and commands marked
+ * `schedulable: false`, each with a clear, actionable message.
+ */
+export function resolveSchedulableCommand(catalog, name) {
+    const broken = catalog.errors.find((e) => e.name === name);
+    if (broken) {
+        return {
+            ok: false,
+            error: `Command '${name}' is not schedulable: ${broken.error}.`,
+        };
+    }
+    const command = catalog.commands.find((c) => c.name === name);
+    if (!command) {
+        const available = catalog.commands.map((c) => c.name).join(", ") || "(none discovered)";
+        return {
+            ok: false,
+            error: `Unknown command '${name}'. Discovered commands: ${available}.`,
+        };
+    }
+    if (!command.schedulable) {
+        return {
+            ok: false,
+            error: `Command '${name}' is marked 'schedulable: false' and cannot be scheduled.`,
+        };
+    }
+    return { ok: true, command };
+}
+/**
+ * Validate and normalize structured post-`--` command argv against an optional
+ * argument schema.
+ *
+ *  - No schema → freeform passthrough: tokens are returned verbatim (boundaries
+ *    preserved) and `parsed.freeform` is true.
+ *  - With a schema → positional and flag tokens are validated; `--flag=value`
+ *    forms are normalized to two tokens while preserving the logical value;
+ *    boolean flags consume no value; repeatable flags collect arrays; unknown
+ *    flags, missing required args, missing flag values, and disallowed extra
+ *    positionals each fail with a controlled error.
+ *
+ * No token is ever concatenated into a shell string; the host shell (or agent)
+ * already split argv exactly once before it reached here.
+ */
+export function validateCommandArgv(argv, schema) {
+    if (!schema) {
+        return {
+            ok: true,
+            normalizedArgv: [...argv],
+            parsed: { freeform: true, positionals: {}, extraPositionals: [], flags: {} },
+        };
+    }
+    const flagByLong = new Map();
+    for (const f of schema.flags)
+        flagByLong.set(f.flag, f);
+    const normalizedArgv = [];
+    const positionalTokens = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith("--")) {
+            const eqIndex = token.indexOf("=");
+            const flagName = eqIndex === -1 ? token : token.slice(0, eqIndex);
+            const inlineValue = eqIndex === -1 ? undefined : token.slice(eqIndex + 1);
+            const descriptor = flagByLong.get(flagName);
+            if (!descriptor) {
+                return { ok: false, error: `Unknown flag '${flagName}' for this command.` };
+            }
+            if (descriptor.type === "boolean") {
+                if (inlineValue !== undefined) {
+                    return { ok: false, error: `Boolean flag '${flagName}' does not take a value.` };
+                }
+                flags[descriptor.name] = true;
+                normalizedArgv.push(flagName);
+                continue;
+            }
+            // string flag — needs a value (inline `=value` or the next token).
+            let value;
+            if (inlineValue !== undefined) {
+                value = inlineValue;
+            }
+            else {
+                if (i + 1 >= argv.length) {
+                    return { ok: false, error: `Flag '${flagName}' requires a value.` };
+                }
+                value = argv[++i];
+            }
+            if (descriptor.repeatable) {
+                const existing = flags[descriptor.name];
+                if (Array.isArray(existing))
+                    existing.push(value);
+                else
+                    flags[descriptor.name] = [value];
+            }
+            else {
+                flags[descriptor.name] = value;
+            }
+            normalizedArgv.push(flagName, value);
+            continue;
+        }
+        positionalTokens.push(token);
+        normalizedArgv.push(token);
+    }
+    // Validate required flags + apply defaults.
+    for (const f of schema.flags) {
+        if (!(f.name in flags)) {
+            if (f.required) {
+                return { ok: false, error: `Missing required flag '${f.flag}'.` };
+            }
+            if (f.default !== undefined) {
+                flags[f.name] = f.default;
+            }
+        }
+    }
+    // Assign positionals in declared order; a variadic positional consumes the rest.
+    const positionals = {};
+    let cursor = 0;
+    for (const p of schema.positionals) {
+        if (p.variadic) {
+            const rest = positionalTokens.slice(cursor);
+            cursor = positionalTokens.length;
+            if (p.required && rest.length === 0) {
+                return { ok: false, error: `Missing required positional '${p.name}'.` };
+            }
+            positionals[p.name] = rest;
+            continue;
+        }
+        if (cursor < positionalTokens.length) {
+            positionals[p.name] = positionalTokens[cursor++];
+        }
+        else if (p.required) {
+            return { ok: false, error: `Missing required positional '${p.name}'.` };
+        }
+        else if (p.default !== undefined) {
+            positionals[p.name] = p.default;
+        }
+    }
+    const extraPositionals = positionalTokens.slice(cursor);
+    if (extraPositionals.length > 0 && !schema.allowExtraPositionals) {
+        return {
+            ok: false,
+            error: `Unexpected extra positional argument(s): ${extraPositionals.join(", ")}.`,
+        };
+    }
+    return {
+        ok: true,
+        normalizedArgv,
+        parsed: { freeform: false, positionals, extraPositionals, flags },
+    };
+}
+/** True when a command schema declares a boolean `--auto` flag (or none/freeform). */
+export function schemaSupportsAutoFlag(schema) {
+    if (!schema)
+        return false;
+    return schema.flags.some((f) => f.flag === "--auto" && f.type === "boolean");
+}