@ddtcorex/dsh-maestro-review 0.12.1 → 0.14.0

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.
Files changed (162) hide show
  1. package/README.md +31 -58
  2. package/cordis.patch.yml +13 -18
  3. package/lib/config-store.d.ts +9 -1
  4. package/lib/config-store.d.ts.map +1 -1
  5. package/lib/config-store.js +1 -1
  6. package/lib/config-store.js.map +1 -1
  7. package/lib/events.d.ts +5 -45
  8. package/lib/events.d.ts.map +1 -1
  9. package/lib/host-orchestrator.d.ts +128 -0
  10. package/lib/host-orchestrator.d.ts.map +1 -0
  11. package/lib/host-orchestrator.js +408 -0
  12. package/lib/host-orchestrator.js.map +1 -0
  13. package/lib/index.d.ts +7 -2
  14. package/lib/index.d.ts.map +1 -1
  15. package/lib/index.js +7 -43
  16. package/lib/index.js.map +1 -1
  17. package/lib/review-intake.d.ts +1 -1
  18. package/lib/review-intake.d.ts.map +1 -1
  19. package/lib/settings-rpc.js +1 -1
  20. package/lib/settings-rpc.js.map +1 -1
  21. package/package.json +19 -36
  22. package/src/client/index.tsx +1 -1
  23. package/src/host/augment.d.ts +3 -1
  24. package/src/host/config-store.ts +2 -2
  25. package/src/host/events.ts +5 -45
  26. package/src/host/host-orchestrator.ts +461 -0
  27. package/src/host/index.ts +7 -35
  28. package/src/host/providers/gitlab.ts +1 -1
  29. package/src/host/review-intake.ts +1 -1
  30. package/src/host/settings-rpc.ts +1 -1
  31. package/lib/ci-clone.d.ts +0 -21
  32. package/lib/ci-clone.d.ts.map +0 -1
  33. package/lib/ci-clone.js +0 -35
  34. package/lib/ci-clone.js.map +0 -1
  35. package/lib/ci-coexist.d.ts +0 -11
  36. package/lib/ci-coexist.d.ts.map +0 -1
  37. package/lib/ci-coexist.js +0 -38
  38. package/lib/ci-coexist.js.map +0 -1
  39. package/lib/gitlab-auth.d.ts +0 -11
  40. package/lib/gitlab-auth.d.ts.map +0 -1
  41. package/lib/gitlab-auth.js +0 -15
  42. package/lib/gitlab-auth.js.map +0 -1
  43. package/lib/gitlab-client.d.ts +0 -78
  44. package/lib/gitlab-client.d.ts.map +0 -1
  45. package/lib/gitlab-client.js +0 -270
  46. package/lib/gitlab-client.js.map +0 -1
  47. package/lib/govard-lint-detection.d.ts +0 -20
  48. package/lib/govard-lint-detection.d.ts.map +0 -1
  49. package/lib/govard-lint-detection.js +0 -48
  50. package/lib/govard-lint-detection.js.map +0 -1
  51. package/lib/hyva-csp-scan-tool.d.ts +0 -11
  52. package/lib/hyva-csp-scan-tool.d.ts.map +0 -1
  53. package/lib/hyva-csp-scan-tool.js +0 -193
  54. package/lib/hyva-csp-scan-tool.js.map +0 -1
  55. package/lib/hyva-theme-inspect-tool.d.ts +0 -10
  56. package/lib/hyva-theme-inspect-tool.d.ts.map +0 -1
  57. package/lib/hyva-theme-inspect-tool.js +0 -299
  58. package/lib/hyva-theme-inspect-tool.js.map +0 -1
  59. package/lib/incremental.d.ts +0 -28
  60. package/lib/incremental.d.ts.map +0 -1
  61. package/lib/incremental.js +0 -62
  62. package/lib/incremental.js.map +0 -1
  63. package/lib/layout-xml-tool.d.ts +0 -11
  64. package/lib/layout-xml-tool.d.ts.map +0 -1
  65. package/lib/layout-xml-tool.js +0 -239
  66. package/lib/layout-xml-tool.js.map +0 -1
  67. package/lib/module-check-tool.d.ts +0 -11
  68. package/lib/module-check-tool.d.ts.map +0 -1
  69. package/lib/module-check-tool.js +0 -303
  70. package/lib/module-check-tool.js.map +0 -1
  71. package/lib/orchestrator.d.ts +0 -357
  72. package/lib/orchestrator.d.ts.map +0 -1
  73. package/lib/orchestrator.js +0 -1497
  74. package/lib/orchestrator.js.map +0 -1
  75. package/lib/perf-log-stats-tool.d.ts +0 -13
  76. package/lib/perf-log-stats-tool.d.ts.map +0 -1
  77. package/lib/perf-log-stats-tool.js +0 -245
  78. package/lib/perf-log-stats-tool.js.map +0 -1
  79. package/lib/phtml-escape-scan-tool.d.ts +0 -11
  80. package/lib/phtml-escape-scan-tool.d.ts.map +0 -1
  81. package/lib/phtml-escape-scan-tool.js +0 -166
  82. package/lib/phtml-escape-scan-tool.js.map +0 -1
  83. package/lib/providers/ci-trigger.d.ts +0 -44
  84. package/lib/providers/ci-trigger.d.ts.map +0 -1
  85. package/lib/providers/ci-trigger.js +0 -150
  86. package/lib/providers/ci-trigger.js.map +0 -1
  87. package/lib/review-findings-tool.d.ts +0 -20
  88. package/lib/review-findings-tool.d.ts.map +0 -1
  89. package/lib/review-findings-tool.js +0 -39
  90. package/lib/review-findings-tool.js.map +0 -1
  91. package/lib/review-history.d.ts +0 -40
  92. package/lib/review-history.d.ts.map +0 -1
  93. package/lib/review-history.js +0 -136
  94. package/lib/review-history.js.map +0 -1
  95. package/lib/review-marker.d.ts +0 -17
  96. package/lib/review-marker.d.ts.map +0 -1
  97. package/lib/review-marker.js +0 -23
  98. package/lib/review-marker.js.map +0 -1
  99. package/lib/review-signals.d.ts +0 -17
  100. package/lib/review-signals.d.ts.map +0 -1
  101. package/lib/review-signals.js +0 -79
  102. package/lib/review-signals.js.map +0 -1
  103. package/lib/scope-split-tool.d.ts +0 -42
  104. package/lib/scope-split-tool.d.ts.map +0 -1
  105. package/lib/scope-split-tool.js +0 -108
  106. package/lib/scope-split-tool.js.map +0 -1
  107. package/lib/search-tool.d.ts +0 -15
  108. package/lib/search-tool.d.ts.map +0 -1
  109. package/lib/search-tool.js +0 -144
  110. package/lib/search-tool.js.map +0 -1
  111. package/lib/skill-provider.d.ts +0 -19
  112. package/lib/skill-provider.d.ts.map +0 -1
  113. package/lib/skill-provider.js +0 -101
  114. package/lib/skill-provider.js.map +0 -1
  115. package/lib/skills-tool.d.ts +0 -29
  116. package/lib/skills-tool.d.ts.map +0 -1
  117. package/lib/skills-tool.js +0 -185
  118. package/lib/skills-tool.js.map +0 -1
  119. package/lib/source.d.ts +0 -23
  120. package/lib/source.d.ts.map +0 -1
  121. package/lib/source.js +0 -16
  122. package/lib/source.js.map +0 -1
  123. package/lib/tool-policy.d.ts +0 -20
  124. package/lib/tool-policy.d.ts.map +0 -1
  125. package/lib/tool-policy.js +0 -42
  126. package/lib/tool-policy.js.map +0 -1
  127. package/presets/maestro-auditor.patch.yml +0 -54
  128. package/presets/maestro-coder/agent.cordis.yml +0 -223
  129. package/presets/maestro-coder/preset.yml +0 -2
  130. package/presets/maestro-reviewer.patch.yml +0 -55
  131. package/profiles/reviewer-ci/cordis.patch.yml +0 -78
  132. package/profiles/reviewer-ci/package.json +0 -19
  133. package/profiles/reviewer-ci/pnpm-lock.yaml +0 -8201
  134. package/profiles/reviewer-ci/pnpm-workspace.yaml +0 -36
  135. package/skills/dsh-native-tools/SKILL.md +0 -80
  136. package/src/host/ci-clone.ts +0 -54
  137. package/src/host/ci-coexist.ts +0 -45
  138. package/src/host/dsh-skill.d.ts +0 -72
  139. package/src/host/gitlab-auth.ts +0 -13
  140. package/src/host/gitlab-client.ts +0 -332
  141. package/src/host/govard-lint-detection.ts +0 -47
  142. package/src/host/hyva-csp-scan-tool.ts +0 -165
  143. package/src/host/hyva-theme-inspect-tool.ts +0 -258
  144. package/src/host/incremental.ts +0 -86
  145. package/src/host/layout-xml-tool.ts +0 -190
  146. package/src/host/module-check-tool.ts +0 -187
  147. package/src/host/orchestrator.ts +0 -1641
  148. package/src/host/perf-log-stats-tool.ts +0 -224
  149. package/src/host/phtml-escape-scan-tool.ts +0 -112
  150. package/src/host/providers/ci-trigger.ts +0 -168
  151. package/src/host/review-findings-tool.ts +0 -59
  152. package/src/host/review-history.ts +0 -168
  153. package/src/host/review-marker.ts +0 -25
  154. package/src/host/review-signals.ts +0 -83
  155. package/src/host/scope-split-tool.ts +0 -109
  156. package/src/host/search-tool.ts +0 -152
  157. package/src/host/skill-provider.ts +0 -94
  158. package/src/host/skills-tool.ts +0 -218
  159. package/src/host/source.ts +0 -26
  160. package/src/host/tool-policy.ts +0 -49
  161. package/templates/reviewer-project.gitlab-ci.yml +0 -93
  162. package/templates/source-project.gitlab-ci.yml +0 -48
@@ -1,36 +0,0 @@
1
- # Marks profiles/reviewer-ci as its OWN standalone pnpm workspace root — without
2
- # this file, pnpm's workspace-root detection walks up and finds
3
- # packages/dsh-maestro-review's own pnpm-workspace.yaml two levels up (this
4
- # profile is nested inside that package's directory tree), silently folding
5
- # the profile into that unrelated workspace instead of installing it
6
- # independently (verified 2026-09-03: `pnpm --dir profiles/reviewer-ci install`
7
- # printed "Scope: all 2 workspace projects" and resolved relative to `../..`
8
- # without this file present).
9
- packages: []
10
- # No `overrides:` block on the 0.1.7-rc.1 line, deliberately. The 0.1.5-rc.2
11
- # profile needed one because those packages declared loose ranges, so ~23 of
12
- # their transitive deps resolved back to the older 0.1.2-rc.1 — silent at
13
- # install time (a peer warning only), fatal at boot: a newer consumer
14
- # ESM-imported a symbol the older peer's build never exported (e.g.
15
- # dsh-session-persistence-jsonl@0.1.5-rc.2 importing SessionAlreadyExistsError
16
- # from dsh-session-persistence@0.1.2-rc.1), crashing the whole plugin tree with
17
- # exit 1. Every `@deepseek-ai/dsh-*` package on the alpha.2 line pins its own
18
- # graph exactly, so the same install needs no forcing (verified 2026-09-23:
19
- # 281 @deepseek-ai packages installed, zero duplicate package names, one
20
- # cordis@4.0.4 that satisfies the plugin's `~4.0.4` peer).
21
- # Postinstall scripts required at runtime (node-pty/subprocess-local spawn
22
- # agents, koffi/protobufjs/genai serve model IO). Exact versions pinned in
23
- # pnpm-lock.yaml; review on every profile dep bump.
24
- allowBuilds:
25
- '@deepseek-ai/dsh-subprocess-local': true
26
- '@google/genai': true
27
- koffi: true
28
- node-pty: true
29
- protobufjs: true
30
- # pnpm keeps only the FIRST entry per package name, so bumping our own
31
- # release means REPLACING its entry — appending the newer version leaves it
32
- # shadowed by the stale one and the 24h age gate keeps rejecting it (observed
33
- # 2026-09-18). The Docker build additionally passes
34
- # --config.minimumReleaseAge=0.
35
- minimumReleaseAgeExclude:
36
- - '@ddtcorex/dsh-maestro-review@0.9.0'
@@ -1,80 +0,0 @@
1
- ---
2
- name: dsh-native-tools
3
- description: Use when running a Maestro skill inside DeepSeek Harness and its text says "native ... when provided" — this maps each such capability (query-log stats, lint, deploy preflight, layout extraction, theme inspection, review scope split, escape scan, module check, MR diff) to the DSH tool or the govard CLI command, run with bash, that provides it
4
- ---
5
-
6
- # DSH Native Tools
7
-
8
- Every public Maestro skill names a **capability**, never a tool: "if the runtime
9
- provides a native query-log stats tool, prefer it; otherwise use the recipe below".
10
- Inside DeepSeek Harness those tools exist, and this file is the map from capability
11
- to call.
12
-
13
- Load this whenever a loaded Maestro skill says *native … when provided*, then call
14
- the tool named here instead of the portable recipe in that skill.
15
-
16
- ## Harness-agnostic actions → DSH tools
17
-
18
- The process skills (superpowers fork, `using-superpowers`) describe actions in
19
- harness-neutral words — announce, dispatch a subagent, ask your partner. On DSH:
20
-
21
- | Action in skill text | DSH tool |
22
- |---|---|
23
- | Invoke / load a skill | `skill` with `{ name }` |
24
- | Dispatch a fresh subagent per task | `subagent` (background by default; pass `run_in_background: false` only when the next step depends on its result) |
25
- | Continue or redirect an existing subagent | `send_message` to its durable `subagent_id` |
26
- | Fan out independent tasks concurrently | several independent tool calls in one assistant turn |
27
- | Large multi-phase orchestration | `workflow` — only when the human explicitly asks for a workflow |
28
- | Fresh-agent iterative loop | `ralph` — only when the human explicitly asks for Ralph |
29
- | Seed a child with this conversation | `subagent_fork` |
30
- | Create a todo / checklist item | `todo_write` (whole list every call) |
31
- | Ask your human partner | `ask_user_question` |
32
- | Present a plan for approval | `exit_plan_mode` (plan mode only) |
33
- | Long-running objective across turns | goal tools: `create_goal`, `get_goal`, `update_goal` |
34
- | Read a file / find files / search contents | `read`, `glob`, `grep` |
35
- | Write / edit files | `write`, `edit` (read before edit) |
36
- | Run shell commands, tests, git | `bash`; background via `run_in_background: true`, collect with `job_output`, stop with `job_kill` |
37
- | Search the web | `web_search` |
38
- | Look at an image file | `read_image` |
39
-
40
- ## Native capability tools
41
-
42
- Left column is the phrase the public skill uses; right column is what to call.
43
-
44
- | Public skill says | Tool and signature |
45
- |---|---|
46
- | native query-log stats tool | `maestro_perf_log_stats {topN?, repeatThreshold?, timeThresholdMs?}` → streaming and bounded; never hand-grep a 16–50k line log or open it as a spreadsheet |
47
- | native lint tool | `govard audit run --checks lint --format json --mode auto --timeout auto --lint-provider govard --scope diff --base <sha>` run with `bash` in the review worktree (`--scope project` drops `--base`); `govard audit run --checks integrity --format json` is the container-free analysis. Read the JSON; exit `0` is clean, `1` findings, `3` a missing capability. A missing `govard` binary or Docker is not a finding: report lint as unavailable |
48
- | native deploy preflight | `govard deploy plan <remote>` (add `--json` for machine-readable) prints the pipeline without connecting; `govard deploy check <remote>` preflights connectivity and the release layout. Both run with `bash`, `remote` is a remote from `.govard.yml`, and running the deploy itself stays in the terminal |
49
- | native layout extraction | `layout_xml_extract {changedFiles:<MR layout files>}` → handles/blocks/moves + templateExists/parseError |
50
- | native theme inspection | `hyva_theme_inspect {classes:["<class-from-diff>"]}` → `{themes[],tailwind:{major,...},hyvaPackages[]}`; a null field means downgrade to a question |
51
- | native review scope split | `maestro_review_scope_split {diffStats:{files,addedLinesPerFile}, mode}` → `{split:{quick,deep},reason,estimatedSavingsTokens}`; run quick checks only on quick files |
52
- | native escape scan | `phtml_escape_scan {scope:"diff", paths:<changed phtml>}` → `{findings[],scannedFiles,truncated}` with confidence + M2-SEC-xxx; `hyva_csp_scan {maxFiles?}` covers CSP work and truncates at `maxFiles` with no `truncated` flag — size the input yourself |
53
- | native module check | `magento_module_check {modulePath:"app/code/Vendor/Module"}` → `{modules[],scannedModules,truncated}`; always check `scannedModules` against what you expected |
54
- | native MR diff | `gitlab_get_mr_diff`, `gitlab_list_own_review_threads`, `gitlab_post_inline_comment` — diff plus own threads plus inline comments in one call |
55
- | local environment inside a review worktree | `govard env up` brings it up, `govard shell -c "<command>"` runs one command in the container, `govard env down -v` tears it down (always, even after a failure). All three run with `bash`; the worktree carries its own project name so it never collides with the primary checkout |
56
-
57
- The `maestro_get_skills` tool searches this same skill catalogue by keyword and
58
- returns full content — useful when a review profile has not preloaded a skill.
59
-
60
- ## Session-shape notes
61
-
62
- - Skills arrive as catalog summaries in a `<system-reminder>`; load one with the
63
- `skill` tool before acting on it. There is no session-start bootstrap injection
64
- on DSH, so checking the available-skills list first is your job.
65
- - Background subagents notify you when they settle — do not poll. Collect any
66
- still-relevant jobs before finishing a turn.
67
- - "Announce …" in a process skill is plain prose in your reply; DSH has no separate
68
- announcement channel.
69
- - "interactive when the runtime supports it" means call `ask_user_question` rather
70
- than guessing a default; on DSH interactive questions are always available.
71
-
72
- ## Maintenance
73
-
74
- - Public skills stay tool-neutral. Never copy a tool name back into
75
- `maestro-skills`: its catalog test rejects `maestro_*`, `DSH`
76
- and `DeepSeek Harness` anywhere in skill content, `compatibility: dsh` frontmatter
77
- excepted.
78
- - Renaming a tool in `src/host` must fail `tests/dsh-native-tools-skill.test.ts`, so
79
- this map cannot rot silently.
80
- - Update this file when the DSH tool surface changes; the public skills need no edit.
@@ -1,54 +0,0 @@
1
- import { execFile } from 'node:child_process'
2
- import { promisify } from 'node:util'
3
- import { gitlabAuthHeaders } from './gitlab-auth.js'
4
-
5
- /**
6
- * Source checkout for CI deep reviews (spec §3): clone the source project at
7
- * the MR head SHA with the PAT over oauth2. The token lives only in the clone
8
- * URL passed to git — errors rethrown here are redacted, and the clone dir is
9
- * ephemeral (fresh container per job; the orchestrator removes it in `finally`).
10
- */
11
-
12
- export type RunFn = (cmd: string, args: string[], cwd?: string) => Promise<void>
13
-
14
- const execFileAsync = promisify(execFile)
15
-
16
- /** Production runner (execFile — no shell, argv cannot leak into shell history). */
17
- export const defaultRun: RunFn = async (cmd, args, cwd) => {
18
- await execFileAsync(cmd, args, { cwd, timeout: 120_000 })
19
- }
20
-
21
- export function redactCloneUrl(url: string): string {
22
- return url.replace(/oauth2:[^@]+@/, 'oauth2:***@')
23
- }
24
-
25
- async function repoHttpUrl(fetcher: typeof fetch, host: string, projectId: number, token: string): Promise<string> {
26
- const res = await fetcher(`https://${host}/api/v4/projects/${projectId}`, { headers: gitlabAuthHeaders(token) })
27
- if (!res.ok) throw new Error(`GitLab API error ${res.status}: ${(await res.text()).slice(0, 200)}`)
28
- const body = (await res.json()) as { http_url_to_repo?: string }
29
- if (!body.http_url_to_repo) throw new Error('project has no http_url_to_repo')
30
- return body.http_url_to_repo
31
- }
32
-
33
- export async function cloneSourceRepo(opts: {
34
- fetcher: typeof fetch
35
- run: RunFn
36
- host: string
37
- projectId: number
38
- sourceBranch: string
39
- headSha: string
40
- token: string
41
- dir: string
42
- }): Promise<string> {
43
- const httpUrl = await repoHttpUrl(opts.fetcher, opts.host, opts.projectId, opts.token)
44
- const authed = httpUrl.replace('https://', `https://oauth2:${opts.token}@`)
45
- try {
46
- await opts.run('git', ['clone', '--depth', '50', '--branch', opts.sourceBranch, '--', authed, opts.dir])
47
- await opts.run('git', ['fetch', '--depth', '50', 'origin', opts.headSha], opts.dir)
48
- await opts.run('git', ['checkout', '--detach', opts.headSha], opts.dir)
49
- } catch (err) {
50
- const message = err instanceof Error ? err.message : String(err)
51
- throw new Error(redactCloneUrl(message))
52
- }
53
- return opts.dir
54
- }
@@ -1,45 +0,0 @@
1
- import { gitlabAuthHeaders } from './gitlab-auth.js'
2
- import { parseReviewMarker } from './review-marker.js'
3
-
4
- /**
5
- * Coexistence checks (spec §4): the CI flow yields to a completed review of
6
- * the same head SHA carrying a review marker (i.e. an earlier CI review —
7
- * webhook reviews post marker-free and stay invisible here) and to an
8
- * in-flight review (eyes running-marker). Fetch failures fail open toward
9
- * running — a missing signal must never block a review, only a present one
10
- * skips it.
11
- */
12
- export async function hasCompletedReviewForSha(
13
- fetcher: typeof fetch, baseUrl: string, token: string, projectId: number, mrIid: number, sha: string,
14
- ): Promise<boolean> {
15
- try {
16
- const res = await fetcher(
17
- `${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/notes?per_page=100&sort=desc&order_by=created_at`,
18
- { headers: gitlabAuthHeaders(token) },
19
- )
20
- if (!res.ok) return false
21
- const notes = (await res.json()) as Array<{ body?: string }>
22
- return notes.some((n) => {
23
- const m = typeof n.body === 'string' ? parseReviewMarker(n.body) : undefined
24
- return m?.sha.toLowerCase() === sha.toLowerCase() && m?.status === 'completed'
25
- })
26
- } catch {
27
- return false
28
- }
29
- }
30
-
31
- export async function hasRunningEyes(
32
- fetcher: typeof fetch, baseUrl: string, token: string, projectId: number, mrIid: number,
33
- ): Promise<boolean> {
34
- try {
35
- const res = await fetcher(
36
- `${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji`,
37
- { headers: gitlabAuthHeaders(token) },
38
- )
39
- if (!res.ok) return false
40
- const awards = (await res.json()) as Array<{ name?: string }>
41
- return awards.some((a) => a.name === 'eyes')
42
- } catch {
43
- return false
44
- }
45
- }
@@ -1,72 +0,0 @@
1
- /**
2
- * Ambient types for the DSH skills provider contract.
3
- *
4
- * `@deepseek-ai/dsh-skill` ships inside the deepseek-harness host and is not a
5
- * resolvable dependency of this package (verified: `require.resolve` returns
6
- * MODULE_NOT_FOUND while `dsh-tools`, `dsh-agent` etc. do resolve). Declaring
7
- * the slice we implement here keeps the types honest without adding a
8
- * dependency that cannot be installed — the same approach
9
- * `dsh-maestro-supervisor` uses for its own provider.
10
- *
11
- * Field-for-field against
12
- * `deepseek-harness/packages/skill/skill/lib/types/index.d.ts`. Getting this
13
- * wrong is worse than having no type at all: an invented shape compiles against
14
- * a wrong call and rejects a correct one.
15
- */
16
- declare module '@deepseek-ai/dsh-skill' {
17
- /** Invocation controls shared by skill discovery consumers. */
18
- export interface SkillInvocationPolicy {
19
- readonly modelInvocable: boolean
20
- readonly userInvocable: boolean
21
- }
22
-
23
- /** Provider-specific base used by loaded bodies to resolve relative resources. */
24
- export type SkillResourceBase =
25
- | { readonly kind: 'directory'; readonly path: string }
26
- | { readonly kind: 'url'; readonly url: string }
27
- | { readonly kind: 'opaque'; readonly description: string }
28
-
29
- /** Invocation-neutral metadata; `path` and `resourceBase` are optional. */
30
- export interface SkillSummary {
31
- readonly path?: string
32
- readonly name: string
33
- readonly description: string
34
- readonly whenToUse?: string
35
- readonly invocation: SkillInvocationPolicy
36
- readonly source: string
37
- readonly provider: string
38
- readonly resourceBase?: SkillResourceBase
39
- }
40
-
41
- /** Provider catalog entry; `rank` orders duplicates, `locator` is opaque. */
42
- export interface SkillCandidate extends SkillSummary {
43
- readonly rank: number
44
- readonly locator: unknown
45
- readonly metadata?: Readonly<Record<string, unknown>>
46
- }
47
-
48
- /** Complete parsed skill definition, including the loaded body. */
49
- export interface SkillDefinition extends SkillSummary {
50
- readonly content: string
51
- readonly metadata?: Readonly<Record<string, unknown>>
52
- }
53
-
54
- /** Caller context for cwd-sensitive and abortable provider work. */
55
- export interface SkillLookupOptions {
56
- readonly cwd?: string | undefined
57
- readonly signal?: AbortSignal | undefined
58
- }
59
-
60
- /** Registration-scoped lifecycle and invalidation capability. */
61
- export interface SkillProviderControl {
62
- readonly signal: AbortSignal
63
- invalidate: () => void
64
- }
65
-
66
- /** The provider contract `registerProvider` expects. */
67
- export interface SkillProvider {
68
- readonly name: string
69
- readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[]>
70
- readonly get: (candidate: SkillCandidate, options: SkillLookupOptions) => Promise<SkillDefinition | undefined>
71
- }
72
- }
@@ -1,13 +0,0 @@
1
- /**
2
- * Centralized GitLab API auth header (spec: token-kind aware).
3
- *
4
- * Personal / project / group tokens authenticate with `PRIVATE-TOKEN`.
5
- * A CI job token (`CI_JOB_TOKEN`, cross-project via the target's job-token
6
- * allowlist) authenticates with `JOB-TOKEN` instead — `PRIVATE-TOKEN` 401s.
7
- * The kind comes from `GITLAB_TOKEN_KIND=job` (set by docker/entrypoint.sh
8
- * when it falls back to `CI_JOB_TOKEN`); anything else means PRIVATE-TOKEN.
9
- */
10
- export function gitlabAuthHeaders(token: string): Record<string, string> {
11
- if (process.env.GITLAB_TOKEN_KIND === 'job') return { 'JOB-TOKEN': token }
12
- return { 'PRIVATE-TOKEN': token }
13
- }
@@ -1,332 +0,0 @@
1
- import type { Context } from '@deepseek-ai/cordis'
2
- import z from '@deepseek-ai/schemastery'
3
- import { defineTool } from '@deepseek-ai/dsh-tools'
4
- import { mkdirSync, writeFileSync } from 'node:fs'
5
- import { join, resolve } from 'node:path'
6
- import { gitlabAuthHeaders } from './gitlab-auth.js'
7
-
8
- export const name = 'maestro-gitlab-client'
9
- export const inject = ['tools']
10
-
11
- export interface Config {
12
- baseUrl: string
13
- projectId: string | number
14
- mrIid: number
15
- token: string
16
- botUsername: string
17
- }
18
-
19
- export const Config: z<Config> = z.object({
20
- baseUrl: z.string().required(),
21
- projectId: z.union([z.string(), z.number()]).required(),
22
- mrIid: z.number().required(),
23
- token: z.string().role('secret').required(),
24
- botUsername: z.string().required(),
25
- })
26
-
27
- interface GitlabDiff {
28
- old_path: string
29
- new_path: string
30
- diff: string
31
- }
32
-
33
- export interface DiffFileEntry {
34
- path: string
35
- bytes: number
36
- }
37
-
38
- /** Per-file inventory of the MR diff — small enough to return inline. Pure. */
39
- export function diffFileList(diffs: GitlabDiff[]): DiffFileEntry[] {
40
- return diffs.map((d) => ({ path: d.new_path, bytes: Buffer.byteLength(d.diff, 'utf8') }))
41
- }
42
-
43
- /** Unified text for one file, or undefined when the path is not in the MR. Pure. */
44
- export function selectFileDiff(diffs: GitlabDiff[], path: string): string | undefined {
45
- const d = diffs.find((x) => x.new_path === path || x.old_path === path)
46
- if (d === undefined) return undefined
47
- return `--- ${d.old_path}\n+++ ${d.new_path}\n${d.diff}`
48
- }
49
-
50
- /**
51
- * `fetch` with a hard ceiling: aborts the request after `ms` (default 15s)
52
- * and throws `GitLab API timeout after <ms>ms` on abort. The timer is always
53
- * cleared on settle. Pre-agent lookups degrade the throw to `undefined` at
54
- * their own call site; post-agent callers let it reach `writeFailedReport`.
55
- */
56
- export async function fetchWithTimeout(
57
- url: string, init: RequestInit | undefined, ms = 15_000,
58
- ): Promise<Response> {
59
- const controller = new AbortController()
60
- const timer = setTimeout(() => controller.abort(), ms)
61
- try {
62
- return await fetch(url, { ...init, signal: controller.signal })
63
- } catch (err) {
64
- if ((err as Error)?.name === 'AbortError') throw new Error(`GitLab API timeout after ${ms}ms`)
65
- throw err
66
- } finally {
67
- clearTimeout(timer)
68
- }
69
- }
70
-
71
- interface GitlabDiffRefs {
72
- base_sha: string
73
- start_sha: string
74
- head_sha: string
75
- }
76
-
77
- interface GitlabDiscussionNote {
78
- body: string
79
- author: { username: string }
80
- position?: { new_path: string, new_line: number | null }
81
- resolved: boolean
82
- }
83
-
84
- interface GitlabDiscussion {
85
- id: string
86
- notes: GitlabDiscussionNote[]
87
- }
88
-
89
- interface OwnThread {
90
- discussionId: string
91
- path: string
92
- line: number | null
93
- lastCommentBody: string
94
- resolved: boolean
95
- }
96
-
97
- /**
98
- * Resolve the in-workspace spill path for the MR diff. The DSH runtime
99
- * spills large tool outputs to /tmp/dsh-spill-*, which sits outside the
100
- * agent's cwd — and Guard blocks the agent from reading it back
101
- * ("path outside cwd", tickets g-dd0d1679/g-716cd436). Writing the diff
102
- * inside the workspace root keeps it readable via maestro_read_file.
103
- */
104
- export function resolveDiffSpillPath(workspaceRoot: string, mrIid: number): string {
105
- return join(resolve(workspaceRoot), '.maestro', `mr-${mrIid}.diff`)
106
- }
107
-
108
- export function writeDiffSpill(workspaceRoot: string, mrIid: number, text: string): { path: string; bytes: number } {
109
- const abs = resolveDiffSpillPath(workspaceRoot, mrIid)
110
- mkdirSync(join(resolve(workspaceRoot), '.maestro'), { recursive: true })
111
- writeFileSync(abs, text, 'utf-8')
112
- return { path: join('.maestro', `mr-${mrIid}.diff`), bytes: Buffer.byteLength(text, 'utf8') }
113
- }
114
-
115
- interface SC{agent?:{session?:{header?:{cwd?:string}}}}
116
- function sessionCwd(e: unknown): string | undefined {
117
- const cwd = (e as SC|undefined)?.agent?.session?.header?.cwd
118
- return typeof cwd === 'string' && cwd !== '' ? cwd : undefined
119
- }
120
-
121
- /**
122
- * Pick this bot's inline threads out of the MR discussions list, including
123
- * resolved ones (flagged) so a same-SHA re-review can reply-update instead
124
- * of posting duplicates. Pure for unit testing.
125
- */
126
- export function selectOwnThreads(
127
- discussions: GitlabDiscussion[],
128
- botUsername: string,
129
- ): { threads: OwnThread[]; totalDiscussions: number } {
130
- const threads = discussions
131
- .filter(d => d.notes.length > 0 && d.notes[0].author.username === botUsername && d.notes[0].position !== undefined)
132
- .map(d => ({
133
- discussionId: d.id,
134
- path: d.notes[0].position!.new_path,
135
- line: d.notes[0].position!.new_line,
136
- lastCommentBody: d.notes[d.notes.length - 1].body,
137
- resolved: d.notes[0].resolved === true,
138
- }))
139
- return { threads, totalDiscussions: discussions.length }
140
- }
141
-
142
- export function apply(ctx: Context, config: Config): void {
143
- const apiBase = `${config.baseUrl}/api/v4/projects/${config.projectId}/merge_requests/${config.mrIid}`
144
- const headers = gitlabAuthHeaders(config.token)
145
- let cachedDiffRefs: GitlabDiffRefs | undefined
146
- let cachedDiffs: GitlabDiff[] | undefined
147
-
148
- async function getDiffs(): Promise<GitlabDiff[]> {
149
- if (cachedDiffs !== undefined) return cachedDiffs
150
- const response = await fetch(`${apiBase}/diffs`, { headers })
151
- if (!response.ok) {
152
- throw new Error(`GitLab API error ${response.status}: ${await response.text()}`)
153
- }
154
- cachedDiffs = (await response.json()) as GitlabDiff[]
155
- return cachedDiffs
156
- }
157
-
158
- async function getDiffRefs(): Promise<GitlabDiffRefs> {
159
- if (cachedDiffRefs !== undefined) return cachedDiffRefs
160
- const response = await fetch(apiBase, { headers })
161
- if (!response.ok) {
162
- throw new Error(`GitLab API error ${response.status}: ${await response.text()}`)
163
- }
164
- cachedDiffRefs = (await response.json() as { diff_refs: GitlabDiffRefs }).diff_refs
165
- return cachedDiffRefs
166
- }
167
-
168
- ctx.tools.register(defineTool({
169
- name: 'gitlab_get_mr_diff',
170
- description: 'Fetch the current unified diff for this merge request. The full diff is written to path (inside your workspace, readable via maestro_read_file); bytes is its size and files lists per-file sizes. Prefer gitlab_get_file_diff per file you inspect — small inline results never spill. Do not look for anything under /tmp.',
171
- parameters: {},
172
- output: {
173
- schema: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', required: true }, bytes: { type: 'number', required: true }, files: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', required: true }, bytes: { type: 'number', required: true } } } } } },
174
- render: (_args, value) => [{ type: 'text', text: `diff written to ${value.path} (${value.bytes} bytes, ${value.files.length} files)` }],
175
- },
176
- async execute(_args, exec) {
177
- const diffs = await getDiffs()
178
- const text = diffs.map(d => `--- ${d.old_path}\n+++ ${d.new_path}\n${d.diff}`).join('\n\n')
179
- const cwd = sessionCwd(exec)
180
- // No session cwd (should not happen for review agents): fall back to
181
- // the legacy inline text, which the runtime may spill to /tmp.
182
- if (cwd === undefined) return { path: '', bytes: Buffer.byteLength(text, 'utf8'), files: diffFileList(diffs) }
183
- const spilled = writeDiffSpill(cwd, config.mrIid, text)
184
- return { ...spilled, files: diffFileList(diffs) }
185
- },
186
- }))
187
-
188
- ctx.tools.register(defineTool({
189
- name: 'gitlab_get_file_diff',
190
- description: "Return one file's unified diff inline (small results never spill to /tmp). Use after gitlab_get_mr_diff to inspect files one by one.",
191
- parameters: {
192
- path: { type: 'string', required: true, description: 'New path of the file, as listed in files.' },
193
- },
194
- output: {
195
- schema: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', required: true }, text: { type: 'string', required: true } } },
196
- render: (_args, value) => [{ type: 'text', text: value.text }],
197
- },
198
- async execute(args) {
199
- const diffs = await getDiffs()
200
- const text = selectFileDiff(diffs, args.path)
201
- if (text === undefined) {
202
- throw new Error(`path not in this MR diff: ${args.path}`)
203
- }
204
- return { path: args.path, text }
205
- },
206
- }))
207
-
208
- ctx.tools.register(defineTool({
209
- name: 'gitlab_post_mr_comment',
210
- description: 'Post a Markdown comment (discussion note) on this merge request.',
211
- parameters: {
212
- body: { type: 'string', required: true, description: 'Markdown comment body.' },
213
- },
214
- output: {
215
- schema: { type: 'object', additionalProperties: false, properties: { posted: { type: 'boolean', required: true } } },
216
- render: () => [{ type: 'text', text: 'Comment posted.' }],
217
- },
218
- async execute(args) {
219
- const response = await fetch(`${apiBase}/notes`, {
220
- method: 'POST',
221
- headers: { ...headers, 'Content-Type': 'application/json' },
222
- body: JSON.stringify({ body: args.body }),
223
- })
224
- if (!response.ok) {
225
- throw new Error(`GitLab API error ${response.status}: ${await response.text()}`)
226
- }
227
- return { posted: true }
228
- },
229
- }))
230
-
231
- ctx.tools.register(defineTool({
232
- name: 'gitlab_list_own_review_threads',
233
- description: 'List this merge request\'s inline discussion threads previously created by this bot account (both unresolved and resolved, flagged), so you can reply instead of duplicating. Returns {threads, totalDiscussions}.',
234
- parameters: {},
235
- output: {
236
- schema: {
237
- type: 'object',
238
- additionalProperties: false,
239
- properties: {
240
- threads: {
241
- type: 'array',
242
- items: {
243
- type: 'object',
244
- additionalProperties: false,
245
- properties: {
246
- discussionId: { type: 'string', required: true },
247
- path: { type: 'string', required: true },
248
- line: { type: 'number' },
249
- lastCommentBody: { type: 'string', required: true },
250
- resolved: { type: 'boolean', required: true },
251
- },
252
- },
253
- },
254
- totalDiscussions: { type: 'number', required: true },
255
- },
256
- },
257
- render: (_args, value: { threads: OwnThread[]; totalDiscussions: number }) => [{
258
- type: 'text',
259
- text: `${value.totalDiscussions} discussion(s) on this MR, ${value.threads.length} own inline thread(s):\n${JSON.stringify(value.threads)}`,
260
- }],
261
- },
262
- async execute() {
263
- const response = await fetch(`${apiBase}/discussions`, { headers })
264
- if (!response.ok) {
265
- throw new Error(`GitLab API error ${response.status}: ${await response.text()}`)
266
- }
267
- const discussions = await response.json() as GitlabDiscussion[]
268
- return selectOwnThreads(discussions, config.botUsername)
269
- },
270
- }))
271
-
272
- ctx.tools.register(defineTool({
273
- name: 'gitlab_post_inline_comment',
274
- description: 'Create a new inline discussion at a specific file and line in this merge request\'s current diff.',
275
- parameters: {
276
- path: { type: 'string', required: true, description: 'File path on the new (target) side of the diff.' },
277
- line: { type: 'number', required: true, description: 'Line number on the new (target) side of the diff.' },
278
- body: { type: 'string', required: true, description: 'Markdown comment body.' },
279
- },
280
- output: {
281
- schema: { type: 'object', additionalProperties: false, properties: { posted: { type: 'boolean', required: true } } },
282
- render: () => [{ type: 'text', text: 'Inline comment posted.' }],
283
- },
284
- async execute(args) {
285
- const diffRefs = await getDiffRefs()
286
- const response = await fetch(`${apiBase}/discussions`, {
287
- method: 'POST',
288
- headers: { ...headers, 'Content-Type': 'application/json' },
289
- body: JSON.stringify({
290
- body: args.body,
291
- position: {
292
- position_type: 'text',
293
- base_sha: diffRefs.base_sha,
294
- start_sha: diffRefs.start_sha,
295
- head_sha: diffRefs.head_sha,
296
- old_path: args.path,
297
- new_path: args.path,
298
- new_line: args.line,
299
- },
300
- }),
301
- })
302
- if (!response.ok) {
303
- throw new Error(`GitLab API error ${response.status}: ${await response.text()}`)
304
- }
305
- return { posted: true }
306
- },
307
- }))
308
-
309
- ctx.tools.register(defineTool({
310
- name: 'gitlab_reply_to_thread',
311
- description: 'Reply to an existing inline discussion thread (discussionId from gitlab_list_own_review_threads) without resolving it.',
312
- parameters: {
313
- discussionId: { type: 'string', required: true },
314
- body: { type: 'string', required: true, description: 'Markdown reply body.' },
315
- },
316
- output: {
317
- schema: { type: 'object', additionalProperties: false, properties: { posted: { type: 'boolean', required: true } } },
318
- render: () => [{ type: 'text', text: 'Reply posted.' }],
319
- },
320
- async execute(args) {
321
- const response = await fetch(`${apiBase}/discussions/${args.discussionId}/notes`, {
322
- method: 'POST',
323
- headers: { ...headers, 'Content-Type': 'application/json' },
324
- body: JSON.stringify({ body: args.body }),
325
- })
326
- if (!response.ok) {
327
- throw new Error(`GitLab API error ${response.status}: ${await response.text()}`)
328
- }
329
- return { posted: true }
330
- },
331
- }))
332
- }