@fusion.dev/helix-cli 0.205.2 → 0.207.0

package/README.md

@@ -10,8 +10,10 @@ npm install --save-dev @fusion.dev/helix-cli
 
 The command is a native binary, and npm installs the build for your machine
 beside this package: macOS and Linux on Arm and x86-64, and Windows on x86-64.
-An install that skips optional dependencies skips it too, and `helix` then names
-the package it's missing. To start a project rather than add Helix to one, use
+An install that skips optional dependencies skips it too. `helix` then runs a
+`helix` on your `PATH` whose `helix --version --json` names this package, and
+otherwise names the package that is missing and each `helix` it did not run,
+such as the Helix text editor. To start a new project with Helix, use
 `npm create @fusion.dev/helix-app`.
 
 ```sh
@@ -24,10 +26,11 @@ helix mcp init --client claude
 |---|---|
 | `component` | Checks the components you build on Helix's base classes: registration under your prefix, imports, slots, parts, states, hooks, words, reflection, attribute names, lifecycle, and listeners. Reads the folders named by `tiers` in `helix.json`. `--only <rule>` runs some of them |
 | `theme` | `init` a starter intent, `build` it to CSS, `audit` every contrast pair, `check` in CI |
-| `new` | Scaffolds a project from a Helix template |
+| `new` | Scaffolds a project from a Helix template: `helix new my-app --template react-vite`. The templates install with the CLI, in `@fusion.dev/helix-templates`, so `npx @fusion.dev/helix-cli new` works from an empty directory. Omit `--template` to list them |
 | `diagnostics` | Receives the runs `initDiagnostics()` sends from your app and prints each new finding. `--once <url>` opens a page headless instead, diagnoses it, and exits. `--out <path>` writes the CI file, `--port` picks the port, 7417 by default, and `--config <path>` names the settings served to the page |
 | `scan` | Reads your project's stylesheets, templates, and modules, and prints each finding with its file and line. `--build <dir>` weighs each Helix family in your bundle, `--out <path>` writes the run to the CI file, `--config <path>` names the settings, `--file <path>` reports one file's findings, and `--stdin <language>` checks a snippet |
 | `api` | Looks up the installed Helix packages: `find` a family, a `family`'s API, an `example` with its imports, the `imports` for a list of tags, and `tokens` |
+| `manifest` | `diff` compares two custom elements manifests and prints each difference. Exits 1 on any difference |
 | `visual` | Pictures each page in a real browser and compares it with a baseline kept in git: `test`, `update` the baselines, open the `report`, and `compare` two PNG files. Reads `visual.config.ts`, and needs Playwright installed. [The guide](https://github.com/project-fusion/fusion/blob/main/helix/cli/npm/visual/README.md) has the config and the GitHub Action |
 | `mcp` | Serves the same lookups, the scan, and the theme derivation to an agent over stdio, as an MCP server. `mcp init --client <client>` writes the configuration for Claude Code, Cursor, VS Code, Gemini CLI, opencode, Roo Code, or Junie |
 
@@ -40,6 +43,8 @@ Color is already off when stdout is not a terminal and when `NO_COLOR` is set.
 rather than compiled into the binary, so one build serves every release that
 changes no Rust. A binary built from a checkout of this repository has no such
 package beside it and says `0.0.0-dev`, which is what that build is.
+`helix --version --json` prints the same release as
+`{ "name": "helix", "package": "@fusion.dev/helix-cli", "version": … }`.
 
 [Documentation](https://fusion.dev/helix)
 

package/bin.mjs

@@ -13,15 +13,17 @@
  * builds one if it can, and says exactly what is missing if it cannot.
  *
  * **Resolution order, and each step is there for a reason.** `HELIX_BIN` first,
- * because a caller that knows better should not have to argue. Then the cargo
- * target directory, release before debug, honoring `CARGO_TARGET_DIR` because a
- * shared target is common and guessing `./target` would miss it. Then the
- * binary npm installed beside this, which is what a consumer has: after the
- * target, so a checkout runs what it built rather than a binary a release once
- * placed. Then whatever is on `PATH`, named out loud in a checkout, because a
- * binary from somewhere else is about to answer questions about this tree. Only
- * then a build, and only in this repository, the one place there is a crate to
- * build.
+ * because a caller that knows better should not have to argue. Then, in a
+ * checkout, the cargo target directory, release before debug, honoring
+ * `CARGO_TARGET_DIR` because a shared target is common and guessing `./target`
+ * would miss it. Then the binary npm installed beside this, which is what a
+ * consumer has: after the target, so a checkout runs what it built rather than
+ * a binary a release once placed. A consumer's target is never read: a `helix`
+ * there is another program or an old build of ours, and the installed one is
+ * the release they asked for. Then whatever is on `PATH` that says it is this
+ * command line, named out loud in a checkout, because a binary from somewhere
+ * else is about to answer questions about this tree. Only then a build, and
+ * only in this repository, the one place there is a crate to build.
  *
  * **A build is a fallback and not the plan.** It happens once, prints that it
  * is happening, and a CI pipeline that has already run `cargo build` never
@@ -97,7 +99,7 @@ const hasCargo = () => spawnSync('cargo', ['--version'], { stdio: 'ignore' }).st
 const SELF = realpathSync(fileURLToPath(import.meta.url))
 
 /**
- * The first `helix` on `PATH`, resolved through its symlinks, or undefined.
+ * Each `helix` on `PATH`, in order, resolved through its symlinks.
  *
  * **Walked rather than spawned, because the spawn is the bug.** Probing with
  * `spawnSync('helix', ['--version'])` asks `PATH` to answer, and under
@@ -112,8 +114,9 @@ const SELF = realpathSync(fileURLToPath(import.meta.url))
  * trap is set for a fresh clone, which is what CI and a new contributor both
  * are.
  */
-const onPath = () => {
+function* onPath() {
   const extensions = process.platform === 'win32' ? ['', '.exe', '.cmd', '.bat'] : ['']
+  const seen = new Set()
   for (const directory of (process.env.PATH ?? '').split(delimiter)) {
     if (directory === '') {
       continue
@@ -136,13 +139,47 @@ const onPath = () => {
          says nothing about a real one later in it, and returning here would
          make an installed binary invisible whenever a checkout was in front of
          it. */
-      if (real === SELF) {
+      if (real === SELF || seen.has(real)) {
         continue
       }
-      return real
+      seen.add(real)
+      yield real
     }
   }
-  return undefined
+}
+
+/**
+ * Set while this shim runs a `PATH` entry with `--version --json`, so a copy
+ * of this shim run that way uses only the binary it has installed and never
+ * searches `PATH` itself: two copies with no binary between them would
+ * otherwise run each other without end.
+ */
+const PROBE = 'HELIX_SHIM_PROBE'
+
+/**
+ * Whether `binary` is this command line, read from what it prints for
+ * `--version --json`.
+ *
+ * **The name proves nothing.** On Arch Linux `helix` is the Helix text editor,
+ * and an old `cargo install` of this command line has none of the commands a
+ * project runs now, such as `scan`. This command line prints its package's
+ * name for `--version --json`. The editor exits with an error on `--json`, and
+ * an older build prints its plain version line. Measured 10 Oct 2026 on an
+ * Apple silicon laptop: 4 ms for this command line, and 2 ms for an old build.
+ * The timeout ends a program that never exits.
+ */
+const ours = (binary) => {
+  const asked = spawnSync(binary, ['--version', '--json'], {
+    encoding: 'utf8',
+    env: { ...process.env, [PROBE]: '1' },
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 2_000,
+  })
+  try {
+    return JSON.parse(asked.stdout ?? '').package === '@fusion.dev/helix-cli'
+  } catch {
+    return false
+  }
 }
 
 /**
@@ -157,6 +194,27 @@ const DRIVER_ENV = {
   HELIX_VISUAL_RUNTIME: process.env.HELIX_VISUAL_RUNTIME ?? process.execPath,
 }
 
+/**
+ * What `helix new` reads: the `@fusion.dev/helix-templates` this package
+ * depends on, at this package's version, named in `HELIX_TEMPLATES` where the
+ * caller has not named another.
+ *
+ * **Resolved here, because node resolves a dependency the way it was
+ * installed.** The binary walks up from where it runs for a `node_modules`
+ * holding the templates, and `npx @fusion.dev/helix-cli new` runs from a
+ * directory with none: npm installed the command and its dependencies in its
+ * own cache. Under pnpm, or beside another version of the templates in a
+ * project, that walk misses this package's copy as well.
+ */
+try {
+  DRIVER_ENV.HELIX_TEMPLATES ??= dirname(
+    createRequire(import.meta.url).resolve('@fusion.dev/helix-templates/templates.json'),
+  )
+} catch {
+  /* Not installed, so the binary walks up for the templates and names the
+     package when nothing has it. */
+}
+
 const run = (binary) => {
   const { status, error } = spawnSync(binary, process.argv.slice(2), {
     env: DRIVER_ENV,
@@ -183,8 +241,14 @@ const run = (binary) => {
    features per selection, so alternating `-p fusion-helix-cli` with `--workspace`
    recompiled on every switch, about a second each, where asking for the same
    selection twice is 0.14s. `HELIX_BIN` still outranks everything, and a checkout
-   with no cargo falls through to whatever is already built. */
-if (process.env.HELIX_BIN === undefined && checkout && hasCargo()) {
+   with no cargo falls through to whatever is already built, as a probe from
+   another copy of this shim does: it waits two seconds for an answer. */
+if (
+  process.env.HELIX_BIN === undefined &&
+  process.env[PROBE] === undefined &&
+  checkout &&
+  hasCargo()
+) {
   const fresh = spawnSync('cargo', ['build', '--workspace', '--quiet'], {
     cwd: WORKSPACE,
     stdio: 'inherit',
@@ -199,14 +263,24 @@ if (process.env.HELIX_BIN === undefined && checkout && hasCargo()) {
   }
 }
 
-const found = process.env.HELIX_BIN ?? built() ?? packaged()
+const found = process.env.HELIX_BIN ?? (checkout ? built() : undefined) ?? packaged()
 if (found && existsSync(found)) {
   run(found)
 }
 
-/* `PATH`, which is what an installed binary looks like. Resolved rather than
-   probed: see `onPath`, where the probe this used to do is what recursed. */
-const installed = onPath()
+/* `PATH`, which is what an installed binary looks like, walked rather than
+   searched by a spawn: see `onPath`, where a spawn of `helix` recursed. Each
+   one found runs only once `ours` says it is this command line, and the
+   others are named below, where the run gives up. */
+const skipped = []
+let installed
+for (const candidate of process.env[PROBE] === undefined ? onPath() : []) {
+  if (ours(candidate)) {
+    installed = candidate
+    break
+  }
+  skipped.push(candidate)
+}
 if (installed) {
   /* **In a checkout, say which binary this is before running it.** Getting here
      means no `target/`, no platform package and no cargo, so what runs is
@@ -231,6 +305,21 @@ if (installed) {
   run(installed)
 }
 
+/** The `helix` binaries on `PATH` that are some other program, named. */
+const foreign = () => {
+  if (skipped.length === 0) {
+    return ''
+  }
+  const one = skipped.length === 1
+  return (
+    `\n\n  Not run, from PATH: ${skipped.map((path) => `\`${path}\``).join(', ')}.\n` +
+    `  ${one ? 'Its output' : 'The output of each'} for \`--version --json\` does not name\n` +
+    `  \`@fusion.dev/helix-cli\`, so ${one ? 'it is' : 'each is'} another program named helix, such\n` +
+    '  as the Helix text editor, or a build of this command line from before that\n' +
+    '  output.'
+  )
+}
+
 /* Installed from the registry, with no platform package for this machine. A
    build would be `cargo build` in somebody else's project, for a crate that is
    not in it. */
@@ -241,7 +330,7 @@ if (!checkout) {
       '  `@fusion.dev/helix-cli`, and it is not installed. Either this machine is not\n' +
       '  one there is a build for, or the install skipped optional dependencies\n' +
       '  (`--omit=optional`, `--no-optional`), in which case install again without it.\n' +
-      '  `HELIX_BIN` names a binary to run instead.',
+      `  \`HELIX_BIN\` names a binary to run instead.${foreign()}`,
   )
   process.exit(69)
 }
@@ -252,7 +341,7 @@ if (!hasCargo()) {
       `  Looked at: $HELIX_BIN, ${join(target, 'release', NAME)},\n` +
       `             ${join(target, 'debug', NAME)}, and \`${NAME}\` on PATH.\n\n` +
       '  Either install the binary, point `HELIX_BIN` at one, or install a Rust\n' +
-      '  toolchain so this can build it.',
+      `  toolchain so this can build it.${foreign()}`,
   )
   process.exit(69)
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-cli",
   "description": "The Helix command line, for a workspace that reaches it through npm, and the visual tests it runs.",
-  "version": "0.205.2",
+  "version": "0.207.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -29,6 +29,9 @@
     "test": "bun test"
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
+  "dependencies": {
+    "@fusion.dev/helix-templates": "0.207.0"
+  },
   "homepage": "https://fusion.dev",
   "keywords": [
     "helix",
@@ -41,11 +44,11 @@
     "visual-regression"
   ],
   "optionalDependencies": {
-    "@fusion.dev/helix-cli-darwin-arm64": "0.205.2",
-    "@fusion.dev/helix-cli-darwin-x64": "0.205.2",
-    "@fusion.dev/helix-cli-linux-arm64": "0.205.2",
-    "@fusion.dev/helix-cli-linux-x64": "0.205.2",
-    "@fusion.dev/helix-cli-win32-x64": "0.205.2"
+    "@fusion.dev/helix-cli-darwin-arm64": "0.207.0",
+    "@fusion.dev/helix-cli-darwin-x64": "0.207.0",
+    "@fusion.dev/helix-cli-linux-arm64": "0.207.0",
+    "@fusion.dev/helix-cli-linux-x64": "0.207.0",
+    "@fusion.dev/helix-cli-win32-x64": "0.207.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.132",

package/visual/README.md

@@ -159,7 +159,9 @@ export default defineConfig({
   ground it is painted on, in each color scheme the shots picture. The ground
   is composited through every translucent layer, and a ground that is a
   picture or a video is not judged. Text hidden from the accessibility tree is
-  a glyph for the eye, and answers to the 3:1 of a graphic. `rules` names the colors of lines that
+  a glyph for the eye, and answers to the 3:1 of a graphic. The run record
+  lists every ink and ground pair it measured, passing or not, under
+  `painted`, so a project can say which of its colors its pages put together. `rules` names the colors of lines that
   separate, which answer to no target.
 - Each check takes `ignore`, selectors it leaves alone with everything inside
   them, and an exception's `checks` excuses one entry from the checks it names.

package/visual/checks.mjs

@@ -12,11 +12,15 @@
 
 /**
  * Reads the page for the checks `options` turns on: `clipped`, `overlap` and
- * `contrast`, each with its own settings, or absent.
+ * `contrast`, each with its own settings, or absent. Returns the findings,
+ * and every ink and ground pair contrast measured, passing or not, as
+ * `<scheme> <ink> on <ground>` in hex, so a run can say which pairs its pages
+ * paint.
  */
 export const readPage = (page, options) =>
   page.evaluate((options) => {
     const findings = []
+    const pairs = new Set()
 
     /* **Every element, shadow roots included**, because the boxes a component
        lays out for itself are inside one, and the light tree alone holds only
@@ -696,6 +700,7 @@ export const readPage = (page, options) =>
         const wanted =
           !text || drawn || size >= large || (bold && size >= largeBold) ? component : target
         const flat = ink.a === 1 ? ink : over(ink, ground.color)
+        pairs.add(`${scheme} ${hex(flat)} on ${hex(ground.color)}`)
         const measured = ratio(flat, ground.color)
         if (measured < wanted) {
           const line = `${describe(painter)} is ${hex(flat)} on ${hex(ground.color)} in ${scheme}, ${measured.toFixed(2)}:1 against ${wanted}:1: "${sample(element.textContent ?? '')}"`
@@ -712,7 +717,7 @@ export const readPage = (page, options) =>
       window.scrollTo(pageAt[0], pageAt[1])
     }
 
-    return findings
+    return { findings, pairs: [...pairs] }
   }, options)
 
 /**

package/visual/driver.mjs

@@ -230,19 +230,34 @@ const respond = (request, response) => {
  *
  * **Bounded, because `whenDefined` on a tag nothing registers never settles.**
  * Unbounded, a page naming an element the bundle does not define hangs the
- * run with no output. This gives up after five seconds and names the tags.
+ * run with no output. This gives up after {@link UPGRADES} seconds and names
+ * the tags.
  */
 const upgrades = (page, prefix) =>
-  page.evaluate(async (prefix) => {
-    const pending = [
-      ...new Set([...document.querySelectorAll(':not(:defined)')].map((one) => one.localName)),
-    ].filter((tag) => tag.startsWith(prefix))
-    await Promise.race([
-      Promise.all(pending.map((tag) => customElements.whenDefined(tag))),
-      new Promise((done) => setTimeout(done, 5000)),
-    ])
-    return pending.filter((tag) => customElements.get(tag) === undefined)
-  }, prefix ?? '')
+  page.evaluate(
+    async ({ prefix, seconds }) => {
+      const pending = [
+        ...new Set([...document.querySelectorAll(':not(:defined)')].map((one) => one.localName)),
+      ].filter((tag) => tag.startsWith(prefix))
+      await Promise.race([
+        Promise.all(pending.map((tag) => customElements.whenDefined(tag))),
+        new Promise((done) => setTimeout(done, seconds * 1000)),
+      ])
+      return pending.filter((tag) => customElements.get(tag) === undefined)
+    },
+    { prefix: prefix ?? '', seconds: UPGRADES },
+  )
+
+/**
+ * **How long a page has to define its elements after it loads: twenty
+ * seconds**, a third of what one shot may take. The bound only stops a run
+ * hanging on a tag nothing registers, and a page that registers late is slow,
+ * which a picture does not judge. Five seconds failed the site's theme builder
+ * on two CI runs in a row on October 10, 2026: its first style pass over
+ * 15,638 elements and Helix's chunk took 1.7 seconds on an M-series Mac, and a
+ * shared runner takes several times that.
+ */
+const UPGRADES = 20
 
 /**
  * Waits for the page to hold still: three frames, the fonts, each element's
@@ -397,6 +412,8 @@ const take = async (lane, item, { elements, readyProperty }, progress) => {
   let error = null
   let problems = []
   let findings = []
+  /* Every ink and ground pair contrast measured on the page. */
+  let painted = []
   let aria = null
   /* The color schemes contrast has been read in. */
   const read = new Set()
@@ -422,7 +439,7 @@ const take = async (lane, item, { elements, readyProperty }, progress) => {
         const missing = await upgrades(page, elements)
         if (missing.length > 0) {
           throw new Error(
-            `nothing defines ${missing.map((tag) => `<${tag}>`).join(', ')}, after five seconds of waiting`,
+            `nothing defines ${missing.map((tag) => `<${tag}>`).join(', ')}, after ${UPGRADES} seconds of waiting`,
           )
         }
       } else if (shot.harness !== null) {
@@ -488,13 +505,13 @@ const take = async (lane, item, { elements, readyProperty }, progress) => {
       if ((index === 0 && (item.checks?.clipped || item.checks?.overlap)) || contrast) {
         progress.stage = 'reading the page'
         read.add(shot.scheme)
-        findings = findings.concat(
-          await readPage(page, {
-            clipped: index === 0 ? (item.checks.clipped ?? null) : null,
-            contrast: contrast ? { ...item.checks.contrast, scheme: shot.scheme } : null,
-            overlap: index === 0 ? (item.checks.overlap ?? null) : null,
-          }),
-        )
+        const reading = await readPage(page, {
+          clipped: index === 0 ? (item.checks.clipped ?? null) : null,
+          contrast: contrast ? { ...item.checks.contrast, scheme: shot.scheme } : null,
+          overlap: index === 0 ? (item.checks.overlap ?? null) : null,
+        })
+        findings = findings.concat(reading.findings)
+        painted = painted.concat(reading.pairs)
       }
       if (index === 0 && item.aria) {
         progress.stage = 'taking its accessibility snapshot'
@@ -526,6 +543,7 @@ const take = async (lane, item, { elements, readyProperty }, progress) => {
     findings,
     key: item.key,
     op: 'item',
+    painted,
     problems,
     seconds,
   })