@starci/hfs 2.0.1 → 2.0.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 2.0.2 - 2026-10-01
+
+- Fixed: `hfs` printed nothing and checked nothing when started through a node_modules junction or symlink (every lane worktree, some npx shims): the entry-point test compared `argv[1]` with the resolved module path. It now compares real paths (`isMain` of `scripts/checks/common.mjs`, shared by the bin and the architecture entry). Spec: `tests/hfs-cli-worktree.spec.mjs` runs `hfs check` inside a `git worktree add` checkout with a junctioned node_modules and requires a report or a loud refusal.
+
 ## 2.0.1 - 2026-10-01
 
 - Fixed: `hfs sync` validates the whole hfs.json declaration against the manifest before rendering (a pre-2.0 `connections` list of names is refused), so a pin bump can never leave eslint unable to start.

package/bin/hfs.mjs

@@ -35,6 +35,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isMain } from '../runtime/scripts/checks/common.mjs';
 import { checkRepository, explainPath, initRepo, trackedFiles } from '../runtime/scripts/lib/hfs-check.mjs';
 import { HfsSlotsError } from '../runtime/scripts/lib/hfs-slots.mjs';
 import { formatFindings } from '../sync/format.mjs';
@@ -201,4 +202,6 @@ export async function main(argv, { stdout = (s) => process.stdout.write(s), stde
   }
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = await main(process.argv.slice(2));
+// Run when this file is the entry point, compared by real path: through a node_modules junction or an npx shim argv[1] is
+// the junction path while import.meta.url is the resolved one, and a plain comparison silently skipped main (hfs printed nothing).
+if (isMain(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "The HFS command line of a StarCi product repository: hfs check, init, explain, sync and work-hygiene. Self-contained: it carries the runtime files it reads.",
   "type": "module",
   "license": "UNLICENSED",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -57,7 +57,7 @@ pins:
     source: packages/jest-preset/package.json
     why: '2.1.0: four projects on the test world, the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
   '@starci/hfs':
-    version: 2.0.1
+    version: 2.0.2
     group: starci
     install: registry
     side: both

package/runtime/scripts/checks/architecture.mjs

@@ -7,6 +7,7 @@
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {checkArchitecture} from './architecture/index.mjs';
+import { isMain } from './common.mjs';
 
 export {checkArchitecture};
 
@@ -38,4 +39,4 @@ export function architectureMain(argv, {check = checkArchitecture, write = (text
   return report?.ok === true ? 0 : 1;
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = architectureMain(process.argv.slice(2));
+if (isMain(import.meta.url)) process.exitCode = architectureMain(process.argv.slice(2));

package/runtime/scripts/checks/common.mjs

@@ -9,7 +9,14 @@ export function isInside(root, target) {
 }
 
 /** True when this module is the process entry point (`node file.mjs`, not an import). */
-export const isMain = (metaUrl, argv = process.argv) => Boolean(argv[1]) && path.resolve(argv[1]) === fileURLToPath(metaUrl);
+/** The real path of a file, or its resolved path when it cannot be read (a missing file is never the entry module). */
+const realPathOf = (file) => { try { return fs.realpathSync.native(path.resolve(file)); } catch { return path.resolve(file); } };
+/**
+ * True when the module at `metaUrl` is the process entry point. Both sides are compared as REAL paths: Node gives a module
+ * its symlink-resolved URL, while argv[1] keeps the path it was started with, so an entry reached through a node_modules
+ * junction or symlink (a lane worktree, an npx shim) would otherwise look like an import and silently do nothing.
+ */
+export const isMain = (metaUrl, argv = process.argv) => Boolean(argv[1]) && realPathOf(argv[1]) === realPathOf(fileURLToPath(metaUrl));
 
 /**
  * Every entry under `dir` that is not a directory, depth-first; `filter` sees the entry name and full