@devdogsuga/devtools 0.1.0

package/dist/ui.d.ts

@@ -0,0 +1,25 @@
+export declare function bail(message?: string): never;
+/** Exits cleanly on Ctrl-C rather than letting a cancel symbol leak onward. */
+export declare function unwrap<T>(value: T | symbol): T;
+/**
+ * Reports a failure with the next thing to try.
+ *
+ * `hints` is not decoration: for most of these failures the fix is one command,
+ * and printing it is the difference between a contributor continuing and a
+ * contributor asking in Discord.
+ */
+export declare function explain(summary: string, detail: string, hints?: string[]): void;
+export declare function errorMessage(err: unknown): string;
+export interface CheckResult {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+/**
+ * A pass/fail list.
+ *
+ * Deliberately plain text rather than a box-drawing table: these lines get
+ * pasted into Discord and GitHub issues, where anything fancier turns to
+ * rubble.
+ */
+export declare function renderChecks(checks: CheckResult[]): string;

package/dist/ui.js

@@ -0,0 +1,51 @@
+/**
+ * Shared prompt plumbing.
+ *
+ * The audience here is a contributor who may not be comfortable in a terminal
+ * at all, so two rules apply throughout:
+ *
+ *   * Nothing requires knowing a command. Running `pnpm devtools` with no
+ *     arguments opens a menu, and every prompt has a sensible default.
+ *   * A failure says what to do next. `explain()` exists so no error path
+ *     ends at a stack trace.
+ */
+import { cancel, isCancel, log, note } from "@clack/prompts";
+export function bail(message = "Cancelled.") {
+    cancel(message);
+    process.exit(1);
+}
+/** Exits cleanly on Ctrl-C rather than letting a cancel symbol leak onward. */
+export function unwrap(value) {
+    if (isCancel(value))
+        bail();
+    return value;
+}
+/**
+ * Reports a failure with the next thing to try.
+ *
+ * `hints` is not decoration: for most of these failures the fix is one command,
+ * and printing it is the difference between a contributor continuing and a
+ * contributor asking in Discord.
+ */
+export function explain(summary, detail, hints = []) {
+    log.error(summary);
+    if (detail)
+        log.message(detail);
+    if (hints.length > 0)
+        note(hints.join("\n"), "Try this");
+}
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * A pass/fail list.
+ *
+ * Deliberately plain text rather than a box-drawing table: these lines get
+ * pasted into Discord and GitHub issues, where anything fancier turns to
+ * rubble.
+ */
+export function renderChecks(checks) {
+    return checks
+        .map((c) => `${c.ok ? "PASS" : "FAIL"}  ${c.name}\n      ${c.detail}`)
+        .join("\n");
+}

package/dist/workers.d.ts

@@ -0,0 +1,5 @@
+/** Workspace-relative paths, exactly as listed in root `workers.json`. */
+export declare function workerPaths(): readonly string[];
+/** Basenames, e.g. `"schedule-builder"` — the `pnpm --filter` / CLI slug. */
+export declare function workerApps(): readonly string[];
+export declare function isWorkerApp(value: string): boolean;

package/dist/workers.js

@@ -0,0 +1,35 @@
+/**
+ * The one list of Worker apps, read from root `workers.json`.
+ *
+ * Six call sites across `devtools` and `env` used to carry their own copy of
+ * `["platform", "sandbox", "schedule-builder"]` — a CLI's app-choice list, a
+ * deploy guard, an env-registry consumer, a cron drift test, and more — with
+ * nothing to say when one of them drifted from the rest. `workers.test.ts`
+ * covers the drift; this module is the one place to fix it.
+ */
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { findRepoRoot } from "./repo/root.js";
+// Both lists used to be top-level `const`s, evaluated the instant this
+// module was imported — which meant `findRepoRoot()` ran (and threw
+// `RepoNotFoundError`) at IMPORT time for anything that pulled this module
+// in transitively, `devtools --help` and `devtools setup` included, even
+// outside any repo. Lazy + memoized getters fix that: nothing here touches
+// the filesystem until a caller actually asks for the list, by which point
+// it is a real repo-dependent command that is supposed to refuse outside a
+// repo anyway.
+let cachedWorkerPaths;
+/** Workspace-relative paths, exactly as listed in root `workers.json`. */
+export function workerPaths() {
+    if (cachedWorkerPaths === undefined) {
+        cachedWorkerPaths = JSON.parse(readFileSync(join(findRepoRoot(), "workers.json"), "utf8"));
+    }
+    return cachedWorkerPaths;
+}
+/** Basenames, e.g. `"schedule-builder"` — the `pnpm --filter` / CLI slug. */
+export function workerApps() {
+    return workerPaths().map((path) => basename(path));
+}
+export function isWorkerApp(value) {
+    return workerApps().includes(value);
+}

package/dist/workflows/commands.d.ts

@@ -0,0 +1,44 @@
+import { type AppWranglerConfig, type CronTier } from "../cron/discovery.js";
+export interface WorkflowChoice {
+    app: string;
+    tier: CronTier;
+    binding: string;
+    name: string;
+    className?: string;
+}
+interface WorkflowOptions {
+    app?: string;
+    tier?: string;
+    workflow?: string;
+    params?: string;
+    port?: string;
+    yes: boolean;
+    json: boolean;
+    instanceId?: string;
+}
+export { renderWranglerEnvFile } from "../cf/local-env.js";
+export declare function workflowChoices(configs: readonly AppWranglerConfig[], tiers?: readonly CronTier[]): WorkflowChoice[];
+export declare function workflowTriggerArgs(choice: WorkflowChoice, options: Pick<WorkflowOptions, "params" | "port" | "instanceId">): string[];
+/** Wait until a locally-triggered instance finishes before its server is stopped. */
+export declare function waitForLocalWorkflow(workflowName: string, instanceId: string, port: string, options?: {
+    timeoutMs?: number;
+    pollMs?: number;
+    fetcher?: typeof fetch;
+}): Promise<number>;
+export declare function wranglerDevArgs(app: string, port: string): string[];
+/** Probe Wrangler's Workflow explorer API, rather than merely checking a port. */
+export declare function isWranglerDevRunning(port: string, timeoutMs?: number, fetcher?: typeof fetch): Promise<boolean>;
+/** Whether nothing is bound to `port` on loopback — a real bind test, not a
+ * connect probe, so it answers the only question that matters here: can Wrangler
+ * take this port? */
+export declare function isPortFree(port: number): Promise<boolean>;
+/** The first free port at or after `from`, or null if a bounded scan finds
+ * none. Bounded so an exhausted range fails loudly instead of looping. */
+export declare function findFreePort(from: number, attempts?: number): Promise<number | null>;
+export declare function isWranglerDevConnectionFailure(stderr: string): boolean;
+export declare function wranglerDevConnectionHint(app: string, port: string): string;
+export declare function wranglerDevNotRunningHint(app: string, port: string): string;
+export declare function runWorkflowsList(argv: readonly string[]): Promise<number>;
+export declare function runWorkflowsRun(argv: readonly string[]): Promise<number>;
+export declare function runWorkflowsServe(argv: readonly string[]): Promise<number>;
+export declare function runWorkflows(argv: readonly string[]): Promise<number>;