@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/commonjs-marker.cjs

@@ -0,0 +1,142 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMONJS_MARKER_CONTENT = exports.COMMONJS_MARKER = void 0;
+exports.markerPathFor = markerPathFor;
+exports.classifyMarker = classifyMarker;
+exports.ensureCommonJsMarker = ensureCommonJsMarker;
+exports.removeCommonJsMarker = removeCommonJsMarker;
+/**
+ * CommonJS module-type marker — single source of truth (#2544).
+ *
+ * GSD stages its own hook scripts and native plugin adapters as `.js` files.
+ * Node resolves a `.js` file's module type by walking up for the nearest
+ * `package.json`, so an ambient `"type": "module"` above the install location
+ * makes every one of those scripts fail with `require is not defined`. GSD
+ * pins them to CommonJS by writing a minimal `{"type":"commonjs"}` marker.
+ *
+ * Two rules govern that marker, and this module exists so both are enforced in
+ * exactly one place:
+ *
+ * 1. **Write only where GSD owns the contents.** The marker belongs in the
+ *    directories GSD fills with its own `.js` files (`hooks/`, and the
+ *    `nativePlugin.dir` for the runtimes that declare one) — never at the
+ *    runtime's shared config root, which on OpenCode and Kilo is documented,
+ *    user-writable territory for declaring local-plugin npm dependencies.
+ *
+ * 2. **Never overwrite a file GSD did not write.** Before #2544 the install
+ *    path wrote the marker unconditionally while the uninstall path already
+ *    compared content before unlinking. That asymmetry is the defect: the
+ *    discipline existed in the codebase, it was simply not applied on the
+ *    write side. `classifyMarker` is now the shared predicate behind both
+ *    `ensureCommonJsMarker` and `removeCommonJsMarker`, so install and
+ *    uninstall cannot drift apart again.
+ *
+ * Ownership is decided by exact content match against the marker GSD itself
+ * writes — the same test the uninstall path has always used.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+// #2874 (ADR-58 cleanup phase): ensureCommonJsMarker is reached from
+// install-engine.cts's _installNativePluginIfDeclared, which is on the
+// installRuntimeArtifacts call tree — route this module's fs calls through
+// the injectable seam too. See install-fs-adapter.cts's module doc.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installFsAdapter = require("./install-fs-adapter.cjs");
+const { installFs } = installFsAdapter;
+/** The exact marker content GSD writes (and the only content it will remove). */
+exports.COMMONJS_MARKER = '{"type":"commonjs"}';
+/** File bytes written to disk — the marker plus a trailing newline. */
+exports.COMMONJS_MARKER_CONTENT = `${exports.COMMONJS_MARKER}\n`;
+/** The marker path for a directory. */
+function markerPathFor(dir) {
+    return node_path_1.default.join(dir, 'package.json');
+}
+/**
+ * Classify the package.json in `dir` by ownership.
+ *
+ * Fails CLOSED: a file that exists but cannot be read is reported `foreign`,
+ * never `absent`. Reporting it absent would license the overwrite this module
+ * exists to prevent. (Same posture as the unreadable-config branch in
+ * capability-command-router.cjs: present-but-unreadable never downgrades to
+ * the permissive answer.)
+ */
+function classifyMarker(dir) {
+    const markerPath = markerPathFor(dir);
+    let stat;
+    try {
+        // lstat, not existsSync: existsSync follows symlinks and reports `false`
+        // for a DANGLING one, which would classify the path `absent` and let the
+        // write below follow the link and land outside the directory GSD owns.
+        stat = installFs().lstatSync(markerPath);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return 'absent';
+        return 'foreign';
+    }
+    // Anything that is not a regular file (symlink, directory, socket) is not
+    // something GSD wrote, so it is never ours to overwrite or remove.
+    if (!stat.isFile())
+        return 'foreign';
+    try {
+        const content = installFs().readFileSync(markerPath, 'utf8');
+        return content.trim() === exports.COMMONJS_MARKER ? 'gsd-owned' : 'foreign';
+    }
+    catch {
+        return 'foreign';
+    }
+}
+/**
+ * Write the CommonJS marker into `dir`, unless a file GSD does not own is
+ * already there.
+ *
+ * Creates `dir` when needed. Returns what happened so the caller can report
+ * it; a `preserved-foreign` result is not an error — it is the guard working.
+ *
+ * NEVER THROWS. Every other marker interaction in this module is best-effort —
+ * `removeCommonJsMarker` swallows unlink failures, `classifyMarker` swallows
+ * read failures — and the write path is the one most likely to fail on a
+ * locked-down config dir (`EACCES` on a read-only `hooks/`, `EROFS`, `ENOSPC`).
+ * Letting it throw made an unwritable marker abort the entire install with a
+ * raw stack trace, which is a strictly worse outcome than hooks that resolve as
+ * ESM: the caller can warn and continue, and does. Both the `mkdir` and the
+ * write are inside the guard — creating the directory is the same environmental
+ * hazard as writing into it.
+ */
+function ensureCommonJsMarker(dir) {
+    const ownership = classifyMarker(dir);
+    if (ownership === 'foreign')
+        return 'preserved-foreign';
+    if (ownership === 'gsd-owned')
+        return 'unchanged';
+    try {
+        installFs().mkdirSync(dir, { recursive: true });
+        // Exclusive create closes the gap between classifying and writing: if
+        // anything at all appeared at the path in between — including a symlink —
+        // this fails with EEXIST instead of following or overwriting it.
+        installFs().writeFileSync(markerPathFor(dir), exports.COMMONJS_MARKER_CONTENT, { flag: 'wx' });
+        return 'written';
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return 'preserved-foreign';
+        return 'failed';
+    }
+}
+/**
+ * Remove the CommonJS marker from `dir` — only when the content is exactly
+ * the marker GSD writes. Returns true when a file was removed.
+ */
+function removeCommonJsMarker(dir) {
+    if (classifyMarker(dir) !== 'gsd-owned')
+        return false;
+    try {
+        installFs().unlinkSync(markerPathFor(dir));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}