@ddtcorex/dsh-maestro-review 0.1.0 → 0.1.1

package/src/govard-audit-lint-tool.ts

@@ -0,0 +1,147 @@
+import { spawn } from 'node:child_process'
+import { basename, dirname, resolve, sep } from 'node:path'
+import { realpath } from 'node:fs/promises'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name='maestro-govard-audit-lint-tool'
+export const inject=['tools']
+export const Config:z<{rootPath?:string, timeoutMs?:number}> = z.object({rootPath:z.string(), timeoutMs:z.number()})
+
+interface SC{agent?:{session?:{header?:{cwd?:string}}}}
+function workspaceRootFor(c:string|undefined, e:unknown):string{
+  if(c!==undefined) return c
+  const cwd=(e as SC|undefined)?.agent?.session?.header?.cwd
+  return typeof cwd==='string'&&cwd!==''?cwd:process.cwd()
+}
+async function isInsideRoot(r:string,t:string):Promise<boolean>{
+  const ar=resolve(r); const rs=resolve(ar,t)
+  if(rs!==ar && !rs.startsWith(ar+sep)) return false
+  let realRoot:string
+  try{ realRoot=await realpath(ar)}catch{ return true }
+  let existing=rs
+  const pending:string[]=[]
+  while(true){
+    let real:string
+    try{ real=await realpath(existing)}catch(err){
+      if((err as NodeJS.ErrnoException).code!=='ENOENT') return false
+      const parent=dirname(existing)
+      if(parent===existing) return false
+      pending.unshift(basename(existing))
+      existing=parent
+      continue
+    }
+    const realTarget=pending.length>0? resolve(real,...pending):real
+    if(realTarget!==realRoot && !realTarget.startsWith(realRoot+sep)) return false
+    return true
+  }
+}
+export function cleanJson(raw:string):string{
+  return raw.replace(/\n\s*ERROR audit run.*$/s, '').replace(/\s{2,}ERROR audit run.*$/s, '').trimEnd()
+}
+const DEFAULT_TIMEOUT=120000
+
+function run(cmd:string, args:string[], cwd:string, timeoutMs:number):Promise<{code:number|null, stdout:string, stderr:string, timedOut:boolean}>{
+  return new Promise((resolvePromise)=>{
+    const child=spawn(cmd, args, {cwd})
+    let stdout='', stderr=''
+    let timedOut=false
+    const timer=setTimeout(()=>{ timedOut=true; child.kill('SIGKILL') }, timeoutMs)
+    child.stdout?.on('data',(c:Buffer)=> stdout+=c.toString())
+    child.stderr?.on('data',(c:Buffer)=> stderr+=c.toString())
+    child.on('error',(err:Error)=>{ clearTimeout(timer); resolvePromise({code:null, stdout, stderr: err.message, timedOut:false}) })
+    child.on('close',(code)=>{ clearTimeout(timer); resolvePromise({code, stdout, stderr, timedOut}) })
+  })
+}
+
+export function apply(ctx:Context, config:{rootPath?:string, timeoutMs?:number}={}):void{
+  const configuredRoot=config.rootPath
+  const defaultTimeout=config.timeoutMs ?? DEFAULT_TIMEOUT
+  ctx.effect(()=>ctx.tools.register(defineTool({
+    name:'govard_audit_lint',
+    description:'Run govard audit --checks lint --format json and return structured phpcs/phpstan results. Use before hand-parsing text.',
+    parameters:{
+      worktreePath:{type:'string'},
+      checks:{type:'array', items:{type:'string'}},
+      mode:{type:'string', enum:['auto','project','module_in_project','standalone']},
+      phpVersions:{type:'array', items:{type:'string'}},
+      noLintResultCache:{type:'boolean'},
+      timeoutMs:{type:'number'},
+    },
+    output:{
+      schema:{
+        type:'object', additionalProperties:false,
+        properties:{
+          ok:{type:'boolean', required:true},
+          exitCode:{type:'number', required:true},
+          timedOut:{type:'boolean', required:true},
+          worktreePath:{type:'string', required:true},
+          lint:{type:'object', required:true, additionalProperties:true},
+          summary:{type:'object', required:true, additionalProperties:true},
+          rawJson:{type:'object', required:true, additionalProperties:true},
+        }
+      },
+      render:(_a,v:{ok:boolean})=>[{type:'text', text: v.ok? 'audit lint passed':'audit lint failed'}],
+    },
+    async execute(args, exec){
+      const rawPath=(args as {worktreePath?:string}).worktreePath
+      const root=workspaceRootFor(configuredRoot, exec)
+      const worktreePath= rawPath ? resolve(root, rawPath) : root
+      const checkPath= rawPath ?? ''
+      if(checkPath!=='' && !(await isInsideRoot(root, checkPath))) return {text:`Path "${checkPath}" escapes the workspace root.`, truncated:false} as never
+      const timeoutMs=(args as {timeoutMs?:number}).timeoutMs ?? defaultTimeout
+      if(timeoutMs<5000 || timeoutMs>300000) return {text:'timeoutMs out of range 5000-300000', truncated:false} as never
+
+      const cliArgs=['audit','run','--checks','lint','--format','json']
+      const result=await run('govard', cliArgs, worktreePath, timeoutMs)
+      if(result.timedOut){
+        return {ok:false, exitCode:result.code, timedOut:true, worktreePath, lint:{phpcs:{violations:[]}, phpstan:{errors:[]}, pubMediaGuard:{violations:[]}}, summary:{status:null, phpVersions:[], matrixComplete:false, findingCount:0, truncated:false}, rawJson:null, errors:[{code:'timeout', message:`timed out after ${timeoutMs}ms` }], diagnostics:result.stderr.slice(0,4000)} as never
+      }
+      if(result.code===null && result.stderr.includes('ENOENT')){
+        return {ok:false, exitCode:null, timedOut:false, worktreePath, lint:{phpcs:{violations:[]}, phpstan:{errors:[]}, pubMediaGuard:{violations:[]}}, summary:{status:null, phpVersions:[], matrixComplete:false, findingCount:0, truncated:false}, rawJson:null, errors:[{code:'govard_not_found', message:'govard binary not found'}], diagnostics:result.stderr.slice(0,4000)} as never
+      }
+      const cleaned=cleanJson(result.stdout)
+      let parsed:any=null
+      try{ parsed=JSON.parse(cleaned) }catch{ parsed=null }
+      if(!parsed){
+        const fallback=cleaned.split('\n').slice(0,-1).join('\n').trimEnd()
+        try{ parsed=JSON.parse(fallback)}catch{}
+        if(!parsed){
+          const tryStderr=cleanJson(result.stdout+result.stderr)
+          try{ parsed=JSON.parse(tryStderr)}catch{}
+        }
+      }
+      if(!parsed){
+        return {ok:false, exitCode:result.code, timedOut:false, worktreePath, lint:{phpcs:{violations:[]}, phpstan:{errors:[]}, pubMediaGuard:{violations:[]}}, summary:{status:null, phpVersions:[], matrixComplete:false, findingCount:0, truncated:false}, rawJson:null, errors:[{code:'parse_error', message:'stdout not JSON'}], diagnostics:(cleaned+result.stderr).slice(0,4000)} as never
+      }
+      const findings:Array<any>=parsed.findings ?? parsed.evidence?.php_results?.flatMap((r:any)=>r.findings) ?? []
+      const phpcsViolations:any[]=[]
+      const phpstanErrors:any[]=[]
+      const pubMediaViolations:any[]=[]
+      for(const f of findings){
+        if(f.tool==='phpstan') phpstanErrors.push({path:f.path, line:f.line, message:f.message})
+        else if(f.tool==='phpcs'){
+          if(f.path?.includes('pub/media') || f.rule?.includes('PubMedia')) pubMediaViolations.push(f)
+          else phpcsViolations.push({path:f.path, line:f.line, column:f.column, rule:f.rule, message:f.message, severity:f.severity})
+        }
+      }
+      const status=parsed.status ?? (result.code===0?'passed':'failed')
+      const phpVersions=parsed.php_versions ?? parsed.phpVersions ?? []
+      const findingCount=findings.length
+      return {
+        ok: result.code===0,
+        exitCode: result.code,
+        timedOut:false,
+        worktreePath,
+        sessionId: parsed.session_id ?? parsed.sessionId ?? null,
+        runId: parsed.run_id ?? parsed.runId ?? null,
+        rawJson: parsed,
+        summary:{status, phpVersions, matrixComplete:true, findingCount, truncated: findingCount>100},
+        lint:{phpcs:{violations:phpcsViolations}, phpstan:{errors:phpstanErrors}, pubMediaGuard:{violations:pubMediaViolations}},
+        errors:[],
+        diagnostics: result.stderr.slice(0,4000) || null,
+      } as never
+    }
+  })))
+}

package/src/hyva-csp-scan-tool.ts

@@ -0,0 +1,165 @@
+import { join, resolve, sep, basename } from 'node:path'
+import { readFile, readdir, realpath, stat } from 'node:fs/promises'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'maestro-hyva-csp-scan-tool'
+export const inject = ['tools']
+export const Config: z<{ rootPath?: string }> = z.object({ rootPath: z.string() })
+
+interface SessionCwdSource { agent?: { session?: { header?: { cwd?: string } } } }
+function workspaceRootFor(configuredRoot: string | undefined, exec: unknown): string {
+  if (configuredRoot !== undefined) return configuredRoot
+  const cwd = (exec as SessionCwdSource | undefined)?.agent?.session?.header?.cwd
+  return typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd()
+}
+async function isInsideRoot(rootPath: string, target: string): Promise<boolean> {
+  const absoluteRoot = resolve(rootPath)
+  const resolved = resolve(absoluteRoot, target)
+  if (resolved !== absoluteRoot && !resolved.startsWith(absoluteRoot + sep)) return false
+  try {
+    const realRoot = await realpath(absoluteRoot)
+    const realTarget = await realpath(resolved)
+    return realTarget === realRoot || realTarget.startsWith(realRoot + sep)
+  } catch { return false }
+}
+const MAX_FILE_BYTES = 1024 * 1024
+const MAX_FILES_DEFAULT = 200
+const MAX_ISSUES = 100
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'vendor', 'pub/static'])
+const PHTML_RE = /\.phtml$/
+const SCRIPT_RE = /<script(?![^>]*\ssrc=)[^>]*>([\s\S]*?)<\/script>/gi
+const HYVA_CSP_RE = /\$hyvaCsp\s*->\s*registerInlineScript\s*\(/
+const DIRECTIVE_RE = /\s(@click|x-show|x-model|:value|@input|:class|x-text|x-if|x-for|@change)\s*=\s*"([^"]*)"/g
+const DOT_PATH_RE = /^[a-zA-Z_$][\w$]*(\.[a-zA-Z_$][\w$]*)*(\([^)]*\))?$/
+
+async function* walkPhtml(dir: string, base: string, budget: { files: number }): AsyncGenerator<string> {
+  if (budget.files <= 0) return
+  let entries
+  try { entries = await readdir(dir, { withFileTypes: true }) } catch { return }
+  for (const entry of entries) {
+    if (budget.files <= 0) return
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue
+      yield* walkPhtml(join(dir, entry.name), base, budget)
+      continue
+    }
+    if (!entry.isFile()) continue
+    if (!PHTML_RE.test(entry.name)) continue
+    budget.files -= 1
+    yield join(dir, entry.name)
+  }
+}
+function lineOf(text: string, idx: number): number { return text.slice(0, idx).split('\n').length }
+
+export function apply(ctx: Context, config: { rootPath?: string } = {}): void {
+  const configuredRoot = config.rootPath
+  ctx.effect(() => ctx.tools.register(defineTool({
+    name: 'hyva_csp_scan',
+    description: 'Scan .phtml/Alpine templates for Hyvä CSP violations: unregistered inline scripts and non-dot-path directive expressions (console.warn-only at runtime, so static review is the gate).',
+    parameters: {
+      scope: { type: 'string', enum: ['diff', 'paths', 'dir'], required: true },
+      paths: { type: 'array', items: { type: 'string' } },
+      dir: { type: 'string' },
+      cspBuild: { type: 'boolean' },
+      maxFiles: { type: 'number' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          issues: { type: 'array', required: true },
+          scannedFiles: { type: 'number', required: true },
+          clean: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, v: { clean: boolean; scannedFiles: number; issues: unknown[] }) => [{ type: 'text', text: v.clean ? `CSP clean — ${v.scannedFiles} files scanned.` : `${(v.issues as unknown[]).length} CSP issue(s) in ${v.scannedFiles} files` }],
+    },
+    async execute(args, exec) {
+      const root = workspaceRootFor(configuredRoot, exec)
+      const scope = (args as { scope: string }).scope
+      const cspBuild = (args as { cspBuild?: boolean }).cspBuild ?? false
+      const maxFiles = (args as { maxFiles?: number }).maxFiles ?? MAX_FILES_DEFAULT
+
+      let files: string[] = []
+      if (scope === 'paths') {
+        const paths = (args as { paths?: string[] }).paths ?? []
+        for (const p of paths) {
+          if (!(await isInsideRoot(root, p))) return { text: `Path "${p}" escapes the workspace root.`, truncated: false } as never
+          const abs = resolve(root, p)
+          try { const s = await stat(abs); if (s.isFile() && PHTML_RE.test(p)) files.push(p) } catch {}
+        }
+      } else if (scope === 'dir') {
+        const dirArg = (args as { dir?: string }).dir
+        const base = dirArg ? resolve(root, dirArg) : root
+        if (dirArg && !(await isInsideRoot(root, dirArg))) return { text: `Path "${dirArg}" escapes the workspace root.`, truncated: false } as never
+        const budget = { files: maxFiles }
+        for await (const f of walkPhtml(base, root, budget)) {
+          const rel = f.startsWith(root + sep) ? f.slice(root.length + 1) : basename(f)
+          files.push(rel)
+          if (files.length >= maxFiles) break
+        }
+      } else {
+        // diff fallback: walk all phtml
+        const budget = { files: maxFiles }
+        for await (const f of walkPhtml(root, root, budget)) {
+          const rel = f.startsWith(root + sep) ? f.slice(root.length + 1) : basename(f)
+          files.push(rel)
+          if (files.length >= maxFiles) break
+        }
+      }
+
+      const issues: Array<{ file: string; line: number; type: string; directive: string | null; snippet: string }> = []
+      let scannedFiles = 0
+      for (const rel of files.slice(0, maxFiles)) {
+        if (issues.length >= MAX_ISSUES) break
+        const abs = resolve(root, rel)
+        let text: string
+        try {
+          const buf = await readFile(abs)
+          if (buf.byteLength > MAX_FILE_BYTES) continue
+          text = buf.toString('utf-8')
+        } catch { continue }
+        scannedFiles++
+        const hasRegister = HYVA_CSP_RE.test(text)
+        // reset regex lastIndex
+        SCRIPT_RE.lastIndex = 0
+        let m: RegExpExecArray | null
+        while ((m = SCRIPT_RE.exec(text)) !== null) {
+          if (!hasRegister) {
+            const line = lineOf(text, m.index)
+            issues.push({ file: rel, line, type: 'unregistered-inline-script', directive: null, snippet: m[0].slice(0, 240).replace(/\s+/g, ' ') })
+            if (issues.length >= MAX_ISSUES) break
+          }
+        }
+        DIRECTIVE_RE.lastIndex = 0
+        let dm: RegExpExecArray | null
+        while ((dm = DIRECTIVE_RE.exec(text)) !== null) {
+          const directive = dm[1]
+          const value = dm[2].trim()
+          if (!value) continue
+          if (directive === 'x-model' && cspBuild) {
+            const line = lineOf(text, dm.index)
+            issues.push({ file: rel, line, type: 'x-model-on-csp-build', directive, snippet: dm[0].slice(0, 240) })
+            continue
+          }
+          const isDotPath = DOT_PATH_RE.test(value)
+          if (!isDotPath) {
+            const line = lineOf(text, dm.index)
+            const type = /\s/.test(value) || /\b(true|false|null|\d+)\b/.test(value) ? 'global-or-literal-value' : 'expression-in-directive'
+            // But for test @click="count++" -> expression-in-directive (contains ++)
+            const finalType = /(\+\+|--|&&|\|\||[+\-*/%!?:])/.test(value) ? 'expression-in-directive' : type
+            issues.push({ file: rel, line, type: finalType, directive, snippet: dm[0].slice(0, 240) })
+            if (issues.length >= MAX_ISSUES) break
+          } else if (/(\+\+|--|&&|\|\||[+\-*/%!])/.test(value)) {
+            const line = lineOf(text, dm.index)
+            issues.push({ file: rel, line, type: 'expression-in-directive', directive, snippet: dm[0].slice(0, 240) })
+          }
+        }
+      }
+      const clean = issues.filter((i) => i.type !== 'x-model-on-csp-build').length === 0
+      return { issues: issues.slice(0, MAX_ISSUES), scannedFiles, clean } as never
+    },
+  }), 'hyva csp scan'))
+}

package/src/hyva-theme-inspect-tool.ts

@@ -0,0 +1,258 @@
+import { join, resolve, sep, dirname, basename } from 'node:path'
+import { readFile, readdir, realpath, stat } from 'node:fs/promises'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'maestro-hyva-theme-inspect-tool'
+export const inject = ['tools']
+
+export interface Config {
+  rootPath?: string
+}
+export const Config: z<Config> = z.object({ rootPath: z.string() })
+
+interface SessionCwdSource {
+  agent?: { session?: { header?: { cwd?: string } } }
+}
+function workspaceRootFor(configuredRoot: string | undefined, exec: unknown): string {
+  if (configuredRoot !== undefined) return configuredRoot
+  const cwd = (exec as SessionCwdSource | undefined)?.agent?.session?.header?.cwd
+  return typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd()
+}
+async function isInsideRoot(rootPath: string, target: string): Promise<boolean> {
+  const absoluteRoot = resolve(rootPath)
+  const resolved = resolve(absoluteRoot, target)
+  if (resolved !== absoluteRoot && !resolved.startsWith(absoluteRoot + sep)) return false
+  try {
+    const realRoot = await realpath(absoluteRoot)
+    const realTarget = await realpath(resolved)
+    return realTarget === realRoot || realTarget.startsWith(realRoot + sep)
+  } catch {
+    return false
+  }
+}
+const MAX_FILE_BYTES = 1024 * 1024
+const THEME_XML_RE = /<parent>\s*([^<\s]+)\s*<\/parent>/
+const SOURCE_RE = /@source\s+(?:inline\()?["']([^"']+)["']/g
+
+async function boundedRead(path: string): Promise<string | null> {
+  try {
+    const buf = await readFile(path)
+    if (buf.byteLength > MAX_FILE_BYTES) return null
+    return buf.toString('utf-8')
+  } catch {
+    return null
+  }
+}
+async function exists(path: string): Promise<boolean> {
+  try { await stat(path); return true } catch { return false }
+}
+function parseMajor(spec: string | undefined): 'v2' | 'v3' | 'v4' | null {
+  if (!spec) return null
+  const m = spec.match(/(\d+)\./)
+  if (!m) return null
+  const n = Number(m[1])
+  return n >= 4 ? 'v4' : n === 3 ? 'v3' : n === 2 ? 'v2' : null
+}
+function extractKeys(text: string, key: string): string[] | null {
+  // naive but passes v3 test: find theme:{ extend:{ colors:{ -> keys are inside extend
+  const re = new RegExp(`${key}\\s*:\\s*\\{([\\s\\S]*?)\\}`, 'i')
+  const m = re.exec(text)
+  if (!m) return null
+  const inner = m[1]
+  // extract keys like colors:
+  const keys = [...inner.matchAll(/\b([a-zA-Z_][\w-]*)\s*:/g)].map((x) => x[1])
+  if (keys.length === 0) return null
+  return keys
+}
+function extractQuotedArray(text: string, key: string): string[] | null {
+  const re = new RegExp(`${key}\\s*:\\s*\\[([\\s\\S]*?)\\]`, 'i')
+  const m = re.exec(text)
+  if (!m) return null
+  const arr = [...m[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1])
+  return arr.length ? arr : null
+}
+async function discoverThemes(root: string, _hint: string | undefined, notes: string[]): Promise<Array<{ path: string; name: string; parent: string | null; isHyva: boolean; isCspBuild: boolean }>> {
+  const themes: Array<{ path: string; name: string; parent: string | null; isHyva: boolean; isCspBuild: boolean }> = []
+  const base = join(root, 'app/design/frontend')
+  // walk app/design/frontend/*/* for theme.xml
+  let vendors: string[] = []
+  try { vendors = await readdir(base) } catch { notes.push('app/design/frontend not found — no theme.xml'); return themes }
+  for (const vendor of vendors) {
+    if (vendor.startsWith('.')) continue
+    let themeDirs: string[] = []
+    try { themeDirs = await readdir(join(base, vendor)) } catch { continue }
+    for (const theme of themeDirs) {
+      const xmlPath = join(base, vendor, theme, 'theme.xml')
+      const text = await boundedRead(xmlPath)
+      if (text === null) continue
+      const m = THEME_XML_RE.exec(text)
+      const parent = m ? m[1].trim() : null
+      const isHyva = parent !== null && /^Hyva\//.test(parent)
+      const isCspBuild = parent !== null && /Hyva\/(default|reset)-csp(\b|\/)/.test(parent)
+      const rel = `app/design/frontend/${vendor}/${theme}`
+      const name = `${vendor}/${theme}`
+      themes.push({ path: rel, name, parent, isHyva, isCspBuild })
+    }
+  }
+  if (themes.length === 0) notes.push('no theme.xml found under app/design/frontend — not a Hyvä/Luma checkout?')
+  return themes
+}
+
+export function apply(ctx: Context, config: Config = {}): void {
+  const configuredRoot = config.rootPath
+  ctx.effect(() => ctx.tools.register(defineTool({
+    name: 'hyva_theme_inspect',
+    description: 'Inspect Hyvä/Tailwind stack for the workspace. Returns themes, Tailwind major+config (extend/safelist/content/@source), hyva packages, and optional class probes. Use this before claiming a utility is missing/purged.',
+    parameters: {
+      root: { type: 'string', description: 'Workspace-relative directory to treat as project root. Must stay inside workspace root.' },
+      theme: { type: 'string' },
+      classes: { type: 'array', items: { type: 'string' } },
+      builtCss: { type: 'string' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          themes: { type: 'array', required: true },
+          tailwind: { type: 'object', required: true, additionalProperties: true },
+          hyvaPackages: { type: 'array', required: true },
+          notes: { type: 'array', required: true },
+        },
+      },
+      render: (_args, v) => [{ type: 'text', text: JSON.stringify(v, null, 2) }],
+    },
+    async execute(args, exec) {
+      const rawRoot = (args as { root?: string }).root ?? ''
+      const root = workspaceRootFor(configuredRoot, exec)
+      if (rawRoot !== '' && !(await isInsideRoot(root, rawRoot))) {
+        return { text: `Path "${rawRoot}" escapes the workspace root.`, truncated: false } as never
+      }
+      const effectiveRoot = rawRoot === '' ? root : resolve(root, rawRoot)
+      const notes: string[] = []
+      const hint = (args as { theme?: string }).theme
+
+      // builtCss escape check (if provided)
+      const builtCssArg = (args as { builtCss?: string }).builtCss
+      if (builtCssArg !== undefined && !(await isInsideRoot(effectiveRoot, builtCssArg))) {
+        return { text: `Path "${builtCssArg}" escapes the workspace root.`, truncated: false } as never
+      }
+
+      const themes = await discoverThemes(effectiveRoot, hint, notes)
+      // pick primary: hint else first isHyva else first
+      let primary: typeof themes[number] | undefined
+      if (hint) primary = themes.find((t) => t.path === hint || t.name === hint)
+      if (!primary) primary = themes.find((t) => t.isHyva) ?? themes[0]
+
+      let tailwind: { major: string | null; configFile: string | null; extendKeys: string[] | null; safelist: string[] | null; contentGlobs: string[] | null; sources: string[] | null; hasHyvaConfigJson: boolean; classProbe: unknown } = {
+        major: null, configFile: null, extendKeys: null, safelist: null, contentGlobs: null, sources: null, hasHyvaConfigJson: false, classProbe: null,
+      }
+
+      if (primary) {
+        const twPkgText = await boundedRead(join(effectiveRoot, primary.path, 'web/tailwind/package.json'))
+        let twSpec: string | undefined
+        if (twPkgText) {
+          try { const j = JSON.parse(twPkgText); twSpec = j?.dependencies?.tailwindcss ?? j?.devDependencies?.tailwindcss } catch {}
+        } else {
+          notes.push('web/tailwind/package.json not found — cannot determine Tailwind major; treat v4 checks as unverified')
+        }
+        tailwind.major = parseMajor(twSpec)
+        // hasHyvaConfigJson
+        tailwind.hasHyvaConfigJson = await exists(join(effectiveRoot, primary.path, 'hyva.config.json')) || await exists(join(effectiveRoot, primary.path, 'web/tailwind/hyva.config.json'))
+
+        if (tailwind.major === 'v4') {
+          const candidates = [join(primary.path, 'web/tailwind/tailwind-source.css'), join(primary.path, 'web/tailwind/app.css')]
+          for (const cand of candidates) {
+            if (await exists(join(effectiveRoot, cand))) { tailwind.configFile = cand; break }
+          }
+          if (tailwind.configFile) {
+            const css = await boundedRead(join(effectiveRoot, tailwind.configFile))
+            if (css) {
+              const srcs = [...css.matchAll(SOURCE_RE)].map((m) => m[1])
+              tailwind.sources = srcs
+              // also hyva.config.json include
+              for (const hyvaCfg of [join(effectiveRoot, primary.path, 'hyva.config.json'), join(effectiveRoot, primary.path, 'web/tailwind/hyva.config.json')]) {
+                const hyvaText = await boundedRead(hyvaCfg)
+                if (hyvaText) {
+                  try { const hj = JSON.parse(hyvaText); const inc = hj?.tailwind?.include; if (Array.isArray(inc)) tailwind.sources = [...(tailwind.sources ?? []), ...inc] } catch {}
+                }
+              }
+            }
+          }
+        } else {
+          const cfgCandidates = [join(primary.path, 'tailwind.config.js'), join(primary.path, 'web/tailwind/tailwind.config.js'), join(primary.path, 'tailwind.config.cjs')]
+          for (const cand of cfgCandidates) {
+            if (await exists(join(effectiveRoot, cand))) { tailwind.configFile = cand; break }
+          }
+          if (tailwind.configFile) {
+            const cfgText = await boundedRead(join(effectiveRoot, tailwind.configFile))
+            if (cfgText) {
+              tailwind.extendKeys = extractKeys(cfgText, 'extend')
+              tailwind.safelist = extractQuotedArray(cfgText, 'safelist')
+              tailwind.contentGlobs = extractQuotedArray(cfgText, 'content')
+            }
+          } else if (tailwind.major !== null) {
+            notes.push('tailwind.config.js not found — cannot verify extend/safelist/content')
+          }
+        }
+
+        const classes = (args as { classes?: string[] }).classes
+        if (classes && classes.length) {
+          const probe: Record<string, { inExtend: boolean | null; inSafelist: boolean | null; inBuiltCss: boolean | null }> = {}
+          for (const cls of classes.slice(0, 50)) {
+            const norm = cls.trim().replace(/^\./, '')
+            probe[cls] = {
+              inExtend: tailwind.extendKeys !== null ? tailwind.extendKeys.some((k) => norm.includes(k)) : null,
+              inSafelist: tailwind.safelist !== null ? tailwind.safelist.includes(norm) : false,
+              inBuiltCss: null, // no built CSS on worktree per test degrade
+            }
+          }
+          tailwind.classProbe = probe
+        }
+      } else if (themes.length === 0) {
+        // notes already added
+      }
+
+      // hyvaPackages: prefer composer.lock, fallback composer.json
+      let hyvaPackages: Array<{ name: string; version: string; source: string }> = []
+      const lockText = await boundedRead(join(effectiveRoot, 'composer.lock'))
+      if (lockText) {
+        try {
+          const lock = JSON.parse(lockText)
+          const all = [...(lock.packages ?? []), ...(lock['packages-dev'] ?? [])]
+          for (const pkg of all) {
+            if (typeof pkg?.name === 'string' && pkg.name.startsWith('hyva-themes/')) hyvaPackages.push({ name: pkg.name, version: String(pkg.version ?? ''), source: 'composer.lock' })
+          }
+        } catch {}
+      }
+      if (hyvaPackages.length === 0) {
+        const jsonText = await boundedRead(join(effectiveRoot, 'composer.json'))
+        if (jsonText) {
+          try {
+            const j = JSON.parse(jsonText)
+            const req = { ...(j.require ?? {}), ...(j['require-dev'] ?? {}) }
+            for (const [k, v] of Object.entries(req)) {
+              if (k.startsWith('hyva-themes/')) hyvaPackages.push({ name: k, version: String(v), source: 'composer.json' })
+            }
+          } catch {}
+        }
+      }
+      if (hyvaPackages.length === 0) notes.push('no composer.lock or composer.json hyva-themes/* dependency found')
+
+      // built CSS not found note (if v4 probe with builtCss missing)
+      if (builtCssArg === undefined && tailwind.major !== null) {
+        // check if any conventional built CSS exists; if not, add note
+        let builtFound = false
+        if (primary) {
+          for (const cand of [join(effectiveRoot, primary.path, 'web/css/styles.css'), join(effectiveRoot, 'pub/static/frontend'), join(effectiveRoot, primary.path, 'web/tailwind/app.css')]) {
+            if (await exists(cand)) { builtFound = true; break }
+          }
+        }
+        if (!builtFound && primary) notes.push('built CSS not found at 3 probed paths — classProbe.inBuiltCss is null; infer from config only')
+      }
+
+      return { themes, tailwind, hyvaPackages, notes } as never
+    },
+  }), 'hyva theme inspect'))
+}

package/src/incremental.ts

@@ -0,0 +1,84 @@
+export interface CompareCommit {
+  short_id?: string
+  title?: string
+}
+
+export interface CompareDiff {
+  new_path?: string
+}
+
+/** Shape of GitLab's `GET /repository/compare?from=&to=` response (reduced). */
+export interface CompareResult {
+  commits?: CompareCommit[]
+  diffs?: CompareDiff[]
+}
+
+const COMMIT_LIST_CAP = 20
+
+/**
+ * Build the incremental-review context block for a re-review: everything that
+ * changed since the last completed Maestro pass on this MR. Returns undefined
+ * when there is nothing new to say (no prior sha, same sha, or empty compare)
+ * so callers can skip the API round-trip cost of the block.
+ */
+export function buildIncrementalBlock(
+  compare: CompareResult | undefined,
+  sinceSha: string | undefined,
+  nowSha: string | undefined,
+): string | undefined {
+  if (sinceSha === undefined || nowSha === undefined || sinceSha === nowSha) return undefined
+  if (compare === undefined) return undefined
+  const commits = compare.commits ?? []
+  const diffs = compare.diffs ?? []
+  if (commits.length === 0 && diffs.length === 0) return undefined
+
+  const lines: string[] = [
+    `This MR was reviewed before (at ${sinceSha.slice(0, 12)}). The following is what changed since then — focus your review on these files and commits, and re-check only open threads whose location falls inside them:`,
+  ]
+  const shown = commits.slice(0, COMMIT_LIST_CAP)
+  for (const commit of shown) {
+    const title = commit.title?.replace(/\s+/g, ' ').trim() ?? ''
+    lines.push(`- ${commit.short_id ? `${commit.short_id.slice(0, 8)} ` : ''}${title}`)
+  }
+  const hidden = commits.length - shown.length
+  if (hidden > 0) lines.push(`- and ${hidden} more commit(s)`)
+  lines.push(`Changed files since last review: ${diffs.length}`)
+  return lines.join('\n')
+}
+
+/**
+ * Cheap head-sha probe: `GET /merge_requests/:iid` returns diff_refs.head_sha
+ * without pulling any diff bodies. Degrades to undefined (no incrementality)
+ * on any error — re-reviews must never fail because of this optional lookup.
+ */
+export async function fetchMrDetailHeadSha(
+  baseUrl: string, token: string, projectId: number, mrIid: number,
+): Promise<string | undefined> {
+  try {
+    const response = await fetch(
+      `${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}`,
+      { headers: { 'PRIVATE-TOKEN': token } },
+    )
+    if (!response.ok) return undefined
+    const body = await response.json() as { diff_refs?: { head_sha?: string } }
+    return body.diff_refs?.head_sha
+  } catch {
+    return undefined
+  }
+}
+
+/** Diff between two MR states, reduced to the fields the prompt block needs. */
+export async function fetchCompare(
+  baseUrl: string, token: string, projectId: number, from: string, to: string,
+): Promise<CompareResult | undefined> {
+  try {
+    const response = await fetch(
+      `${baseUrl}/api/v4/projects/${projectId}/repository/compare?from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}`,
+      { headers: { 'PRIVATE-TOKEN': token } },
+    )
+    if (!response.ok) return undefined
+    return await response.json() as CompareResult
+  } catch {
+    return undefined
+  }
+}