feat(cli): add crayon local run-dev for testing cloud features locally

Starts the auth-server as a background process alongside the dev UI so
cloud features (cron scheduling, webhook tokens, Schedule/Trigger tabs)
work against localhost. Only available in the monorepo — the command is
conditionally registered based on auth-server directory existence.

Changes:
- New `local run-dev` CLI command (guarded to monorepo only)
- startLocalAuthServer() spawns `next dev` on port 3000, waits for
  health, sets CRAYON_SERVER_URL + CRAYON_TOKEN, registers cleanup
- Widen isCloud detection to include CRAYON_SERVER_URL (not just FLY_APP_NAME)
- TriggerSection fetches appUrl from /api/claude-command instead of
  hardcoding hostname check
- Updated DEVELOPMENT.md with local dev instructions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cevian

DEVELOPMENT.md

@@ -7,12 +7,35 @@ git clone https://github.com/timescale/crayon.git
 cd crayon
 pnpm install
 pnpm build
-npx tsx packages/core/src/cli/index.ts install --force
 ```
 
 > **Note:** This outputs the `claude --plugin-dir <path>` command you need to run Claude Code with the local plugin.
 
-## Testing Local Changes Against Cloud
+## Local Development
+
+`crayon local run-dev` starts the auth-server alongside the dev UI so you can test cloud features (cron scheduling, webhook tokens) locally. This command is only available when running from the monorepo.
+
+### Prerequisites
+
+1. **Auth-server `.env.local`** must exist at `packages/auth-server/.env.local` with the required env vars (see `packages/auth-server/README.md`). It should point to the same `DATABASE_URL` as the deployed auth-server so your CLI token works. Contents can be found in 1password "Crayon auth-server secrets".
+
+2. **CLI login** — run `crayon login` once so `~/.crayon/credentials` has a valid token.
+
+### Usage
+
+```bash
+npx tsx /path/to/crayon/packages/core/src/cli/index.ts local run-dev
+```
+
+This will:
+- Start the auth-server on `http://localhost:3000`
+- Set `CRAYON_SERVER_URL` and `CRAYON_TOKEN` automatically
+- Launch the dev UI with cloud features enabled (webhook section, cron scheduling)
+- Open the browser and start Claude Code
+
+
+
+## Testing Local Changes On Cloud
 
 To test local core changes on a cloud dev machine:
 

packages/core/dev-ui/src/components/TriggerSection.tsx

@@ -1,4 +1,4 @@
-import { useState, useCallback } from "react";
+import { useState, useCallback, useEffect } from "react";
 import type { WorkflowDAG } from "../types";
 
 interface TriggerSectionProps {
@@ -49,8 +49,17 @@ export function TriggerSection({ dag, onSuccess }: TriggerSectionProps) {
   const [webhookExpiry, setWebhookExpiry] = useState("30d");
   const [generatingToken, setGeneratingToken] = useState(false);
 
-  const isCloud = typeof window !== "undefined" && window.location.hostname.endsWith(".fly.dev");
-  const appUrl = isCloud ? `${window.location.origin}/dev` : "";
+  // Fetch cloud info from the backend
+  const [cloudInfo, setCloudInfo] = useState<{ isCloud: boolean; appUrl: string } | null>(null);
+  useEffect(() => {
+    fetch("/dev/api/claude-command")
+      .then((r) => r.json())
+      .then((data) => setCloudInfo({ isCloud: data.isCloud, appUrl: data.appUrl ?? "" }))
+      .catch(() => {});
+  }, []);
+
+  const isCloud = cloudInfo?.isCloud ?? false;
+  const appUrl = cloudInfo?.appUrl ?? "";
 
   const buildInput = useCallback((): Record<string, unknown> => {
     if (useRawJson) {

packages/core/src/cli/index.ts

@@ -2,9 +2,9 @@
 import { Command } from "commander";
 import pc from "picocolors";
 import Table from "cli-table3";
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { dirname, resolve } from "node:path";
+import { dirname, resolve, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { createCrayon } from "../index.js";
@@ -98,6 +98,17 @@ local
     await runRun();
   });
 
+// Only register run-dev in the monorepo (auth-server must exist nearby)
+const authServerDir = resolve(__dirname, "../../../auth-server");
+if (existsSync(join(authServerDir, "package.json"))) {
+  local
+    .command("run-dev")
+    .description("Launch with local auth-server (for testing cloud features)")
+    .action(async () => {
+      await runRun({ withAuthServer: true });
+    });
+}
+
 // ============ Build command ============
 program
   .command("build")

packages/core/src/cli/run.ts

@@ -1,8 +1,9 @@
-import { exec, execSync, spawn } from "node:child_process";
+import { exec, execSync, spawn, type ChildProcess } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { promisify } from "node:util";
-import { join, resolve } from "node:path";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import * as dotenv from "dotenv";
@@ -202,7 +203,81 @@ function discoverProjects(): ProjectInfo[] {
   return projects;
 }
 
-async function launchExistingProject(projectPath: string): Promise<void> {
+/**
+ * Resolve the auth-server directory relative to this file's location in the monorepo.
+ * Returns null if not in the monorepo (e.g., published npm package).
+ */
+function getAuthServerDir(): string | null {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const candidate = resolve(__dirname, "../../../auth-server");
+  return existsSync(join(candidate, "package.json")) ? candidate : null;
+}
+
+/**
+ * Start the auth-server as a local Next.js dev process.
+ * Sets CRAYON_SERVER_URL and CRAYON_TOKEN in process.env.
+ * Registers cleanup handlers to kill the child on exit.
+ */
+async function startLocalAuthServer(): Promise<void> {
+  const authServerDir = getAuthServerDir();
+  if (!authServerDir) {
+    throw new Error("Auth-server not found. This command is only available in the crayon monorepo.");
+  }
+  if (!existsSync(join(authServerDir, ".env.local"))) {
+    throw new Error(`auth-server/.env.local not found. Create it first — see packages/auth-server/README.md`);
+  }
+
+  const { getToken } = await import("../connections/cloud-auth.js");
+  const token = getToken();
+  if (!token) {
+    throw new Error("Not authenticated with crayon cloud. Run `crayon login` first.");
+  }
+
+  p.log.info("Starting local auth-server on port 3000...");
+
+  const child = spawn("npx", ["next", "dev", "--port", "3000"], {
+    cwd: authServerDir,
+    stdio: "pipe",
+    env: { ...process.env },
+  });
+
+  // Log auth-server errors to stderr
+  child.stderr?.on("data", (data: Buffer) => {
+    const msg = data.toString().trim();
+    if (msg) process.stderr.write(`[auth-server] ${msg}\n`);
+  });
+
+  // Cleanup on exit
+  const cleanup = () => { try { child.kill("SIGTERM"); } catch {} };
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => { cleanup(); process.exit(0); });
+  process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+
+  // Wait for health
+  const timeout = 30_000;
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    try {
+      const res = await fetch("http://localhost:3000");
+      if (res.ok || res.status < 500) break;
+    } catch {
+      // not ready yet
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+
+  if (Date.now() - start >= timeout) {
+    cleanup();
+    throw new Error("Auth-server failed to start within 30 seconds");
+  }
+
+  p.log.success("Auth-server ready at http://localhost:3000");
+
+  process.env.CRAYON_SERVER_URL = "http://localhost:3000";
+  process.env.CRAYON_TOKEN = token;
+}
+
+async function launchExistingProject(projectPath: string, opts?: { withAuthServer?: boolean }): Promise<void> {
   // Check if database is paused and start it if needed
   try {
     const { findEnvFile } = await import("./env.js");
@@ -246,10 +321,10 @@ async function launchExistingProject(projectPath: string): Promise<void> {
   }
 
   p.outro(pc.green("Launching..."));
-  await launchDevServer(projectPath, { yolo: mode === "yolo" });
+  await launchDevServer(projectPath, { yolo: mode === "yolo", withAuthServer: opts?.withAuthServer });
 }
 
-async function launchDevServer(cwd: string, { yolo = false }: { yolo?: boolean } = {}): Promise<void> {
+async function launchDevServer(cwd: string, { yolo = false, withAuthServer = false }: { yolo?: boolean; withAuthServer?: boolean } = {}): Promise<void> {
   // Load .env from the app directory (not process.cwd(), which may be a parent)
   try {
     const { findEnvFile, loadEnv } = await import("./env.js");
@@ -259,6 +334,10 @@ async function launchDevServer(cwd: string, { yolo = false }: { yolo?: boolean }
     // Dev UI can work without env
   }
 
+  if (withAuthServer) {
+    await startLocalAuthServer();
+  }
+
   const { startDevServer } = await import("../dev-ui/index.js");
   const { url } = await startDevServer({
     projectRoot: cwd,
@@ -282,7 +361,7 @@ async function launchDevServer(cwd: string, { yolo = false }: { yolo?: boolean }
   claude.on("exit", (code) => process.exit(code ?? 0));
 }
 
-export async function runRun(): Promise<void> {
+export async function runRun(opts?: { withAuthServer?: boolean }): Promise<void> {
   p.intro(pc.red("crayon"));
 
   if (!isClaudeAvailable()) {
@@ -292,7 +371,7 @@ export async function runRun(): Promise<void> {
 
   // ── Existing project (CWD) → launch directly ───────────────────────
   if (isExistingcrayon()) {
-    await launchExistingProject(process.cwd());
+    await launchExistingProject(process.cwd(), opts);
     return;
   }
 
@@ -323,7 +402,7 @@ export async function runRun(): Promise<void> {
     }
 
     if (projectChoice !== CREATE_NEW) {
-      await launchExistingProject(projectChoice);
+      await launchExistingProject(projectChoice, opts);
       return;
     }
   }
@@ -553,7 +632,7 @@ export async function runRun(): Promise<void> {
 
   if (!p.isCancel(launchChoice) && launchChoice !== "no") {
     p.outro(pc.green("Launching..."));
-    await launchDevServer(resolve(appPath), { yolo: launchChoice === "yolo" });
+    await launchDevServer(resolve(appPath), { yolo: launchChoice === "yolo", withAuthServer: opts?.withAuthServer });
     return;
   }
 

packages/core/src/dev-ui/dev-server.ts

@@ -153,10 +153,13 @@ export async function startDevServer(options: DevServerOptions) {
 
       // Claude command hint (no database required)
       if (devPath === "/api/claude-command" && req.method === "GET") {
-        const isCloud = !!process.env.FLY_APP_NAME;
+        const isCloud = !!(process.env.FLY_APP_NAME || process.env.CRAYON_SERVER_URL);
         const appName = process.env.APP_NAME;
+        const appUrl = process.env.FLY_APP_NAME
+          ? `https://${process.env.FLY_APP_NAME}.fly.dev/dev`
+          : `http://localhost:${actualPort}/dev`;
         res.writeHead(200, { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" });
-        res.end(JSON.stringify({ projectRoot, isCloud, appName }));
+        res.end(JSON.stringify({ projectRoot, isCloud, appName, appUrl }));
         return;
       }