refactor(packages): move findUpPackageJson into packages/operations

Naming was off (now: `findUpPackageJson`, returns the file path) and
placement was off (was a standalone src/paths/find-up-package-json.ts
module). Move into src/packages/operations.ts next to readPackageJson
so all `*PackageJson*` IO helpers live together — pair them as `find`
+ `read`:

  const pkgJsonPath = findUpPackageJson(import.meta)
  const pkg = await readPackageJson(pkgJsonPath)

Taxonomy in this lib:
  - `paths/` = pure string transforms on path-shaped data (no I/O)
      walkUp, normalize, isPackageJsonFile, resolvePackageJsonDirname
  - `fs/` = generic filesystem IO
      findUp, findUpSync, readJson, writeJson
  - `packages/` = package.json-shaped high-level operations
      readPackageJson, writePackageJson, EditablePackageJson,
      findUpPackageJson ← new

`findUpPackageJson` calls `findUpSync` internally (so it touches the
filesystem) but its CONTRACT is package.json-specific — defaults to
that name, throws on missing, accepts `import.meta` instead of a cwd.
That puts it in the same conceptual layer as `readPackageJson`.

Drops the standalone `./paths/find-up-package-json` export (was never
published — v6.0.7 not yet on npm). Accessible via the existing
`./packages/operations` export. Test moved to
test/unit/packages/operations.find-up-package-json.test.mts mirroring
the readPackageJson test naming.

Author: jdalton

package.json

@@ -2081,11 +2081,6 @@
       "types": "./dist/paths/filenames.d.ts",
       "default": "./dist/paths/filenames.js"
     },
-    "./paths/find-up-package-json": {
-      "source": "./src/paths/find-up-package-json.ts",
-      "types": "./dist/paths/find-up-package-json.d.ts",
-      "default": "./dist/paths/find-up-package-json.js"
-    },
     "./paths/globs": {
       "source": "./src/paths/globs.ts",
       "types": "./dist/paths/globs.d.ts",

src/packages/operations.ts

@@ -2,6 +2,8 @@
  * @file Package operations including extraction, packing, and I/O.
  */
 
+import { fileURLToPath } from 'node:url'
+
 import {
   getPackageExtensions,
   getPackumentCache,
@@ -21,7 +23,9 @@ import * as semver from '../external/semver'
 
 import { getSmolPurl } from '../smol/purl'
 
+import { findUpSync } from '../fs/find-up'
 import { readJson, readJsonSync } from '../fs/read-json'
+import { getNodePath } from '../node/path'
 import { merge } from '../objects/mutate'
 import { isPlainObject } from '../objects/predicates'
 import type {
@@ -32,6 +36,7 @@ import type {
   ReadPackageJsonOptions,
 } from './types'
 import { normalizePackageJson } from './normalize'
+import { normalizePath } from '../paths/normalize'
 import { resolvePackageJsonPath } from '../paths/packages'
 import {
   getRepoUrlDetails,
@@ -231,6 +236,74 @@ export function pkgNameToSlug(pkgName: string): string {
     : pkgName
 }
 
+export interface FindUpPackageJsonOptions {
+  /**
+   * Names to look for. Defaults to `['package.json']`. Pass alternate
+   * markers for non-package roots (e.g. `['pnpm-workspace.yaml']` for the
+   * workspace root in a pnpm monorepo).
+   */
+  names?: readonly string[] | undefined
+  /**
+   * Optional ancestor boundary. Useful when a script is run from a deeply
+   * nested fixture and you don't want to escape the test's tmpdir.
+   * Defaults to the filesystem root.
+   */
+  stopAt?: string | undefined
+}
+
+/**
+ * Find the nearest `package.json` walking up from `import.meta`. Returns the
+ * absolute path to the file (normalized to forward slashes), matching the
+ * `findUp` / `findUpSync` return shape. Throws when no marker is found —
+ * every script using this helper lives inside a package and should resolve.
+ *
+ * Use this instead of `path.join(__dirname, '..', '..'[, '..'])`. The ascent
+ * count is computed at runtime from the actual filesystem layout, not
+ * hard-coded into the source, so the helper stays correct across refactors
+ * that move scripts between directories.
+ *
+ * Pair with `readPackageJson` to find AND parse the nearest package.json:
+ *
+ * @example
+ *   ;```ts
+ *   const pkgJsonPath = findUpPackageJson(import.meta)
+ *   // → '/abs/path/to/package.json'
+ *   const pkg = await readPackageJson(pkgJsonPath)
+ *   console.log(pkg?.name)
+ *
+ *   // Workspace root in a pnpm monorepo:
+ *   const wsRoot = findUpPackageJson(import.meta, {
+ *     names: ['pnpm-workspace.yaml'],
+ *   })
+ *   ```
+ *
+ * @param meta - `import.meta` from the calling script.
+ * @param options - Override marker name(s) or set a stopAt boundary.
+ *
+ * @returns Absolute, normalized path to the marker file.
+ * @throws When no marker is found between the script and the filesystem
+ *   root (or `stopAt`).
+ */
+export function findUpPackageJson(
+  meta: ImportMeta,
+  options?: FindUpPackageJsonOptions | undefined,
+): string {
+  const { names = ['package.json'], stopAt } = {
+    __proto__: null,
+    ...options,
+  } as FindUpPackageJsonOptions
+  const scriptPath = fileURLToPath(meta.url)
+  const path = getNodePath()
+  const scriptDir = path.dirname(scriptPath)
+  const found = findUpSync(names as string[], { cwd: scriptDir, stopAt })
+  if (found === undefined) {
+    throw new Error(
+      `findUpPackageJson: no ${names.join(' / ')} found between ${scriptPath} and ${stopAt ?? 'filesystem root'}`,
+    )
+  }
+  return normalizePath(found)
+}
+
 /**
  * Read and parse a package.json file asynchronously.
  *

src/paths/find-up-package-json.ts

@@ -42,3 +42,64 @@ export function resolvePackageJsonPath(filepath: string): string {
   const path = getNodePath()
   return normalizePath(path.join(filepath, 'package.json'))
 }
+
+export interface FindUpPackageJsonOptions {
+  /**
+   * Names to look for. Defaults to `['package.json']`. Pass alternate
+   * markers for non-package roots (e.g. `['pnpm-workspace.yaml']` for
+   * the workspace root in a pnpm monorepo).
+   */
+  names?: readonly string[] | undefined
+  /**
+   * Optional ancestor boundary. Useful when a script is run from a
+   * deeply nested fixture and you don't want to escape the test's
+   * tmpdir. Defaults to the filesystem root.
+   */
+  stopAt?: string | undefined
+}
+
+/**
+ * Find the nearest `package.json` walking up from `import.meta`. Returns the
+ * absolute path to the file (normalized to forward slashes), matching the
+ * existing `findUpSync` family. Callers who want the directory do
+ * `path.dirname(found)`, or pass the result through `resolvePackageJsonDirname`.
+ *
+ * Use this to replace the fragile `path.join(__dirname, '..', '..'[, '..'])`
+ * pattern that breaks every time a script moves between directories. The
+ * ascent count is computed at runtime from the actual filesystem layout,
+ * not hard-coded into the source.
+ *
+ * @example
+ *   ;```ts
+ *   const pkgJson = findUpPackageJson(import.meta)
+ *   // → '/abs/path/to/package.json'
+ *   const pkgRoot = resolvePackageJsonDirname(pkgJson)
+ *   // → '/abs/path/to'
+ *   ```
+ *
+ * @param meta - `import.meta` from the calling script.
+ * @param options - Override the marker file name(s) or set a stopAt boundary.
+ * @returns Absolute path to the marker file.
+ * @throws If no marker is found between the calling script and the filesystem
+ *   root (or `stopAt`). This is a programming error — every script that uses
+ *   this helper lives inside a package and should resolve.
+ */
+export function findUpPackageJson(
+  meta: ImportMeta,
+  options?: FindUpPackageJsonOptions | undefined,
+): string {
+  const { names = ['package.json'], stopAt } = {
+    __proto__: null,
+    ...options,
+  } as FindUpPackageJsonOptions
+  const scriptPath = fileURLToPath(meta.url)
+  const path = getNodePath()
+  const scriptDir = path.dirname(scriptPath)
+  const found = findUpSync(names as string[], { cwd: scriptDir, stopAt })
+  if (found === undefined) {
+    throw new Error(
+      `findUpPackageJson: no ${names.join(' / ')} found between ${scriptPath} and ${stopAt ?? 'filesystem root'}`,
+    )
+  }
+  return normalizePath(found)
+}

src/paths/packages.ts

@@ -1,5 +1,5 @@
 /**
- * @file Tests for paths/find-up-package-json — boundary-anchored
+ * @file Tests for packages/operations findUpPackageJson — boundary-anchored
  *   nearest-package-json lookup via findUpSync from import.meta.
  */
 
@@ -10,7 +10,7 @@ import { pathToFileURL } from 'node:url'
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
-import { findUpPackageJson } from '../../../src/paths/find-up-package-json'
+import { findUpPackageJson } from '../../../src/packages/operations'
 
 describe('findUpPackageJson', () => {
   let tmpDir: string
@@ -24,7 +24,7 @@ describe('findUpPackageJson', () => {
   })
 
   it('returns the path of the nearest package.json walking up from the script', () => {
-    // Layout: tmpDir/package.json + tmpDir/scripts/fleet/check/foo.mts
+    // Layout: tmpDir/package.json + tmpDir/scripts/fleet/check/foo.mts.
     // The script is 3 levels deep; result should be tmpDir/package.json,
     // regardless of the actual ascent count.
     writeFileSync(path.join(tmpDir, 'package.json'), '{}', 'utf8')
@@ -62,9 +62,9 @@ describe('findUpPackageJson', () => {
   })
 
   it('picks the nearest package.json when nested packages are present', () => {
-    // Inner package.json should be the nearest match — findUpSync
-    // returns the FIRST marker, not the outermost (matches the
-    // package-resolution semantics every module system uses).
+    // Inner package.json should be the nearest match — findUpSync returns
+    // the FIRST marker, not the outermost (matches the package-resolution
+    // semantics every module system uses).
     writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"outer"}', 'utf8')
     mkdirSync(path.join(tmpDir, 'inner'), { recursive: true })
     writeFileSync(
@@ -119,8 +119,8 @@ describe('findUpPackageJson', () => {
   })
 
   it('resolves the calling lib script (smoke test against the real source tree)', () => {
-    // Self-test: findUpPackageJson(import.meta) from this test file
-    // resolves to the socket-lib package.json — never hard-coded.
+    // Self-test: findUpPackageJson(import.meta) from this test file resolves
+    // to the socket-lib package.json — never hard-coded.
     const found = findUpPackageJson(import.meta)
     expect(found).toMatch(/socket-lib\/package\.json$/)
   })