@devdogsuga/devtools 0.1.0

package/dist/repo/peers.js

@@ -0,0 +1,114 @@
+/**
+ * Loads devtools' optional-peer `@devdogsuga/*` libraries — the ones
+ * published to npm and consumed by the TARGET repo, which devtools reads at
+ * runtime rather than bundling its own copy of (see this package's
+ * `package.json`: `peerDependencies` + `peerDependenciesMeta.optional`, and
+ * `FINDINGS.md` experiment 2).
+ *
+ * Every export here is memoized per module (one dynamic `import()` per
+ * process, not per call) — this is what makes the module-identity guarantee
+ * in FINDINGS experiment 3 hold: every devtools call site that needs
+ * `@devdogsuga/env`'s registry gets the exact same module instance the
+ * repo's own manifests populated via `declare()`/`define()`, because both
+ * resolve to the identical absolute file path and Node's ESM cache is keyed
+ * by resolved URL.
+ */
+import { pathToFileURL } from "node:url";
+import { findRepoRoot, RepoNotFoundError } from "./root.js";
+import { findDependent, resolveFromRepo } from "./resolve.js";
+const moduleCache = new Map();
+/**
+ * Dynamically imports `specifier` as the repo would resolve it, memoized so
+ * repeated calls in one process return the SAME module instance (required
+ * for the env-registry identity guarantee above).
+ *
+ * Falls back to a plain bare-specifier `import()` when devtools is not
+ * running inside a DevDogsUGA checkout at all (`findRepoRoot()` throws
+ * `RepoNotFoundError`). That is not a production affordance — under real
+ * `pnpm dlx` use, `specifier` is an optional peer devtools' own package
+ * never installs, so the fallback import fails with the ordinary
+ * `MODULE_NOT_FOUND` either way. It exists so devtools' OWN test suite
+ * (which has no target repo to discover, but does have every one of these
+ * peers as a real Backstage workspace package) exercises this code against
+ * the genuine package rather than needing every test to mock this module.
+ */
+function loadPeer(specifier) {
+    const cached = moduleCache.get(specifier);
+    if (cached)
+        return cached;
+    const promise = (async () => {
+        // See `findRepoRoot()`'s own comment: Backstage's test suite sets this
+        // so every peer resolves to the real Backstage-workspace copy instead
+        // of a nonexistent target repo, without a per-test mock.
+        if (process.env.DEVTOOLS_TEST_REPO_ROOT) {
+            return import(specifier);
+        }
+        let repoRoot;
+        try {
+            repoRoot = findRepoRoot();
+        }
+        catch (err) {
+            if (err instanceof RepoNotFoundError) {
+                return import(specifier);
+            }
+            throw err;
+        }
+        const resolutionBase = findDependent(repoRoot, specifier);
+        if (!resolutionBase) {
+            throw new Error(`Nothing in this repo depends on ${specifier} — expected an app or package under apps/*` +
+                ` or packages/* to declare it (dependencies/devDependencies/peerDependencies).`);
+        }
+        const { resolvedPath } = resolveFromRepo(repoRoot, resolutionBase, specifier);
+        return import(pathToFileURL(resolvedPath).href);
+    })();
+    moduleCache.set(specifier, promise);
+    return promise;
+}
+/** Test-only: clears the memoized peer modules so a test can re-resolve with a fresh mock. */
+export function resetPeerCacheForTests() {
+    moduleCache.clear();
+}
+let resolvedEnvModule;
+export function loadEnv() {
+    return loadPeer("@devdogsuga/env").then((mod) => {
+        resolvedEnvModule = mod;
+        return mod;
+    });
+}
+/**
+ * The synchronous companion to `loadEnv()`, for the handful of call sites
+ * (`gh/environments.ts`'s `GITHUB_ENVIRONMENT_SPECS` getters) that cannot
+ * become async without changing their own callers' contract — they read a
+ * plain array off a getter, not a Promise. Safe ONLY after `loadEnv()` has
+ * resolved at least once; every caller of these getters already requires
+ * `env/discovery.ts`'s `loadRegistry()` (which calls `loadEnv()` itself) to
+ * have run first, via `assertRegistryLoaded()`'s own guard.
+ */
+export function getEnvSync() {
+    if (!resolvedEnvModule) {
+        throw new Error("getEnvSync() called before loadEnv() ever resolved — call loadRegistry() " +
+            "(env/discovery.ts) first.");
+    }
+    return resolvedEnvModule;
+}
+/** Test-only: clears the sync cache alongside `resetPeerCacheForTests()`. */
+export function resetEnvSyncCacheForTests() {
+    resolvedEnvModule = undefined;
+}
+export function loadEnvLoad() {
+    return loadPeer("@devdogsuga/env/load");
+}
+export function loadEnvSession() {
+    return loadPeer("@devdogsuga/env/session");
+}
+export function loadDbTypegen() {
+    return loadPeer("@devdogsuga/db/typegen");
+}
+export function loadBrandEvent() {
+    return loadPeer("@devdogsuga/brand/event");
+}
+// `@devdogsuga/newsletter` used to be an optional peer here, read by
+// devtools' own `newsletter` command. Wave 2, stage A2 moved that command to
+// a plain Backstage script (`packages/newsletter-cli`) — see its README —
+// since the content it exports lives in Backstage already; devtools has no
+// reason to load it at all any more.

package/dist/repo/preflight.d.ts

@@ -0,0 +1,109 @@
+import { z } from "zod";
+declare const ManifestSchema: z.ZodObject<{
+    devtools: z.ZodObject<{
+        latest: z.ZodString;
+        minimum: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DevtoolsMinimumsManifest = z.infer<typeof ManifestSchema>;
+/** Exported so tests can point elsewhere without touching the real `~/.cache`. */
+export declare function cacheFilePath(): string;
+export interface ManifestResult {
+    manifest: DevtoolsMinimumsManifest | null;
+    source: "cache" | "network" | "fail-open";
+    error?: string;
+}
+/**
+ * Fetches (or reads the disk cache for) the minimums manifest. Never
+ * throws: any failure — timeout, network error, non-200, invalid JSON,
+ * schema mismatch — comes back as `{ manifest: null, source: "fail-open" }`.
+ */
+export declare function fetchManifest(options?: {
+    url?: string;
+    skipCache?: boolean;
+    timeoutMs?: number;
+}): Promise<ManifestResult>;
+export type PreflightAction = {
+    action: "skip-preflight";
+} | {
+    action: "dev-mode";
+} | {
+    action: "fail-open";
+    reason: string;
+} | {
+    action: "self-refresh";
+    from: string;
+    to: string;
+    source: ManifestResult["source"];
+} | {
+    action: "loop-guard-tripped";
+    detail: string;
+} | {
+    action: "nudge";
+    from: string;
+    to: string;
+    source: ManifestResult["source"];
+} | {
+    action: "up-to-date";
+    source: ManifestResult["source"];
+};
+export interface PreflightOptions {
+    currentVersion: string;
+    argv: readonly string[];
+    skipPreflight: boolean;
+    refresh: boolean;
+    registry?: string;
+    manifestUrl?: string;
+    devMode?: boolean;
+}
+/**
+ * Runs the decision half of preflight. Does not itself re-exec or print —
+ * `runPreflight` below does both, so the pure decision stays independently
+ * testable (loop guard, fail-open, version comparisons) without spawning a
+ * real child process in every test.
+ */
+export declare function decidePreflight(options: PreflightOptions): Promise<PreflightAction>;
+/**
+ * Re-execs as the exact pinned `version`, inheriting stdio and propagating
+ * the child's exit code. Never returns — the caller relies on this to end
+ * the process, matching `spawnSync`'s synchronous nature (there is nothing
+ * meaningful left to do in this process either way).
+ *
+ * Exported separately from `runPreflight` so tests can stub it instead of
+ * spawning a real `pnpm dlx`.
+ */
+export declare function selfRefresh(options: {
+    version: string;
+    argv: readonly string[];
+    registry?: string;
+}): never;
+/**
+ * The full preflight: decides, prints the single line each outcome calls
+ * for (or nothing, for the common `up-to-date`/`skip-preflight`/`dev-mode`
+ * cases — see each branch), and re-execs on `self-refresh`. Returns once
+ * for every other outcome so `launch()` can continue dispatching the
+ * original command.
+ */
+export declare function runPreflight(options: PreflightOptions & {
+    reexec?: typeof selfRefresh;
+}): Promise<PreflightAction>;
+/** The directory this module's compiled file lives in one level under —
+ * i.e. the devtools package's own root (`dist/repo/preflight.js` → up two).
+ * Exported for tests; memoized since it never changes within a process. */
+export declare function ownPackageDir(): string;
+/** Reads this build's own `package.json` — the version preflight compares
+ * against the manifest, and the value dev-mode detection inspects. */
+export declare function ownVersion(): string;
+/**
+ * True when this devtools is running from a workspace/dev checkout rather
+ * than a published install — a `pnpm build && node ./bin/devtools.mjs` run
+ * inside `Backstage/packages/devtools` itself, or any other case where the
+ * package's own directory is not sitting under a `node_modules` tree (a
+ * real install — via dlx's isolated cache or an ordinary `node_modules` —
+ * always puts it under one). `version: "0.0.0-dev"` is the explicit,
+ * unambiguous override for anything that wants to force this (a fixture,
+ * an integration test); the path heuristic is the sensible default so
+ * nobody has to remember to set it.
+ */
+export declare function isDevMode(version?: string, dir?: string): boolean;
+export {};

package/dist/repo/preflight.js

@@ -0,0 +1,266 @@
+/**
+ * The dlx-distribution preflight: fetches a tiny minimums manifest from
+ * DevDogsUGA's `main` branch, compares it against this build's own version,
+ * and decides whether to proceed, nudge, or self-refresh by re-exec'ing
+ * `pnpm dlx @devdogsuga/devtools@<latest>`.
+ *
+ * Ported from the `devtools-dlx` prototype
+ * (`/home/sloan/scratchpad/devdogs/prototypes/devtools-dlx/FINDINGS.md`,
+ * experiment 7 and its "Recommended contract" section) — read that file for
+ * why each design choice below is the one that survived testing rather than
+ * the first thing that seemed reasonable:
+ *
+ *   - The re-exec spec MUST be an exact version (`@devdogsuga/devtools@0.4.2`),
+ *     never a bare spec. Experiment 6 found TWO independent staleness
+ *     mechanisms a bare spec (even with `dlx-cache-max-age=0`) does not
+ *     reliably bypass: pnpm's dlx cache TTL, and pnpm 11's
+ *     `minimumReleaseAge` cooldown on a just-published version. Only an
+ *     exact pinned spec bypasses both.
+ *   - `--config.registry=<url>`, not `--registry` after `dlx` — pnpm 11
+ *     rejects the latter positioned there.
+ *   - The manifest fetch fails open (log + proceed on the current version)
+ *     on ANY error — dead host, timeout, malformed JSON, schema mismatch —
+ *     so an offline contributor is never blocked by this check.
+ *
+ * `devtools-ci` (`launch-ci.ts`) never calls this module — CI pins an exact
+ * version on purpose (see the carve-out plan's §9 Wave 2 decisions), and a
+ * self-refreshing CI job would defeat that pin.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+/** Env var set on the re-exec'd child so a still-below-minimum child refuses
+ * to loop a second time instead of re-exec'ing forever. */
+const LOOP_GUARD_ENV = "DEVTOOLS_REEXEC_GUARD";
+/** Default location of the manifest — a repo-root file in DevDogsUGA's own
+ * `main` branch, not buried inside a package, so it survives reorganization
+ * and is a trivial hotfix-PR edit. Overridable for tests and for use before
+ * the file exists on the real remote. */
+const DEFAULT_MINIMUMS_URL = "https://raw.githubusercontent.com/DevDogsUGA/DevDogsUGA/main/devtools-minimums.json";
+const FETCH_TIMEOUT_MS = 1500;
+/**
+ * Deliberately short — 10 minutes, not the plan's original "a few hours" —
+ * so a mid-meeting hotfix (someone drops the `minimum` to force a
+ * self-refresh) propagates to every contributor's next command within one
+ * coffee break, not one workday. This is the one place stage A2 knowingly
+ * overrides §5's original wording; see the carve-out plan's §9 note.
+ */
+const CACHE_TTL_MS = 10 * 60 * 1000;
+const ManifestSchema = z.object({
+    devtools: z.object({
+        latest: z.string().min(1),
+        minimum: z.string().min(1),
+    }),
+});
+function xdgCacheHome() {
+    const fromEnv = process.env.XDG_CACHE_HOME;
+    return fromEnv !== undefined && fromEnv !== "" ? fromEnv : join(homedir(), ".cache");
+}
+/** Exported so tests can point elsewhere without touching the real `~/.cache`. */
+export function cacheFilePath() {
+    return join(xdgCacheHome(), "devdogsuga-devtools", "minimums.json");
+}
+function readCache(url) {
+    const file = cacheFilePath();
+    if (!existsSync(file))
+        return null;
+    try {
+        const entry = JSON.parse(readFileSync(file, "utf8"));
+        if (entry.url !== url)
+            return null;
+        if (Date.now() - entry.fetchedAt > CACHE_TTL_MS)
+            return null;
+        const parsed = ManifestSchema.safeParse(entry.manifest);
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(url, manifest) {
+    try {
+        const file = cacheFilePath();
+        mkdirSync(dirname(file), { recursive: true });
+        const entry = { fetchedAt: Date.now(), url, manifest };
+        writeFileSync(file, JSON.stringify(entry));
+    }
+    catch {
+        // Best-effort. A cache write failure (read-only home dir, full disk,
+        // whatever) must never fail the command it is only trying to speed up
+        // next time.
+    }
+}
+/**
+ * Fetches (or reads the disk cache for) the minimums manifest. Never
+ * throws: any failure — timeout, network error, non-200, invalid JSON,
+ * schema mismatch — comes back as `{ manifest: null, source: "fail-open" }`.
+ */
+export async function fetchManifest(options) {
+    const url = options?.url ?? process.env.DEVTOOLS_MINIMUMS_URL ?? DEFAULT_MINIMUMS_URL;
+    const timeoutMs = options?.timeoutMs ?? FETCH_TIMEOUT_MS;
+    if (options?.skipCache !== true) {
+        const cached = readCache(url);
+        if (cached)
+            return { manifest: cached, source: "cache" };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        if (!res.ok)
+            throw new Error(`manifest fetch: HTTP ${res.status}`);
+        const json = await res.json();
+        const parsed = ManifestSchema.safeParse(json);
+        if (!parsed.success) {
+            throw new Error(`manifest fetch: invalid shape (${parsed.error.message})`);
+        }
+        writeCache(url, parsed.data);
+        return { manifest: parsed.data, source: "network" };
+    }
+    catch (err) {
+        return { manifest: null, source: "fail-open", error: errorText(err) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Three-part semver comparison; `<0` means `a` is older than `b`. Anything
+ * non-numeric in a segment sorts as `0`, which is permissive on purpose —
+ * this only ever compares two well-formed manifest/package versions. */
+function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * Runs the decision half of preflight. Does not itself re-exec or print —
+ * `runPreflight` below does both, so the pure decision stays independently
+ * testable (loop guard, fail-open, version comparisons) without spawning a
+ * real child process in every test.
+ */
+export async function decidePreflight(options) {
+    if (options.skipPreflight)
+        return { action: "skip-preflight" };
+    if (options.devMode === true)
+        return { action: "dev-mode" };
+    const { manifest, source, error } = await fetchManifest({
+        url: options.manifestUrl,
+        skipCache: options.refresh,
+    });
+    if (!manifest) {
+        return { action: "fail-open", reason: error ?? "unknown error" };
+    }
+    const { latest, minimum } = manifest.devtools;
+    if (compareVersions(options.currentVersion, minimum) < 0) {
+        if (process.env[LOOP_GUARD_ENV]) {
+            return {
+                action: "loop-guard-tripped",
+                detail: `already re-exec'd once (${LOOP_GUARD_ENV}=${process.env[LOOP_GUARD_ENV]}); refusing to loop again`,
+            };
+        }
+        return { action: "self-refresh", from: options.currentVersion, to: latest, source };
+    }
+    if (compareVersions(options.currentVersion, latest) < 0) {
+        return { action: "nudge", from: options.currentVersion, to: latest, source };
+    }
+    return { action: "up-to-date", source };
+}
+/**
+ * Re-execs as the exact pinned `version`, inheriting stdio and propagating
+ * the child's exit code. Never returns — the caller relies on this to end
+ * the process, matching `spawnSync`'s synchronous nature (there is nothing
+ * meaningful left to do in this process either way).
+ *
+ * Exported separately from `runPreflight` so tests can stub it instead of
+ * spawning a real `pnpm dlx`.
+ */
+export function selfRefresh(options) {
+    const spec = `@devdogsuga/devtools@${options.version}`;
+    const registryArgs = options.registry !== undefined ? [`--config.registry=${options.registry}`] : [];
+    const result = spawnSync("pnpm", ["dlx", ...registryArgs, spec, ...options.argv], {
+        stdio: "inherit",
+        env: { ...process.env, [LOOP_GUARD_ENV]: "1" },
+    });
+    process.exit(result.status ?? 1);
+}
+/**
+ * The full preflight: decides, prints the single line each outcome calls
+ * for (or nothing, for the common `up-to-date`/`skip-preflight`/`dev-mode`
+ * cases — see each branch), and re-execs on `self-refresh`. Returns once
+ * for every other outcome so `launch()` can continue dispatching the
+ * original command.
+ */
+export async function runPreflight(options) {
+    const decision = await decidePreflight(options);
+    const reexec = options.reexec ?? selfRefresh;
+    switch (decision.action) {
+        case "skip-preflight":
+        case "dev-mode":
+        case "up-to-date":
+            // Silent — see the module header: this runs on every command, and a
+            // line of noise on the overwhelmingly common "nothing to do" path
+            // would defeat the point of the check running unconditionally.
+            break;
+        case "fail-open":
+            process.stderr.write(`devtools: preflight check skipped (${decision.reason})\n`);
+            break;
+        case "loop-guard-tripped":
+            process.stderr.write(`devtools: still below the minimum version after one self-refresh attempt; ` +
+                `continuing on the current version instead of looping (${decision.detail})\n`);
+            break;
+        case "nudge":
+            process.stderr.write(`devtools: a newer version (${decision.to}) is available — you're on ${decision.from}. ` +
+                `Run with --refresh, or it'll catch up on its own shortly.\n`);
+            break;
+        case "self-refresh":
+            process.stderr.write(`devtools: ${decision.from} is below the minimum supported version — ` +
+                `relaunching as ${decision.to}...\n`);
+            reexec({ version: decision.to, argv: options.argv, registry: options.registry });
+            break;
+    }
+    return decision;
+}
+let cachedOwnDir;
+/** The directory this module's compiled file lives in one level under —
+ * i.e. the devtools package's own root (`dist/repo/preflight.js` → up two).
+ * Exported for tests; memoized since it never changes within a process. */
+export function ownPackageDir() {
+    if (cachedOwnDir === undefined) {
+        cachedOwnDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    }
+    return cachedOwnDir;
+}
+/** Reads this build's own `package.json` — the version preflight compares
+ * against the manifest, and the value dev-mode detection inspects. */
+export function ownVersion() {
+    const pkg = JSON.parse(readFileSync(join(ownPackageDir(), "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+}
+/**
+ * True when this devtools is running from a workspace/dev checkout rather
+ * than a published install — a `pnpm build && node ./bin/devtools.mjs` run
+ * inside `Backstage/packages/devtools` itself, or any other case where the
+ * package's own directory is not sitting under a `node_modules` tree (a
+ * real install — via dlx's isolated cache or an ordinary `node_modules` —
+ * always puts it under one). `version: "0.0.0-dev"` is the explicit,
+ * unambiguous override for anything that wants to force this (a fixture,
+ * an integration test); the path heuristic is the sensible default so
+ * nobody has to remember to set it.
+ */
+export function isDevMode(version = ownVersion(), dir = ownPackageDir()) {
+    if (version === "0.0.0-dev")
+        return true;
+    const marker = `${sep}node_modules${sep}`;
+    return !dir.includes(marker);
+}

package/dist/repo/resolve.d.ts

@@ -0,0 +1,41 @@
+export interface ResolvedFromRepo {
+    /** Absolute path to the resolved module entry point. */
+    resolvedPath: string;
+    /** The version declared in the resolved package's own `package.json`. */
+    version: string;
+    /** Absolute path to the resolved package's `package.json`. */
+    pkgJsonPath: string;
+}
+/**
+ * The installable package name a (possibly subpath) specifier belongs to:
+ * `@devdogsuga/env/load` → `@devdogsuga/env`, `foo/bar` → `foo`. A repo's
+ * package.json declares the PACKAGE as a dependency, never a subpath, so
+ * `findDependent` has to search on this rather than the literal specifier a
+ * caller wants to import.
+ */
+export declare function packageNameOf(specifier: string): string;
+/**
+ * Scans `apps/*` and `packages/*` under `repoRoot` for the first
+ * `package.json` whose `dependencies`/`devDependencies`/`peerDependencies`
+ * names `specifier`'s package (see `packageNameOf`). Returns its path
+ * relative to `repoRoot`, or `null` if nothing in the repo depends on it.
+ *
+ * Re-scans the filesystem on every call — fine for a short-lived CLI
+ * invocation calling this a handful of times; see FINDINGS item 5 if this
+ * is ever called in a hot loop.
+ */
+export declare function findDependent(repoRoot: string, specifier: string): string | null;
+/**
+ * Resolves `specifier` as `resolutionBase` (a workspace-relative
+ * `package.json` path known to depend on it, from `findDependent()`) would
+ * see it.
+ *
+ * `opts.condition`, when given, is NOT passed through to Node's resolver —
+ * `require.resolve` ignores tsx's `register({ conditions })` entirely (see
+ * this module's header). Instead the target package's own
+ * `exports["."]` map is read directly and `exports["."][condition]` is
+ * picked, falling back to `.default`.
+ */
+export declare function resolveFromRepo(repoRoot: string, resolutionBase: string, specifier: string, opts?: {
+    condition?: string;
+}): ResolvedFromRepo;

package/dist/repo/resolve.js

@@ -0,0 +1,152 @@
+/**
+ * Resolves an `@devdogsuga/*` package FROM the target repo, not from
+ * devtools' own (dlx-isolated) `node_modules`.
+ *
+ * Ported from the `devtools-dlx` prototype
+ * (`/home/sloan/scratchpad/devdogs/prototypes/devtools-dlx/FINDINGS.md`,
+ * experiments 2 and 4 — read that file for the two gotchas this module
+ * exists to avoid). The short version:
+ *
+ *   - `require.resolve(\`${specifier}/package.json\`)` throws
+ *     `ERR_PACKAGE_PATH_NOT_EXPORTED` on packages (like `@devdogsuga/env`,
+ *     `@devdogsuga/open-graph`) whose `exports` map does not list
+ *     `"./package.json"`, even though the file is on disk.
+ *   - A resolved path cannot be assumed to contain a literal
+ *     `node_modules/<specifier>` segment — pnpm workspace-linked packages
+ *     resolve to their REALPATH (e.g. `packages/open-graph/dist/index.js`),
+ *     which has no such segment at all.
+ *   - `require.resolve` ignores whatever `conditions` a caller has set on
+ *     `tsx`'s `register()` — condition-based resolution (the
+ *     `devdogs-source` condition) has to be done by hand, reading the
+ *     target package's own `exports["."]` map.
+ *
+ * Both problems are solved the same way: walk up from the resolved file's
+ * directory to the nearest `package.json` whose own `"name"` field matches
+ * the specifier. That works for a real installed dependency AND a
+ * workspace symlink, uniformly.
+ */
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * The installable package name a (possibly subpath) specifier belongs to:
+ * `@devdogsuga/env/load` → `@devdogsuga/env`, `foo/bar` → `foo`. A repo's
+ * package.json declares the PACKAGE as a dependency, never a subpath, so
+ * `findDependent` has to search on this rather than the literal specifier a
+ * caller wants to import.
+ */
+export function packageNameOf(specifier) {
+    const parts = specifier.split("/");
+    return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+/**
+ * Scans `apps/*` and `packages/*` under `repoRoot` for the first
+ * `package.json` whose `dependencies`/`devDependencies`/`peerDependencies`
+ * names `specifier`'s package (see `packageNameOf`). Returns its path
+ * relative to `repoRoot`, or `null` if nothing in the repo depends on it.
+ *
+ * Re-scans the filesystem on every call — fine for a short-lived CLI
+ * invocation calling this a handful of times; see FINDINGS item 5 if this
+ * is ever called in a hot loop.
+ */
+export function findDependent(repoRoot, specifier) {
+    const packageName = packageNameOf(specifier);
+    const groups = ["apps", "packages"];
+    for (const group of groups) {
+        const groupDir = join(repoRoot, group);
+        let entries;
+        try {
+            entries = readdirSync(groupDir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const pkgJsonPath = join(groupDir, entry, "package.json");
+            if (!existsSync(pkgJsonPath))
+                continue;
+            let pkg;
+            try {
+                pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            const deps = {
+                ...pkg.dependencies,
+                ...pkg.devDependencies,
+                ...pkg.peerDependencies,
+            };
+            if (packageName in deps) {
+                return join(group, entry, "package.json");
+            }
+        }
+    }
+    return null;
+}
+/** Walks up from `startDir` to the nearest `package.json` whose `"name"` matches `specifier`. */
+function findOwningPackageJson(startDir, specifier) {
+    const packageName = packageNameOf(specifier);
+    let dir = startDir;
+    for (;;) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (pkg.name === packageName)
+                    return candidate;
+            }
+            catch {
+                // fall through and keep walking
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error(`resolveFromRepo: could not find ${specifier}'s own package.json by walking up from ${startDir}`);
+        }
+        dir = parent;
+    }
+}
+/**
+ * Resolves `specifier` as `resolutionBase` (a workspace-relative
+ * `package.json` path known to depend on it, from `findDependent()`) would
+ * see it.
+ *
+ * `opts.condition`, when given, is NOT passed through to Node's resolver —
+ * `require.resolve` ignores tsx's `register({ conditions })` entirely (see
+ * this module's header). Instead the target package's own
+ * `exports["."]` map is read directly and `exports["."][condition]` is
+ * picked, falling back to `.default`.
+ */
+export function resolveFromRepo(repoRoot, resolutionBase, specifier, opts) {
+    const baseFile = join(repoRoot, resolutionBase);
+    const require = createRequire(baseFile);
+    let resolvedPath;
+    if (opts?.condition) {
+        // Find the package's own package.json first (via a plain resolve of the
+        // specifier itself, which DOES work through node's default conditions),
+        // then read its exports map by hand.
+        const defaultEntry = require.resolve(specifier);
+        const pkgJsonPath = findOwningPackageJson(dirname(defaultEntry), specifier);
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+        const rootExport = pkg.exports?.["."];
+        const conditioned = rootExport && typeof rootExport === "object"
+            ? (rootExport[opts.condition] ??
+                rootExport.default)
+            : undefined;
+        if (typeof conditioned !== "string") {
+            throw new Error(`resolveFromRepo: ${specifier} has no "${opts.condition}" (or "default") export in its exports["."] map`);
+        }
+        resolvedPath = join(dirname(pkgJsonPath), conditioned);
+    }
+    else {
+        resolvedPath = require.resolve(specifier);
+    }
+    const pkgJsonPath = findOwningPackageJson(dirname(resolvedPath), specifier);
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+    return {
+        resolvedPath,
+        version: pkg.version ?? "0.0.0",
+        pkgJsonPath,
+    };
+}