@ddtcorex/dsh-maestro-review 0.4.0 → 0.5.0

package/src/host/review-marker.ts

@@ -0,0 +1,25 @@
+/**
+ * Machine-readable review comment identity (spec: coexistence §4-5).
+ *
+ * Every posted review comment (webhook + CI, quick + deep) ends with an
+ * invisible marker so the CI flow can detect "this head SHA already has a
+ * completed review" without access to the webhook's history store.
+ */
+
+export type ReviewFlow = 'ci-quick' | 'ci-deep' | 'webhook'
+
+export function reviewMarker(sha: string, flow: ReviewFlow): string {
+  return `<!-- maestro-review sha=${sha} flow=${flow} status=completed -->`
+}
+
+export function parseReviewMarker(body: string): { sha: string; flow: string; status: string } | undefined {
+  const m = /<!-- maestro-review sha=([0-9a-fA-F]+) flow=([a-z-]+) status=([a-z]+) -->/.exec(body)
+  if (!m) return undefined
+  return { sha: m[1], flow: m[2], status: m[3] }
+}
+
+/** CI detection is env-based (established pattern): the reviewer job always sets these. */
+export function resolveFlow(mode: 'quick' | 'deep'): ReviewFlow {
+  if (process.env.SOURCE_PROJECT_ID === undefined) return 'webhook'
+  return mode === 'deep' ? 'ci-deep' : 'ci-quick'
+}

package/src/host/review-signals.ts

@@ -1,3 +1,4 @@
+import { gitlabAuthHeaders } from './gitlab-auth.js'
 /**
  * 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
@@ -12,7 +13,7 @@ export interface ReviewSignals {
 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' },
+    headers: { ...gitlabAuthHeaders(token), 'Content-Type': 'application/json' },
     body: JSON.stringify({ name }),
   })
 }
@@ -20,7 +21,7 @@ async function award(baseUrl: string, token: string, projectId: number, mrIid: n
 /** 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 },
+    headers: gitlabAuthHeaders(token),
   })
   if (!response.ok) return
   const awards = (await response.json()) as Array<{ id?: number; name?: string; user?: { username?: string } }>
@@ -28,7 +29,7 @@ async function unawardOwn(baseUrl: string, token: string, projectId: number, mrI
     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 },
+      headers: gitlabAuthHeaders(token),
     }).catch(() => {})
   }
 }

package/src/host/settings-rpc.ts

@@ -12,7 +12,7 @@ export const inject = ['connection', 'maestroTunnel']
 /** Keys the Settings card may persist; anything else is a rejected save. */
 const SAVABLE_KEYS = new Set<keyof MaestroUserConfig>([
   'gitlabBaseUrl', 'gitlabToken', 'botUsername', 'webhookSecret', 'webhookPort',
-  'projectMappings', 'reviewModel', 'autoRereviewOnPush', 'agentTimeoutMs', 'reviewSessionRetentionDays',
+  'projectMappings', 'reviewModel', 'autoRereviewOnPush', 'autoReviewOnAssign', 'agentTimeoutMs', 'reviewSessionRetentionDays',
   'tunnelMode', 'quickTarget', 'tunnelId', 'tunnelCredentialsFile', 'tunnelHostname',
   'proxyPort', 'proxyHost', 'lanPinEnabled', 'telegramBotToken', 'telegramChatId',
   'telegramReviewNotifications',

package/templates/reviewer-project.gitlab-ci.yml

@@ -0,0 +1,90 @@
+# ddtcorex/maestro-reviewer — dedicated reviewer project
+stages: [review]
+
+variables:
+  # Image registry — pin the SHA for reproducibility
+  REVIEWER_IMAGE: "ddtcorex/maestro-reviewer:latest"
+  # Or use $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA when building the image in the same project
+
+review:
+  stage: review
+  image: $REVIEWER_IMAGE
+  # Only runs when triggered from the source project (or manually)
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "pipeline"          # bridge trigger
+    - if: $CI_PIPELINE_SOURCE == "trigger"           # token trigger
+    - if: $CI_PIPELINE_SOURCE == "web"               # manual retry
+      when: manual
+  variables:
+    GIT_STRATEGY: none   # no need to check out the reviewer repo
+  # Every parameter comes from env (SOURCE_PROJECT_ID, MR_IID, GITLAB_HOST, REVIEW_MODE) — no CLI args.
+  script:
+    - /entrypoint.sh
+  # History cache — the push-gate (skip already-reviewed head SHAs) and incremental
+  # context read $DSH_HOME/dsh-maestro-review/reviews.json, which is ephemeral in a
+  # fresh container. entrypoint.sh symlinks it at this cached path (one store, many
+  # MRs — entries are keyed per MR inside). Cache miss fails open toward reviewing.
+  cache:
+    key: maestro-review-history
+    paths:
+      - .maestro-history/
+  artifacts:
+    when: always
+    expire_in: 1 week
+    paths:
+      - review-report.json
+      - review-report.md
+  # Secrets — Protected + Masked, only available on the reviewer project's protected branches.
+  # MAESTRO_GITLAB_TOKEN is REQUIRED and must be a user PAT or Group/Project
+  # Access Token (api scope). CI_JOB_TOKEN is NOT enough: proven 2026-09-04 on
+  # GitLab 18.11 that reads work (GET=200) but posting the review comment fails
+  # (POST /notes=401) even with the source project allowlisting this reviewer —
+  # the run would "complete" without ever posting. A human-tied PAT needs yearly
+  # rotation; prefer a bot/group token where the instance allows creating one.
+  # MAESTRO_GITLAB_TOKEN (api scope) — required
+  # Route selection is key-based (entrypoint.sh swaps the baked settings variant):
+  # OPENCODE_GO_API_KEY → opencode profile (default, host mirror; serves opencode-go
+  #   AND deepseek-official-via-zen). Set alone, or with DEEPSEEK_API_KEY (opencode wins).
+  # DEEPSEEK_API_KEY → deepseek profile ONLY when OPENCODE_GO_API_KEY is absent
+  #   (deepseek-official straight from api.deepseek.com — needs a LIVE deepseek.com key).
+  # TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID (optional)
+  # Opencode model (optional, one variable — default muse-spark-1.3-contributor):
+  # OPENCODE_MODEL: "muse-spark-1.3-contributor"
+  # Model pin (optional, as a pair — unset both for the host-mirrored default
+  #   = opencode-go/muse-spark-1.3-contributor, baked in docker/ci-settings.yaml):
+  # REVIEW_MODEL_PROVIDER: "opencode-go"             # or "deepseek-official"
+  # REVIEW_MODEL: "muse-spark-1.3-contributor"       # e.g. deepseek-v4-flash (deepseek-official via zen)
+  #   Only the provider's key is needed — no settings mount required. ID without
+  #   provider fails the review with a provider error (not silently the wrong
+  #   model); provider without ID is ignored.
+  # Review skill profile (optional — unset for the legacy diff-only generic review):
+  # REVIEW_PROFILE: "magento2"                       # magento2 | laravel | symfony | wordpress | generic
+  #   The reviewer must load the full skill set or the review fails closed
+  #   (no half-skilled review). Runtime-backed checks still degrade without a
+  #   checkout — the profile adds framework checklists, not a govard run.
+  # Review mode (default quick; deep runs on demand — no new variables):
+  # REVIEW_MODE: "deep"                              # manual downstream run with the same
+  #   bridge variables (SOURCE_PROJECT_ID, MR_IID, GITLAB_HOST) + REVIEW_ON_PUSH=1
+  #   to re-review pushes. The job clones the source at the MR head SHA with
+  #   MAESTRO_GITLAB_TOKEN (api scope, oauth2) and runs reviewer (+auditor
+  #   degraded to reviewer-only without a runtime). No govard in the container.
+  #   CI yields to webhook: if the head SHA already has a completed review
+  #   comment (either flow), the run skips instead of double-posting.
+  # Re-review pushes (optional — mirrors Settings UI autoRereviewOnPush, default off):
+  # REVIEW_ON_PUSH: "1"                              # re-review new pushes with incremental context;
+  #   unset = only the first (opened) review runs; same head SHA always skips.
+
+# Build the image inside the same reviewer project (optional):
+#
+# build:image:
+#   stage: .pre
+#   image: docker:27
+#   services: [docker:27-dind]
+#   rules:
+#     - if: $CI_COMMIT_BRANCH == "main"
+#   script:
+#     - docker build -f packages/dsh-maestro-review/docker/Dockerfile -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA -t $CI_REGISTRY_IMAGE:latest .
+#     - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+#     - docker push $CI_REGISTRY_IMAGE:latest
+#   # Build context must be the maestro-harness workspace root (contains deepseek-harness/) —
+#   # the trailing "." above assumes this job checks out maestro-harness, not this repo alone.

package/templates/source-project.gitlab-ci.yml

@@ -0,0 +1,42 @@
+# example-group/example-project — source project (copy this template into YOUR source project)
+stages: [review]
+
+# Only runs when there is an MR (fork MRs run fine too — this job has no secrets)
+maestro:trigger-review:
+  stage: review
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  # No image needed, no secrets needed
+  trigger:
+    project: ddtcorex/maestro-reviewer   # ← reviewer project path
+    branch: main                          # ← the reviewer project's default branch (master on some instances)
+    strategy: depend                      # optional: wait for the reviewer pipeline, surface its status on the MR
+  variables:
+    SOURCE_PROJECT_ID: $CI_PROJECT_ID
+    MR_IID: $CI_MERGE_REQUEST_IID
+    GITLAB_HOST: $CI_SERVER_HOST
+    SOURCE_SHA: $CI_COMMIT_SHA
+    REVIEW_MODE: "quick"                 # or "deep" for a govard audit
+    REVIEW_PROFILE: "generic"            # per-project skill profile: magento2 | laravel | symfony | wordpress | generic
+    # REVIEW_ON_PUSH: "1"               # uncomment to re-review every push (default: only the opened review runs)
+
+# Trigger Token fallback (when not using `trigger: project:`):
+#
+# maestro:trigger-review:token:
+#   stage: review
+#   rules:
+#     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+#   image: curlimages/curl:8
+#   variables:
+#     REVIEWER_PROJECT_ID: "123"  # id of the maestro-reviewer project
+#   script:
+#     - |
+#       curl --fail --request POST \
+#         --form token=$MAESTRO_TRIGGER_TOKEN \
+#         --form ref=main \
+#         --form variables[SOURCE_PROJECT_ID]=$CI_PROJECT_ID \
+#         --form variables[MR_IID]=$CI_MERGE_REQUEST_IID \
+#         --form variables[GITLAB_HOST]=$CI_SERVER_HOST \
+#         "https://${CI_SERVER_HOST}/api/v4/projects/${REVIEWER_PROJECT_ID}/trigger/pipeline"
+#   # MAESTRO_TRIGGER_TOKEN is the reviewer project's Trigger Token, stored in the source project
+#   # (can only trigger, never read/write code — safer than GITLAB_TOKEN)