@ddtcorex/dsh-maestro-review 0.1.0

package/src/pin-store.ts

@@ -0,0 +1,4 @@
+export async function readPin(): Promise<string> { return '00000000' }
+export async function rotatePin(): Promise<string> { return '00000000' }
+export async function readLanPin(): Promise<string> { return '00000000' }
+export async function rotateLanPin(): Promise<string> { return '00000000' }

package/src/providers/github.stub.ts

@@ -0,0 +1,11 @@
+import type { ReviewProvider, ReviewRequest } from './interface.js'
+
+export const githubProvider: ReviewProvider = {
+  id: 'github',
+  async intake(_req: Request): Promise<ReviewRequest> {
+    throw new Error('github not implemented')
+  },
+  async postFindings(_findings: any[]): Promise<void> {
+    throw new Error('not implemented')
+  },
+}

package/src/providers/gitlab.ts

@@ -0,0 +1,190 @@
+import { createServer, type IncomingMessage } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { loadUserConfig } from '../config-store.js'
+import { secretsMatch } from '../secure-compare.js'
+import type { MrOpenedPayload, ReviewRequest as OrchestratorReviewRequest } from '../events.js'
+import { routeGitlabReviewRequest } from '../review-intake.js'
+import type { ReviewProvider, ReviewRequest } from './interface.js'
+
+export const name = 'maestro-review-webhook'
+
+export interface Config {
+  port: number
+  botUsername?: string
+  secret?: string
+}
+
+export const Config: z<Config> = z.object({
+  port: z.natural().max(65535).required(),
+  botUsername: z.string(),
+  secret: z.string().role('secret'),
+})
+
+interface GitlabMrWebhookBody {
+  object_kind: string
+  project: { id: number; path_with_namespace: string }
+  object_attributes: { iid: number; action: string; source_branch: string }
+}
+
+const MAX_WEBHOOK_BODY_BYTES = 5 * 1024 * 1024
+
+function readBody(req: IncomingMessage, limit = MAX_WEBHOOK_BODY_BYTES): Promise<string | undefined> {
+  return new Promise((resolvePromise) => {
+    let raw = ''
+    let settled = false
+    req.on('data', (chunk: Buffer) => {
+      if (settled) return
+      if (raw.length + chunk.length > limit) {
+        settled = true
+        req.resume()
+        resolvePromise(undefined)
+        return
+      }
+      raw += chunk.toString()
+    })
+    req.on('end', () => { if (!settled) { settled = true; resolvePromise(raw) } })
+    req.on('error', () => { if (!settled) { settled = true; resolvePromise(undefined) } })
+  })
+}
+
+function isValidMrOpenedPayload(value: unknown): value is MrOpenedPayload {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  return typeof v.projectPath === 'string'
+    && typeof v.projectId === 'number'
+    && typeof v.mrIid === 'number'
+    && typeof v.sourceBranch === 'string'
+}
+
+function hasValidGitlabMrIdentity(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null) return false
+  const body = value as Record<string, unknown>
+  const project = body.project as Record<string, unknown> | undefined
+  const attributes = body.object_attributes as Record<string, unknown> | undefined
+  const mergeRequest = body.merge_request as Record<string, unknown> | undefined
+  const source = body.object_kind === 'note' ? mergeRequest : attributes
+  return typeof project?.id === 'number' && typeof project.path_with_namespace === 'string'
+    && typeof source?.iid === 'number' && typeof source.source_branch === 'string'
+}
+
+// ReviewProvider implementation — pluggable interface for orchestrator
+export const gitlabProvider: ReviewProvider = {
+  id: 'gitlab',
+  async intake(req: Request): Promise<ReviewRequest> {
+    // Try to parse the request body as GitLab webhook JSON
+    let body: unknown
+    try {
+      body = await req.clone().json()
+    } catch {
+      // Fallback/STUB: return generic empty request (keeps interface working without GitLab)
+      return { provider: 'gitlab', projectPath: '', mrId: '', profile: 'generic' }
+    }
+    // If body looks like a GitLab MR webhook, map to ReviewRequest
+    if (typeof body === 'object' && body !== null) {
+      const b = body as Record<string, unknown>
+      const project = b.project as Record<string, unknown> | undefined
+      const attrs = b.object_attributes as Record<string, unknown> | undefined
+      const mr = b.merge_request as Record<string, unknown> | undefined
+      const source = b.object_kind === 'note' ? mr : attrs
+      const projectPath = typeof project?.path_with_namespace === 'string' ? project.path_with_namespace : ''
+      const mrId = typeof source?.iid === 'number' ? String(source.iid) : ''
+      if (projectPath && mrId) {
+        return { provider: 'gitlab', projectPath, mrId, profile: 'generic' }
+      }
+    }
+    // Fallback stub
+    return { provider: 'gitlab', projectPath: '', mrId: '', profile: 'generic' }
+  },
+  async postFindings(_findings: any[]): Promise<void> {
+    // Real posting is handled by orchestrator's GitLab API flow (postReviewFindings)
+    // Keep interface compliant — no-op here; orchestrator will call postReviewFindings separately
+  },
+}
+
+export function apply(ctx: Context, config: Config): void {
+  let warnedUnconfigured = false
+  async function requestAuthorized(headerValue: string | string[] | undefined): Promise<boolean> {
+    const userConfig = await loadUserConfig()
+    const expected = userConfig.webhookSecret ?? config.secret
+    if (expected === undefined) {
+      if (!warnedUnconfigured) {
+        warnedUnconfigured = true
+        console.error('maestro-review-webhook: no webhook secret configured — set one in Maestro Settings or MAESTRO_GITLAB_WEBHOOK_SECRET; rejecting all requests until then')
+      }
+      return false
+    }
+    return secretsMatch(headerValue, expected)
+  }
+
+  const server = createServer((req, res) => {
+    if (req.method !== 'POST') {
+      res.writeHead(404).end()
+      return
+    }
+    void requestAuthorized(req.headers['x-gitlab-token']).then(async (authorized) => {
+      if (!authorized) {
+        res.writeHead(401).end()
+        return
+      }
+      readBody(req).then(async (raw) => {
+        if (raw === undefined) {
+          res.writeHead(413).end()
+          return
+        }
+        if (req.url === '/hooks/gitlab-mr/trigger') {
+          let parsed: unknown
+          try {
+            parsed = JSON.parse(raw)
+          } catch {
+            res.writeHead(400).end()
+            return
+          }
+          if (!isValidMrOpenedPayload(parsed)) {
+            res.writeHead(400).end()
+            return
+          }
+          const request: OrchestratorReviewRequest = {
+            ...parsed,
+            trigger: 'mention',
+            mode: 'quick',
+            scope: { kind: 'mr' },
+          }
+          ctx.emit('maestro/review-request', request)
+          res.writeHead(200).end()
+          return
+        }
+
+        if (req.url !== '/hooks/gitlab-mr') {
+          res.writeHead(404).end()
+          return
+        }
+        let body: GitlabMrWebhookBody
+        try {
+          body = JSON.parse(raw)
+        } catch {
+          res.writeHead(400).end()
+          return
+        }
+        const userConfig = await loadUserConfig()
+        if ((body.object_kind === 'merge_request' || body.object_kind === 'note') && !hasValidGitlabMrIdentity(body)) {
+          res.writeHead(400).end()
+          return
+        }
+        const request = routeGitlabReviewRequest(
+          body,
+          userConfig.botUsername ?? config.botUsername ?? 'maestro',
+          { pushEnabled: userConfig.autoRereviewOnPush === true },
+        )
+        if (request !== undefined) ctx.emit('maestro/review-request', request)
+        res.writeHead(200).end()
+      })
+    })
+  })
+
+  server.listen(config.port)
+
+  ctx.effect(() => async () => {
+    await new Promise<void>((resolve) => { server.close(() => resolve()) })
+  }, 'gitlab-webhook teardown')
+}

package/src/providers/interface.ts

@@ -0,0 +1,2 @@
+export interface ReviewRequest { provider: string; projectPath: string; mrId: string; profile: 'magento2'|'generic'|'laravel'|'custom'; }
+export interface ReviewProvider { id: string; intake(req: Request): Promise<ReviewRequest>; postFindings(f: any[]): Promise<void>; }

package/src/review-findings-tool.ts

@@ -0,0 +1,51 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'maestro-review-findings-tool'
+export const inject = ['tools']
+
+export interface ReviewFinding {
+  status: 'new' | 'reply'
+  body: string
+  path?: string
+  line?: number
+  discussionId?: string
+}
+
+export interface Config {
+  onReport: (findings: ReviewFinding[]) => void
+}
+
+export function apply(ctx: Context, config: Config): void {
+  ctx.tools.register(defineTool({
+    name: 'report_review_findings',
+    description: 'Submit your complete list of review findings exactly once, when done analyzing. Each finding is {status: "new", path, line, body} for a location with no existing thread, or {status: "reply", discussionId, body} to update an existing thread returned by gitlab_list_own_review_threads.',
+    parameters: {
+      findings: {
+        type: 'array',
+        required: true,
+        description: 'The complete list of findings for this review.',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            status: { type: 'string', enum: ['new', 'reply'], required: true },
+            body: { type: 'string', required: true },
+            path: { type: 'string' },
+            line: { type: 'number' },
+            discussionId: { type: 'string' },
+          },
+        },
+      },
+    },
+    output: {
+      schema: { type: 'object', additionalProperties: false, properties: { received: { type: 'number', required: true } } },
+      render: (_args, value) => [{ type: 'text', text: `Recorded ${value.received} finding(s).` }],
+    },
+    async execute(args) {
+      const findings = args.findings as ReviewFinding[]
+      config.onReport(findings)
+      return { received: findings.length }
+    },
+  }))
+}

package/src/review-history.ts

@@ -0,0 +1,112 @@
+import { chmod, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import type { ReviewMode, ReviewRequest } from './events.js'
+
+export interface ReviewHistoryEntry {
+  id: string
+  projectId: number
+  projectPath: string
+  mrIid: number
+  mode: ReviewMode
+  scope: 'mr' | 'discussion'
+  trigger: ReviewRequest['trigger']
+  status: 'running' | 'completed' | 'failed'
+  startedAt: number
+  finishedAt?: number
+  summary?: string
+  error?: string
+}
+
+const HISTORY_CAP = 100
+
+export function historyPath(dshHome?: string): string {
+  const home = dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh')
+  return join(home, 'dsh-maestro-review', 'reviews.json')
+}
+
+
+async function readAll(dshHome?: string): Promise<ReviewHistoryEntry[]> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(historyPath(dshHome), 'utf-8'))
+    if (!Array.isArray(parsed)) return []
+    return parsed.filter((entry): entry is ReviewHistoryEntry =>
+      typeof entry === 'object' && entry !== null && typeof (entry as ReviewHistoryEntry).id === 'string')
+  } catch {
+    // Missing or corrupt store: start from an empty log rather than failing reviews.
+    return []
+  }
+}
+
+async function writeAll(entries: ReviewHistoryEntry[], dshHome?: string): Promise<void> {
+  const path = historyPath(dshHome)
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+  await writeFile(path, JSON.stringify(entries, null, 2), { encoding: 'utf-8', mode: 0o600 })
+  await chmod(path, 0o600)
+}
+
+/** Prepend a running entry; the oldest entries fall off past `HISTORY_CAP`. */
+export async function recordReviewStart(entry: Omit<ReviewHistoryEntry, 'status'>, dshHome?: string): Promise<void> {
+  const all = await readAll(dshHome)
+  all.unshift({ ...entry, status: 'running' })
+  await writeAll(all.slice(0, HISTORY_CAP), dshHome)
+}
+
+/** Attach an outcome to the entry with this id; unknown ids are ignored. */
+export async function recordReviewFinish(
+  id: string,
+  patch: { status: 'completed' | 'failed'; summary?: string; error?: string },
+  dshHome?: string,
+): Promise<void> {
+  const all = await readAll(dshHome)
+  const entry = all.find((candidate) => candidate.id === id)
+  if (entry === undefined) return
+  Object.assign(entry, patch, { finishedAt: Date.now() })
+  await writeAll(all, dshHome)
+}
+
+/** Newest-first slice of the log. */
+export async function listReviews(limit = 20, dshHome?: string): Promise<ReviewHistoryEntry[]> {
+  return (await readAll(dshHome)).slice(0, limit)
+}
+
+/** Whether any review of this MR ever completed — gates push re-reviews. */
+export async function hasCompletedReview(projectId: number, mrIid: number, dshHome?: string): Promise<boolean> {
+  return (await readAll(dshHome)).some(entry =>
+    entry.projectId === projectId && entry.mrIid === mrIid && entry.status === 'completed')
+}
+
+/**
+ * Drop history entries and failed-report files older than `retentionDays`.
+ * `0` disables pruning entirely. Maestro records only — DSH session
+ * transcripts are never touched.
+ */
+export async function pruneHistory(retentionDays: number, dshHome?: string): Promise<void> {
+  if (!Number.isFinite(retentionDays) || retentionDays <= 0) return
+  const cutoff = Date.now() - retentionDays * DAY_MS
+  const kept: ReviewHistoryEntry[] = []
+  for (const entry of await readAll(dshHome)) {
+    if ((entry.finishedAt ?? entry.startedAt) < cutoff) continue
+    kept.push(entry)
+  }
+  await writeAll(kept, dshHome)
+
+  const home = dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh')
+  const failedDir = join(home, 'maestro', 'failed-reports')
+  let names: string[]
+  try {
+    names = await readdir(failedDir)
+  } catch {
+    return
+  }
+  await Promise.all(names.map(async (name) => {
+    // Failed reports are named `<mrIid>-<epoch-ms>.md`.
+    const match = /^-?\d+-(\d{13,})\.md$/.exec(name)
+    if (match === null) return
+    const stamp = Number(match[1])
+    if (!Number.isFinite(stamp) || stamp >= cutoff) return
+    await rm(join(failedDir, name), { force: true }).catch(() => {})
+  }))
+}
+
+const DAY_MS = 24 * 60 * 60_000

package/src/review-intake.ts

@@ -0,0 +1,86 @@
+import type { MrOpenedPayload, ReviewMode, ReviewRequest, ReviewScope } from './events.js'
+
+type JsonRecord = Record<string, unknown>
+
+function record(value: unknown): JsonRecord | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as JsonRecord : undefined
+}
+
+function mrPayload(body: JsonRecord): MrOpenedPayload | undefined {
+  const project = record(body.project)
+  const attributes = record(body.object_attributes)
+  const mergeRequest = record(body.merge_request)
+  const source = body.object_kind === 'note' ? mergeRequest : attributes
+  if (project === undefined || source === undefined
+    || typeof project.id !== 'number' || typeof project.path_with_namespace !== 'string'
+    || typeof source.iid !== 'number' || typeof source.source_branch !== 'string') return undefined
+  return {
+    projectId: project.id,
+    projectPath: project.path_with_namespace,
+    mrIid: source.iid,
+    sourceBranch: source.source_branch,
+  }
+}
+
+function usernames(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((reviewer) => {
+    const item = record(reviewer)
+    return item !== undefined && typeof item.username === 'string' ? [item.username.toLowerCase()] : []
+  })
+}
+
+function isMentioned(text: string, botUsername: string): boolean {
+  const escaped = botUsername.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`(^|[^A-Za-z0-9_.-])@${escaped}(?=$|[^A-Za-z0-9_.-])`, 'i').test(text)
+}
+
+function noteScope(attributes: JsonRecord): ReviewScope | undefined {
+  const position = record(attributes.position)
+  if (position === undefined) return { kind: 'mr' }
+  const path = typeof position.new_path === 'string' ? position.new_path : position.old_path
+  const line = typeof position.new_line === 'number' ? position.new_line : position.old_line
+  if (typeof attributes.discussion_id !== 'string' || typeof path !== 'string' || typeof line !== 'number') return undefined
+  return { kind: 'discussion', discussionId: attributes.discussion_id, path, line }
+}
+
+export interface RouteOptions {
+  /** When true, an MR update carrying new commits routes a push re-review. */
+  pushEnabled?: boolean
+}
+
+export function routeGitlabReviewRequest(body: unknown, botUsername: string, options: RouteOptions = {}): ReviewRequest | undefined {
+  const value = record(body)
+  if (value === undefined || botUsername.trim() === '') return undefined
+  const payload = mrPayload(value)
+  if (payload === undefined) return undefined
+  const attributes = record(value.object_attributes)
+  if (attributes === undefined) return undefined
+
+  if (value.object_kind === 'merge_request') {
+    const changes = record(value.changes)
+
+    // New commits landed on an already-assigned MR: a quick re-review, gated
+    // downstream on a previously completed review of the same MR.
+    if (options.pushEnabled === true) {
+      const hasNewCommits = typeof attributes.oldrev === 'string' && attributes.oldrev !== ''
+      if (hasNewCommits) {
+        return { ...payload, trigger: 'push', mode: 'quick', scope: { kind: 'mr' } }
+      }
+    }
+
+    const reviewerChange = changes === undefined ? undefined : record(changes.reviewers)
+    if (reviewerChange === undefined) return undefined
+    const bot = botUsername.toLowerCase()
+    const nowAssigned = usernames(reviewerChange.current).includes(bot)
+    const previouslyAssigned = usernames(reviewerChange.previous).includes(bot)
+    if (!nowAssigned || previouslyAssigned) return undefined
+    return { ...payload, trigger: 'reviewer-assignment', mode: 'quick', scope: { kind: 'mr' } }
+  }
+
+  if (value.object_kind !== 'note' || typeof attributes.note !== 'string' || !isMentioned(attributes.note, botUsername)) return undefined
+  const scope = noteScope(attributes)
+  if (scope === undefined) return undefined
+  const mode: ReviewMode = /(?:^|\s)\/maestro\s+deep(?:\s|$)/i.test(attributes.note) ? 'deep' : 'quick'
+  return { ...payload, trigger: 'mention', mode, scope }
+}

package/src/review-signals.ts

@@ -0,0 +1,52 @@
+/**
+ * MR award-emoji acknowledgements: the MR shows "eyes" while a review runs and
+ * a final marker when it completes or fails. Signalling is best-effort — any
+ * GitLab error is swallowed so it can never fail the review itself.
+ */
+
+export interface ReviewSignals {
+  start(): Promise<void>
+  finish(outcome: 'completed' | 'failed'): Promise<void>
+}
+
+async function award(baseUrl: string, token: string, projectId: number, mrIid: number, name: string): Promise<void> {
+  await fetch(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji`, {
+    method: 'POST',
+    headers: { 'PRIVATE-TOKEN': token, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name }),
+  })
+}
+
+/** Remove only this bot's stale running markers; other users' awards stay untouched. */
+async function unawardOwn(baseUrl: string, token: string, projectId: number, mrIid: number, botUsername: string): Promise<void> {
+  const response = await fetch(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji`, {
+    headers: { 'PRIVATE-TOKEN': token },
+  })
+  if (!response.ok) return
+  const awards = (await response.json()) as Array<{ id?: number; name?: string; user?: { username?: string } }>
+  for (const awardItem of Array.isArray(awards) ? awards : []) {
+    if (awardItem.name !== 'eyes' || awardItem.user?.username !== botUsername || typeof awardItem.id !== 'number') continue
+    await fetch(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji/${awardItem.id}`, {
+      method: 'DELETE',
+      headers: { 'PRIVATE-TOKEN': token },
+    }).catch(() => {})
+  }
+}
+
+export function createReviewSignals(options: { baseUrl: string; token: string; projectId: number; mrIid: number; botUsername: string }): ReviewSignals {
+  const { baseUrl, token, projectId, mrIid, botUsername } = options
+  return {
+    async start() {
+      try {
+        await unawardOwn(baseUrl, token, projectId, mrIid, botUsername)
+        await award(baseUrl, token, projectId, mrIid, 'eyes')
+      } catch { /* signalling must never break the review */ }
+    },
+    async finish(outcome) {
+      try {
+        await unawardOwn(baseUrl, token, projectId, mrIid, botUsername)
+        await award(baseUrl, token, projectId, mrIid, outcome === 'completed' ? 'white_check_mark' : 'warning')
+      } catch { /* signalling must never break the review */ }
+    },
+  }
+}

package/src/secure-compare.ts

@@ -0,0 +1,13 @@
+import { createHash, timingSafeEqual } from 'node:crypto'
+
+/**
+ * Constant-time comparison of two secrets through sha256 digests, so differing
+ * lengths leak nothing and `timingSafeEqual`'s equal-length requirement is
+ * always met. Fails closed when either side is missing.
+ */
+export function secretsMatch(provided: string | string[] | undefined, expected: string | undefined): boolean {
+  if (provided === undefined || expected === undefined || expected === '') return false
+  const providedDigest = createHash('sha256').update(Array.isArray(provided) ? provided[0] ?? '' : provided).digest()
+  const expectedDigest = createHash('sha256').update(expected).digest()
+  return timingSafeEqual(providedDigest, expectedDigest)
+}