omakit 0.5.1 → 0.6.2

package/tools/blocks/registry.mjs

@@ -0,0 +1,191 @@
+// The blocks omakit ships, read from blocks/<name>/ in this checkout or
+// package: which files each has, their headers, and the sha256 of every
+// file's body, which is what `omakit add` writes, what it refuses to
+// overwrite when it differs, and what `omakit inspect` recognises an
+// unmodified copy by. Nothing here is a marketplace rule (AGENTS.md, rule
+// 2): a block is behaviour measured from public review comments (M13,
+// docs/BLOCKS.md), and this module only knows the block's own files.
+//
+// A file's header is its leading comment lines up to and including the
+// line `end of omakit block header`; the body is everything after that
+// line. The header names the block and its version, the licence, the
+// copyright, where the file came from (the commit is stamped by `add`,
+// so it is the one line a copy may differ from the shipped file in) and
+// the body's sha256, so a person can check a copy with sha256sum alone.
+
+import { createHash } from "node:crypto"
+import { readdirSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const BLOCKS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "../../blocks")
+
+export const HEADER_END = "end of omakit block header"
+
+/**
+ * A block that uses another block's files from the same omakit/ directory:
+ * `omakit add` writes the required block too, and inspect reads the
+ * requirement when it says whether a block is complete.
+ */
+export const REQUIRES = Object.freeze({ store: Object.freeze(["run"]) })
+
+/** The blocks to add for one name: its requirements first, then itself, each once. */
+export function blockClosure(name) {
+  const names = []
+  for (const required of REQUIRES[name] || []) for (const entry of blockClosure(required)) if (!names.includes(entry)) names.push(entry)
+  if (!names.includes(name)) names.push(name)
+  return names
+}
+
+/**
+ * Split a block file's text into its header lines and its body. Null when
+ * the text has no block header, which is how a plugin's own file reads.
+ *
+ * @param {string} text
+ * @returns {{ header: string[], body: string, name: string, version: string, sha256: string|null } | null}
+ */
+export function parseHeader(text) {
+  const lines = String(text).split("\n")
+  const end = lines.findIndex((line) => line.replace(/^(?:\/\/|#)\s*/, "").trim() === HEADER_END)
+  if (end < 0 || end > 12) return null
+  const header = lines.slice(0, end + 1)
+  const strip = (line) => line.replace(/^(?:\/\/|#)\s?/, "")
+  const named = header.map(strip).find((line) => /^omakit block: /.test(line))
+  if (!named) return null
+  const match = named.match(/^omakit block: ([a-z][a-z0-9-]*) (\d+\.\d+\.\d+)$/)
+  if (!match) return null
+  const sha = header.map(strip).find((line) => /^Body sha256: /.test(line))?.slice("Body sha256: ".length).trim() || null
+  return { header, body: lines.slice(end + 1).join("\n"), name: match[1], version: match[2], sha256: sha && /^[0-9a-f]{64}$/.test(sha) ? sha : null }
+}
+
+export function bodySha256(body) {
+  return createHash("sha256").update(body, "utf8").digest("hex")
+}
+
+/**
+ * Every shipped block: its name, version, and files with their parsed
+ * headers and body hashes, from blocks/<name>/ (NOTICE is the listing, not
+ * a block file, and has no header).
+ *
+ * @param {string} [dir]
+ * @returns {Array<{ name: string, version: string, dir: string, files: Array<{ file: string, text: string, header: string[], body: string, sha256: string, headerSha256: string|null }>, notice: string }>}
+ */
+export function shippedBlocks(dir = BLOCKS_DIR) {
+  const blocks = []
+  for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (!entry.isDirectory()) continue
+    const blockDir = join(dir, entry.name)
+    const files = []
+    let notice = ""
+    for (const file of readdirSync(blockDir).sort()) {
+      const text = readFileSync(join(blockDir, file), "utf8")
+      if (file === "NOTICE") {
+        notice = text
+        continue
+      }
+      const parsed = parseHeader(text)
+      if (!parsed) throw new Error(`blocks/${entry.name}/${file} has no block header`)
+      if (parsed.name !== entry.name) throw new Error(`blocks/${entry.name}/${file} names block ${parsed.name}`)
+      files.push({ file, text, header: parsed.header, body: parsed.body, sha256: bodySha256(parsed.body), headerSha256: parsed.sha256, version: parsed.version })
+    }
+    if (!files.length) continue
+    const versions = new Set(files.map((file) => file.version))
+    if (versions.size !== 1) throw new Error(`blocks/${entry.name} carries ${versions.size} versions`)
+    blocks.push({ name: entry.name, version: files[0].version, dir: blockDir, files, notice })
+  }
+  return blocks
+}
+
+/** One shipped block by name, or null. */
+export function shippedBlock(name, dir = BLOCKS_DIR) {
+  return shippedBlocks(dir).find((block) => block.name === name) || null
+}
+
+/**
+ * What a file found in a plugin tree is, judged by its header and body
+ * alone: `unmodified` when a block header names a shipped block and the
+ * body's sha256 is that block's for that file; `modified` when it carries
+ * a block header but the body is not one this omakit ships; null when it
+ * has no block header at all.
+ *
+ * @param {string} file the base name, e.g. Run.qml
+ * @param {string} text
+ * @param {ReturnType<typeof shippedBlocks>} [blocks]
+ * An older shipped body (blocks/history.json) is unmodified at its own
+ * version, which the row names beside the shipped one.
+ *
+ * @returns {{ name: string, version: string, state: "unmodified"|"modified", shippedVersion: string|null } | null}
+ */
+export function recogniseBlockFile(file, text, blocks = shippedBlocks(), history = shippedHistory()) {
+  const parsed = parseHeader(text)
+  if (!parsed) return null
+  const shipped = blocks.find((block) => block.name === parsed.name)
+  const sha = bodySha256(parsed.body)
+  const known = shipped?.files.find((entry) => entry.file === file)
+  const older = !known || known.sha256 !== sha ? history.find((row) => row.block === parsed.name && row.file === file && row.sha256 === sha) : null
+  const state = known && known.sha256 === sha ? "unmodified" : older ? "unmodified" : "modified"
+  return { name: parsed.name, version: older ? older.version : parsed.version, state, shippedVersion: shipped ? shipped.version : null }
+}
+
+/** The header line that carries the body hash, rewritten to the given digest. */
+export function withBodySha256(text, sha256) {
+  return String(text).replace(/^((?:\/\/|#) ?Body sha256: )[0-9a-f]{64}$/m, `$1${sha256}`)
+}
+
+/** The header's source line with the commit stamped in. */
+export function withSourceCommit(text, commit) {
+  return String(text).replace(/^((?:\/\/|#) ?Source: omakit [^,\n]+, commit )\S+$/m, `$1${commit}`)
+}
+
+/**
+ * The NOTICE for a set of blocks in one `omakit/` directory: per file the
+ * block, version, licence, copyright, source path and commit, and the
+ * body sha256, so the review's vendored-code expectation (record the
+ * upstream, keep the licence, disclose modifications) is met by one file.
+ *
+ * @param {Array<{ name: string, version: string, files: Array<{ file: string, sha256: string }> }>} blocks
+ * @param {string} commit the omakit commit the files came from, or "unstamped"
+ */
+export function renderNotice(blocks, commit) {
+  const lines = [
+    "omakit blocks in this directory",
+    "",
+    "Each file below was copied from omakit (https://github.com/mtolhuys/omakit),",
+    "MIT licence, Copyright (c) 2026 Maarten Tolhuijs, by `omakit add`. The body",
+    "sha256 is over everything after the file's header line",
+    `\`${HEADER_END}\`; \`omakit inspect\` reports a file whose body differs as`,
+    "modified, and `omakit add --update` refuses to overwrite one. Modifications",
+    "are to be listed here by the plugin's author.",
+    "",
+  ]
+  for (const block of blocks) {
+    lines.push(`block ${block.name} ${block.version}, from omakit commit ${commit}`)
+    for (const file of block.files) lines.push(`  ${file.file}  sha256 ${file.sha256}`)
+    lines.push("")
+  }
+  return `${lines.join("\n")}\n`.replace(/\n\n$/, "\n")
+}
+
+/**
+ * Every body sha256 omakit ever shipped for a block file, from
+ * blocks/history.json (appended by tools/blocks/stamp.mjs at every block
+ * change, never pruned) plus the current files: what `omakit add --update`
+ * may replace, and what `inspect` names as an older unmodified copy.
+ *
+ * @returns {Array<{ block: string, version: string, file: string, sha256: string }>}
+ */
+export function shippedHistory(dir = BLOCKS_DIR) {
+  let history = []
+  try {
+    history = JSON.parse(readFileSync(join(dir, "history.json"), "utf8"))
+  } catch {
+    history = []
+  }
+  const rows = [...history]
+  for (const block of shippedBlocks(dir)) {
+    for (const entry of block.files) {
+      if (!rows.some((row) => row.block === block.name && row.file === entry.file && row.sha256 === entry.sha256)) rows.push({ block: block.name, version: block.version, file: entry.file, sha256: entry.sha256 })
+    }
+  }
+  return rows
+}

package/tools/blocks/stamp.mjs

@@ -0,0 +1,61 @@
+// Maintainer's tool: rewrite the `Body sha256` line of every shipped block
+// file to its body's digest and regenerate blocks/<name>/NOTICE, so the
+// header a plugin author reads and the hash inspect recognises are one
+// number. Run after editing a block:
+//
+//   node tools/blocks/stamp.mjs          # writes; prints what changed
+//   node tools/blocks/stamp.mjs --check  # exits 1 when a header is stale
+//
+// Writes only under this checkout's blocks/ directory, never into a
+// plugin tree; tests/unit/self-containment.test.mjs holds it to that.
+
+import { readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { BLOCKS_DIR, renderNotice, shippedBlocks, shippedHistory, withBodySha256 } from "./registry.mjs"
+
+const check = process.argv.includes("--check")
+let stale = 0
+for (const block of shippedBlocks()) {
+  for (const entry of block.files) {
+    const stamped = withBodySha256(entry.text, entry.sha256)
+    if (stamped !== entry.text) {
+      stale += 1
+      process.stdout.write(`${check ? "stale" : "stamped"} blocks/${block.name}/${entry.file} ${entry.sha256}\n`)
+      const blockFile = join(block.dir, entry.file)
+      if (!check) writeFileSync(blockFile, stamped)
+    }
+  }
+  const notice = renderNotice([block], "unstamped")
+  let current = null
+  try {
+    current = readFileSync(join(block.dir, "NOTICE"), "utf8")
+  } catch {
+    current = null
+  }
+  if (current !== notice) {
+    stale += 1
+    process.stdout.write(`${check ? "stale" : "written"} blocks/${block.name}/NOTICE\n`)
+    const blockFile = join(block.dir, "NOTICE")
+    if (!check) writeFileSync(blockFile, notice)
+  }
+}
+// history.json: every (block, version, file, sha256) ever shipped, so
+// `add --update` can tell an older copy from a modified one. Append-only.
+{
+  const rows = shippedHistory()
+  const text = `${JSON.stringify(rows, null, 1)}\n`
+  let current = null
+  try {
+    current = readFileSync(join(BLOCKS_DIR, "history.json"), "utf8")
+  } catch {
+    current = null
+  }
+  if (current !== text) {
+    stale += 1
+    process.stdout.write(`${check ? "stale" : "written"} blocks/history.json (${rows.length} shipped file versions)\n`)
+    const blockFile = join(BLOCKS_DIR, "history.json")
+    if (!check) writeFileSync(blockFile, text)
+  }
+}
+if (!stale) process.stdout.write("every block header carries its body's sha256 and every NOTICE is current\n")
+process.exitCode = check && stale ? 1 : 0

package/tools/inspect/contract.mjs

@@ -11,8 +11,9 @@ import { resolve } from "node:path"
 import { pathToFileURL } from "node:url"
 
 const ARGV_FORMS = new Set(["array", "string", "computed"])
-const DEADLINE_VIA = new Set(["timer-kill", "timeout-argv", "destruction", null])
-const COLLECTORS = new Set(["StdioCollector", "SplitParser", "none", "unknown"])
+const DEADLINE_VIA = new Set(["timer-kill", "timeout-argv", "destruction", "block-run", null])
+const COLLECTORS = new Set(["StdioCollector", "SplitParser", "Run", "none", "unknown"])
+const BLOCK_STATES = new Set(["unmodified", "modified"])
 const CONTROLLED = new Set(["observed", "not-observed", "unknown"])
 const DECLARED_IN = new Set(["qml", "shell"])
 const FILE_KINDS = ["qml", "js", "shell", "python", "other"]
@@ -44,14 +45,18 @@ function processRow(row, at, problems) {
   if (row.argvForm === "array" && Array.isArray(row.argv)) {
     for (const entry of row.expressions || []) if (row.argv[entry.index] !== entry.text) problems.push(`${at}.expressions[${entry.index}] does not name the argv element it stands for`)
   }
-  for (const key of ["running", "detached", "shellWrapper"]) if (!isBool(row[key])) problems.push(`${at}.${key} is not a boolean`)
+  for (const key of ["running", "detached", "shellWrapper", "closedEnvironment"]) if (!isBool(row[key])) problems.push(`${at}.${key} is not a boolean`)
+  if (row.closedEnvironment && row.declaredIn !== "shell") problems.push(`${at}.closedEnvironment is set on a site that is not a shell line`)
   const deadline = row.deadline || {}
   if (!isBool(deadline.observed)) problems.push(`${at}.deadline.observed is not a boolean`)
-  if (!DEADLINE_VIA.has(deadline.via)) problems.push(`${at}.deadline.via is not timer-kill, timeout-argv, destruction or null`)
+  if (!DEADLINE_VIA.has(deadline.via)) problems.push(`${at}.deadline.via is not timer-kill, timeout-argv, destruction, block-run or null`)
+  if ((deadline.via === "block-run") !== (row.block === "run")) problems.push(`${at}.deadline.via block-run and block: "run" go together`)
+  if (row.block === "run" && !nullOr(isString)(row.helper)) problems.push(`${at}.helper is neither a tree path nor null`)
+  if (row.block !== "run" && row.helper !== undefined) problems.push(`${at}.helper is only for a Run site`)
   if (deadline.observed !== (deadline.via !== null)) problems.push(`${at}.deadline.observed disagrees with deadline.via`)
   if (!nullOr(isInt)(deadline.ms)) problems.push(`${at}.deadline.ms is neither an integer nor null`)
   const output = row.output || {}
-  if (!COLLECTORS.has(output.collector)) problems.push(`${at}.output.collector is not StdioCollector, SplitParser, none or unknown`)
+  if (!COLLECTORS.has(output.collector)) problems.push(`${at}.output.collector is not StdioCollector, SplitParser, Run, none or unknown`)
   if (!isBool(output.capObserved)) problems.push(`${at}.output.capObserved is not a boolean`)
   if (!nullOr(isString)(output.via)) problems.push(`${at}.output.via is neither a string nor null`)
   if (output.capObserved !== (output.via !== null)) problems.push(`${at}.output.capObserved disagrees with output.via`)
@@ -83,6 +88,7 @@ function write(row, at, problems) {
   if (row.canonicalPath === null && row.controlledDirectory !== "unknown") problems.push(`${at}.controlledDirectory is decided for a path that could not be read`)
   if (!isBool(row.temp)) problems.push(`${at}.temp is not a boolean`)
   if (!nullOr(isString)(row.mode)) problems.push(`${at}.mode is neither a string nor null`)
+  if ((row.via === "block-store") !== (row.block === "store")) problems.push(`${at}.via block-store and block: "store" go together`)
 }
 
 function fn(row, at, problems) {
@@ -203,6 +209,31 @@ export function validateInspectDocument(document, known = {}) {
       }
     }
   }
+  if (!Array.isArray(document.blocks)) problems.push("blocks is not a list")
+  else for (const [index, row] of document.blocks.entries()) {
+    const at = `blocks[${index}]`
+    if (!isString(row.name) || !/^[a-z][a-z0-9-]*$/.test(row.name)) problems.push(`${at}.name is not a block name`)
+    if (!isString(row.version)) problems.push(`${at}.version is not a string`)
+    if (!nullOr(isString)(row.shippedVersion)) problems.push(`${at}.shippedVersion is neither a string nor null`)
+    if (!BLOCK_STATES.has(row.state)) problems.push(`${at}.state is not unmodified or modified`)
+    if (!isBool(row.complete)) problems.push(`${at}.complete is not a boolean`)
+    if (!Array.isArray(row.files) || !row.files.length) problems.push(`${at}.files is not a non-empty list`)
+    else {
+      for (const [fileIndex, file] of row.files.entries()) {
+        if (!isString(file.path)) problems.push(`${at}.files[${fileIndex}].path is not a string`)
+        if (!BLOCK_STATES.has(file.state)) problems.push(`${at}.files[${fileIndex}].state is not unmodified or modified`)
+        if (!isString(file.version)) problems.push(`${at}.files[${fileIndex}].version is not a string`)
+      }
+      if ((row.state === "unmodified") !== row.files.every((file) => file.state === "unmodified")) problems.push(`${at}.state disagrees with its files`)
+      // An unmodified block's files were not read: no row of any kind at them.
+      if (row.state === "unmodified" && observed) {
+        const paths = new Set(row.files.map((file) => file.path))
+        for (const key of ["processes", "hosts", "writes", "timers", "functions"]) {
+          for (const fact of Array.isArray(observed[key]) ? observed[key] : []) if (paths.has(fact.file)) problems.push(`observed.${key} has a row at ${fact.file}:${fact.line}, a file of unmodified block ${row.name}`)
+        }
+      }
+    }
+  }
   if (!Array.isArray(document.patterns)) problems.push("patterns is not a list")
   else for (const [index, row] of document.patterns.entries()) {
     const at = `patterns[${index}]`

package/tools/inspect/helpers.mjs

@@ -0,0 +1,217 @@
+// Which files of the tree a `Run {` site starts: the site's argv[0]
+// resolved through the text to a path, never guessed from a base name. A
+// path resolves when the text shows it: a string literal, a `+` chain of
+// literals, `Qt.resolvedUrl("...")` (relative to the QML file) and
+// `Quickshell.env("X")`; an identifier through its `const`, `let`, `var`
+// or assignment in the enclosing text, a `property` binding, or the value
+// a parent QML file binds when it instantiates the component; a call to a
+// function the same file defines, through its return expression with the
+// arguments in place of its parameters; `a ? b : c` through `b`, `a || b`
+// through `a`, and `String()`, `decodeURIComponent()`, `.replace()`,
+// `.trim()`, `.toString()` through their receiver. Anything else, a
+// value from a JavaScript module included, is unresolved, and a helper
+// whose path is unresolved is not read as started through Run. Measured
+// before this: the rule matched a helper by base name in any string
+// literal of the QML, so the plugin's own copy of a script Omarchy starts
+// from its own tree read as Run-started.
+
+import { basename, blankComments, closingBracket, propertyValue, blocks, stringLiteral } from "./text.mjs"
+
+const DEPTH = 12
+const TREE = "@/"
+
+/** Split an expression at a top-level operator, ignoring strings and brackets. */
+function splitTop(text, operator) {
+  const parts = []
+  let depth = 0
+  let quote = null
+  let start = 0
+  for (let index = 0; index < text.length; index += 1) {
+    const ch = text[index]
+    if (quote) {
+      if (ch === "\\") index += 1
+      else if (ch === quote) quote = null
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch
+    else if ("([{".includes(ch)) depth += 1
+    else if (")]}".includes(ch)) depth -= 1
+    else if (depth === 0 && text.startsWith(operator, index) && (operator !== "?" || text[index + 1] !== "?") && (operator !== "+" || text[index + 1] !== "+")) {
+      parts.push(text.slice(start, index))
+      index += operator.length - 1
+      start = index + 1
+    }
+  }
+  parts.push(text.slice(start))
+  return parts.map((part) => part.trim())
+}
+
+/** A normalised tree-relative path from a directory and a relative reference. */
+function joinTree(dir, relative) {
+  const segments = []
+  for (const part of `${dir}/${relative}`.split("/")) {
+    if (part === "" || part === ".") continue
+    if (part === "..") segments.pop()
+    else segments.push(part)
+  }
+  return segments.join("/")
+}
+
+/** The definition of a function named `name` in `text`: its parameters and body. */
+function functionIn(text, name) {
+  const match = new RegExp(`(?<![\\w.])function\\s+${name}\\s*\\(([^)]*)\\)\\s*\\{`).exec(text)
+  if (!match) return null
+  const open = match.index + match[0].length - 1
+  const end = closingBracket(text, open)
+  if (end < 0) return null
+  return { params: match[1].split(",").map((part) => part.trim()).filter(Boolean), body: text.slice(open + 1, end) }
+}
+
+/**
+ * The assignment or declaration of `name` in `text`: the first one, or,
+ * given a site offset `at`, the last one before the site (else the first
+ * after it: a property declared below its use), as expression text.
+ */
+function assignmentIn(text, name, at = undefined) {
+  const patterns = [
+    new RegExp(`(?:const|let|var)\\s+${name}\\s*=\\s*([^\\n;]+)`, "g"),
+    new RegExp(`(?<![\\w.])(?:readonly\\s+)?property\\s+(?:string|var)\\s+${name}\\s*:\\s*([^\\n]+)`, "g"),
+    new RegExp(`(?<![\\w.])${name}\\s*=(?!=)\\s*([^\\n;]+)`, "g"),
+  ]
+  const found = patterns.flatMap((pattern) => [...text.matchAll(pattern)].map((match) => ({ index: match.index, text: match[1].trim() })))
+  if (!found.length) return null
+  const first = found.sort((a, b) => a.index - b.index)[0]
+  if (at === undefined) return first.text
+  const before = found.filter((entry) => entry.index < at).sort((a, b) => b.index - a.index)
+  return (before[0] || first).text
+}
+
+/** The value a parent QML file binds to `name` on an instance of `component`, with the file it sits in. */
+function parentBinding(name, component, files) {
+  for (const file of files) {
+    if (file.kind !== "qml") continue
+    for (const block of blocks(file.text, component)) {
+      const value = propertyValue(block.body, name)
+      if (value && value.text.trim() !== '""') return { text: value.text.trim(), file }
+    }
+  }
+  return null
+}
+
+function resolveCall(callee, inner, scope) {
+  const args = splitTop(inner, ",")
+  if (callee === "Qt.resolvedUrl") {
+    const literal = stringLiteral(args[0] || "")
+    return literal === null ? null : `${TREE}${joinTree(scope.file.path.split("/").slice(0, -1).join("/"), literal)}`
+  }
+  if (callee === "Quickshell.env") {
+    const literal = stringLiteral(args[0] || "")
+    return literal === null ? null : `$${literal}`
+  }
+  if (["String", "decodeURIComponent", "encodeURIComponent"].includes(callee)) return resolve(args[0] || "", scope)
+  const name = callee.split(".").pop()
+  const fn = functionIn(scope.text, name) || functionIn(scope.file.text, name)
+  if (!fn) return null
+  const params = {}
+  fn.params.forEach((param, index) => { params[param] = { text: args[index] || '""', scope } })
+  const inner_scope = { ...scope, text: fn.body, params, depth: scope.depth + 1 }
+  for (const expression of returnsIn(fn.body)) {
+    const value = resolve(expression, inner_scope)
+    if (value !== null) return value
+  }
+  return null
+}
+
+/** Every `return` expression of a body, cut at a newline, a `;` or the `}` that closes an enclosing block. */
+function returnsIn(body) {
+  const found = []
+  for (const match of body.matchAll(/(?<![\w.])return\s+/g)) {
+    let depth = 0
+    let quote = null
+    let end = body.length
+    for (let index = match.index + match[0].length; index < body.length; index += 1) {
+      const ch = body[index]
+      if (quote) {
+        if (ch === "\\") index += 1
+        else if (ch === quote) quote = null
+        continue
+      }
+      if (ch === '"' || ch === "'" || ch === "`") quote = ch
+      else if ("([{".includes(ch)) depth += 1
+      else if (")]}".includes(ch)) { if (depth === 0) { end = index; break } depth -= 1 }
+      else if ((ch === "\n" || ch === ";") && depth === 0) { end = index; break }
+    }
+    found.push(body.slice(match.index + match[0].length, end).trim())
+  }
+  return found
+}
+
+function resolveIdentifier(name, scope) {
+  if (scope.params[name]) return resolve(scope.params[name].text, scope.params[name].scope)
+  const inner = scope.text === scope.file.text ? null : assignmentIn(scope.text, name)
+  if (inner !== null && inner !== '""' && inner !== "''") return resolve(inner, { ...scope, depth: scope.depth + 1 })
+  const outer = assignmentIn(scope.file.text, name, scope.at)
+  if (outer !== null && outer !== '""' && outer !== "''") return resolve(outer, { ...scope, text: scope.file.text, params: {}, depth: scope.depth + 1 })
+  const component = basename(scope.file.path).replace(/\.qml$/, "")
+  const bound = parentBinding(name, component, scope.files)
+  if (!bound) return null
+  return resolve(bound.text, { file: bound.file, files: scope.files, text: bound.file.text, params: {}, depth: scope.depth + 1, at: Infinity })
+}
+
+/**
+ * @returns {string|null} a value: `@/tree/path` for a path under the tree, `$NAME...` for one built on an environment variable, a plain string for a literal; null when the text does not show it
+ */
+export function resolve(text, scope) {
+  const expr = String(text || "").trim().replace(/;$/, "")
+  if (!expr || scope.depth > DEPTH) return null
+  const literal = stringLiteral(expr)
+  if (literal !== null) return literal
+  const ternary = splitTop(expr, "?")
+  if (ternary.length > 1) return resolve(splitTop(ternary.slice(1).join("?"), ":")[0], scope)
+  const either = splitTop(expr, "||")
+  if (either.length > 1) return resolve(either[0], scope)
+  const chain = splitTop(expr, "+")
+  if (chain.length > 1) {
+    const parts = chain.map((part) => resolve(part, scope))
+    return parts.some((part) => part === null) ? null : parts.join("")
+  }
+  if (expr.startsWith("(") && closingBracket(expr, 0) === expr.length - 1) return resolve(expr.slice(1, -1), scope)
+  const method = expr.match(/^(.+)\.(?:replace|trim|toString|toLowerCase|normalize)\s*\(/)
+  if (method && closingBracket(expr, expr.lastIndexOf("(", method[1].length + method[0].length)) === expr.length - 1) return resolve(method[1], scope)
+  const call = expr.match(/^([\w.]+)\s*\(/)
+  if (call && closingBracket(expr, call[0].length - 1) === expr.length - 1) return resolveCall(call[1], expr.slice(call[0].length, -1), scope)
+  if (expr === "Quickshell.shellDir") return "$QUICKSHELL_SHELL_DIR"
+  const identifier = expr.match(/^(?:root\.|this\.|[a-z][\w]*\.)?([A-Za-z_]\w*)$/)
+  if (identifier) return resolveIdentifier(identifier[1], scope)
+  return null
+}
+
+/**
+ * The tree files the QML starts through Run: for every Run site of every
+ * QML file, argv[0] resolved through the text; only a value under the
+ * tree that names a file of the tree counts. Sites whose argv[0] the text
+ * does not show resolve to nothing and mark nothing.
+ *
+ * @param {Array<{ path: string, kind: string, text: string }>} files
+ * @param {Array} processes the process rows, Run sites carrying block: "run"
+ * @returns {{ helpers: Set<string>, resolved: Map<string, string|null> }} helper paths, and per Run site (file:line) what argv[0] resolved to
+ */
+export function runStartedHelpers(files, processes) {
+  const helpers = new Set()
+  const resolved = new Map()
+  const paths = new Set(files.map((file) => file.path))
+  // Comments are blanked first, as every extractor does: an apostrophe in
+  // a comment would otherwise open a string for the bracket matcher.
+  const blanked = files.map((file) => (file.kind === "qml" ? { ...file, text: blankComments(file.text) } : file))
+  for (const row of processes) {
+    if (row.declaredIn !== "qml" || row.block !== "run") continue
+    const file = blanked.find((entry) => entry.path === row.file)
+    const first = Array.isArray(row.argv) ? row.argv[0] : null
+    const at = file ? file.text.split("\n").slice(0, row.line).join("\n").length : 0
+    const value = file && first ? resolve(first, { file, files: blanked, text: file.text, params: {}, depth: 0, at }) : null
+    const path = value && value.startsWith(TREE) ? joinTree("", value.slice(TREE.length)) : null
+    resolved.set(`${row.file}:${row.line}`, path ? `${TREE}${path}` : value)
+    if (path && paths.has(path)) helpers.add(path)
+  }
+  return { helpers, resolved }
+}

package/tools/inspect/inspect.mjs

@@ -25,6 +25,8 @@ import { extractWrites } from "./writes.mjs"
 import { extractTimers } from "./timers.mjs"
 import { extractFunctions } from "./functions.mjs"
 import { evaluatePatterns, heavyShare, overSize, PATTERNS, rankOf, SIZE, sizeScore } from "./patterns.mjs"
+import { recogniseBlockFile, shippedBlocks } from "../blocks/registry.mjs"
+import { runStartedHelpers } from "./helpers.mjs"
 
 export const METHOD = "static extraction, regular expressions over qml and shell; observed, not executed"
 
@@ -43,7 +45,40 @@ export const NOT_VISIBLE = Object.freeze([
 ])
 
 /** The failure codes that mean the target could not be read at all: exit 2, the contract's second status. */
-export const NOT_READABLE = Object.freeze(["subject-not-found", "not-a-git-repository", "commit-not-found", "nothing-to-inspect", "usage"])
+export const NOT_READABLE = Object.freeze(["subject-not-found", "not-a-directory", "not-a-git-repository", "commit-not-found", "nothing-to-inspect", "usage"])
+
+/**
+ * The omakit blocks in the tree, read from the files' own headers and
+ * bodies (tools/blocks/registry.mjs): an unmodified copy of a shipped
+ * block is omakit's code, tested in this repository, and its lines are
+ * not extracted, so it raises no row of its own; a copy whose body is not
+ * one omakit shipped is reported as modified and read like any other file.
+ * A block is complete when every file the shipped block has is present.
+ *
+ * @returns {{ blocks: Array<{ name: string, version: string, shippedVersion: string|null, state: "unmodified"|"modified", complete: boolean, files: Array<{ path: string, state: "unmodified"|"modified", version: string }> }>, skip: Set<string> }}
+ */
+export function recogniseBlocks(files) {
+  const shipped = shippedBlocks()
+  const found = new Map()
+  for (const file of files) {
+    const base = file.path.split("/").pop()
+    const seen = recogniseBlockFile(base, file.text, shipped)
+    if (!seen) continue
+    if (!found.has(seen.name)) found.set(seen.name, { name: seen.name, shippedVersion: seen.shippedVersion, files: [] })
+    found.get(seen.name).files.push({ path: file.path, state: seen.state, version: seen.version })
+  }
+  const blocks = []
+  const skip = new Set()
+  for (const entry of [...found.values()].sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    const expected = shipped.find((block) => block.name === entry.name)?.files.map((file) => file.file) || []
+    const complete = expected.length > 0 && expected.every((name) => entry.files.some((file) => file.path.split("/").pop() === name))
+    const state = entry.files.every((file) => file.state === "unmodified") ? "unmodified" : "modified"
+    const versions = [...new Set(entry.files.map((file) => file.version))]
+    for (const file of entry.files) if (file.state === "unmodified") skip.add(file.path)
+    blocks.push({ name: entry.name, version: versions.length === 1 ? versions[0] : versions.join(", "), shippedVersion: entry.shippedVersion, state, complete, files: entry.files.sort((a, b) => (a.path < b.path ? -1 : 1)) })
+  }
+  return { blocks, skip }
+}
 
 export class InspectError extends Error {
   constructor(code, message, remedy = null) {
@@ -78,6 +113,11 @@ export async function inspectPlugin({ repoRoot, target, offline = false, allowDi
   const pluginId = typeof tree.manifest?.id === "string" ? tree.manifest.id.trim() : null
 
   onPhase("reading processes, hosts, writes and timers")
+  const { blocks, skip } = recogniseBlocks(tree.files)
+  // A `Run {` site is a process only where the tree carries the run block
+  // whole and unmodified; otherwise the name is the plugin's own.
+  const runBlock = blocks.some((block) => block.name === "run" && block.state === "unmodified" && block.complete)
+  const storeBlock = runBlock && blocks.some((block) => block.name === "store" && block.state === "unmodified" && block.complete)
   const processes = []
   const hosts = []
   const writes = []
@@ -85,9 +125,10 @@ export async function inspectPlugin({ repoRoot, target, offline = false, allowDi
   const functions = []
   const notResolvable = []
   for (const file of tree.files) {
+    if (skip.has(file.path)) continue
     // Each function carries its rank among the listed ones (M12).
     functions.push(...extractFunctions(file).map((entry) => ({ ...entry, percentile: rankOf(entry) })))
-    const rows = extractProcesses(file)
+    const rows = extractProcesses(file, { runBlock })
     processes.push(...rows)
     for (const row of rows) {
       if (row.argvForm === "computed") notResolvable.push({ file: row.file, line: row.line, kind: "command", text: `command: ${row.commandText}` })
@@ -95,12 +136,32 @@ export async function inspectPlugin({ repoRoot, target, offline = false, allowDi
     const found = extractHosts(file, rows)
     hosts.push(...found.hosts)
     notResolvable.push(...found.notResolvable)
-    writes.push(...extractWrites(file, { pluginId }))
+    writes.push(...extractWrites(file, { pluginId, storeBlock }))
     const ticking = extractTimers(file)
     timers.push(...ticking.timers)
     notResolvable.push(...ticking.notResolvable)
   }
 
+  // A helper the QML starts through Run runs in the block's closed
+  // environment (PATH=/usr/bin and the named variables, docs/BLOCKS.md),
+  // so a bare tool name inside it is not an ambient PATH lookup. A helper
+  // is one a Run site's argv[0] resolves to through the text
+  // (helpers.mjs): a path the text does not show marks nothing, and only
+  // when every QML process site of the tree is a Run site are its shell
+  // lines marked closedEnvironment. The hook Omarchy runs, a test script,
+  // a helper reached through a value the text does not show: ambient.
+  const qmlSites = processes.filter((row) => row.declaredIn === "qml")
+  const allRun = qmlSites.length > 0 && qmlSites.every((row) => row.block === "run")
+  const started = runStartedHelpers(tree.files, processes)
+  const closed = allRun ? started.helpers : new Set()
+  for (const row of processes) {
+    row.closedEnvironment = row.declaredIn === "shell" && closed.has(row.file)
+    if (row.block === "run") {
+      const value = started.resolved.get(`${row.file}:${row.line}`)
+      row.helper = value && value.startsWith("@/") && started.helpers.has(value.slice(2)) ? value.slice(2) : null
+    }
+  }
+
   let marketplaceBaseline
   let blockingRules = []
   if (offline) {
@@ -138,6 +199,10 @@ export async function inspectPlugin({ repoRoot, target, offline = false, allowDi
       uncommittedFiles: subject.uncommittedFiles,
     },
     observed: { processes, hosts, writes, timers, functions },
+    // The omakit blocks in the tree, by their headers and body hashes: an
+    // unmodified block's files were not read for facts (they are omakit's,
+    // tested here), a modified one's were.
+    blocks,
     // Size: the functions over the M12 thresholds, longest first. A count of
     // lines, branches and nesting over the text, compared with what 90 of
     // 100 functions in listed trees stay under; never a judgement.