@interlok/cli 0.0.0-stage → 1.3.1

package/dist/classify.js

@@ -0,0 +1,524 @@
+/**
+ * Tool risk classifier and coverage math.
+ *
+ * Deterministic on purpose, like the posture score: the same tool must classify the same way on
+ * every machine, in the console, in CI, and in the gate. No model, no network, no clock.
+ *
+ * This file imports nothing. The public CLI vendors it byte-for-byte (cli/src/classify.ts) and a
+ * test fails the build if the two copies drift, so a CI coverage number and a console coverage
+ * number can never disagree about the same inventory.
+ *
+ * Precedence, highest first:
+ *   1. A human declaration (recorded in the ledger) wins outright.
+ *   2. The registry's write_path, when the tool is registered.
+ *   3. The higher of annotation risk and name/schema heuristics. MCP annotations come from the
+ *      server and are untrusted, so they can raise risk but never lower it.
+ *   4. A tool whose name matches neither a read nor a write verb fails closed: it is treated as a
+ *      high-risk write path and counted as unclassified until someone declares it.
+ */
+export const CLASSIFIER_VERSION = "1.0.0";
+const TIERS = ["low", "medium", "high", "critical"];
+export const tierRank = (t) => TIERS.indexOf(t);
+export const maxTier = (a, b) => (tierRank(a) >= tierRank(b) ? a : b);
+export const atLeast = (t, floor) => tierRank(t) >= tierRank(floor);
+/* The gate's own write test, copied from write-path.ts so this file can stay import-free.
+   tests/classify.test.ts proves the invariant that matters: whenever inferWritePath calls a name a
+   write, so does the classifier. The classifier may be more cautious than the gate, never less. */
+const WRITE = /(create|update|delete|write|send|post|put|patch|exec|run|deploy|merge|push|remove|drop|insert|upsert|transfer|pay|approve|apply|set_|modify|rollback|restart|invite|revoke|grant|publish|purge|truncate|terminate|scale|provision)/i;
+const READ_OVERRIDE = /^(get|list|read|search|find|describe|fetch|show|query|count|head)_?/i;
+function gateSaysWrite(name) {
+    if (READ_OVERRIDE.test(name) && !WRITE.test(name.replace(READ_OVERRIDE, "")))
+        return false;
+    return WRITE.test(name);
+}
+/** Verb tokens, grouped by the consequence they carry. A token matches exactly or with s/es/ed/ing. */
+const VERBS = {
+    read: [
+        "get",
+        "list",
+        "read",
+        "search",
+        "find",
+        "describe",
+        "fetch",
+        "show",
+        "query",
+        "count",
+        "head",
+        "view",
+        "browse",
+        "lookup",
+        "inspect",
+        "check",
+        "validate",
+        "preview",
+        "summarize",
+        "summarise",
+        "analyze",
+        "analyse",
+        "diff",
+        "compare",
+        "resolve",
+        "explain",
+        "lint",
+        "screenshot",
+        "snapshot",
+        "navigate",
+        "think",
+        "sequentialthinking",
+        "status",
+        "whoami",
+        "ping",
+        "echo",
+        "health",
+        "download",
+        "retrieve",
+        "load",
+        "watch",
+        "poll",
+        "wait",
+        "calculate",
+        "convert",
+        "translate",
+        "parse",
+        "render",
+        "format",
+        "hover",
+        "scroll",
+        "estimate",
+        "verify",
+        "generate",
+        "log",
+        "show",
+    ],
+    payment: [
+        "pay",
+        "transfer",
+        "refund",
+        "charge",
+        "withdraw",
+        "disburse",
+        "payout",
+        "buy",
+        "purchase",
+        "sell",
+        "wire",
+    ],
+    access_grant: ["grant", "revoke", "invite", "impersonate", "share", "authorize", "unshare"],
+    destructive: [
+        "delete",
+        "remove",
+        "drop",
+        "truncate",
+        "destroy",
+        "purge",
+        "wipe",
+        "erase",
+        "terminate",
+        "kill",
+        "uninstall",
+        "reset",
+    ],
+    code_exec: ["exec", "execute", "shell", "bash", "eval", "evaluate", "spawn", "sh"],
+    deploy: [
+        "deploy",
+        "release",
+        "publish",
+        "merge",
+        "push",
+        "rollback",
+        "restart",
+        "scale",
+        "provision",
+        "promote",
+        "apply",
+        "run",
+        "trigger",
+        "dispatch",
+        "start",
+        "stop",
+        "reboot",
+        "pause",
+        "resume",
+    ],
+    outbound_msg: [
+        "send",
+        "post",
+        "notify",
+        "email",
+        "reply",
+        "comment",
+        "tweet",
+        "message",
+        "mail",
+        "sms",
+        "text",
+        "call",
+        "broadcast",
+        "dm",
+    ],
+    external_write: [],
+    data_write: [
+        "create",
+        "update",
+        "write",
+        "put",
+        "patch",
+        "insert",
+        "upsert",
+        "set",
+        "modify",
+        "edit",
+        "add",
+        "move",
+        "rename",
+        "upload",
+        "save",
+        "commit",
+        "approve",
+        "assign",
+        "unassign",
+        "close",
+        "reopen",
+        "label",
+        "unlabel",
+        "archive",
+        "cancel",
+        "submit",
+        "click",
+        "fill",
+        "type",
+        "press",
+        "drag",
+        "replace",
+        "star",
+        "unstar",
+        "fork",
+        "lock",
+        "unlock",
+        "pin",
+        "unpin",
+        "mark",
+        "enable",
+        "disable",
+        "schedule",
+        "book",
+        "order",
+        "import",
+        "sync",
+        "restore",
+        "copy",
+        "duplicate",
+        "configure",
+        "register",
+        "unregister",
+        "subscribe",
+        "unsubscribe",
+        "react",
+        "finalize",
+        "confirm",
+        "rebase",
+        "checkout",
+        "open",
+        "select",
+        "draft",
+    ],
+};
+/** A verbless name made only of these reads as a lookup: `directory_tree`, `git_log`, `project_info`. */
+const READ_NOUNS = /^(tree|info|details|docs|documentation|history|logs|stats|metrics|overview|time|weather|status|version|schema|summary|usage)$/;
+/** Nouns that sharpen a write verb: `create_payment` is a payment, `add_member` grants access. */
+const NOUNS = [
+    [
+        /^(payment|payments|payout|payouts|transfer|transfers|refund|refunds|charge|charges|funds|money|wire|invoice_payment)$/,
+        "payment",
+    ],
+    [
+        /^(member|members|role|roles|permission|permissions|collaborator|collaborators|access|acl|apikey|api_key|key|keys|token|tokens|secret|secrets|owner|admin|policy|policies)$/,
+        "access_grant",
+    ],
+    [/^(command|commands|script|scripts|code|shell|terminal|cmd|process)$/, "code_exec"],
+    [
+        /^(deployment|deployments|release|releases|production|prod|workflow|workflows|pipeline|pipelines|job|jobs|build|builds|instance|instances|cluster|clusters|service|services|function|functions)$/,
+        "deploy",
+    ],
+    [
+        /^(email|emails|message|messages|sms|notification|notifications|tweet|post|comment|comments|reply|dm|chat)$/,
+        "outbound_msg",
+    ],
+];
+const SCHEMA_CLASSES = [
+    [
+        /^(amount|amount_cents|price|cost|total|currency|iban|routing|account_number|card|payment_method)$/i,
+        "financial",
+    ],
+    [
+        /^(to|cc|bcc|recipient|recipients|phone|phone_number|email|email_address|channel|channel_id|user_ids?)$/i,
+        "comms",
+    ],
+    [
+        /^(ssn|social_security|dob|date_of_birth|passport|address|full_name|patient|medical_record)$/i,
+        "pii",
+    ],
+    [/^(password|secret|token|api_key|apikey|credential|credentials|private_key)$/i, "secrets"],
+    [/^(sql|query|statement|table|table_name|database|schema)$/i, "prod_data"],
+];
+const DESCRIPTION_IRREVERSIBLE = /(irreversibl|permanently|cannot be undone|can't be undone|no way to recover)/i;
+const EFFECT_TIER = {
+    payment: "critical",
+    access_grant: "critical",
+    destructive: "critical",
+    code_exec: "critical",
+    deploy: "high",
+    outbound_msg: "high",
+    external_write: "medium",
+    data_write: "medium",
+};
+const CLASS_TIER = {
+    financial: "high",
+    secrets: "high",
+    prod_data: "high",
+    pii: "medium",
+    comms: "medium",
+};
+/** The verb part of a namespaced or dotted tool name: `github/create_release` → `create_release`. */
+export function bareToolName(tool) {
+    const cut = Math.max(tool.lastIndexOf("/"), tool.lastIndexOf(":"), tool.lastIndexOf("."));
+    return cut >= 0 ? tool.slice(cut + 1) : tool;
+}
+/** camelCase and kebab-case to snake_case, so `sendEmail` and `send-email` match `send_email`. */
+function normalize(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[-\s]+/g, "_")
+        .toLowerCase();
+}
+const tokens = (name) => name.split(/_+/).filter(Boolean);
+const inflect = (tok, verb) => tok === verb ||
+    tok === `${verb}s` ||
+    tok === `${verb}es` ||
+    tok === `${verb}ed` ||
+    tok === `${verb}d` ||
+    tok === `${verb}ing` ||
+    tok === `${verb.replace(/e$/, "")}ing` ||
+    tok === `${verb}${verb.slice(-1)}ing`;
+const verbOf = (tok, group, exact = false) => VERBS[group].some((v) => (exact ? tok === v : inflect(tok, v)));
+function schemaKeys(schema) {
+    const props = schema?.properties;
+    return props && typeof props === "object" ? Object.keys(props) : [];
+}
+const uniq = (xs) => [...new Set(xs)].sort();
+const WRITE_GROUPS = [
+    "payment",
+    "access_grant",
+    "destructive",
+    "code_exec",
+    "deploy",
+    "outbound_msg",
+    "data_write",
+];
+export function classifyTool(t, declared) {
+    const name = normalize(bareToolName(t.name));
+    const toks = tokens(name);
+    const basis = [];
+    const effects = [];
+    const classes = [];
+    let tier = "low";
+    let reversibility = "unknown";
+    let source = "heuristic";
+    // Which verb tokens are present, by consequence. Once a read verb has appeared, a later token
+    // only counts as a write verb in its bare form: `get_or_create_user` writes, but in
+    // `list_releases` and `list_runs` the plural is a noun being listed.
+    const firstRead = toks.findIndex((tok) => verbOf(tok, "read"));
+    const firstWrite = toks.findIndex((tok) => WRITE_GROUPS.some((g) => verbOf(tok, g)));
+    const readLeads = firstRead >= 0 && (firstWrite < 0 || firstRead < firstWrite);
+    const verbEffects = WRITE_GROUPS.filter((g) => toks.some((tok, i) => verbOf(tok, g, readLeads && i > firstRead)));
+    // A verbless name that ends in a lookup noun reads: `directory_tree`, `project_info`.
+    const hasReadVerb = firstRead >= 0 || READ_NOUNS.test(toks[toks.length - 1] ?? "");
+    const gateWrite = gateSaysWrite(name);
+    let write;
+    if (verbEffects.length) {
+        // A write verb wins over a read verb: `get_or_create_user` writes.
+        write = true;
+        effects.push(...verbEffects);
+        basis.push(`write verb in "${name}"`);
+        // Nouns only sharpen a real write verb, never invent one.
+        for (const tok of toks)
+            for (const [re, e] of NOUNS)
+                if (re.test(tok))
+                    effects.push(e);
+    }
+    else if (gateWrite) {
+        // The gate's substring test sees a write (e.g. "pay" inside get_payment_status) but no write
+        // verb token does. Stay at least as cautious as the gate, without inventing a consequence.
+        write = true;
+        effects.push("data_write");
+        basis.push(`the gate's write test matches "${name}"`);
+    }
+    else if (hasReadVerb) {
+        write = false;
+        basis.push(`read verb in "${name}"`);
+    }
+    else
+        write = null;
+    for (const k of schemaKeys(t.input_schema))
+        for (const [re, c] of SCHEMA_CLASSES)
+            if (re.test(k))
+                classes.push(c);
+    if (classes.length)
+        basis.push(`argument names suggest ${uniq(classes).join(", ")}`);
+    // Annotations can raise, never lower.
+    const a = t.annotations ?? {};
+    if (a.destructiveHint === true) {
+        write = true;
+        effects.push("destructive");
+        basis.push("annotated destructive");
+        source = "annotation";
+    }
+    if (a.readOnlyHint === false && write !== true) {
+        write = true;
+        effects.push("data_write");
+        basis.push("annotated not read-only");
+        source = "annotation";
+    }
+    if (a.openWorldHint === true && write) {
+        effects.push("external_write");
+        basis.push("annotated open-world");
+    }
+    // Registry write_path beats everything but a declaration.
+    if (typeof t.write_path === "boolean") {
+        if (t.write_path !== write)
+            basis.push(`registry says ${t.write_path ? "write" : "read"}`);
+        write = t.write_path;
+        source = "registry";
+        if (write && !effects.length)
+            effects.push("data_write");
+    }
+    let unclassified = false;
+    if (write === null) {
+        // Neither a read verb nor a write verb: fail closed.
+        write = true;
+        unclassified = true;
+        source = "unknown";
+        tier = "high";
+        basis.push(`no recognized verb in "${name}"; treated as a high-risk write until declared`);
+    }
+    if (write) {
+        for (const e of effects)
+            tier = maxTier(tier, EFFECT_TIER[e]);
+        for (const c of classes)
+            tier = maxTier(tier, CLASS_TIER[c]);
+        if (classes.includes("comms") && effects.length === 1 && effects[0] === "data_write") {
+            effects.push("outbound_msg");
+            tier = maxTier(tier, "high");
+        }
+        reversibility = effects.includes("destructive")
+            ? "irreversible"
+            : effects.includes("payment") || effects.includes("outbound_msg")
+                ? "compensable"
+                : effects.length
+                    ? "reversible"
+                    : "unknown";
+        if (t.description && DESCRIPTION_IRREVERSIBLE.test(t.description)) {
+            reversibility = "irreversible";
+            tier = maxTier(tier, "high");
+            basis.push("description says it cannot be undone");
+        }
+    }
+    else {
+        tier = "low";
+        reversibility = "reversible";
+    }
+    let profile = {
+        tool: t.name,
+        write_path: write,
+        risk_tier: tier,
+        reversibility,
+        data_classes: uniq(classes),
+        side_effects: write ? uniq(effects) : [],
+        source,
+        unclassified,
+        basis,
+        classifier_version: CLASSIFIER_VERSION,
+    };
+    if (declared && Object.keys(declared).length) {
+        profile = {
+            ...profile,
+            ...(declared.write_path !== undefined ? { write_path: declared.write_path } : {}),
+            ...(declared.risk_tier ? { risk_tier: declared.risk_tier } : {}),
+            ...(declared.reversibility ? { reversibility: declared.reversibility } : {}),
+            ...(declared.data_classes ? { data_classes: uniq(declared.data_classes) } : {}),
+            ...(declared.side_effects ? { side_effects: uniq(declared.side_effects) } : {}),
+            source: "declared",
+            unclassified: false,
+            basis: [...basis, "declared by a person"],
+        };
+        if (!profile.write_path)
+            profile = { ...profile, risk_tier: declared.risk_tier ?? "low", side_effects: [] };
+    }
+    return profile;
+}
+const RUNGS = ["guarded", "exercised", "governed", "enforced"];
+export function computeCoverage(items, threshold = "high") {
+    const byKey = new Map();
+    for (const i of items) {
+        const prev = byKey.get(i.key);
+        // The same path listed twice keeps its highest risk and any rung that is true on either.
+        if (!prev)
+            byKey.set(i.key, i);
+        else
+            byKey.set(i.key, {
+                key: i.key,
+                profile: tierRank(i.profile.risk_tier) > tierRank(prev.profile.risk_tier)
+                    ? i.profile
+                    : prev.profile,
+                guarded: or(prev.guarded, i.guarded),
+                exercised: or(prev.exercised, i.exercised),
+                governed: or(prev.governed, i.governed),
+                enforced: or(prev.enforced, i.enforced),
+            });
+    }
+    const high = [...byKey.values()]
+        .filter((i) => i.profile.write_path && atLeast(i.profile.risk_tier, threshold))
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const rungs = {};
+    for (const r of RUNGS) {
+        if (!high.some((i) => i[r] !== undefined) && !items.some((i) => i[r] !== undefined))
+            continue;
+        const covered = high.filter((i) => i[r] === true).length;
+        rungs[r] = {
+            covered,
+            total: high.length,
+            pct: high.length ? Math.round((covered / high.length) * 100) : null,
+        };
+    }
+    return {
+        classifier_version: CLASSIFIER_VERSION,
+        threshold,
+        high_risk_write_paths: high.length,
+        unclassified: high.filter((i) => i.profile.unclassified).length,
+        rungs,
+        paths: high.map((i) => ({
+            key: i.key,
+            risk_tier: i.profile.risk_tier,
+            unclassified: i.profile.unclassified,
+            ...(i.guarded !== undefined ? { guarded: i.guarded } : {}),
+            ...(i.exercised !== undefined ? { exercised: i.exercised } : {}),
+            ...(i.governed !== undefined ? { governed: i.governed } : {}),
+            ...(i.enforced !== undefined ? { enforced: i.enforced } : {}),
+        })),
+    };
+}
+function or(a, b) {
+    if (a === undefined && b === undefined)
+        return undefined;
+    return a === true || b === true;
+}
+/** One line a person can read: "guarded 3/8 (38%) · 2 unclassified". */
+export function coverageLine(c, rung = "guarded") {
+    const r = c.rungs[rung];
+    if (!c.high_risk_write_paths)
+        return "no high-risk write paths found";
+    const pct = r?.pct === null || r?.pct === undefined ? "—" : `${r.pct}%`;
+    const un = c.unclassified ? ` · ${c.unclassified} unclassified` : "";
+    return `${rung} ${r?.covered ?? 0}/${c.high_risk_write_paths} (${pct})${un}`;
+}

package/dist/gate.d.ts

@@ -0,0 +1,19 @@
+export declare function collectContext(agentIds?: string[]): {
+    repo: string | null;
+    ref: string | null;
+    commit_sha: string | null;
+    pr_number: number | null;
+    requester: string | null;
+    author_kinds: string[];
+    author_ids: string[];
+    changed_paths: string[];
+    files_changed: number;
+    source_ref: string;
+};
+export declare function planFromFile(path: string): {
+    summary: import("./packs.js").PlanSummary;
+    plan_hash: string;
+};
+/** `--action model.promote` flags → the model description the Change Gate judges. */
+export declare function modelFromFlags(value: (n: string) => string | undefined): string | Record<string, unknown>;
+export declare function gateCommand(args: string[], value: (n: string) => string | undefined, has: (n: string) => boolean): Promise<void>;