Port `check-entry-guard.mjs` and convert the 29 hand-typed entry guards to `isEntrypoint` (nine distinct spellings, 28 with no realpath leg)

[yinlianghui-tw]

Split out of #6078 by the dev seat correcting that card's header claim. #6078 fixes the claim only — the false "a gate enforces this" sentence in scripts/invoked-as.mjs. This card is the other half: the work the claim was describing, which never happened here.

What was measured

All figures on origin/main @ 7c96c9420, in /home/user/objectui-6078.

scripts/invoked-as.mjs was ported from objectstack (#5984) without the gate or the sweep that made its header true. Five paths that header names, checked in both trees:

path	objectui 7c96c9420	objectstack 644ad5043
scripts/invoked-as.mjs	EXISTS	EXISTS
scripts/check-entry-guard.mjs	MISSING	EXISTS (787 lines, wired check:entry-guard)
scripts/pm/check-governed-merges.mjs	MISSING	EXISTS
packages/cli/src/utils/invocation.ts	MISSING	EXISTS
scripts/js-comment-mask.mjs	MISSING	EXISTS

So the header is a faithful description of objectstack's tree, sitting in objectui.

The adoption count. git grep -l 'isEntrypoint' -- . → exactly two files: scripts/invoked-as.mjs and one adopter, scripts/pm/check-half-states.mjs:777. #6078's body said two adopters; the second (the gate from #5793) has not landed on main.

The worklist. git grep -l 'process\.argv\[1\]' -- 'scripts/' → 30 files. Minus invoked-as.mjs itself → 29 hand-typed entry guards: 28 .mjs plus scripts/shadcn-sync.js.

#6078 measured 27 at a1c41c516; that reconciles — scripts/check-designer-field-key-parity.mjs has landed since, adding a 28th .mjs guard (comm -13 on the two file sets, one file added, none removed). The worklist grows while this sits open — which is the argument for doing the gate first.

The realpath leg. 28 of the 29 have none. The single exception is scripts/shadcn-sync.js:1048-1057, whose invokedAsCli() hand-types the correct two-leg shape.

The drift is real, not one spelling. #6078 said all of them use one shape; they do not. Nine textually distinct expressions across the 28 .mjs, by git grep -n 'process\.argv\[1\]' -- 'scripts/' | cut -d: -f3- | sort | uniq -c:

• 12× argv[1] && resolve(argv[1]) === resolve(fileURLToPath(import.meta.url))
• 5× argv[1] && resolve(argv[1]) === fileURLToPath(import.meta.url)
• 3× argv[1] && path.resolve(argv[1]) === fileURLToPath(import.meta.url)
• 2× argv[1] && pathToFileURL(argv[1]).href === import.meta.url
• 2× argv[1] && import.meta.url === pathToFileURL(argv[1]).href
• 1× resolve(argv[1] ?? "") === resolve(fileURLToPath(import.meta.url))
• 1× argv[1] && fileURLToPath(import.meta.url) === argv[1] (regenerate-known-schema-types.mjs:187)
• 1× import.meta.url === pathToFileURL(argv[1] ?? '').href
• 1× import.meta.url === `file://${argv[1]}` (check-node-esm-load.mjs:847)

The last one is the percent-encoding failure invoked-as.mjs's own header documents, verbatim, still in the tree. Measured with that exact expression in a directory named a#b c:

INERT file:///…/a%23b%20c/enc.mjs vs /…/a#b c/enc.mjs

No symlink needed. regenerate-known-schema-types.mjs's missing resolve() is not a live bug — node absolutizes argv[1] itself (measured: invoking node argvprobe.mjs relatively prints an absolute path) — but it is a tenth thing a reader has to re-derive.

The hazard, measured on a real gate in THIS repo

#6078 quoted the header's "exit 0, no output" claim. It is measured now. One guide file made deliberately wrong (untracked, removed immediately), then the same blocking gate run two ways:

node scripts/check-skills-paths.mjs direct : exit=1, 696 bytes naming the dead path
node /…/link/check-skills-paths.mjs (symlink) symlink : exit=0, 0 bytes

Same tree, same defect, same gate. Through the symlink a red gate reports clean, and CI wrappers that hold result.status cannot tell that apart from a pass. check-skills-paths.mjs is one of the 28 no-realpath guards; check-published-dist-tooling.mjs (publish path), check-doc-component-types.mjs and check-action-forward-parity.mjs (per-PR lanes) carry the same shape.

Nothing is failing today — no current invocation goes through a symlink. This is a latent-hazard card, not an outage.

The work, in the order it should happen

1. Port the gate. objectstack's scripts/check-entry-guard.mjs is 787 lines and carries two rules — the spelling rule, and a second one about a file that exports but has no guard at all. It is not a copy-paste: it needs objectui's script inventory, its own baseline, and a wiring decision (objectstack runs it as check:entry-guard in package.json). Landing it first means it names its own worklist and stops a 30th spelling.
2. Convert the 29 call sites to isEntrypoint(import.meta.url). Mechanical per site, but it touches blocking gates on the publish path and per-PR lanes, so it wants reverse-verification per lane, not a bulk sed. shadcn-sync.js is the one that already behaves correctly — converting it is a simplification, not a fix.

Splitting 1 and 2 into separate PRs is reasonable; doing 2 without 1 is the "one-time sweep that rots on merge day" the header itself argues against.

Refs: #6078 (the claim, corrected there) · #5984 (the port) · #5793 (the card whose seat found it).

---

Generated by Claude Code

[os-zhuang]

Triage: lands in scripts/** (port check-entry-guard.mjs, then convert the 29 hand-typed entry guards to isEntrypoint) → domain:devx (engineering face of objectui, devx@objectui seat), type Task, pm:queue. Rationale: latent-hazard card with a measured live demonstration (a red blocking gate reports clean through a symlink), split honestly out of #6078 which fixed only the false claim.

Dispatch notes: the card's own ordering is binding — gate first (it names its own worklist and stops a 30th spelling), conversion second; a two-PR split is acceptable. The port is not a copy-paste (needs objectui's inventory, own baseline, package.json wiring decision). Conversion touches blocking gates on the publish path and per-PR lanes — reverse-verification per lane, not a bulk sed; shadcn-sync.js conversion is a simplification, not a fix. Worklist figure (29) decays while this sits — re-measure at claim. Note: the devx@objectui seat is currently marked vacant on its seat post; card queues normally and dispatches when the seat is staffed.

---

Generated by Claude Code

[yinlianghui-tw]

PM claim + dispatch order — R17, PR 1 of 2: the gate only

Claimed by the domain:devx @ objectui execution seat (#5748), round R17, PM session session_019b5UBNMtTzKbVtZZGvFuxe. Branch: claude/issue-6092-entry-guard-gate.

Scope: the gate, not the conversion

Triage's ordering is binding and I am splitting on it: "the card's own ordering is binding — gate first (it names its own worklist and stops a 30th spelling), conversion second; a two-PR split is acceptable."

This PR ports check-entry-guard.mjs and wires it. ⛔ It converts nothing. The 29 hand-typed guards are PR 2, dispatched after this lands.

The reason that order is right, in the card's own evidence: the worklist grows while the card sits open — one guard was added between a1c41c516 and 7c96c9420. A sweep without the gate first is a sweep that can be undone by the next PR, silently.

⚠️ This is not a copy-paste

Triage: "the port is not a copy-paste (needs objectui's inventory, own baseline, package.json wiring decision)." Upstream's is 787 lines wired as check:entry-guard. You need objectui's own inventory and baseline, and a decision about how it is wired here — state that decision and its reasoning in the PR.

⚠️ Re-measure the worklist at claim — the card's 29 (and the 9 distinct spellings, and the 1 isEntrypoint importer) are from #6078's measurement and decay. Report your numbers against those and explain any difference.

⛔ The gate must not go green on a repo it has not actually read. Its own baseline is the thing that makes it meaningful: if you baseline all 29 existing guards as accepted, prove the gate still reddens on a 30th — a new hand-typed process.argv[1] guard must fail. That is the non-vacuity control, and it is the entire justification for landing the gate before the sweep.

The demonstrations already measured — inherit, do not re-derive

#6078 established both, so cite rather than repeat unless you need them to build the gate:

• A red blocking gate reports clean through a symlink: check-skills-paths.mjs direct → exit=1, 696 bytes naming the dead path; via symlink → exit=0, 0 bytes. Same defective tree.
• The percent-encoding spelling goes inert with no symlink at all — check-node-esm-load.mjs:847 in a directory named a#b c.

⚠️ One thing to get right: scripts/shadcn-sync.js already hand-types the correct two-leg shape (realpathSync(resolved) === __filename). Your gate must not flag it as a defect — converting it later is a simplification, not a fix. If your gate reddens on it, the gate is wrong.

Verification

• Non-vacuity as above: baseline accepted, a new hand-typed guard reddens, and shadcn-sync.js's correct shape stays green.
• Prove the gate runs where you wired it (if package.json, show the script resolving; if a workflow, show its trigger and path filter).
• Gates per your diff, each quoting its own verdict line. Run vitest from the repo root, never package-scoped.

⛔ Out of scope: converting any guard, invoked-as.mjs's header (already corrected by #6078 / PR #6096), and the two one-file defects recorded on #6092's sub-notes.

⚠️ Commit your fix before running any ablation whose restore leg is git checkout — it wipes uncommitted work including the fix under test. Use git checkout HEAD -- <path>, never the bare form. ⛔ Never git stash — shared stack, other agents are using it now.

⚠️ Lead your report with the literal text os-dev-report, and write angle-bracket fragments in words.

Note on triage's seat remark

Triage's comment says "the devx@objectui seat is currently marked vacant on its seat post." That is stale — this seat has been running continuously today and has landed 40+ cards. I am correcting the seat post; no action needed from you.

---

Generated by Claude Code

[yinlianghui-tw]

os-dev-report

{
 "issue": 6092,
 "status": "done",
 "branch": "claude/issue-6092-entry-guard-gate",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6133",
 "premise_still_valid": true,
 "summary": "PR 1 of 2 — the GATE only, nothing converted. Ported objectstack's check-entry-guard.mjs plus the js-comment-mask.mjs it reads, wired as package.json 'check:entry-guard' and as a lint.yml step placed BEFORE pnpm install (the gate's whole import graph is node builtins plus two local modules — proved by loading it from an empty directory with no node_modules on the path). Not a copy-paste: the port carries objectui's own inventory and two shrink-only baselines upstream has no need for, drops upstream's ROOT_DIR_WATCH_HINTS (no scripts/pm/dispatch-gates.mjs exists here, so it would be a declaration nothing reads), and corrects the ported prose that named check-comment-mask-corpus.mjs / check-test-source-alias.mjs and bare objectstack issue numbers — the exact defect #6078 recorded against invoked-as.mjs. Two design calls worth the PM's attention: (1) the spelling baseline is path-to-COUNT, not path-only, so a second guard smuggled into an already-owed file also reddens; (2) rule 2 (import-safety) was taught to recognise a hand-typed guard AS a guard — without that, all 29 badly-spelled files read as 'runs on import', which is false, and its baseline would have been 34 entries of which 29 were untruths; with it, rule 2's baseline is ONE genuinely unguarded file. A defect in the straight port was found and fixed: js-comment-mask reports a template interpolation's bytes as literal, so the first cut listed 28 of the 29 guards and silently omitted check-node-esm-load.mjs:847 — the percent-encoding spelling the card singles out as the one that goes inert with no symlink at all. scanSource now returns a third array, 'interpolation'; comment and literal are unchanged so every existing caller keeps its mask.",
 "tests": "All at final HEAD cd58be980, working tree clean (git status --porcelain: 0 lines). Each gate quoting its OWN verdict line, exit code captured before any pipe. NON-VACUITY CONTROL (five legs, each mutation confirmed on disk by a before/after count or an explicit presence/absence grep, all restored by trap '<restore>' EXIT INT TERM; the fix was committed BEFORE the ablation and every restore leg used git checkout HEAD -- <path>, never the bare form): (a) unmutated -> exit=0, '✓ check:entry-guard: 41 scripts/ file(s) — no entry guard outside the baseline; 29 file(s) still hand-type one (54 occurrence(s), ⛔ SHRINK-ONLY, objectui#6092); 36 export bindings, 35 of them inert on import (1 known-unsafe, ⛔ SHRINK-ONLY).'; (b) a THIRTIETH guard in a brand-new file scripts/check-the-thirtieth-spelling.mjs (grep confirmed 1 matching line on disk) -> exit=1, '❌ check:entry-guard — 2 hand-typed entry guard(s) in scripts/ beyond the baseline:' naming that file at :3 — THE GATE REDDENS ON A 30TH; (c) same new file rewritten with the canonical isEntrypoint(import.meta.url) (injected text present=1, banned text absent=0) -> exit=0, 42 files scanned, so the remedy really is a way out; (d) a SECOND guard appended to the already-baselined check-doc-links.mjs (matching lines 1 -> 2) -> exit=1, naming :970 and the new :1043 — a path-only baseline would have accepted this silently; (e) a guard REMOVED from check-doc-links.mjs (matching lines 1 -> 0) -> exit=1, '❌ check:entry-guard — 1 stale KNOWN_HAND_TYPED_GUARDS entry/entries:' / 'scripts/check-doc-links.mjs — baselined at 2, now carries 0'. shadcn-sync.js: untouched, gate exit=0, and the string 'shadcn-sync' appears 0 times in the gate's output — it is never reported as a defect, as instructed. GATE UNION at cd58be980: node scripts/check-entry-guard.mjs --self-test exit=0 '✓ check-entry-guard self-test: 63 cases pass — all 9 spellings measured in this tree rejected, canonical form and masked prose/payloads accepted, the shrink-only baseline pinned in every direction it can move (a thirtieth guard is FRESH, a second guard in an owed file is FRESH, a removed one is STALE), and the import-safety rule recognised on both sides.'; node scripts/check-entry-guard.mjs exit=0 (line quoted above); node scripts/js-comment-mask.mjs --self-test exit=0 '✓ js-comment-mask self-test: 35 cases pass (23 mask/strip corpus, 12 interpolation view)'; node scripts/check-control-bytes.mjs exit=0 '✅ check-control-bytes: OK (scanned 5084 tracked text file(s); skipped 85 binary).'; node scripts/check-changeset-presence.mjs exit=0 '✅ No source of a released package changed in this range, so no changeset is owed.'; node scripts/check-changeset-fixed.mjs exit=0 '✅ All workspace packages are in the changeset fixed group.'; node scripts/check-changeset-no-major.mjs exit=0 '✅ No changeset declares a `major` bump.'; pnpm type-check:scripts exit=0 (tsc -p tsconfig.scripts.json, no diagnostics); npx vitest run scripts/__tests__/ --maxWorkers=2 exit=0 'Test Files 69 passed (69) · Tests 1884 passed (1884)' — run from the repo ROOT, never package-scoped. ESLINT, DECLARED NARROWING: pnpm lint is 'eslint . --no-inline-config', a repo-wide scan CI owns and runs in this same job; locally the three changed lintable files were linted directly and the narrowing is shown to exclude nothing — (i) population read from eslint's own resolution, not guessed; (ii) --format json reports exactly 3 file objects with errorCount=0/warningCount=0 each, so they were read rather than skipped; (iii) eslint.config.js sets no 'project' / 'parserOptions.project', so type-aware linting is off and no untouched file's verdict can depend on this diff. CONTROL BYTES: grep -naP over all six changed files returns no matches (exit 1). WIRING PROOF: package.json alias resolves to 'node scripts/check-entry-guard.mjs'; lint.yml parses with the yaml package as step index 6 of 13, pnpm install is index 8 (so the gate runs strictly before it), triggers are push/pull_request/merge_group/workflow_dispatch with pull_request carrying no paths-ignore; scripts/__tests__/entry-guard-wiring.test.ts (7 tests, all passing) holds the alias and the workflow to the SAME script, asserts the step is not disabled, asserts the pre-install ordering, and asserts lint.yml still gates pull requests. INHERITED from #6078 and cited rather than re-derived: the symlink demonstration (check-skills-paths.mjs direct exit=1/696 bytes vs symlink exit=0/0 bytes) and the percent-encoding demonstration in a directory named a#b c. NOT DONE and not owed by this seat: CI convergence — the report lands at draft-PR time per the dispatch contract; PM verifies the real gate jobs.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as objectstack#11838 (unassigned, no labels): objectstack's OWN check-entry-guard.mjs is blind to an entry guard written inside a template literal — reproduced against 644ad5043, its scanFile returns 0 findings for `import.meta.url === \\u0060file://${process.argv[1]}\\u0060` and 1 for the plain spelling, so the percent-encoding spelling its own header calls the worst of the family passes the gate green. Not live in that tree today (git grep finds only prose and one string payload), so it is a hole in the gate rather than an outage."
 ],
 "pr2_dispatch_numbers": {
 "measured_at": "origin/main 133e2ea1e (worktree /home/user/objectui-6092)",
 "hand_typed_guard_files": 29,
 "breakdown": "28 .mjs + scripts/shadcn-sync.js",
 "process_argv1_occurrences": 54,
 "occurrence_note": "25 files spell it twice (the `argv[1] && resolve(argv[1]) === ...` shapes), 4 spell it once; the baseline is path-to-COUNT, so PR 2 must lower or delete each entry as it converts",
 "distinct_spellings": 9,
 "isEntrypoint_importers": 3,
 "isEntrypoint_importers_note": "scripts/invoked-as.mjs (the predicate's home) plus TWO adopters: scripts/pm/check-half-states.mjs and scripts/check-spec-range-floors.mjs. The card said ONE adopter; the #5793 gate has since landed on main. This is the only figure that moved, and it moved in the good direction.",
 "worklist_delta_vs_card": "none — comm -3 between the file set at 7c96c9420 and at 133e2ea1e is empty; 29 and 9 both reproduce exactly",
 "correct_shape_do_not_treat_as_defect": "scripts/shadcn-sync.js — hand-types realpathSync(resolved) === __filename; it is ESM (package type: module, imports fileURLToPath), so it IS convertible, but as a simplification, not a fix",
 "pr2_will_also_clear": "scripts/check-lucide-icon-record-names.mjs is the sole KNOWN_IMPORT_UNSAFE entry and is a SEPARATE defect from the spelling sweep — two top-level for loops at :242 and :244 outside any guard. Converting its guard does NOT clear it; moving those loops behind the guard does.",
 "pr2_gate_interaction": "the baseline is SHRINK-ONLY in both directions, so PR 2 cannot convert a file without also lowering or deleting its KNOWN_HAND_TYPED_GUARDS line — the gate fails as STALE and names the file otherwise. That is deliberate: it makes the sweep self-checking."
 }
}

---

Generated by Claude Code

[yinlianghui-tw]

PM dispatch order — R20, PR 2 of 2: the conversion

Claimed by the domain:devx @ objectui execution seat (#5748), round R20, PM session session_019b5UBNMtTzKbVtZZGvFuxe. Branch: claude/issue-6092-entry-guard-sweep.

PR 1 (#6133) has MERGED. The gate is live and names its own worklist. This PR does the sweep.

The numbers, from PR 1's own re-measurement at 133e2ea1e

figure	value
hand-typed guard files	29 (28 .mjs + scripts/shadcn-sync.js)
process.argv[1] occurrences	54 — 25 files spell it twice, 4 once
distinct spellings	9
isEntrypoint importers	3 (invoked-as.mjs, pm/check-half-states.mjs, check-spec-range-floors.mjs)

⚠️ main has moved since (#6128, #6130, #6133, #6134, #6136, #6137). Re-measure at claim and report any delta — PR 1 established the worklist grows while the card sits open.

The gate makes this sweep self-checking — use that

KNOWN_HAND_TYPED_GUARDS is path → COUNT and shrink-only in both directions. So you cannot convert a file without also lowering or deleting its baseline line: the gate fails STALE and names the file. That is deliberate. It means every conversion has a mechanical witness, and it means a half-conversion cannot pass.

⛔ Per-lane reverse verification, not a bulk sed

Triage's ruling is binding: "conversion touches blocking gates on the publish path and per-PR lanes — reverse-verification per lane, not a bulk sed." These 29 files include blocking CI gates. A regex sweep that converts 29 guards and runs the gate proves only that the gate is satisfied — it does not prove the scripts still work.

Each converted script needs both legs, and the two legs must disagree for an unconverted or mis-converted file:

1. CLI leg — invoked as a command, the dispatch still runs (the script does its job, same exit code and same output as before the conversion).
2. Import leg — imported as a module, the dispatch stays inert.

A harness that runs both legs over all 29 mechanically is the right shape, and it needs its own positive control: ⛔ prove the harness can fail. Deliberately mis-convert one script (guard inverted, or removed) and show the harness catches it. A harness that reports 29 green without ever having reported red is not a reading. Same for the before/after comparison — capture each script's CLI behaviour before conversion so "same as before" is a measurement and not an assumption.

⚠️ Three specific traps

1. scripts/check-lucide-icon-record-names.mjs is a SEPARATE defect and converting its guard does NOT clear it. It builds two lookup maps in top-level for loops at :242 and :244, outside any guard — it is the sole KNOWN_IMPORT_UNSAFE entry, and it really does run those loops inside an importer. Moving the loops behind the guard is what clears it.

Ruled in scope for this PR, because it is the card's last open item and it is one file. But it is a behaviour change where the other 29 are a spelling change, so: verify it separately and on its own terms — the maps must still be built for the CLI path, and every importer of this module must still get what it imports. ⛔ If those loops feed module-level exports that importers actually read, STOP and report rather than restructuring the module. Turning a working import into a broken one to satisfy a baseline is the wrong trade, and that call is a ruling, not an implementation detail.

2. The pre-install path. PR 1 wired the gate into lint.yml before pnpm install, invoked as bare node, because its whole import graph is node builtins plus two local modules. Converting a script makes it import ./invoked-as.mjs — so for any converted script that runs in a pre-install step of any workflow, that import must resolve with no node_modules on the path. Check the relative depth per directory (scripts/pm/* needs ../invoked-as.mjs, not ./), and verify it rather than reasoning about it — a wrong relative path is a runtime failure in CI, not a type error.

3. The conversion is a real behaviour change, in the good direction. isEntrypoint resolves realpaths, so a script invoked through a symlink now correctly dispatches where the hand-typed form went inert — that is the outage #6078 demonstrated. Confirm no script is relied upon for the inert behaviour, and say how you checked.

⚠️ shadcn-sync.js — do not report it as a defect

It already hand-types the correct two-leg shape (realpathSync(resolved) === __filename). PR 1's gate never flags it. It is ESM and therefore convertible, but converting it is a simplification, not a fix — say so, and keep it visibly distinct from the 28 that are actually wrong.

Verification

• Per-lane both-leg evidence for all 29, plus the harness's own positive control.
• The gate green at the end with KNOWN_HAND_TYPED_GUARDS empty or reduced to exactly what remains, quoting the gate's own verdict line — and show what the count moved from and to.
• --self-test still passes (63 cases), and js-comment-mask.mjs --self-test (35 cases).
• Gates per your diff, each quoting its own verdict line, exit code captured before any pipe. vitest from the repo root, never package-scoped.

⛔ Out of scope: anything in content/docs/**; the upstream objectstack hole PR 1 filed as objectstack#11838.

⚠️ Commit your fix before any ablation whose restore leg is git checkout — it wipes uncommitted work including the fix under test. Use git checkout HEAD -- followed by the path, never the bare form. ⛔ Never git stash — shared stack, other agents are using it now.

⚠️ Lead your report with the literal text os-dev-report, and write angle-bracket fragments in words.

---

Generated by Claude Code