@descryy/mcp 0.11.1 → 0.11.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/descry-mcp.js +6 -0
- package/dist/bin/descry-mcp.js.map +1 -1
- package/dist/browser/auth.d.ts +8 -0
- package/dist/browser/auth.d.ts.map +1 -1
- package/dist/browser/auth.js +12 -2
- package/dist/browser/auth.js.map +1 -1
- package/dist/credential-store.d.ts +22 -0
- package/dist/credential-store.d.ts.map +1 -0
- package/dist/credential-store.js +33 -0
- package/dist/credential-store.js.map +1 -0
- package/dist/index.d.ts +6 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -0
- package/dist/index.js.map +1 -1
- package/dist/planner/predict-then-propose.d.ts +34 -1
- package/dist/planner/predict-then-propose.d.ts.map +1 -1
- package/dist/planner/predict-then-propose.js +51 -1
- package/dist/planner/predict-then-propose.js.map +1 -1
- package/dist/planner/propose-journey.d.ts +15 -0
- package/dist/planner/propose-journey.d.ts.map +1 -1
- package/dist/planner/propose-journey.js.map +1 -1
- package/dist/render.d.ts +7 -11
- package/dist/render.d.ts.map +1 -1
- package/dist/render.js +22 -2
- package/dist/render.js.map +1 -1
- package/dist/scenarios/browser-run-plan-projection.d.ts +24 -6
- package/dist/scenarios/browser-run-plan-projection.d.ts.map +1 -1
- package/dist/scenarios/browser-run-plan-projection.js +45 -9
- package/dist/scenarios/browser-run-plan-projection.js.map +1 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +13 -2
- package/dist/server.js.map +1 -1
- package/dist/tools/alias-kit.d.ts +29 -0
- package/dist/tools/alias-kit.d.ts.map +1 -0
- package/dist/tools/alias-kit.js +21 -0
- package/dist/tools/alias-kit.js.map +1 -0
- package/dist/tools/aliases.d.ts +42 -0
- package/dist/tools/aliases.d.ts.map +1 -0
- package/dist/tools/aliases.js +52 -0
- package/dist/tools/aliases.js.map +1 -0
- package/dist/tools/browser-close-session.d.ts +5 -1
- package/dist/tools/browser-close-session.d.ts.map +1 -1
- package/dist/tools/browser-close-session.js +3 -1
- package/dist/tools/browser-close-session.js.map +1 -1
- package/dist/tools/browser-navigate.d.ts +5 -1
- package/dist/tools/browser-navigate.d.ts.map +1 -1
- package/dist/tools/browser-navigate.js +3 -1
- package/dist/tools/browser-navigate.js.map +1 -1
- package/dist/tools/browser-read.d.ts +33 -0
- package/dist/tools/browser-read.d.ts.map +1 -0
- package/dist/tools/browser-read.js +113 -0
- package/dist/tools/browser-read.js.map +1 -0
- package/dist/tools/browser-snapshot.d.ts +5 -2
- package/dist/tools/browser-snapshot.d.ts.map +1 -1
- package/dist/tools/browser-snapshot.js +3 -1
- package/dist/tools/browser-snapshot.js.map +1 -1
- package/dist/tools/browser-start-session.d.ts.map +1 -1
- package/dist/tools/browser-start-session.js +57 -11
- package/dist/tools/browser-start-session.js.map +1 -1
- package/dist/tools/browser-wait-for.d.ts +5 -1
- package/dist/tools/browser-wait-for.d.ts.map +1 -1
- package/dist/tools/browser-wait-for.js +3 -1
- package/dist/tools/browser-wait-for.js.map +1 -1
- package/dist/tools/browser.d.ts +69 -0
- package/dist/tools/browser.d.ts.map +1 -0
- package/dist/tools/browser.js +386 -0
- package/dist/tools/browser.js.map +1 -0
- package/dist/tools/change-scope.d.ts +25 -0
- package/dist/tools/change-scope.d.ts.map +1 -0
- package/dist/tools/change-scope.js +110 -0
- package/dist/tools/change-scope.js.map +1 -0
- package/dist/tools/code-context.d.ts +83 -0
- package/dist/tools/code-context.d.ts.map +1 -0
- package/dist/tools/code-context.js +416 -0
- package/dist/tools/code-context.js.map +1 -0
- package/dist/tools/disclosure.d.ts +75 -0
- package/dist/tools/disclosure.d.ts.map +1 -0
- package/dist/tools/disclosure.js +288 -0
- package/dist/tools/disclosure.js.map +1 -0
- package/dist/tools/draw-conclusion.d.ts +12 -1
- package/dist/tools/draw-conclusion.d.ts.map +1 -1
- package/dist/tools/draw-conclusion.js +11 -2
- package/dist/tools/draw-conclusion.js.map +1 -1
- package/dist/tools/git-context.d.ts +39 -0
- package/dist/tools/git-context.d.ts.map +1 -0
- package/dist/tools/git-context.js +364 -0
- package/dist/tools/git-context.js.map +1 -0
- package/dist/tools/index.d.ts +16 -4
- package/dist/tools/index.d.ts.map +1 -1
- package/dist/tools/index.js +46 -67
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/kit.d.ts +3 -2
- package/dist/tools/kit.d.ts.map +1 -1
- package/dist/tools/kit.js.map +1 -1
- package/dist/tools/merged-browser.d.ts +11 -0
- package/dist/tools/merged-browser.d.ts.map +1 -0
- package/dist/tools/merged-browser.js +20 -0
- package/dist/tools/merged-browser.js.map +1 -0
- package/dist/tools/merged-context.d.ts +11 -0
- package/dist/tools/merged-context.d.ts.map +1 -0
- package/dist/tools/merged-context.js +21 -0
- package/dist/tools/merged-context.js.map +1 -0
- package/dist/tools/merged-observe.d.ts +13 -0
- package/dist/tools/merged-observe.d.ts.map +1 -0
- package/dist/tools/merged-observe.js +21 -0
- package/dist/tools/merged-observe.js.map +1 -0
- package/dist/tools/merged-workspace.d.ts +14 -0
- package/dist/tools/merged-workspace.d.ts.map +1 -0
- package/dist/tools/merged-workspace.js +21 -0
- package/dist/tools/merged-workspace.js.map +1 -0
- package/dist/tools/observe-runtime.d.ts +38 -1
- package/dist/tools/observe-runtime.d.ts.map +1 -1
- package/dist/tools/observe-runtime.js +236 -6
- package/dist/tools/observe-runtime.js.map +1 -1
- package/dist/tools/observe-tests.d.ts +12 -1
- package/dist/tools/observe-tests.d.ts.map +1 -1
- package/dist/tools/observe-tests.js +6 -2
- package/dist/tools/observe-tests.js.map +1 -1
- package/dist/tools/observe.d.ts +28 -0
- package/dist/tools/observe.d.ts.map +1 -0
- package/dist/tools/observe.js +330 -0
- package/dist/tools/observe.js.map +1 -0
- package/dist/tools/prove-reach.d.ts +74 -0
- package/dist/tools/prove-reach.d.ts.map +1 -0
- package/dist/tools/prove-reach.js +286 -0
- package/dist/tools/prove-reach.js.map +1 -0
- package/dist/tools/verb.d.ts +46 -0
- package/dist/tools/verb.d.ts.map +1 -0
- package/dist/tools/verb.js +78 -0
- package/dist/tools/verb.js.map +1 -0
- package/dist/tools/workspace.d.ts +28 -0
- package/dist/tools/workspace.d.ts.map +1 -0
- package/dist/tools/workspace.js +101 -0
- package/dist/tools/workspace.js.map +1 -0
- package/package.json +25 -21
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `browser` — the merged action-class browser tool. §4/§7 step 5 of
|
|
3
|
+
* `documents/plans/mcp-surface-consolidation.md`.
|
|
4
|
+
*
|
|
5
|
+
* Absorbs the eight consent-gated browser verbs — `start_session` `click`
|
|
6
|
+
* `type` `fill` `select` `submit` `save_scenario` `run_scenario` — behind one
|
|
7
|
+
* `verb` argument. The four stateful-read tools (`snapshot`, `navigate`,
|
|
8
|
+
* `wait_for`, `close_session`) are a different class and are not touched
|
|
9
|
+
* here.
|
|
10
|
+
*
|
|
11
|
+
* ## This is the surface merge only
|
|
12
|
+
*
|
|
13
|
+
* §4 names the real design problem: an element ref is issued per snapshot and
|
|
14
|
+
* a stale one refuses rather than resolving elsewhere, so a caller cannot
|
|
15
|
+
* author a multi-step batch up front — step 2's ref does not exist until step
|
|
16
|
+
* 1 has run. The eventual fix is a server-side step loop that takes its own
|
|
17
|
+
* snapshot between steps and resolves targets by role + accessible name, so a
|
|
18
|
+
* ref never leaves the server and an ambiguous target refuses rather than
|
|
19
|
+
* guessing. That is a design change, not a merge, and it is **not** done
|
|
20
|
+
* here. This tool still takes one ref, for one step, per call — exactly
|
|
21
|
+
* today's semantics, including the refusal on a superseded ref — and only
|
|
22
|
+
* changes how the eight verbs are named and dispatched.
|
|
23
|
+
*
|
|
24
|
+
* ## Reuse, not reimplementation
|
|
25
|
+
*
|
|
26
|
+
* Every verb's `run` and `describeAction` is the same function object the
|
|
27
|
+
* standalone tool exported before this file existed — `VERB_TOOLS` below is
|
|
28
|
+
* a dispatch table over those objects, never a rewrite of what they do. The
|
|
29
|
+
* one thing genuinely new is `selectVerb`: with eight verbs' properties
|
|
30
|
+
* unioned into one schema, `additionalProperties: false` can no longer catch
|
|
31
|
+
* `browser({ verb: "click", text: "hi" })` silently ignoring `text` — that is
|
|
32
|
+
* exactly the defect `browser_start_session({ profile })` silently reading
|
|
33
|
+
* `environment` was (UAT phase 5 F12), one level further down. `selectVerb`
|
|
34
|
+
* re-establishes per-verb argument discrimination at runtime; see
|
|
35
|
+
* `verb.ts`'s own header for the full reasoning.
|
|
36
|
+
*
|
|
37
|
+
* ## Consent
|
|
38
|
+
*
|
|
39
|
+
* Only `start_session` mints anything — it is the one call that opens a
|
|
40
|
+
* browser and grants consent for the rest of the session's life
|
|
41
|
+
* (`browser-start-session.ts`, DEC-380). The other seven verbs already
|
|
42
|
+
* declare `describeAction: () => undefined` (nothing left to confirm; a verb
|
|
43
|
+
* cannot mint its own consent), and that is preserved by delegating to each
|
|
44
|
+
* verb's own `describeAction` rather than writing a new one — the one
|
|
45
|
+
* consent sentence this tool produces is `browser_start_session`'s own,
|
|
46
|
+
* unchanged, so it cannot drift from what `start_session` alone still
|
|
47
|
+
* enforces.
|
|
48
|
+
*/
|
|
49
|
+
import type { ToolDefinition } from "./kit.ts";
|
|
50
|
+
import type { BrowserStartSessionData } from "./browser-start-session.ts";
|
|
51
|
+
import type { BrowserClickData } from "./browser-click.ts";
|
|
52
|
+
import type { BrowserTypeData } from "./browser-type.ts";
|
|
53
|
+
import type { BrowserFillData } from "./browser-fill.ts";
|
|
54
|
+
import type { BrowserSelectData } from "./browser-select.ts";
|
|
55
|
+
import type { BrowserSubmitData } from "./browser-submit.ts";
|
|
56
|
+
import type { BrowserSaveScenarioData } from "./browser-save-scenario.ts";
|
|
57
|
+
import type { BrowserRunScenarioData } from "./browser-run-scenario.ts";
|
|
58
|
+
/**
|
|
59
|
+
* What this tool answers with: one verb's shape, never a merged one.
|
|
60
|
+
*
|
|
61
|
+
* The merge cost this its single concrete output type, and `unknown` would have
|
|
62
|
+
* silently retired `output-shapes.test.ts`'s check that a declared shape is tied
|
|
63
|
+
* to the code producing it. A union keeps that tie: a verb added without its
|
|
64
|
+
* shape here stops compiling.
|
|
65
|
+
*/
|
|
66
|
+
export type BrowserData = BrowserStartSessionData | BrowserClickData | BrowserTypeData | BrowserFillData | BrowserSelectData | BrowserSubmitData | BrowserSaveScenarioData | BrowserRunScenarioData;
|
|
67
|
+
export type BrowserVerb = "start_session" | "click" | "type" | "fill" | "select" | "submit" | "save_scenario" | "run_scenario";
|
|
68
|
+
export declare const browserTool: ToolDefinition;
|
|
69
|
+
//# sourceMappingURL=browser.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/tools/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAYH,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB,uBAAuB,GACvB,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,iBAAiB,GACjB,iBAAiB,GACjB,uBAAuB,GACvB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,eAAe,GACf,cAAc,CAAC;AA0VnB,eAAO,MAAM,WAAW,EAAE,cAoBzB,CAAC"}
|
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `browser` — the merged action-class browser tool. §4/§7 step 5 of
|
|
3
|
+
* `documents/plans/mcp-surface-consolidation.md`.
|
|
4
|
+
*
|
|
5
|
+
* Absorbs the eight consent-gated browser verbs — `start_session` `click`
|
|
6
|
+
* `type` `fill` `select` `submit` `save_scenario` `run_scenario` — behind one
|
|
7
|
+
* `verb` argument. The four stateful-read tools (`snapshot`, `navigate`,
|
|
8
|
+
* `wait_for`, `close_session`) are a different class and are not touched
|
|
9
|
+
* here.
|
|
10
|
+
*
|
|
11
|
+
* ## This is the surface merge only
|
|
12
|
+
*
|
|
13
|
+
* §4 names the real design problem: an element ref is issued per snapshot and
|
|
14
|
+
* a stale one refuses rather than resolving elsewhere, so a caller cannot
|
|
15
|
+
* author a multi-step batch up front — step 2's ref does not exist until step
|
|
16
|
+
* 1 has run. The eventual fix is a server-side step loop that takes its own
|
|
17
|
+
* snapshot between steps and resolves targets by role + accessible name, so a
|
|
18
|
+
* ref never leaves the server and an ambiguous target refuses rather than
|
|
19
|
+
* guessing. That is a design change, not a merge, and it is **not** done
|
|
20
|
+
* here. This tool still takes one ref, for one step, per call — exactly
|
|
21
|
+
* today's semantics, including the refusal on a superseded ref — and only
|
|
22
|
+
* changes how the eight verbs are named and dispatched.
|
|
23
|
+
*
|
|
24
|
+
* ## Reuse, not reimplementation
|
|
25
|
+
*
|
|
26
|
+
* Every verb's `run` and `describeAction` is the same function object the
|
|
27
|
+
* standalone tool exported before this file existed — `VERB_TOOLS` below is
|
|
28
|
+
* a dispatch table over those objects, never a rewrite of what they do. The
|
|
29
|
+
* one thing genuinely new is `selectVerb`: with eight verbs' properties
|
|
30
|
+
* unioned into one schema, `additionalProperties: false` can no longer catch
|
|
31
|
+
* `browser({ verb: "click", text: "hi" })` silently ignoring `text` — that is
|
|
32
|
+
* exactly the defect `browser_start_session({ profile })` silently reading
|
|
33
|
+
* `environment` was (UAT phase 5 F12), one level further down. `selectVerb`
|
|
34
|
+
* re-establishes per-verb argument discrimination at runtime; see
|
|
35
|
+
* `verb.ts`'s own header for the full reasoning.
|
|
36
|
+
*
|
|
37
|
+
* ## Consent
|
|
38
|
+
*
|
|
39
|
+
* Only `start_session` mints anything — it is the one call that opens a
|
|
40
|
+
* browser and grants consent for the rest of the session's life
|
|
41
|
+
* (`browser-start-session.ts`, DEC-380). The other seven verbs already
|
|
42
|
+
* declare `describeAction: () => undefined` (nothing left to confirm; a verb
|
|
43
|
+
* cannot mint its own consent), and that is preserved by delegating to each
|
|
44
|
+
* verb's own `describeAction` rather than writing a new one — the one
|
|
45
|
+
* consent sentence this tool produces is `browser_start_session`'s own,
|
|
46
|
+
* unchanged, so it cannot drift from what `start_session` alone still
|
|
47
|
+
* enforces.
|
|
48
|
+
*/
|
|
49
|
+
import { browserClickTool } from "./browser-click.js";
|
|
50
|
+
import { browserTypeTool } from "./browser-type.js";
|
|
51
|
+
import { browserFillTool } from "./browser-fill.js";
|
|
52
|
+
import { browserSelectTool } from "./browser-select.js";
|
|
53
|
+
import { browserSubmitTool } from "./browser-submit.js";
|
|
54
|
+
import { browserStartSessionTool } from "./browser-start-session.js";
|
|
55
|
+
import { browserSaveScenarioTool } from "./browser-save-scenario.js";
|
|
56
|
+
import { browserRunScenarioTool } from "./browser-run-scenario.js";
|
|
57
|
+
import { selectVerb } from "./verb.js";
|
|
58
|
+
const VERB_TOOLS = {
|
|
59
|
+
start_session: browserStartSessionTool,
|
|
60
|
+
click: browserClickTool,
|
|
61
|
+
type: browserTypeTool,
|
|
62
|
+
fill: browserFillTool,
|
|
63
|
+
select: browserSelectTool,
|
|
64
|
+
submit: browserSubmitTool,
|
|
65
|
+
save_scenario: browserSaveScenarioTool,
|
|
66
|
+
run_scenario: browserRunScenarioTool,
|
|
67
|
+
};
|
|
68
|
+
/** Every verb's own exclusive properties, beyond `verb` and the shared ones below — the table
|
|
69
|
+
* `selectVerb` needs to say "that belongs to a different verb" instead of just "unknown". Kept
|
|
70
|
+
* as data, next to `VERB_TOOLS`, so the two cannot silently drift apart: a verb added to one
|
|
71
|
+
* and not the other fails loudly (`browser-verb-dispatch.test.ts` asserts the two agree). */
|
|
72
|
+
const SPECS = [
|
|
73
|
+
{
|
|
74
|
+
verb: "start_session",
|
|
75
|
+
accepts: [
|
|
76
|
+
"targetUrl",
|
|
77
|
+
"headless",
|
|
78
|
+
"stackParser",
|
|
79
|
+
"documentRoot",
|
|
80
|
+
"environment",
|
|
81
|
+
"storageState",
|
|
82
|
+
"storageStatePath",
|
|
83
|
+
"storageStateCredential",
|
|
84
|
+
"extraHttpHeaders",
|
|
85
|
+
"saveStorageStateTo",
|
|
86
|
+
],
|
|
87
|
+
},
|
|
88
|
+
{ verb: "click", accepts: ["sessionId", "ref"] },
|
|
89
|
+
{ verb: "type", accepts: ["sessionId", "ref", "text"] },
|
|
90
|
+
{ verb: "fill", accepts: ["sessionId", "ref", "text"] },
|
|
91
|
+
{ verb: "select", accepts: ["sessionId", "ref", "value"] },
|
|
92
|
+
{ verb: "submit", accepts: ["sessionId", "ref"] },
|
|
93
|
+
{ verb: "save_scenario", accepts: ["sessionId", "name", "description", "targetUrl", "steps", "assertions"] },
|
|
94
|
+
{ verb: "run_scenario", accepts: ["sessionId", "name"] },
|
|
95
|
+
];
|
|
96
|
+
/** Accepted by every verb, `start_session` included — the handshake reads it for any
|
|
97
|
+
* action-class tool whether or not that verb ever mints. */
|
|
98
|
+
const SHARED = ["confirmToken"];
|
|
99
|
+
function resolveVerb(args) {
|
|
100
|
+
return selectVerb(args, "verb", SPECS, SHARED);
|
|
101
|
+
}
|
|
102
|
+
async function run(args, ctx) {
|
|
103
|
+
const verb = resolveVerb(args);
|
|
104
|
+
// `ToolDefinition` erases its answer's type parameter — it has to, the
|
|
105
|
+
// registry is one array of many shapes — so the delegated call comes back as
|
|
106
|
+
// an erased answer type. The verb table is what makes the union true: every
|
|
107
|
+
// entry's own `run` is declared against one of BrowserData's members, and a verb
|
|
108
|
+
// added without its shape stops compiling at the union. The assertion
|
|
109
|
+
// re-applies what the table already guarantees rather than asserting
|
|
110
|
+
// something unchecked.
|
|
111
|
+
return (await VERB_TOOLS[verb].run(args, ctx));
|
|
112
|
+
}
|
|
113
|
+
/** Delegates to the resolved verb's own `describeAction` — never writes a new consent sentence.
|
|
114
|
+
* Only `start_session`'s returns a string; every other verb's is `() => undefined` today, and
|
|
115
|
+
* reading that through the same dispatch table means this tool cannot describe the wrong verb
|
|
116
|
+
* without the underlying tool describing it wrong too, which is exactly the bar §7's "one
|
|
117
|
+
* describeAction, tested against all eight verbs" sets. */
|
|
118
|
+
async function describeAction(args, ctx) {
|
|
119
|
+
const verb = resolveVerb(args);
|
|
120
|
+
return VERB_TOOLS[verb].describeAction?.(args, ctx);
|
|
121
|
+
}
|
|
122
|
+
/** Only `start_session`'s arguments can carry a credential (`storageState`, `extraHttpHeaders`).
|
|
123
|
+
* Dispatched on the raw `verb` value rather than through `selectVerb`/`resolveVerb`: this runs
|
|
124
|
+
* over whatever was actually recorded, including a call that never validated — a malformed or
|
|
125
|
+
* unconfirmed call is exactly the one a redactor must not throw on. */
|
|
126
|
+
function redactArgs(args) {
|
|
127
|
+
const verb = args["verb"];
|
|
128
|
+
const tool = typeof verb === "string" ? VERB_TOOLS[verb] : undefined;
|
|
129
|
+
return tool?.redactArgs?.(args) ?? args;
|
|
130
|
+
}
|
|
131
|
+
const REF_NOTE = "An element ref from a browser_snapshot reply. Refs are issued per snapshot and invalidated by " +
|
|
132
|
+
"navigation — a stale ref is refused rather than resolved against whatever now matches it, so " +
|
|
133
|
+
"take a fresh snapshot after the page changes.";
|
|
134
|
+
const TARGET_SCHEMA = {
|
|
135
|
+
type: "object",
|
|
136
|
+
description: "The element, named by role, name and selector together — copy all three from a " +
|
|
137
|
+
"browser_snapshot element. No ref field: a ref is scoped to the snapshot that issued it and a " +
|
|
138
|
+
"replay is always a later session. No fallback between the three at replay either — a " +
|
|
139
|
+
"selector match with a disagreeing role or name stops the replay rather than substituting.",
|
|
140
|
+
properties: {
|
|
141
|
+
role: { type: "string", description: "The element's ARIA role, as browser_snapshot reported it." },
|
|
142
|
+
name: { type: "string", description: "The element's accessible name, as browser_snapshot reported it." },
|
|
143
|
+
selector: {
|
|
144
|
+
type: ["string", "null"],
|
|
145
|
+
description: "The selector browser_snapshot reported, or null when the element has no id, test attribute " +
|
|
146
|
+
"or name. A null selector cannot be saved — add a data-testid and re-explore.",
|
|
147
|
+
},
|
|
148
|
+
},
|
|
149
|
+
required: ["role", "name", "selector"],
|
|
150
|
+
additionalProperties: false,
|
|
151
|
+
};
|
|
152
|
+
const SCHEMA = {
|
|
153
|
+
type: "object",
|
|
154
|
+
properties: {
|
|
155
|
+
verb: {
|
|
156
|
+
type: "string",
|
|
157
|
+
enum: ["start_session", "click", "type", "fill", "select", "submit", "save_scenario", "run_scenario"],
|
|
158
|
+
description: "REQUIRED. Which action to perform. Each verb accepts only its own arguments, listed in the " +
|
|
159
|
+
"property descriptions below by verb name — a property belonging to a different verb is " +
|
|
160
|
+
"refused, naming which verb it belongs to.",
|
|
161
|
+
},
|
|
162
|
+
// --- start_session only ---
|
|
163
|
+
targetUrl: {
|
|
164
|
+
type: "string",
|
|
165
|
+
description: "start_session (REQUIRED): the URL to open, including scheme and port, e.g. " +
|
|
166
|
+
'"http://localhost:3000/invoices". Also what consent is granted for — the session may be ' +
|
|
167
|
+
"driven anywhere on this URL's origin for its life, and leaving that origin refuses rather " +
|
|
168
|
+
"than asking again. save_scenario: where a replay should start; defaults to the session's " +
|
|
169
|
+
"current URL and must stay within its consented origin.",
|
|
170
|
+
},
|
|
171
|
+
headless: {
|
|
172
|
+
type: "boolean",
|
|
173
|
+
description: "start_session: run without a visible window. Defaults to true; pass false to watch it happen.",
|
|
174
|
+
},
|
|
175
|
+
stackParser: {
|
|
176
|
+
type: "object",
|
|
177
|
+
description: "start_session: the module that can parse this application's stack traces. Without one, " +
|
|
178
|
+
"requests are still observed and named, but no frontend→backend caller edge is written. Name " +
|
|
179
|
+
'it "@descryy/runtime-adapter-<language>" (one such package per frontend language — never ' +
|
|
180
|
+
'guess) exporting a single "create<Name>StackTraceParser" factory. @descryy/runtime-browser ' +
|
|
181
|
+
"is never the right answer here despite the name — it exports no stack-trace parser at all. " +
|
|
182
|
+
'"export" is needed only when a module exports more than one factory.',
|
|
183
|
+
properties: {
|
|
184
|
+
module: { type: "string", description: "Module specifier to import — a runtime adapter package for the frontend's language." },
|
|
185
|
+
export: { type: "string", description: "Named export to call. Defaults to the module's single create*StackTraceParser factory." },
|
|
186
|
+
},
|
|
187
|
+
required: ["module"],
|
|
188
|
+
additionalProperties: false,
|
|
189
|
+
},
|
|
190
|
+
documentRoot: {
|
|
191
|
+
type: "string",
|
|
192
|
+
description: "start_session: the directory the target URL's origin serves files from, if not the " +
|
|
193
|
+
'repository root — e.g. "public/". Getting this wrong degrades the call-site stack to ' +
|
|
194
|
+
"nothing while looking like a clean run with no edges. Defaults to the repository root.",
|
|
195
|
+
},
|
|
196
|
+
environment: {
|
|
197
|
+
type: "object",
|
|
198
|
+
description: 'start_session: the environment profile this session runs against. "readOnly" refuses click, ' +
|
|
199
|
+
"type, fill, select and submit for the whole session while still permitting navigate and " +
|
|
200
|
+
"snapshot. The same profile shape observe_runtime takes (DEC-270) — a browser run and a " +
|
|
201
|
+
"runtime run must not disagree about one environment. Omit it and the session's own consent " +
|
|
202
|
+
"is the only authorization.",
|
|
203
|
+
properties: {
|
|
204
|
+
name: { type: "string", description: "The profile's name, free-form. Named back in any refusal it causes." },
|
|
205
|
+
safetyLevel: {
|
|
206
|
+
type: "string",
|
|
207
|
+
enum: ["readOnly", "write", "destructiveWithApproval"],
|
|
208
|
+
description: '"readOnly" refuses every mutating verb whatever the profile is called.',
|
|
209
|
+
},
|
|
210
|
+
},
|
|
211
|
+
required: ["name", "safetyLevel"],
|
|
212
|
+
additionalProperties: true,
|
|
213
|
+
},
|
|
214
|
+
storageState: {
|
|
215
|
+
type: "object",
|
|
216
|
+
description: "start_session: an already-authenticated session to seed before the first navigation. " +
|
|
217
|
+
"Without it, click/type/fill can drive a login form but cannot reach a screen requiring an " +
|
|
218
|
+
"existing session. Scoped to targetUrl's own origin by construction.",
|
|
219
|
+
properties: {
|
|
220
|
+
cookies: {
|
|
221
|
+
type: "array",
|
|
222
|
+
description: "Cookies to set before navigating, scoped to targetUrl's own origin.",
|
|
223
|
+
items: {
|
|
224
|
+
type: "object",
|
|
225
|
+
properties: {
|
|
226
|
+
name: { type: "string" },
|
|
227
|
+
value: { type: "string" },
|
|
228
|
+
path: { type: "string", description: 'Defaults to "/".' },
|
|
229
|
+
httpOnly: { type: "boolean" },
|
|
230
|
+
secure: { type: "boolean" },
|
|
231
|
+
sameSite: { type: "string", enum: ["Strict", "Lax", "None"] },
|
|
232
|
+
},
|
|
233
|
+
required: ["name", "value"],
|
|
234
|
+
additionalProperties: false,
|
|
235
|
+
},
|
|
236
|
+
},
|
|
237
|
+
localStorage: {
|
|
238
|
+
type: "object",
|
|
239
|
+
description: "localStorage entries to set for targetUrl's own origin before navigating, as string values.",
|
|
240
|
+
additionalProperties: { type: "string" },
|
|
241
|
+
},
|
|
242
|
+
},
|
|
243
|
+
additionalProperties: false,
|
|
244
|
+
},
|
|
245
|
+
storageStatePath: {
|
|
246
|
+
type: "string",
|
|
247
|
+
description: "start_session: a FILE holding a saved browser storage state, instead of naming cookies " +
|
|
248
|
+
"inline. Absolute, or relative to the repository root. Anything in the file outside this " +
|
|
249
|
+
"session's consented origin is refused by name.",
|
|
250
|
+
},
|
|
251
|
+
storageStateCredential: {
|
|
252
|
+
type: "string",
|
|
253
|
+
description: "start_session: the NAME of a stored credential holding a saved storage state (the JSON " +
|
|
254
|
+
"storageStatePath reads), instead of a file on disk — set with `descry credential set <name>`, " +
|
|
255
|
+
"reading the JSON from stdin. Refused by name when no credential store is configured, nothing is " +
|
|
256
|
+
"stored under the name, or the value is not a storage state this origin can use — never a silent " +
|
|
257
|
+
"logged-out session. Give at most one of storageState, storageStatePath and storageStateCredential.",
|
|
258
|
+
},
|
|
259
|
+
extraHttpHeaders: {
|
|
260
|
+
type: "object",
|
|
261
|
+
description: "start_session: headers added to every request to the consented origin only — typically an " +
|
|
262
|
+
"Authorization bearer token. Deliberately never sent to any other host a page loads.",
|
|
263
|
+
additionalProperties: { type: "string" },
|
|
264
|
+
},
|
|
265
|
+
saveStorageStateTo: {
|
|
266
|
+
type: "string",
|
|
267
|
+
description: "start_session: write this session's cookies and stored data here when it closes, so a login " +
|
|
268
|
+
"done once can seed later sessions via storageStatePath. Must be an absolute path OUTSIDE the " +
|
|
269
|
+
"repository — this is a live credential.",
|
|
270
|
+
},
|
|
271
|
+
// --- click / type / fill / select / submit / save_scenario / run_scenario ---
|
|
272
|
+
sessionId: {
|
|
273
|
+
type: "string",
|
|
274
|
+
description: "REQUIRED for every verb except start_session. The id returned by a start_session call.",
|
|
275
|
+
},
|
|
276
|
+
ref: {
|
|
277
|
+
type: "string",
|
|
278
|
+
description: `REQUIRED for click, type, fill, select and submit. ${REF_NOTE}`,
|
|
279
|
+
},
|
|
280
|
+
text: {
|
|
281
|
+
type: "string",
|
|
282
|
+
description: "REQUIRED for type and fill. type: entered as real keystrokes and APPENDS to the field's " +
|
|
283
|
+
"current contents — every keydown/keypress/keyup a person typing would produce, needed for " +
|
|
284
|
+
"autocomplete, per-character validation or a debounced search. fill: sets the value directly, " +
|
|
285
|
+
"REPLACING the contents, and fires no key events at all, so anything reacting to typing will " +
|
|
286
|
+
"not run. Use type when the field reacts to typing; fill otherwise.",
|
|
287
|
+
},
|
|
288
|
+
value: {
|
|
289
|
+
type: "string",
|
|
290
|
+
description: "REQUIRED for select. The option to choose on a chooser — either the stored value or the " +
|
|
291
|
+
"displayed label, matched exactly; no near match is substituted. An unmatched value is " +
|
|
292
|
+
"refused with the full list of options actually offered.",
|
|
293
|
+
},
|
|
294
|
+
// --- save_scenario / run_scenario ---
|
|
295
|
+
name: {
|
|
296
|
+
type: "string",
|
|
297
|
+
description: "REQUIRED for save_scenario and run_scenario. save_scenario: what to call it — becomes " +
|
|
298
|
+
"descry/scenarios/<name>.scenario.json, a committed, reviewable file. run_scenario: which " +
|
|
299
|
+
"saved scenario to replay, by that same name.",
|
|
300
|
+
},
|
|
301
|
+
// --- save_scenario only ---
|
|
302
|
+
description: { type: "string", description: "save_scenario: free text for whoever reads the file later. Optional." },
|
|
303
|
+
steps: {
|
|
304
|
+
type: "array",
|
|
305
|
+
description: "save_scenario (REQUIRED, at least one): the sequence to replay, in order. Every step is " +
|
|
306
|
+
"re-resolved against a fresh page at replay time, except one this session's own history shows " +
|
|
307
|
+
"it actually performed, which is accepted on that record alone.",
|
|
308
|
+
items: {
|
|
309
|
+
type: "object",
|
|
310
|
+
properties: {
|
|
311
|
+
action: {
|
|
312
|
+
type: "string",
|
|
313
|
+
enum: ["navigate", "click", "type", "fill"],
|
|
314
|
+
description: "navigate acts on the page; click, type and fill act on an element and need a target.",
|
|
315
|
+
},
|
|
316
|
+
target: TARGET_SCHEMA,
|
|
317
|
+
url: { type: "string", description: "Where to go. navigate steps only." },
|
|
318
|
+
text: {
|
|
319
|
+
type: "string",
|
|
320
|
+
description: "What to enter. type and fill steps only — type fires real keystrokes and appends, fill " +
|
|
321
|
+
"sets the value directly and fires none.",
|
|
322
|
+
},
|
|
323
|
+
},
|
|
324
|
+
required: ["action"],
|
|
325
|
+
additionalProperties: false,
|
|
326
|
+
},
|
|
327
|
+
},
|
|
328
|
+
assertions: {
|
|
329
|
+
type: "array",
|
|
330
|
+
description: "save_scenario (REQUIRED, may be empty). What this scenario claims about the application. " +
|
|
331
|
+
"Absent is refused — empty means an honest exploration, which replays as unverified, never as " +
|
|
332
|
+
"passed.",
|
|
333
|
+
items: {
|
|
334
|
+
type: "object",
|
|
335
|
+
properties: {
|
|
336
|
+
kind: {
|
|
337
|
+
type: "string",
|
|
338
|
+
enum: ["elementVisible", "textEquals", "urlEquals", "noConsoleErrors", "noFailedRequests"],
|
|
339
|
+
description: "elementVisible/textEquals need a target; textEquals/urlEquals compare against expected. " +
|
|
340
|
+
"noConsoleErrors/noFailedRequests read gathered evidence — an observed error the author " +
|
|
341
|
+
"never asserted against never blocks; one asserted against and seen does.",
|
|
342
|
+
},
|
|
343
|
+
afterStep: {
|
|
344
|
+
type: "integer",
|
|
345
|
+
description: "Which step this runs after, by index. Omit for end-of-scenario. An index past the last step is refused.",
|
|
346
|
+
},
|
|
347
|
+
target: TARGET_SCHEMA,
|
|
348
|
+
expected: { type: "string", description: "The value to compare against, for the kinds that compare one." },
|
|
349
|
+
},
|
|
350
|
+
required: ["kind"],
|
|
351
|
+
additionalProperties: false,
|
|
352
|
+
},
|
|
353
|
+
},
|
|
354
|
+
confirmToken: {
|
|
355
|
+
type: "string",
|
|
356
|
+
description: "The token from a previous call to this verb. The arguments used are the ones frozen when the token was minted, never those on the confirming call. Only start_session normally needs a second, " +
|
|
357
|
+
"confirming call — the other seven verbs run directly because consent was already granted at " +
|
|
358
|
+
"start_session and confirmToken is declared only because the handshake reads it for every " +
|
|
359
|
+
"action-class tool. On a confirming call, the arguments frozen at mint time run, never " +
|
|
360
|
+
"whatever this call supplies instead; a changed value is discarded and the reply discloses it.",
|
|
361
|
+
},
|
|
362
|
+
},
|
|
363
|
+
required: ["verb"],
|
|
364
|
+
additionalProperties: false,
|
|
365
|
+
};
|
|
366
|
+
export const browserTool = {
|
|
367
|
+
name: "browser",
|
|
368
|
+
title: "Drive a real browser",
|
|
369
|
+
description: "Open a real browser session and drive it — one verb per call, chosen with the required `verb` " +
|
|
370
|
+
"argument: start_session opens it and grants consent for the rest of the session (the only verb " +
|
|
371
|
+
"that needs confirming); click, type, fill, select and submit act on an element named by a ref " +
|
|
372
|
+
"from a browser_snapshot reply, never a raw selector, and a ref superseded by a later snapshot is " +
|
|
373
|
+
"refused rather than resolved elsewhere; save_scenario turns an explored session into a committed, " +
|
|
374
|
+
"replayable file and run_scenario replays one in a single batched call. Every verb returns " +
|
|
375
|
+
"whatever the page produced — console errors, failed requests — raw and untriaged. Each verb " +
|
|
376
|
+
"accepts only its own arguments; sending another verb's argument is refused, naming which verb it " +
|
|
377
|
+
"belongs to.",
|
|
378
|
+
class: "action",
|
|
379
|
+
tier: "evidence",
|
|
380
|
+
version: "1.0.0",
|
|
381
|
+
inputSchema: SCHEMA,
|
|
382
|
+
run,
|
|
383
|
+
describeAction,
|
|
384
|
+
redactArgs,
|
|
385
|
+
};
|
|
386
|
+
//# sourceMappingURL=browser.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/tools/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,UAAU,EAAiB,MAAM,WAAW,CAAC;AAwCtD,MAAM,UAAU,GAAkD;IAChE,aAAa,EAAE,uBAAuB;IACtC,KAAK,EAAE,gBAAgB;IACvB,IAAI,EAAE,eAAe;IACrB,IAAI,EAAE,eAAe;IACrB,MAAM,EAAE,iBAAiB;IACzB,MAAM,EAAE,iBAAiB;IACzB,aAAa,EAAE,uBAAuB;IACtC,YAAY,EAAE,sBAAsB;CACrC,CAAC;AAEF;;;8FAG8F;AAC9F,MAAM,KAAK,GAAqC;IAC9C;QACE,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE;YACP,WAAW;YACX,UAAU;YACV,aAAa;YACb,cAAc;YACd,aAAa;YACb,cAAc;YACd,kBAAkB;YAClB,wBAAwB;YACxB,kBAAkB;YAClB,oBAAoB;SACrB;KACF;IACD,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE;IAChD,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE;IACvD,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE;IACvD,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE;IAC1D,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE;IACjD,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE;IAC5G,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE;CACzD,CAAC;AAEF;6DAC6D;AAC7D,MAAM,MAAM,GAAG,CAAC,cAAc,CAAU,CAAC;AAEzC,SAAS,WAAW,CAAC,IAA6B;IAChD,OAAO,UAAU,CAAc,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAC9D,CAAC;AAED,KAAK,UAAU,GAAG,CAAC,IAA6B,EAAE,GAAgB;IAChE,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,uEAAuE;IACvE,6EAA6E;IAC7E,4EAA4E;IAC5E,iFAAiF;IACjF,sEAAsE;IACtE,qEAAqE;IACrE,uBAAuB;IACvB,OAAO,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAA4B,CAAC;AAC5E,CAAC;AAED;;;;4DAI4D;AAC5D,KAAK,UAAU,cAAc,CAAC,IAA6B,EAAE,GAAgB;IAC3E,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACtD,CAAC;AAED;;;wEAGwE;AACxE,SAAS,UAAU,CAAC,IAA6B;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,IAAmB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACpF,OAAO,IAAI,EAAE,UAAU,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AAC1C,CAAC;AAED,MAAM,QAAQ,GACZ,gGAAgG;IAChG,+FAA+F;IAC/F,+CAA+C,CAAC;AAElD,MAAM,aAAa,GAAG;IACpB,IAAI,EAAE,QAAQ;IACd,WAAW,EACT,iFAAiF;QACjF,+FAA+F;QAC/F,uFAAuF;QACvF,2FAA2F;IAC7F,UAAU,EAAE;QACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2DAA2D,EAAE;QAClG,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iEAAiE,EAAE;QACxG,QAAQ,EAAE;YACR,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC;YACxB,WAAW,EACT,6FAA6F;gBAC7F,8EAA8E;SACjF;KACF;IACD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC;IACtC,oBAAoB,EAAE,KAAK;CACnB,CAAC;AAEX,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,CAAC;YACrG,WAAW,EACT,6FAA6F;gBAC7F,yFAAyF;gBACzF,2CAA2C;SAC9C;QAED,6BAA6B;QAC7B,SAAS,EAAE;YACT,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,6EAA6E;gBAC7E,0FAA0F;gBAC1F,4FAA4F;gBAC5F,2FAA2F;gBAC3F,wDAAwD;SAC3D;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,+FAA+F;SAC7G;QACD,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,yFAAyF;gBACzF,8FAA8F;gBAC9F,2FAA2F;gBAC3F,6FAA6F;gBAC7F,6FAA6F;gBAC7F,sEAAsE;YACxE,UAAU,EAAE;gBACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qFAAqF,EAAE;gBAC9H,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wFAAwF,EAAE;aAClI;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;YACpB,oBAAoB,EAAE,KAAK;SAC5B;QACD,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,qFAAqF;gBACrF,uFAAuF;gBACvF,wFAAwF;SAC3F;QACD,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,8FAA8F;gBAC9F,0FAA0F;gBAC1F,yFAAyF;gBACzF,6FAA6F;gBAC7F,4BAA4B;YAC9B,UAAU,EAAE;gBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qEAAqE,EAAE;gBAC5G,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,yBAAyB,CAAC;oBACtD,WAAW,EAAE,wEAAwE;iBACtF;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC;YACjC,oBAAoB,EAAE,IAAI;SAC3B;QACD,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,uFAAuF;gBACvF,4FAA4F;gBAC5F,qEAAqE;YACvE,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,OAAO;oBACb,WAAW,EAAE,qEAAqE;oBAClF,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;4BACxB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;4BACzB,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE;4BACzD,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;4BAC7B,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;4BAC3B,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE;yBAC9D;wBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;wBAC3B,oBAAoB,EAAE,KAAK;qBAC5B;iBACF;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,6FAA6F;oBAC1G,oBAAoB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iBACzC;aACF;YACD,oBAAoB,EAAE,KAAK;SAC5B;QACD,gBAAgB,EAAE;YAChB,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,yFAAyF;gBACzF,0FAA0F;gBAC1F,gDAAgD;SACnD;QACD,sBAAsB,EAAE;YACtB,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,yFAAyF;gBACzF,gGAAgG;gBAChG,kGAAkG;gBAClG,kGAAkG;gBAClG,oGAAoG;SACvG;QACD,gBAAgB,EAAE;YAChB,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,4FAA4F;gBAC5F,qFAAqF;YACvF,oBAAoB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACzC;QACD,kBAAkB,EAAE;YAClB,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,8FAA8F;gBAC9F,+FAA+F;gBAC/F,yCAAyC;SAC5C;QAED,+EAA+E;QAC/E,SAAS,EAAE;YACT,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,wFAAwF;SACtG;QACD,GAAG,EAAE;YACH,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,sDAAsD,QAAQ,EAAE;SAC9E;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,0FAA0F;gBAC1F,4FAA4F;gBAC5F,+FAA+F;gBAC/F,8FAA8F;gBAC9F,oEAAoE;SACvE;QACD,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,0FAA0F;gBAC1F,wFAAwF;gBACxF,yDAAyD;SAC5D;QAED,uCAAuC;QACvC,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,wFAAwF;gBACxF,2FAA2F;gBAC3F,8CAA8C;SACjD;QAED,6BAA6B;QAC7B,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sEAAsE,EAAE;QACpH,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,WAAW,EACT,0FAA0F;gBAC1F,+FAA+F;gBAC/F,gEAAgE;YAClE,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,MAAM,EAAE;wBACN,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC;wBAC3C,WAAW,EAAE,sFAAsF;qBACpG;oBACD,MAAM,EAAE,aAAa;oBACrB,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mCAAmC,EAAE;oBACzE,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,WAAW,EACT,yFAAyF;4BACzF,yCAAyC;qBAC5C;iBACF;gBACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;gBACpB,oBAAoB,EAAE,KAAK;aAC5B;SACF;QACD,UAAU,EAAE;YACV,IAAI,EAAE,OAAO;YACb,WAAW,EACT,2FAA2F;gBAC3F,+FAA+F;gBAC/F,SAAS;YACX,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,CAAC,gBAAgB,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,CAAC;wBAC1F,WAAW,EACT,0FAA0F;4BAC1F,yFAAyF;4BACzF,0EAA0E;qBAC7E;oBACD,SAAS,EAAE;wBACT,IAAI,EAAE,SAAS;wBACf,WAAW,EAAE,yGAAyG;qBACvH;oBACD,MAAM,EAAE,aAAa;oBACrB,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+DAA+D,EAAE;iBAC3G;gBACD,QAAQ,EAAE,CAAC,MAAM,CAAC;gBAClB,oBAAoB,EAAE,KAAK;aAC5B;SACF;QAED,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,iMAAiM;gBACjM,8FAA8F;gBAC9F,2FAA2F;gBAC3F,wFAAwF;gBACxF,+FAA+F;SAClG;KACF;IACD,QAAQ,EAAE,CAAC,MAAM,CAAC;IAClB,oBAAoB,EAAE,KAAK;CACnB,CAAC;AAEX,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,sBAAsB;IAC7B,WAAW,EACT,gGAAgG;QAChG,iGAAiG;QACjG,gGAAgG;QAChG,mGAAmG;QACnG,oGAAoG;QACpG,4FAA4F;QAC5F,8FAA8F;QAC9F,mGAAmG;QACnG,aAAa;IACf,KAAK,EAAE,QAAQ;IACf,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;IAChB,WAAW,EAAE,MAAM;IACnB,GAAG;IACH,cAAc;IACd,UAAU;CACX,CAAC"}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `change_scope` — merges `scope` and `pre_push` behind one `verb`
|
|
3
|
+
* (documents/plans/mcp-surface-consolidation.md §2, group 2). Both are
|
|
4
|
+
* `read`/`evidence`, so the merge crosses neither boundary.
|
|
5
|
+
*
|
|
6
|
+
* Dispatch only. Each verb's own `run()` body is untouched and stays in its
|
|
7
|
+
* own module (`scope.ts` / `pre-push.ts`) — `pre-push.ts` itself already
|
|
8
|
+
* composes `scope`, `pr_analysis`, `contracts` and `validate` internally, and
|
|
9
|
+
* that composition is unaffected by this merge: it still calls `scopeTool.run`
|
|
10
|
+
* directly, not through this dispatcher.
|
|
11
|
+
*/
|
|
12
|
+
import type { ToolDefinition } from "./kit.ts";
|
|
13
|
+
import type { ScopeData } from "./scope.ts";
|
|
14
|
+
import type { PrePushData } from "./pre-push.ts";
|
|
15
|
+
/**
|
|
16
|
+
* What this tool answers with: one verb's shape, never a merged one.
|
|
17
|
+
*
|
|
18
|
+
* The merge cost this its single concrete output type, and `unknown` would have
|
|
19
|
+
* silently retired `output-shapes.test.ts`'s check that a declared shape is tied
|
|
20
|
+
* to the code producing it. A union keeps that tie: a verb added without its
|
|
21
|
+
* shape here stops compiling.
|
|
22
|
+
*/
|
|
23
|
+
export type ChangeScopeData = ScopeData | PrePushData;
|
|
24
|
+
export declare const changeScopeTool: ToolDefinition;
|
|
25
|
+
//# sourceMappingURL=change-scope.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"change-scope.d.ts","sourceRoot":"","sources":["../../src/tools/change-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,UAAU,CAAC;AAK5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,WAAW,CAAC;AA6FhB,eAAO,MAAM,eAAe,EAAE,cAe7B,CAAC"}
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `change_scope` — merges `scope` and `pre_push` behind one `verb`
|
|
3
|
+
* (documents/plans/mcp-surface-consolidation.md §2, group 2). Both are
|
|
4
|
+
* `read`/`evidence`, so the merge crosses neither boundary.
|
|
5
|
+
*
|
|
6
|
+
* Dispatch only. Each verb's own `run()` body is untouched and stays in its
|
|
7
|
+
* own module (`scope.ts` / `pre-push.ts`) — `pre-push.ts` itself already
|
|
8
|
+
* composes `scope`, `pr_analysis`, `contracts` and `validate` internally, and
|
|
9
|
+
* that composition is unaffected by this merge: it still calls `scopeTool.run`
|
|
10
|
+
* directly, not through this dispatcher.
|
|
11
|
+
*/
|
|
12
|
+
import { selectVerb } from "./verb.js";
|
|
13
|
+
import { scopeTool } from "./scope.js";
|
|
14
|
+
import { prePushTool } from "./pre-push.js";
|
|
15
|
+
const VERBS = ["diff", "pre_push"];
|
|
16
|
+
const TRIGGERS = ["pre-push", "pr", "nightly"];
|
|
17
|
+
const WORKING_TREE_SCOPES = ["unstaged", "staged", "all"];
|
|
18
|
+
const VERB_SPECS = [
|
|
19
|
+
{ verb: "diff", accepts: ["files", "nodeIds", "trigger", "budget", "limit"] },
|
|
20
|
+
{ verb: "pre_push", accepts: ["files", "base", "workingTree", "includeUntracked", "perSource"] },
|
|
21
|
+
];
|
|
22
|
+
const SCHEMA = {
|
|
23
|
+
type: "object",
|
|
24
|
+
properties: {
|
|
25
|
+
verb: {
|
|
26
|
+
type: "string",
|
|
27
|
+
enum: [...VERBS],
|
|
28
|
+
description: '"diff" — blast radius of changed files/nodes, ranked by impact score. "pre_push" — diff, ' +
|
|
29
|
+
"pr_analysis, contracts and validate together under the pre-push budget, in one envelope.",
|
|
30
|
+
},
|
|
31
|
+
files: {
|
|
32
|
+
type: "array",
|
|
33
|
+
items: { type: "string" },
|
|
34
|
+
description: "Repository-relative paths. diff: seeds the blast radius, with or instead of nodeIds. " +
|
|
35
|
+
"pre_push: required — the files about to be pushed.",
|
|
36
|
+
},
|
|
37
|
+
nodeIds: {
|
|
38
|
+
type: "array",
|
|
39
|
+
items: { type: "string" },
|
|
40
|
+
description: "diff only. Graph node ids to seed with directly, instead of or as well as files.",
|
|
41
|
+
},
|
|
42
|
+
trigger: {
|
|
43
|
+
type: "string",
|
|
44
|
+
enum: [...TRIGGERS],
|
|
45
|
+
description: "diff only. Node budget: pre-push 200, pr 1000, nightly 5000. Default pr.",
|
|
46
|
+
},
|
|
47
|
+
budget: {
|
|
48
|
+
type: "integer",
|
|
49
|
+
minimum: 1,
|
|
50
|
+
description: "diff only. Override the trigger's node budget.",
|
|
51
|
+
},
|
|
52
|
+
limit: {
|
|
53
|
+
type: "integer",
|
|
54
|
+
minimum: 1,
|
|
55
|
+
description: "diff only. Cap how many affected nodes come back. Default 25.",
|
|
56
|
+
},
|
|
57
|
+
base: {
|
|
58
|
+
type: "string",
|
|
59
|
+
description: 'pre_push only. Git ref to diff against, three-dot, for the pr_analysis section. Mutually ' +
|
|
60
|
+
'exclusive with "workingTree".',
|
|
61
|
+
},
|
|
62
|
+
workingTree: {
|
|
63
|
+
type: "string",
|
|
64
|
+
enum: [...WORKING_TREE_SCOPES],
|
|
65
|
+
description: 'pre_push only. Review the working tree instead of a ref range. Mutually exclusive with "base".',
|
|
66
|
+
},
|
|
67
|
+
includeUntracked: {
|
|
68
|
+
type: "boolean",
|
|
69
|
+
description: 'pre_push only. With "workingTree", include files git has never seen. Default true.',
|
|
70
|
+
},
|
|
71
|
+
perSource: {
|
|
72
|
+
type: "integer",
|
|
73
|
+
minimum: 1,
|
|
74
|
+
description: "pre_push only. How many items each source contributes. Default 3.",
|
|
75
|
+
},
|
|
76
|
+
},
|
|
77
|
+
required: ["verb"],
|
|
78
|
+
additionalProperties: false,
|
|
79
|
+
};
|
|
80
|
+
const DISPATCH = {
|
|
81
|
+
diff: scopeTool,
|
|
82
|
+
pre_push: prePushTool,
|
|
83
|
+
};
|
|
84
|
+
async function run(args, ctx) {
|
|
85
|
+
const verb = selectVerb(args, "verb", VERB_SPECS);
|
|
86
|
+
// `ToolDefinition` erases its answer's type parameter — it has to, the
|
|
87
|
+
// registry is one array of many shapes — so the delegated call comes back as
|
|
88
|
+
// an erased answer type. The verb table is what makes the union true: every
|
|
89
|
+
// entry's own `run` is declared against one of ChangeScopeData's members, and a verb
|
|
90
|
+
// added without its shape stops compiling at the union. The assertion
|
|
91
|
+
// re-applies what the table already guarantees rather than asserting
|
|
92
|
+
// something unchecked.
|
|
93
|
+
return (await DISPATCH[verb].run(args, ctx));
|
|
94
|
+
}
|
|
95
|
+
export const changeScopeTool = {
|
|
96
|
+
name: "change_scope",
|
|
97
|
+
class: "read",
|
|
98
|
+
tier: "evidence",
|
|
99
|
+
version: "1.0.0",
|
|
100
|
+
title: "Blast radius of a change, or everything worth knowing before a push",
|
|
101
|
+
description: 'What a change touches, by verb. "diff" — given files or symbols you are changing, return what ' +
|
|
102
|
+
"else is affected, ranked by impact score and grouped into tiers 1-4; names paths it could not " +
|
|
103
|
+
'find rather than reporting them unaffected. "pre_push" — runs diff, pr_analysis, contracts and ' +
|
|
104
|
+
"validate together under the pre-push node budget and returns one short envelope: blast radius, " +
|
|
105
|
+
"untested reach, contract breaks, and environment claims that do not hold. blockingTotal counts " +
|
|
106
|
+
"only defects; leads are reported separately.",
|
|
107
|
+
inputSchema: SCHEMA,
|
|
108
|
+
run,
|
|
109
|
+
};
|
|
110
|
+
//# sourceMappingURL=change-scope.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"change-scope.js","sourceRoot":"","sources":["../../src/tools/change-scope.ts"],"names":[],"mappings":"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"}
|