create-dstack 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "create-dstack",
+  "version": "0.1.0",
+  "description": "Create a new dstack project — Next.js, Bun, Convex, Shadcn, Oxlint, Oxfmt",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devanshg03/dstack.git"
+  },
+  "bin": {
+    "create-dstack": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outfile ./dist/index.js --target node --banner '#!/usr/bin/env node'",
+    "start": "bun run ./src/index.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "keywords": ["create-next-app", "nextjs", "convex", "shadcn", "oxlint", "bun"],
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11"
+  }
+}

package/templates/.claude/settings.json

@@ -0,0 +1,32 @@
+{
+    "permissions": {
+      "allow": [
+        "WebFetch(domain:ai-sdk.dev)",
+        "Bash(curl*localhost*)",
+        "Bash(curl -s -X POST http://localhost:3000/api/test)"
+      ],
+      "deny": ["Bash(rm -rf *)", "Bash(curl *)", "Read(./.env)", "Read(./.env.*)"]
+    },
+    "sandbox": {
+      "enabled": true,
+      "autoAllowBashIfSandboxed": true
+    },
+    "attribution": {
+      "commit": "",
+      "pr": ""
+    },
+    "hooks": {
+      "Stop": [
+        {
+          "hooks": [
+            {
+              "type": "command",
+              "command": "cd <project-dir> && ./node_modules/.bin/oxfmt . 2>/dev/null || true",
+              "statusMessage": "Formatting..."
+            }
+          ]
+        }
+      ]
+    }
+  }
+  

package/templates/.cursor/hooks.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "hooks": {
+    "stop": [
+      {
+        "command": "cd <project-dir> && ./node_modules/.bin/oxfmt . 2>/dev/null || true"
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,198 @@
+---
+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

@@ -0,0 +1,77 @@
+---
+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.

package/templates/.cursor/skills/brand-styling/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: brand-styling
+description: dstack brand identity, colors, typography, and visual styling guidelines. Use when creating UI components, pages, or any visual elements.
+disable-model-invocation: true
+---
+
+# dstack branding
+
+## Overview
+
+To access dstack's official brand identity and style resources, use this skill.
+
+Keywords: branding, corporate identity, visual identity, styling, brand colors, typography, dstack brand, visual formatting, visual design, dstack
+
+## Brand Guidelines
+
+### Colors
+
+Main Colors:
+
+Teal:
+#0da5a1 - Primary brand color, calls to action, active states
+
+Background:
+#f7f7f4 - Page background (warm off-white, not pure white)
+
+Foreground:
+#26251e - Primary text and dark elements
+
+Card:
+#f2f1ed - Card surfaces and elevated containers
+
+Muted:
+#6e6c5e - Secondary text and subdued labels
+
+Border:
+#d5d4cd - Borders, dividers, and separators
+
+Accent Colors:
+
+Teal Gradient Start:
+#0da5a1 - Brand gradient start (287deg angle)
+
+Teal Gradient End:
+#00d4cf - Brand gradient end (lighter teal)
+
+Semantic Colors:
+
+Success:
+#25935f - Success states and positive indicators
+
+Warning:
+#ec9c13 - Warning states and caution indicators
+
+Error:
+#dc2828 - Error states and destructive actions
+
+Card Hierarchy (light to dark):
+
+#f2f1ed - Card (base surface)
+#f0efeb - Card-01 (slightly elevated)
+#ebeae5 - Card-02 (mid elevation)
+#e6e5e0 - Card-03 (high elevation)
+#e1e0db - Card-04 (highest elevation)
+
+### Typography
+
+Display/Brand: Manrope (with system sans-serif fallback)
+Body Text: Inter (with system sans-serif fallback)
+Data/Labels: System monospace (SF Mono, Menlo, Consolas)
+
+## Features
+
+### Smart Font Application
+
+- Applies Manrope to brand and display text (logo, hero sections, loading screens, onboarding)
+- Applies Inter at light weight to all body text
+- Applies monospace to data labels, statistics, tabular numbers, status badges, and micro-labels
+- Manrope should use tight letter-spacing for brand moments
+- Standard UI text (form labels, table cells, body copy) stays on Inter
+
+### Text Styling
+
+- Headings and brand moments: Manrope, tight tracking
+- Body text: Inter, light weight
+- Data and metrics: Monospace, small size (10-11px), uppercase, wide tracking
+- Tabular numbers always use monospace for alignment
+- Smart color selection based on surface — darker text on light surfaces, lighter text on dark
+- Preserves text hierarchy and formatting
+
+### Color Application
+
+- Warm neutral palette throughout — cream and off-white tones, never stark white
+- Brand teal used for primary actions, focus rings, and interactive highlights
+- Brand gradient reserved for premium or highlight elements — use sparingly
+- Card hierarchy provides layered depth through progressively darker warm neutrals
+- Semantic colors (success, warning, error) only for their intended status meaning
+
+### Shape and Accent Colors
+
+- Non-text elements use the brand teal or card hierarchy colors
+- Brand gradient cycles from #0da5a1 to #00d4cf at a 287deg angle
+- Maintains visual interest while staying on-brand
+- No emojis anywhere — not in UI, copy, or documentation

package/templates/.cursor/skills/create-pr/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: create-pr
+description: Turn current workspace changes into a published GitHub pull request by creating or reusing a branch, committing the changes, pushing the branch, and opening a PR with gh.
+---
+
+## 1. Trigger this skill
+
+- Use when the user asks to run end-to-end PR publishing for current local changes.
+- Use when the user asks for branch creation + commit + push + PR in one command.
+
+## 2. Required tooling
+
+- `git` and `gh` are available and authenticated.
+- `scripts/create-pr.sh` exists at repo root.
+- Git remote `origin` is configured.
+
+## 3. Inputs you can pass
+
+- `TARGET_BRANCH`: desired branch name.
+- `COMMIT_MESSAGE`: commit message used for the commit.
+- `PR_TITLE`: PR title shown in GitHub.
+- `PR_BODY_FILE`: optional markdown file path for PR body.
+- `BASE_BRANCH`: PR base branch (default `main`).
+- `GIT_REMOTE`: git remote name (default `origin`).
+
+## 4. Process
+
+Run the workflow via script:
+
+```bash
+TARGET_BRANCH=<branch-name> \
+COMMIT_MESSAGE="<message>" \
+PR_TITLE="<PR title>" \
+BASE_BRANCH=<base branch> \
+scripts/create-pr.sh
+```
+
+Workflow order:
+
+- Create or checkout `TARGET_BRANCH`.
+- Add all local changes and create one commit with `COMMIT_MESSAGE`.
+- Push branch with upstream tracking to `GIT_REMOTE`.
+- Open a PR from `TARGET_BRANCH` to `BASE_BRANCH`.
+- Print PR URL on success.
+
+## 5. Safety and failure behavior
+
+- Abort with clear error when no changes are present.
+- Abort when required commands are unavailable.
+- If PR creation fails after push, return a message with the pushed remote branch and stop cleanly.
+
+## 6. PR description guidelines
+
+# Pull Request Guide
+
+This document describes how we write PRs for this project. The goal is for a reviewer — or anyone reading the PR months later — to understand what problem existed, what decision was made, and why, without having to read the code.
+
+---
+
+## Structure
+
+Every non-trivial PR should follow this structure:
+
+### 1. Summary
+
+One short paragraph stating what this PR does and why it matters. No bullet lists here — write in prose.
+
+### 2. Before vs After
+
+For architectural or flow changes, show the old and new as ASCII diagrams or code blocks. Label the problems with the old approach explicitly. The diagram should make the improvement self-evident.
+
+```
+# Example
+Before:
+  raw snapshot (~50K tokens)
+    └─ agent A → agent B → agent C (sequential)
+
+After:
+  formatted input (~1.5K tokens)
+    ├─ agent A
+    ├─ agent B  (parallel)
+    └─ agent C
+```
+
+### 3. Key Improvements
+
+Bullet list of the specific wins. Be concrete — use numbers.
+
+- "~97% token reduction" not "significant token reduction"
+- "MAE dropped from 3.5 to 2.1" not "improved accuracy"
+- "removed one sequential LLM hop" not "made it faster"
+
+### 4. Deep-dive Sections
+
+For anything non-obvious — evaluation methodology, format design, data shape changes, model selection — give it its own titled section. Reviewers who want detail can read it; others can skip.
+
+### 5. New Data Shape
+
+Whenever the output schema of a service or database record changes, show the new shape as a TypeScript snippet or JSON example.
+
+### 6. Open TODOs
+
+Explicitly list what is **not** in this PR but should be done. Bold the item name, one sentence of context. This prevents follow-up questions and captures intent before it gets lost.
+
+- **Item name** — why it matters and what needs to happen
+
+### 7. Test Plan
+
+Checkboxes with specific commands and specific things to verify. Not "test it works" but:
+
+- [ ] Run `doppler run -- npx tsx scripts/foo.ts` — verify output X
+- [ ] Process a new profile end-to-end — confirm data shape matches Y
+- [ ] Retry a partially-failed job — confirm only failed steps re-run
+
+---
+
+## Tone and Style
+
+- No emojis
+- No tool attribution footers (e.g. "Generated with X")
+- Write in plain declarative sentences: "Personality runs in parallel" not "We made personality run in parallel"
+- Use exact numbers where available
+- For model or approach comparisons, use a table
+- Don't hedge: say what happened
+
+## Title Format
+
+Use [Conventional Commits](https://www.conventionalcommits.org/). Use title case for PR titles (capitalize principal words; lowercase short conjunctions like `and`, `or`, `for` unless they start the title). Preserve identifiers as they appear in code (`Cluster.AgentId`, API names, etc.).
+
+Keep titles under 72 characters. Use the description/body for details, not the title.
+
+---
+
+## PR Size
+
+- Prefer one focused PR over several small ones for tightly coupled changes
+- If a PR touches both a refactor and a new feature, split them unless they are inseparable
+- Infrastructure changes (schema, DB migrations) should be their own PR

package/templates/.cursor/skills/frontend-design/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: You is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.