@ddtcorex/dsh-maestro-review 0.1.0 → 0.1.2

package/src/host/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/host/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
+  }
+}

package/src/host/layout-xml-tool.ts

@@ -0,0 +1,191 @@
+import { join, resolve, sep, basename, dirname } 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-layout-xml-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(c:string|undefined, exec:unknown):string{
+  if(c!==undefined) return c
+  const cwd=(exec as SessionCwdSource|undefined)?.agent?.session?.header?.cwd
+  return typeof cwd==='string' && cwd!=='' ? cwd : process.cwd()
+}
+async function isInsideRoot(root:string, target:string):Promise<boolean>{
+  const ar=resolve(root); const rs=resolve(ar,target)
+  if(rs!==ar && !rs.startsWith(ar+sep)) return false
+  try{ const rr=await realpath(ar); const rt=await realpath(rs); return rt===rr || rt.startsWith(rr+sep)}catch{return false}
+}
+const MAX_FILE_BYTES=1024*1024
+const MAX_FILES=2000
+const SKIP_DIRS=new Set(['.git','node_modules','vendor','pub/static'])
+const LAYOUT_RE = /\/layout\//
+
+// tiny helpers
+function parseAttrs(s:string):Record<string,string>{
+  const out:Record<string,string>={}
+  let m:RegExpExecArray|null
+  const re=/(\w+)="([^"]*)"/g
+  while((m=re.exec(s))!==null) out[m[1]]=m[2]
+  return out
+}
+async function exists(p:string):Promise<boolean>{ try{await stat(p); return true}catch{return false}}
+async function* walkLayout(dir:string, root:string, budget:{files:number}):AsyncGenerator<string>{
+  if(budget.files<=0) return
+  let entries
+  try{ entries=await readdir(dir,{withFileTypes:true})}catch{return}
+  for(const e of entries){
+    if(budget.files<=0) return
+    if(e.isDirectory()){
+      if(SKIP_DIRS.has(e.name)) continue
+      yield* walkLayout(join(dir,e.name), root, budget)
+      continue
+    }
+    if(!e.isFile()) continue
+    if(!e.name.endsWith('.xml')) continue
+    if(!join(dir,e.name).includes('/layout/')) continue
+    budget.files-=1
+    yield join(dir,e.name)
+  }
+}
+
+export function apply(ctx:Context, config:{rootPath?:string}={}):void{
+  const configuredRoot=config.rootPath
+  ctx.effect(()=>ctx.tools.register(defineTool({
+    name:'layout_xml_extract',
+    description:'Extract Magento layout handles/blocks/moves/head from layout XML under workspace. Use before claiming layout is correct.',
+    parameters:{
+      root:{type:'string'},
+      changedFiles:{type:'array', items:{type:'string'}},
+    },
+    output:{
+      schema:{
+        type:'object', additionalProperties:false,
+        properties:{
+          handles:{type:'array', required:true},
+          handleCount:{type:'number', required:true},
+          blockCount:{type:'number', required:true},
+          scannedFiles:{type:'number', required:true},
+          truncated:{type:'boolean', 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 changedFiles=(args as {changedFiles?:string[]}).changedFiles
+      if(changedFiles){
+        for(const p of changedFiles){
+          if(!(await isInsideRoot(effectiveRoot, p))) return {text:`Path "${p}" escapes the workspace root.`, truncated:false} as never
+        }
+      }
+      // collect files
+      const budget={files:MAX_FILES}
+      const all:string[]=[]
+      for await(const f of walkLayout(effectiveRoot, effectiveRoot, budget)){
+        const rel=f.startsWith(effectiveRoot+sep)? f.slice(effectiveRoot.length+1): basename(f)
+        all.push(rel)
+      }
+      let files=all
+      if(changedFiles && changedFiles.length>0){
+        const set=new Set(changedFiles.map(p=>p.endsWith('.xml')?p:p))
+        files=all.filter(p=> set.has(p) || changedFiles.some(cf=> p.endsWith(basename(cf))))
+        // also if allow-list contains files not discovered via walk (e.g., outside layout but still layout), include them if they exist and are layout
+        for(const cf of changedFiles){
+          if(!files.includes(cf)){
+            const abs=resolve(effectiveRoot, cf)
+            if(await exists(abs) && cf.includes('/layout/') && cf.endsWith('.xml') && !(all.includes(cf))) files.push(cf)
+          }
+        }
+      }
+      const truncated = budget.files<=0
+      const handles:Array<{file:string,handle:string,layoutType:string,blocks:Array<{name:string|null,type:string,class:string|null,template:string|null,templateExists:boolean|null,as:string|null,cacheable:boolean|null,remove:boolean,refs:string[]}>,moves:Array<{element:string,destination:string|null,as:string|null,before:string|null,after:string|null}>,references:Array<{kind:string,name:string,attrs:Record<string,string>}>,head:{scripts:Array<{src:string}>,css:Array<{src:string}>,metas:Array<Record<string,string>>,removes:Array<string>},parseError:string|null}>=[]
+      let blockCount=0
+      for(const rel of files){
+        const abs=resolve(effectiveRoot, rel)
+        let text:string
+        try{
+          const buf=await readFile(abs)
+          if(buf.byteLength>MAX_FILE_BYTES) continue
+          text=buf.toString('utf-8')
+        }catch{continue}
+        const handle=basename(rel,'.xml')
+        const layoutType=/<page\b/.test(text)?'page':'generic'
+        // quick parseError heuristic: mismatched < vs > or unclosed tag
+        let parseError:string|null=null
+        const openCount=(text.match(/</g)||[]).length
+        const closeCount=(text.match(/>/g)||[]).length
+        if(openCount!==closeCount) parseError=`mismatched < (${openCount}) vs > (${closeCount})`
+        // also detect block tag without closing >
+        if(/<block[^>]*$/m.test(text) || /<block[^>]*<\/body/.test(text)) parseError=parseError ?? 'malformed block tag'
+        if(parseError){
+          handles.push({file:rel,handle,layoutType,blocks:[],moves:[],references:[],head:{scripts:[],css:[],metas:[],removes:[]},parseError})
+          continue
+        }
+        const blocks:Array<{name:string|null,type:string,class:string|null,template:string|null,templateExists:boolean|null,as:string|null,cacheable:boolean|null,remove:boolean,refs:string[]}>=[]
+        const moves:Array<{element:string,destination:string|null,as:string|null,before:string|null,after:string|null}>=[]
+        const references:Array<{kind:string,name:string,attrs:Record<string,string>}>=[]
+        const head={scripts:[] as Array<{src:string}>, css:[] as Array<{src:string}>, metas:[] as Array<Record<string,string>>, removes:[] as string[]}
+        // blocks/containers (only concrete)
+        const tagRe=/<(block|container)\b([^>]*?)(?:\/>|>)/g
+        let m:RegExpExecArray|null
+        while((m=tagRe.exec(text))!==null){
+          const type=m[1]; const attrStr=m[2]; const attrs=parseAttrs(attrStr)
+          const name=attrs.name ?? null
+          const klass=attrs.class ?? null
+          const template=attrs.template ?? null
+          let templateExists:boolean|null=null
+          if(template!==null){
+            if(template.includes('::')){
+              const [modPart, filePart]=template.split('::')
+              const [vendor, mod]=modPart.split('_')
+              if(vendor && mod && filePart){
+                const cand=join(effectiveRoot, `app/code/${vendor}/${mod}/view/frontend/templates/${filePart}`)
+                templateExists=await exists(cand)
+                if(!templateExists){
+                  templateExists=false
+                }
+              } else templateExists=false
+            } else {
+              templateExists=await exists(join(effectiveRoot, template))
+            }
+          }
+          const as=attrs.as ?? null
+          const cacheable=attrs.cacheable ? attrs.cacheable==='true' : null
+          const remove=attrs.remove==='true'
+          blocks.push({name, type, class:klass, template, templateExists, as, cacheable, remove, refs:[]})
+        }
+        // references
+        const refRe=/(<(referenceBlock|referenceContainer)\b([^>]*?)(?:\/>|>))/g
+        while((m=refRe.exec(text))!==null){
+          const type=m[2]; const attrs=parseAttrs(m[3])
+          references.push({kind:type, name: attrs.name ?? '', attrs})
+        }
+        // moves
+        const moveRe=/<move\b([^>]*?)\/>/g
+        while((m=moveRe.exec(text))!==null){
+          const attrs=parseAttrs(m[1])
+          moves.push({element:attrs.element ?? '', destination:attrs.destination ?? null, as:attrs.as ?? null, before:attrs.before ?? null, after:attrs.after ?? null})
+        }
+        // head css/scripts
+        const cssRe=/<css\b([^>]*?)\/>/g
+        while((m=cssRe.exec(text))!==null){ const a=parseAttrs(m[1]); if(a.src) head.css.push({src:a.src}) }
+        const scriptRe=/<script\b([^>]*?)\/>/g
+        while((m=scriptRe.exec(text))!==null){ const a=parseAttrs(m[1]); if(a.src) head.scripts.push({src:a.src}) }
+        // also <remove src=>
+        const removeRe=/<remove\b([^>]*?)\/>/g
+        while((m=removeRe.exec(text))!==null){ const a=parseAttrs(m[1]); if(a.src) head.removes.push(a.src) }
+
+        blockCount+=blocks.length
+        handles.push({file:rel,handle,layoutType,blocks,moves,references,head,parseError:null})
+      }
+      return {handles, handleCount:handles.length, blockCount, scannedFiles:files.length, truncated} as never
+    },
+  }), 'layout xml'))
+}