omakit 0.6.7 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "Tested plumbing, the marketplace's own checks, and a disposable Omarchy to test in.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

package/skills/omarchy-plugin-build/SKILL.md

@@ -164,4 +164,8 @@ that asked for each are in `docs/BLOCKS.md`; the ones that shape the call:
 `omakit inspect` lists an unmodified store block as one row and each
 `Store {}` site as a write under a directory the plugin controls at mode
 0600; a `FileView` write or a shell redirect that remains names a site
-that still keeps state on its own.
+that still keeps state on its own. A `cp`, `mv`, `install` or `ln` to a
+variable destination is not state Store keeps: the file goes wherever
+the variable points (a hook, a wallpaper), and no block covers that yet;
+the review's requirements for the class are in `docs/MEASUREMENTS.md`
+(M11).

package/tools/blocks/commit.json

@@ -1,5 +1,5 @@
 {
-  "commit": "5dd9db1969775b87b10f21445570557cf82e8073",
-  "recordedAt": "2026-09-21T20:24:57.368Z",
+  "commit": "0c11dd5671c8ed65a89ea71a2bf44ab5f38b1a90",
+  "recordedAt": "2026-09-23T07:35:32.560Z",
   "how": "Written by `node tools/blocks/record-commit.mjs` in the release workflow before `npm pack`, so a packaged omakit, which has no Git checkout, still names the commit its block files come from. In a checkout this file is null and `git rev-parse HEAD` is the source; a package with null here was packed without the release step, and `omakit add` refuses to stamp a header it cannot name."
 }

package/tools/inspect/contract.mjs

@@ -14,7 +14,7 @@ const ARGV_FORMS = new Set(["array", "string", "computed"])
 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 CONTROLLED = new Set(["observed", "not-observed", "variable", "unknown"])
 const DECLARED_IN = new Set(["qml", "shell"])
 const FILE_KINDS = ["qml", "js", "shell", "python", "other"]
 
@@ -83,9 +83,10 @@ function write(row, at, problems) {
   if (!isString(row.path)) problems.push(`${at}.path is not a string`)
   if (!nullOr(isString)(row.canonicalPath)) problems.push(`${at}.canonicalPath is neither a string nor null`)
   if (!isString(row.via)) problems.push(`${at}.via is not a string`)
-  if (!CONTROLLED.has(row.controlledDirectory)) problems.push(`${at}.controlledDirectory is not observed, not-observed or unknown`)
+  if (!CONTROLLED.has(row.controlledDirectory)) problems.push(`${at}.controlledDirectory is not observed, not-observed, variable or unknown`)
   if ((row.controlledDirectory === "observed") !== isString(row.controlledBy)) problems.push(`${at}.controlledBy names a directory exactly when controlledDirectory is observed`)
   if (row.canonicalPath === null && row.controlledDirectory !== "unknown") problems.push(`${at}.controlledDirectory is decided for a path that could not be read`)
+  if (row.controlledDirectory === "variable" && (!/^\$(?:[A-Za-z_]\w*|\d)\/?$/.test(row.canonicalPath ?? "") || /^\$(?:HOME|XDG_)/.test(row.canonicalPath))) problems.push(`${at}.controlledDirectory is variable for a path that is not one variable other than $HOME and the XDG names`)
   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`)

package/tools/inspect/patterns.mjs

@@ -51,6 +51,39 @@ function pathResolved(process) {
   return tool
 }
 
+/**
+ * The verbs that put a file at a destination the caller names. A write by
+ * one of them whose destination is one variable (`cp "$src" "$dest"`) is
+ * the shape of both file-boundary blockers in one review thread,
+ * `install-wallpaper.sh` (`cp -f`, 2026-09-11) and `install-hook.sh`
+ * (`cp`, 2026-09-22), and the class cited neither copy: the path was
+ * `unknown`, with 52 of that tree's 54 writes. A link planted at the
+ * destination picks where the file lands for all four, measured on GNU
+ * coreutils 9.11: `cp` writes through a link to a file, and all four put
+ * the file inside a linked directory. A redirect or `tee` onto a variable
+ * is left out, measured over 15 plugin trees on 2026-09-23: 28 writes by
+ * these four verbs to a variable, against 61 redirects and tees, 24 of
+ * them `>>` appends to a log (docs/MEASUREMENTS.md, M11).
+ */
+const PLACING = new Set(["cp", "mv", "install", "ln"])
+
+/**
+ * The writes the file and state boundary class cites, by what it cites
+ * them for. Each test reads one row alone, so the report can ask it of the
+ * rows at one site and show the write the class cited there, not another
+ * write on the same line (`printf ... > "$f.tmp" && mv "$f.tmp" "$f"`).
+ */
+export function boundaryWrites(writes) {
+  return {
+    outside: writes.filter((row) => row.controlledDirectory === "not-observed" && row.via !== "mktemp"),
+    placed: writes.filter((row) => row.controlledDirectory === "variable" && PLACING.has(row.via)),
+    unmoded: writes.filter((row) => row.via === "mkdir" && row.mode === null),
+  }
+}
+
+/** Words as a list a person reads, in the order given: "cp", "cp and ln", "mv, cp and ln". */
+const listed = (words) => (words.length > 1 ? `${words.slice(0, -1).join(", ")} and ${words.at(-1)}` : words[0])
+
 const SECRET = /authorization|bearer|token=|api[_-]?key|password|secret=/i
 const PRIVILEGED = new Set(["sudo", "pkexec", "doas", "docker"])
 
@@ -210,17 +243,17 @@ export const PATTERNS = Object.freeze([
   {
     id: "file-and-state-boundary",
     label: "file and state boundary",
-    notObserved: "no write outside a controlled directory",
+    notObserved: "no write outside a controlled directory or by cp, mv, install or ln to a variable, no mkdir without a mode",
     measurement: "M11",
     share: 0.15,
     sample: SAMPLE,
     precondition: ({ writes }) => {
-      const outside = writes.filter((row) => row.controlledDirectory === "not-observed" && row.via !== "mktemp")
-      const unmoded = writes.filter((row) => row.via === "mkdir" && row.mode === null)
+      const { outside, placed, unmoded } = boundaryWrites(writes)
       const parts = []
       if (outside.length) parts.push(`${plural(outside.length, "write")} outside a controlled directory (${sites(outside)})`)
+      if (placed.length) parts.push(`${plural(placed.length, "write")} by ${listed([...new Set(placed.map((row) => row.via))])} to a variable destination, not resolvable to a controlled directory (${sites(placed)})`)
       if (unmoded.length) parts.push(`${plural(unmoded.length, "mkdir")} with no mode (${sites(unmoded)})`)
-      return { sites: [...outside, ...unmoded].map(site), observation: `observed ${parts.join("; ")}` }
+      return { sites: [...outside, ...placed, ...unmoded].map(site), observation: `observed ${parts.join("; ")}` }
     },
   },
   {

package/tools/inspect/report.mjs

@@ -19,7 +19,7 @@
 
 import { colourEnabled, field, GUTTER, INSPECT_VERDICT, mark, outputColumns, styler, verdict, wrap } from "../marketplace/style.mjs"
 import { withHomeAbbreviated } from "../marketplace/paths.mjs"
-import { PATTERNS, SIZE } from "./patterns.mjs"
+import { boundaryWrites, PATTERNS, SIZE } from "./patterns.mjs"
 
 const NOTHING = "observed nothing of this kind"
 
@@ -110,7 +110,9 @@ function writeRow(write, c) {
     ? `observed (${write.controlledBy})`
     : write.controlledDirectory === "not-observed"
       ? `not observed${write.temp ? ` (${write.canonicalPath.split("/").slice(0, 2).join("/")} is shared)` : ""}`
-      : "unknown (path not readable as a literal prefix)"
+      : write.controlledDirectory === "variable"
+        ? `not resolvable (${write.canonicalPath} is a variable)`
+        : "unknown (path not readable as a literal prefix)"
   const notes = [`under a directory the plugin controls: ${where}`]
   if (write.mode) notes.push(`mode ${write.mode}`)
   return row("info", site(write), what, c, [notes.join("; ")])
@@ -207,7 +209,7 @@ function commandLine(process) {
 }
 
 /**
- * The fact at a site, in one line: the write there for the file class, the
+ * The fact at a site, in one line: the write the file class cited there, the
  * host there for the egress class, otherwise the command, then the host,
  * then the write, whichever the site has.
  */
@@ -222,7 +224,9 @@ function factAt(document, at, patternId) {
     return row ? `${row.scheme}://${row.host}${row.tool ? ` via ${row.tool}` : ""}` : ""
   }
   const write = () => {
-    const row = document.observed.writes.find(same)
+    // On a line with two writes, the one the file class cited, not the first.
+    const here = document.observed.writes.filter(same)
+    const row = (patternId === "file-and-state-boundary" ? Object.values(boundaryWrites(here)).flat()[0] : null) ?? here[0]
     return row ? `${row.via} ${row.canonicalPath ?? row.path}` : ""
   }
   const order = patternId === "file-and-state-boundary" ? [write, process, host] : patternId === "network-egress" ? [host, process, write] : [process, host, write]

package/tools/inspect/writes.mjs

@@ -3,7 +3,11 @@
 // or `touch` in shell; `writeFile` and its variants in JavaScript; `open()`
 // for writing in Python. Each row says whether the path's literal prefix,
 // after the `$HOME`, `~` and `XDG_*` idioms are expanded, falls under a
-// directory the plugin controls, and which mode the file shows for it.
+// directory the plugin controls, and which mode the file shows for it. A
+// path that is one variable and nothing else (`$dest`, `$2`, `$target/`)
+// is said apart from any other path the classification cannot place: the
+// write names no directory, and the extraction follows no assignment to
+// find one.
 
 import { basename, blankComments, blocks, closingBracket, lineOf, propertyValue, blankShellExpressions, shellLogicalLines, shellPieces, shellWords, stringLiteral, withoutRedirections } from "./text.mjs"
 
@@ -11,6 +15,8 @@ import { basename, blankComments, blocks, closingBracket, lineOf, propertyValue,
 export const CONTROLLED = Object.freeze(["$XDG_STATE_HOME", "$XDG_CACHE_HOME", "$XDG_RUNTIME_DIR"])
 export const SHARED_TEMP = Object.freeze(["/tmp", "/var/tmp", "/dev/shm"])
 const DEVICES = new Set(["/dev/null", "/dev/stderr", "/dev/stdout", "/dev/tty"])
+/** A canonical path that is one variable expansion, a name or a positional parameter, with at most a trailing slash. */
+const VARIABLE = /^\$(?:[A-Za-z_]\w*|\d)\/?$/
 
 /**
  * A path's literal prefix in canonical form: `~` and `$HOME` idioms,
@@ -45,8 +51,12 @@ export function canonicalPath(raw) {
 }
 
 /**
- * Whether a canonical path is under a directory the plugin controls.
- * @returns {{ controlledDirectory: "observed"|"not-observed"|"unknown", controlledBy: string|null, temp: boolean }}
+ * Whether a canonical path is under a directory the plugin controls:
+ * `variable` when the path is one variable other than `$HOME` and the XDG
+ * names, so the write names no directory; `unknown` for any other path it
+ * cannot place, an expression, a relative path or a path under a variable
+ * (`$dir/name`).
+ * @returns {{ controlledDirectory: "observed"|"not-observed"|"variable"|"unknown", controlledBy: string|null, temp: boolean }}
  */
 export function classifyPath(path, pluginId) {
   if (path === null || path === undefined) return { controlledDirectory: "unknown", controlledBy: null, temp: false }
@@ -59,6 +69,7 @@ export function classifyPath(path, pluginId) {
     if (path === prefix || path.startsWith(`${prefix}/`)) return { controlledDirectory: "not-observed", controlledBy: null, temp: true }
   }
   if (path.startsWith("/") || path.startsWith("$HOME") || path.startsWith("$XDG_")) return { controlledDirectory: "not-observed", controlledBy: null, temp: false }
+  if (VARIABLE.test(path)) return { controlledDirectory: "variable", controlledBy: null, temp: false }
   return { controlledDirectory: "unknown", controlledBy: null, temp: false }
 }
 
@@ -126,21 +137,31 @@ function pythonWrites(file, pluginId) {
   return rows
 }
 
-/** The words that are not options, and the value of `-m`/`--mode` when one is given. */
-function operands(all) {
+/**
+ * The words that are not options, the value of `-m`/`--mode` when one is
+ * given, and, with `targets`, of `-t`/`--target-directory`: for `cp`, `mv`,
+ * `install` and `ln` that directory is the destination, and every operand
+ * a source.
+ */
+function operands(all, { targets = false } = {}) {
   const words = withoutRedirections(all)
   const out = []
   let mode = null
+  let target = null
   for (let index = 1; index < words.length; index += 1) {
     const word = words[index]
     if (word === "-m" || word === "--mode") {
       mode = words[index + 1] ?? null
       index += 1
     } else if (word.startsWith("--mode=")) mode = word.slice("--mode=".length)
+    else if (targets && (word === "-t" || word === "--target-directory")) {
+      target = words[index + 1] ?? null
+      index += 1
+    } else if (targets && word.startsWith("--target-directory=")) target = word.slice("--target-directory=".length)
     else if (word.startsWith("-") && word !== "-") continue
     else out.push(word)
   }
-  return { operands: out, mode }
+  return { operands: out, mode, target }
 }
 
 function shellWrites(file, pluginId) {
@@ -179,8 +200,9 @@ function shellWrites(file, pluginId) {
         const { operands: paths, mode } = operands(words)
         for (const path of paths) rows.push(row(file, line, path, command, pluginId, mode))
       } else if (["cp", "mv", "install", "ln"].includes(command)) {
-        const { operands: paths, mode } = operands(words)
-        if (paths.length >= 2) rows.push(row(file, line, paths[paths.length - 1], command, pluginId, mode))
+        const { operands: paths, mode, target } = operands(words, { targets: true })
+        if (target !== null && paths.length >= 1) rows.push(row(file, line, target, command, pluginId, mode))
+        else if (paths.length >= 2) rows.push(row(file, line, paths[paths.length - 1], command, pluginId, mode))
       } else if (command === "mktemp") {
         const { operands: paths } = operands(words)
         const template = paths[0] || (words.includes("-p") ? `${words[words.indexOf("-p") + 1]}/tmp.XXXXXX` : "/tmp/tmp.XXXXXX")