docs(devx): reciprocal pointers for the invoked-as three-copy sync obligation

.changeset/invoked-as-reciprocal-pointers.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/cli": patch
+---
+
+docs(cli): `invocation.ts`'s `isProcessEntry` doc now names its two siblings
+
+The three-copy `argv[1]`-vs-`import.meta.url` predicate (`isProcessEntry` here,
+`isEntrypoint`/`invokedAs` in this repo's `scripts/invoked-as.mjs`, and
+objectui's own `scripts/invoked-as.mjs`) carried the "change one, change the
+others" sync obligation in only one of the three copies — objectui's. Neither
+objectstack copy pointed at the other two, so an agent editing either file
+here had no way to discover that a third copy exists elsewhere (#12013).
+
+Both objectstack copies were otherwise correct and are not changed in
+substance; only a reciprocal pointer is added to each, comment-only.

packages/cli/src/utils/invocation.ts

@@ -87,6 +87,11 @@ function realOrSelf(path: string): string {
  * basename matching, which #10086 also found in the wild and which fires for
  * any entry script that happens to share a filename.
  *
+ * This predicate is duplicated, not shared, in two other places: this repo's
+ * `scripts/invoked-as.mjs` (`isEntrypoint`) and objectui's own
+ * `scripts/invoked-as.mjs`. All three copies carry the same two legs above and
+ * must not diverge — change one, change the others.
+ *
  * @param entryArg `process.argv[1]` — undefined under `node --eval` / the REPL
  * @param selfUrl the caller's `import.meta.url`
  */

scripts/invoked-as.mjs

@@ -75,18 +75,23 @@
  * failure. That gate is what stops a TWELFTH spelling, which is the whole
  * reason this file exists rather than a one-time sweep.
  *
- * ## The sibling in `packages/cli`, and why the duplication is deliberate
+ * ## The siblings, and why the duplication is deliberate
  *
  * `packages/cli/src/utils/invocation.ts` exports `isProcessEntry`, the same
  * predicate for the same reason (its header cites this defect). It is NOT
  * imported here and this is not imported there: `scripts/` runs as plain .mjs
  * against a possibly-unbuilt tree, and making the whole tooling layer depend on
  * a package build to answer "was I run?" trades this bug for a worse one.
  *
+ * A third copy lives outside this repo: objectui's `scripts/invoked-as.mjs`
+ * carries the same predicate under the same name (ported from here, #5984), so
+ * the pairing is a CROSS-REPO obligation as well as a local one.
+ *
  * The duplication is therefore structural, but DIVERGENCE is not allowed --
  * two predicates answering this question differently is precisely the defect
- * being closed. Both carry the same two legs: realpath for symlinks, and
- * directory resolution for `node <dir>`. Change one, change the other.
+ * being closed. All three copies carry the same two legs: realpath for
+ * symlinks, and directory resolution for `node <dir>`. Change one, change the
+ * others.
  */
 
 import { spawnSync } from 'node:child_process';