@descryy/mcp 0.11.5 → 0.11.6

package/dist/tools/observe.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `observe` — merges `observe_runtime` and `observe_tests` into one action-class tool
+ * (documents/plans/mcp-surface-consolidation.md, group 1). Dispatches on "verb" to the exact
+ * `run`/`describeAction` bodies each absorbed tool already had (see observe-runtime.ts,
+ * observe-tests.ts) — extracted, not reimplemented, so behaviour is unchanged per verb.
+ *
+ * The schema below restates both tools' arguments under one flat, `additionalProperties: false`
+ * shape — required by the merge itself, since a merged tool has one schema for two verbs. It is
+ * also deliberately far shorter than `observe_runtime`'s own prose (that tool alone was 10,646
+ * schema bytes, 14% of the whole registry). Nothing here drops an argument, an enum value, a
+ * default, or a conditional-requirement rule — only the narrative explaining each one. The real
+ * behaviour (every disclosure, every refusal) still lives in the reused `run`/`describeAction`
+ * bodies, untouched by this trim.
+ */
+import type { ToolDefinition } from "./kit.ts";
+import type { ObserveRuntimeData } from "./observe-runtime.ts";
+import type { ObserveTestsData } from "./observe-tests.ts";
+/**
+ * What this tool answers with: one verb's shape, never a merged one.
+ *
+ * The merge cost this its single concrete output type, and `unknown` would have
+ * silently retired `output-shapes.test.ts`'s check that a declared shape is tied
+ * to the code producing it. A union keeps that tie: a verb added without its
+ * shape here stops compiling.
+ */
+export type ObserveData = ObserveRuntimeData | ObserveTestsData;
+export declare const observeTool: ToolDefinition;
+//# sourceMappingURL=observe.d.ts.map

package/dist/tools/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/tools/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,UAAU,CAAC;AAQ5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB,kBAAkB,GAClB,gBAAgB,CAAC;AA4QrB,eAAO,MAAM,WAAW,EAAE,cAczB,CAAC"}

package/dist/tools/observe.js

@@ -0,0 +1,291 @@
+/**
+ * `observe` — merges `observe_runtime` and `observe_tests` into one action-class tool
+ * (documents/plans/mcp-surface-consolidation.md, group 1). Dispatches on "verb" to the exact
+ * `run`/`describeAction` bodies each absorbed tool already had (see observe-runtime.ts,
+ * observe-tests.ts) — extracted, not reimplemented, so behaviour is unchanged per verb.
+ *
+ * The schema below restates both tools' arguments under one flat, `additionalProperties: false`
+ * shape — required by the merge itself, since a merged tool has one schema for two verbs. It is
+ * also deliberately far shorter than `observe_runtime`'s own prose (that tool alone was 10,646
+ * schema bytes, 14% of the whole registry). Nothing here drops an argument, an enum value, a
+ * default, or a conditional-requirement rule — only the narrative explaining each one. The real
+ * behaviour (every disclosure, every refusal) still lives in the reused `run`/`describeAction`
+ * bodies, untouched by this trim.
+ */
+import { SAFETY_LEVELS, PROFILE_MODES } from "@descryy/runtime-environment-profile";
+import { selectVerb } from "./verb.js";
+import { run as runRuntime, describeAction as describeRuntimeAction, DEFAULT_EVIDENCE_RELATIVE_PATH, } from "./observe-runtime.js";
+import { run as runTests, describeAction as describeTestsAction } from "./observe-tests.js";
+/** Mirrors observe-runtime.ts's own module-local `READINESS_KINDS` — kept as a literal here
+ *  rather than imported so this schema module has no other reason to reach into that file's
+ *  internals beyond the two functions it reuses. */
+const READINESS_KINDS = ["http", "tcp-port", "command"];
+const VERB_SPECS = [
+    {
+        verb: "runtime",
+        accepts: [
+            "profile",
+            "services",
+            "adapter",
+            "scopeByService",
+            "observeForMs",
+            "environmentTier",
+            "fidelityLevel",
+            "evidencePath",
+            "resourceLimits",
+            "filesystemPolicy",
+            "networkPolicy",
+            "sandboxBackend",
+            "journey",
+            "database",
+        ],
+    },
+    { verb: "tests", accepts: ["command", "cwd"] },
+];
+/** `timeoutMs` means a different thing per verb (whole-execution budget vs. suite timeout) but
+ *  is the same key in both schemas — shared so neither verb refuses the other's caller for
+ *  sending it. `confirmToken` is the handshake's own field, not either tool's. */
+const SHARED_PROPS = ["confirmToken", "timeoutMs"];
+const SCHEMA = {
+    type: "object",
+    properties: {
+        verb: {
+            type: "string",
+            enum: ["runtime", "tests"],
+            description: "runtime: boot/attach services and record evidence. tests: run the suite and record what ran.",
+        },
+        // --- runtime only ---
+        profile: {
+            type: "object",
+            description: "runtime, REQUIRED. Target environment; every field explicit, never inferred.",
+            properties: {
+                name: { type: "string" },
+                url: { type: "string" },
+                safetyLevel: {
+                    type: "string",
+                    enum: [...SAFETY_LEVELS],
+                    description: "readOnly blocks spawning; all-attach is fine under readOnly.",
+                },
+                credentialRef: { type: "string", description: "Opaque credential key, never the secret." },
+                mode: { type: "string", enum: [...PROFILE_MODES] },
+            },
+            required: ["name", "url", "safetyLevel", "credentialRef", "mode"],
+            additionalProperties: false,
+        },
+        services: {
+            type: "object",
+            description: "runtime, REQUIRED. One per service, keyed by name; each needs command or attach.",
+            additionalProperties: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "How to start it. Omit if using attach." },
+                    cwd: { type: "string", description: "Working directory. Required with command." },
+                    port: {
+                        type: "integer",
+                        description: "REQUIRED with attach for http/tcp-port readiness. Else omit for an ephemeral port.",
+                    },
+                    dependsOn: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Services that must be ready first.",
+                    },
+                    env: { type: "object", additionalProperties: { type: "string" } },
+                    attach: {
+                        type: "object",
+                        description: "Observe an already-running process instead of spawning one.",
+                        properties: {
+                            pid: { type: "integer" },
+                            logFilePath: { type: "string", description: "File the process writes stdout/stderr to." },
+                        },
+                        required: ["pid", "logFilePath"],
+                        additionalProperties: false,
+                    },
+                    readiness: {
+                        type: "object",
+                        description: "Required per service. Only http/tcp-port/command are supported here.",
+                        properties: {
+                            kind: { type: "string", enum: [...READINESS_KINDS] },
+                            path: { type: "string", description: 'http: path after host/port. Default "/".' },
+                            expectedStatus: { type: "integer", description: "http: default any 2xx/3xx." },
+                            host: { type: "string", description: "tcp-port: default 127.0.0.1." },
+                            command: { type: "string", description: "command: executable to run." },
+                            args: { type: "array", items: { type: "string" }, description: "command: arguments." },
+                            timeoutMs: { type: "integer", description: "Default 30000." },
+                        },
+                        required: ["kind"],
+                        additionalProperties: false,
+                    },
+                },
+                required: ["readiness"],
+                additionalProperties: false,
+            },
+        },
+        adapter: {
+            type: "object",
+            description: "runtime, REQUIRED. Adapter module to observe with; install one and name it here.",
+            properties: {
+                module: { type: "string" },
+                export: { type: "string", description: "Defaults to the sole factory export." },
+                options: { type: "object", description: "Passed to the factory." },
+            },
+            required: ["module"],
+            additionalProperties: false,
+        },
+        scopeByService: {
+            type: "object",
+            description: "runtime. Service name → repo its symbols resolve in. Default: this session's own repo.",
+            additionalProperties: {
+                type: "object",
+                properties: {
+                    repo: { type: "string" },
+                    repoRoot: { type: "string", description: "Absolute root, for path translation." },
+                    cwd: { type: "string" },
+                },
+                required: ["repo"],
+                additionalProperties: false,
+            },
+        },
+        observeForMs: {
+            type: "integer",
+            description: "runtime. How long to drain output after services are ready. Default 5000.",
+        },
+        timeoutMs: {
+            type: "integer",
+            description: "Timeout, ms. runtime: whole run, default 60000. tests: suite limit, default 600000.",
+        },
+        environmentTier: {
+            type: "string",
+            enum: ["tier-0-ci-attached", "tier-1-preview", "tier-2-container", "tier-2b-api-only", "tier-3-static-only"],
+            description: "runtime. Recorded on the run. Default tier-2-container.",
+        },
+        fidelityLevel: {
+            type: "integer",
+            enum: [1, 2, 3, 4],
+            description: "runtime. 1 stub · 2 real+disposable DB · 3 real+redacted · 4 real staging. Default 2.",
+        },
+        evidencePath: {
+            type: "string",
+            description: `runtime. Evidence database path. Default ${DEFAULT_EVIDENCE_RELATIVE_PATH}.`,
+        },
+        resourceLimits: {
+            type: "object",
+            description: "runtime. OS caps on a spawned service; not applied to attach. Unset = unconstrained.",
+            properties: {
+                maxMemoryBytes: { type: "integer", description: "Memory cap, bytes." },
+                maxCpuSeconds: { type: "integer", description: "CPU time cap, seconds." },
+                maxProcesses: { type: "integer", description: "Process count cap." },
+            },
+            additionalProperties: false,
+        },
+        filesystemPolicy: {
+            type: "object",
+            description: "runtime. Confines a service to cwd + these roots; refuses if unenforceable.",
+            properties: {
+                allowedRoots: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Extra read-write paths, beyond the service's cwd.",
+                },
+            },
+            required: ["allowedRoots"],
+            additionalProperties: false,
+        },
+        networkPolicy: {
+            type: "object",
+            description: "runtime. Only full denial is enforced; other shapes refuse. Default unconstrained.",
+            properties: {
+                mode: { type: "string", enum: ["allow", "deny"] },
+                hosts: { type: "array", items: { type: "string" } },
+            },
+            required: ["mode", "hosts"],
+            additionalProperties: false,
+        },
+        sandboxBackend: {
+            type: "string",
+            enum: ["bwrap", "container"],
+            description: "runtime. Enforces filesystem/network policy. Default bwrap (Linux); container elsewhere.",
+        },
+        journey: {
+            type: "object",
+            description: "runtime. Drive a browser in this run's window. Give scenario or startUrl, not both.",
+            properties: {
+                service: { type: "string", description: "Attributed service. Optional." },
+                scenario: {
+                    type: "string",
+                    description: "Saved scenario under descry/scenarios/ to replay.",
+                },
+                startUrl: { type: "string", description: "Navigate here, no steps. Exclusive with scenario." },
+                recordVideo: { type: "boolean", description: "Off by default; returned as a video artifact." },
+                headless: { type: "boolean", description: "Default true." },
+                settleForMs: {
+                    type: "integer",
+                    description: "Page lifetime after last step, for late activity. Default 1000.",
+                },
+            },
+            additionalProperties: false,
+        },
+        database: {
+            type: "object",
+            description: "runtime. Tails Postgres logs into evidence; Node gets sqlite automatically. Omit for none.",
+            properties: {
+                statementLog: {
+                    type: "object",
+                    description: "Reads existing Postgres logging; never turns it on.",
+                    properties: {
+                        kind: { type: "string", enum: ["file", "dockerContainer"] },
+                        path: { type: "string", description: "file: log path." },
+                        container: { type: "string", description: "dockerContainer: container to tail." },
+                    },
+                    required: ["kind"],
+                    additionalProperties: false,
+                },
+                service: { type: "string", description: "Attributed service. Optional." },
+            },
+            required: ["statementLog"],
+            additionalProperties: false,
+        },
+        // --- tests only ---
+        command: {
+            type: "string",
+            description: "tests, REQUIRED. Test command, as typed in a terminal. Unrecognised is refused.",
+        },
+        cwd: {
+            type: "string",
+            description: "tests. Where to run the command. Default: repo root.",
+        },
+        // --- shared ---
+        confirmToken: {
+            type: "string",
+            description: "Arguments frozen when the token was minted; a conflicting one is discarded and disclosed.",
+        },
+    },
+    required: ["verb"],
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const verb = selectVerb(args, "verb", VERB_SPECS, SHARED_PROPS);
+    return verb === "runtime" ? runRuntime(args, ctx) : runTests(args, ctx);
+}
+/** One `describeAction` for two verbs — the requirement this merge cannot get wrong (UAT phase 5
+ *  F12: `browser_start_session` once issued a consent sentence for the wrong verb). `selectVerb`
+ *  decides which verb the call names before either absorbed `describeAction` sees it, so each one
+ *  only ever describes the run it was actually asked to describe. */
+function describeAction(args, ctx) {
+    const verb = selectVerb(args, "verb", VERB_SPECS, SHARED_PROPS);
+    return verb === "runtime" ? describeRuntimeAction(args, ctx) : describeTestsAction(args);
+}
+export const observeTool = {
+    name: "observe",
+    class: "action",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Observe a running application or a test run",
+    description: "Gather runtime evidence, chosen by verb. runtime: boot or attach to services and record what " +
+        "they do. tests: run the test suite and record what ran. Gated: first call returns a " +
+        "confirmToken; second call with it runs. runtime needs an app you can already run. Slow; acts " +
+        "on a real process.",
+    inputSchema: SCHEMA,
+    run,
+    describeAction,
+};
+//# sourceMappingURL=observe.js.map

package/dist/tools/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/tools/observe.ts"],"names":[],"mappings":"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"}

package/dist/tools/pr-analysis.d.ts

@@ -0,0 +1,189 @@
+/**
+ * `pr-analysis` — "what should I test before I open this PR?"
+ *
+ * The blast radius of a diff, intersected with the tests that cover it. The
+ * useful half of the answer is the second list: **what is affected and has no
+ * covering test.** A green suite proves nothing about that set, and it is the
+ * only part of a PR review that a test run cannot supply.
+ *
+ * ## `base...head`, three dots
+ *
+ * `changedFiles` diffs against the merge base rather than the two tips. On a
+ * branch a week behind `main`, two dots would fold every change made on `main`
+ * since the branch point into "this PR", and the blast radius would belong to
+ * somebody else's work. This is stated here as well as at the git call because
+ * it is the kind of thing that gets "simplified" later.
+ *
+ * ## Absence of a test is not evidence of absence
+ *
+ * `TESTS` edges come from adapters, and every adapter's recall is below 100% by
+ * design — precision over recall, when in doubt omit the edge. So "no covering
+ * test" means "no test that this graph can link", and the difference is
+ * disclosed. Reporting the untested list without it would turn a measured recall
+ * gap into a confident accusation.
+ *
+ * ## One node map, three id lists
+ *
+ * `affected`, `untested` and `tests` overlap heavily by construction — an
+ * affected node with no covering test is in two of them — and each used to
+ * carry the whole node inline, so the same fields were serialized up to three
+ * times in one reply. `indexPrAnalysisNodes` collapses that: the lists name
+ * ids, `nodes` holds each node once. Tool version 2.0.0 for it.
+ */
+import { type BriefNode, type ToolDefinition } from "./kit.ts";
+/**
+ * A node in the change's blast radius, named by id into `nodes`.
+ *
+ * It used to carry the whole node inline, and so did `untested` and `tests` —
+ * three lists over one heavily-overlapping population, every member
+ * serialized up to three times. An affected node with no covering test is in
+ * two of them by construction, which is the normal case rather than the
+ * unusual one, so the duplication scaled with exactly the answer a caller
+ * most wants. One map, three id lists.
+ */
+export interface AffectedRef {
+    readonly id: string;
+    readonly score: number;
+    readonly depth: number;
+    /** 1-based position in this answer, highest score first. */
+    readonly rank: number;
+    /**
+     * `top` / `notable` / `rest` by rank, never by an absolute score threshold.
+     * This score is `weightedBfs`'s confidence decay — `changeRisk` passes only a
+     * budget, so it takes the default `weightFor` — and §12.7's tiers were
+     * calibrated against `scoping/`'s designed weights instead. See
+     * `prominence.ts`'s header for why reusing them here would be a calibrated
+     * label on an uncalibrated number.
+     */
+    readonly prominence: "top" | "notable" | "rest";
+}
+/**
+ * The three lists and the one node map they name into.
+ *
+ * `nodes` holds each node once, whichever lists mention it. A caller reads a
+ * list, then looks each id up — never the reverse, and never by scanning.
+ */
+export interface PrAnalysisLists {
+    readonly nodes: Readonly<Record<string, BriefNode>>;
+    readonly affected: readonly AffectedRef[];
+    readonly untested: readonly string[];
+    readonly tests: readonly string[];
+}
+/** What `briefNode` accepts — the graph-node shape these three lists arrive as. */
+interface IndexableNode {
+    readonly id: string;
+    readonly type: string;
+    readonly name: string;
+    readonly file: string | null;
+    readonly range: {
+        readonly startLine: number;
+        readonly endLine: number;
+    } | null;
+    readonly language: string | null;
+    readonly resolution: number;
+}
+/**
+ * Collapse three overlapping node lists into one map plus three id lists.
+ *
+ * Order within each list is preserved exactly — it is the ranking the query
+ * layer produced, and re-sorting it here would silently change which nodes a
+ * caller's own `limit` keeps.
+ */
+export declare function indexPrAnalysisNodes(affected: readonly {
+    readonly node: IndexableNode;
+    readonly score: number;
+    readonly depth: number;
+}[], untested: readonly IndexableNode[], tests: readonly IndexableNode[]): PrAnalysisLists;
+/** Shared by every branch: what was diffed, and what came out of git. */
+export interface PrAnalysisRange {
+    /**
+     * Which change set this answer is about — declared by the caller.
+     *
+     * `range` is `base...head`. `working-tree` is the change as it stands,
+     * uncommitted. Stated because the two answer different questions and a reply
+     * that did not say which one it answered would be readable as either — which
+     * is precisely how a composite came to describe 25 committed files under a
+     * headline about the 2 uncommitted ones passed to it.
+     */
+    readonly mode: "range" | "working-tree";
+    /** Null in working-tree mode: there is no second ref to compare against. */
+    readonly base: string | null;
+    readonly head: string | null;
+    /** Present in working-tree mode only. */
+    readonly workingTree?: {
+        readonly scope: "unstaged" | "staged" | "all";
+        readonly includeUntracked: boolean;
+    };
+    /** Paths in `base...head` — three dots, so somebody else's work on base is not folded in. */
+    readonly files: readonly string[];
+}
+/**
+ * git rejected the range, so nothing downstream ran.
+ *
+ * The narrowest of the four shapes, and the tell is what is absent: no
+ * `missing`, because no path was ever looked up. Narrow on `!("affected" in data)`.
+ */
+export type PrAnalysisGitFailure = PrAnalysisRange;
+/**
+ * The diff is empty. A real answer: there is nothing to assess.
+ *
+ * The three lists are present and empty on purpose — the absence here **is**
+ * a fact about the change. No `missing`, because there was nothing to resolve.
+ */
+export interface PrAnalysisEmptyDiff extends PrAnalysisRange, PrAnalysisLists {
+}
+/**
+ * The diff resolved to no graph node at all, so no blast radius was computed.
+ *
+ * Distinguished from `PrAnalysisEmptyDiff` by `missing`, which names every
+ * path the graph has never heard of. The empty lists here mean *nothing was
+ * examined* rather than *nothing is affected*.
+ */
+export interface PrAnalysisUnresolved extends PrAnalysisEmptyDiff {
+    readonly missing: readonly string[];
+}
+/**
+ * The full answer.
+ *
+ * `untested` is the half a test run cannot supply, and it means *no test is
+ * linked to the node in this graph* — adapters omit an edge they cannot prove,
+ * so a genuinely covered symbol can appear here. A gap to check, never a
+ * proven hole. Narrow on `"changedSymbols" in data`.
+ */
+export interface PrAnalysisReport extends PrAnalysisRange, PrAnalysisLists {
+    readonly missing: readonly string[];
+    /**
+     * Nodes whose declared range actually intersects an added line in the diff
+     * (F5, UAT Phase 5) — the honest reading of "changed symbol". Previously
+     * this field held `symbolsInChangedFiles` under this name: every node whose
+     * *file* was touched, whether or not the diff's hunks came near it — a
+     * `useMemo` edit measured as "43 changed symbols" for a two-hunk change,
+     * which then over-seeded blast radius from every symbol in every touched
+     * file. A node with no known range (a git-history-only symbol, or one in a
+     * file whose patch was withheld by the diff's own size budget) cannot be
+     * proven to intersect anything and is never counted here — rule 2: an
+     * unprovable membership is omitted from the strong claim, not assumed into
+     * it. A wholly deleted file's symbols are counted here as 0 for the same
+     * reason (a deletion has no added lines to intersect), never as a false "no
+     * symbols changed" — they remain in `symbolsInChangedFiles` and still seed
+     * the blast radius below.
+     */
+    readonly changedSymbols: number;
+    /**
+     * Every node declared in a touched file, regardless of which lines moved —
+     * what `changedSymbols` used to be called. Genuinely useful for "what else
+     * lives here", a different question from "what changed", and this is what
+     * blast radius still seeds from: a line-precise seed set would silently
+     * lose a deleted file's symbols (a deletion has no added lines to
+     * intersect) and any file whose patch was withheld by the diff's size
+     * budget, both real, common cases this tool must not go blind to.
+     */
+    readonly symbolsInChangedFiles: number;
+    readonly affectedTotal: number;
+    readonly untestedTotal: number;
+    readonly testsTotal: number;
+}
+export type PrAnalysisData = PrAnalysisGitFailure | PrAnalysisEmptyDiff | PrAnalysisUnresolved | PrAnalysisReport;
+export declare const prAnalysisTool: ToolDefinition;
+export {};
+//# sourceMappingURL=pr-analysis.d.ts.map

package/dist/tools/pr-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-analysis.d.ts","sourceRoot":"","sources":["../../src/tools/pr-analysis.ts"],"names":[],"mappings":"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"}