@devdogsuga/devtools 0.1.0

package/dist/repo/root.d.ts

@@ -0,0 +1,23 @@
+export declare class RepoNotFoundError extends Error {
+    constructor();
+}
+/**
+ * Walks up from `startDir` (default `process.cwd()`) looking for the repo
+ * marker. Returns `null` rather than throwing — `findRepoRoot()` below is
+ * the throwing convenience most callers want; this is exported for callers
+ * (like `setup`) that need to know without failing.
+ */
+export declare function discoverRepoRoot(startDir?: string): string | null;
+/**
+ * The memoized, throwing repo-root lookup. Lazy on purpose: importing this
+ * module must never fail just because nothing has called it yet (`setup`
+ * and `completions` in `launch.ts` never need a repo at all, and must stay
+ * that way — see that file's header comment on why).
+ *
+ * Resolved once per process: `process.cwd()` does not change mid-invocation
+ * for this CLI, and re-walking the filesystem on every call would be pure
+ * waste.
+ */
+export declare function findRepoRoot(): string;
+/** Test-only: clears the memoized root so a test can point `process.cwd()` elsewhere. */
+export declare function resetRepoRootCacheForTests(): void;

package/dist/repo/root.js

@@ -0,0 +1,91 @@
+/**
+ * Where devtools finds the DevDogsUGA checkout it is running against.
+ *
+ * devtools used to live inside `packages/devtools` of that repo, so its own
+ * `import.meta.url` WAS a path into the repo (`PROJECT_ROOT` /
+ * `REPO_ROOT` walked up a fixed number of `..` segments from this file).
+ * Published as its own package and run through `pnpm dlx`, that assumption
+ * breaks: this file's `import.meta.url` points into a dlx cache directory
+ * or an isolated `node_modules` tree that has nothing to do with the repo
+ * the contributor is standing in.
+ *
+ * So repo discovery walks up from `process.cwd()` instead, looking for the
+ * marker validated in the `devtools-dlx` prototype
+ * (`/home/sloan/scratchpad/devdogs/prototypes/devtools-dlx/FINDINGS.md`,
+ * experiment 1): a directory containing `pnpm-workspace.yaml` AND whose
+ * `package.json` has `"name": "devdogs-monorepo"`. The name check is not
+ * redundant — a bare `pnpm-workspace.yaml` also matches a Backstage
+ * checkout (a separate pnpm workspace), which devtools should refuse
+ * rather than silently "find".
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** The `package.json` name every real DevDogsUGA checkout carries at its root. */
+const REPO_MARKER_NAME = "devdogs-monorepo";
+export class RepoNotFoundError extends Error {
+    constructor() {
+        super("run this from inside a DevDogsUGA clone");
+        this.name = "RepoNotFoundError";
+    }
+}
+function looksLikeRepoRoot(dir) {
+    if (!existsSync(join(dir, "pnpm-workspace.yaml")))
+        return false;
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        return pkg.name === REPO_MARKER_NAME;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walks up from `startDir` (default `process.cwd()`) looking for the repo
+ * marker. Returns `null` rather than throwing — `findRepoRoot()` below is
+ * the throwing convenience most callers want; this is exported for callers
+ * (like `setup`) that need to know without failing.
+ */
+export function discoverRepoRoot(startDir = process.cwd()) {
+    let dir = startDir;
+    for (;;) {
+        if (looksLikeRepoRoot(dir))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+let cachedRoot;
+/**
+ * The memoized, throwing repo-root lookup. Lazy on purpose: importing this
+ * module must never fail just because nothing has called it yet (`setup`
+ * and `completions` in `launch.ts` never need a repo at all, and must stay
+ * that way — see that file's header comment on why).
+ *
+ * Resolved once per process: `process.cwd()` does not change mid-invocation
+ * for this CLI, and re-walking the filesystem on every call would be pure
+ * waste.
+ */
+export function findRepoRoot() {
+    if (cachedRoot === undefined) {
+        // Backstage's own test suite has no DevDogsUGA checkout to discover —
+        // it IS a different pnpm workspace — but most of devtools' unit tests
+        // exercise code that calls `findRepoRoot()` only to build a path string
+        // that a mocked `node:fs/promises` never actually reads. Rather than
+        // adding a `vi.mock("../repo/root.js", ...)` to every one of those
+        // files, `vitest.config.ts` sets this one env var for the whole run so
+        // `findRepoRoot()` resolves to a stable fake path instead of throwing.
+        // A test that specifically wants the real "not in a repo" refusal
+        // (`RepoNotFoundError`) unsets it locally — see `root.test.ts`.
+        cachedRoot = process.env.DEVTOOLS_TEST_REPO_ROOT ?? discoverRepoRoot();
+    }
+    if (cachedRoot === null) {
+        throw new RepoNotFoundError();
+    }
+    return cachedRoot;
+}
+/** Test-only: clears the memoized root so a test can point `process.cwd()` elsewhere. */
+export function resetRepoRootCacheForTests() {
+    cachedRoot = undefined;
+}

package/dist/repo/source.d.ts

@@ -0,0 +1,14 @@
+/** Test-only: clears the memoized source modules. */
+export declare function resetSourceCacheForTests(): void;
+import type { OpenGraphModule } from "../images/open-graph-types.js";
+export declare function loadOpenGraph(): Promise<OpenGraphModule>;
+import type { EmailTemplates } from "../emails/email-types.js";
+export interface EmailModule {
+    render<K extends keyof EmailTemplates>(name: K, props: EmailTemplates[K]): {
+        subject: string;
+        html: string;
+        text: string;
+    };
+}
+export declare function loadEmail(): Promise<EmailModule>;
+export declare function loadDocs(): Promise<unknown>;

package/dist/repo/source.js

@@ -0,0 +1,54 @@
+/**
+ * Loads the repo-local, never-published `@devdogsuga/*` packages devtools
+ * needs at runtime: `open-graph`, `email`, `docs`. Unlike the
+ * `peers.ts` set, these are `"private": true` in the target repo and never
+ * reach npm — devtools resolves them straight out of the repo's own
+ * `node_modules` (a pnpm workspace symlink) using the `devdogs-source`
+ * export condition, picked by hand (see `resolve.ts`'s header and
+ * FINDINGS.md experiment 4 for why this can't go through
+ * `require.resolve`/tsx's `register({ conditions })`).
+ *
+ * `open-graph` and `email` both declare a `"devdogs-source"` entry in their
+ * `exports["."]` map, pointing at TS source. `docs` does not (its `default`
+ * points straight at a built `dist/index.js`, produced by
+ * `docs-compiler`) — `resolveFromRepo` falls back to `.default` for it,
+ * and routing the result through the same tsx-backed import as the other
+ * two is harmless: tsx passes plain `.js` through unchanged.
+ */
+import { findRepoRoot } from "./root.js";
+import { findDependent, resolveFromRepo } from "./resolve.js";
+import { importRepoTs } from "./tsx-loader.js";
+const CONDITION = "devdogs-source";
+const cache = new Map();
+function loadSource(specifier) {
+    const cached = cache.get(specifier);
+    if (cached)
+        return cached;
+    const promise = (async () => {
+        const repoRoot = findRepoRoot();
+        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.`);
+        }
+        const { resolvedPath } = resolveFromRepo(repoRoot, resolutionBase, specifier, {
+            condition: CONDITION,
+        });
+        return importRepoTs(resolvedPath);
+    })();
+    cache.set(specifier, promise);
+    return promise;
+}
+/** Test-only: clears the memoized source modules. */
+export function resetSourceCacheForTests() {
+    cache.clear();
+}
+export function loadOpenGraph() {
+    return loadSource("@devdogsuga/open-graph");
+}
+export function loadEmail() {
+    return loadSource("@devdogsuga/email");
+}
+export function loadDocs() {
+    return loadSource("@devdogsuga/docs");
+}

package/dist/repo/tsx-loader.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Imports a repo TypeScript file at an absolute path, loaded through tsx.
+ * Returns the module namespace, typed as `T` by the caller (there is no way
+ * to know the shape of an arbitrary repo file's exports statically here).
+ */
+export declare function importRepoTs<T>(absolutePath: string): Promise<T>;

package/dist/repo/tsx-loader.js

@@ -0,0 +1,41 @@
+/**
+ * Loads the repo's own TypeScript at runtime: env manifests
+ * (each app's `src/env.ts` and friends), cron contracts
+ * (each app's `cloudflare/scheduled.ts`), and — via `source.ts` — the
+ * `devdogs-source` condition packages (`open-graph`, `email`, `docs`).
+ *
+ * Uses `tsx`'s programmatic API (`register()` from `tsx/esm/api`), NOT the
+ * `--conditions=devdogs-source` CLI flag the old in-repo devtools used —
+ * this package ships built JS and runs from `dist/`, so there is no `tsx`
+ * process wrapping it anymore (see the package README / CUTOVER note on
+ * "built JS, tsx only for repo TS").
+ *
+ * Gotcha (FINDINGS.md experiments 3 and 4, gotcha C): do NOT pass a
+ * `namespace` to `register()`. It silently breaks tsx's own relative
+ * `./foo.js` → `./foo.ts` extension-fallback resolution for files loaded
+ * under that registration — exactly the convention `open-graph`, `email`,
+ * and any future `devdogs-source` package use for their internal relative
+ * imports. `register({})` (no options) is the only form validated.
+ */
+import { pathToFileURL } from "node:url";
+let registered = false;
+/** Idempotent: registers tsx's ESM loader hooks once per process. */
+async function ensureRegistered() {
+    if (registered)
+        return;
+    const { register } = await import("tsx/esm/api");
+    // `register()`'s return value is an unregister callback (`() => Promise<void>`),
+    // not something this process ever calls: the hooks stay installed for the
+    // CLI's whole lifetime.
+    register();
+    registered = true;
+}
+/**
+ * Imports a repo TypeScript file at an absolute path, loaded through tsx.
+ * Returns the module namespace, typed as `T` by the caller (there is no way
+ * to know the shape of an arbitrary repo file's exports statically here).
+ */
+export async function importRepoTs(absolutePath) {
+    await ensureRegistered();
+    return import(pathToFileURL(absolutePath).href);
+}

package/dist/run/pick.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Whether to ask at all.
+ *
+ * Every one of these is a case where a prompt is either impossible or wrong:
+ *
+ *   * `CI`, set by GitHub Actions and every other runner. No workflow reaches
+ *     this today (see the header), but a workflow that blocked on a
+ *     multiselect would hang until its timeout with no output saying why, and
+ *     that failure is bad enough to keep guarding against.
+ *   * No TTY: a pipe, a `pnpm` invoked by a script, an editor task runner.
+ *     Nobody is there to answer. Every other picker in this repo checks the
+ *     same thing.
+ *   * An explicit filter. The caller has already said which packages, and
+ *     asking again would be asking them to repeat themselves.
+ *   * `DEVDOGS_PICK=0`, the escape hatch and the recursion guard above.
+ */
+export declare function shouldAsk(args: string[]): boolean;
+/**
+ * Pulls every `--filter`/`-F`/`--scope` value out of `args`, returning the
+ * package patterns named and the remaining args with those flags removed.
+ *
+ * `--scope` is folded into the same bucket as `--filter` here: pnpm has no
+ * `--scope` flag of its own, so a caller who still types the turbo-era name
+ * gets it translated into a real `--filter` value rather than passed through
+ * to a `pnpm` invocation that would reject it outright.
+ *
+ * Exported for the same reason `parseTierArg` is: pure, no `process.exit`, so
+ * it is unit-testable without going through `passthrough`.
+ */
+export declare function extractFilters(args: readonly string[]): {
+    filters: string[];
+    rest: string[];
+};
+export interface TierArgResult {
+    /** The validated tier, or absent when `--tier` was not passed. */
+    tier?: string;
+    /** `args` with `--tier` and its value removed, so pnpm never sees them. */
+    rest: string[];
+    /** Set instead of `tier` when parsing failed; `rest` is unchanged on error. */
+    error?: string;
+}
+/**
+ * Parses and strips `--tier <value>` from pnpm-bound args, mirroring the
+ * `--all` strip above.
+ *
+ * Pure on purpose — no `process.exit` — so this is unit-testable without
+ * going through `passthrough`, which every other path in this file ends at
+ * and which a test cannot observe return from. `runTask` is the one caller,
+ * and it is the one that turns `error` into an exit.
+ */
+export declare function parseTierArg(args: readonly string[]): TierArgResult;
+/**
+ * Runs one root task, asking which apps first where that makes sense.
+ *
+ * Never returns: every path ends in `passthrough`, which exits with the
+ * underlying `pnpm` invocation's own status. That is why `cli.ts` dispatches
+ * this before `intro()`. There is no `outro()` to reach, and a banner would
+ * land on the stream a dev server is about to take over.
+ */
+export declare function runTask(argv: string[]): Promise<never>;