runspec-node 0.22.0 → 0.23.0

package/dist/finder.d.ts

@@ -1,4 +1,36 @@
+/**
+ * Locate the governing `runspec.toml`.
+ *
+ * Resolution order mirrors the Python `parse()`:
+ *   1. `RUNSPEC_CONFIG` env var — explicit override.
+ *   2. an explicit `start` directory, when one is passed.
+ *   3. **caller-relative** — walk up from the entry script's directory
+ *      (`require.main` / `process.argv[1]`). This is what lets an installed
+ *      runnable find its own config from *any* working directory — e.g. when a
+ *      controller launches `bin/greet` over SSH with `cwd` = the login home,
+ *      not the package. Mirrors Python resolving relative to the installed
+ *      package, "what makes installed entry points work from any working
+ *      directory".
+ *   4. **cwd-relative** — walk up from `process.cwd()` (the historical
+ *      behaviour, kept as the final fallback).
+ *
+ * A `runspec.toml` found *inside* a `node_modules` path is ignored: those
+ * belong to installed dependencies (including runspec-node's own bundled CLI
+ * spec), never the project being discovered.
+ */
 export declare function findConfig(start?: string): {
     configPath: string;
 };
+/**
+ * Ordered, de-duplicated list of directories to walk up from, mirroring the
+ * resolution order documented on `findConfig`. Pure (no I/O) so the priority
+ * logic is unit-testable without a filesystem fixture.
+ */
+export declare function searchStarts(start: string | undefined, entryDir: string | undefined, cwd: string): string[];
+/**
+ * Walk up from `start` looking for a `runspec.toml`, skipping any found under a
+ * `node_modules` path (a dependency's spec, not the project's). Returns the
+ * path or null. Exported for testing.
+ */
+export declare function walkUp(start: string): string | null;
 //# sourceMappingURL=finder.d.ts.map

package/dist/finder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"finder.d.ts","sourceRoot":"","sources":["../src/finder.ts"],"names":[],"mappings":"AAGA,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAiBjE"}
+{"version":3,"file":"finder.d.ts","sourceRoot":"","sources":["../src/finder.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAoBjE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAM3G;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWnD"}

package/dist/finder.js

@@ -34,20 +34,81 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findConfig = findConfig;
+exports.searchStarts = searchStarts;
+exports.walkUp = walkUp;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+/**
+ * Locate the governing `runspec.toml`.
+ *
+ * Resolution order mirrors the Python `parse()`:
+ *   1. `RUNSPEC_CONFIG` env var — explicit override.
+ *   2. an explicit `start` directory, when one is passed.
+ *   3. **caller-relative** — walk up from the entry script's directory
+ *      (`require.main` / `process.argv[1]`). This is what lets an installed
+ *      runnable find its own config from *any* working directory — e.g. when a
+ *      controller launches `bin/greet` over SSH with `cwd` = the login home,
+ *      not the package. Mirrors Python resolving relative to the installed
+ *      package, "what makes installed entry points work from any working
+ *      directory".
+ *   4. **cwd-relative** — walk up from `process.cwd()` (the historical
+ *      behaviour, kept as the final fallback).
+ *
+ * A `runspec.toml` found *inside* a `node_modules` path is ignored: those
+ * belong to installed dependencies (including runspec-node's own bundled CLI
+ * spec), never the project being discovered.
+ */
 function findConfig(start) {
-    let dir = path.resolve(start ?? process.cwd());
+    const env = process.env.RUNSPEC_CONFIG;
+    if (env && fs.existsSync(env))
+        return { configPath: path.resolve(env) };
+    // process.argv[1] over require.main.filename: the latter realpath-resolves
+    // symlinks, which under `npm link` / workspaces / a local install jumps the
+    // entry *out* of the project (to the linked source) and breaks the walk.
+    // process.argv[1] preserves the path the binary was actually invoked at —
+    // inside the project's node_modules — which is what we want to walk up from.
+    const entry = process.argv[1] ?? require.main?.filename;
+    const entryDir = entry ? path.dirname(entry) : undefined;
+    for (const dir of searchStarts(start, entryDir, process.cwd())) {
+        const found = walkUp(dir);
+        if (found)
+            return { configPath: found };
+    }
+    throw new Error("No runspec configuration found.\nExpected runspec.toml inside your package directory.\n\nRun 'runspec init' to create one.");
+}
+/**
+ * Ordered, de-duplicated list of directories to walk up from, mirroring the
+ * resolution order documented on `findConfig`. Pure (no I/O) so the priority
+ * logic is unit-testable without a filesystem fixture.
+ */
+function searchStarts(start, entryDir, cwd) {
+    const out = [];
+    if (start)
+        out.push(path.resolve(start));
+    if (entryDir)
+        out.push(path.resolve(entryDir));
+    out.push(path.resolve(cwd));
+    return [...new Set(out)];
+}
+/**
+ * Walk up from `start` looking for a `runspec.toml`, skipping any found under a
+ * `node_modules` path (a dependency's spec, not the project's). Returns the
+ * path or null. Exported for testing.
+ */
+function walkUp(start) {
+    let dir = path.resolve(start);
     while (true) {
         const runspecToml = path.join(dir, 'runspec.toml');
-        if (fs.existsSync(runspecToml)) {
-            return { configPath: runspecToml };
+        if (fs.existsSync(runspecToml) && !isInNodeModules(dir)) {
+            return runspecToml;
         }
         const parent = path.dirname(dir);
         if (parent === dir)
-            break;
+            return null;
         dir = parent;
     }
-    throw new Error("No runspec configuration found.\nExpected runspec.toml inside your package directory.\n\nRun 'runspec init' to create one.");
+}
+function isInNodeModules(dir) {
+    return dir.split(path.sep).includes('node_modules');
 }
 //# sourceMappingURL=finder.js.map

package/dist/finder.js.map

@@ -1 +1 @@
-{"version":3,"file":"finder.js","sourceRoot":"","sources":["../src/finder.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA,gCAiBC;AApBD,uCAAyB;AACzB,2CAA6B;AAE7B,SAAgB,UAAU,CAAC,KAAc;IACvC,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAE/C,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QACnD,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC/B,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;QACrC,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IAED,MAAM,IAAI,KAAK,CACb,4HAA4H,CAC7H,CAAC;AACJ,CAAC"}
+{"version":3,"file":"finder.js","sourceRoot":"","sources":["../src/finder.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuBA,gCAoBC;AAOD,oCAMC;AAOD,wBAWC;AA1ED,uCAAyB;AACzB,2CAA6B;AAE7B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,UAAU,CAAC,KAAc;IACvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IACvC,IAAI,GAAG,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;IAExE,2EAA2E;IAC3E,4EAA4E;IAC5E,yEAAyE;IACzE,0EAA0E;IAC1E,6EAA6E;IAC7E,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxD,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEzD,KAAK,MAAM,GAAG,IAAI,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QAC/D,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,KAAK;YAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,IAAI,KAAK,CACb,4HAA4H,CAC7H,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAAC,KAAyB,EAAE,QAA4B,EAAE,GAAW;IAC/F,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,KAAK;QAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACzC,IAAI,QAAQ;QAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/C,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,SAAgB,MAAM,CAAC,KAAa;IAClC,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QACnD,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;YACxD,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAChC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;AACtD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runspec-node",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Node/TypeScript language pack for runspec",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/finder.ts

@@ -1,21 +1,79 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
+/**
+ * Locate the governing `runspec.toml`.
+ *
+ * Resolution order mirrors the Python `parse()`:
+ *   1. `RUNSPEC_CONFIG` env var — explicit override.
+ *   2. an explicit `start` directory, when one is passed.
+ *   3. **caller-relative** — walk up from the entry script's directory
+ *      (`require.main` / `process.argv[1]`). This is what lets an installed
+ *      runnable find its own config from *any* working directory — e.g. when a
+ *      controller launches `bin/greet` over SSH with `cwd` = the login home,
+ *      not the package. Mirrors Python resolving relative to the installed
+ *      package, "what makes installed entry points work from any working
+ *      directory".
+ *   4. **cwd-relative** — walk up from `process.cwd()` (the historical
+ *      behaviour, kept as the final fallback).
+ *
+ * A `runspec.toml` found *inside* a `node_modules` path is ignored: those
+ * belong to installed dependencies (including runspec-node's own bundled CLI
+ * spec), never the project being discovered.
+ */
 export function findConfig(start?: string): { configPath: string } {
-  let dir = path.resolve(start ?? process.cwd());
+  const env = process.env.RUNSPEC_CONFIG;
+  if (env && fs.existsSync(env)) return { configPath: path.resolve(env) };
 
+  // process.argv[1] over require.main.filename: the latter realpath-resolves
+  // symlinks, which under `npm link` / workspaces / a local install jumps the
+  // entry *out* of the project (to the linked source) and breaks the walk.
+  // process.argv[1] preserves the path the binary was actually invoked at —
+  // inside the project's node_modules — which is what we want to walk up from.
+  const entry = process.argv[1] ?? require.main?.filename;
+  const entryDir = entry ? path.dirname(entry) : undefined;
+
+  for (const dir of searchStarts(start, entryDir, process.cwd())) {
+    const found = walkUp(dir);
+    if (found) return { configPath: found };
+  }
+
+  throw new Error(
+    "No runspec configuration found.\nExpected runspec.toml inside your package directory.\n\nRun 'runspec init' to create one.",
+  );
+}
+
+/**
+ * Ordered, de-duplicated list of directories to walk up from, mirroring the
+ * resolution order documented on `findConfig`. Pure (no I/O) so the priority
+ * logic is unit-testable without a filesystem fixture.
+ */
+export function searchStarts(start: string | undefined, entryDir: string | undefined, cwd: string): string[] {
+  const out: string[] = [];
+  if (start) out.push(path.resolve(start));
+  if (entryDir) out.push(path.resolve(entryDir));
+  out.push(path.resolve(cwd));
+  return [...new Set(out)];
+}
+
+/**
+ * Walk up from `start` looking for a `runspec.toml`, skipping any found under a
+ * `node_modules` path (a dependency's spec, not the project's). Returns the
+ * path or null. Exported for testing.
+ */
+export function walkUp(start: string): string | null {
+  let dir = path.resolve(start);
   while (true) {
     const runspecToml = path.join(dir, 'runspec.toml');
-    if (fs.existsSync(runspecToml)) {
-      return { configPath: runspecToml };
+    if (fs.existsSync(runspecToml) && !isInNodeModules(dir)) {
+      return runspecToml;
     }
-
     const parent = path.dirname(dir);
-    if (parent === dir) break;
+    if (parent === dir) return null;
     dir = parent;
   }
+}
 
-  throw new Error(
-    "No runspec configuration found.\nExpected runspec.toml inside your package directory.\n\nRun 'runspec init' to create one.",
-  );
+function isInNodeModules(dir: string): boolean {
+  return dir.split(path.sep).includes('node_modules');
 }

package/tests/test_finder.test.ts

@@ -0,0 +1,94 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { findConfig, searchStarts, walkUp } from '../src/finder';
+
+function tmpdir(): string {
+  return fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'runspec-finder-'));
+}
+
+function writeToml(dir: string): string {
+  fs.mkdirSync(dir, { recursive: true });
+  const p = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(p, '[greet]\ndescription = "x"\n');
+  return p;
+}
+
+describe('searchStarts — resolution priority', () => {
+  it('orders explicit start, then entry dir, then cwd', () => {
+    expect(searchStarts('/a', '/b', '/c')).toEqual([path.resolve('/a'), path.resolve('/b'), path.resolve('/c')]);
+  });
+
+  it('omits a missing explicit start / entry dir', () => {
+    expect(searchStarts(undefined, undefined, '/c')).toEqual([path.resolve('/c')]);
+    expect(searchStarts(undefined, '/b', '/c')).toEqual([path.resolve('/b'), path.resolve('/c')]);
+  });
+
+  it('de-duplicates while preserving order (cwd === entry dir)', () => {
+    expect(searchStarts(undefined, '/same', '/same')).toEqual([path.resolve('/same')]);
+  });
+});
+
+describe('walkUp', () => {
+  let dir: string;
+  afterEach(() => {
+    if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('finds runspec.toml walking up from a nested dir', () => {
+    dir = tmpdir();
+    const toml = writeToml(dir);
+    const nested = path.join(dir, 'a', 'b', 'c');
+    fs.mkdirSync(nested, { recursive: true });
+    expect(walkUp(nested)).toBe(toml);
+  });
+
+  it('ignores a runspec.toml that lives under node_modules', () => {
+    dir = tmpdir();
+    const projectToml = writeToml(dir); // {root}/runspec.toml — the project's
+    // A dependency ships its own runspec.toml (e.g. runspec-node's CLI spec).
+    const depDir = path.join(dir, 'node_modules', 'runspec-node', 'dist');
+    writeToml(depDir);
+    // Walking up from inside node_modules must skip the dep's toml and resolve
+    // the project's — this is the installed-CLI discovery case.
+    expect(walkUp(depDir)).toBe(projectToml);
+  });
+
+  it('returns null when no runspec.toml exists up the tree', () => {
+    dir = tmpdir();
+    const nested = path.join(dir, 'x', 'y');
+    fs.mkdirSync(nested, { recursive: true });
+    expect(walkUp(nested)).toBeNull();
+  });
+});
+
+describe('findConfig', () => {
+  let dir: string;
+  const savedEnv = process.env.RUNSPEC_CONFIG;
+  afterEach(() => {
+    if (savedEnv === undefined) delete process.env.RUNSPEC_CONFIG;
+    else process.env.RUNSPEC_CONFIG = savedEnv;
+    if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('honours RUNSPEC_CONFIG when set', () => {
+    dir = tmpdir();
+    const toml = writeToml(path.join(dir, 'custom'));
+    process.env.RUNSPEC_CONFIG = toml;
+    // cwd has no toml, but the env var wins regardless.
+    expect(findConfig(dir).configPath).toBe(path.resolve(toml));
+  });
+
+  it('resolves from an explicit start dir', () => {
+    delete process.env.RUNSPEC_CONFIG;
+    dir = tmpdir();
+    const toml = writeToml(dir);
+    expect(findConfig(path.join(dir, 'sub', 'dir')).configPath).toBe(toml);
+  });
+
+  it('throws a helpful error when nothing is found', () => {
+    delete process.env.RUNSPEC_CONFIG;
+    dir = tmpdir(); // empty, no runspec.toml anywhere up the chain inside the tmp root
+    expect(() => findConfig(dir)).toThrow(/No runspec configuration found/);
+  });
+});