@devdogsuga/devtools 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @devdogsuga/devtools
+
+Contributor CLI for workspace tasks, runtime infrastructure, generated
+content, configuration, and moderation checks.
+
+```bash
+pnpm devtools                      # no arguments: menu of interactive commands
+pnpm devtools db start             # boot Supabase on this machine
+pnpm devtools db connect <ref>     # or register a hosted project as the remote target
+pnpm devtools db reset             # replay migrations, then seeds, then regenerate types
+pnpm devtools cron run             # choose a configured route cron
+pnpm devtools workflows run        # choose a configured Cloudflare Workflow
+pnpm devtools workflows serve      # keep an app-scoped Wrangler runtime open
+```
+
+The menu is generated from the same command tree the argv parser walks, so
+there is no second list to fall out of step — reach for `--help` at any level
+rather than a table here.
+
+## Telemetry disclosure
+
+This CLI reports its own crashes to Sentry (see `src/telemetry.ts`), on by
+default, in both `pnpm devtools` and `devtools-ci`:
+
+- **What**: uncaught errors only — a captured exception plus a `command` tag
+  naming the subcommand that threw (e.g. `db reset`, `deploy platform`).
+  Nothing about a successful run is ever sent.
+- **When**: every run, unless `DEVTOOLS_TELEMETRY=0` is set (per-machine or
+  per-job opt-out) — or `DEVTOOLS_SENTRY_DSN` is unset, which is the state of
+  local development until an operator configures one and the state of every
+  environment until the devtools Sentry project exists at all (see the
+  committed placeholder in `src/telemetry.ts`). Either condition means no
+  `Sentry.init()` call happens: no network request, no console output.
+- **What's scrubbed**: this CLI touches local `.env` files, so every event
+  passes through
+  `@devdogsuga/telemetry`'s shared scrubbers before it leaves the process —
+  file paths reduced to basenames, email addresses redacted, and
+  token/secret-shaped values stripped out of messages, breadcrumbs, and
+  stack frames. See Backstage's `packages/telemetry/src/scrub.ts` for exactly what each
+  scrubber matches.
+
+[Command guide](../../docs/toolkit/guides/devtools.md) ·
+[API reference](https://devdogsuga.org/docs/toolkit/reference/api/devtools) ·
+[Quickstart](../../docs/monorepo/guides/quickstart.md)

package/bin/devtools-ci-bare.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the `devtools-ci-bare` bin: `ci.ts`'s `main()` with no tier
+ * resolution and no env-file loading — the counterpart to the old in-repo
+ * `"ci": "tsx --conditions=devdogs-source src/ci.ts"` package script.
+ *
+ * `devtools-ci` (`bin/devtools-ci.mjs` -> `src/launch-ci.ts`) ALWAYS resolves
+ * a deploy tier and calls `enterEnvironment` before dispatching to `ci.ts`.
+ * That's wrong for two kinds of CI step: `deploy write-env`, which CREATES
+ * the env file tier resolution would otherwise insist on reading first (a
+ * bootstrap cycle), and the handful of steps that hold one narrow credential
+ * via the job's own `env:` block and compose no env file at all (`preflight`,
+ * `migrate`, `plan`, `require-planner`, `require-token`, `orphans`). Those
+ * steps need `ci.ts`'s `main()` with nothing in front of it.
+ *
+ * Same technique as `bin/devtools.mjs` and `bin/devtools-ci.mjs` — see
+ * `bin/devtools.mjs`'s header — except it imports `dist/ci.js` directly
+ * rather than going through a `launch*.ts` wrapper: `ci.ts` has no
+ * tier-resolution step to run first, so there is nothing for a wrapper
+ * module to do. `dist/ci.js`'s own self-invoke guard
+ * (`import.meta.url === file://${process.argv[1]}`) does not fire here —
+ * `process.argv[1]` is this bin script, not `dist/ci.js` — so importing it
+ * only defines `main`, exactly like `bin/devtools-ci.mjs`'s import of
+ * `launch-ci.js` relies on.
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ciEntry = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "dist",
+  "ci.js",
+);
+
+const { main } = await import(ciEntry);
+try {
+  await main(process.argv.slice(2));
+} catch (err) {
+  process.stderr.write(
+    `devtools-ci-bare: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  const { captureDevtoolsError } = await import(
+    join(dirname(fileURLToPath(import.meta.url)), "..", "dist", "telemetry.js")
+  );
+  await captureDevtoolsError(err);
+  process.exitCode = 1;
+}

package/bin/devtools-ci.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the `devtools-ci` bin. Same technique as `bin/devtools.mjs`
+ * — see that file's header — pointed at `dist/launch-ci.js` instead.
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const launchCiEntry = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "dist",
+  "launch-ci.js",
+);
+
+const { launchCi } = await import(launchCiEntry);
+await launchCi(process.argv.slice(2));

package/bin/devtools.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the `devtools` bin.
+ *
+ * Ships built JS (see the package's `build` script — `tsc` to `dist/`) and
+ * runs it directly with plain `node`: no `tsx` wrapper, no
+ * `--conditions=devdogs-source` flag. Those were needed when devtools lived
+ * INSIDE the DevDogsUGA workspace and imported sibling `@devdogsuga/*`
+ * packages by TypeScript source; published as its own package and run via
+ * `pnpm dlx`, none of that applies — every `@devdogsuga/*` import now goes
+ * through `src/repo/peers.ts`/`src/repo/source.ts`'s runtime resolution
+ * against the TARGET repo instead, and `tsx` is a regular dependency used
+ * only programmatically (`src/repo/tsx-loader.ts`) to load that repo's own
+ * TypeScript (env manifests, cron contracts, `devdogs-source` packages).
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const launchEntry = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "dist",
+  "launch.js",
+);
+
+const { launch } = await import(launchEntry);
+await launch(process.argv.slice(2));

package/dist/args.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Positional arguments, with flag values excluded.
+ *
+ * Its own module because of one bug it prevents. The first positional is the
+ * subcommand, and `pull`, `push` and `audit` do very different things to live
+ * credentials. A naive `filter((a) => !a.startsWith("--"))` reads a flag's
+ * VALUE as a positional, so `env --file notes.env audit` fails loudly:
+ * `notes.env` is not a subcommand and the command refuses. The quiet version
+ * is the one that matters:
+ *
+ *     env --file push audit
+ *
+ * which runs `push`, writing to Bitwarden and GitHub, when the caller asked
+ * for `audit`, which writes nothing at all.
+ */
+/**
+ * Flags that consume the token after them.
+ *
+ * `--env` is here even though nothing accepts it any more. It was this CLI's
+ * spelling of `--target` until the two vocabularies behind it were merged, and
+ * a stale `env push --env staging` in somebody's shell history must not read
+ * `staging` as the subcommand. `cli.ts` rejects the flag by name instead,
+ * which says what happened.
+ */
+export declare const VALUE_FLAGS: Set<string>;
+export declare function positionals(argv: readonly string[]): string[];

package/dist/args.js

@@ -0,0 +1,78 @@
+/**
+ * Positional arguments, with flag values excluded.
+ *
+ * Its own module because of one bug it prevents. The first positional is the
+ * subcommand, and `pull`, `push` and `audit` do very different things to live
+ * credentials. A naive `filter((a) => !a.startsWith("--"))` reads a flag's
+ * VALUE as a positional, so `env --file notes.env audit` fails loudly:
+ * `notes.env` is not a subcommand and the command refuses. The quiet version
+ * is the one that matters:
+ *
+ *     env --file push audit
+ *
+ * which runs `push`, writing to Bitwarden and GitHub, when the caller asked
+ * for `audit`, which writes nothing at all.
+ */
+/**
+ * Flags that consume the token after them.
+ *
+ * `--env` is here even though nothing accepts it any more. It was this CLI's
+ * spelling of `--target` until the two vocabularies behind it were merged, and
+ * a stale `env push --env staging` in somebody's shell history must not read
+ * `staging` as the subcommand. `cli.ts` rejects the flag by name instead,
+ * which says what happened.
+ */
+export const VALUE_FLAGS = new Set([
+    "--access-token",
+    // `qr`: every value flag, so `qr --out poster.png https://…` still reads
+    // the URL as the text and not `poster.png`.
+    "--background",
+    "--color",
+    "--ecl",
+    "--format",
+    // `images`: so `images --format og page/events` reads `og` as the format and
+    // `page/events` as the graphic, not both as graphics.
+    "--format",
+    "--logo",
+    "--logo-padding",
+    "--logo-size",
+    "--margin",
+    "--out",
+    "--size",
+    "--text",
+    "--version",
+    "--app",
+    "--apps",
+    "--base-url",
+    "--env",
+    "--file",
+    "--source",
+    "--target",
+    "--tier",
+    "--cron",
+    "--workflow",
+    "--params",
+    "--port",
+    "--preview-url",
+    "--db-url",
+    "--user",
+    "--filter",
+    "--shell",
+]);
+export function positionals(argv) {
+    const found = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (!arg.startsWith("-")) {
+            found.push(arg);
+            continue;
+        }
+        // Skip the value, but only if it looks like one. `--file --yes` is a
+        // mistake, and swallowing `--yes` would turn it into a silent one.
+        const next = argv[i + 1];
+        if (VALUE_FLAGS.has(arg) && next !== undefined && !next.startsWith("-")) {
+            i += 1;
+        }
+    }
+    return found;
+}

package/dist/bws/bw.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Runs the Bitwarden CLI with `args`, then exits with its status.
+ *
+ * Returns a promise that never settles, because every path out of it ends in
+ * `process.exit`. That signature is load-bearing rather than pedantic: a
+ * `void` return would let the caller carry on and print `outro("Done.")`
+ * while `bw login` was still waiting for a master password.
+ */
+export declare function runBw(args: string[]): Promise<never>;

package/dist/bws/bw.js

@@ -0,0 +1,49 @@
+/**
+ * `pnpm devtools bw …`, the Bitwarden CLI passed through untouched.
+ *
+ * This is not a command of this CLI wearing a Bitwarden hat. Everything after
+ * `bw` goes to the real binary verbatim, and its exit code comes back
+ * verbatim, because the thing people actually run is `bw login` and its
+ * session handling is Bitwarden's business rather than ours.
+ *
+ * It exists because `@bitwarden/cli` is a dependency of this package, so the
+ * binary sits in devtools' own `node_modules/.bin` and nowhere else. Before
+ * this, reaching it meant a root alias (`pnpm bw`) that ran
+ * `pnpm --filter @devdogsuga/devtools exec bw`, the last script at the
+ * workspace root whose whole job was to reach into this package.
+ *
+ * ⚠️ `cwd` is deliberately NOT overridden, unlike the pnpm spawn in
+ * `run/pick.ts`. pnpm puts this package's `node_modules/.bin` on PATH as a
+ * relative entry, so moving the working directory would make `bw` unresolvable
+ * from the very place it is installed. Bitwarden does not care where it runs.
+ */
+import { spawn } from "node:child_process";
+/**
+ * Runs the Bitwarden CLI with `args`, then exits with its status.
+ *
+ * Returns a promise that never settles, because every path out of it ends in
+ * `process.exit`. That signature is load-bearing rather than pedantic: a
+ * `void` return would let the caller carry on and print `outro("Done.")`
+ * while `bw login` was still waiting for a master password.
+ */
+export function runBw(args) {
+    return new Promise(() => {
+        const child = spawn("bw", args, { stdio: "inherit" });
+        child.on("error", (err) => {
+            // ENOENT here means the dependency is not installed rather than that the
+            // user mistyped, so say the thing that fixes it.
+            console.error(`bw: ${err.message}\n` +
+                "The Bitwarden CLI ships as a devtools dependency — " +
+                "run `pnpm install` at the repo root.");
+            process.exit(1);
+        });
+        child.on("exit", (code, signal) => {
+            // Re-raise rather than translating to a number: a Ctrl-C in `bw login`
+            // should look to the shell exactly like a Ctrl-C in `bw login`.
+            if (signal)
+                process.kill(process.pid, signal);
+            else
+                process.exit(code ?? 1);
+        });
+    });
+}

package/dist/bws/client.d.ts

@@ -0,0 +1,43 @@
+export declare class BwsError extends Error {
+}
+export interface BwsSecret {
+    id: string;
+    key: string;
+    value: string;
+    note: string;
+    projectId: string;
+    /**
+     * ISO 8601, when this secret last changed.
+     *
+     * Optional because push and pull do not need it. It is the whole basis of
+     * the staleness half of `env audit`, which cannot compare values (GitHub
+     * secrets are write-only) and instead asks whether GitHub was updated after
+     * this.
+     */
+    revisionDate?: string;
+}
+/** Records `--access-token`, before any command runs. */
+export declare function setExplicitAccessToken(token: string | undefined): void;
+/**
+ * The access token, found once per process.
+ *
+ * Memoized as a **promise**, not a value: resolution can prompt, and a single
+ * command makes several Secrets Manager calls. Caching the value alone would
+ * still let two concurrent calls open two prompts over each other.
+ *
+ * Whatever the source, the token reaches the SDK as a function argument in
+ * this process, never argv, never a child's environment.
+ */
+export declare function accessToken(): Promise<string>;
+/** Resolves a project name to its id. Names are unique within an org. */
+export declare function projectIdFor(name: string): Promise<string>;
+export declare function listSecrets(projectId: string): Promise<BwsSecret[]>;
+export declare function createSecret(projectId: string, key: string, value: string, note: string): Promise<void>;
+/**
+ * Takes the whole secret rather than an id: the SDK's update is a full
+ * replace (organization, key, project list included), and every caller
+ * already holds the listed secret it is updating.
+ */
+export declare function updateSecret(secret: BwsSecret, value: string, note: string): Promise<void>;
+export declare function deleteSecrets(ids: string[]): Promise<void>;
+export declare function byKey(secrets: BwsSecret[]): Map<string, BwsSecret>;