@cosyte/script-utils 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to `@cosyte/script-utils` are documented here, following
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions are managed with Changesets;
+this file is hand-maintained (Changesets' own changelog generation is disabled). The package stays on
+the **`0.0.x`-until-first-alpha** ladder.
+
+> Because the generator is disabled, **`[Unreleased]` is promoted to a version heading BY HAND**, in
+> the pull request that adds the changeset. Nothing does it automatically.
+
+## [0.0.1] - 2026-08-05
+
+### Added
+
+- First release. `isCliEntrypoint(import.meta.url)` answers "is this module the file Node was
+  pointed at", for the `scripts/*.mjs` gates that must not run their CLI body when a test imports
+  them for their exports.
+
+  It replaces the raw string comparison those gates were spelling by hand,
+  `` import.meta.url === `file://${resolve(process.argv[1])}` ``, which compares two strings rather
+  than two paths and therefore answers `false` for three ordinary invocations: an extension-less
+  specifier that Node or `tsx` resolved (`node scripts/gate` running `scripts/gate.js`), a checkout
+  under a path containing a space (`import.meta.url` percent-encodes and the concatenation does
+  not), and a symlinked invocation (Node resolves the main module to its real path). In each the
+  gate exits 0 having checked nothing.
+
+  Those three forms also COMBINE, and the combination is the one that hides: an extension-less
+  `argv[1]` names no file, so it cannot be resolved directly, and any symlinked ancestor then puts
+  the two sides in different places. `isCliEntrypoint` resolves the deepest ancestor that does
+  exist and keeps the rest verbatim, so `tsx scripts/gate` answers correctly under a symlinked
+  checkout.
+
+  The package carries no runtime dependencies and no build step, because the gates that import it
+  run before `pnpm install` on purpose.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cosyte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @cosyte/script-utils
+
+Zero-dependency helpers for the repo-local gate scripts every cosyte repo keeps in `scripts/`.
+
+No runtime dependencies and no build step. Both are load-bearing for the gates in `config` itself,
+which run **before `pnpm install`** on purpose, so that a broken or hostile install cannot decide
+whether a release gate runs.
+
+## Install
+
+```sh
+pnpm add -D @cosyte/script-utils
+```
+
+### If your gate runs before `pnpm install`, do not use the bare specifier
+
+Read this before adopting the package, because it is the one thing that does not generalise.
+
+A bare `import ... from "@cosyte/script-utils"` resolves through `node_modules`, so it only works
+once the install has happened. `config`'s own two gates run before their install and therefore
+import this file by **relative path** instead, which needs nothing on disk but the checkout.
+
+So check when your gate runs, and pick accordingly:
+
+| When the gate runs               | How to import                                    |
+| -------------------------------- | ------------------------------------------------ |
+| After `pnpm install` (the usual) | `@cosyte/script-utils`, as a `devDependency`     |
+| Before `pnpm install`            | A relative path to a vendored or checked-in copy |
+
+Installing the package does not, on its own, give a pre-install gate the property described above.
+
+## `isCliEntrypoint(import.meta.url)`
+
+Is this module the file Node was pointed at, rather than one imported by something else?
+
+```js
+import { isCliEntrypoint } from "@cosyte/script-utils";
+
+export function main(argv) {
+  /* ... */
+}
+
+if (isCliEntrypoint(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}
+```
+
+That guard is what lets a test import the module for its exports without the CLI executing as a side
+effect, while the script still runs normally when invoked.
+
+### Why not compare the strings
+
+The obvious spelling is a one-liner, and several cosyte repos wrote it by hand:
+
+```js
+// Do not do this.
+import.meta.url === `file://${resolve(process.argv[1])}`;
+```
+
+It compares two strings rather than two paths, so it answers `false` for three ordinary invocations
+of the script that contains it. All three were measured on Node 22.23.1, not predicted:
+
+| Invocation                     | What happens                                                                                                                                              |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `node scripts/gate`            | Node resolves the extension and runs `scripts/gate.js`; `argv[1]` keeps `scripts/gate`, which names no file. `tsx scripts/gate` does the same with `.ts`. |
+| A checkout under `/space dir/` | `import.meta.url` percent-encodes to `/space%20dir/`; concatenating `file://` onto a raw path does not.                                                   |
+| A symlinked invocation         | Node resolves the main module to its real path, so `import.meta.url` is the target while `argv[1]` is the link. `node_modules/.bin` shims hit this.       |
+
+In every one the guard is `false`, so the gate exits 0 having checked nothing. That is worse than
+the defect the gate was written to catch, because the run conclusion is the only thing anyone reads.
+
+`isCliEntrypoint` compares canonical paths, resolves symlinks, and treats an `argv[1]` that names no
+file on disk as a specifier Node had to resolve.
+
+### Which way it errs
+
+When the answer is genuinely ambiguous it returns `true` and the CLI runs. A false positive runs a
+gate during an import, which is loud and immediately visible; a false negative skips a gate and
+exits 0, which is silent. Those are not symmetric, so the tie goes to running.
+
+It throws a `TypeError` rather than returning `false` when handed something that is not a non-empty
+string, for the same reason.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Is this module the file Node was pointed at, rather than one imported by something else?
+ *
+ * Compares the caller's module URL against `process.argv[1]` as PATHS, tolerating the three
+ * divergences a raw string comparison gets wrong: an extension-less specifier that Node or a
+ * loader resolved, percent-encoding in the module URL, and a symlinked invocation.
+ *
+ * When the answer is genuinely ambiguous it returns `true`, so an unsure gate runs loudly rather
+ * than skipping silently.
+ *
+ * @param moduleUrl The calling module's `import.meta.url`.
+ * @returns `true` when this module is the process entry point.
+ * @throws {TypeError} When `moduleUrl` is not a non-empty string.
+ */
+export declare function isCliEntrypoint(moduleUrl: string): boolean;

package/index.js

@@ -0,0 +1,157 @@
+// @cosyte/script-utils
+//
+// SMALL, ZERO-DEPENDENCY HELPERS FOR THE .mjs/.js GATE SCRIPTS EVERY COSYTE REPO KEEPS IN `scripts/`.
+//
+// Zero-dependency is a hard constraint, not a preference. This repo's own two gates
+// (`scripts/changeset-guard.mjs`, `scripts/release-notes.mjs`) run in `ci.yml` and `release.yml`
+// BEFORE `pnpm install`, on purpose, so that a broken or malicious install cannot decide whether a
+// release gate runs. Anything imported by such a gate must therefore resolve with no `node_modules`
+// present. Keep this package free of runtime dependencies and free of a build step.
+
+import { statSync, realpathSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Extensions Node or a loader may append to a specifier that was typed without one.
+ *
+ * The TypeScript entries are here because `tsx`, `ts-node` and `node --experimental-strip-types`
+ * all resolve an extension-less specifier to a TypeScript file while leaving `process.argv[1]`
+ * exactly as typed.
+ */
+const SCRIPT_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"]);
+
+/**
+ * Resolve symlinks, including for a path that does not exist.
+ *
+ * THE NAIVE FALLBACK HERE IS A SILENT-SKIP BUG, and it takes two conditions that look unrelated.
+ * An extension-less `argv[1]` names no file by construction, so `realpathSync` throws on it;
+ * returning the input raw then compares an UNRESOLVED path against a resolved one, because the
+ * module side always resolves. Add any symlinked ancestor (macOS reaches `tmpdir()` through
+ * `/var` to `/private/var`, and a symlinked checkout does the same) and the two disagree, so the
+ * gate reports "not the entry point" and exits 0 having checked nothing. That is the combination of
+ * `tsx scripts/prebuild` and a symlinked ancestor, which is an ordinary way to run a gate.
+ *
+ * So resolve the deepest ancestor that DOES exist and keep the rest verbatim.
+ *
+ * @param {string} path An absolute path.
+ * @returns {string} The path with every resolvable ancestor resolved.
+ */
+function canonical(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    const parent = dirname(path);
+    // At the filesystem root `dirname` is a fixed point. Without this the recursion never ends.
+    if (parent === path) return path;
+    return join(canonical(parent), basename(path));
+  }
+}
+
+/**
+ * `statSync` that reports a missing path as `null` rather than throwing.
+ *
+ * @param {string} path An absolute path.
+ * @returns {import("node:fs").Stats | null} The stats, or `null`.
+ */
+function statOrNull(path) {
+  try {
+    return statSync(path);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Strip a trailing script extension, so `/a/gate.ts` and `/a/gate` compare equal.
+ *
+ * @param {string} path An absolute path.
+ * @returns {string} `path` without its script extension.
+ */
+function withoutScriptExtension(path) {
+  const ext = extname(path);
+  return SCRIPT_EXTENSIONS.has(ext) ? path.slice(0, -ext.length) : path;
+}
+
+/**
+ * Is this module the file Node was pointed at, rather than one imported by something else?
+ *
+ * The question every `scripts/*.mjs` gate asks before running its CLI body, so that a test can
+ * import the module for its exports without the CLI executing as a side effect.
+ *
+ * WHY THIS IS NOT A STRING COMPARISON, all four cases measured on Node 22.23.1 rather than
+ * predicted. The obvious spelling,
+ *
+ *     import.meta.url === `file://${resolve(process.argv[1])}`
+ *
+ * asks whether two strings match, not whether two paths name the same file, and it answers FALSE
+ * for three ordinary invocations of the very script that wrote it:
+ *
+ *   1. EXTENSION-LESS. `node scripts/gate` runs `scripts/gate.js`, and `tsx scripts/gate` runs
+ *      `scripts/gate.ts`. Node and the loader resolve the extension; `process.argv[1]` keeps the
+ *      specifier as typed, so it names a file that does not exist. This is the expensive one: it is
+ *      how a gate goes silent while looking like it ran, and a first cut at this helper that
+ *      canonicalised each side independently reintroduced it.
+ *   2. A PATH CONTAINING A SPACE. `import.meta.url` percent-encodes (`/space%20dir/gate.js`);
+ *      string-concatenating `file://` onto a raw path does not. Any checkout under a directory with
+ *      a space in its name disables every gate written this way.
+ *   3. A SYMLINKED INVOCATION. Node resolves the main module to its real path, so `import.meta.url`
+ *      is the target while `process.argv[1]` is the link. Both `node_modules/.bin` shims and a
+ *      symlinked checkout hit this.
+ *
+ * In all three the gate exits 0 having checked nothing, which is worse than the defect it guards,
+ * because a green run is the only thing anyone reads.
+ *
+ * WHICH WAY THIS ERRS, deliberately. When the answer is genuinely ambiguous (an extension-less
+ * `argv[1]` that resolves to no file on disk, so the stem comparison below is the only evidence
+ * available) this returns TRUE and the CLI runs. A false positive runs a gate during an import,
+ * which is loud and immediately visible. A false negative skips a gate and exits 0, which is
+ * silent. Those are not symmetric, so the tie goes to running.
+ *
+ * @param {string} moduleUrl The calling module's `import.meta.url`.
+ * @returns {boolean} `true` when this module is the process entry point.
+ * @throws {TypeError} When `moduleUrl` is not a non-empty string. Passing the wrong thing must be
+ *   loud: returning `false` would silently disable the caller's CLI.
+ * @example
+ *   if (isCliEntrypoint(import.meta.url)) process.exit(main(process.argv.slice(2)));
+ */
+export function isCliEntrypoint(moduleUrl) {
+  if (typeof moduleUrl !== "string" || moduleUrl === "") {
+    throw new TypeError(
+      `isCliEntrypoint(moduleUrl) expects a non-empty string, got ${typeof moduleUrl}. ` +
+        `Pass \`import.meta.url\`.`,
+    );
+  }
+
+  const entry = process.argv[1];
+  // No entry script at all: `node --eval`, the REPL, or an embedder. Nothing was pointed at.
+  if (typeof entry !== "string" || entry === "") return false;
+
+  let modulePath;
+  try {
+    modulePath = fileURLToPath(moduleUrl);
+  } catch {
+    // A `data:`, `http:` or `node:` module is never the file Node was pointed at.
+    return false;
+  }
+
+  const moduleReal = canonical(modulePath);
+  const entryReal = canonical(resolve(entry));
+  if (moduleReal === entryReal) return true;
+
+  // Past here the strings differ, so Node either resolved the specifier or the caller is genuinely
+  // not the entry. An `argv[1]` that names a real file is the second case: Node was pointed at some
+  // other script and had no resolving to do.
+  const entryStat = statOrNull(entryReal);
+  if (entryStat !== null && entryStat.isFile()) return false;
+
+  const entryStem = withoutScriptExtension(entryReal);
+  const moduleStem = withoutScriptExtension(moduleReal);
+
+  // `node scripts/gate` -> `scripts/gate.js`, and `tsx scripts/gate` -> `scripts/gate.ts`.
+  if (moduleStem === entryStem) return true;
+  // `node ./scripts` and `node ./scripts/` -> `scripts/index.js`.
+  if (moduleStem === join(entryStem, "index")) return true;
+
+  return false;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@cosyte/script-utils",
+  "version": "0.0.1",
+  "description": "Zero-dependency helpers for the repo-local gate scripts in @cosyte/* repos.",
+  "keywords": [
+    "cli",
+    "entrypoint",
+    "import-meta",
+    "scripts",
+    "cosyte"
+  ],
+  "homepage": "https://github.com/cosyte/config/tree/main/packages/script-utils#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cosyte/config.git",
+    "directory": "packages/script-utils"
+  },
+  "license": "MIT",
+  "author": "Cosyte <hello@cosyte.com> (https://cosyte.com)",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}