@devdogsuga/devtools 0.1.0 → 0.1.1

package/dist/cli.js

@@ -19,7 +19,8 @@
  */
 import { confirm, intro, log, note, outro, select, spinner, } from "@clack/prompts";
 import { assertMigrated, detectLocalInstance, PERSONAS, } from "./instance.js";
-import { conformance, listApps, quarantineRoundTrip } from "./doctor.js";
+import { conformance, listApps, quarantineRoundTrip } from "./moderation.js";
+import { runEnvironmentDoctor } from "./environment-doctor.js";
 import { currentRootHolder, grantRoot, listCandidates, transferRoot, } from "./grantRoot.js";
 import { connectRemoteProject, runStackCommand, } from "./stack.js";
 import { runConfigPush } from "./db/config-push.js";
@@ -62,14 +63,9 @@ import { runWorkflows } from "./workflows/commands.js";
 import { runCf } from "./cf/commands.js";
 import { captureDevtoolsError, initDevtoolsTelemetry } from "./telemetry.js";
 import { ownVersion } from "./repo/preflight.js";
-const DOCTOR_COMMANDS = [
-    "doctor",
-    "roundtrip",
-    "catalog",
-    "grant-root",
-];
-function isDoctorCommand(value) {
-    return DOCTOR_COMMANDS.includes(value);
+const MODERATION_COMMANDS = ["moderation", "grant-root"];
+function isModerationCommand(value) {
+    return MODERATION_COMMANDS.includes(value);
 }
 function flagValue(rest, flag) {
     const index = rest.indexOf(flag);
@@ -236,11 +232,11 @@ async function runStack(command, rest) {
         process.exitCode = 1;
     }
 }
-async function runCatalog(instance) {
+async function runModerationCatalog(instance) {
     const catalog = await readCatalog(instance);
     note(renderCatalog(catalog), "Moderation catalog");
 }
-async function runDoctor(instance, appSlug) {
+async function runModerationCheck(instance, appSlug) {
     let slug = appSlug;
     if (!slug) {
         const apps = await listApps(instance);
@@ -289,7 +285,7 @@ async function runDoctor(instance, appSlug) {
             "than trusting outright.");
     }
 }
-async function runRoundTrip(instance) {
+async function runModerationRoundTrip(instance) {
     const s = spinner();
     s.start("Filing a report, quarantining it, and looking again");
     try {
@@ -605,7 +601,11 @@ async function runDbCommand(rest) {
     if (sub === "migration") {
         const [msub, ...mrest] = subRest;
         if (msub === "new") {
-            const code = await runNewMigration(mrest.find((arg) => !arg.startsWith("-")));
+            // Skip `--app`'s own value, so `new --app <slug> "<description>"`
+            // doesn't take the slug for the description.
+            const appAt = mrest.indexOf("--app");
+            const positional = mrest.filter((arg, i) => !arg.startsWith("-") && !(appAt >= 0 && i === appAt + 1));
+            const code = await runNewMigration(flagValue(mrest, "--app"), positional[0]);
             process.exitCode = code === 0 ? 0 : 1;
             return;
         }
@@ -921,7 +921,25 @@ async function dispatch(argv) {
         process.exitCode = 1;
         return null;
     }
-    if (!isDoctorCommand(first)) {
+    // The old moderation names, refused with the new namespace rather than
+    // falling into "Unknown command" — same rationale as `secrets` above.
+    // `doctor` itself is NOT here: that name now belongs to the environment
+    // checker below, a deliberate reuse rather than a collision.
+    if (first === "catalog" || first === "roundtrip") {
+        explain(`\`${first}\` is now \`devtools moderation ${first}\`.`, "", [
+            `pnpm devtools moderation ${first}`,
+        ]);
+        process.exitCode = 1;
+        return null;
+    }
+    if (first === "doctor") {
+        await runEnvironmentDoctor({
+            app: flagValue(rest, "--app"),
+            report: rest.includes("--report"),
+        });
+        return DONE;
+    }
+    if (!isModerationCommand(first)) {
         log.error(`Unknown command: ${first}`);
         // The top level only. The command is unknown, so there is no level below
         // it to describe, and reprinting the whole tree here is what made the old
@@ -935,17 +953,26 @@ async function dispatch(argv) {
         process.exitCode = 1;
         return null;
     }
-    if (first === "catalog") {
-        await runCatalog(instance);
-    }
-    else if (first === "doctor") {
-        await runDoctor(instance, flagValue(rest, "--app"));
-    }
-    else if (first === "grant-root") {
-        await runGrantRoot(instance, flagValue(rest, "--user"));
+    if (first === "moderation") {
+        const [msub, ...mrest] = rest;
+        if (msub === "check") {
+            await runModerationCheck(instance, flagValue(mrest, "--app"));
+        }
+        else if (msub === "catalog") {
+            await runModerationCatalog(instance);
+        }
+        else if (msub === "roundtrip") {
+            await runModerationRoundTrip(instance);
+        }
+        else {
+            log.error(msub
+                ? `devtools moderation: unknown subcommand "${msub}". Try ${subcommandList(["moderation"])}.`
+                : `devtools moderation: which of ${subcommandList(["moderation"])}?`);
+            process.exitCode = 1;
+        }
     }
     else {
-        await runRoundTrip(instance);
+        await runGrantRoot(instance, flagValue(rest, "--user"));
     }
     return DONE;
 }

package/dist/commands.js

@@ -337,32 +337,39 @@ const DECLARED_GROUPS = [
         title: "Moderation",
         commands: [
             {
-                name: "catalog",
-                summary: "List the report reasons and content types in the database.",
-                hint: "what can be reported here",
-                needs: "instance-running",
-                options: [JSON_FLAG],
-            },
-            {
-                name: "doctor",
-                summary: "Check an app's moderation integration.",
-                hint: "and whether the catalog holds up",
-                needs: "instance-running",
-                options: [
+                name: "moderation",
+                summary: "An app's moderation integration: the catalog and its wiring.",
+                hint: "check, catalog, roundtrip",
+                subcommands: [
                     {
-                        flag: "--app",
-                        value: "<slug>",
-                        summary: "App to check. Asked for when absent.",
+                        name: "check",
+                        summary: "Check an app's moderation integration.",
+                        hint: "and whether the catalog holds up",
+                        needs: "instance-running",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<slug>",
+                                summary: "App to check. Asked for when absent.",
+                            },
+                            JSON_FLAG,
+                        ],
+                    },
+                    {
+                        name: "catalog",
+                        summary: "List the report reasons and content types in the database.",
+                        hint: "what can be reported here",
+                        needs: "instance-running",
+                        options: [JSON_FLAG],
+                    },
+                    {
+                        name: "roundtrip",
+                        summary: "File a report, quarantine it, and check the freeze.",
+                        hint: "end to end, then cleans up",
+                        needs: "instance-running",
                     },
-                    JSON_FLAG,
                 ],
             },
-            {
-                name: "roundtrip",
-                summary: "File a report, quarantine it, and check the freeze.",
-                hint: "end to end, then cleans up",
-                needs: "instance-running",
-            },
             {
                 name: "grant-root",
                 summary: "Give an account every permission on your own database.",
@@ -377,6 +384,27 @@ const DECLARED_GROUPS = [
             },
         ],
     },
+    {
+        title: "Environment",
+        commands: [
+            {
+                name: "doctor",
+                summary: "Check this machine's environment against what the repo needs.",
+                hint: "node, pnpm, Docker, .env, hosted Supabase, OAuth — read-only",
+                options: [
+                    {
+                        flag: "--app",
+                        value: "<slug>",
+                        summary: "Scope checks to one app. Defaults to every app you have env for.",
+                    },
+                    {
+                        flag: "--report",
+                        summary: "Print a redacted, paste-able block (versions, OS, results — no secrets).",
+                    },
+                ],
+            },
+        ],
+    },
     {
         title: "Generate",
         commands: [
@@ -817,6 +845,14 @@ const DECLARED_GROUPS = [
                             {
                                 name: "new",
                                 summary: "Create an empty timestamped migration file.",
+                                hint: "<timestamp>_<schema>_<description>.sql",
+                                options: [
+                                    {
+                                        flag: "--app",
+                                        value: "<slug>",
+                                        summary: "Whose schema. Asked for when absent.",
+                                    },
+                                ],
                             },
                             {
                                 name: "generate",
@@ -1084,7 +1120,11 @@ export const GROUPS = [
     },
     {
         title: "Moderation",
-        commands: commands("catalog", "doctor", "roundtrip", "grant-root"),
+        commands: commands("moderation", "grant-root"),
+    },
+    {
+        title: "Environment",
+        commands: commands("doctor"),
     },
     {
         title: "GitHub",

package/dist/db/new-migration.d.ts

@@ -1 +1,8 @@
-export declare function runNewMigration(name: string | undefined): Promise<number>;
+/** App slug -> Postgres schema name. Schedule Builder and Study Group
+ * Finder use underscores; their slugs use hyphens. */
+export declare const APP_SCHEMAS: Record<string, string>;
+/** Builds the `supabase migration new` name argument — `<schema>_<desc>` —
+ * given an app slug and a free-text description. Pure, so the naming rule
+ * is testable without spawning the CLI. */
+export declare function migrationName(appSlug: string, description: string): string | null;
+export declare function runNewMigration(appArg: string | undefined, descriptionArg: string | undefined): Promise<number>;

package/dist/db/new-migration.js

@@ -1,7 +1,65 @@
+/**
+ * `db migration new --app <slug> <description>`
+ *
+ * One flat `supabase/migrations/` directory, shared by every app, so the
+ * filename is the only thing that says whose schema a migration belongs to.
+ * Contract: `<timestamp>_<schema>_<description>.sql`, where `schema` is
+ * `platform`, `schedule_builder`, or `study_group_finder` — never the
+ * app slug verbatim (schedule-builder's schema is `schedule_builder`, with
+ * an underscore, because it is a Postgres identifier).
+ *
+ * The supabase CLI already produces `<timestamp>_<name>.sql` from `migration
+ * new <name>` — its own clock, not ours, which is the part CI's
+ * newer-than-main check actually cares about — so this only has to build
+ * `name` as `<schema>_<description>` and hand it off unchanged.
+ */
+import { select, text } from "@clack/prompts";
+import { unwrap } from "../ui.js";
 import { supabase } from "./run.js";
-export async function runNewMigration(name) {
+/** App slug -> Postgres schema name. Schedule Builder and Study Group
+ * Finder use underscores; their slugs use hyphens. */
+export const APP_SCHEMAS = {
+    platform: "platform",
+    "schedule-builder": "schedule_builder",
+    "study-group-finder": "study_group_finder",
+};
+/** Builds the `supabase migration new` name argument — `<schema>_<desc>` —
+ * given an app slug and a free-text description. Pure, so the naming rule
+ * is testable without spawning the CLI. */
+export function migrationName(appSlug, description) {
+    const schema = APP_SCHEMAS[appSlug];
+    if (!schema)
+        return null;
+    const slug = description
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (!slug)
+        return null;
+    return `${schema}_${slug}`;
+}
+async function pickApp() {
+    return unwrap(await select({
+        message: "Whose schema is this migration for?",
+        options: Object.keys(APP_SCHEMAS).map((value) => ({ value, label: value })),
+    }));
+}
+export async function runNewMigration(appArg, descriptionArg) {
+    const app = appArg ?? (await pickApp());
+    if (!APP_SCHEMAS[app]) {
+        process.stderr.write(`devtools db migration new: unknown app "${app}". Expected one of: ${Object.keys(APP_SCHEMAS).join(", ")}.\n`);
+        return 1;
+    }
+    const description = descriptionArg ??
+        unwrap(await text({
+            message: "Short description (used as the migration's filename)",
+            placeholder: "add_widgets_table",
+            validate: (v) => (v?.trim() ? undefined : "Required"),
+        }));
+    const name = migrationName(app, description);
     if (!name) {
-        process.stderr.write("devtools new-migration: a migration name is required.\n");
+        process.stderr.write("devtools db migration new: the description left nothing usable in the filename.\n");
         return 1;
     }
     return supabase("migration", "new", name);

package/dist/db/pooler.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Validates a hosted `DB_URL` against the one shape it must have: the
+ * Session pooler string, not the direct connection and not the Transaction
+ * pooler.
+ *
+ * Pure and synchronous on purpose — `setup.ts`'s hosted wizard calls this
+ * before writing anything to `.env`, and `doctor.ts`'s environment checker
+ * calls the same function against whatever is already there, so the two
+ * never drift into disagreeing about what a good `DB_URL` looks like.
+ *
+ * See the writing guide's collapsed note on poolers (docs/_shared or
+ * toolkit/guides) for the wording this explains to a contributor; this
+ * module only classifies, it does not print.
+ */
+export type DbUrlProblem = "invalid" | "direct-connection" | "transaction-pooler";
+export interface DbUrlValidation {
+    ok: boolean;
+    problem?: DbUrlProblem;
+    /** The FAQ anchor id for this problem, for a caller that wants to link. */
+    faqId?: "db-url-direct-connection" | "db-url-transaction-pooler";
+    message?: string;
+}
+export declare function validateSessionPoolerUrl(dbUrl: string): DbUrlValidation;

package/dist/db/pooler.js

@@ -0,0 +1,55 @@
+/**
+ * Validates a hosted `DB_URL` against the one shape it must have: the
+ * Session pooler string, not the direct connection and not the Transaction
+ * pooler.
+ *
+ * Pure and synchronous on purpose — `setup.ts`'s hosted wizard calls this
+ * before writing anything to `.env`, and `doctor.ts`'s environment checker
+ * calls the same function against whatever is already there, so the two
+ * never drift into disagreeing about what a good `DB_URL` looks like.
+ *
+ * See the writing guide's collapsed note on poolers (docs/_shared or
+ * toolkit/guides) for the wording this explains to a contributor; this
+ * module only classifies, it does not print.
+ */
+/** `db.<ref>.supabase.co` — the direct connection host, IPv6-only on the
+ * free tier. */
+const DIRECT_CONNECTION_HOST = /^db\.[a-z0-9]+\.supabase\.co$/i;
+/** The Transaction pooler's port. Session pooler is 5432, same as plain
+ * Postgres. */
+const TRANSACTION_POOLER_PORT = "6543";
+export function validateSessionPoolerUrl(dbUrl) {
+    let url;
+    try {
+        url = new URL(dbUrl);
+    }
+    catch {
+        return {
+            ok: false,
+            problem: "invalid",
+            message: "That does not look like a connection string (expected postgresql://...).",
+        };
+    }
+    if (DIRECT_CONNECTION_HOST.test(url.hostname)) {
+        return {
+            ok: false,
+            problem: "direct-connection",
+            faqId: "db-url-direct-connection",
+            message: `${url.hostname} is the direct connection host. It only answers on ` +
+                "IPv6, and most campus/home networks are IPv4. Copy the Session " +
+                "pooler string instead — Database settings → Connection string → " +
+                "Session pooler.",
+        };
+    }
+    if (url.port === TRANSACTION_POOLER_PORT) {
+        return {
+            ok: false,
+            problem: "transaction-pooler",
+            faqId: "db-url-transaction-pooler",
+            message: "Port 6543 is the Transaction pooler, meant for serverless — it " +
+                "breaks prepared statements (drizzle-kit hangs). Use the Session " +
+                "pooler on port 5432 instead.",
+        };
+    }
+    return { ok: true };
+}

package/dist/environment-doctor.d.ts

@@ -0,0 +1,36 @@
+import { validateSessionPoolerUrl } from "./db/pooler.js";
+export type CheckStatus = "ok" | "warn" | "skip";
+export interface DoctorCheck {
+    id: string;
+    status: CheckStatus;
+    summary: string;
+    /** How to fix it, when `status !== "ok"`. */
+    fix?: string;
+    faqId?: string;
+}
+/** The floor is 22.12: pnpm 11 needs `node:sqlite`, stable there. `.nvmrc`
+ * pins 24, which is what a `fnm use` picks up; a machine below the floor is
+ * a WARN, not an error — plenty of contributors' shells still resolve an
+ * old global `node` first. */
+export declare function checkNodeVersion(nodeVersion: string, app: string): DoctorCheck;
+export declare function checkFnmHookPresent(shellProfile: string | null, app: string): DoctorCheck;
+export declare function checkPnpmVersion(pnpmVersion: string | null, pinned: string, app: string): DoctorCheck;
+/** `git config core.autocrlf` — `input` or `false` is correct on every
+ * platform this repo documents (WSL2, native Windows, macOS, Linux); `true`
+ * rewrites LF to CRLF on checkout and breaks anything that shells out to a
+ * script with a shebang. */
+export declare function checkAutocrlf(value: string | null): DoctorCheck;
+/** WSL2's own filesystem, never `/mnt/c/...` — a Windows-drive checkout
+ * makes every file operation cross the 9p boundary and Docker bind mounts
+ * silently fail to see edits. */
+export declare function checkRepoUnderMntC(repoRoot: string): DoctorCheck;
+/** Windows only. `RemoteSigned` (or looser) is what lets fnm's PowerShell
+ * hook and pnpm's shims actually run. */
+export declare function checkPowerShellExecutionPolicy(policy: string | null): DoctorCheck;
+export declare function checkEnvKeysPresent(env: Record<string, string | undefined>, keys: string[]): DoctorCheck;
+export { validateSessionPoolerUrl };
+export interface RunDoctorOptions {
+    app?: string;
+    report?: boolean;
+}
+export declare function runEnvironmentDoctor(opts: RunDoctorOptions): Promise<void>;