create-dstack 0.1.0 → 0.1.2

package/README.md

@@ -6,6 +6,8 @@ Scaffold a production-ready Next.js app with a single command.
 bunx create-dstack my-app
 ```
 
+![Demo](./assets/demo.gif)
+
 ## What's included
 
 

package/dist/index.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env bun
 // @bun
-#!/usr/bin/env node
 var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
@@ -163,15 +162,15 @@ var require_picocolors = __commonJS((exports, module) => {
 
 // src/index.ts
 var {$: $2 } = globalThis.Bun;
-import { existsSync, cpSync, mkdirSync, appendFileSync } from "fs";
+import { existsSync, cpSync } from "fs";
 import { join, resolve, dirname } from "path";
 import { fileURLToPath } from "url";
 
 // node_modules/@clack/core/dist/index.mjs
-import { styleText as y } from "node:util";
-import { stdout as S, stdin as $ } from "node:process";
-import * as _ from "node:readline";
-import P from "node:readline";
+import { styleText as y } from "util";
+import { stdout as S, stdin as $ } from "process";
+import * as _ from "readline";
+import P from "readline";
 
 // node_modules/fast-string-truncated-width/dist/utils.js
 var isAmbiguous = (x) => {
@@ -350,7 +349,7 @@ var dist_default2 = fastStringWidth;
 
 // node_modules/fast-wrap-ansi/lib/main.js
 var ESC = "\x1B";
-var CSI = "›";
+var CSI = "\x9B";
 var END_CODE = 39;
 var ANSI_ESCAPE_BELL = "\x07";
 var ANSI_CSI = "[";
@@ -559,7 +558,7 @@ function wrapAnsi(string, columns, options) {
 
 // node_modules/@clack/core/dist/index.mjs
 var import_sisteransi = __toESM(require_src(), 1);
-import { ReadStream as D } from "node:tty";
+import { ReadStream as D } from "tty";
 function d(r, t, e) {
   if (!e.some((o) => !o.disabled))
     return r;
@@ -620,12 +619,6 @@ function z({ input: r = $, output: t = S, overwrite: e = true, hideCursor: s = t
 }
 var O = (r) => ("columns" in r) && typeof r.columns == "number" ? r.columns : 80;
 var A = (r) => ("rows" in r) && typeof r.rows == "number" ? r.rows : 20;
-function R(r, t, e, s = e) {
-  const i = O(r ?? S);
-  return wrapAnsi(t, i - e.length, { hard: true, trim: false }).split(`
-`).map((n, o) => `${o === 0 ? s : e}${n}`).join(`
-`);
-}
 var p = class {
   input;
   output;
@@ -784,7 +777,7 @@ var H = class extends p {
     if (!this.userInput)
       return y(["inverse", "hidden"], "_");
     if (this._cursor >= this.userInput.length)
-      return `${this.userInput}█`;
+      return `${this.userInput}\u2588`;
     const t = this.userInput.slice(0, this._cursor), [e, ...s] = this.userInput.slice(this._cursor);
     return `${t}${y("inverse", e)}${s.join("")}`;
   }
@@ -832,24 +825,6 @@ var H = class extends p {
     }
   }
 };
-
-class Q extends p {
-  get cursor() {
-    return this.value ? 0 : 1;
-  }
-  get _value() {
-    return this.cursor === 0;
-  }
-  constructor(t) {
-    super(t, false), this.value = !!t.initialValue, this.on("userInput", () => {
-      this.value = this._value;
-    }), this.on("confirm", (e) => {
-      this.output.write(import_sisteransi.cursor.move(0, -1)), this.value = e, this.state = "submit", this.close();
-    }), this.on("cursor", () => {
-      this.value = !this.value;
-    });
-  }
-}
 var X = { Y: { type: "year", len: 4 }, M: { type: "month", len: 2 }, D: { type: "day", len: 2 } };
 function L(r) {
   return [...r].map((t) => X[t]);
@@ -954,7 +929,7 @@ class et extends p {
       }
   }
   #f(t, e) {
-    if (e?.name === "backspace" || e?.sequence === "" || e?.sequence === "\b" || t === "" || t === "\b") {
+    if (e?.name === "backspace" || e?.sequence === "\x7F" || e?.sequence === "\b" || t === "\x7F" || t === "\b") {
       this.inlineError = "";
       const s = this.#u();
       if (!s)
@@ -1086,7 +1061,7 @@ class at extends p {
       return this.userInput;
     const t = this.userInput;
     if (this.cursor >= t.length)
-      return `${this.userInput}█`;
+      return `${this.userInput}\u2588`;
     const e = t.slice(0, this.cursor), [s, ...i] = t.slice(this.cursor);
     return `${e}${y("inverse", s)}${i.join("")}`;
   }
@@ -1103,8 +1078,8 @@ class at extends p {
 }
 
 // node_modules/@clack/prompts/dist/index.mjs
-import { styleText as t, stripVTControlCharacters as ne } from "node:util";
-import P2 from "node:process";
+import { styleText as t, stripVTControlCharacters as ne } from "util";
+import P2 from "process";
 var import_sisteransi2 = __toESM(require_src(), 1);
 function Ze() {
   return P2.platform !== "win32" ? P2.env.TERM !== "linux" : !!P2.env.CI || !!P2.env.WT_SESSION || !!P2.env.TERMINUS_SUBLIME || P2.env.ConEmuTask === "{cmd::Cmder}" || P2.env.TERM_PROGRAM === "Terminus-Sublime" || P2.env.TERM_PROGRAM === "vscode" || P2.env.TERM === "xterm-256color" || P2.env.TERM === "alacritty" || P2.env.TERMINAL_EMULATOR === "JetBrains-JediTerm";
@@ -1112,31 +1087,31 @@ function Ze() {
 var ee = Ze();
 var ae = () => process.env.CI === "true";
 var w2 = (e, i) => ee ? e : i;
-var _e = w2("◆", "*");
-var oe = w2("■", "x");
-var ue = w2("▲", "x");
-var F2 = w2("◇", "o");
-var le = w2("┌", "T");
-var d2 = w2("│", "|");
-var E2 = w2("└", "—");
-var Ie = w2("┐", "T");
-var Ee = w2("┘", "—");
-var z2 = w2("●", ">");
-var H2 = w2("○", " ");
-var te = w2("◻", "[•]");
-var U = w2("◼", "[+]");
-var J2 = w2("◻", "[ ]");
-var xe = w2("▪", "•");
-var se = w2("─", "-");
-var ce = w2("╮", "+");
-var Ge = w2("├", "+");
-var $e = w2("╯", "+");
-var de = w2("╰", "+");
-var Oe = w2("╭", "+");
-var he = w2("●", "•");
-var pe = w2("◆", "*");
-var me = w2("▲", "!");
-var ge = w2("■", "x");
+var _e = w2("\u25C6", "*");
+var oe = w2("\u25A0", "x");
+var ue = w2("\u25B2", "x");
+var F2 = w2("\u25C7", "o");
+var le = w2("\u250C", "T");
+var d2 = w2("\u2502", "|");
+var E2 = w2("\u2514", "\u2014");
+var Ie = w2("\u2510", "T");
+var Ee = w2("\u2518", "\u2014");
+var z2 = w2("\u25CF", ">");
+var H2 = w2("\u25CB", " ");
+var te = w2("\u25FB", "[\u2022]");
+var U = w2("\u25FC", "[+]");
+var J2 = w2("\u25FB", "[ ]");
+var xe = w2("\u25AA", "\u2022");
+var se = w2("\u2500", "-");
+var ce = w2("\u256E", "+");
+var Ge = w2("\u251C", "+");
+var $e = w2("\u256F", "+");
+var de = w2("\u2570", "+");
+var Oe = w2("\u256D", "+");
+var he = w2("\u25CF", "\u2022");
+var pe = w2("\u25C6", "*");
+var me = w2("\u25B2", "!");
+var ge = w2("\u25A0", "x");
 var V2 = (e) => {
   switch (e) {
     case "initial":
@@ -1150,61 +1125,6 @@ var V2 = (e) => {
       return t("green", F2);
   }
 };
-var ot2 = (e) => {
-  const i = e.active ?? "Yes", s = e.inactive ?? "No";
-  return new Q({ active: i, inactive: s, signal: e.signal, input: e.input, output: e.output, initialValue: e.initialValue ?? true, render() {
-    const r = e.withGuide ?? u.withGuide, u2 = `${V2(this.state)}  `, n = r ? `${t("gray", d2)}  ` : "", o = R(e.output, e.message, n, u2), c2 = `${r ? `${t("gray", d2)}
-` : ""}${o}
-`, a = this.value ? i : s;
-    switch (this.state) {
-      case "submit": {
-        const l = r ? `${t("gray", d2)}  ` : "";
-        return `${c2}${l}${t("dim", a)}`;
-      }
-      case "cancel": {
-        const l = r ? `${t("gray", d2)}  ` : "";
-        return `${c2}${l}${t(["strikethrough", "dim"], a)}${r ? `
-${t("gray", d2)}` : ""}`;
-      }
-      default: {
-        const l = r ? `${t("cyan", d2)}  ` : "", $2 = r ? t("cyan", E2) : "";
-        return `${c2}${l}${this.value ? `${t("green", z2)} ${i}` : `${t("dim", H2)} ${t("dim", i)}`}${e.vertical ? r ? `
-${t("cyan", d2)}  ` : `
-` : ` ${t("dim", "/")} `}${this.value ? `${t("dim", H2)} ${t("dim", s)}` : `${t("green", z2)} ${s}`}
-${$2}
-`;
-      }
-    }
-  } }).prompt();
-};
-var O2 = { message: (e = [], { symbol: i = t("gray", d2), secondarySymbol: s = t("gray", d2), output: r = process.stdout, spacing: u2 = 1, withGuide: n } = {}) => {
-  const o = [], c2 = n ?? u.withGuide, a = c2 ? s : "", l = c2 ? `${i}  ` : "", $2 = c2 ? `${s}  ` : "";
-  for (let p2 = 0;p2 < u2; p2++)
-    o.push(a);
-  const y2 = Array.isArray(e) ? e : e.split(`
-`);
-  if (y2.length > 0) {
-    const [p2, ...m] = y2;
-    p2.length > 0 ? o.push(`${l}${p2}`) : o.push(c2 ? i : "");
-    for (const g of m)
-      g.length > 0 ? o.push(`${$2}${g}`) : o.push(c2 ? s : "");
-  }
-  r.write(`${o.join(`
-`)}
-`);
-}, info: (e, i) => {
-  O2.message(e, { ...i, symbol: t("blue", he) });
-}, success: (e, i) => {
-  O2.message(e, { ...i, symbol: t("green", pe) });
-}, step: (e, i) => {
-  O2.message(e, { ...i, symbol: t("green", F2) });
-}, warn: (e, i) => {
-  O2.message(e, { ...i, symbol: t("yellow", me) });
-}, warning: (e, i) => {
-  O2.warn(e, i);
-}, error: (e, i) => {
-  O2.message(e, { ...i, symbol: t("red", ge) });
-} };
 var pt = (e = "", i) => {
   const s = i?.output ?? process.stdout, r = i?.withGuide ?? u.withGuide ? `${t("gray", E2)}  ` : "";
   s.write(`${r}${t("red", e)}
@@ -1224,7 +1144,7 @@ ${t("gray", E2)}  ` : "";
 `);
 };
 var Ct = (e) => t("magenta", e);
-var fe = ({ indicator: e = "dots", onCancel: i, output: s = process.stdout, cancelMessage: r, errorMessage: u2, frames: n = ee ? ["◒", "◐", "◓", "◑"] : ["•", "o", "O", "0"], delay: o = ee ? 80 : 120, signal: c2, ...a } = {}) => {
+var fe = ({ indicator: e = "dots", onCancel: i, output: s = process.stdout, cancelMessage: r, errorMessage: u2, frames: n = ee ? ["\u25D2", "\u25D0", "\u25D3", "\u25D1"] : ["\u2022", "o", "O", "0"], delay: o = ee ? 80 : 120, signal: c2, ...a } = {}) => {
   const l = ae();
   let $2, y2, p2 = false, m = false, g = "", S2, h = performance.now();
   const f = O(s), v = a?.styleFrame ?? Ct, T2 = (_2) => {
@@ -1281,7 +1201,7 @@ var fe = ({ indicator: e = "dots", onCancel: i, output: s = process.stdout, canc
     return m;
   } };
 };
-var Ve = { light: w2("─", "-"), heavy: w2("━", "="), block: w2("█", "#") };
+var Ve = { light: w2("\u2500", "-"), heavy: w2("\u2501", "="), block: w2("\u2588", "#") };
 var je = `${t("gray", d2)}  `;
 var Ot = (e) => new at({ validate: e.validate, placeholder: e.placeholder, defaultValue: e.defaultValue, initialValue: e.initialValue, output: e.output, signal: e.signal, input: e.input, render() {
   const i = e?.withGuide ?? u.withGuide, s = `${`${i ? `${t("gray", d2)}
@@ -1338,11 +1258,6 @@ async function main() {
     }
     projectName = input;
   }
-  const useStackAuth = await ot2({ message: "Add Stack Auth?" });
-  if (q(useStackAuth)) {
-    pt("Cancelled.");
-    process.exit(0);
-  }
   const projectDir = resolve(process.cwd(), projectName);
   if (existsSync(projectDir)) {
     pt(`Directory "${projectName}" already exists.`);
@@ -1350,7 +1265,7 @@ async function main() {
   }
   const s = fe();
   s.start("preheating the oven...");
-  await $2`bunx create-next-app@latest ${projectName} --typescript --tailwind --no-eslint --app --src-dir --import-alias "@/*" --use-bun`.quiet();
+  await $2`bunx create-next-app@latest ${projectName} --typescript --tailwind --no-eslint --app --no-src-dir --import-alias "@/*" --use-bun`.quiet();
   s.stop("next.js is in the chat");
   s.start("calling convex off the bench...");
   await $2`bun add convex`.cwd(projectDir).quiet();
@@ -1361,29 +1276,8 @@ async function main() {
   s.start("adding the drip (shadcn)...");
   await $2`bunx shadcn@latest init -d`.cwd(projectDir).quiet();
   s.stop("looking fire already");
-  if (useStackAuth) {
-    s.start("sliding stack auth into the dm...");
-    await $2`bun add @stackframe/stack`.cwd(projectDir).quiet();
-    s.stop("auth is cooked and ready");
-    mkdirSync(join(projectDir, "convex"), { recursive: true });
-    copyTemplate(join(TEMPLATES_DIR, "convex", "auth.config.ts"), join(projectDir, "convex", "auth.config.ts"));
-    appendFileSync(join(projectDir, ".env.local"), [
-      "",
-      "# Stack Auth \u2014 fill in from https://app.stack-auth.com",
-      "NEXT_PUBLIC_STACK_PROJECT_ID=",
-      "NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=",
-      "STACK_SECRET_SERVER_KEY=",
-      ""
-    ].join(`
-`));
-    O2.warn(`Stack Auth needs manual steps:
-` + `  1. Create a project at ${import_picocolors.default.cyan("https://app.stack-auth.com")}
-` + `  2. Fill in ${import_picocolors.default.dim(".env.local")} with your keys
-` + `  3. Set the same vars in your Convex dashboard
-` + `  4. Run ${import_picocolors.default.cyan("bunx @stackframe/stack-cli@latest init")} inside the project to finish wiring up the provider`);
-  }
   s.start("putting the secret sauce on it...");
-  copyTemplate(join(TEMPLATES_DIR, "globals.css"), join(projectDir, "src", "app", "globals.css"));
+  copyTemplate(join(TEMPLATES_DIR, "globals.css"), join(projectDir, "app", "globals.css"));
   copyTemplate(join(TEMPLATES_DIR, "oxlint.json"), join(projectDir, "oxlint.json"));
   copyTemplate(join(TEMPLATES_DIR, "oxfmt.json"), join(projectDir, "oxfmt.json"));
   if (existsSync(join(TEMPLATES_DIR, ".claude"))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dstack",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Create a new dstack project — Next.js, Bun, Convex, Shadcn, Oxlint, Oxfmt",
   "type": "module",
   "repository": {
@@ -11,7 +11,7 @@
     "create-dstack": "./dist/index.js"
   },
   "scripts": {
-    "build": "bun build ./src/index.ts --outfile ./dist/index.js --target node --banner '#!/usr/bin/env node'",
+    "build": "bun build ./src/index.ts --outfile ./dist/index.js --target bun",
     "start": "bun run ./src/index.ts",
     "prepublishOnly": "bun run build"
   },

package/templates/CLAUDE.md

@@ -19,7 +19,6 @@ bunx oxfmt --check . # Check formatting
 - React 19
 - TypeScript 5 with strict mode
 - Convex for DB
-- StackAuth for auth, teams, user metadata
 - All database types in Convex
 
 ## Conventions
@@ -49,7 +48,6 @@ API routes: mirror domains (app/api/mail/, app/api/profile/)
 
 ## Authentication & Security
 
-- User endpoints: StackAuth server session for API routes and Server Actions; `useUser` only in client components
 - System/cron: Bearer token
 - Error handling: `throwOnError` or `if (error)` patterns
 

package/templates/agents.md

@@ -19,7 +19,6 @@ bunx oxfmt --check . # Check formatting
 - React 19
 - TypeScript 5 with strict mode
 - Convex for DB
-- StackAuth for auth, teams, user metadata
 - All database types in Convex
 
 ## Conventions
@@ -49,7 +48,6 @@ API routes: mirror domains (app/api/mail/, app/api/profile/)
 
 ## Authentication & Security
 
-- User endpoints: StackAuth server session for API routes and Server Actions; `useUser` only in client components
 - System/cron: Bearer token
 - Error handling: `throwOnError` or `if (error)` patterns
 

package/templates/.cursor/skills/api/SKILL.md

@@ -1,198 +0,0 @@
----
-name: api
-description: Whenever designing or working on API routes
----
-
-# API Development Rules
-
-Every API route is either user-authenticated or system-authenticated. No exceptions.
-
-## 1. Route Handlers
-
-- Use standard Next.js `NextRequest` and `NextResponse` types only
-- No custom middleware that wraps handlers
-
-## 2. Authentication
-
-### User APIs (browser/app requests)
-
-Resolve the signed-in user with **StackAuth on the server**. In Route Handlers and Server Actions, use Stack's server-side session APIs—**not** the React `useUser` hook (that is client-only).
-
-After auth, read and write data through **Convex** (`fetchQuery`, `fetchMutation`, `fetchAction` from `convex/nextjs`) so authorization can rely on `ctx.auth` inside Convex functions. Pass the Convex auth token when your setup requires it (same pattern as other OIDC providers: token option on `fetch*`).
-
-```typescript
-import { fetchMutation } from "convex/nextjs";
-import { api } from "@/convex/_generated/api";
-import type { NextRequest } from "next/server";
-
-export async function PATCH(request: NextRequest) {
-  // 1. Resolve user with StackAuth server APIs; return 401 if missing
-  // 2. Build Convex token if your Stack+Convex integration uses JWT forwarding
-  const token = await getConvexAuthTokenFromRequest(request);
-  const args = await request.json();
-  await fetchMutation(api.example.updateThing, args, { token });
-}
-```
-
-### Cron/System APIs
-
-Use Bearer token + trusted Convex entry points:
-
-```typescript
-const authHeader = request.headers.get("authorization");
-if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
-  return new Response("Unauthorized", { status: 401 });
-}
-
-await fetchMutation(api.jobs.runScheduled, payload);
-```
-
-Use **deployment-appropriate** Convex access for system jobs (e.g. internal mutations or HTTP actions that validate the same secret). Never reuse a "god mode" client for user-initiated work.
-
-### Access shape
-
-| Caller            | Auth              | Data layer                          |
-| ----------------- | ----------------- | ----------------------------------- |
-| User API route    | StackAuth session | Convex via `fetch*` + user token    |
-| System / cron API | Bearer secret     | Convex mutation/action for batch/system work |
-
-Never bypass user-level Convex auth for operations that should be scoped to a single user.
-
-## 3. Validation
-
-**Every API route MUST validate with Zod.** No exceptions.
-
-### Validation Order: Fail Fast
-
-1. Authenticate
-2. Parse and validate request body immediately
-3. Then do expensive operations (Convex calls, external APIs)
-
-### Schema Patterns
-
-- Use `.trim()` for strings, `.email()` for emails
-- Use `.refine()` for custom business logic
-- Use `z.discriminatedUnion()` for conditional validation
-
-## 4. Error Response Format
-
-All errors use Stripe-style format:
-
-```typescript
-{
-  error: {
-    type: string;      // Required: validation_error, authentication_error, api_error, etc.
-    message: string;   // Required: Human-readable
-    code?: string;     // Optional: MISSING_EMAIL, QUOTA_EXCEEDED, etc.
-    param?: string;    // Optional: Field name for validation errors
-    details?: unknown; // Optional: Zod errors array
-  }
-}
-```
-
-### Error Types by Status
-
-- `400` validation_error - Invalid input
-- `401` authentication_error - Not authenticated
-- `403` authorization_error - Not authorized
-- `404` not_found_error - Resource missing
-- `429` rate_limit_error - Quota exceeded
-- `500` api_error - Internal error
-- `503` service_unavailable_error - External service down
-
-### Forbidden Formats
-
-```typescript
-// NEVER use these:
-{ success: false, error: "message" }
-{ error: "string" }  // Must be object
-{ message: "..." }   // Must use error.message
-```
-
-## 5. Standard API Template
-
-```typescript
-import { NextRequest, NextResponse } from "next/server";
-import { z } from "zod";
-import { fetchMutation } from "convex/nextjs";
-import { api } from "@/convex/_generated/api";
-
-const schema = z.object({
-  email: z.string().email(),
-  name: z.string().min(1),
-});
-
-export async function POST(request: NextRequest) {
-  const user = await getStackAuthUserFromRequest(request);
-  if (!user) {
-    return NextResponse.json(
-      {
-        error: { type: "authentication_error", message: "Unauthorized" },
-      },
-      { status: 401 },
-    );
-  }
-
-  try {
-    const rawBody = await request.json();
-    const data = schema.parse(rawBody);
-
-    const token = await getConvexAuthTokenFromRequest(request, user);
-    const result = await fetchMutation(api.example.createProfile, data, { token });
-
-    return NextResponse.json({ success: true, data: result });
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      return NextResponse.json(
-        {
-          error: {
-            type: "validation_error",
-            message: "Validation failed",
-            details: error.issues,
-          },
-        },
-        { status: 400 },
-      );
-    }
-    console.error("API Error:", error);
-    return NextResponse.json(
-      {
-        error: { type: "api_error", message: "Internal server error" },
-      },
-      { status: 500 },
-    );
-  }
-}
-```
-
-Replace `getStackAuthUserFromRequest` / `getConvexAuthTokenFromRequest` with the project's StackAuth server helpers and Convex token bridge.
-
-## 6. Security
-
-- Always sanitize inputs: `.trim()`, `.toLowerCase()` for emails
-- Check user quotas before expensive operations via `user.clientReadOnlyMetadata`
-- Use Supabase query builders, never raw SQL with user input
-- Validate environment variables exist before using
-- There is no SQL layer; do not concatenate user input into query strings for external services
-
-## 7. Database Best Practices (Convex)
-
-- Define schema and indexes in `convex/schema.ts`; query with indexed fields
-- Limit list reads (e.g. `.take(n)` / bounded queries); avoid unbounded scans
-- Use Convex argument validators on every function; keep Zod at the HTTP boundary
-- Use `Promise.allSettled()` for concurrent operations that can fail independently
-- Use `pLimit` for controlled concurrency against external APIs
-
-## 8. Logging
-
-- Use `console.error()` for errors with context (userId, error message, stack)
-- Use `console.log()` sparingly for important business events
-- Never log sensitive data (passwords, tokens, PII)
-- Logs are auto-captured by Vercel
-
-## 9. Testing
-
-- Test files in `__tests__/` within API route folders
-- Mock StackAuth server user resolution and Convex `fetch*` helpers when testing handlers in isolation
-- Mock `request.json()` for body parsing
-- Use `{} as NextRequest` if handler doesn't use request object

package/templates/.cursor/skills/api-timing-logs/SKILL.md

@@ -1,77 +0,0 @@
----
-name: api-timing-logs
-description: Adds readable one-line phase timing logs for API routes and server handlers (local debugging and production correlation). Use when instrumenting slow routes, debugging latency, adding request tracing, or when the user asks for timing logs, speed stats, or structured server logging.
----
-
-# API phase timing logs (gold standard)
-
-## Goals
-
-- **Scannable in a terminal**: one line per phase, aligned columns, no nested objects on the happy path.
-- **Grep-friendly**: fixed bracket tag per feature (e.g. `[ck-gen]`, `[mail-send]`).
-- **Minimal PII**: log `user=…` **once** at start; repeat **only** on error lines that need correlation.
-
-## Log line shape
-
-```
-[TAG] begin  user=<full-user-id>
-[TAG] <step>              <ms>ms  <optional key=value ...>
-```
-
-- **`TAG`**: short, stable, unique within the codebase (2–8 chars after the bracket is enough if unambiguous).
-- **`step`**: lowercase, use **dots** for sub-phases (`db.company_row`, `storage.sign`, `llm`). Pad `step` to a fixed width (e.g. 18 chars) so `ms` columns line up.
-- **`ms`**: wall time for **that phase only** (`Date.now() - phaseStart`), not cumulative unless the step name says `total`.
-- **Detail tail**: space-separated `key=value`. Prefer counts and compact units over raw dumps.
-
-## Helpers (TypeScript pattern)
-
-Copy/adapt per route; keep helpers **file-local** unless three+ routes need the same tag.
-
-```ts
-const TAG = "[feature-tag]";
-
-function elapsedMs(start: number) {
-  return Date.now() - start;
-}
-
-function phaseLog(step: string, ms: number, detail?: string) {
-  const tail = detail ? `  ${detail}` : "";
-  console.info(`${TAG} ${step.padEnd(18)} ${String(ms).padStart(5)}ms${tail}`);
-}
-
-function phaseWarn(bucket: string, detail: string) {
-  console.warn(`${TAG} ${bucket}  ${detail}`);
-}
-
-function phaseErr(step: string, userId: string, detail: string) {
-  console.error(`${TAG} ${step}  user=${userId}  ${detail}`);
-}
-```
-
-After auth (or once `userId` is known): `console.info(\`${TAG} begin  user=${userId}\`);`then use`phaseLog`for every subsequent phase **without** repeating`userId`.
-
-## What to log per phase
-
-- **External I/O**: hub pull, DB reads/writes, storage sign/download, HTTP fetches, LLM calls—each gets its own line with duration.
-- **CPU-ish work** only if it can be large (parse/format of huge payloads); otherwise merge with the phase that produced the bytes.
-- **Final line**: `done` or `total` with end-to-end `ms` plus 1–3 summary stats (`docs=`, `llmIn=34500ch`, etc.).
-
-## Units and compaction
-
-- Prefer **`kch`** (thousands of **characters**) when approximating payload size from string length. Do **not** label char counts as `kB` (misleading).
-- Rough token hints are OK: `~8676tok` with a comment in code that it is approximate (e.g. chars/4).
-- For multiple similar items, one compact tail beats an array of objects:  
-  `ok=3/3 raw~1200kch  [a.json:400kch@800ms, b.pdf:…]`
-- Cap list length in logs (e.g. first 3 files + `+2 more`) if noise gets large.
-
-## Errors
-
-- Use **`phaseErr`** for failures where you need to find the user in logs: include `user=<id>` and a **short** reason (message string, not full stack objects).
-- Keep generic `console.error` for unexpected exceptions if you already logged `begin` with `user=`.
-
-## Anti-patterns
-
-- Repeating `userId` on every `info` line.
-- Dumping **full prompts**, document bodies, or tokens in logs.
-- Large **JSON blobs** for routine success paths—use one line + counts.
-- Inconsistent tags (e.g. mixing `console.info("feature: …")` and `[tag] …` styles) in the same route.