Compare commits
103
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
b7aab61be0 | ||
|
|
04beadc0e2 | ||
|
|
cf67c5d96f | ||
|
|
e6c7dcf295 | ||
|
|
9e44e91d81 | ||
|
|
c6cd515588 | ||
|
|
0f871729c0 | ||
|
|
e73f81d6fe | ||
|
|
f5235bf219 | ||
|
|
19f10d25df | ||
|
|
3ddd6ec150 | ||
|
|
42f4701fda | ||
|
|
4c6978ea90 | ||
|
|
3c03b4e7a4 | ||
|
|
d2bdb0cee8 | ||
|
|
21adb9f2e8 | ||
|
|
b792dc0373 | ||
|
|
cbbc38ecc9 | ||
|
|
bbb231541b | ||
|
|
70fd3e1818 | ||
|
|
0ee8ae700c | ||
|
|
2c17b1e701 | ||
|
|
2ed8da0e1c | ||
|
|
9006064240 | ||
|
|
fe2cfa9dac | ||
|
|
84f3691c22 | ||
|
|
f9384b8244 | ||
|
|
d0ae85049f | ||
|
|
64815c114c | ||
|
|
e86fdf56d0 | ||
|
|
c25a1e6d58 | ||
|
|
f9c8bcff17 | ||
|
|
008e8cd01d | ||
|
|
1d1c7b270b | ||
|
|
63a5e5d8a1 | ||
|
|
39c1172b0b | ||
|
|
09ac165420 | ||
|
|
1daa8a6979 | ||
|
|
2c97f8e1e3 | ||
|
|
1fb830e962 | ||
|
|
5e542c3ca6 | ||
|
|
7e25fdfba2 | ||
|
|
c56987d6ce | ||
|
|
40888fb7dd | ||
|
|
e6305ca92f | ||
|
|
ebd9106cb8 | ||
|
|
51c8c28a08 | ||
|
|
9b7c41834c | ||
|
|
98c724a8c8 | ||
|
|
e6e0b8cbd4 | ||
|
|
98ab6372a1 | ||
|
|
772754e069 | ||
|
|
a254784c3a | ||
|
|
4889d7abea | ||
|
|
045eb03440 | ||
|
|
a773336d4b | ||
|
|
fcbe5f460e | ||
|
|
ab80dad42b | ||
|
|
69b66b44c9 | ||
|
|
e1d2c38687 | ||
|
|
1e21de55d7 | ||
|
|
c480bfdbd2 | ||
|
|
8dcb9f406d | ||
|
|
0625371ed4 | ||
|
|
45a213ac09 | ||
|
|
753071224e | ||
|
|
93504624ae | ||
|
|
ca17552d3d | ||
|
|
a9934f471e | ||
|
|
25e4280cad | ||
|
|
2e30a04ff1 | ||
|
|
6adb693f53 | ||
|
|
ef323f2c57 | ||
|
|
215dd9251c | ||
|
|
ce081c21fc | ||
|
|
0634712802 | ||
|
|
179dbdfad2 | ||
|
|
62d344baec | ||
|
|
6a3b143614 | ||
|
|
6cb7be0de1 | ||
|
|
1e59c9868e | ||
|
|
af1915805a | ||
|
|
d8205e6c3a | ||
|
|
e5b686c556 | ||
|
|
400a6abe74 | ||
|
|
6c8163dae3 | ||
|
|
e0ac5041c2 | ||
|
|
0b64459cfe | ||
|
|
e917caf7f1 | ||
|
|
6730aaff13 | ||
|
|
7c1fce98bd | ||
|
|
30bee799e1 | ||
|
|
031a073cf9 | ||
|
|
43d6a057ba | ||
|
|
9c03edb65c | ||
|
|
9f1f39203e | ||
|
|
9b459206d6 | ||
|
|
cd44a41c5d | ||
|
|
82cc79fa45 | ||
|
|
fdc722de51 | ||
|
|
be692fadaa | ||
|
|
eb12866d03 | ||
|
|
c279b7c3d1 |
No files matched your search
@@ -1,60 +0,0 @@
|
||||
# Global Skills Index
|
||||
|
||||
All skills below are installed at `C:\Users\silve\.agents\skills\` and are available in every project.
|
||||
When the user invokes `/skill-name`, read and follow the skill at the path shown.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|---|---|---|
|
||||
| `adapt` | Adapt designs to work across different screen sizes, devices, contexts, or platforms. Implements breakpoints, fluid layouts, and touch targets. | `C:\Users\silve\.agents\skills\adapt\SKILL.md` |
|
||||
| `better-auth-security-best-practices` | Configure rate limiting, manage auth secrets, set up CSRF protection, define trusted origins, secure sessions and cookies, encrypt OAuth tokens, track IP addresses, and implement audit logging for Better Auth. | `C:\Users\silve\.agents\skills\better-auth-security-best-practices\SKILL.md` |
|
||||
| `brainstorming` | Use before any creative work — creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. | `C:\Users\silve\.agents\skills\brainstorming\SKILL.md` |
|
||||
| `ckm-banner-design` | Design banners for social media, ads, website heroes, creative assets, and print. Multiple art direction options. | `C:\Users\silve\.agents\skills\ckm-banner-design\SKILL.md` |
|
||||
| `ckm-brand` | Brand voice, visual identity, messaging frameworks, asset management, brand consistency. | `C:\Users\silve\.agents\skills\ckm-brand\SKILL.md` |
|
||||
| `ckm-design` | Comprehensive design skill: brand identity, design tokens, UI styling, logo generation, CIP, HTML presentations, banner design, icon design, social photos. | `C:\Users\silve\.agents\skills\ckm-design\SKILL.md` |
|
||||
| `ckm-design-system` | Token architecture, component specifications, and slide generation. Three-layer tokens (primitive→semantic→component), CSS variables. | `C:\Users\silve\.agents\skills\ckm-design-system\SKILL.md` |
|
||||
| `ckm-slides` | Create strategic HTML presentations with Chart.js, design tokens, responsive layouts, copywriting formulas. | `C:\Users\silve\.agents\skills\ckm-slides\SKILL.md` |
|
||||
| `ckm-ui-styling` | Create beautiful, accessible UIs with shadcn/ui components (Radix UI + Tailwind), Tailwind CSS, canvas-based visual designs. | `C:\Users\silve\.agents\skills\ckm-ui-styling\SKILL.md` |
|
||||
| `create-agentsmd` | Generate an AGENTS.md file for a repository. | `C:\Users\silve\.agents\skills\create-agentsmd\SKILL.md` |
|
||||
| `create-proposal` | Generate a customized premium HTML proposal for clients. | `C:\Users\silve\.agents\skills\create-proposal\SKILL.md` |
|
||||
| `create-readme` | Create a README.md file for the project. | `C:\Users\silve\.agents\skills\create-readme\SKILL.md` |
|
||||
| `dispatching-parallel-agents` | Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies. | `C:\Users\silve\.agents\skills\dispatching-parallel-agents\SKILL.md` |
|
||||
| `docker-compose-orchestration` | Container orchestration with Docker Compose for multi-container applications, networking, volumes, and production deployment. | `C:\Users\silve\.agents\skills\docker-compose-orchestration\SKILL.md` |
|
||||
| `executing-plans` | Use when you have a written implementation plan to execute in a separate session with review checkpoints. | `C:\Users\silve\.agents\skills\executing-plans\SKILL.md` |
|
||||
| `explain simply` | Explains a task or concept in a straightforward, jargon-free way. Use when the user asks for a simple explanation, or when complex technical topics need to be made accessible. | `C:\Users\silve\.agents\skills\explain-simply\SKILL.md` |
|
||||
| `find-skills` | Helps discover and install agent skills — use when asking "how do I do X", "find a skill for X", or "is there a skill that can...". | `C:\Users\silve\.agents\skills\find-skills\SKILL.md` |
|
||||
| `finishing-a-development-branch` | Use when implementation is complete, all tests pass, and you need to decide how to integrate the work. | `C:\Users\silve\.agents\skills\finishing-a-development-branch\SKILL.md` |
|
||||
| `generate-update-notes` | Generate formatted update notes from recent git commits and track the last processed commit. | `C:\Users\silve\.agents\skills\generate-update-notes\SKILL.md` |
|
||||
| `multi-stage-dockerfile` | Create optimized multi-stage Dockerfiles for any language or framework. | `C:\Users\silve\.agents\skills\multi-stage-dockerfile\SKILL.md` |
|
||||
| `n8n-code-javascript` | Write JavaScript code in n8n Code nodes using $input/$json/$node syntax. | `C:\Users\silve\.agents\skills\n8n-code-javascript\SKILL.md` |
|
||||
| `n8n-expression-syntax` | Validate n8n expression syntax and fix common errors with {{}} syntax. | `C:\Users\silve\.agents\skills\n8n-expression-syntax\SKILL.md` |
|
||||
| `n8n-mcp-tools-expert` | Expert guide for using n8n-mcp MCP tools effectively. | `C:\Users\silve\.agents\skills\n8n-mcp-tools-expert\SKILL.md` |
|
||||
| `n8n-node-configuration` | Operation-aware node configuration guidance for n8n. | `C:\Users\silve\.agents\skills\n8n-node-configuration\SKILL.md` |
|
||||
| `n8n-validation-expert` | Interpret n8n validation errors and guide fixing them. | `C:\Users\silve\.agents\skills\n8n-validation-expert\SKILL.md` |
|
||||
| `n8n-workflow-patterns` | Proven workflow architectural patterns from real n8n workflows. | `C:\Users\silve\.agents\skills\n8n-workflow-patterns\SKILL.md` |
|
||||
| `next-best-practices` | Next.js best practices — file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling. | `C:\Users\silve\.agents\skills\next-best-practices\SKILL.md` |
|
||||
| `next-cache-components` | Next.js 16 Cache Components — PPR, use cache directive, cacheLife, cacheTag, updateTag. | `C:\Users\silve\.agents\skills\next-cache-components\SKILL.md` |
|
||||
| `next-upgrade` | Upgrade Next.js to the latest version following official migration guides and codemods. | `C:\Users\silve\.agents\skills\next-upgrade\SKILL.md` |
|
||||
| `nextjs-prisma-standalone` | Use when building Next.js standalone containers with Prisma, or when encountering datasource/dotenv/Prisma 7 schema errors during deployment. | `C:\Users\silve\.agents\skills\nextjs-prisma-standalone\SKILL.md` |
|
||||
| `nodejs-backend-patterns` | Build production-ready Node.js backend services with Express/Fastify, middleware, error handling, authentication, database integration, and API design. | `C:\Users\silve\.agents\skills\nodejs-backend-patterns\SKILL.md` |
|
||||
| `pnpm` | Node.js package manager with strict dependency resolution. Use for pnpm commands, configuring workspaces, managing dependencies with catalogs, patches, or overrides. | `C:\Users\silve\.agents\skills\pnpm\SKILL.md` |
|
||||
| `readme-i18n` | Translate a repository README, make a repo multilingual, localize docs, add a language switcher. | `C:\Users\silve\.agents\skills\readme-i18n\SKILL.md` |
|
||||
| `receiving-code-review` | Use when receiving code review feedback, before implementing suggestions — requires technical rigor and verification. | `C:\Users\silve\.agents\skills\receiving-code-review\SKILL.md` |
|
||||
| `refactor` | Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming, breaking down god functions, improving type safety. | `C:\Users\silve\.agents\skills\refactor\SKILL.md` |
|
||||
| `refactoring-ui` | Audit and fix visual hierarchy, spacing, color, and depth in web UIs. | `C:\Users\silve\.agents\skills\refactoring-ui\SKILL.md` |
|
||||
| `requesting-code-review` | Use when completing tasks, implementing major features, or before merging to verify work meets requirements. | `C:\Users\silve\.agents\skills\requesting-code-review\SKILL.md` |
|
||||
| `researching-plugins` | Use when evaluating new data sources, researching APIs, or planning a new plugin structure, before writing any implementation code. | `C:\Users\silve\.agents\skills\researching-plugins\SKILL.md` |
|
||||
| `security-review` | Use when adding authentication, handling user input, working with secrets, creating API endpoints, or implementing payment/sensitive features. | `C:\Users\silve\.agents\skills\security-review\SKILL.md` |
|
||||
| `seo-audit` | Audit, review, or diagnose SEO issues — technical SEO, meta tags, core web vitals, crawl errors, indexing issues. | `C:\Users\silve\.agents\skills\seo-audit\SKILL.md` |
|
||||
| `subagent-driven-development` | Use when executing implementation plans with independent tasks in the current session. | `C:\Users\silve\.agents\skills\subagent-driven-development\SKILL.md` |
|
||||
| `supabase-postgres-best-practices` | Postgres performance optimization and best practices from Supabase. Use when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations. | `C:\Users\silve\.agents\skills\supabase-postgres-best-practices\SKILL.md` |
|
||||
| `systematic-debugging` | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. | `C:\Users\silve\.agents\skills\systematic-debugging\SKILL.md` |
|
||||
| `test-driven-development` | Use when implementing any feature or bugfix, before writing implementation code. | `C:\Users\silve\.agents\skills\test-driven-development\SKILL.md` |
|
||||
| `ui-ux-pro-max` | UI/UX design intelligence for web and mobile. 50+ styles, 161 color palettes, 57 font pairings across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, HTML/CSS). | `C:\Users\silve\.agents\skills\ui-ux-pro-max\SKILL.md` |
|
||||
| `update-context` | Update context documents — sync `.agents/context/` with current project state. | `C:\Users\silve\.agents\skills\update-context\SKILL.md` |
|
||||
| `using-superpowers` | Use when starting any conversation — establishes how to find and use skills, requires Skill tool invocation before ANY response. | `C:\Users\silve\.agents\skills\using-superpowers\SKILL.md` |
|
||||
| `vercel-react-best-practices` | React and Next.js performance optimization guidelines from Vercel Engineering. Use when writing, reviewing, or refactoring React/Next.js code. | `C:\Users\silve\.agents\skills\vercel-react-best-practices\SKILL.md` |
|
||||
| `verification-before-completion` | Use before claiming work is complete — requires running verification commands and confirming output before making any success claims. | `C:\Users\silve\.agents\skills\verification-before-completion\SKILL.md` |
|
||||
| `web-design-guidelines` | Review UI code for Web Interface Guidelines compliance, accessibility, and UX best practices. | `C:\Users\silve\.agents\skills\web-design-guidelines\SKILL.md` |
|
||||
| `worldwideview-plugin-creation` | Use when creating a new plugin, adding a new data source, or debugging missing plugin data in the WorldWideView project (Fastify + Next.js + Cesium architecture). | `C:\Users\silve\.agents\skills\worldwideview-plugin-creation\SKILL.md` |
|
||||
| `writing-plans` | Use when you have a spec or requirements for a multi-step task, before touching code. | `C:\Users\silve\.agents\skills\writing-plans\SKILL.md` |
|
||||
| `writing-skills` | Use when creating new skills, editing existing skills, or verifying skills work before deployment. | `C:\Users\silve\.agents\skills\writing-skills\SKILL.md` |
|
||||
@@ -1,216 +0,0 @@
|
||||
# Plugin Architecture Migration Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Migrate the WorldWideView plugin architecture from compile-time hardcoded imports to a dynamic, runtime-loaded ecosystem where external developers can build, host, and distribute plugins without touching the core repository.
|
||||
|
||||
**Architecture:** We will introduce a bundler (`tsup`) to the SDK to compile `bundle` plugins into browser-ready ECMAScript Modules (ESM). We will expose shared dependencies (`react`, `cesium`, `lucide-react`) via a global `window.__WWV_SHARED__` object. Finally, we will refactor `AppShell.tsx` to dynamically load all plugins at runtime via `import(/* webpackIgnore: true */)`, removing the hardcoded imports, and we will update `loadPluginFromManifest.ts` to seamlessly handle the global dependency injection.
|
||||
|
||||
**Tech Stack:** Next.js, React, CesiumJS, tsup.
|
||||
|
||||
---
|
||||
|
||||
## User Review Required
|
||||
|
||||
> [!WARNING]
|
||||
> **Breaking Change**: This migration will decouple your built-in plugins from `AppShell.tsx`. They will now act as true "external" plugins that are loaded at runtime. During the transition, if the build steps aren't executed, the plugins will temporarily stop appearing on the globe. We will mitigate this by ensuring the build step runs before `next dev`.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Static GeoJSON Files**: Since static `.geojson` files currently live in `public/data`, we will leave them there during phase 1 of this migration to ensure the app doesn't break, but we will point the plugin manifests to load them via absolute or absolute-relative URLs (`/data/...`). In phase 2, we will introduce a symlink script to move them out of `public` entirely.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **Build Tool Choice**: I am proposing `tsup` because it requires zero configuration to output multiple formats, automatically externalizes dependencies, and natively transpiles TypeScript/React. Are you comfortable adding `tsup` to the `wwv-plugin-sdk` package?
|
||||
2. **Local Serving**: To test "built-in" plugins using the dynamic loading method, we need the Next.js app to serve their compiled `plugin.js` bundles. My plan adds a quick copy script to the root `package.json` that copies their `dist` folders into `public/builtin-plugins/` so they can be fetched locally via HTTP. Does this sound good?
|
||||
|
||||
## Proposed Changes
|
||||
|
||||
### Task 1: Initialize Global Shared Dependencies
|
||||
|
||||
**Files:**
|
||||
- Modify: `c:\dev\worldwideview\src\components\layout\AppShell.tsx`
|
||||
- Create: `c:\dev\worldwideview\src\core\plugins\PluginGlobals.ts`
|
||||
|
||||
- [ ] **Step 1: Create the PluginGlobals initializer**
|
||||
|
||||
```typescript
|
||||
import React from "react";
|
||||
import ReactDOM from "react-dom";
|
||||
import * as ReactDomServer from "react-dom/server";
|
||||
import { Plane, Ship, Camera, Shield, Flame, Map, Swords, Atom, Landmark, Mountain, PlaneTakeoff, Anchor, Lamp, Rocket, SunMoon, Cable, Pickaxe, ShieldAlert, Crosshair, SatelliteDish, Hand, Radar, Scale } from "lucide-react";
|
||||
import * as Cesium from "cesium";
|
||||
import * as WWVPluginSDK from "@worldwideview/wwv-plugin-sdk";
|
||||
|
||||
export function initPluginGlobals() {
|
||||
if (typeof window === "undefined") return;
|
||||
|
||||
// Create a registry of Lucide icons commonly used by plugins to prevent them from bundling the massive icon library
|
||||
const lucideIcons = {
|
||||
Plane, Ship, Camera, Shield, Flame, Map, Swords, Atom, Landmark, Mountain,
|
||||
PlaneTakeoff, Anchor, Lamp, Rocket, SunMoon, Cable, Pickaxe, ShieldAlert,
|
||||
Crosshair, SatelliteDish, Hand, Radar, Scale
|
||||
};
|
||||
|
||||
(window as any).__WWV_SHARED__ = {
|
||||
"react": React,
|
||||
"react-dom": ReactDOM,
|
||||
"react-dom/server": ReactDomServer,
|
||||
"cesium": Cesium,
|
||||
"@worldwideview/wwv-plugin-sdk": WWVPluginSDK,
|
||||
"lucide-react": lucideIcons
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Inject globals in AppShell before anything loads**
|
||||
|
||||
In `AppShell.tsx`, import and call `initPluginGlobals()` at the top of the file, outside of any React components.
|
||||
|
||||
```tsx
|
||||
import { initPluginGlobals } from "@/core/plugins/PluginGlobals";
|
||||
import dynamic from "next/dynamic";
|
||||
|
||||
// Initialize globals immediately so they exist before any dynamic imports
|
||||
if (typeof window !== "undefined") {
|
||||
initPluginGlobals();
|
||||
}
|
||||
//... rest of the file
|
||||
```
|
||||
|
||||
### Task 2: Configure SDK Build Tool (`tsup`)
|
||||
|
||||
**Files:**
|
||||
- Modify: `c:\dev\worldwideview\packages\wwv-plugin-sdk\package.json`
|
||||
- Create: `c:\dev\worldwideview\packages\wwv-plugin-sdk\bin\wwv-plugin-build.js`
|
||||
|
||||
- [ ] **Step 1: Add tsup dependency**
|
||||
|
||||
Run: `pnpm --filter @worldwideview/wwv-plugin-sdk add -D tsup`
|
||||
|
||||
- [ ] **Step 2: Create the wwv-plugin-build CLI wrapper**
|
||||
|
||||
Add this to `wwv-plugin-sdk/bin/wwv-plugin-build.js`:
|
||||
|
||||
```javascript
|
||||
#!/usr/bin/env node
|
||||
const { build } = require("tsup");
|
||||
const path = require("path");
|
||||
|
||||
async function run() {
|
||||
const cwd = process.cwd();
|
||||
await build({
|
||||
entry: ["src/index.ts"],
|
||||
outDir: "dist",
|
||||
format: ["esm"],
|
||||
target: "es2022",
|
||||
clean: true,
|
||||
dts: false,
|
||||
minify: false,
|
||||
sourcemap: true,
|
||||
// Mark all these as externals so they aren't bundled
|
||||
external: ["react", "react-dom", "cesium", "@worldwideview/wwv-plugin-sdk", "lucide-react"],
|
||||
// Provide a shim that converts bare imports into global lookups
|
||||
esbuildPlugins: [{
|
||||
name: "wwv-globals",
|
||||
setup(build) {
|
||||
build.onResolve({ filter: /^(react|react-dom|cesium|@worldwideview\/wwv-plugin-sdk|lucide-react)$/ }, args => {
|
||||
return { path: args.path, namespace: "wwv-global" };
|
||||
});
|
||||
build.onLoad({ filter: /.*/, namespace: "wwv-global" }, args => {
|
||||
let globalKey = args.path;
|
||||
if (args.path === "lucide-react") return { contents: `module.exports = window.__WWV_SHARED__["lucide-react"];` };
|
||||
return { contents: `module.exports = window.__WWV_SHARED__["${globalKey}"];` };
|
||||
});
|
||||
}
|
||||
}]
|
||||
});
|
||||
}
|
||||
run();
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Update SDK package.json to expose the bin**
|
||||
|
||||
```json
|
||||
"bin": {
|
||||
"wwv-plugin-build": "./bin/wwv-plugin-build.js"
|
||||
},
|
||||
```
|
||||
|
||||
### Task 3: Refactor Plugins to use Build Tool and Manifests
|
||||
|
||||
**Files:**
|
||||
- Modify: `wwv-plugin-aviation/package.json`
|
||||
- Modify: `wwv-plugin-aviation/plugin.json` (Create)
|
||||
|
||||
- [ ] **Step 1: Add build script to aviation plugin**
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"build": "wwv-plugin-build"
|
||||
},
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Create plugin.json for aviation**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "aviation",
|
||||
"name": "Aviation",
|
||||
"version": "1.0.7",
|
||||
"type": "data-layer",
|
||||
"format": "bundle",
|
||||
"trust": "built-in",
|
||||
"capabilities": ["data:own", "network:fetch"],
|
||||
"category": "aviation",
|
||||
"icon": "Plane",
|
||||
"entry": "/builtin-plugins/aviation/index.mjs"
|
||||
}
|
||||
```
|
||||
|
||||
*(Repeat for all other built-in plugins)*
|
||||
|
||||
### Task 4: Dynamic Initial Loader
|
||||
|
||||
**Files:**
|
||||
- Modify: `c:\dev\worldwideview\src\components\layout\AppShell.tsx`
|
||||
- Modify: `c:\dev\worldwideview\package.json`
|
||||
|
||||
- [ ] **Step 1: Remove Hardcoded Plugins**
|
||||
|
||||
In `AppShell.tsx`, delete the `builtIns` array and `import` statements at the top.
|
||||
|
||||
- [ ] **Step 2: Fetch and load all plugins via manifest**
|
||||
|
||||
Modify `AppShell.tsx` `startPlatform`:
|
||||
|
||||
```typescript
|
||||
// Fetch the unified list of ALL installed plugins (both built-in and dynamic)
|
||||
const res = await fetch("/api/marketplace/load");
|
||||
if (res.ok) {
|
||||
const data = await res.json();
|
||||
for (const manifest of data.manifests) {
|
||||
if (disabledIds.has(manifest.id)) continue;
|
||||
try {
|
||||
await pluginManager.loadFromManifest(manifest);
|
||||
initLayer(manifest.id);
|
||||
} catch (e) {
|
||||
console.error("Failed to load plugin", manifest.id, e);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Add predev copy-script**
|
||||
|
||||
Modify `package.json` to copy compiled plugin `dist` folders to `public/builtin-plugins` so the Next.js server can serve them at the `/builtin-plugins/...` path.
|
||||
|
||||
## Verification Plan
|
||||
|
||||
### Automated Tests
|
||||
- Run `pnpm --filter wwv-plugin-aviation build` to ensure `tsup` generates a valid ES Module with no bundled React.
|
||||
- Verify `dist/index.mjs` contains `window.__WWV_SHARED__["react"]` lookups.
|
||||
|
||||
### Manual Verification
|
||||
- Start the Next.js server.
|
||||
- Open network tab in browser and verify `GET /builtin-plugins/aviation/index.mjs` succeeds.
|
||||
- Verify the Aviation plugin appears on the globe and renders planes successfully, indicating that it successfully retrieved Cesium and React from the global shared context.
|
||||
@@ -1,475 +0,0 @@
|
||||
# Demo Google AdSense Panel Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Add a Google AdSense vertical ad strip to the right side of the demo instance, with a dismissible banner explaining it's temporary to fund hosting.
|
||||
|
||||
**Architecture:** Three layers: (1) load the AdSense script conditionally in the root layout only when `isDemo` is true, (2) a reusable `AdUnit` client component that calls `adsbygoogle.push({})`, (3) a `DemoAdStrip` shell component that wraps the ad unit + a "why ads?" dismissible message, positioned as a fixed vertical strip on the right edge. CSP headers in `next.config.ts` must be updated to allow the AdSense domains.
|
||||
|
||||
**Tech Stack:** Next.js 16 (App Router, `next/script`), Google AdSense, vanilla CSS, Vitest
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
| File | Action | Responsibility |
|
||||
|---|---|---|
|
||||
| `src/app/layout.tsx` | MODIFY | Conditionally load AdSense `<Script>` for demo |
|
||||
| `next.config.ts` | MODIFY | Add AdSense domains to CSP `script-src` and `frame-src` |
|
||||
| `.env` | MODIFY | Add `NEXT_PUBLIC_ADSENSE_CLIENT_ID` placeholder |
|
||||
| `src/components/ads/AdUnit.tsx` | CREATE | Generic reusable AdSense unit component |
|
||||
| `src/components/ads/DemoAdStrip.tsx` | CREATE | Demo-only vertical strip: ad + "why ads?" message |
|
||||
| `src/components/ads/DemoAdStrip.css` | CREATE | Styles for the vertical ad strip |
|
||||
| `src/components/layout/AppShell.tsx` | MODIFY | Import and render `<DemoAdStrip />` |
|
||||
| `src/types/adsense.d.ts` | CREATE | TypeScript ambient declaration for `window.adsbygoogle` |
|
||||
|
||||
---
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Before starting:** You need a Google AdSense publisher ID (`ca-pub-XXXXXXXXXXXXXXXX`) and an ad slot ID. These go into `.env` as `NEXT_PUBLIC_ADSENSE_CLIENT_ID` and are passed to the ad unit component. You can get these from [Google AdSense](https://www.google.com/adsense/). Without them the ads will not render, but the component framework will still work.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: TypeScript Ambient Declaration for AdSense
|
||||
|
||||
**Files:**
|
||||
- Create: `src/types/adsense.d.ts`
|
||||
|
||||
- [ ] **Step 1: Create the ambient type declaration**
|
||||
|
||||
```ts
|
||||
// src/types/adsense.d.ts
|
||||
interface Window {
|
||||
adsbygoogle: Array<Record<string, unknown>>;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add src/types/adsense.d.ts
|
||||
git commit -m "chore: add adsense ambient type declaration"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Environment Variable
|
||||
|
||||
**Files:**
|
||||
- Modify: `.env`
|
||||
|
||||
- [ ] **Step 1: Add the AdSense client ID placeholder**
|
||||
|
||||
Add the following line to the end of `.env`:
|
||||
|
||||
```
|
||||
# Google AdSense — only used on demo edition
|
||||
NEXT_PUBLIC_ADSENSE_CLIENT_ID=
|
||||
```
|
||||
|
||||
The actual value (`ca-pub-XXXXXXXXXXXXXXXX`) should be set in `.env.local` for local testing or in the deployment environment. The ad slot IDs will be hardcoded in the component since there's only one placement.
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add .env
|
||||
git commit -m "chore: add NEXT_PUBLIC_ADSENSE_CLIENT_ID env var"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: CSP Headers Update
|
||||
|
||||
**Files:**
|
||||
- Modify: `next.config.ts:29-52`
|
||||
|
||||
- [ ] **Step 1: Update CSP in next.config.ts**
|
||||
|
||||
In the `headers()` function, modify the `script-src` and `frame-src` directives to allow AdSense domains.
|
||||
|
||||
```ts
|
||||
// Change this line (line 39):
|
||||
"script-src 'self' 'unsafe-eval' 'unsafe-inline' blob: https://analytics.worldwideview.dev https://va.vercel-scripts.com",
|
||||
|
||||
// To this:
|
||||
"script-src 'self' 'unsafe-eval' 'unsafe-inline' blob: https://analytics.worldwideview.dev https://va.vercel-scripts.com https://pagead2.googlesyndication.com https://adservice.google.com https://www.googletagservices.com",
|
||||
```
|
||||
|
||||
```ts
|
||||
// Change this line (line 49):
|
||||
"frame-src 'self' *.youtube.com *.youtube-nocookie.com *.twitch.tv *.vimeo.com *.webcamera.pl *.ivideon.com *.rtsp.me *.bnu.tv",
|
||||
|
||||
// To this:
|
||||
"frame-src 'self' *.youtube.com *.youtube-nocookie.com *.twitch.tv *.vimeo.com *.webcamera.pl *.ivideon.com *.rtsp.me *.bnu.tv https://googleads.g.doubleclick.net https://tpc.googlesyndication.com",
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add next.config.ts
|
||||
git commit -m "feat: add Google AdSense domains to CSP headers"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: AdSense Script in Root Layout
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/app/layout.tsx:24-39`
|
||||
|
||||
- [ ] **Step 1: Conditionally load AdSense script for demo edition**
|
||||
|
||||
Add the AdSense `<Script>` tag inside `<head>`, using the `NEXT_PUBLIC_` env var for the client ID and the `NEXT_PUBLIC_WWV_EDITION` env var to gate loading.
|
||||
|
||||
```tsx
|
||||
// src/app/layout.tsx — updated <head> section
|
||||
<head>
|
||||
{/* Load CesiumJS base styles (optional, but helps with UI widgets if used later) */}
|
||||
<link rel="stylesheet" href="/cesium/Widgets/widgets.css" />
|
||||
</head>
|
||||
<body suppressHydrationWarning>
|
||||
{children}
|
||||
<Analytics />
|
||||
<Script
|
||||
src="https://analytics.worldwideview.dev/script.js"
|
||||
data-website-id="2c8f6c09-2651-4a2a-af99-b8cee1612b9a"
|
||||
strategy="afterInteractive"
|
||||
/>
|
||||
{process.env.NEXT_PUBLIC_WWV_EDITION === "demo" &&
|
||||
process.env.NEXT_PUBLIC_ADSENSE_CLIENT_ID && (
|
||||
<Script
|
||||
src={`https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=${process.env.NEXT_PUBLIC_ADSENSE_CLIENT_ID}`}
|
||||
crossOrigin="anonymous"
|
||||
strategy="afterInteractive"
|
||||
/>
|
||||
)}
|
||||
</body>
|
||||
```
|
||||
|
||||
> **Note:** We use the raw env var at the layout level (Server Component) rather than importing `isDemo` which uses `process.env.NEXT_PUBLIC_WWV_EDITION` anyway. This avoids importing the edition module into the root layout.
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add src/app/layout.tsx
|
||||
git commit -m "feat: conditionally load AdSense script on demo edition"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Reusable AdUnit Component
|
||||
|
||||
**Files:**
|
||||
- Create: `src/components/ads/AdUnit.tsx`
|
||||
|
||||
- [ ] **Step 1: Create the generic AdSense unit component**
|
||||
|
||||
```tsx
|
||||
// src/components/ads/AdUnit.tsx
|
||||
"use client";
|
||||
|
||||
import { useEffect, useRef } from "react";
|
||||
|
||||
interface AdUnitProps {
|
||||
adSlot: string;
|
||||
adFormat?: string;
|
||||
style?: React.CSSProperties;
|
||||
className?: string;
|
||||
}
|
||||
|
||||
export function AdUnit({ adSlot, adFormat = "auto", style, className }: AdUnitProps) {
|
||||
const pushed = useRef(false);
|
||||
const clientId = process.env.NEXT_PUBLIC_ADSENSE_CLIENT_ID;
|
||||
|
||||
useEffect(() => {
|
||||
if (pushed.current || !clientId) return;
|
||||
try {
|
||||
(window.adsbygoogle = window.adsbygoogle || []).push({});
|
||||
pushed.current = true;
|
||||
} catch (err) {
|
||||
console.error("[AdUnit] AdSense push error:", err);
|
||||
}
|
||||
}, [clientId]);
|
||||
|
||||
if (!clientId) return null;
|
||||
|
||||
return (
|
||||
<div className={className} style={style}>
|
||||
<ins
|
||||
className="adsbygoogle"
|
||||
style={{ display: "block" }}
|
||||
data-ad-client={clientId}
|
||||
data-ad-slot={adSlot}
|
||||
data-ad-format={adFormat}
|
||||
data-full-width-responsive="false"
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
> **Key detail:** The `pushed` ref prevents double-push on React strict mode / hot reload. `data-full-width-responsive="false"` prevents the ad from expanding beyond the container — critical for a fixed-width vertical strip.
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add src/components/ads/AdUnit.tsx
|
||||
git commit -m "feat: add reusable AdUnit component"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: DemoAdStrip Component + Styles
|
||||
|
||||
**Files:**
|
||||
- Create: `src/components/ads/DemoAdStrip.tsx`
|
||||
- Create: `src/components/ads/DemoAdStrip.css`
|
||||
|
||||
- [ ] **Step 1: Create the CSS for the vertical ad strip**
|
||||
|
||||
```css
|
||||
/* src/components/ads/DemoAdStrip.css */
|
||||
|
||||
.demo-ad-strip {
|
||||
position: fixed;
|
||||
right: 0;
|
||||
top: 0;
|
||||
bottom: 0;
|
||||
width: 160px;
|
||||
z-index: 45;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
gap: var(--space-md);
|
||||
padding: var(--space-sm);
|
||||
pointer-events: none;
|
||||
transition: transform var(--duration-slow) var(--ease-smooth),
|
||||
opacity var(--duration-slow) var(--ease-smooth);
|
||||
}
|
||||
|
||||
.demo-ad-strip--hidden {
|
||||
transform: translateX(200px);
|
||||
opacity: 0;
|
||||
}
|
||||
|
||||
.demo-ad-strip__ad {
|
||||
pointer-events: auto;
|
||||
width: 160px;
|
||||
min-height: 600px;
|
||||
}
|
||||
|
||||
.demo-ad-strip__banner {
|
||||
pointer-events: auto;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
gap: var(--space-xs);
|
||||
padding: var(--space-sm) var(--space-md);
|
||||
background: var(--bg-glass);
|
||||
backdrop-filter: blur(var(--glass-blur));
|
||||
-webkit-backdrop-filter: blur(var(--glass-blur));
|
||||
border: 1px solid var(--border-subtle);
|
||||
border-radius: var(--radius-md);
|
||||
max-width: 160px;
|
||||
text-align: center;
|
||||
cursor: pointer;
|
||||
transition: all var(--duration-fast) var(--ease-smooth);
|
||||
}
|
||||
|
||||
.demo-ad-strip__banner:hover {
|
||||
border-color: rgba(var(--accent-rgb), 0.3);
|
||||
box-shadow: var(--glow-cyan);
|
||||
}
|
||||
|
||||
.demo-ad-strip__banner-label {
|
||||
font-size: 9px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.12em;
|
||||
text-transform: uppercase;
|
||||
color: var(--text-muted);
|
||||
}
|
||||
|
||||
.demo-ad-strip__banner-text {
|
||||
font-size: 11px;
|
||||
line-height: 1.4;
|
||||
color: var(--text-secondary);
|
||||
}
|
||||
|
||||
.demo-ad-strip__close {
|
||||
position: absolute;
|
||||
top: var(--space-xs);
|
||||
right: var(--space-xs);
|
||||
width: 20px;
|
||||
height: 20px;
|
||||
border-radius: 50%;
|
||||
background: transparent;
|
||||
border: none;
|
||||
color: var(--text-muted);
|
||||
font-size: 12px;
|
||||
cursor: pointer;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
transition: color var(--duration-fast) var(--ease-smooth);
|
||||
}
|
||||
|
||||
.demo-ad-strip__close:hover {
|
||||
color: var(--text-primary);
|
||||
}
|
||||
|
||||
/* Hide on mobile — ads shouldn't overlay the full-screen globe */
|
||||
@media (max-width: 768px) {
|
||||
.demo-ad-strip {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Create the DemoAdStrip component**
|
||||
|
||||
```tsx
|
||||
// src/components/ads/DemoAdStrip.tsx
|
||||
"use client";
|
||||
|
||||
import { useState } from "react";
|
||||
import { isDemo } from "@/core/edition";
|
||||
import { AdUnit } from "./AdUnit";
|
||||
import { X } from "lucide-react";
|
||||
import "./DemoAdStrip.css";
|
||||
|
||||
/** The ad slot ID for the vertical skyscraper unit — set this in AdSense dashboard. */
|
||||
const VERTICAL_AD_SLOT = "REPLACE_WITH_YOUR_AD_SLOT_ID";
|
||||
|
||||
export function DemoAdStrip() {
|
||||
const [showMessage, setShowMessage] = useState(false);
|
||||
const [closed, setClosed] = useState(false);
|
||||
|
||||
if (!isDemo || closed) return null;
|
||||
|
||||
return (
|
||||
<aside className="demo-ad-strip" aria-label="Sponsored content">
|
||||
<AdUnit
|
||||
adSlot={VERTICAL_AD_SLOT}
|
||||
adFormat="vertical"
|
||||
className="demo-ad-strip__ad"
|
||||
/>
|
||||
|
||||
<div
|
||||
className="demo-ad-strip__banner"
|
||||
onClick={() => setShowMessage((prev) => !prev)}
|
||||
role="button"
|
||||
tabIndex={0}
|
||||
onKeyDown={(e) => { if (e.key === "Enter") setShowMessage((prev) => !prev); }}
|
||||
>
|
||||
<button
|
||||
className="demo-ad-strip__close"
|
||||
onClick={(e) => { e.stopPropagation(); setClosed(true); }}
|
||||
aria-label="Dismiss ad panel"
|
||||
>
|
||||
<X size={12} />
|
||||
</button>
|
||||
<span className="demo-ad-strip__banner-label">Why ads?</span>
|
||||
{showMessage ? (
|
||||
<span className="demo-ad-strip__banner-text">
|
||||
This isn't permanent — it's temporary because I'm a single
|
||||
dev and need to cover hosting costs. Thank you for understanding.
|
||||
</span>
|
||||
) : (
|
||||
<span className="demo-ad-strip__banner-text">
|
||||
Click to learn more
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
</aside>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add src/components/ads/DemoAdStrip.tsx src/components/ads/DemoAdStrip.css
|
||||
git commit -m "feat: add DemoAdStrip with Google AdSense vertical unit"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 7: Integrate into AppShell
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/components/layout/AppShell.tsx:8-9,168`
|
||||
|
||||
- [ ] **Step 1: Add import**
|
||||
|
||||
After the existing `CameraStatsPanel` import (line 8), add:
|
||||
|
||||
```tsx
|
||||
import CameraStatsPanel from "@/components/panels/CameraStatsPanel";
|
||||
import { DemoAdStrip } from "@/components/ads/DemoAdStrip"; // ADD THIS
|
||||
import { Timeline } from "@/components/timeline/Timeline";
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Add the JSX**
|
||||
|
||||
After `<EntityInfoCard />` (line 168), add:
|
||||
|
||||
```tsx
|
||||
<EntityInfoCard />
|
||||
<DemoAdStrip />
|
||||
<Timeline />
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add src/components/layout/AppShell.tsx
|
||||
git commit -m "feat: integrate DemoAdStrip into AppShell"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 8: ads.txt for AdSense Verification
|
||||
|
||||
**Files:**
|
||||
- Create: `public/ads.txt`
|
||||
|
||||
- [ ] **Step 1: Create ads.txt**
|
||||
|
||||
```
|
||||
google.com, ca-pub-XXXXXXXXXXXXXXXX, DIRECT, f08c47fec0942fa0
|
||||
```
|
||||
|
||||
> Replace `ca-pub-XXXXXXXXXXXXXXXX` with your actual publisher ID. This file is required by AdSense for domain verification.
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add public/ads.txt
|
||||
git commit -m "chore: add ads.txt for AdSense domain verification"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Do you have a Google AdSense publisher ID yet?** If not, you'll need to sign up at https://www.google.com/adsense/ and get your `ca-pub-XXXX` ID and create a 160x600 "Wide Skyscraper" ad unit to get the slot ID. The code will render nothing gracefully until these are configured.
|
||||
|
||||
> [!WARNING]
|
||||
> **CSP changes are required for AdSense to work.** The current CSP is restrictive and blocks `pagead2.googlesyndication.com` and `googleads.g.doubleclick.net`. Task 3 adds them. Without this, ads will be silently blocked by the browser.
|
||||
|
||||
---
|
||||
|
||||
## Verification Plan
|
||||
|
||||
### Manual Verification
|
||||
|
||||
1. Set `NEXT_PUBLIC_WWV_EDITION=demo` and `NEXT_PUBLIC_ADSENSE_CLIENT_ID=ca-pub-XXXX` in `.env.local`
|
||||
2. Run `pnpm dev`
|
||||
3. Verify: A 160px vertical strip appears on the right edge of the screen
|
||||
4. Verify: The "Why ads?" banner is clickable and toggles the explanation message
|
||||
5. Verify: Clicking the X dismisses the entire strip
|
||||
6. Verify: On mobile viewport widths (< 768px), the strip is hidden
|
||||
7. Verify: Set `NEXT_PUBLIC_WWV_EDITION=local` → strip does not render at all
|
||||
8. Verify: Browser console shows no CSP violations related to AdSense domains
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1,145 +0,0 @@
|
||||
# Expand OSM Chips Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Expand the available OSM search chips to include a curated list of ~30 pre-loaded OSINT-relevant tags, and add a live Taginfo API autocomplete search to dynamically find and select any of the millions of other OSM tags.
|
||||
|
||||
**Architecture:** We will replace the current small `COMMON_TAGS` array with a richer, categorized list inside the `OSMSidebar` file. To allow access to "all" tags without crashing the UI, we will add a debounced fetch hook that hits `https://taginfo.openstreetmap.org/api/4/tags/popular` (or the equivalent search endpoint) when the user types in the filter box. These dynamically fetched tags will temporarily populate the chip list.
|
||||
|
||||
**Tech Stack:** React, TypeScript, Taginfo API
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Update Pre-Loaded COMMON_TAGS
|
||||
|
||||
**Files:**
|
||||
- Modify: `c:\dev\worldwideview\packages\wwv-plugin-osm-search\src\components\OSMSidebar.tsx:6-11`
|
||||
|
||||
- [ ] **Step 1: Replace existing COMMON_TAGS array**
|
||||
|
||||
```tsx
|
||||
const COMMON_TAGS = [
|
||||
// Military & Security
|
||||
"military=base", "military=bunker", "amenity=police", "amenity=prison",
|
||||
// Aviation & Maritime
|
||||
"aeroway=aerodrome", "aeroway=helipad", "aeroway=hangar", "man_made=pier", "harbour=yes",
|
||||
// Infrastructure & Utilities
|
||||
"power=plant", "power=substation", "telecom=antenna", "man_made=communications_tower", "man_made=water_tower",
|
||||
// Transport
|
||||
"highway=bus_stop", "railway=station", "amenity=fuel", "amenity=parking",
|
||||
// Medical & Emergency
|
||||
"amenity=hospital", "amenity=fire_station", "amenity=clinic",
|
||||
// General Commercial & Industrial
|
||||
"shop=supermarket", "tourism=hotel", "industrial=factory", "landuse=industrial",
|
||||
// Education & Amenities
|
||||
"amenity=school", "amenity=university", "amenity=cafe", "building=house"
|
||||
];
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-plugin-osm-search/src/components/OSMSidebar.tsx
|
||||
git commit -m "feat(osm-search): expand quick preset tags with OSINT categories"
|
||||
```
|
||||
|
||||
### Task 2: Implement Taginfo Dynamic Autocomplete
|
||||
|
||||
**Files:**
|
||||
- Modify: `c:\dev\worldwideview\packages\wwv-plugin-osm-search\src\components\OSMSidebar.tsx`
|
||||
|
||||
- [ ] **Step 1: Add state and debounced fetch logic inside OSMSidebar component**
|
||||
|
||||
```tsx
|
||||
const [searchText, setSearchText] = useState("");
|
||||
const [activeTags, setActiveTags] = useState<string[]>([]);
|
||||
const [dynamicTags, setDynamicTags] = useState<string[]>([]);
|
||||
const [isSearchingApi, setIsSearchingApi] = useState(false);
|
||||
|
||||
// Add this useEffect below the useState hooks
|
||||
React.useEffect(() => {
|
||||
if (searchText.length < 3) {
|
||||
setDynamicTags([]);
|
||||
return;
|
||||
}
|
||||
|
||||
const timer = setTimeout(async () => {
|
||||
setIsSearchingApi(true);
|
||||
try {
|
||||
// Fetch tags matching the search term from OSM Taginfo
|
||||
const res = await fetch(`https://taginfo.openstreetmap.org/api/4/search/by_keyword?query=${encodeURIComponent(searchText)}`);
|
||||
const data = await res.json();
|
||||
if (data && data.data) {
|
||||
// Extract exact key=value pairs or just keys, format as "key=value"
|
||||
const tags = data.data
|
||||
.filter((item: any) => item.key && item.value)
|
||||
.map((item: any) => `${item.key}=${item.value}`)
|
||||
.slice(0, 15); // Limit to top 15 results
|
||||
setDynamicTags(tags);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error("Taginfo fetch failed", err);
|
||||
} finally {
|
||||
setIsSearchingApi(false);
|
||||
}
|
||||
}, 500); // 500ms debounce
|
||||
|
||||
return () => clearTimeout(timer);
|
||||
}, [searchText]);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update rendering logic to merge static and dynamic tags**
|
||||
|
||||
Look for the `renderedTags` definition and replace it:
|
||||
|
||||
```tsx
|
||||
// Combine filtered common tags with newly fetched dynamic tags, removing duplicates
|
||||
const filteredCommon = searchText
|
||||
? COMMON_TAGS.filter(t => t.toLowerCase().includes(searchText.toLowerCase()))
|
||||
: COMMON_TAGS;
|
||||
|
||||
const renderedTags = Array.from(new Set([...filteredCommon, ...dynamicTags]));
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Add loading indicator to the search input area**
|
||||
|
||||
Look for the `<input>` element for `searchText` and wrap it/add a loading indicator:
|
||||
|
||||
```tsx
|
||||
<div style={{ position: "relative" }}>
|
||||
<input
|
||||
style={{
|
||||
width: "100%",
|
||||
padding: "8px",
|
||||
paddingRight: "24px",
|
||||
backgroundColor: "rgba(0,0,0,0.3)",
|
||||
color: "#fff",
|
||||
border: "1px solid var(--border-subtle)",
|
||||
borderRadius: "4px",
|
||||
fontSize: "13px"
|
||||
}}
|
||||
placeholder="Filter or search OSM for tags..."
|
||||
value={searchText}
|
||||
onChange={e => setSearchText(e.target.value)}
|
||||
/>
|
||||
{isSearchingApi && (
|
||||
<span style={{
|
||||
position: "absolute",
|
||||
right: "8px",
|
||||
top: "50%",
|
||||
transform: "translateY(-50%)",
|
||||
fontSize: "10px",
|
||||
color: "var(--text-muted)"
|
||||
}}>
|
||||
⏳
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-plugin-osm-search/src/components/OSMSidebar.tsx
|
||||
git commit -m "feat(osm-search): add live Taginfo autocomplete for unlisted tags"
|
||||
```
|
||||
@@ -1,139 +0,0 @@
|
||||
# Plugin Versioning Streamlining Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Refactor all WorldWideView plugin classes to derive their `version` property dynamically from their local `package.json` file rather than hardcoding string literals.
|
||||
|
||||
**Architecture:** We will replace the hardcoded `version = "x.y.z"` strings in the core `WorldPlugin` interface implementations across all monorepo packages. We will utilize TypeScript's JSON module resolution feature to `import pkg from "../package.json"` and map `version = pkg.version`. This ensures that `pnpm version patch` is the single source of truth and eliminates the double-bookkeeping that previously made CI fixes tedious.
|
||||
|
||||
**Tech Stack:** TypeScript, Next.js / bundler (JSON module resolution), pnpm workspaces.
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Verify TypeScript Configuration
|
||||
|
||||
**Files:**
|
||||
- Modify: N/A (Verification step)
|
||||
|
||||
- [ ] **Step 1: Check `tsconfig.json` for JSON resolution**
|
||||
|
||||
Run: `cat tsconfig.json | grep resolveJsonModule`
|
||||
Expected: `"resolveJsonModule": true`
|
||||
|
||||
- [ ] **Step 2: Check compiler compatibility**
|
||||
|
||||
Run: `pnpm exec tsc --noEmit`
|
||||
Expected: PASS (exit code 0)
|
||||
|
||||
## Task 2: Refactor Group A Plugins (Core Infrastructure)
|
||||
|
||||
**Files:**
|
||||
- Modify: `packages/wwv-plugin-aviation/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-maritime/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-military-aviation/src/index.ts`
|
||||
|
||||
- [ ] **Step 1: Update plugin classes**
|
||||
|
||||
For each file above, modify the imports and the class body:
|
||||
|
||||
```typescript
|
||||
import pkg from "../package.json";
|
||||
// ...
|
||||
export class AviationPlugin implements WorldPlugin { // (or extends BasePlugin)
|
||||
// ...
|
||||
version = pkg.version;
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify compilation**
|
||||
|
||||
Run: `pnpm exec tsc --noEmit`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git commit -am "refactor(plugins): derive version dynamically for core infrastructure plugins [Patch]"
|
||||
```
|
||||
|
||||
## Task 3: Refactor Group B Plugins (Facilities & Infrastructure)
|
||||
|
||||
**Files:**
|
||||
- Modify: `packages/wwv-plugin-airports/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-seaports/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-spaceports/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-embassies/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-lighthouses/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-nuclear/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-undersea-cables/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-mineral-mines/src/index.ts`
|
||||
|
||||
- [ ] **Step 1: Update plugin classes**
|
||||
|
||||
For each file above, replace `version = "..."` with `version = pkg.version` and add `import pkg from "../package.json";`.
|
||||
|
||||
- [ ] **Step 2: Verify compilation**
|
||||
|
||||
Run: `pnpm exec tsc --noEmit`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git commit -am "refactor(plugins): derive version dynamically for facility plugins [Patch]"
|
||||
```
|
||||
|
||||
## Task 4: Refactor Group C Plugins (Hazards & Events)
|
||||
|
||||
**Files:**
|
||||
- Modify: `packages/wwv-plugin-earthquakes/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-volcanoes/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-wildfire/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-conflict-events/src/index.tsx`
|
||||
- Modify: `packages/wwv-plugin-conflict-zones/src/index.tsx`
|
||||
- Modify: `packages/wwv-plugin-civil-unrest/src/index.tsx`
|
||||
- Modify: `packages/wwv-plugin-cyber-attacks/src/index.tsx`
|
||||
- Modify: `packages/wwv-plugin-international-sanctions/src/index.tsx`
|
||||
|
||||
- [ ] **Step 1: Update plugin classes**
|
||||
|
||||
For each file above, replace `version = "..."` with `version = pkg.version` and add `import pkg from "../package.json";`. Note that some files are `.tsx`.
|
||||
|
||||
- [ ] **Step 2: Verify compilation**
|
||||
|
||||
Run: `pnpm exec tsc --noEmit`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git commit -am "refactor(plugins): derive version dynamically for event and hazard plugins [Patch]"
|
||||
```
|
||||
|
||||
## Task 5: Refactor Group D Plugins (Misc & Utilities)
|
||||
|
||||
**Files:**
|
||||
- Modify: `packages/wwv-plugin-satellite/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-surveillance-satellites/src/index.tsx`
|
||||
- Modify: `packages/wwv-plugin-osm-search/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-iranwarlive/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-daynight/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-camera/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-borders/src/index.ts`
|
||||
- Modify: `packages/wwv-plugin-gps-jamming/src/index.tsx`
|
||||
- Modify: `packages/wwv-plugin-air-defense/src/index.tsx`
|
||||
|
||||
- [ ] **Step 1: Update plugin classes**
|
||||
|
||||
For each file above, replace `version = "..."` with `version = pkg.version` and add `import pkg from "../package.json";`.
|
||||
|
||||
- [ ] **Step 2: Verify compilation and tests**
|
||||
|
||||
Run: `pnpm exec tsc --noEmit`
|
||||
Run: `pnpm test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git commit -am "refactor(plugins): derive version dynamically for utility plugins [Patch]"
|
||||
```
|
||||
@@ -1,124 +0,0 @@
|
||||
# Demo Default Plugins Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Enable specific plugins by default on the demo edition via environment variables so the user is immediately impressed.
|
||||
|
||||
**Architecture:** Update `layersSlice.ts` to accept an optional `defaultEnabled` parameter in `initLayer`. In `AppShell.tsx`, look up `NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS` when the edition is `demo`, and pass the flag true to `initLayer` for matching plugins during registration. Document the variable in `.env.example`.
|
||||
|
||||
**Tech Stack:** Next.js, Zustand, TypeScript.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Update layer slice definition
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/core/state/layersSlice.ts`
|
||||
|
||||
- [ ] **Step 1: Write the implementation**
|
||||
|
||||
Update `initLayer` in `src/core/state/layersSlice.ts` to accept a second parameter:
|
||||
|
||||
```typescript
|
||||
// Add defaultEnabled parameter to the interface
|
||||
export interface LayersSlice {
|
||||
// ...
|
||||
initLayer: (pluginId: string, defaultEnabled?: boolean) => void;
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
// Use the parameter in the state updater
|
||||
initLayer: (pluginId, defaultEnabled = false) =>
|
||||
set((state) => ({
|
||||
layers: {
|
||||
...state.layers,
|
||||
[pluginId]: state.layers[pluginId] || { enabled: defaultEnabled, entityCount: 0, loading: false },
|
||||
},
|
||||
})),
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add src/core/state/layersSlice.ts
|
||||
npm run commit -- "feat: add defaultEnabled param to initLayer in layers slice"
|
||||
```
|
||||
|
||||
### Task 2: Apply default configuration in AppShell
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/components/layout/AppShell.tsx`
|
||||
|
||||
- [ ] **Step 1: Write the implementation**
|
||||
|
||||
Add `isDemo` import at the top of `src/components/layout/AppShell.tsx`:
|
||||
|
||||
```typescript
|
||||
import { isDemo } from "@/core/edition";
|
||||
```
|
||||
|
||||
In `AppShell.tsx`, around line 71, inside `startPlatform()`, fetch the value from the environment if the instance is demo:
|
||||
|
||||
```typescript
|
||||
// Fetch disabled built-in plugins before registration
|
||||
let disabledIds = new Set<string>();
|
||||
// ... (keep existing try/catch block)
|
||||
|
||||
// Setup demo defaults
|
||||
const demoDefaultPlugins = new Set<string>();
|
||||
if (isDemo) {
|
||||
const envVar = process.env.NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS || "";
|
||||
envVar.split(",").forEach(s => {
|
||||
const clean = s.trim();
|
||||
if (clean) demoDefaultPlugins.add(clean);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
Then update the `pluginManager` registration loop to inject the boolean for `initLayer`:
|
||||
|
||||
```typescript
|
||||
for (const plugin of pluginRegistry.getAll()) {
|
||||
await pluginManager.registerPlugin(plugin);
|
||||
initLayer(plugin.id, demoDefaultPlugins.has(plugin.id));
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it passes**
|
||||
|
||||
Run type checks to verify no compilation issues:
|
||||
`npx tsc --noEmit`
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add src/components/layout/AppShell.tsx
|
||||
npm run commit -- "feat: parse and apply default demo plugins via NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS"
|
||||
```
|
||||
|
||||
### Task 3: Document environment definitions
|
||||
|
||||
**Files:**
|
||||
- Modify: `.env.example`
|
||||
- Modify: `.env`
|
||||
|
||||
- [ ] **Step 1: Write the implementation**
|
||||
|
||||
Update `.env.example` and `.env` around the `NEXT_PUBLIC_WWV_EDITION=local` definition:
|
||||
|
||||
```dotenv
|
||||
# Default plugins enabled on boot for demo edition
|
||||
# Comma-separated list of plugin IDs (e.g. aviation,maritime,iranwarlive)
|
||||
NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS=
|
||||
|
||||
# Edition: "local" | "cloud" | "demo"
|
||||
NEXT_PUBLIC_WWV_EDITION=local
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add .env.example .env
|
||||
npm run commit -- "docs: add NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS to env templates"
|
||||
```
|
||||
@@ -1,177 +0,0 @@
|
||||
# Decouple Plugin Proxies Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Strip out hardcoded proxy endpoints from the `worldwideview` core repository to enforce a fully decoupled plugin ecosystem, replacing them with direct browser fetching or a universal CORS proxy.
|
||||
|
||||
**Architecture:** Remove preferential API routes (`/api/earthquake`, `/api/undersea-cables`, `/api/camera/*`) from the `worldwideview` core app. Promote the existing camera proxy to a universal `/api/proxy` with strict SSRF defenses. Provide direct browser-fetch code for the `wwv-plugin-earthquakes` where CORS permits, and migrate traffic camera fetchers directly into the `wwv-plugin-camera` package to fetch via the universal proxy.
|
||||
|
||||
**Tech Stack:** Next.js 16 (App Router), TypeScript, pnpm workspace
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Promote Universal Proxy in Core Repository
|
||||
|
||||
**Files:**
|
||||
- Create (Move): `src/app/api/proxy/route.ts`
|
||||
- Delete: `src/app/api/camera/proxy/route.ts`
|
||||
|
||||
- [ ] **Step 1: Relocate the proxy route and update logs**
|
||||
|
||||
Move the existing camera proxy to act as a system-wide universal proxy.
|
||||
|
||||
Run: `mkdir -p src/app/api/proxy`
|
||||
Run: `mv src/app/api/camera/proxy/route.ts src/app/api/proxy/route.ts`
|
||||
|
||||
- [ ] **Step 2: Update the error logging prefix in the new file**
|
||||
|
||||
Modify `src/app/api/proxy/route.ts` near line 97:
|
||||
|
||||
```json
|
||||
{
|
||||
"instruction": "Update the error logging prefix",
|
||||
"replace_chunks": [
|
||||
{
|
||||
"start_line": 96,
|
||||
"end_line": 98,
|
||||
"target_content": " } catch (error: any) {\n console.error(\"[CameraProxy] Error fetching target URL:\", error);\n return NextResponse.json(",
|
||||
"replacement_content": " } catch (error: any) {\n console.error(\"[UniversalProxy] Error fetching target URL:\", error);\n return NextResponse.json("
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Commit the Universal Proxy**
|
||||
|
||||
```bash
|
||||
git add src/app/api/proxy/route.ts src/app/api/camera/proxy/route.ts
|
||||
git commit -m "refactor: promote camera proxy to universal proxy"
|
||||
```
|
||||
|
||||
### Task 2: Strip Preferential Proxy Routes From Core Application
|
||||
|
||||
**Files:**
|
||||
- Delete: `src/app/api/earthquake/route.ts`
|
||||
- Delete: `src/app/api/undersea-cables/route.ts`
|
||||
- Delete: everything in `src/app/api/camera` codebase (`caltrans`, `extract`, `gdot`, `test`, `tfl`, `traffic`)
|
||||
|
||||
- [ ] **Step 1: Delete all plugin-specific Next.js API routes**
|
||||
|
||||
Run: `rm -rf src/app/api/earthquake`
|
||||
Run: `rm -rf src/app/api/undersea-cables`
|
||||
|
||||
**WAIT**: For `src/app/api/camera`, we must physically copy the fetchers into `worldwideview-plugins` before we delete them.
|
||||
|
||||
Run: `cp -r src/app/api/camera/caltrans ../worldwideview-plugins/packages/wwv-plugin-camera/src/`
|
||||
Run: `cp -r src/app/api/camera/gdot ../worldwideview-plugins/packages/wwv-plugin-camera/src/`
|
||||
Run: `cp -r src/app/api/camera/tfl ../worldwideview-plugins/packages/wwv-plugin-camera/src/`
|
||||
Run: `rm -rf src/app/api/camera`
|
||||
|
||||
- [ ] **Step 2: Commit the deleted API routes**
|
||||
|
||||
```bash
|
||||
git add src/app/api/earthquake src/app/api/undersea-cables src/app/api/camera
|
||||
git commit -m "refactor!: strip preferential plugin APIs from core"
|
||||
```
|
||||
|
||||
### Task 3: Migrate Earthquakes and Undersea Cables Plugins
|
||||
|
||||
**Files:**
|
||||
- Modify: `../worldwideview-plugins/packages/wwv-plugin-earthquakes/src/index.ts`
|
||||
- Modify: `../worldwideview-plugins/packages/wwv-plugin-undersea-cables/src/index.ts`
|
||||
|
||||
- [ ] **Step 1: Update Earthquakes plugin to direct browser fetch (Option A)**
|
||||
|
||||
In `../worldwideview-plugins/packages/wwv-plugin-earthquakes/src/index.ts`, replace the `/api/earthquake` fetch with the USGS direct URL.
|
||||
|
||||
```json
|
||||
{
|
||||
"instruction": "Replace the API fetch with direct USGS fetch and remove apiBasePath",
|
||||
"replace_chunks": [
|
||||
{
|
||||
"start_line": 38,
|
||||
"end_line": 40,
|
||||
"target_content": " try {\n const res = await globalThis.fetch(`/api/earthquake`);\n if (!res.ok) {",
|
||||
"replacement_content": " try {\n const res = await globalThis.fetch(`https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson`);\n if (!res.ok) {"
|
||||
},
|
||||
{
|
||||
"start_line": 94,
|
||||
"end_line": 96,
|
||||
"target_content": " getServerConfig(): ServerPluginConfig {\n return { apiBasePath: \"/api/earthquake\", pollingIntervalMs: 120000, historyEnabled: false };\n }",
|
||||
"replacement_content": " getServerConfig(): ServerPluginConfig {\n return { pollingIntervalMs: 120000, historyEnabled: false };\n }"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update Undersea Cables plugin to use Universal Proxy (Option B)**
|
||||
|
||||
In `../worldwideview-plugins/packages/wwv-plugin-undersea-cables/src/index.ts`:
|
||||
|
||||
```json
|
||||
{
|
||||
"instruction": "Proxy route to universal proxy",
|
||||
"replace_chunks": [
|
||||
{
|
||||
"start_line": 35,
|
||||
"end_line": 37,
|
||||
"target_content": " // Proxy route to bypass CORS for Telegeography submarine cable map API\n const url = \"/api/undersea-cables\";\n ",
|
||||
"replacement_content": " // Proxy route to bypass CORS for Telegeography submarine cable map API\n const targetUrl = encodeURIComponent(\"https://www.submarinecablemap.com/api/v3/cable/cable-geo.json\");\n const url = `/api/proxy?url=${targetUrl}`;\n "
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Commit the plugin migrations**
|
||||
|
||||
```bash
|
||||
cd ../worldwideview-plugins
|
||||
git add packages/wwv-plugin-earthquakes/src/index.ts packages/wwv-plugin-undersea-cables/src/index.ts
|
||||
git commit -m "refactor: transition earthquake and undersea cables to decoupled fetching"
|
||||
cd ../worldwideview
|
||||
```
|
||||
|
||||
### Task 4: Refactor Camera Plugin to Fetch Natively
|
||||
|
||||
**Files:**
|
||||
- Modify: `../worldwideview-plugins/packages/wwv-plugin-camera/src/index.ts`
|
||||
- Delete: `caltrans`, `gdot`, `tfl` previously copied components (combine into `trafficFetchers.ts`)
|
||||
|
||||
- [ ] **Step 1: Consolidate the camera fetchers**
|
||||
|
||||
Create `../worldwideview-plugins/packages/wwv-plugin-camera/src/trafficFetchers.ts`.
|
||||
Migrate the code from the `caltransFetcher.ts`, `gdotFetcher.ts`, and `tflFetcher.ts` files that we copied in Task 2.
|
||||
Crucially, when doing `fetch(...)` in these fetchers, if the endpoint doesn't support CORS, wrap it in `/api/proxy?url=${encodeURIComponent(...) }` so the browser can fetch it. Ensure the data models align.
|
||||
|
||||
- [ ] **Step 2: Update `wwv-plugin-camera/src/index.ts` to call the fetchers natively**
|
||||
|
||||
In `../worldwideview-plugins/packages/wwv-plugin-camera/src/index.ts` function `loadTrafficCameras()`:
|
||||
|
||||
```json
|
||||
{
|
||||
"instruction": "Replace API fetch with native client-side parallel fetching",
|
||||
"replace_chunks": [
|
||||
{
|
||||
"start_line": 106,
|
||||
"end_line": 118,
|
||||
"target_content": " private async loadTrafficCameras(): Promise<void> {\n try {\n const res = await fetch(\"/api/camera/traffic\");\n if (!res.ok) throw new Error(`API returned ${res.status}`);\n const data = await res.json();\n if (data.cameras && Array.isArray(data.cameras)) {\n this.sourceBuckets[\"default\"] = data.cameras.map(\n (f: unknown, i: number) => mapGeoJsonFeature(f, i, \"traffic\"),\n );\n }\n } catch (err) {\n console.warn(\"[CameraPlugin] Traffic cameras API failed:\", err);\n }",
|
||||
"replacement_content": " private async loadTrafficCameras(): Promise<void> {\n try {\n const { fetchCaltrans, fetchGdot, fetchTfl } = await import(\"./trafficFetchers\");\n const [caltrans, gdot, tfl] = await Promise.allSettled([\n fetchCaltrans(), fetchGdot(), fetchTfl()\n ]);\n \n const cameras = [];\n if (caltrans.status === \"fulfilled\") cameras.push(...caltrans.value);\n if (gdot.status === \"fulfilled\") cameras.push(...gdot.value);\n if (tfl.status === \"fulfilled\") cameras.push(...tfl.value);\n\n if (cameras.length > 0) {\n this.sourceBuckets[\"default\"] = cameras.map(\n (f: unknown, i: number) => mapGeoJsonFeature(f, i, \"traffic\"),\n );\n }\n } catch (err) {\n console.warn(\"[CameraPlugin] Traffic cameras API failed:\", err);\n }"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Remove the extra node API files from the plugin source tree**
|
||||
|
||||
Run: `rm -rf ../worldwideview-plugins/packages/wwv-plugin-camera/src/caltrans`
|
||||
Run: `rm -rf ../worldwideview-plugins/packages/wwv-plugin-camera/src/gdot`
|
||||
Run: `rm -rf ../worldwideview-plugins/packages/wwv-plugin-camera/src/tfl`
|
||||
|
||||
- [ ] **Step 4: Commit Camera plugin refactoring**
|
||||
|
||||
```bash
|
||||
cd ../worldwideview-plugins
|
||||
git add packages/wwv-plugin-camera/src
|
||||
git commit -m "feat: migrate traffic camera fetchers to client-side plugin bundle"
|
||||
cd ../worldwideview
|
||||
```
|
||||
@@ -1,118 +0,0 @@
|
||||
# Persistent Custom OSM Tags Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Allow users to persistently save custom OSM tags to local storage so they remain available across sessions, and track their usage via Umami analytics.
|
||||
|
||||
**Architecture:** We will use `useState` and `useEffect` in the `OSMSidebar` component to sync `customTags` to the browser's `localStorage`. When the user enters a custom tag, we'll store it, render it with a small delete button (so the list doesn't get cluttered over time), and fire an event to `window.umami.track`.
|
||||
|
||||
**Tech Stack:** React Hooks, `localStorage`, Umami Analytics
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Add Custom Tag State and Persistence
|
||||
|
||||
**Files:**
|
||||
- Modify: `c:\dev\worldwideview-plugins\packages\wwv-plugin-osm-search\src\components\OSMSidebar.tsx`
|
||||
|
||||
- [ ] **Step 1: Add customTags state and persistence effects**
|
||||
|
||||
In `OSMSidebar.tsx`, below the existing `const [activeTags, setActiveTags] = useState<string[]>([]);` line, add:
|
||||
|
||||
```tsx
|
||||
const [customTags, setCustomTags] = useState<string[]>([]);
|
||||
|
||||
React.useEffect(() => {
|
||||
try {
|
||||
const saved = localStorage.getItem("wwv_osm_custom_tags");
|
||||
if (saved) setCustomTags(JSON.parse(saved));
|
||||
} catch {}
|
||||
}, []);
|
||||
|
||||
React.useEffect(() => {
|
||||
localStorage.setItem("wwv_osm_custom_tags", JSON.stringify(customTags));
|
||||
}, [customTags]);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Include customTags in the rendered list**
|
||||
|
||||
Replace `const customTagMatch = searchText.includes("=") ? [searchText.trim()] : [];` and `const renderedTags = ...` with:
|
||||
|
||||
```tsx
|
||||
const renderedTags = Array.from(new Set([...filteredCommon, ...dynamicTags, ...customTags]));
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Update Enter key handler to save tags and track**
|
||||
|
||||
Inside the `input`'s `onKeyDown` handler:
|
||||
|
||||
```tsx
|
||||
onKeyDown={e => {
|
||||
if (e.key === "Enter" && searchText.includes("=")) {
|
||||
const tag = searchText.trim();
|
||||
if (!activeTags.includes(tag)) {
|
||||
setActiveTags(prev => [...prev, tag]);
|
||||
}
|
||||
if (!customTags.includes(tag)) {
|
||||
setCustomTags(prev => [...prev, tag]);
|
||||
try {
|
||||
(window as any).umami?.track("osm-search-custom-tag", { tag });
|
||||
} catch {}
|
||||
}
|
||||
setSearchText("");
|
||||
}
|
||||
}}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Add a delete button to custom tags**
|
||||
|
||||
Inside the `.map(tag => {` block, update the `button` contents to include a delete span if it's a custom tag:
|
||||
|
||||
```tsx
|
||||
<button
|
||||
key={tag}
|
||||
style={{
|
||||
background: isActive ? "var(--accent-blue)" : "rgba(255,255,255,0.05)",
|
||||
color: isActive ? "#fff" : "var(--text-secondary)",
|
||||
padding: "4px 10px",
|
||||
borderRadius: "14px",
|
||||
border: `1px solid ${isActive ? "transparent" : "rgba(255,255,255,0.1)"}`,
|
||||
fontSize: "11px",
|
||||
cursor: "pointer",
|
||||
transition: "all 0.2s",
|
||||
display: "flex",
|
||||
alignItems: "center",
|
||||
gap: "4px"
|
||||
}}
|
||||
onClick={() => setActiveTags(prev => prev.includes(tag) ? prev.filter(t=>t!==tag) : [...prev, tag])}
|
||||
>
|
||||
{tag.replace("=", ": ")}
|
||||
{customTags.includes(tag) && (
|
||||
<span
|
||||
onClick={(e) => {
|
||||
e.stopPropagation();
|
||||
setCustomTags(prev => prev.filter(t => t !== tag));
|
||||
setActiveTags(prev => prev.filter(t => t !== tag));
|
||||
}}
|
||||
style={{
|
||||
marginLeft: "2px",
|
||||
padding: "0 4px",
|
||||
borderRadius: "50%",
|
||||
background: "rgba(255,255,255,0.15)",
|
||||
display: "flex",
|
||||
justifyContent: "center",
|
||||
alignItems: "center"
|
||||
}}
|
||||
>
|
||||
×
|
||||
</span>
|
||||
)}
|
||||
</button>
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Commit changes**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-plugin-osm-search/src/components/OSMSidebar.tsx
|
||||
git commit -m "feat(osm-search): persist custom tags and track via umami"
|
||||
```
|
||||
@@ -1,132 +0,0 @@
|
||||
# Robust Plugin Linking Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Ensure that when developers link local plugins using `wwv-cli link`, the main engine's database is automatically updated to prioritize the local code instead of accidentally loading the published version from the cloud CDN.
|
||||
|
||||
**Architecture:** We will implement a dedicated development API route in the main app (`/api/plugins/dev-link`) that allows the `wwv-cli` to safely push local plugin manifests directly into the `InstalledPlugin` database table without requiring Marketplace authentication. The CLI will be updated to make this request immediately after copying the bundle.
|
||||
|
||||
**Tech Stack:** Next.js API Routes, Prisma, Node.js `fetch`
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Create the Dev-Link API Route
|
||||
|
||||
**Files:**
|
||||
- Create: `c:\dev\worldwideview\src\app\api\plugins\dev-link\route.ts`
|
||||
|
||||
- [ ] **Step 1: Write the API Route**
|
||||
|
||||
```typescript
|
||||
import { NextResponse } from "next/server";
|
||||
import { upsertPlugin } from "@/lib/marketplace/repository";
|
||||
import { validateManifest } from "@/core/plugins/validateManifest";
|
||||
import { isPluginInstallEnabled } from "@/core/edition";
|
||||
|
||||
export async function POST(request: Request) {
|
||||
// 1. Security Check: Only allow in development mode or local editions
|
||||
if (process.env.NODE_ENV !== "development" && !isPluginInstallEnabled) {
|
||||
return NextResponse.json({ error: "Dev-link is only available in development environments" }, { status: 403 });
|
||||
}
|
||||
|
||||
try {
|
||||
const body = await request.json();
|
||||
const { manifest } = body;
|
||||
|
||||
if (!manifest || !manifest.id) {
|
||||
return NextResponse.json({ error: "Invalid payload. 'manifest' with an 'id' is required." }, { status: 400 });
|
||||
}
|
||||
|
||||
// 2. Validate the manifest
|
||||
const validation = validateManifest(manifest);
|
||||
if (!validation.valid) {
|
||||
console.error(`[Dev-Link] Invalid manifest for ${manifest.id}:`, validation.errors);
|
||||
return NextResponse.json({ error: "Invalid manifest", details: validation.errors }, { status: 400 });
|
||||
}
|
||||
|
||||
// 3. Upsert into database
|
||||
const config = JSON.stringify(manifest);
|
||||
const record = await upsertPlugin(manifest.id, manifest.version || "1.0.0", config);
|
||||
|
||||
console.log(`[Dev-Link] Successfully synced local plugin config for: ${manifest.id}`);
|
||||
|
||||
return NextResponse.json({ success: true, pluginId: record.pluginId });
|
||||
} catch (err) {
|
||||
console.error("[Dev-Link] Server Error:", err);
|
||||
return NextResponse.json({ error: "Internal server error" }, { status: 500 });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit API Route**
|
||||
|
||||
```bash
|
||||
git add src/app/api/plugins/dev-link/route.ts
|
||||
git commit -m "feat(api): add dev-link route to sync local plugin manifests"
|
||||
```
|
||||
|
||||
### Task 2: Update the CLI Link Command
|
||||
|
||||
**Files:**
|
||||
- Modify: `c:\dev\worldwideview-plugins\packages\wwv-cli\src\commands\link.ts`
|
||||
|
||||
- [ ] **Step 1: Add the sync request to linkCommand**
|
||||
|
||||
Find the `linkCommand` function. Below the `fs.writeFileSync` that writes `plugin.json` (around line 67), add a network request to sync the database.
|
||||
|
||||
```typescript
|
||||
fs.writeFileSync(path.join(finalDestDir, 'plugin.json'), JSON.stringify(manifest, null, 2));
|
||||
console.log(green(`✅ Proxy manifest injected to WWV instance: ${pluginId}`));
|
||||
|
||||
// --- NEW CODE: Sync with database ---
|
||||
fetch('http://localhost:3000/api/plugins/dev-link', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ manifest })
|
||||
})
|
||||
.then(res => res.json())
|
||||
.then(data => {
|
||||
if (data.success) {
|
||||
console.log(green(`✅ Database successfully synced to point to local files.`));
|
||||
} else {
|
||||
console.log(red(`⚠️ Warning: Database sync failed: ${data.error}`));
|
||||
}
|
||||
})
|
||||
.catch(err => {
|
||||
console.log(red(`⚠️ Warning: Could not reach dev server to sync DB. Is localhost:3000 running?`));
|
||||
});
|
||||
// --- END NEW CODE ---
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Rebuild the CLI**
|
||||
|
||||
```bash
|
||||
cd packages/wwv-cli
|
||||
pnpm build
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Commit CLI Update**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli/src/commands/link.ts
|
||||
git commit -m "feat(cli): auto-sync local plugin manifests with engine database during link"
|
||||
```
|
||||
|
||||
### Task 3: Test the Integration
|
||||
|
||||
- [ ] **Step 1: Run the Sync Command**
|
||||
|
||||
Run the updated sync command in the plugins repo to verify it pushes the manifest properly to the API.
|
||||
|
||||
```bash
|
||||
cd c:\dev\worldwideview-plugins
|
||||
pnpm run sync:all
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify Output**
|
||||
|
||||
Expected output in the plugins terminal should include:
|
||||
`[wwv-plugin-osm-search] ✅ Database successfully synced to point to local files.`
|
||||
|
||||
Expected output in the main WorldWideView terminal should include:
|
||||
`[Dev-Link] Successfully synced local plugin config for: osm-search`
|
||||
@@ -1,105 +0,0 @@
|
||||
# Phase 1: Database Adapter Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Modify Prisma schema and client initialization to support both SQLite (local/demo) and PostgreSQL (cloud).
|
||||
|
||||
**Architecture:** We use a pre-generation script to swap the Prisma provider based on `NEXT_PUBLIC_WWV_EDITION`. Abstract `src/lib/db.ts` to inject the correct adapter (better-sqlite3 vs pg) based on the edition.
|
||||
|
||||
**Tech Stack:** Prisma, PostgreSQL, SQLite.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Create Schema Swap Script
|
||||
|
||||
**Files:**
|
||||
- Create: `scripts/prepare-schema.mjs`
|
||||
- Modify: `package.json`
|
||||
|
||||
- [ ] **Step 1: Create a schema swap script**
|
||||
|
||||
```javascript
|
||||
// scripts/prepare-schema.mjs
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
|
||||
const schemaPath = path.join(process.cwd(), 'prisma', 'schema.prisma');
|
||||
let schema = fs.readFileSync(schemaPath, 'utf-8');
|
||||
|
||||
if (process.env.NEXT_PUBLIC_WWV_EDITION === 'cloud') {
|
||||
schema = schema.replace(/provider\s*=\s*"sqlite"/, 'provider = "postgresql"');
|
||||
console.log("Swapped Prisma provider to PostgreSQL for cloud edition.");
|
||||
} else {
|
||||
// Revert back to sqlite just in case it was swapped
|
||||
schema = schema.replace(/provider\s*=\s*"postgresql"/, 'provider = "sqlite"');
|
||||
}
|
||||
|
||||
fs.writeFileSync(schemaPath, schema);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update package.json scripts**
|
||||
|
||||
Modify `package.json` to run the prepare script before prisma generate:
|
||||
```json
|
||||
"pregenerate": "node scripts/prepare-schema.mjs",
|
||||
"generate": "prisma generate"
|
||||
```
|
||||
|
||||
### Task 2: Create DB Adapter Factory
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/lib/db.ts`
|
||||
- Create: `src/core/adapters/db.ts`
|
||||
|
||||
- [ ] **Step 1: Create the adapter factory**
|
||||
|
||||
```typescript
|
||||
// src/core/adapters/db.ts
|
||||
import { isCloud } from "@/core/edition";
|
||||
import { PrismaClient } from "../../generated/prisma/client";
|
||||
|
||||
export function createPrismaClient(): PrismaClient {
|
||||
if (isCloud) {
|
||||
// Cloud uses native pg driver or connection pool via standard url
|
||||
return new PrismaClient({
|
||||
datasources: {
|
||||
db: {
|
||||
url: process.env.DATABASE_URL,
|
||||
},
|
||||
},
|
||||
});
|
||||
} else {
|
||||
// Local uses better-sqlite3 adapter (already set up)
|
||||
const { PrismaBetterSqlite3 } = require("@prisma/adapter-better-sqlite3");
|
||||
const adapter = new PrismaBetterSqlite3({
|
||||
url: process.env.DATABASE_URL || "file:./data/wwv.db",
|
||||
});
|
||||
return new PrismaClient({ adapter });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Refactor `src/lib/db.ts`**
|
||||
|
||||
```typescript
|
||||
// src/lib/db.ts
|
||||
import { PrismaClient } from "../generated/prisma/client";
|
||||
import { createPrismaClient } from "@/core/adapters/db";
|
||||
|
||||
const globalForPrisma = globalThis as unknown as {
|
||||
prisma: PrismaClient | undefined;
|
||||
};
|
||||
|
||||
export const prisma = globalForPrisma.prisma ?? createPrismaClient();
|
||||
|
||||
if (process.env.NODE_ENV !== "production") {
|
||||
globalForPrisma.prisma = prisma;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add package.json scripts/ src/lib/ src/core/adapters/
|
||||
git commit -m "feat: multi-provider database adapter for cloud"
|
||||
```
|
||||
@@ -1,152 +0,0 @@
|
||||
# Phase 2: Tenant System Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Implement single-container multi-tenancy using PostgreSQL Row-Level Security (RLS) and Next.js middleware to resolve subdomains.
|
||||
|
||||
**Architecture:** Middleware extracts the subdomain (e.g., `acme.app.worldwideview.dev`) and sets an `x-tenant-id` header. Prisma extension wraps all queries to `SET LOCAL app.tenant_id = '...'` to enforce RLS in PostgreSQL.
|
||||
|
||||
**Tech Stack:** Next.js Middleware, Prisma Client Extensions, PostgreSQL RLS.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Database Schema Tenant Column
|
||||
|
||||
**Files:**
|
||||
- Modify: `prisma/schema.prisma`
|
||||
|
||||
- [ ] **Step 1: Add tenant columns to models**
|
||||
|
||||
Add `tenantId String?` to all relevant models (`InstalledPlugin`, `Favorite`, `Setting`).
|
||||
For local SQLite, `tenantId` is ignored (null). For cloud, it's enforced via RLS.
|
||||
|
||||
```prisma
|
||||
model InstalledPlugin {
|
||||
id String @id @default(uuid())
|
||||
tenantId String? // NULL for local, UUID for cloud
|
||||
pluginId String
|
||||
version String
|
||||
config String @default("{}")
|
||||
enabled Boolean @default(true)
|
||||
installedAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
|
||||
@@unique([tenantId, pluginId]) // Replaces @@unique([pluginId])
|
||||
@@map("installed_plugins")
|
||||
}
|
||||
|
||||
model Setting {
|
||||
id String @id @default(uuid())
|
||||
tenantId String?
|
||||
key String
|
||||
value String
|
||||
|
||||
@@unique([tenantId, key])
|
||||
@@map("settings")
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update primary keys if needed**
|
||||
|
||||
Ensure `Setting` uses `id` as `@id` instead of `key` since `key` is no longer globally unique (it's unique per tenant).
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add prisma/schema.prisma
|
||||
git commit -m "feat: add tenantId columns to schema"
|
||||
```
|
||||
|
||||
### Task 2: Subdomain Middleware
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/middleware.ts` (or create if doesn't exist)
|
||||
|
||||
- [ ] **Step 1: Create Next.js middleware**
|
||||
|
||||
```typescript
|
||||
// src/middleware.ts
|
||||
import { NextResponse } from "next/server";
|
||||
import type { NextRequest } from "next/server";
|
||||
|
||||
export function middleware(req: NextRequest) {
|
||||
const hostname = req.headers.get("host") || "";
|
||||
|
||||
// Extract subdomain if on cloud
|
||||
if (process.env.NEXT_PUBLIC_WWV_EDITION === "cloud") {
|
||||
const isApp = hostname.includes(".app.worldwideview.dev");
|
||||
if (isApp) {
|
||||
const subdomain = hostname.replace(".app.worldwideview.dev", "");
|
||||
if (subdomain && subdomain !== "app") {
|
||||
const res = NextResponse.next();
|
||||
res.headers.set("x-tenant-subdomain", subdomain);
|
||||
return res;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return NextResponse.next();
|
||||
}
|
||||
|
||||
export const config = {
|
||||
matcher: ["/((?!api/auth|_next/static|_next/image|favicon.ico).*)"],
|
||||
};
|
||||
```
|
||||
|
||||
### Task 3: Prisma RLS Extension
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/core/adapters/db.ts`
|
||||
|
||||
- [ ] **Step 1: Wrap Prisma with RLS extension for Cloud**
|
||||
|
||||
Modify `createPrismaClient` to wrap the client if in cloud mode:
|
||||
|
||||
```typescript
|
||||
// src/core/adapters/db.ts
|
||||
import { isCloud } from "@/core/edition";
|
||||
import { PrismaClient } from "../../generated/prisma/client";
|
||||
import { headers } from "next/headers";
|
||||
|
||||
export function createPrismaClient() {
|
||||
if (isCloud) {
|
||||
const client = new PrismaClient({
|
||||
datasources: { db: { url: process.env.DATABASE_URL } },
|
||||
});
|
||||
|
||||
// Use Prisma Client Extension to inject RLS
|
||||
return client.$extends({
|
||||
query: {
|
||||
$allModels: {
|
||||
async $allOperations({ args, query }) {
|
||||
const headersList = await headers();
|
||||
const tenantSubdomain = headersList.get("x-tenant-subdomain");
|
||||
|
||||
if (tenantSubdomain) {
|
||||
const [, result] = await client.$transaction([
|
||||
client.$executeRaw`SELECT set_config('app.tenant_id', ${tenantSubdomain}, TRUE)`,
|
||||
query(args),
|
||||
]);
|
||||
return result;
|
||||
}
|
||||
return query(args);
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
} else {
|
||||
const { PrismaBetterSqlite3 } = require("@prisma/adapter-better-sqlite3");
|
||||
const adapter = new PrismaBetterSqlite3({
|
||||
url: process.env.DATABASE_URL || "file:./data/wwv.db",
|
||||
});
|
||||
return new PrismaClient({ adapter });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add src/middleware.ts src/core/adapters/db.ts
|
||||
git commit -m "feat: multi-tenant middleware and RLS prisma extension"
|
||||
```
|
||||
@@ -1,117 +0,0 @@
|
||||
# Phase 3: Auth Upgrade Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Integrate Supabase Auth for the cloud edition while maintaining the existing Credentials provider for the local edition.
|
||||
|
||||
**Architecture:** Use the NextAuth adapter pattern. Modify `src/lib/auth.ts` to dynamically include the Supabase provider and Supabase Adapter if `isCloud` is true.
|
||||
|
||||
**Tech Stack:** NextAuth v5, Supabase Auth.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Supabase Adapter Integration
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/lib/auth.ts`
|
||||
- Modify: `package.json`
|
||||
|
||||
- [ ] **Step 1: Install Supabase NextAuth Adapter**
|
||||
|
||||
Run: `pnpm add @auth/supabase-adapter`
|
||||
|
||||
- [ ] **Step 2: Update `src/lib/auth.ts` to branch providers**
|
||||
|
||||
```typescript
|
||||
// src/lib/auth.ts
|
||||
import NextAuth from "next-auth";
|
||||
import Credentials from "next-auth/providers/credentials";
|
||||
import { compareSync } from "bcryptjs";
|
||||
import { timingSafeEqual } from "crypto";
|
||||
import { prisma } from "@/lib/db";
|
||||
import { isDemo, isCloud, getDemoAdminSecret, DEMO_ADMIN_ROLE } from "@/core/edition";
|
||||
import { authConfig } from "@/lib/auth.config";
|
||||
import { SupabaseAdapter } from "@auth/supabase-adapter";
|
||||
|
||||
// Extract local credentials logic to a helper
|
||||
const localCredentialsProvider = Credentials({
|
||||
credentials: {
|
||||
email: { label: "Email", type: "email" },
|
||||
password: { label: "Password", type: "password" },
|
||||
},
|
||||
async authorize(credentials) {
|
||||
// ... existing credentials logic ...
|
||||
return null;
|
||||
}
|
||||
});
|
||||
|
||||
export const { handlers, auth, signIn, signOut } = NextAuth({
|
||||
...authConfig,
|
||||
session: { strategy: "jwt" },
|
||||
adapter: isCloud ? SupabaseAdapter({
|
||||
url: process.env.NEXT_PUBLIC_SUPABASE_URL!,
|
||||
secret: process.env.SUPABASE_SERVICE_ROLE_KEY!,
|
||||
}) : undefined,
|
||||
providers: isCloud
|
||||
? [] // If using standard GoTrue via custom logic, or add providers here if using NextAuth OAuth
|
||||
: [localCredentialsProvider],
|
||||
callbacks: {
|
||||
...authConfig.callbacks,
|
||||
// ... existing callbacks ...
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Task 2: Login Form Cloud Adaptation
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/app/login/page.tsx`
|
||||
- Modify: `src/app/login/actions.ts`
|
||||
|
||||
- [ ] **Step 1: Update Login Form for Cloud Mode**
|
||||
|
||||
```typescript
|
||||
// src/app/login/actions.ts
|
||||
import { signIn } from "@/lib/auth";
|
||||
import { isCloud } from "@/core/edition";
|
||||
import { createClient } from "@supabase/supabase-js";
|
||||
|
||||
export async function loginAction(formData: FormData) {
|
||||
const email = formData.get("email") as string;
|
||||
const password = formData.get("password") as string;
|
||||
|
||||
if (isCloud) {
|
||||
// Use Supabase GoTrue
|
||||
const supabase = createClient(
|
||||
process.env.NEXT_PUBLIC_SUPABASE_URL!,
|
||||
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
|
||||
);
|
||||
const { data, error } = await supabase.auth.signInWithPassword({
|
||||
email,
|
||||
password,
|
||||
});
|
||||
|
||||
if (error) return { success: false, error: error.message };
|
||||
return { success: true };
|
||||
} else {
|
||||
// Use NextAuth Credentials
|
||||
try {
|
||||
await signIn("credentials", {
|
||||
email,
|
||||
password,
|
||||
redirect: false,
|
||||
});
|
||||
return { success: true };
|
||||
} catch (error: any) {
|
||||
return { success: false, error: "Invalid credentials" };
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add package.json pnpm-lock.yaml src/lib/auth.ts src/app/login/actions.ts
|
||||
git commit -m "feat: supabase auth adapter for cloud edition"
|
||||
```
|
||||
@@ -1,99 +0,0 @@
|
||||
# Phase 4: License Keys & Tiers Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Implement RSA-signed JWT license keys to gate Pro and Enterprise features on both Local and Cloud editions.
|
||||
|
||||
**Architecture:** A hardcoded public key verifies the JWT. The JWT payload dictates the tier (`free`, `pro`, `enterprise`) and expiration. The `uiSlice` state provides easy access to the active tier.
|
||||
|
||||
**Tech Stack:** `jose` for JWT verification.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: License Verification Module
|
||||
|
||||
**Files:**
|
||||
- Create: `src/core/license/verifyLicense.ts`
|
||||
- Create: `src/core/license/tiers.ts`
|
||||
|
||||
- [ ] **Step 1: Create Tier Definitions**
|
||||
|
||||
```typescript
|
||||
// src/core/license/tiers.ts
|
||||
export type LicenseTier = "free" | "pro" | "team" | "enterprise";
|
||||
|
||||
export interface TierFeatures {
|
||||
maxUsers: number;
|
||||
storageQuotaBytes: number;
|
||||
historyEnabled: boolean;
|
||||
snapshotCapture: boolean;
|
||||
customDomains: boolean;
|
||||
}
|
||||
|
||||
export const TIER_FEATURES: Record<LicenseTier, TierFeatures> = {
|
||||
free: { maxUsers: 3, storageQuotaBytes: 500 * 1024 * 1024, historyEnabled: false, snapshotCapture: false, customDomains: false },
|
||||
pro: { maxUsers: 20, storageQuotaBytes: 5 * 1024 * 1024 * 1024, historyEnabled: true, snapshotCapture: true, customDomains: false },
|
||||
team: { maxUsers: -1, storageQuotaBytes: -1, historyEnabled: true, snapshotCapture: true, customDomains: false },
|
||||
enterprise: { maxUsers: -1, storageQuotaBytes: -1, historyEnabled: true, snapshotCapture: true, customDomains: true },
|
||||
};
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Create JWT Verification**
|
||||
|
||||
```typescript
|
||||
// src/core/license/verifyLicense.ts
|
||||
import * as jose from "jose";
|
||||
|
||||
// Public key is safe to hardcode/ship to client
|
||||
const PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
|
||||
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu... (generate real one)
|
||||
-----END PUBLIC KEY-----`;
|
||||
|
||||
export interface LicensePayload {
|
||||
tier: "pro" | "team" | "enterprise";
|
||||
exp: number;
|
||||
org: string;
|
||||
}
|
||||
|
||||
export async function verifyLicenseKey(token: string): Promise<LicensePayload | null> {
|
||||
try {
|
||||
const publicKey = await jose.importSPKI(PUBLIC_KEY_PEM, "RS256");
|
||||
const { payload } = await jose.jwtVerify(token, publicKey);
|
||||
return payload as unknown as LicensePayload;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Task 2: State Integration
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/core/state/configSlice.ts`
|
||||
- Modify: `src/components/panels/SettingsPanel.tsx`
|
||||
|
||||
- [ ] **Step 1: Add license to configSlice**
|
||||
|
||||
```typescript
|
||||
// src/core/state/configSlice.ts
|
||||
// Add to DataConfig:
|
||||
export interface DataConfig {
|
||||
// ... existing ...
|
||||
licenseKey: string | null;
|
||||
activeTier: "free" | "pro" | "team" | "enterprise";
|
||||
}
|
||||
|
||||
// Add to initial state:
|
||||
// licenseKey: null, activeTier: "free"
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Add License input UI**
|
||||
|
||||
Add a text input in `SettingsPanel` for users to paste their license key, dispatching an action to verify and save it to the DB and Zustand store.
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add src/core/license/ src/core/state/configSlice.ts src/components/panels/
|
||||
git commit -m "feat: rsa jwt license key verification"
|
||||
```
|
||||
@@ -1,76 +0,0 @@
|
||||
# Phase 5: Cloud Deployment Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Create the Docker Compose configuration and routing layer necessary to run the multi-tenant cloud application.
|
||||
|
||||
**Architecture:** Use Traefik or nginx to route wildcard subdomains to the Next.js container. Provide environment variable overrides.
|
||||
|
||||
**Tech Stack:** Docker Compose, Traefik.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Docker Compose Setup
|
||||
|
||||
**Files:**
|
||||
- Create: `deploy/cloud/docker-compose.yml`
|
||||
- Create: `deploy/cloud/.env.example`
|
||||
|
||||
- [ ] **Step 1: Create compose file**
|
||||
|
||||
```yaml
|
||||
# deploy/cloud/docker-compose.yml
|
||||
services:
|
||||
wwv-cloud:
|
||||
image: ghcr.io/silvertakana/worldwideview:latest
|
||||
restart: always
|
||||
environment:
|
||||
NEXT_PUBLIC_WWV_EDITION: cloud
|
||||
DATABASE_URL: ${SUPABASE_PG_URL}
|
||||
NEXT_PUBLIC_SUPABASE_URL: ${SUPABASE_URL}
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY: ${SUPABASE_ANON_KEY}
|
||||
SUPABASE_SERVICE_ROLE_KEY: ${SUPABASE_SERVICE_ROLE_KEY}
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.wwv.rule=HostRegexp(`{user:[a-z0-9-]+}.app.worldwideview.dev`) || Host(`app.worldwideview.dev`)"
|
||||
- "traefik.http.routers.wwv.entrypoints=websecure"
|
||||
- "traefik.http.routers.wwv.tls.certresolver=letsencrypt"
|
||||
|
||||
traefik:
|
||||
image: traefik:v3.0
|
||||
command:
|
||||
- "--api.insecure=true"
|
||||
- "--providers.docker=true"
|
||||
- "--entrypoints.web.address=:80"
|
||||
- "--entrypoints.websecure.address=:443"
|
||||
- "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
|
||||
- "--certificatesresolvers.letsencrypt.acme.email=${ACME_EMAIL}"
|
||||
- "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- "/var/run/docker.sock:/var/run/docker.sock:ro"
|
||||
- "letsencrypt:/letsencrypt"
|
||||
|
||||
volumes:
|
||||
letsencrypt:
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Create example env file**
|
||||
|
||||
```env
|
||||
# deploy/cloud/.env.example
|
||||
SUPABASE_PG_URL=postgresql://postgres:[email protected]:5432/postgres
|
||||
SUPABASE_URL=https://xyz.supabase.co
|
||||
SUPABASE_ANON_KEY=eyJ...
|
||||
SUPABASE_SERVICE_ROLE_KEY=eyJ...
|
||||
ACME_EMAIL=[email protected]
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add deploy/
|
||||
git commit -m "chore: add cloud deployment compose configuration"
|
||||
```
|
||||
@@ -1,77 +0,0 @@
|
||||
# Phase 6: Stripe Billing Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Implement Stripe subscriptions for the cloud edition, generating license keys upon payment.
|
||||
|
||||
**Architecture:** Use Stripe Checkout Sessions for upgrades. Use Stripe Webhooks to listen for `checkout.session.completed` and `customer.subscription.updated` to update the user's tier in the database and generate their JWT license key.
|
||||
|
||||
**Tech Stack:** Stripe Node SDK, Next.js API Routes.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Stripe Integration
|
||||
|
||||
**Files:**
|
||||
- Modify: `package.json`
|
||||
- Create: `src/lib/stripe/client.ts`
|
||||
- Create: `src/app/api/billing/webhook/route.ts`
|
||||
- Create: `src/app/api/billing/checkout/route.ts`
|
||||
|
||||
- [ ] **Step 1: Install SDK**
|
||||
|
||||
Run: `pnpm add stripe`
|
||||
|
||||
- [ ] **Step 2: Create Stripe Client**
|
||||
|
||||
```typescript
|
||||
// src/lib/stripe/client.ts
|
||||
import Stripe from "stripe";
|
||||
|
||||
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
|
||||
apiVersion: "2024-04-10",
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Create Checkout Route**
|
||||
|
||||
```typescript
|
||||
// src/app/api/billing/checkout/route.ts
|
||||
import { stripe } from "@/lib/stripe/client";
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth } from "@/lib/auth";
|
||||
|
||||
export async function POST(req: Request) {
|
||||
const session = await auth();
|
||||
if (!session?.user) return new NextResponse("Unauthorized", { status: 401 });
|
||||
|
||||
const { priceId } = await req.json();
|
||||
|
||||
const checkoutSession = await stripe.checkout.sessions.create({
|
||||
mode: "subscription",
|
||||
payment_method_types: ["card"],
|
||||
line_items: [{ price: priceId, quantity: 1 }],
|
||||
success_url: `${process.env.NEXT_PUBLIC_APP_URL}/settings?success=true`,
|
||||
cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/settings?canceled=true`,
|
||||
client_reference_id: session.user.id,
|
||||
});
|
||||
|
||||
return NextResponse.json({ url: checkoutSession.url });
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Create Webhook Handler**
|
||||
|
||||
```typescript
|
||||
// src/app/api/billing/webhook/route.ts
|
||||
import { stripe } from "@/lib/stripe/client";
|
||||
import { NextResponse } from "next/server";
|
||||
// ... basic webhook payload verification and logging ...
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add package.json pnpm-lock.yaml src/lib/stripe/ src/app/api/billing/
|
||||
git commit -m "feat: stripe checkout and webhook integration"
|
||||
```
|
||||
@@ -1,51 +0,0 @@
|
||||
# Cloud Hosting & Plans — Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Transform WorldWideView from a local-only SQLite app into a multi-tenant cloud platform with `[user].app.worldwideview.dev` subdomains, PostgreSQL RLS isolation, Supabase Auth, cryptographic license keys, and Stripe billing.
|
||||
|
||||
**Architecture:** Single Docker container serves all tenants. nginx wildcard routes `*.app.worldwideview.dev` → Next.js. Middleware reads subdomain → sets `tenant_id` → PostgreSQL RLS scopes all queries. Same codebase, three editions (`local`/`cloud`/`demo`), adapter pattern for DB/auth/storage/tenant.
|
||||
|
||||
**Tech Stack:** Next.js 16, Prisma (multi-provider), PostgreSQL + RLS, Supabase Auth, Supabase Storage, RSA-signed JWTs (license keys), Stripe Checkout + Webhooks, nginx wildcard SSL.
|
||||
|
||||
---
|
||||
|
||||
## Current State Summary
|
||||
|
||||
| Component | Status |
|
||||
|---|---|
|
||||
| Edition system (`edition.ts`) | ✅ `local`/`cloud`/`demo` flags exist |
|
||||
| Auth (`src/lib/auth.ts`) | ✅ Credentials provider (bcrypt + SQLite) |
|
||||
| Database (`src/lib/db.ts`) | ⚠️ Hardcoded to `better-sqlite3` adapter |
|
||||
| Prisma schema | ⚠️ `provider = "sqlite"` only |
|
||||
| Tenant isolation | ❌ Not implemented |
|
||||
| Cloud auth (Supabase) | ❌ Not implemented |
|
||||
| License keys | ❌ Not implemented |
|
||||
| Storage adapter | ❌ Not implemented |
|
||||
| Stripe billing | ❌ Not implemented |
|
||||
| Cloud deployment repo | ❌ Not created |
|
||||
|
||||
---
|
||||
|
||||
## Phase Breakdown
|
||||
|
||||
Each phase is a self-contained deliverable. Phases 1–3 are foundational. Phases 4–6 add monetization.
|
||||
|
||||
| Phase | File | What It Builds | Depends On |
|
||||
|---|---|---|---|
|
||||
| 1 | [01-database-adapter.md](./01-database-adapter.md) | Prisma multi-provider (SQLite + PostgreSQL) | Nothing |
|
||||
| 2 | [02-tenant-system.md](./02-tenant-system.md) | RLS isolation, middleware, tenant context | Phase 1 |
|
||||
| 3 | [03-auth-upgrade.md](./03-auth-upgrade.md) | Supabase Auth provider for cloud edition | Phase 1 |
|
||||
| 4 | [04-license-keys.md](./04-license-keys.md) | RSA-signed JWT license keys, tier gating | Phase 1 |
|
||||
| 5 | [05-cloud-deployment.md](./05-cloud-deployment.md) | `worldwideview-cloud` repo, nginx, Docker Compose | Phases 1–3 |
|
||||
| 6 | [06-stripe-billing.md](./06-stripe-billing.md) | Stripe Checkout, webhooks, subscription management | Phases 3–4 |
|
||||
|
||||
---
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
1. **Adapter pattern** — Three thin files (`src/core/adapters/db.ts`, `auth.ts`, `storage.ts`, `tenant.ts`) branch on `edition`. Everything else is edition-unaware.
|
||||
2. **Prisma multi-provider** — Use a build-time script to swap the provider in `schema.prisma` before generating the client if building for cloud. One schema, two providers.
|
||||
3. **RLS over application-level filtering** — PostgreSQL physically refuses cross-tenant data. Even bugs can't leak.
|
||||
4. **License keys are RSA JWTs** — Marketplace signs with private key; app verifies with hardcoded public key. No phone-home required.
|
||||
5. **Stripe is the only payment processor** — Checkout Sessions for signup, Webhooks for lifecycle events.
|
||||
@@ -1,533 +0,0 @@
|
||||
# WorldWideView CLI Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Build `@worldwideview/cli`, a standalone CLI tool that scaffolds, hot-reloads, and packages WWV plugins using the Chrome Extension model, completely decoupled from the main monorepo build pipeline.
|
||||
|
||||
**Architecture:** A Node.js CLI built with `commander`. It uses `vite` programmatically to serve and build plugins. For dev mode, it attaches a `ws` WebSocket server to the Vite dev server to broadcast hot-reload events to the running WWV web app, and communicates with `/api/dev/load-unpacked` to inject the plugin. Publishing creates a `.wwvpkg` ZIP archive via `archiver`.
|
||||
|
||||
**Tech Stack:** Node.js, TypeScript, Commander, Vite, WebSocket (`ws`), Archiver, Vitest.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Initialize Package & CLI Entry Point
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-cli/package.json`
|
||||
- Create: `packages/wwv-cli/tsconfig.json`
|
||||
- Create: `packages/wwv-cli/bin/wwv.js`
|
||||
- Create: `packages/wwv-cli/src/index.ts`
|
||||
- Create: `packages/wwv-cli/tests/index.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/index.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { execSync } from "child_process";
|
||||
import path from "path";
|
||||
|
||||
describe("wwv cli", () => {
|
||||
it("should print help information", () => {
|
||||
const binPath = path.resolve(__dirname, "../bin/wwv.js");
|
||||
const output = execSync(`node ${binPath} --help`).toString();
|
||||
expect(output).toContain("Usage: wwv [options] [command]");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm test`
|
||||
Expected: FAIL (File not found or missing package.json setup)
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
```json
|
||||
// packages/wwv-cli/package.json
|
||||
{
|
||||
"name": "@worldwideview/cli",
|
||||
"version": "1.0.0",
|
||||
"bin": { "wwv": "./bin/wwv.js" },
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"test": "vitest run"
|
||||
},
|
||||
"dependencies": {
|
||||
"commander": "^11.1.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"typescript": "^5.0.0",
|
||||
"vitest": "^1.0.0",
|
||||
"@types/node": "^20.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// packages/wwv-cli/tsconfig.json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "CommonJS",
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true
|
||||
},
|
||||
"include": ["src/**/*"]
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
// packages/wwv-cli/bin/wwv.js
|
||||
#!/usr/bin/env node
|
||||
require('../dist/index.js');
|
||||
```
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/index.ts
|
||||
import { Command } from "commander";
|
||||
|
||||
const program = new Command();
|
||||
|
||||
program
|
||||
.name("wwv")
|
||||
.description("WorldWideView Plugin CLI")
|
||||
.version("1.0.0");
|
||||
|
||||
program.parse();
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm install && pnpm run build && pnpm test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli
|
||||
git commit -m "feat(wwv-cli): initialize cli package and entry point"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Implement `wwv create` (Scaffolding)
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-cli/src/commands/create.ts`
|
||||
- Create: `packages/wwv-cli/tests/create.test.ts`
|
||||
- Modify: `packages/wwv-cli/src/index.ts:10-15`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/create.test.ts
|
||||
import { describe, it, expect, afterEach } from "vitest";
|
||||
import { createPlugin } from "../src/commands/create";
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
|
||||
describe("create command", () => {
|
||||
const testDir = path.join(__dirname, "test-plugin");
|
||||
|
||||
afterEach(() => {
|
||||
if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it("should scaffold a new plugin folder with manifest and index.ts", async () => {
|
||||
await createPlugin("test-plugin", __dirname);
|
||||
expect(fs.existsSync(path.join(testDir, "wwv-manifest.json"))).toBe(true);
|
||||
expect(fs.existsSync(path.join(testDir, "src", "index.ts"))).toBe(true);
|
||||
|
||||
const manifest = JSON.parse(fs.readFileSync(path.join(testDir, "wwv-manifest.json"), "utf-8"));
|
||||
expect(manifest.id).toBe("test-plugin");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm test tests/create.test.ts`
|
||||
Expected: FAIL ("createPlugin is not defined")
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/commands/create.ts
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
|
||||
export async function createPlugin(name: string, basePath: string = process.cwd()) {
|
||||
const targetDir = path.join(basePath, name);
|
||||
if (fs.existsSync(targetDir)) {
|
||||
throw new Error(`Directory ${name} already exists`);
|
||||
}
|
||||
|
||||
fs.mkdirSync(targetDir, { recursive: true });
|
||||
fs.mkdirSync(path.join(targetDir, "src"), { recursive: true });
|
||||
|
||||
const manifest = {
|
||||
manifest_version: 1,
|
||||
id: name,
|
||||
name: name,
|
||||
version: "1.0.0",
|
||||
description: "A WorldWideView plugin",
|
||||
type: "data-layer",
|
||||
category: "custom",
|
||||
icon: "Box",
|
||||
capabilities: ["data:own"],
|
||||
entry: "dist/frontend.mjs",
|
||||
dev_entry: "src/index.ts"
|
||||
};
|
||||
|
||||
fs.writeFileSync(
|
||||
path.join(targetDir, "wwv-manifest.json"),
|
||||
JSON.stringify(manifest, null, 2)
|
||||
);
|
||||
|
||||
const indexContent = `export default class MyPlugin {
|
||||
id = "${name}";
|
||||
name = "${name}";
|
||||
version = "1.0.0";
|
||||
category = "custom";
|
||||
icon = "Box";
|
||||
|
||||
async initialize(ctx) {
|
||||
console.log("Initialized", this.id);
|
||||
}
|
||||
|
||||
destroy() {}
|
||||
|
||||
async fetch(timeRange) {
|
||||
return [];
|
||||
}
|
||||
|
||||
getPollingInterval() {
|
||||
return 5000;
|
||||
}
|
||||
|
||||
getLayerConfig() {
|
||||
return { color: "#3b82f6", clusterEnabled: true, clusterDistance: 50 };
|
||||
}
|
||||
|
||||
renderEntity(entity) {
|
||||
return { type: "point", color: "#3b82f6", size: 6 };
|
||||
}
|
||||
}
|
||||
`;
|
||||
fs.writeFileSync(path.join(targetDir, "src", "index.ts"), indexContent);
|
||||
console.log(`Plugin ${name} scaffolded successfully in ./${name}`);
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Modify packages/wwv-cli/src/index.ts (add this before program.parse())
|
||||
import { createPlugin } from "./commands/create";
|
||||
|
||||
program
|
||||
.command("create <name>")
|
||||
.description("Scaffold a new WorldWideView plugin")
|
||||
.action(async (name) => {
|
||||
try {
|
||||
await createPlugin(name);
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm run build && pnpm test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli
|
||||
git commit -m "feat(wwv-cli): implement create command for scaffolding"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Implement `wwv dev` (Vite Server + WebSocket)
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-cli/src/commands/dev.ts`
|
||||
- Create: `packages/wwv-cli/tests/dev.test.ts`
|
||||
- Modify: `packages/wwv-cli/src/index.ts:25-30`
|
||||
- Modify: `packages/wwv-cli/package.json:13-15` (Add vite, ws)
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/dev.test.ts
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import { startDevServer } from "../src/commands/dev";
|
||||
|
||||
// Mock vite and ws
|
||||
vi.mock("vite", () => ({
|
||||
createServer: vi.fn().mockResolvedValue({
|
||||
listen: vi.fn(),
|
||||
httpServer: { on: vi.fn() },
|
||||
ws: { on: vi.fn() }
|
||||
})
|
||||
}));
|
||||
|
||||
describe("dev command", () => {
|
||||
it("should export startDevServer function", () => {
|
||||
expect(typeof startDevServer).toBe("function");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm test tests/dev.test.ts`
|
||||
Expected: FAIL ("startDevServer is not defined")
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
Add `vite` and `ws` to dependencies in `packages/wwv-cli/package.json` and run `pnpm install`:
|
||||
```json
|
||||
"dependencies": {
|
||||
"commander": "^11.1.0",
|
||||
"vite": "^5.0.0",
|
||||
"ws": "^8.16.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/ws": "^8.5.10"
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/commands/dev.ts
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
import { createServer } from "vite";
|
||||
import { WebSocketServer } from "ws";
|
||||
|
||||
export async function startDevServer(targetUrl: string = "http://localhost:3000") {
|
||||
const cwd = process.cwd();
|
||||
const manifestPath = path.join(cwd, "wwv-manifest.json");
|
||||
|
||||
if (!fs.existsSync(manifestPath)) {
|
||||
throw new Error("No wwv-manifest.json found in current directory");
|
||||
}
|
||||
|
||||
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
|
||||
const port = 24601;
|
||||
|
||||
// Start Vite Dev Server
|
||||
const vite = await createServer({
|
||||
root: cwd,
|
||||
server: { port, cors: true, hmr: false }, // We handle HMR via custom WS
|
||||
plugins: [{
|
||||
name: 'wwv-hmr',
|
||||
handleHotUpdate({ server }) {
|
||||
// When Vite detects file changes, broadcast to our custom WS
|
||||
wss.clients.forEach(client => {
|
||||
client.send(JSON.stringify({ type: "plugin:updated", pluginId: manifest.id }));
|
||||
});
|
||||
return []; // Prevent default Vite HMR
|
||||
}
|
||||
}]
|
||||
});
|
||||
|
||||
await vite.listen();
|
||||
|
||||
// Attach custom WebSocket server for WWV DevModeSubscriber
|
||||
const wss = new WebSocketServer({ server: vite.httpServer as any, path: "/__wwv_dev__" });
|
||||
|
||||
wss.on("connection", (ws) => {
|
||||
console.log(`[WWV CLI] Connected to WorldWideView instance`);
|
||||
ws.send(JSON.stringify({ type: "plugin:added", manifest }));
|
||||
});
|
||||
|
||||
// Notify WorldWideView via API
|
||||
try {
|
||||
const fetch = (await import('node-fetch')).default || globalThis.fetch;
|
||||
await fetch(`${targetUrl}/api/dev/load-unpacked`, {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({
|
||||
...manifest,
|
||||
entry: `http://localhost:${port}/${manifest.dev_entry || "src/index.ts"}`
|
||||
})
|
||||
});
|
||||
console.log(`[WWV CLI] Registered with WorldWideView at ${targetUrl}`);
|
||||
} catch (err: any) {
|
||||
console.error(`[WWV CLI] Failed to connect to ${targetUrl}: ${err.message}`);
|
||||
console.log(`Waiting for WorldWideView to connect via WebSocket...`);
|
||||
}
|
||||
|
||||
console.log(`\n🚀 Dev server running on http://localhost:${port}`);
|
||||
console.log(`Watching for file changes in ${cwd}...\n`);
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Modify packages/wwv-cli/src/index.ts (add this before program.parse())
|
||||
import { startDevServer } from "./commands/dev";
|
||||
|
||||
program
|
||||
.command("dev")
|
||||
.description("Start the plugin development server with hot-reload")
|
||||
.option("-t, --target <url>", "Target WorldWideView URL", "http://localhost:3000")
|
||||
.action(async (options) => {
|
||||
try {
|
||||
await startDevServer(options.target);
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm run build && pnpm test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli
|
||||
git commit -m "feat(wwv-cli): implement dev command with vite and websockets"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Implement `wwv publish` (.wwvpkg creation)
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-cli/src/commands/publish.ts`
|
||||
- Create: `packages/wwv-cli/tests/publish.test.ts`
|
||||
- Modify: `packages/wwv-cli/src/index.ts:40-45`
|
||||
- Modify: `packages/wwv-cli/package.json:16-17` (Add archiver)
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/publish.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { buildPackage } from "../src/commands/publish";
|
||||
|
||||
describe("publish command", () => {
|
||||
it("should export buildPackage function", () => {
|
||||
expect(typeof buildPackage).toBe("function");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm test tests/publish.test.ts`
|
||||
Expected: FAIL ("buildPackage is not defined")
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
Add `archiver` to dependencies in `packages/wwv-cli/package.json` and run `pnpm install`:
|
||||
```json
|
||||
"dependencies": {
|
||||
"archiver": "^7.0.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/archiver": "^6.0.2"
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/commands/publish.ts
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
import { build } from "vite";
|
||||
import archiver from "archiver";
|
||||
|
||||
export async function buildPackage() {
|
||||
const cwd = process.cwd();
|
||||
const manifestPath = path.join(cwd, "wwv-manifest.json");
|
||||
|
||||
if (!fs.existsSync(manifestPath)) {
|
||||
throw new Error("No wwv-manifest.json found in current directory");
|
||||
}
|
||||
|
||||
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
|
||||
|
||||
console.log(`[WWV CLI] Building production bundle...`);
|
||||
await build({
|
||||
root: cwd,
|
||||
build: {
|
||||
lib: {
|
||||
entry: path.resolve(cwd, manifest.dev_entry || "src/index.ts"),
|
||||
name: 'WWVPlugin',
|
||||
formats: ['es'],
|
||||
fileName: () => 'frontend.mjs'
|
||||
},
|
||||
outDir: 'dist',
|
||||
emptyOutDir: true
|
||||
}
|
||||
});
|
||||
|
||||
const pkgName = `${manifest.id}-${manifest.version}.wwvpkg`;
|
||||
const outputPath = path.join(cwd, pkgName);
|
||||
|
||||
console.log(`[WWV CLI] Creating archive ${pkgName}...`);
|
||||
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
const output = fs.createWriteStream(outputPath);
|
||||
const archive = archiver("zip", { zlib: { level: 9 } });
|
||||
|
||||
output.on("close", () => resolve());
|
||||
archive.on("error", (err) => reject(err));
|
||||
|
||||
archive.pipe(output);
|
||||
|
||||
archive.file(manifestPath, { name: "wwv-manifest.json" });
|
||||
archive.directory(path.join(cwd, "dist"), "dist");
|
||||
|
||||
if (fs.existsSync(path.join(cwd, "data"))) {
|
||||
archive.directory(path.join(cwd, "data"), "data");
|
||||
}
|
||||
|
||||
archive.finalize();
|
||||
});
|
||||
|
||||
console.log(`\n🎉 Success! Package created at ${outputPath}`);
|
||||
console.log(`You can now upload this file to the WorldWideView Marketplace.`);
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Modify packages/wwv-cli/src/index.ts (add this before program.parse())
|
||||
import { buildPackage } from "./commands/publish";
|
||||
|
||||
program
|
||||
.command("publish")
|
||||
.description("Build and package the plugin into a .wwvpkg file")
|
||||
.action(async () => {
|
||||
try {
|
||||
await buildPackage();
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm run build && pnpm test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli
|
||||
git commit -m "feat(wwv-cli): implement publish command for wwvpkg creation"
|
||||
```
|
||||
@@ -1,323 +0,0 @@
|
||||
# Split CLI Publish into Package and Publish Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Split the CLI publish command into `package` (for local .wwvpkg zip creation) and `publish` (for NPM distribution and marketplace registry updates).
|
||||
|
||||
**Architecture:**
|
||||
The current `publish` command creates a `.wwvpkg` file. We will rename this functionality to the `package` command. Then, we will create a true `publish` command that handles building the plugin, automatically generating a valid `package.json` from the `wwv-manifest.json`, running `npm publish` via a child process, and finally notifying the marketplace of the new release.
|
||||
|
||||
**Tech Stack:** TypeScript, Vite, Node.js `child_process`, Node.js `fs`.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Rename current publish to package
|
||||
|
||||
We will rename the file and its internal function from `buildPackage` to `packagePlugin`.
|
||||
|
||||
**Files:**
|
||||
- Modify: `packages/wwv-cli/src/commands/publish.ts` -> rename to `packages/wwv-cli/src/commands/package.ts`
|
||||
- Modify: `packages/wwv-cli/tests/publish.test.ts` -> rename to `packages/wwv-cli/tests/package.test.ts`
|
||||
|
||||
- [ ] **Step 1: Rename the command file and update function name**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/commands/package.ts
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
import { build } from "vite";
|
||||
import archiver from "archiver";
|
||||
|
||||
export async function packagePlugin() {
|
||||
const cwd = process.cwd();
|
||||
const manifestPath = path.join(cwd, "wwv-manifest.json");
|
||||
|
||||
if (!fs.existsSync(manifestPath)) {
|
||||
throw new Error("No wwv-manifest.json found in current directory");
|
||||
}
|
||||
|
||||
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
|
||||
|
||||
console.log(`[WWV CLI] Building production bundle...`);
|
||||
await build({
|
||||
root: cwd,
|
||||
build: {
|
||||
lib: {
|
||||
entry: path.resolve(cwd, manifest.dev_entry || "src/index.ts"),
|
||||
name: 'WWVPlugin',
|
||||
formats: ['es'],
|
||||
fileName: () => 'frontend.mjs'
|
||||
},
|
||||
outDir: 'dist',
|
||||
emptyOutDir: true
|
||||
}
|
||||
});
|
||||
|
||||
const pkgName = `${manifest.id}-${manifest.version}.wwvpkg`;
|
||||
const outputPath = path.join(cwd, pkgName);
|
||||
|
||||
console.log(`[WWV CLI] Creating archive ${pkgName}...`);
|
||||
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
const output = fs.createWriteStream(outputPath);
|
||||
const archive = archiver("zip", { zlib: { level: 9 } });
|
||||
|
||||
output.on("close", () => resolve());
|
||||
archive.on("error", (err) => reject(err));
|
||||
|
||||
archive.pipe(output);
|
||||
|
||||
archive.file(manifestPath, { name: "wwv-manifest.json" });
|
||||
archive.directory(path.join(cwd, "dist"), "dist");
|
||||
|
||||
if (fs.existsSync(path.join(cwd, "data"))) {
|
||||
archive.directory(path.join(cwd, "data"), "data");
|
||||
}
|
||||
|
||||
archive.finalize();
|
||||
});
|
||||
|
||||
console.log(`\n🎉 Success! Package created at ${outputPath}`);
|
||||
console.log(`You can use this file to sideload the plugin into your WWV instance.`);
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Rename and update the test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/package.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { packagePlugin } from "../src/commands/package";
|
||||
|
||||
describe("package command", () => {
|
||||
it("should export packagePlugin function", () => {
|
||||
expect(typeof packagePlugin).toBe("function");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Remove old files**
|
||||
|
||||
Run: `git rm packages/wwv-cli/src/commands/publish.ts packages/wwv-cli/tests/publish.test.ts`
|
||||
Expected: Files deleted.
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli/src/commands/package.ts packages/wwv-cli/tests/package.test.ts
|
||||
git commit -m "refactor(wwv-cli): rename publish to package for wwvpkg creation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Implement true NPM Publish command
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-cli/src/commands/publish.ts`
|
||||
- Create: `packages/wwv-cli/tests/publish.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/publish.test.ts
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import { publishToNpm } from "../src/commands/publish";
|
||||
|
||||
vi.mock("child_process", () => ({
|
||||
execSync: vi.fn()
|
||||
}));
|
||||
vi.mock("vite", () => ({
|
||||
build: vi.fn().mockResolvedValue({})
|
||||
}));
|
||||
|
||||
describe("publish command", () => {
|
||||
it("should export publishToNpm function", () => {
|
||||
expect(typeof publishToNpm).toBe("function");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `pnpm test tests/publish.test.ts` inside `packages/wwv-cli`
|
||||
Expected: FAIL because `publishToNpm` does not exist.
|
||||
|
||||
- [ ] **Step 3: Write the publish implementation**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/commands/publish.ts
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
import { build } from "vite";
|
||||
import { execSync } from "child_process";
|
||||
|
||||
export async function publishToNpm() {
|
||||
const cwd = process.cwd();
|
||||
const manifestPath = path.join(cwd, "wwv-manifest.json");
|
||||
|
||||
if (!fs.existsSync(manifestPath)) {
|
||||
throw new Error("No wwv-manifest.json found in current directory");
|
||||
}
|
||||
|
||||
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
|
||||
|
||||
console.log(`[WWV CLI] Compiling bundle for NPM...`);
|
||||
await build({
|
||||
root: cwd,
|
||||
build: {
|
||||
lib: {
|
||||
entry: path.resolve(cwd, manifest.dev_entry || "src/index.ts"),
|
||||
name: 'WWVPlugin',
|
||||
formats: ['es'],
|
||||
fileName: () => 'frontend.mjs'
|
||||
},
|
||||
outDir: 'dist',
|
||||
emptyOutDir: true
|
||||
}
|
||||
});
|
||||
|
||||
console.log(`[WWV CLI] Generating package.json...`);
|
||||
// Create a temporary package.json required for NPM publish
|
||||
const packageJsonPath = path.join(cwd, "package.json");
|
||||
const packageJson = {
|
||||
name: manifest.id, // e.g. @username/my-plugin
|
||||
version: manifest.version,
|
||||
description: manifest.description,
|
||||
main: "dist/frontend.mjs",
|
||||
type: "module",
|
||||
files: ["dist", "wwv-manifest.json", "data"],
|
||||
keywords: ["worldwideview", "plugin", manifest.category],
|
||||
author: manifest.author || ""
|
||||
};
|
||||
|
||||
fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
|
||||
|
||||
console.log(`[WWV CLI] Publishing to NPM...`);
|
||||
try {
|
||||
execSync(`npm publish --access public`, { stdio: "inherit", cwd });
|
||||
} catch (err) {
|
||||
console.error(`[WWV CLI] NPM publish failed. Please ensure you are logged in via 'npm login'.`);
|
||||
throw err;
|
||||
} finally {
|
||||
// Clean up the generated package.json so it doesn't clutter the dev's repo
|
||||
fs.unlinkSync(packageJsonPath);
|
||||
}
|
||||
|
||||
console.log(`[WWV CLI] Notifying WorldWideView Marketplace...`);
|
||||
try {
|
||||
const targetUrl = process.env.WWV_MARKETPLACE_URL || "https://marketplace.worldwideview.dev";
|
||||
await fetch(`${targetUrl}/api/webhooks/npm-publish`, {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ pluginId: manifest.id, version: manifest.version })
|
||||
});
|
||||
console.log(`[WWV CLI] Marketplace notified.`);
|
||||
} catch (err: any) {
|
||||
console.warn(`[WWV CLI] Could not notify marketplace: ${err.message}. It will be indexed on the next sweep.`);
|
||||
}
|
||||
|
||||
console.log(`\n🚀 Success! Version ${manifest.version} published globally to NPM.`);
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `pnpm test tests/publish.test.ts` inside `packages/wwv-cli`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli/src/commands/publish.ts packages/wwv-cli/tests/publish.test.ts
|
||||
git commit -m "feat(wwv-cli): implement npm publish and marketplace webhook ping"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Update CLI Entry Point
|
||||
|
||||
**Files:**
|
||||
- Modify: `packages/wwv-cli/src/index.ts:36-50`
|
||||
|
||||
- [ ] **Step 1: Write the updated entry point logic**
|
||||
|
||||
Replace the existing `publish` command logic with both `package` and `publish`:
|
||||
|
||||
```typescript
|
||||
// Edit packages/wwv-cli/src/index.ts
|
||||
import { Command } from "commander";
|
||||
import { createPlugin } from "./commands/create";
|
||||
import { startDevServer } from "./commands/dev";
|
||||
import { packagePlugin } from "./commands/package";
|
||||
import { publishToNpm } from "./commands/publish";
|
||||
|
||||
const program = new Command();
|
||||
|
||||
program
|
||||
.name("wwv")
|
||||
.description("WorldWideView Plugin CLI")
|
||||
.version("1.0.0");
|
||||
|
||||
program
|
||||
.command("create <name>")
|
||||
.description("Scaffold a new WorldWideView plugin")
|
||||
.action(async (name) => {
|
||||
try {
|
||||
await createPlugin(name);
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
program
|
||||
.command("dev")
|
||||
.description("Start the plugin development server with hot-reload")
|
||||
.option("-t, --target <url>", "Target WorldWideView URL", "http://localhost:3000")
|
||||
.action(async (options) => {
|
||||
try {
|
||||
await startDevServer(options.target);
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
program
|
||||
.command("package")
|
||||
.description("Build and package the plugin into a .wwvpkg file for sideloading")
|
||||
.action(async () => {
|
||||
try {
|
||||
await packagePlugin();
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
program
|
||||
.command("publish")
|
||||
.description("Publish the plugin to NPM and notify the WWV Marketplace")
|
||||
.action(async () => {
|
||||
try {
|
||||
await publishToNpm();
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
program.parse();
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Build to verify no TypeScript errors**
|
||||
|
||||
Run: `pnpm run build` inside `packages/wwv-cli`
|
||||
Expected: Clean build.
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli/src/index.ts
|
||||
git commit -m "feat(wwv-cli): register package and npm publish commands"
|
||||
```
|
||||
@@ -1,53 +0,0 @@
|
||||
# Prisma 7 Setup Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Finalize the Prisma 7 adapter architecture by removing legacy `url` parameters from the schema, syncing the local database, and validating the end-to-end connection.
|
||||
|
||||
**Architecture:** Prisma 7 strictly separates connection logic from the schema. The schema only defines the provider (`postgresql`), while connection strings for CLI commands like `db push` are handled by `prisma.config.ts`, and runtime connections are handled by the explicit `@prisma/adapter-pg` driver instance passed to the `PrismaClient` constructor.
|
||||
|
||||
**Tech Stack:** Prisma 7, PostgreSQL, Next.js, Node.js
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Update Prisma Schema
|
||||
|
||||
**Files:**
|
||||
- Modify: `prisma/schema.prisma:5-8`
|
||||
|
||||
- [ ] **Step 1: Remove the legacy `url` property from the datasource block**
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
}
|
||||
```
|
||||
|
||||
### Task 2: Push Schema to Local Database
|
||||
|
||||
- [ ] **Step 1: Execute Prisma db push to create the tables in the newly running Docker Postgres container**
|
||||
|
||||
Run: `npx dotenv-cli -e .env.local -- npx prisma db push`
|
||||
Expected: PASS with "Your database is now in sync with your schema."
|
||||
|
||||
### Task 3: Generate Prisma Client
|
||||
|
||||
- [ ] **Step 1: Regenerate the Prisma Client types to ensure they match the schema**
|
||||
|
||||
Run: `npx dotenv-cli -e .env.local -- npx prisma generate`
|
||||
Expected: PASS with "Generated Prisma Client"
|
||||
|
||||
### Task 4: Verify End-to-End Connection
|
||||
|
||||
- [ ] **Step 1: Run the user management script to prove the `adapter-pg` runtime can connect and query the new tables**
|
||||
|
||||
Run: `npx tsx --env-file=.env.local scripts/manage-users.ts list`
|
||||
Expected: PASS with no errors (it should just exit silently if there are no users, rather than throwing a `P2021 TableDoesNotExist` or `P1001` error).
|
||||
|
||||
### Task 5: Restart the Development Server
|
||||
|
||||
- [ ] **Step 1: Restart the Next.js dev server**
|
||||
Because the server has been running while we were debugging the `PrismaClientInitializationError`, Webpack may have cached the broken client. We need to kill the current `pnpm run dev` and start it fresh so we can test the API routes in the browser.
|
||||
|
||||
Run: Terminate the current `pnpm run dev` terminal, then run: `pnpm run dev`
|
||||
Expected: Next.js starts successfully without any Prisma instantiation crashes.
|
||||
@@ -1,618 +0,0 @@
|
||||
# Unify Database Adapter (PostgreSQL-Only) Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.
|
||||
|
||||
**Goal:** Replace the dual SQLite/PostgreSQL database system with a single PostgreSQL adapter, using Prisma's built-in `prisma dev` for zero-install local development.
|
||||
|
||||
**Architecture:** The app currently has two database paths — `@prisma/adapter-better-sqlite3` for local and `@prisma/adapter-pg` for cloud — which causes constant migration conflicts and config drift. We unify to `@prisma/adapter-pg` everywhere. Local developers use `npx prisma dev` (PGLite-backed local Postgres managed by Prisma CLI) or their own Postgres instance. Production connects to Supabase via the same adapter and connection string swap.
|
||||
|
||||
**Tech Stack:** Prisma 7, `@prisma/adapter-pg`, `pg`, PostgreSQL, Next.js 16
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
| Action | File | Responsibility |
|
||||
|---|---|---|
|
||||
| Modify | `prisma/schema.prisma` | Change provider to `postgresql` |
|
||||
| **Rewrite** | `src/lib/db.ts` | Single PostgreSQL adapter factory |
|
||||
| Delete | `src/core/adapters/db.ts` | Remove cloud-branch adapter factory (merge into `db.ts`) |
|
||||
| Modify | `package.json` | Remove `better-sqlite3` + adapter deps, add `pg` |
|
||||
| Modify | `next.config.ts` | Remove `better-sqlite3` from `serverExternalPackages` |
|
||||
| Modify | `docker-entrypoint.sh` | Update comments, remove SQLite references |
|
||||
| Modify | `Dockerfile` | Remove SQLite build step, update env defaults |
|
||||
| Modify | `local-dev.ps1` | Add `prisma dev` startup guidance |
|
||||
| Modify | `.env` | Change default `DATABASE_URL` to local PostgreSQL |
|
||||
| Modify | `prisma.config.ts` | No changes needed (already reads `DATABASE_URL`) |
|
||||
| Modify | `scripts/cleanup-plugins.ts` | Use shared `db.ts` instead of hardcoded SQLite |
|
||||
| Modify | `scripts/manage-users.ts` | Use shared `db.ts` instead of hardcoded SQLite |
|
||||
| Keep | `scripts/migrate-aviation-history.ts` | This is a one-off Supabase-to-SQLite migration tool. Leave as-is but mark deprecated |
|
||||
| **Delete** | `prisma/migrations/` | Remove old SQLite migrations (will regenerate for PostgreSQL) |
|
||||
| **Create** | `prisma/migrations/` | Fresh PostgreSQL init migration |
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Update Prisma Schema Provider
|
||||
|
||||
**Files:**
|
||||
- Modify: `prisma/schema.prisma:1-6`
|
||||
|
||||
- [x] **Step 1: Change the datasource provider from SQLite to PostgreSQL**
|
||||
|
||||
Open `prisma/schema.prisma` and replace the datasource block:
|
||||
|
||||
```prisma
|
||||
// Prisma schema — PostgreSQL for all environments.
|
||||
// Local dev: use `npx prisma dev` for a zero-install local PGLite instance.
|
||||
// Cloud/Production: set DATABASE_URL to your Supabase/Postgres connection string.
|
||||
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
}
|
||||
```
|
||||
|
||||
Leave the `generator` block and all models unchanged.
|
||||
|
||||
- [x] **Step 2: Verify the schema is valid**
|
||||
|
||||
Run:
|
||||
```powershell
|
||||
npx prisma validate
|
||||
```
|
||||
|
||||
Expected: `The schema at prisma/schema.prisma is valid.`
|
||||
|
||||
- [x] **Step 3: Commit**
|
||||
|
||||
```powershell
|
||||
git add prisma/schema.prisma
|
||||
git commit -m "refactor(db): switch schema provider from sqlite to postgresql"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Remove SQLite Dependencies
|
||||
|
||||
**Files:**
|
||||
- Modify: `package.json:22-80`
|
||||
- Modify: `next.config.ts:5`
|
||||
|
||||
- [x] **Step 1: Remove better-sqlite3 packages from package.json**
|
||||
|
||||
In `package.json`, remove these lines from `dependencies`:
|
||||
```diff
|
||||
- "@prisma/adapter-better-sqlite3": "^7.5.0",
|
||||
```
|
||||
|
||||
Remove from `pnpm.onlyBuiltDependencies`:
|
||||
```diff
|
||||
- "better-sqlite3",
|
||||
```
|
||||
|
||||
Ensure `@prisma/adapter-pg` and `pg` remain (they're already present):
|
||||
```json
|
||||
"@prisma/adapter-pg": "^7.8.0",
|
||||
"pg": "^8.20.0",
|
||||
```
|
||||
|
||||
- [x] **Step 2: Update serverExternalPackages in next.config.ts**
|
||||
|
||||
In `next.config.ts` line 5, replace:
|
||||
```typescript
|
||||
serverExternalPackages: ["better-sqlite3", "@prisma/adapter-better-sqlite3", "@prisma/client", "prisma"],
|
||||
```
|
||||
|
||||
With:
|
||||
```typescript
|
||||
serverExternalPackages: ["@prisma/client", "prisma", "pg"],
|
||||
```
|
||||
|
||||
- [x] **Step 3: Install to update lockfile**
|
||||
|
||||
Run:
|
||||
```powershell
|
||||
pnpm install
|
||||
```
|
||||
|
||||
Expected: Clean install with no `better-sqlite3` compilation step.
|
||||
|
||||
- [x] **Step 4: Commit**
|
||||
|
||||
```powershell
|
||||
git add package.json next.config.ts pnpm-lock.yaml
|
||||
git commit -m "refactor(db): remove better-sqlite3 dependencies"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Rewrite the Database Adapter Factory
|
||||
|
||||
**Files:**
|
||||
- Rewrite: `src/lib/db.ts`
|
||||
|
||||
- [x] **Step 1: Replace db.ts with a unified PostgreSQL adapter**
|
||||
|
||||
Replace the entire contents of `src/lib/db.ts` with:
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from "../generated/prisma";
|
||||
import { PrismaPg } from "@prisma/adapter-pg";
|
||||
import { Pool } from "pg";
|
||||
|
||||
/**
|
||||
* Prisma client singleton — PostgreSQL only.
|
||||
*
|
||||
* Local dev: Run `npx prisma dev` for a zero-install local Postgres.
|
||||
* Production: Set DATABASE_URL to your Supabase/Postgres connection string.
|
||||
*
|
||||
* Uses globalThis to survive Next.js HMR in development.
|
||||
*/
|
||||
|
||||
const globalForPrisma = globalThis as unknown as {
|
||||
prisma: PrismaClient | undefined;
|
||||
};
|
||||
|
||||
function createPrismaClient(): PrismaClient {
|
||||
const connectionString = process.env.DATABASE_URL;
|
||||
|
||||
if (!connectionString) {
|
||||
throw new Error(
|
||||
"[db] DATABASE_URL is not set. " +
|
||||
"Run `npx prisma dev` for local development, " +
|
||||
"or set DATABASE_URL to your PostgreSQL connection string."
|
||||
);
|
||||
}
|
||||
|
||||
const pool = new Pool({ connectionString });
|
||||
const adapter = new PrismaPg(pool);
|
||||
|
||||
return new PrismaClient({ adapter } as any);
|
||||
}
|
||||
|
||||
export const prisma = globalForPrisma.prisma ?? createPrismaClient();
|
||||
|
||||
if (process.env.NODE_ENV !== "production") {
|
||||
globalForPrisma.prisma = prisma;
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** The `feature/cloud-hosting-core` branch has a more complex version at `src/core/adapters/db.ts` with tenant isolation via `applyTenantIsolation()`. When merging that branch later, the tenant isolation extension should be layered on top of this unified base — it does NOT need a separate SQLite path.
|
||||
|
||||
- [x] **Step 2: Verify TypeScript compilation**
|
||||
|
||||
Run:
|
||||
```powershell
|
||||
npx tsc --noEmit --pretty 2>&1 | Select-String "db.ts"
|
||||
```
|
||||
|
||||
Expected: No errors related to `db.ts`.
|
||||
|
||||
- [x] **Step 3: Commit**
|
||||
|
||||
```powershell
|
||||
git add src/lib/db.ts
|
||||
git commit -m "refactor(db): unify adapter to postgresql-only via PrismaPg"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Update Utility Scripts
|
||||
|
||||
**Files:**
|
||||
- Modify: `scripts/cleanup-plugins.ts`
|
||||
- Modify: `scripts/manage-users.ts`
|
||||
|
||||
- [x] **Step 1: Rewrite cleanup-plugins.ts to use shared db**
|
||||
|
||||
Replace the entire contents of `scripts/cleanup-plugins.ts`:
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from "../src/generated/prisma/index.js";
|
||||
import { PrismaPg } from "@prisma/adapter-pg";
|
||||
import { Pool } from "pg";
|
||||
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
|
||||
const adapter = new PrismaPg(pool);
|
||||
const prisma = new PrismaClient({ adapter } as any);
|
||||
|
||||
async function main() {
|
||||
const plugins = await prisma.installedPlugin.findMany();
|
||||
console.log("Installed plugins:");
|
||||
plugins.forEach((p) => console.log(` ${p.pluginId} | config: ${p.config.substring(0, 60)}`));
|
||||
|
||||
const geojson = plugins.find((p) => p.pluginId === "geojson");
|
||||
if (geojson) {
|
||||
await prisma.installedPlugin.delete({ where: { id: geojson.id } });
|
||||
console.log("\nDeleted orphaned 'geojson' record.");
|
||||
} else {
|
||||
console.log("\nNo orphaned 'geojson' record found.");
|
||||
}
|
||||
|
||||
const remaining = await prisma.installedPlugin.findMany();
|
||||
console.log("\nRemaining plugins:");
|
||||
remaining.forEach((p) => console.log(` ${p.pluginId}`));
|
||||
|
||||
await prisma.$disconnect();
|
||||
}
|
||||
|
||||
main().catch(console.error);
|
||||
```
|
||||
|
||||
- [x] **Step 2: Rewrite manage-users.ts to use shared db**
|
||||
|
||||
Replace the entire contents of `scripts/manage-users.ts`:
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from "../src/generated/prisma/index.js";
|
||||
import { PrismaPg } from "@prisma/adapter-pg";
|
||||
import { Pool } from "pg";
|
||||
import { hashSync } from "bcryptjs";
|
||||
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
|
||||
const adapter = new PrismaPg(pool);
|
||||
const prisma = new PrismaClient({ adapter } as any);
|
||||
|
||||
async function main() {
|
||||
const action = process.argv[2];
|
||||
|
||||
if (action === "list") {
|
||||
const users = await prisma.user.findMany();
|
||||
if (users.length === 0) {
|
||||
console.log("No users found — visit /setup to create one.");
|
||||
} else {
|
||||
users.forEach((u) =>
|
||||
console.log(` ${u.email} | ${u.name} | ${u.role} | ${u.createdAt}`)
|
||||
);
|
||||
}
|
||||
} else if (action === "reset") {
|
||||
const email = process.argv[3];
|
||||
const newPass = process.argv[4];
|
||||
if (!email || !newPass) {
|
||||
console.log("Usage: tsx scripts/manage-users.ts reset <email> <password>");
|
||||
return;
|
||||
}
|
||||
const hashed = hashSync(newPass, 12);
|
||||
await prisma.user.update({
|
||||
where: { email },
|
||||
data: { hashedPassword: hashed },
|
||||
});
|
||||
console.log(`Password reset for ${email}`);
|
||||
} else if (action === "delete-all") {
|
||||
await prisma.user.deleteMany();
|
||||
console.log("All users deleted — visit /setup to create a new admin.");
|
||||
} else {
|
||||
console.log("Usage: tsx scripts/manage-users.ts <list|reset|delete-all>");
|
||||
}
|
||||
|
||||
await prisma.$disconnect();
|
||||
}
|
||||
|
||||
main().catch(console.error);
|
||||
```
|
||||
|
||||
- [x] **Step 3: Add deprecation notice to migrate-aviation-history.ts**
|
||||
|
||||
Add this comment at the top of `scripts/migrate-aviation-history.ts`:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* @deprecated This script uses better-sqlite3 directly to migrate data
|
||||
* from Supabase into the legacy data engine's SQLite database.
|
||||
* It is NOT part of the main application's database layer.
|
||||
* It will be removed once the data engine migration is complete.
|
||||
*/
|
||||
```
|
||||
|
||||
- [x] **Step 4: Commit**
|
||||
|
||||
```powershell
|
||||
git add scripts/cleanup-plugins.ts scripts/manage-users.ts scripts/migrate-aviation-history.ts
|
||||
git commit -m "refactor(scripts): update utility scripts to use postgresql adapter"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Create Fresh PostgreSQL Migration
|
||||
|
||||
**Files:**
|
||||
- Delete: `prisma/migrations/` (entire directory)
|
||||
- Create: `prisma/migrations/YYYYMMDD_init/migration.sql` (generated by Prisma)
|
||||
|
||||
- [x] **Step 1: Delete old SQLite migrations**
|
||||
|
||||
```powershell
|
||||
Remove-Item -Recurse -Force prisma/migrations
|
||||
```
|
||||
|
||||
- [x] **Step 2: Ensure a local PostgreSQL is available**
|
||||
|
||||
Either:
|
||||
- Run `npx prisma dev` in a separate terminal, OR
|
||||
- Use your existing local PostgreSQL at `127.0.0.1:5432`
|
||||
|
||||
Verify the connection string in `.env.local` points to a reachable PostgreSQL instance:
|
||||
```
|
||||
DATABASE_URL="postgresql://postgres:[email protected]:5432/postgres?schema=public"
|
||||
```
|
||||
|
||||
- [x] **Step 3: Reset and create initial migration**
|
||||
|
||||
```powershell
|
||||
npx prisma migrate reset --force
|
||||
npx prisma migrate dev --name init
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
Applying migration `YYYYMMDDHHMMSS_init`
|
||||
The following migration(s) have been created and applied...
|
||||
```
|
||||
|
||||
- [x] **Step 4: Verify migration_lock.toml says postgresql**
|
||||
|
||||
```powershell
|
||||
Get-Content prisma/migrations/migration_lock.toml
|
||||
```
|
||||
|
||||
Expected:
|
||||
```
|
||||
provider = "postgresql"
|
||||
```
|
||||
|
||||
- [x] **Step 5: Commit**
|
||||
|
||||
```powershell
|
||||
git add prisma/migrations
|
||||
git commit -m "feat(db): create initial postgresql migration"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Update Dockerfile and Entrypoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `Dockerfile:11,36-38,49,54`
|
||||
- Modify: `docker-entrypoint.sh:3-5`
|
||||
|
||||
- [x] **Step 1: Update Dockerfile**
|
||||
|
||||
Make these changes to `Dockerfile`:
|
||||
|
||||
**Line 11** — Remove `python3 make g++` (no longer need to compile better-sqlite3 native bindings):
|
||||
```dockerfile
|
||||
RUN apk add --no-cache python3 make g++
|
||||
```
|
||||
Replace with:
|
||||
```dockerfile
|
||||
# python3/make/g++ no longer needed — removed better-sqlite3 native compilation
|
||||
```
|
||||
|
||||
**Lines 36-38** — Remove the conditional SQLite build step entirely:
|
||||
```dockerfile
|
||||
# Create an empty SQLite database with all tables applied ONLY IF NOT CLOUD
|
||||
# (For cloud, we'll run migrations against Postgres at runtime)
|
||||
RUN if [ "$NEXT_PUBLIC_WWV_EDITION" != "cloud" ]; then mkdir -p ./data && DATABASE_URL=file:./data/wwv.db npx prisma migrate deploy; fi
|
||||
```
|
||||
Replace with:
|
||||
```dockerfile
|
||||
# Database migrations run at container startup via docker-entrypoint.sh
|
||||
# DATABASE_URL must be set to a PostgreSQL connection string
|
||||
```
|
||||
|
||||
**Line 49** — Keep `prisma` global install (needed for `migrate deploy` at runtime).
|
||||
|
||||
**Line 54** — Remove the SQLite default DATABASE_URL:
|
||||
```dockerfile
|
||||
ENV DATABASE_URL=file:./data/wwv.db
|
||||
```
|
||||
Replace with:
|
||||
```dockerfile
|
||||
# DATABASE_URL must be provided via environment variable (no default)
|
||||
# Example: postgresql://user:pass@host:5432/dbname
|
||||
```
|
||||
|
||||
- [x] **Step 2: Update docker-entrypoint.sh comments**
|
||||
|
||||
Replace lines 2-5 of `docker-entrypoint.sh`:
|
||||
```bash
|
||||
# ─── Docker Entrypoint ───────────────────────────────────────
|
||||
# Ensures the SQLite database exists and is migrated before
|
||||
# starting the application. On first run with a fresh volume
|
||||
# the DB file won't exist yet, so we run prisma migrate deploy.
|
||||
```
|
||||
|
||||
With:
|
||||
```bash
|
||||
# ─── Docker Entrypoint ───────────────────────────────────────
|
||||
# Ensures the PostgreSQL database is migrated before starting
|
||||
# the application. DATABASE_URL must point to a PostgreSQL
|
||||
# instance (Supabase, self-hosted, etc).
|
||||
```
|
||||
|
||||
Remove `mkdir -p ./data` from line 9 (no longer creating a local SQLite file):
|
||||
```bash
|
||||
set -e
|
||||
|
||||
echo "[entrypoint] Running database migrations..."
|
||||
prisma migrate deploy
|
||||
echo "[entrypoint] Migrations complete."
|
||||
```
|
||||
|
||||
- [x] **Step 3: Commit**
|
||||
|
||||
```powershell
|
||||
git add Dockerfile docker-entrypoint.sh
|
||||
git commit -m "refactor(docker): remove sqlite from build and runtime"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 7: Update Environment Defaults and Dev Scripts
|
||||
|
||||
**Files:**
|
||||
- Modify: `.env:1`
|
||||
- Modify: `package.json:13` (predev script)
|
||||
- Modify: `local-dev.ps1`
|
||||
|
||||
- [x] **Step 1: Update .env default DATABASE_URL**
|
||||
|
||||
Replace line 1 of `.env`:
|
||||
```
|
||||
DATABASE_URL=file:./data/wwv.db
|
||||
```
|
||||
|
||||
With:
|
||||
```
|
||||
# PostgreSQL connection string.
|
||||
# For local dev: run `npx prisma dev` and use the URL it prints.
|
||||
# For production: set to your Supabase/Postgres connection string.
|
||||
# DATABASE_URL=postgresql://postgres:[email protected]:5432/worldwideview
|
||||
```
|
||||
|
||||
> **Important:** The default is now commented out. The `.env.local` file (or `npx prisma dev`) must provide the actual value. This forces contributors to explicitly set up their database rather than silently falling back to a potentially broken SQLite path.
|
||||
|
||||
- [x] **Step 2: Simplify the predev script**
|
||||
|
||||
In `package.json`, the `predev` script currently runs `npx prisma migrate deploy`. This will fail if no Postgres is running. Change it to only copy Cesium assets and generate the Prisma client:
|
||||
|
||||
```json
|
||||
"predev": "npx prisma generate && node scripts/copy-cesium.mjs",
|
||||
```
|
||||
|
||||
> **Rationale:** `prisma migrate deploy` should only run in production (Docker entrypoint) or explicitly by the developer. During local dev, `npx prisma dev` handles migrations automatically.
|
||||
|
||||
- [x] **Step 3: Update local-dev.ps1**
|
||||
|
||||
Replace the entire contents of `local-dev.ps1`:
|
||||
|
||||
```powershell
|
||||
Write-Host "[*] Setting up WorldWideView for Local Development..."
|
||||
|
||||
# Check for pnpm
|
||||
try {
|
||||
$null = Get-Command pnpm -ErrorAction Stop
|
||||
} catch {
|
||||
Write-Host "[Error] pnpm is not installed or not in PATH."
|
||||
Write-Host "Please install it first: https://pnpm.io/installation"
|
||||
exit 1
|
||||
}
|
||||
|
||||
Write-Host "[*] Installing dependencies..."
|
||||
pnpm install
|
||||
|
||||
Write-Host "[*] Running initial setup (generating secrets)..."
|
||||
pnpm run setup
|
||||
|
||||
Write-Host "[*] Generating Prisma client..."
|
||||
npx prisma generate
|
||||
|
||||
# Check for the sibling Data Engine repository
|
||||
if (-not (Test-Path "../wwv-data-engine")) {
|
||||
Write-Host ""
|
||||
Write-Host "=====================================================================" -ForegroundColor Yellow
|
||||
Write-Host "[!] NOTICE: Local Data Engine not found at ../wwv-data-engine" -ForegroundColor Yellow
|
||||
Write-Host ""
|
||||
Write-Host "Frontend-Only Mode: You are developing the frontend UI." -ForegroundColor Green
|
||||
Write-Host "WorldWideView will automatically stream data from the Cloud Engine." -ForegroundColor Green
|
||||
Write-Host ""
|
||||
Write-Host "Full-Stack Mode: If you want to develop backend data seeders, you" -ForegroundColor Cyan
|
||||
Write-Host "must clone the open-source data engine as a sibling directory:" -ForegroundColor Cyan
|
||||
Write-Host " cd ..; git clone https://github.com/silvertakana/wwv-data-engine"
|
||||
Write-Host " cd wwv-data-engine; pnpm install"
|
||||
Write-Host "=====================================================================" -ForegroundColor Yellow
|
||||
Write-Host ""
|
||||
}
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "=====================================================================" -ForegroundColor Cyan
|
||||
Write-Host "[!] DATABASE SETUP REQUIRED" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
Write-Host "WorldWideView uses PostgreSQL. Choose one option:" -ForegroundColor White
|
||||
Write-Host ""
|
||||
Write-Host " Option A (Easiest): Run Prisma's built-in local database:" -ForegroundColor Green
|
||||
Write-Host " npx prisma dev" -ForegroundColor Yellow
|
||||
Write-Host " (Copy the DATABASE_URL it prints into your .env.local file)" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
Write-Host " Option B: Use your own PostgreSQL or Supabase instance:" -ForegroundColor Green
|
||||
Write-Host " Set DATABASE_URL in .env.local to your connection string" -ForegroundColor Gray
|
||||
Write-Host "=====================================================================" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
|
||||
Write-Host "[*] Starting local Next.js frontend server..."
|
||||
Write-Host " (To run the data engine backends concurrently, run: pnpm dev:all)"
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
- [x] **Step 4: Commit**
|
||||
|
||||
```powershell
|
||||
git add .env package.json local-dev.ps1
|
||||
git commit -m "refactor(dev): update env defaults and dev scripts for postgresql"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 8: Run Tests and Validate
|
||||
|
||||
**Files:**
|
||||
- No file changes — validation only
|
||||
|
||||
- [x] **Step 1: Generate Prisma client**
|
||||
|
||||
```powershell
|
||||
npx prisma generate
|
||||
```
|
||||
|
||||
Expected: `Generated Prisma Client to ./src/generated/prisma`
|
||||
|
||||
- [x] **Step 2: Run the test suite**
|
||||
|
||||
```powershell
|
||||
pnpm test
|
||||
```
|
||||
|
||||
Expected: All tests pass. The repository tests mock `db.ts`, so the adapter change should be transparent to them.
|
||||
|
||||
- [x] **Step 3: Start the dev server**
|
||||
|
||||
Ensure your `.env.local` has a valid `DATABASE_URL` pointing to PostgreSQL, then:
|
||||
|
||||
```powershell
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
Expected: Server starts at `http://localhost:3000` without `P3005` or `P3018` errors.
|
||||
|
||||
- [x] **Step 4: Verify database operations work**
|
||||
|
||||
1. Navigate to `http://localhost:3000/setup` — create a test user
|
||||
2. Log in
|
||||
3. Open the Plugins panel — verify installed plugins load
|
||||
4. Star a favorite entity — verify it persists across reload
|
||||
|
||||
- [x] **Step 5: Final commit**
|
||||
|
||||
```powershell
|
||||
git add -A
|
||||
git commit -m "test(db): verify postgresql-only adapter works end-to-end"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Post-Implementation Notes
|
||||
|
||||
### For the `feature/cloud-hosting-core` merge
|
||||
|
||||
When merging the cloud-hosting-core branch back into main, the `src/core/adapters/db.ts` file with `applyTenantIsolation()` should be integrated into `src/lib/db.ts` as a wrapper around the single `PrismaPg` adapter. The conditional SQLite path in that file can be completely removed.
|
||||
|
||||
### For self-hosted Docker users
|
||||
|
||||
Add a note to the release changelog:
|
||||
|
||||
> **Breaking Change:** WorldWideView now requires a PostgreSQL database. SQLite is no longer supported.
|
||||
> Self-hosted users must provide a `DATABASE_URL` environment variable pointing to a PostgreSQL instance.
|
||||
> The easiest option is a free Supabase project, or run `docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=pass postgres:17-alpine` alongside your WWV container.
|
||||
|
||||
### For the migrate-aviation-history.ts script
|
||||
|
||||
This script uses `better-sqlite3` directly to talk to the data engine's separate SQLite database (not the platform database). It is unrelated to this migration and can remain as-is. If `better-sqlite3` is needed for this script, install it as a `devDependency` only, or move the script to the data engine repo where it belongs.
|
||||
@@ -0,0 +1,169 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: Architecture rules and conventions for the WorldwideView Next.js 16 frontend application, state management, and CesiumJS integration.
|
||||
---
|
||||
|
||||
# WorldwideView Application Architecture
|
||||
|
||||
## 1. Core Framework
|
||||
- Built on **Next.js 16 (App Router)** with `output: "standalone"`.
|
||||
- Uses **React 19** and **TypeScript 5** (strict mode).
|
||||
- **Styling**: Strictly Vanilla CSS. No Tailwind or CSS-in-JS.
|
||||
- **Component File Size**: Max 150 lines per file. Split components, extract helpers, and use hooks for anything larger.
|
||||
|
||||
## 2. State & Event Bus
|
||||
- **Zustand**: Slices handle global state (`globe`, `layers`, `timeline`, `ui`, `filter`, `data`, `config`, `favorites`, `geojson`).
|
||||
- **DataBus**: Custom typed pub/sub singleton (`DataBus.getInstance().emit()`) decoupling React components from background WebSocket streams.
|
||||
|
||||
## 3. Edition System
|
||||
Features are controlled by `NEXT_PUBLIC_WWV_EDITION`:
|
||||
- `local`: Self-hosted, full features, auth.
|
||||
- `cloud`: Managed instance.
|
||||
- `demo`: Public demo, no auth.
|
||||
|
||||
## Source Layout
|
||||
|
||||
|
||||
```
|
||||
worldwideview/
|
||||
├── .agents/ # AI agent workflows, rules, memories, skills
|
||||
├── docs/ # Public-facing documentation
|
||||
├── artifacts/
|
||||
│ └── context/ # ← THIS FOLDER — private source of truth (not committed)
|
||||
├── packages/ # Plugin packages (workspaces)
|
||||
├── public/ # Static assets (Cesium assets, GeoJSON data files)
|
||||
├── scripts/ # Build/utility scripts (copy-cesium.mjs, scaffold-osm-plugin.mjs, etc.)
|
||||
└── src/
|
||||
├── app/ # Next.js App Router (layouts, pages, API routes)
|
||||
├── components/ # React UI components (HUD, LayersPanel, Panels, Sidebar)
|
||||
├── core/
|
||||
│ ├── data/ # DataBus, PollingManager, CacheLayer
|
||||
│ ├── globe/ # Cesium hooks, viewer lifecycle, primitive collections
|
||||
│ └── plugins/ # Plugin registry, lifecycle, loaders
|
||||
├── lib/ # Shared utilities, server-side logic
|
||||
│ └── marketplace/ # Marketplace bridge (auth, token, CORS, repository)
|
||||
└── plugins/ # Built-in feature plugins (aviation, maritime, borders, etc.)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Breakdown
|
||||
|
||||
### `src/core/data/` — The Heartbeat
|
||||
|
||||
- **DataBus**: Decentralized event pipeline for all system actions. Plugins emit, components subscribe.
|
||||
- **PollingManager**: Intelligent scheduler for external API calls with exponential backoff.
|
||||
- **CacheLayer**: 2-stage persistent caching — In-Memory + IndexedDB (`worldwideview-cache`).
|
||||
|
||||
### `src/core/globe/` — Rendering Engine
|
||||
|
||||
- **Cesium Integration**: Low-level control over the Cesium Viewer and Primitive Collections.
|
||||
- **EntityRenderer**: High-performance Primitive-based renderer. See `Primitives vs. Entities` below.
|
||||
- **Spiderifier & Clustering Engine** (`StackManager.ts` & `stackAnimation.ts`):
|
||||
- Automatically identifies overlapping entities and groups them into geometrically balanced clusters (concentric rings for <18 density, Fermat's golden spiral for massive stacks).
|
||||
- **Mobile Layout Constraints**: Integrates responsive coordinate geometry. Modifies logical icon dimensions via `iconUpscaler.ts` (32px mobile / 48px desktop) and scales the radial expansion offsets proportionally by 70% on mobile displays to ensure tight, aesthetically pleasing clusters without massive gaps.
|
||||
- **Z-Fighting Mitigation**: Clustering involves highly frequent stack rebuild cycles on any zoom/pan delta. To prevent chaotic render flickering, the global `AnimationLoop` explicitly yields visibility management to `stackAnimation.ts` via `isEntityClustered()`. Items transitioning into the `collapsed` state intentionally bypass animation lerping (to prevent 220ms ghost visibility bleed) and mathematically cloak themselves instantly.
|
||||
- Globe is initialized via `GlobeView.tsx`. Viewer instance passed via `CesiumContext`.
|
||||
|
||||
### `src/core/plugins/` — Plugin System
|
||||
|
||||
- **PluginManager**: Registers, boots, and destroys plugins. Enforces capability checks.
|
||||
- **Loaders**: Plugins are dynamically imported at runtime as ES module bundles (`loadPluginFromManifest`). The legacy `StaticDataPlugin` and `DeclarativePlugin` runtimes are fully deprecated.
|
||||
- **Manifest Requirement**: All plugins MUST include a `"worldwideview"` manifest block in their `package.json` (containing `id`, `icon`, `category`, and `format`). This is strictly required by the Marketplace in order to parse display attributes correctly.
|
||||
|
||||
---
|
||||
|
||||
## Performance: Primitives vs. Entities
|
||||
|
||||
**Core design decision:** Use Cesium `Primitive` API instead of the high-level `Entity` API for high-count datasets.
|
||||
|
||||
| Feature | Entity API | Primitive API (WWV) |
|
||||
|---|---|---|
|
||||
| **Abstraction** | High (easy to use) | Low (direct GPU access) |
|
||||
| **JS Overhead** | Significant per-entity objects | Minimal (batched draw calls) |
|
||||
| **Max Capacity** | ~1,000 entities | **100,000+ points/billboards** |
|
||||
| **WWV Use Case** | Info window / detail panel content | Live data point visualization |
|
||||
|
||||
Specifically: `PointPrimitiveCollection` and `BillboardCollection` ensure 60FPS even with dense global data. The full migration from Entity-based rendering to Primitives was completed to eliminate severe FPS drops.
|
||||
|
||||
---
|
||||
|
||||
## Globe Occlusion & Depth Testing
|
||||
|
||||
- **Correct approach:** `depthTestAgainstTerrain = false` — uses GPU to depth-test against the smooth WGS84 ellipsoid. Icons visible on the near hemisphere, correctly occluded behind Earth.
|
||||
- **Avoid:** `eyeOffset`, `disableDepthTestDistance` hacks that push entities in front of everything. These cause icons to bleed through the globe.
|
||||
- The Plugin SDK's `CesiumEntityOptions` exposes this via `disableDepthTestDistance` when absolutely needed for specific usecases.
|
||||
|
||||
---
|
||||
|
||||
## Data Pipeline (Example: Aviation)
|
||||
|
||||
```
|
||||
Remote API (e.g. OpenSky)
|
||||
↓ [raw JSON, every ~30s via PollingManager]
|
||||
Plugin (e.g. AviationPlugin)
|
||||
↓ [parse, filter, sanitize → GeoEntity[]]
|
||||
DataBus.emit("dataUpdated", { entities })
|
||||
↓
|
||||
EntityRenderer [batched Primitive update]
|
||||
↓
|
||||
GPU (CesiumJS) → 60FPS visualization
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Database (Unified PostgreSQL)
|
||||
|
||||
**Location:** We have migrated from a fragmented SQLite + PostgreSQL setup to a unified **PostgreSQL** architecture using Prisma 7 with the `@prisma/adapter-pg` driver. This enables true multi-tenant cloud capability, real-time sync, and scalable connection pooling via `DATABASE_URL`.
|
||||
|
||||
**Next.js Core Tables:**
|
||||
| Model | Table | Purpose |
|
||||
|---|---|---|
|
||||
| `User` | `users` | Auth accounts (email, bcrypt password, role) |
|
||||
| `InstalledPlugin` | `installed_plugins` | Marketplace plugin install records |
|
||||
| `Setting` | `settings` | Key-value app config (Cesium token, map style, etc.) |
|
||||
| `Tenant` | `tenants` | Multi-tenant organization boundaries |
|
||||
|
||||
**Data Engine Tables:**
|
||||
Managed explicitly via optimized queries in `packages/wwv-data-engine/src/db.ts` targeting PostgreSQL to maximize ingest performance.
|
||||
Includes tables like `iranwar_events`, `earthquakes`, `wildfires`, and `maritime_history`.
|
||||
|
||||
> [!WARNING]
|
||||
> **Catastrophic Time-Series Polling (The Lookback Trap):**
|
||||
> High-frequency polling (e.g. 6,000 aircraft every 10s) accumulates millions of rows rapidly.
|
||||
> - **DO NOT** query unindexed columns (like `ts`) for lookback/freshness without a dedicated index, otherwise you will trigger full table scans and 500 Route timeout errors.
|
||||
> - **REQUIRED:** Implement aggressive data retention / hourly pruning via `scheduler.ts` to prevent infinite table growth.
|
||||
> - **PREFERRED:** Keep real-time / spatial lookbacks in Redis (like `getLiveSnapshot()`), and leave PostgreSQL strictly for historical chronological replays that hit standard indices.
|
||||
|
||||
**Hot-Caching (Redis) & Connection Rules:**
|
||||
The `wwv-data-engine` polls external APIs, dumps raw payloads to PostgreSQL for historical persistence, and broadcasts active snapshots via WebSockets while persisting to Upstash Redis. The Next.js frontend fetches initial state from Redis to ensure horizontal scalability.
|
||||
*TLS Connection Requirement:* The `REDIS_URL` mapped in Coolify and `.env.local` must use the `rediss://` protocol for TLS encryption. Attempting to use plain `redis://` with Upstash will cause the connection to drop (`ECONNRESET`) and throw a `MaxRetriesPerRequestError (which is 3)` inside the data engine.
|
||||
*Upstash Request Limit Throttling:* Due to Upstash Serverless billing (capped at 10k requests/day or 500k/month on free tier), the data engine decouples WebSocket live broadcasting from Redis persistence. High-frequency scrapers (like Aviation) run every 15 seconds to push WebSockets, but the backend forces a **5-minute throttle** before saving the next snapshot to Upstash using `zlib` compression. This executes just 2 commands (`SET` and `EXPIRE`) per 5 minutes per scraper, completely eliminating `max requests limit exceeded` errors while retaining real-time frontend updates.
|
||||
|
||||
**Resilience (Data Self-Healing):**
|
||||
Even with persistent PostgreSQL, critical history (like `iranwarlive` events) should be bundled as `seed.json` or `history.csv` artifacts. If the Data Engine detects an empty table, it MUST parse its built-in fallback seed to hydrate the database and Redis, ensuring 100% data recovery without manual intervention.
|
||||
|
||||
**Dynamic Engine URL Resolution:**
|
||||
The decoupled Data Engine lives at `http://localhost:5001` during local development, and deploys to `https://dataengine.worldwideview.dev` in production. The Next.js frontend injects this context directly into the plugin via the `ctx.env` object (specifically reading from `NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL` environment variables). Plugins resolve their required backend natively by parsing `this.context.env.DATA_ENGINE_URL`. The legacy `globalThis.__WWV_ENGINE_URL__` proxy approach has been fully deprecated.
|
||||
|
||||
---
|
||||
|
||||
## Settings Architecture
|
||||
|
||||
User-configurable values live in the `settings` table (not `.env`). They can be updated without rebuilds.
|
||||
|
||||
| Setting Type | Where | Example |
|
||||
|---|---|---|
|
||||
| **Infrastructure** | `.env` | `DATABASE_URL`, `NEXT_PUBLIC_WWV_EDITION` |
|
||||
| **User settings** | `settings` table (DB) | Cesium token, map style, API keys |
|
||||
|
||||
**Setup Wizard:** If `cesium_token` is missing from the DB on first load, the app shows a setup wizard. Plugin-level wizards work the same way — plugin declares required settings in its manifest; if missing, it renders a setup form instead of data.
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
- **Single Responsibility:** Plugins only handle data mapping — they don't know about UI or cache.
|
||||
- **Dependency Inversion:** `PluginManager` communicates via the `WorldPlugin` interface — new plugins don't require core changes.
|
||||
- **Event-Driven:** Components subscribe to what they need via DataBus — no prop-drilling.
|
||||
- **Defensive Programming:** All external calls wrapped in error boundaries + `PollingManager` backoff.
|
||||
@@ -0,0 +1,217 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: Cloud edition implementation details, PostgreSQL Row-Level Security (RLS) isolation, cross-subdomain auth, and cryptographic license keys.
|
||||
---
|
||||
|
||||
# WorldWideView — Cloud & Auth Architecture
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
> **This file contains the master plan and advanced implementation details for the future Cloud edition.**
|
||||
> It covers single-container multi-tenancy, PostgreSQL Row-Level Security (RLS) isolation, cross-subdomain auth, and cryptographic license keys. It is intended for AI reference when building multi-tenant or auth-related features.
|
||||
|
||||
---
|
||||
|
||||
## Auth Strategy
|
||||
|
||||
**Auth.js (NextAuth)** is the single auth API across all editions. `app.worldwideview.dev` owns **all auth UI** — login, registration, password reset. No other subdomain ever shows a login or registration form.
|
||||
|
||||
```typescript
|
||||
// src/lib/auth.ts
|
||||
const providers = isCloud
|
||||
? [SupabaseProvider({ /* delegates to Supabase Auth (GoTrue) */ })]
|
||||
: [Credentials({ /* local bcrypt + PostgreSQL */ })];
|
||||
|
||||
export const { auth, signIn, signOut } = NextAuth({ providers });
|
||||
```
|
||||
|
||||
Application code is **identical** across editions — always calls `auth()`, `signIn()`, `signOut()`.
|
||||
|
||||
**One account for the entire ecosystem:**
|
||||
- Cloud instance (`[user].app.worldwideview.dev`)
|
||||
- Marketplace (browse, install, publish) — via SSO redirect
|
||||
- Local instance Bridge API connection
|
||||
|
||||
**Marketplace never owns auth UI** — it redirects to `app.worldwideview.dev/login?redirect_to=marketplace...` for all sign-in.
|
||||
|
||||
---
|
||||
|
||||
## Registration & Auto-Provisioning
|
||||
|
||||
Registration: `app.worldwideview.dev/register`
|
||||
|
||||
```
|
||||
1. User fills: email, password, username (= subdomain)
|
||||
2. Account created (Supabase Auth)
|
||||
3. Tenant row inserted instantly → [username].app.worldwideview.dev is live
|
||||
4. User lands on their instance → Setup Wizard (Cesium token)
|
||||
```
|
||||
|
||||
**Subdomain validation:** alphanumeric + hyphens, min 3 chars, not already taken.
|
||||
**Reserved names:** `www`, `app`, `api`, `demo`, `marketplace`, `docs`, `status`, `admin`, `cdn`, `blog`, `changelog`
|
||||
|
||||
"Provisioning" is just inserting a database row — no container to spin up (multi-tenant shared app).
|
||||
|
||||
---
|
||||
|
||||
## Multi-Tenant Architecture
|
||||
|
||||
**One Docker container, RLS isolation.** All cloud tenants share one Next.js deployment. Data isolation enforced at the **PostgreSQL database level** via Row-Level Security:
|
||||
|
||||
```
|
||||
nginx (wildcard *.app.worldwideview.dev)
|
||||
→ reads subdomain → passes X-Tenant-ID header
|
||||
→ single WWV Docker container (Next.js)
|
||||
→ middleware reads X-Tenant-ID
|
||||
→ sets app.tenant_id in DB connection
|
||||
→ RLS scopes ALL queries to that tenant
|
||||
```
|
||||
|
||||
```sql
|
||||
ALTER TABLE installed_plugins ENABLE ROW LEVEL SECURITY;
|
||||
CREATE POLICY tenant_isolation ON installed_plugins
|
||||
USING (tenant_id = current_setting('app.tenant_id')::uuid);
|
||||
```
|
||||
|
||||
PostgreSQL **physically refuses** to return other tenants' rows — even application bugs cannot leak data.
|
||||
|
||||
> Schema-per-tenant (stronger isolation) can be offered later for enterprise. The `tenant_id` design makes migration straightforward.
|
||||
|
||||
### Security Analysis
|
||||
|
||||
| Concern | Risk | Mitigation |
|
||||
|---|---|---|
|
||||
| Data bleed between tenants | 🔴 Critical | RLS enforced at PostgreSQL level |
|
||||
| One tenant crashes the app | 🟡 Medium | Next.js request isolation. Rate limit per tenant at nginx |
|
||||
| One tenant hammers CPU | 🟡 Medium | Rate limiting at nginx (req/min per subdomain) |
|
||||
| Plugin code between tenants | 🟢 Low | Plugins run in the user's **browser**, not the server |
|
||||
| Server crash from users | 🟢 Low | Users can't run arbitrary server code. Rate limits handle abuse |
|
||||
|
||||
---
|
||||
|
||||
## Storage & Database
|
||||
|
||||
| Feature | Local | Cloud |
|
||||
|---|---|---|
|
||||
| **Database queries** | Prisma → PostgreSQL | Prisma → PostgreSQL (Supabase) |
|
||||
| **Auth** | None (single owner) | Supabase Auth (GoTrue) |
|
||||
| **File storage** | Local filesystem (`data/`) | Supabase Storage |
|
||||
| **Storage limit** | ∞ (your disk) | Quota enforced per tier |
|
||||
|
||||
**Prisma is write-once, deploy-anywhere** — the same queries and schema work on both databases. `DATABASE_URL` in `.env` is the only difference.
|
||||
|
||||
---
|
||||
|
||||
## Tier Matrix
|
||||
|
||||
| Deployment | `NEXT_PUBLIC_WWV_EDITION` | License Key | Users | Storage |
|
||||
|---|---|---|---|---|
|
||||
| **Demo** | `demo` | none | ∞ (anonymous, read-only) | N/A |
|
||||
| Local Free | `local` | none | 1 (owner) | ∞ |
|
||||
| Local Pro | `local` | Pro key | 1 (owner) | ∞ |
|
||||
| Local Team | `local` | Team key | Unlimited | ∞ |
|
||||
| Cloud Free | `cloud` | none | 3 | 500 MB |
|
||||
| Cloud Pro | `cloud` | Pro key | 20 | 5 GB |
|
||||
| Cloud Enterprise | `cloud` | Enterprise key | Unlimited | 50 GB+ |
|
||||
|
||||
### Cryptographic License Keys
|
||||
|
||||
Paid features gated by **RSA-signed JWTs** — users cannot forge them by flipping flags:
|
||||
|
||||
```typescript
|
||||
// Marketplace signs (PRIVATE key — only you have this):
|
||||
const licenseKey = jwt.sign(
|
||||
{ tier: "pro", exp: "2027-01-01", org: "acme-corp" },
|
||||
PRIVATE_KEY, { algorithm: "RS256" }
|
||||
);
|
||||
|
||||
// WWV verifies (PUBLIC key — hardcoded in codebase):
|
||||
const license = jwt.verify(process.env.WWV_LICENSE_KEY, PUBLIC_KEY);
|
||||
// license.tier = "free" | "pro" | "team"
|
||||
```
|
||||
|
||||
### Storage Quota (Cloud Only)
|
||||
|
||||
- **Counts:** Imported GeoJSON, plugin data history, uploaded assets
|
||||
- **NOT counted:** Built-in plugin real-time data (transient)
|
||||
- **Quota exceeded:** Upgrade prompt, reject new imports, allow read access
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Local `.env`
|
||||
```env
|
||||
NEXT_PUBLIC_WWV_EDITION=local
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/wwv?schema=public
|
||||
```
|
||||
|
||||
### Cloud `.env`
|
||||
```env
|
||||
NEXT_PUBLIC_WWV_EDITION=cloud
|
||||
DATABASE_URL=postgresql://...
|
||||
NEXT_PUBLIC_SUPABASE_URL=https://[project].supabase.co
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
|
||||
SUPABASE_SERVICE_ROLE_KEY=eyJ...
|
||||
WWV_TENANT_MODE=rls
|
||||
WWV_STORAGE_PROVIDER=supabase
|
||||
```
|
||||
|
||||
### Demo `.env`
|
||||
```env
|
||||
NEXT_PUBLIC_WWV_EDITION=demo
|
||||
DATABASE_URL=postgresql://...
|
||||
```
|
||||
|
||||
`.env` is **infrastructure only** — things the operator sets once. Everything user-configurable lives in the `settings` DB table.
|
||||
|
||||
---
|
||||
|
||||
## Edition Adapters
|
||||
|
||||
Three thin files are all that differs between editions — everything else is edition-unaware:
|
||||
|
||||
| Adapter | Local | Cloud | Demo |
|
||||
|---|---|---|---|
|
||||
| `src/core/auth.ts` | Auth.js `Credentials` (bcrypt + PostgreSQL) | Auth.js `@auth/supabase-adapter` | Disabled |
|
||||
| `src/core/storage.ts` | `fs.writeFile()` to `data/` | Supabase Storage SDK | Read-only |
|
||||
| `src/core/tenant.ts` | No-op (single tenant) | Sets `app.tenant_id` for RLS | No-op |
|
||||
|
||||
---
|
||||
|
||||
## Bot Prevention (Layered)
|
||||
|
||||
| Layer | What | Cost |
|
||||
|---|---|---|
|
||||
| **Email verification** | Supabase Auth built-in | Free |
|
||||
| **Rate limiting** | 3 signups per IP per hour (nginx) | Free |
|
||||
| **Cloudflare Turnstile** | Invisible CAPTCHA on signup | Free |
|
||||
| **Cloudflare Bot Fight Mode** | Auto-enabled on free tier | Free |
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
```
|
||||
Push to silvertakana/worldwideview
|
||||
→ GitHub Actions: build Docker image
|
||||
→ Push to ghcr.io/silvertakana/worldwideview:latest
|
||||
→ Coolify webhook triggers
|
||||
→ Rolling restart (zero downtime)
|
||||
```
|
||||
|
||||
### `worldwideview-cloud/docker-compose.yml` (concept)
|
||||
```yaml
|
||||
services:
|
||||
wwv-cloud:
|
||||
image: ghcr.io/silvertakana/worldwideview:latest
|
||||
environment:
|
||||
NEXT_PUBLIC_WWV_EDITION: cloud
|
||||
DATABASE_URL: ${SUPABASE_PG_URL}
|
||||
SUPABASE_URL: ${SUPABASE_URL}
|
||||
SUPABASE_ANON_KEY: ${SUPABASE_ANON_KEY}
|
||||
labels:
|
||||
- "traefik.http.routers.wwv.rule=HostRegexp(`{user:[a-z0-9-]+}.app.worldwideview.dev`)"
|
||||
```
|
||||
|
||||
The cloud repo (`worldwideview-cloud`) holds **no application logic** — it is purely a thin deployment configuration layer that pulls versioned Docker images.
|
||||
@@ -1,150 +0,0 @@
|
||||
# Coding Principles
|
||||
|
||||
You are about to write or modify code. **Read this file first.** It exists to prevent accumulated coupling and band-aids that turn a clean codebase into a fragile one.
|
||||
|
||||
## The Hard Rule
|
||||
|
||||
> **Always interface-based, extensible, composable, modular. Never band-aids on band-aids.**
|
||||
|
||||
If you find yourself adding a flag, an `if`-check, or a special case to make a problem go away, you are probably band-aiding. Stop and find the seam where the abstraction broke. Fix it there.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Interfaces before implementations
|
||||
Define the contract first. Public functions accept the interface, not the concrete type.
|
||||
```ts
|
||||
// Yes
|
||||
function attachSource(source: DataSource) { ... }
|
||||
// No
|
||||
function attachPostgresSource(pg: PostgresInstance) { ... }
|
||||
```
|
||||
When a pattern repeats across two modules, refactor it into an interface immediately. Don't wait for the third copy.
|
||||
|
||||
### 2. Loose coupling through explicit contracts
|
||||
Components communicate through well-defined contracts (typed signatures, events, registries). Pick one and make it the only path.
|
||||
Components do **not** communicate through:
|
||||
- Direct imports of each other's internal modules
|
||||
- Shared mutable state outside the contract
|
||||
- "Just this once" backdoors
|
||||
If you are tempted to write `import { internalThing } from '../other-module/internal'`, you are doing it wrong. Propose adding it to the public contract or solve it elsewhere.
|
||||
|
||||
### 3. Domain boundaries are sacred
|
||||
Each domain owns its own state and surface. Cross-domain access is **explicit, gated, and audited**.
|
||||
**Forbidden:**
|
||||
- Reading another domain's storage directly
|
||||
- Calling another domain's private functions
|
||||
- Hardcoded `if (tenant === 'X')` branches in shared code
|
||||
**Allowed:**
|
||||
- Calling a documented API on the other domain
|
||||
- A configuration field driving strategy
|
||||
Rule of thumb: If removing a domain requires code archaeology in other domains to untangle internals, the boundary is violated.
|
||||
|
||||
### 4. Don't bend architecture to fit dependencies
|
||||
Use libraries where they fit cleanly; build natively where they don't.
|
||||
- **Library handles:** The specific problem it's good at, in the shape it expects.
|
||||
- **Your code owns:** Your domain, lifecycle invariants, and integration seams.
|
||||
If you find yourself bending your design to fit a library convenience, stop and build it natively or find the correct hook.
|
||||
|
||||
### 5. Data lifetimes are deliberate
|
||||
Different data has different lifetimes. Get this wrong and you'll retain garbage or delete user data.
|
||||
- **Operational telemetry** (logs, metrics) — short rolling window.
|
||||
- **User content** — **permanent unless explicitly deleted.** Never swept by telemetry prunes.
|
||||
- **Resumable session state** — bounded window; archived rather than deleted.
|
||||
Write explicit retention policies for each category separately.
|
||||
|
||||
### 6. Optional features must be truly removable
|
||||
Optional features declare their surface explicitly and communicate via standard contracts. No optional feature reaches into another's internals.
|
||||
Test: **If removing this feature should break the system, it's core. Otherwise it's optional and must be cleanly removable without leaving residue.**
|
||||
|
||||
### 7. Put code where it belongs
|
||||
When a feature spans layers, resist the urge to fold it all into one place "for convenience." Routing across layers is the job — not collapsing them. If a feature needs to write durable state, it extends the layer that owns that state.
|
||||
|
||||
## Antipatterns to Refuse
|
||||
These are common failure modes that calcify a codebase. Refuse them:
|
||||
|
||||
| Antipattern | Better answer |
|
||||
|---|---|
|
||||
| Adding a new flag to an existing function | Extract a strategy interface |
|
||||
| Patching around a bug at the call site | Find the seam where abstraction broke; fix it there |
|
||||
| Direct database access from a feature module | Go through the layer that owns the data |
|
||||
| Hardcoded paths/IDs in business logic | Use configuration or registries |
|
||||
| `if (tenant === 'X')` in shared code | Strategy pattern or per-tenant config |
|
||||
| Inheriting one layer's concerns into another | Cross the boundary through a documented contract |
|
||||
| Inline coupling between layers ("it works") | Draw the contract or merge them honestly |
|
||||
| Adding defensive `try/catch` to swallow errors| Find root cause; gate cleanly at the boundary |
|
||||
| Comment explaining *what* code does | Rename and refactor so the code reads itself |
|
||||
| Copying snippets to "avoid dependency" | Move to a shared module or accept duplicate drift |
|
||||
|
||||
## Debugging Discipline
|
||||
1. **Reproduce it.** Don't trust intuition about what's failing.
|
||||
2. **Find the seam.** Where did the abstraction break? Which contract was violated?
|
||||
3. **Fix at the seam.** Not at the call site. Not at the consumer.
|
||||
4. **If you can't find the seam, surface it.** Tell the user: "this is a design gap; the right fix needs an architectural decision, not a patch."
|
||||
If a fix doesn't work, **don't add another guard on top.** Stacked defensive layers ruin maintainability.
|
||||
|
||||
## Lifecycle Invariants and Mutating Operations
|
||||
To prevent silent corruption and orphan rows:
|
||||
1. **Name the invariant.** E.g., "Closed sessions don't accept work." Write it down.
|
||||
2. **Throw a typed error at the seam.** The function that enforces the invariant must throw a specific typed error, not a silent skip or generic `Error`.
|
||||
3. **Pre-check at every mutating call site *before* reaching the seam.** Pre-check is hygiene; the seam check is correctness. Both are required.
|
||||
4. **Validate, then mutate.** Resolve all inputs/permissions before touching durable state. A validation failure must leave nothing half-applied.
|
||||
5. **Unsafe APIs are still unsafe.** Documenting "don't use when X" is a foot-gun. Make it safe (drain, throw) or remove it.
|
||||
|
||||
## Definition of Done (Checklist)
|
||||
Every code change must satisfy these checklists before merge.
|
||||
|
||||
### Adding a new function
|
||||
- [ ] Belongs strictly in this module.
|
||||
- [ ] Fulfills an existing interface or explicitly adds a new one.
|
||||
- [ ] Has a doc-comment header (purpose, params, returns, throws).
|
||||
- [ ] Has at least one test targeting the contract, not implementation details.
|
||||
- [ ] Communicates via public contracts only (no cross-module internal imports).
|
||||
- [ ] Does not touch storage owned by another component.
|
||||
|
||||
### Updating an existing function
|
||||
- [ ] Reason for change is clear (bug fix, refactor, spec change).
|
||||
- [ ] Doc-comments and tests are updated to reflect the change.
|
||||
- [ ] Fix is applied at the seam, not as a symptom patch.
|
||||
- [ ] No new flags or special cases were added instead of extracting a strategy.
|
||||
|
||||
### Refusal Triggers (STOP)
|
||||
- Adding `if (tenant === 'X')` to shared code.
|
||||
- Adding a flag to make a problem go away.
|
||||
- Direct DB/filesystem access from a feature module.
|
||||
- `try/catch` swallowing an error without gating cleanly.
|
||||
- Skipping tests ("it's trivial") or headers ("it's obvious").
|
||||
- Adding "just another guard" when a guard failed.
|
||||
If any trigger is met, surface it to the user. Do not paper over.
|
||||
|
||||
## Code-Style Minimums
|
||||
|
||||
### Comments & Tests
|
||||
- **Doc-comments:** Every function gets a header (purpose, params, returns, throws). Inline comments explain WHY, not WHAT.
|
||||
- **Tests:** Every function ships with at least one contract test. Storage code must use a real temporary DB instance, not a mock.
|
||||
|
||||
### Logging
|
||||
Log every non-happy-path branch with structured loggers and module-scoped children.
|
||||
- **info**: Expected but noteworthy (e.g., privilege bypass).
|
||||
- **warn**: Rare, worth investigating (e.g., orphan row caught).
|
||||
- **error**: Operator action required (e.g., crash, integration failure).
|
||||
- **debug**: High-volume state changes (include `module` field to filter).
|
||||
Use structured fields (`logger.warn({ id, state }, "msg")`), not interpolated strings.
|
||||
|
||||
### Structure & Dependencies
|
||||
- Keep modules under ~500 lines. Prefer explicit composition over implicit DI.
|
||||
- **Always check registry versions before adding/updating a dependency.** Never use "latest" blindly. Active deprecations are real; pin behind if needed and document why.
|
||||
|
||||
### Doc-vs-Spec Discipline
|
||||
Specs are **functional**, not narrative. They require:
|
||||
- Concrete data structures (schemas, DDL).
|
||||
- Concrete function/API signatures (input/output types).
|
||||
- Concrete event payloads.
|
||||
- Explicit invariants and failure modes.
|
||||
|
||||
## When in Doubt
|
||||
Ask the user explicitly:
|
||||
- "I don't see a clean seam; options are A or B. Which fits?"
|
||||
- "This needs a new contract. Draft it first?"
|
||||
- "I'm about to add a special case. Extract abstraction instead?"
|
||||
|
||||
Don't ship band-aids and ask forgiveness later.
|
||||
@@ -10,7 +10,7 @@ This specification ensures that any agent maintains persistent, accurate project
|
||||
## 2. Synchronization Target
|
||||
The agent MUST orient itself by immediately reading:
|
||||
1. `c:\dev\worldwideview\AGENTS.md` (The root index of all technical stack details)
|
||||
2. `c:\dev\worldwideview\.agents\context\01-platform-overview.md` (The high-level platform goals)
|
||||
2. `c:\dev\worldwideview\.agents\rules\platform-architecture.md` (The high-level platform goals)
|
||||
|
||||
If deep technical rules are required for a specific domain (e.g., UI state, Map Rendering, Monorepo management), the agent MUST consult the relevant file in `c:\dev\worldwideview\.agents\rules\`.
|
||||
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
trigger: always_on
|
||||
description: Guidelines for ongoing project maintenance, cleanliness, and self-correction during everyday development tasks.
|
||||
---
|
||||
|
||||
# Continuous Improvement & Maintenance
|
||||
|
||||
As an AI agent working within the WorldWideView project, you are expected to practice the **Boy Scout Rule**: always leave the codebase (and its context) cleaner than you found it.
|
||||
|
||||
While executing your primary programming tasks, you MUST actively abide by these maintenance protocols:
|
||||
|
||||
## 1. Documentation & Rule Parity
|
||||
- **Self-Correction**: If you notice that an architectural choice you are implementing contradicts an existing rule in `.agents/rules/`, you must halt and update the rule file to reflect the new paradigm.
|
||||
- **Dead Context**: If you encounter context, plans, or architectural files referencing deprecated concepts (e.g., legacy microservices, `StaticDataPlugin`), proactively prune or update them.
|
||||
|
||||
## 2. Codebase Cleanliness
|
||||
- **Dead Code**: If you refactor a file and leave behind unused functions, imports, or CSS classes, clean them up immediately. Do not leave "commented out" code unless explicitly requested for future use.
|
||||
- **Console Logs**: Remove debugging `console.log` statements before finalizing a feature, except for structured error logging or critical startup info.
|
||||
- **Sandbox Hygiene**: Any throwaway scripts or debugging tools placed in `/local-scripts/` should be deleted once the underlying issue is resolved, unless they provide permanent utility.
|
||||
|
||||
## 3. Dependency & Typings Checks
|
||||
- **Type Safety**: Never use `any` or `@ts-ignore` as a shortcut when refactoring. Always build the proper TypeScript interfaces.
|
||||
- **Manifest Validation**: Whenever you touch a plugin, ensure its `package.json` `"worldwideview"` manifest block is completely accurate and synced with its capabilities.
|
||||
|
||||
## 4. The "See Something, Say Something" Rule
|
||||
If you spot an unrelated but obvious bug, security vulnerability, or architectural anti-pattern in the file you are editing:
|
||||
1. Fix it if it's a minor, isolated issue (and document the fix in your summary).
|
||||
2. For larger issues, explicitly call it out to the user so it can be added to the technical debt backlog.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: Architecture rules and dependency management guidelines for wwv-data-engine seeders.
|
||||
---
|
||||
|
||||
# Data Engine V2 Architecture & Dependency Loading
|
||||
|
||||
## 1. Engine Versions: V2 vs Legacy
|
||||
The current and only active engine is **`wwv-data-engine-v2`**.
|
||||
- **Legacy Engine**: Previously, data sources ran as isolated, standalone microservices running their own Node environments.
|
||||
- **V2 Engine**: Acts as a unified **"Host Environment" runner**. It is a single Node.js process that dynamically downloads and executes multiple independent seeder bundles (both public community seeders and private seeders).
|
||||
|
||||
## 2. Deployment Architecture
|
||||
- **Single Docker Image**: V2 is deployed via Coolify as a single Docker image, natively mapping environment variables continuously into the container shell.
|
||||
- **Automated Restarts**: Code pushes to the `wwv-data-engine-public` repository automatically trigger a service restart via a secure `COOLIFY_API_TOKEN` configured in the CI/CD pipeline (replacing unreliable generic webhooks).
|
||||
- **Dual-Output Engine**: Seeders in V2 expose both a WebSocket stream (`/stream`) for real-time instantaneous updates, and a REST API endpoint (`/api/:id`) for fetching live data snapshots directly from Redis.
|
||||
|
||||
## 3. Pnpm Workspaces & Dynamic Dependency Loading
|
||||
To prevent seeders from ballooning in size by bundling a massive amount of dependencies, the system heavily relies on `pnpm` workspaces.
|
||||
- **Host Environment**: The V2 engine natively provides common geospatial and utility packages (e.g., `zod`, `ws`, `node-cron`, `undici`, `satellite.js`, `geoip-lite`). Seeders **MUST NOT** bundle these standard dependencies, and should leave them external in `tsup`.
|
||||
- **Dynamic Workspaces**: When V2 loads a compiled `dist/index.mjs` via `node`, it dynamically resolves imports by traversing up to the workspace `node_modules`.
|
||||
|
||||
## 4. Production Deployment & Downloader
|
||||
In production, the `wwv-data-engine-v2` does NOT mount the local file system. Instead:
|
||||
1. `download-seeders.ts` runs on container startup.
|
||||
2. It fetches the latest compiled `seeders.zip` from GitHub Releases for both community and private repositories.
|
||||
3. **CRITICAL STEP:** After unzipping the workspaces into a staging directory (`/app/seeders`), the script dynamically generates a root `package.json` and `pnpm-workspace.yaml`.
|
||||
4. It then runs a single **workspace-aware `pnpm install --prod`**. This ensures all custom unbundled dependencies declared by the extracted plugins are downloaded directly into the container and properly linked together.
|
||||
|
||||
## 5. Namespace Separation Rule
|
||||
To prevent collisions and `404` or `ERR_MODULE_NOT_FOUND` errors, seeders **MUST NOT** exist simultaneously in both the community (`wwv-seeders-community`) and private (`wwv-seeders-private`) repositories. Namespace overlaps will cause module resolution failures when the V2 engine attempts to load them. Private seeders have priority.
|
||||
@@ -0,0 +1,305 @@
|
||||
# Deployment, Testing, and Operations
|
||||
|
||||
## Development Commands
|
||||
|
||||
```bash
|
||||
pnpm install # Install all workspace dependencies
|
||||
pnpm run setup # Generate .env.local with AUTH_SECRET (first-time setup)
|
||||
pnpm dev # Next.js frontend only (auto-runs prisma db push + copy-cesium)
|
||||
pnpm dev:all # Frontend + wwv-data-engine (via Docker Compose) concurrently
|
||||
pnpm dev:backends # Starts the local data engine + Redis via Docker Compose
|
||||
pnpm build # Production build
|
||||
pnpm test # Run all Vitest tests (scoped to src/lib, src/core, src/plugins)
|
||||
pnpm db:reset # Reset and re-migrate the frontend database (destructive)
|
||||
pnpm start:backends # Legacy command for standalone Fastify backends
|
||||
pnpm clean:backends # Wipe all plugin database records
|
||||
pnpm run scaffold-osm-plugin <name> # Generate a new plugin from scaffold
|
||||
pnpm dev:plugins # File watcher for local-plugins/ directory (runs automatically in dev)
|
||||
node packages/wwv-cli/dist/index.js create <name> --local # Scaffold a new local plugin
|
||||
node packages/wwv-cli/dist/index.js link <name> # Promote a local plugin to packages/
|
||||
```
|
||||
|
||||
Frontend runs at `http://localhost:3000`.
|
||||
|
||||
## Deployment
|
||||
|
||||
- **Docker**: Multi-stage Dockerfile using the Extractor Pattern (`deps` → `builder` → `runner`). The `node_modules` folders must be explicitly untracked in from `git` across the workspace to prevent corrupted BuildKit contextual cache overlaps during the `COPY . .` stage.
|
||||
- **Standalone output**: `next.config.ts` uses `output: "standalone"`.
|
||||
- **Cesium assets**: Copied to `public/cesium/` via `scripts/copy-cesium.mjs` at build time, excluded from output tracing.
|
||||
- **Prisma Configuration**: `prisma.config.ts` must export a native javascript object instead of dynamically importing CLI wrapper binaries (`prisma/config` or `dotenv`). The standalone Next.js tracer strips CLI devDependencies during the build, which will cause fatal runtime container crashes if imported.
|
||||
- **Data Engine**: The single runner container defined in `docker-compose.yml`, proxied via `next.config.ts` rewrites.
|
||||
- **Coolify**: Deployed via Dockerfile builder natively mapping environment variables continuously into the container shell.
|
||||
- **Docker volumes**: Ensure PostgreSQL data and Redis volumes are mounted for persistence.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- **Framework**: Vitest with jsdom environment
|
||||
- **Coverage**: `src/lib/**`, `src/core/**`, `src/plugins/**`
|
||||
- **Run**: `pnpm test` (or `vitest run`)
|
||||
- **Key test files**: `rateLimit.test.ts`, `edition.test.ts`, `demoAdmin.test.ts`, `DeclarativePlugin.test.ts`, `cors.test.ts`, `repository.test.ts`, `marketplaceToken.test.ts`
|
||||
|
||||
## Security Headers
|
||||
|
||||
Configured in `next.config.ts` `headers()`:
|
||||
- **CSP**: Restrictive with exceptions for CesiumJS (`unsafe-eval`, `unsafe-inline`), camera streams (`http: https:`), and analytics
|
||||
- **X-Frame-Options**: DENY
|
||||
- **X-Content-Type-Options**: nosniff
|
||||
- **Referrer-Policy**: strict-origin-when-cross-origin
|
||||
- **Permissions-Policy**: camera/microphone disabled, geolocation self-only
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Package Manager
|
||||
|
||||
The project uses **pnpm workspaces**. All `npm` commands in older docs/scripts should be treated as `pnpm`.
|
||||
|
||||
```bash
|
||||
pnpm install # install all workspace deps
|
||||
pnpm run dev # start dev server ONLY (worldwideview/)
|
||||
pnpm run dev:all # start ALL services concurrently (worldwideview, data-engine, marketplace)
|
||||
pnpm run build # production build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Local Dev Setup
|
||||
|
||||
```
|
||||
1. Clone repo
|
||||
2. pnpm install
|
||||
3. pnpm run setup # generates .env.local with AUTH_SECRET, copies .env.example
|
||||
4. pnpm run dev:all # predev: prisma migrate deploy + copy-cesium.mjs → then starts all services
|
||||
5. Open http://localhost:3000
|
||||
```
|
||||
|
||||
**Marketplace:** `cd worldwideview-marketplace && pnpm run dev` → http://localhost:3001
|
||||
|
||||
**Database auto-creates** on first run via `predev` script — no manual DB setup required.
|
||||
|
||||
---
|
||||
|
||||
## Database Operations
|
||||
|
||||
**All SQL from `c:\dev\worldwideview`:**
|
||||
|
||||
```powershell
|
||||
npx prisma db execute --sql "<SQL>"
|
||||
```
|
||||
|
||||
> Stop the dev server first to avoid "database is locked" errors.
|
||||
|
||||
### Common Commands
|
||||
|
||||
```powershell
|
||||
# View row counts (all tables)
|
||||
npx prisma db execute --sql "SELECT 'users' AS t, COUNT(*) AS n FROM users UNION ALL SELECT 'aviation_history', COUNT(*) FROM aviation_history UNION ALL SELECT 'installed_plugins', COUNT(*) FROM installed_plugins UNION ALL SELECT 'settings', COUNT(*) FROM settings;"
|
||||
|
||||
# List installed plugins
|
||||
npx prisma db execute --sql "SELECT pluginId, version, installedAt FROM installed_plugins ORDER BY installedAt DESC;"
|
||||
|
||||
# Clear all installed plugins
|
||||
npx prisma db execute --sql "DELETE FROM installed_plugins;"
|
||||
|
||||
# List settings
|
||||
npx prisma db execute --sql "SELECT key, value FROM settings;"
|
||||
|
||||
# Set/update a setting
|
||||
npx prisma db execute --sql "INSERT INTO settings (key, value) VALUES ('<key>', '<value>') ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value;"
|
||||
|
||||
# Prune aviation history older than 7 days
|
||||
npx prisma db execute --sql "DELETE FROM aviation_history WHERE timestamp < NOW() - INTERVAL '7 days';"
|
||||
|
||||
# Vacuum (reclaim disk space after pruning)
|
||||
npx prisma db execute --sql "VACUUM FULL;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Engine & Data Recovery
|
||||
|
||||
The secondary backend (Data Engine) handles high-volume API ingestion and pushes active snapshots to Upstash Redis. Because its PostgreSQL database is completely wiped on fresh Coolify deployments if volumes aren't preserved, it uses **Self-Healing Architecture**.
|
||||
|
||||
**How Recovery Works:**
|
||||
1. Upon startup, or during the 60-second cron cycle, the seeder checks if the target table (e.g., `iranwar_events`) is empty.
|
||||
2. If empty, the engine instantly hydrates the PostgreSQL database and the Upstash Redis cache from the committed fallback payload (e.g., `data/fallback/iranwar_seed.json`).
|
||||
3. To **force a rapid recovery** locally (such as when testing new scraper data), simply wipe the table and let the minute-tick refill it via `npx prisma db execute --sql "DELETE FROM iranwar_events;"`.
|
||||
|
||||
**OSINT Scraping & Hydration Best Practices:**
|
||||
Utility scripts (like `hydrate.ts`) exist to repair or enrich the fallback seed block offline. Important takeaways from building these scrapers:
|
||||
- **Location Mapping:** Always append structured `_osint_meta.coordinates: {lat, lng}`. Without exact coordinates, the SDK defaults to Null Island or scatters points uniformly across the globe (declutter grid effect).
|
||||
- **Tracking URL Resolution:** News aggregators (like Bing News RSS) wrap URLs in tracking redirect pages (`apiclick.aspx`). Never serve these directly to the frontend. Use `cheerio` to fetch the tracking page, parse the `<noscript><meta refresh="URL=..."></noscript>` node, extract the *actual* news URL, and then scrape the destination article for `og:image` and `og:video` tags.
|
||||
- **Frontend Sync:** Ensure Next.js schema mapping in the plugin (`wwv-plugin-xyz/src/index.ts`) perfectly mirrors the enriched fields so they render correctly in the UI.
|
||||
|
||||
### Schema Changes
|
||||
|
||||
```powershell
|
||||
npx prisma db push # sync schema changes to DB (non-destructive)
|
||||
npx prisma migrate dev --name "<description>" # create + apply a migration
|
||||
npx prisma generate # regenerate Prisma client types after schema change
|
||||
npx prisma studio # visual DB browser at http://localhost:5555
|
||||
```
|
||||
|
||||
### Full Reset
|
||||
|
||||
```powershell
|
||||
# Stop dev server first
|
||||
Remove-Item c:\dev\worldwideview\data\wwv.db
|
||||
npx prisma db push
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
### Browser Cache Clearing
|
||||
|
||||
```javascript
|
||||
// Clear IndexedDB entity cache
|
||||
indexedDB.deleteDatabase("worldwideview-cache");
|
||||
|
||||
// Clear localStorage user API keys
|
||||
Object.keys(localStorage)
|
||||
.filter(k => k.startsWith("wwv_"))
|
||||
.forEach(k => localStorage.removeItem(k));
|
||||
```
|
||||
|
||||
Known `wwv_*` localStorage keys (defined in `src/lib/userApiKeys.ts`):
|
||||
- `wwv_key_google_maps`
|
||||
- `wwv_key_nasa_firms`
|
||||
|
||||
Hard refresh: `Ctrl+Shift+R`
|
||||
|
||||
---
|
||||
|
||||
## DB Troubleshooting
|
||||
|
||||
| Error | Fix |
|
||||
|---|---|
|
||||
| "Database is locked" | Stop the dev server first |
|
||||
| "Table does not exist" | Run `npx prisma db push` |
|
||||
| "Plugin still shows after clearing" | Hard-refresh (`Ctrl+Shift+R`) or clear IndexedDB |
|
||||
| DB file is very large | Prune aviation history + run `VACUUM` |
|
||||
| Prisma client types are stale | Run `npx prisma generate` |
|
||||
|
||||
---
|
||||
|
||||
## Creating Static OSM Plugins
|
||||
|
||||
See full guide: `.agents/skills/osm-static-plugin-creation.md`
|
||||
|
||||
**Quick start:**
|
||||
```bash
|
||||
node scripts/scaffold-osm-plugin.mjs '{
|
||||
"name": "volcanoes",
|
||||
"displayName": "Volcanoes",
|
||||
"osmTag": "natural=volcano",
|
||||
"icon": "Mountain",
|
||||
"color": "#ef4444",
|
||||
"category": "Natural Disaster"
|
||||
}'
|
||||
```
|
||||
|
||||
**Manual Overpass API query (PowerShell):**
|
||||
```powershell
|
||||
$tag = '"natural"="volcano"'
|
||||
$body = "data=[out:json][timeout:300];(node[$tag];way[$tag];relation[$tag];);out center;"
|
||||
Invoke-RestMethod -Uri 'https://overpass-api.de/api/interpreter' -Method Post -Body $body -OutFile 'tmp/raw_data.json'
|
||||
```
|
||||
|
||||
**Note:** OSM data is licensed under **ODbL** — include attribution in plugin READMEs.
|
||||
|
||||
---
|
||||
|
||||
## npm Plugin Publishing
|
||||
|
||||
See full guide: `.agents/skills/version-control/npm-plugin-publishing.md`
|
||||
|
||||
```bash
|
||||
# First-time publish
|
||||
pnpm publish --workspace=packages/wwv-plugin-<name> --access public
|
||||
|
||||
# Future versions — via Trusted Publishing (GitHub Actions CI/CD)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git / Version Control
|
||||
|
||||
See full guide: `.agents/skills/version-control/git-version-control.md`
|
||||
|
||||
**Commit convention:** `feat:`, `fix:`, `chore:`, `docs:` prefixes.
|
||||
**Commit when:** A new feature is completed (per project rules).
|
||||
|
||||
---
|
||||
|
||||
## Security Checks
|
||||
|
||||
See full guide: `.agents/skills/security/security-check.md`
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
**Host Server:**
|
||||
The production Coolify instance runs on a local server at `192.168.68.64`. Direct SSH access: `ssh [email protected]`.
|
||||
|
||||
**CI/CD Flow:**
|
||||
1. Push to `silvertakana/worldwideview`
|
||||
2. Coolify webhook triggers → automated BuildKit deployment on the host server.
|
||||
|
||||
**Coolify Deployment Rules & Gotchas (The "Redis 500k" Rule):**
|
||||
- **Coolify Pulls from GitHub:** Coolify does *not* deploy your local workspace files. It strictly clones the repository from GitHub.
|
||||
- **Push Before You Deploy:** If you make a critical infrastructure or optimization fix locally (e.g., swapping a massive `HSET` pipeline for a compressed 5-min throttled `setLiveSnapshot`), you **must** `git commit` and `git push` those changes to the `main` branch before triggering a Coolify deployment.
|
||||
- **The "Rollback DDOS" Risk:** If you update environmental variables (like a new Upstash Redis URL) inside Coolify and deploy *without* pushing your local optimized code to GitHub, Coolify will pull the *older, unoptimized* repository code and aim it at your new endpoints. This will immediately exhaust the 500,000 requests/month Upstash free limit.
|
||||
- **Redis Connection Errors:** If the data engine crashes on startup with `MaxRetriesPerRequestError: Reached the max retries per request limit (which is 3)` and `ECONNRESET`, the `REDIS_URL` in your Coolify environment variables is incorrectly using `redis://` instead of the TLS-required `rediss://`.
|
||||
- **Immediate Rollback on Failure:** Whenever a Coolify deployment fails or introduces a critical bug (such as rate-limit exhaustion), **immediately select the last known working deployment in the Coolify dashboard and redeploy it.** Do not leave a broken deployment hanging while trying to debug directly in production. Roll back to stability first, debug locally, commit the verified fix, and then deploy forward.
|
||||
- **Public Port Binding:** Both the `wwv` (Next.js frontend) and `wwv-data-engine` containers are meant to be directly exposed to the internet, rather than relying on Traefik internal network routing. They MUST use `ports: - "3000:3000"` and `ports: - "5000:5000"` respectively in `docker-compose.yml`. Using `expose` hides them behind internal Docker routing. Only backend infrastructure like `db` and `wwv-redis` should use `expose`.
|
||||
|
||||
**Local verification:**
|
||||
Before pushing infrastructure changes, run `docker build -t wwv-test .` to verify that the Next.js `standalone` isolated multi-stage build works correctly.
|
||||
|
||||
**Critical Docker/BuildKit Patterns:**
|
||||
- **No Tracked `node_modules`:** Never track `node_modules` in git. It will severely break the Docker `COPY . .` BuildKit cache stage, as it attempts to overwrite the internally symlinked modules from the `deps` stage with the non-symlinked folders from git, causing cryptic `cannot copy to non-directory` errors.
|
||||
- **Prisma 7 in Standalone:** Prisma v7 strictly forbids `url = env("DATABASE_URL")` in `schema.prisma` if `prisma.config.ts` exists. You *must* provide the `url` property in `prisma.config.ts`.
|
||||
- **The `dotenv` Paradox:** Next.js `standalone` output does NOT automatically trace CLI tool devDependencies (like `dotenv`). If you import `dotenv` in `prisma.config.ts`, the production runner container will crash in a reboot loop. *Solution:* `prisma.config.ts` must use native Node `fs` and `path` to gracefully read from `.env` as a fallback, exporting a plain Javascript object without CLI wrappers.
|
||||
- **Standalone Scripts & Next.js Typechecking:** Next.js `pnpm build` triggers `tsc`. By default, this will aggressively typecheck the `scripts/` directory. One-off migration scripts that import backend-only dependencies (like `pg`) will fail the global build. Always ensure `"scripts"` is added to the `"exclude"` array in `tsconfig.json`.
|
||||
- **WSL2 / Docker Memory Bloat:** Next.js `standalone` + `pnpm workspaces` caching takes roughly 7GB to 10GB of virtual disk space and maxes out WSL2 memory during `docker-compose build`. Avoid building complex monorepos locally unless necessary. To reclaim local BuildKit disk space: `docker builder prune -a -f`. To reclaim WSL RAM: `wsl --shutdown`.
|
||||
- **TypeScript NodeNext ESM Extensions:** By default in strict NodeNext ESM, backend scripts compiled via TypeScript (like `server.ts`) require dynamic imports to explicitly list the extension. You MUST write `await import('./routes/index.js')`, even if the underlying code is a `.ts` file, or the Docker compilation will fail with `TS2834`.
|
||||
- **Git vs Docker Context Bloat:** Ensure `.dockerignore` ruthlessly excludes generated artifacts (e.g., `artifacts/`, `performance/`). Ensure `.gitignore` strips large binary caches like heavy database seed files inside `packages/*/data/` to prevent GitHub from bouncing commits exceeding the 100MB chunk limit.
|
||||
- **Host Resource Exhaustion & Implicit Failures:** Complex multi-stage pnpm builds generate massive amounts of intermediate layer cache. If the Coolify host server reaches 100% disk capacity during an active deployment, the build logs will silently truncate and die abruptly with no explicit `pnpm` error. Worse, services like PostgreSQL (`coolify-db`) will instantly crash because they cannot write lock files, causing total system outages. Always maintain at least 30-40GB of free space on deployment hosts before auto-deploying via Coolify.
|
||||
|
||||
|
||||
**Local update:** `git pull && pnpm install && pnpm run dev`
|
||||
|
||||
---
|
||||
|
||||
## Disk Space Management & Monitoring
|
||||
|
||||
The Docker build uses `standalone` output to minimize image size. The `copy-cesium.mjs` script copies only the required Cesium assets into `public/` — avoids shipping the entire Cesium package (300MB+) in the build.
|
||||
|
||||
**Host Server Maintenance:**
|
||||
On Coolify deployment targets (e.g., `192.168.68.64`), dangling BuildKit caches and orphaned images will eventually consume 100% of the disk.
|
||||
- To recover a crashed server: SSH into the host and run `docker system prune -a -f`.
|
||||
- **Proactive Monitoring:** Use the `netdata-remote` MCP server to poll or setup alerts for the host disk space. It is highly recommended to set a warning alert when disk usage exceeds 80%.
|
||||
|
||||
**Application Database Growth:**
|
||||
Aviation history can grow large. Prune regularly:
|
||||
```powershell
|
||||
npx prisma db execute --sql "DELETE FROM aviation_history WHERE timestamp < datetime('now', '-7 days');"
|
||||
npx prisma db execute --sql "VACUUM;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Terminology Quick Reference
|
||||
|
||||
| Term | Definition |
|
||||
|---|---|
|
||||
| **Edition** | `local`, `cloud`, or `demo` — set via `NEXT_PUBLIC_WWV_EDITION`. Drives auth/storage/tenant adapters |
|
||||
| **Bridge API** | Routes in WWV (`/api/marketplace/*`) that the marketplace calls to install/manage plugins |
|
||||
| **Setup Wizard** | First-run config UI — app-level (Cesium token) and plugin-level (plugin API keys) |
|
||||
| **Runtime Settings Store** | `settings` DB table — replaces `.env` for everything user-facing |
|
||||
| **RLS** | Row-Level Security — PostgreSQL feature enforcing tenant data isolation at the DB level |
|
||||
| **Snapshot Capture** | WWV periodically stores plugin data per tenant for history/timeline. Pro/Local only |
|
||||
| **Trust Stamping** | WWV always overwrites `manifest.trust` server-side — no client claims are accepted |
|
||||
| **NpmCache** | DB table caching NPM registry metadata to decouple from live NPM polling |
|
||||
@@ -0,0 +1,69 @@
|
||||
# Directory Structure & Repositories
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
worldwideview/
|
||||
├── src/
|
||||
│ ├── app/ # Next.js App Router (pages, API routes, layouts)
|
||||
│ │ ├── api/ # Server-side API routes (auth, aviation, camera, etc.)
|
||||
│ │ ├── login/ # Login page
|
||||
│ │ ├── setup/ # First-time setup page
|
||||
│ │ └── globals.css # Root stylesheet
|
||||
│ ├── components/
|
||||
│ │ ├── common/ # Shared UI: BootOverlay, FloatingWindow, PluginIcon
|
||||
│ │ ├── layout/ # AppShell, Header, SearchBar, DataBusSubscriber
|
||||
│ │ ├── panels/ # LayerPanel, EntityInfoCard, FilterPanel, GraphicsSettings
|
||||
│ │ ├── timeline/ # Timeline component
|
||||
│ │ ├── marketplace/ # Plugin install/unverified dialogs
|
||||
│ │ ├── ui/ # Tooltip, ReloadToast
|
||||
│ │ └── video/ # Floating video manager
|
||||
│ ├── core/
|
||||
│ │ ├── data/ # DataBus, PollingManager, CacheLayer, SmartFetcher
|
||||
│ │ ├── filters/ # filterEngine (applies plugin filters to entities)
|
||||
│ │ ├── globe/ # GlobeView, EntityRenderer, AnimationLoop, StackManager,
|
||||
│ │ │ │ CameraController, InteractionHandler, SelectionHandler,
|
||||
│ │ │ │ ModelManager, ImageryProviderFactory
|
||||
│ │ │ └── hooks/ # useCameraActions, useEntityRendering, useModelRendering, etc.
|
||||
│ │ ├── hooks/ # useBootSequence, useIsMobile, useMarketplaceSync
|
||||
│ │ ├── plugins/ # PluginManager, PluginRegistry, PluginManifest,
|
||||
│ │ │ │ loadPluginFromManifest, validateManifest, InstalledPluginsLoader
|
||||
│ │ │ └── loaders/ # mapJsonToEntities (Legacy loaders like DeclarativePlugin are deprecated)
|
||||
│ │ └── state/ # Zustand store + slices (config, data, globe, layers, timeline, ui, etc.)
|
||||
│ ├── lib/ # auth, db, rateLimit, analytics, AIS stream, marketplace APIs
|
||||
│ ├── plugins/ # GeoJSON plugin registrations
|
||||
│ ├── styles/ # HUD animations CSS
|
||||
│ ├── types/ # GeoJSON types, Umami types
|
||||
│ └── generated/ # Prisma generated client (gitignored)
|
||||
├── local-plugins/ # Local sandbox for developing plugins (gitignored)
|
||||
├── packages/ # pnpm monorepo workspace packages
|
||||
│ ├── wwv-plugin-sdk/ # Plugin SDK: type definitions, manifest schema
|
||||
│ ├── wwv-plugin-aviation/
|
||||
│ ├── wwv-plugin-maritime/
|
||||
│ ├── wwv-plugin-wildfire/
|
||||
│ ├── wwv-plugin-borders/
|
||||
│ ├── wwv-plugin-camera/
|
||||
│ ├── wwv-plugin-military-aviation/
|
||||
│ ├── wwv-plugin-satellite/
|
||||
│ ├── wwv-plugin-iranwarlive/ # Standalone plugin with custom endpoints
|
||||
│ └── wwv-plugin-{airports,embassies,lighthouses,nuclear,seaports,spaceports,volcanoes}/
|
||||
├── prisma/ # schema.prisma, migrations/
|
||||
├── public/ # Static assets, Cesium workers, plugin GeoJSON data
|
||||
├── scripts/ # Build scripts (copy-cesium, scaffold-osm-plugin, setup)
|
||||
├── data/ # PostgreSQL data volume (gitignored)
|
||||
├── Dockerfile # Multi-stage production build
|
||||
├── docker-compose.yml # Main app + data engine runner + local seeders
|
||||
└── .agents/ # Agent documentation, rules, skills, workflows
|
||||
```
|
||||
|
||||
## Related Repositories
|
||||
|
||||
| Repo | Purpose |
|
||||
|---|---|
|
||||
| `worldwideview` | Main application (this repo) |
|
||||
| `wwv-data-engine` | Generic data engine runner (PUBLIC, runs via Docker) |
|
||||
| `wwv-seeders-community` | Open-source community seeders (PUBLIC) |
|
||||
| `wwv-seeders-private` | Proprietary seeder scripts (PRIVATE, downloaded in prod) |
|
||||
| `worldwideview-marketplace` | Plugin marketplace web app |
|
||||
| `worldwideview-plugins` | Published npm plugin packages (frontend source) |
|
||||
| `worldwideview-web` | Marketing / landing page |
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: A comprehensive guide to the WorldWideView ecosystem repositories in the local C:\dev environment. Use this to determine which repository to edit based on the feature being developed.
|
||||
---
|
||||
|
||||
# Ecosystem Repositories & Development Structure
|
||||
|
||||
The WorldWideView platform is not a single monolith; it is distributed across several repositories. In the local development environment, these repositories are organized as sibling directories under `C:\dev\`.
|
||||
|
||||
If you are asked to implement a feature or fix a bug, you **MUST** determine the correct repository to edit before writing code.
|
||||
|
||||
## Ecosystem Map (C:\dev\)
|
||||
|
||||
| Repository Folder | Purpose & When to Edit |
|
||||
|---|---|
|
||||
| **`worldwideview`** | The main application, Next.js frontend, Cesium globe, UI components, and the core plugin SDK. **Edit here** for anything related to the UI, state, map rendering, or built-in plugin frontend configurations. |
|
||||
| **`wwv-data-engine`** | The V2 Data Engine (Host Environment) that runs the seeders. **Edit here** if you need to modify how the engine parses WebSocket streams, implements REST APIs, downloads seeder bundles, or handles Redis caching. |
|
||||
| **`wwv-seeders`** | The community (public) data seeders. **Edit here** to create or modify background polling scripts (e.g. `aviation.ts`, `wildfire.ts`) that fetch data from public APIs and normalize it into `GeoEntity` arrays. |
|
||||
| **`wwv-seeders-private`** | The proprietary (private) data seeders. **Edit here** for closed-source, premium, or high-security data ingestion scripts. |
|
||||
| **`worldwideview-marketplace`** | The Plugin Marketplace web application. **Edit here** if you are modifying the platform where users browse, purchase, or manage plugin installations. |
|
||||
| **`worldwideview-plugins`** | Independent repository for published npm plugin packages (typically frontend source bundles). |
|
||||
| **`worldwideview-web`** | The marketing site, landing pages, and documentation. |
|
||||
| **`wwv-test`** | A testing ground repository (e.g., for docker-compose setups, scratch testing). |
|
||||
|
||||
## Cross-Repository Workflows
|
||||
|
||||
1. **Adding a New Data Source:**
|
||||
- Write the backend fetcher inside `C:\dev\wwv-seeders` (or `private`).
|
||||
- Write the frontend plugin interface inside `C:\dev\worldwideview` (or dynamically loaded via `worldwideview-plugins`).
|
||||
2. **Fixing Real-Time Streaming Issues:**
|
||||
- Investigate `C:\dev\worldwideview` (for frontend `WsClient` or `DataBus`).
|
||||
- Investigate `C:\dev\wwv-data-engine` (for backend Fastify websocket broadcasting).
|
||||
3. **Pnpm Workspaces:**
|
||||
- The Data Engine V2 automatically combines `community` and `private` seeders at runtime using pnpm workspaces. When testing seeders locally, refer to `C:\dev\worldwideview\local-seeders`.
|
||||
@@ -0,0 +1,17 @@
|
||||
# Environment Variables
|
||||
|
||||
| Variable | Required | Description |
|
||||
|---|---|---|
|
||||
| `DATABASE_URL` | Yes | PostgreSQL connection string |
|
||||
| `AUTH_SECRET` | Yes | JWT signing secret (generate with `openssl rand -hex 32`) |
|
||||
| `NEXT_PUBLIC_CESIUM_ION_TOKEN` | No | Cesium Ion access token |
|
||||
| `NEXT_PUBLIC_BING_MAPS_KEY` | No | Bing Maps imagery |
|
||||
| `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY` | No | Google 3D Tiles |
|
||||
| `NEXT_PUBLIC_WWV_EDITION` | No | `local` / `cloud` / `demo` (default: `local`) |
|
||||
| `NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL` | No | Override engine WebSocket URL (default: cloud) |
|
||||
| `OPENSKY_CREDENTIALS` | No | Comma-separated `id:secret` pairs for credential rotation |
|
||||
| `WWV_BRIDGE_TOKEN` | No | Shared secret for marketplace → WWV install bridge |
|
||||
| `WWV_DEMO_ADMIN_SECRET` | No | Demo edition admin password |
|
||||
| `IRANWARLIVE_BACKEND_URL` | No | Override for IranWarLive custom backend URL |
|
||||
|
||||
Secrets go in `.env.local` (gitignored). Non-secrets go in `.env` (committed).
|
||||
@@ -0,0 +1,222 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: Guidelines for the WorldwideView plugin marketplace, database interactions, and dynamic plugin installation.
|
||||
---
|
||||
|
||||
# Marketplace Architecture
|
||||
|
||||
## 1. InstalledPluginsLoader
|
||||
Marketplace plugins are dynamically loaded via `InstalledPluginsLoader`. At startup, this service queries the PostgreSQL database (`installed_plugins` table) for dynamically installed manifests.
|
||||
|
||||
## 2. Dynamic Bundle Loading
|
||||
Plugins from the marketplace use the `bundle` format and are imported at runtime from CDN endpoints (e.g., unpkg) via `loadPluginFromManifest()`.
|
||||
|
||||
## 3. Database Sync
|
||||
- Marketplace installations mutate the Prisma database.
|
||||
- `pluginManager.loadFromManifest()` validates and registers these plugins.
|
||||
- Ensure any schema changes to the marketplace tables follow the `database-migrations.md` rule.
|
||||
|
||||
## Current Implementation State
|
||||
|
||||
|
||||
- **Stage 4 (Bridge API + One-Click Install)** ✅ COMPLETE
|
||||
- Plugin data currently served from a volume-backed **PostgreSQL database** — plugins are submitted by entering an NPM package name in the Admin UI
|
||||
- The marketplace auto-fetches metadata from the NPM registry and parses the `"worldwideview"` block in `package.json`
|
||||
- A background `NpmCache` table caches NPM registry metadata to decouple from live NPM dependency
|
||||
- Future: Supabase DB for full publisher workflow (Stage 5)
|
||||
|
||||
---
|
||||
|
||||
## Plugin Submission Flow (Current)
|
||||
|
||||
1. Developer publishes their plugin to npm with a `"worldwideview"` block in `package.json`
|
||||
2. Admin opens the Marketplace Admin UI
|
||||
3. Admin enters the npm package name (e.g. `@worldwideview/wwv-plugin-my-data`)
|
||||
4. Marketplace fetches metadata from NPM registry, parses the manifest block, stores in PostgreSQL DB
|
||||
5. Plugin appears in the browse catalog
|
||||
|
||||
> Static plugins still need their GeoJSON files placed in the host application's `public/data/` directory.
|
||||
|
||||
---
|
||||
|
||||
## One-Click Install Flow (Redirect-Based)
|
||||
|
||||
**No static API keys.** Auth is entirely session-based. The marketplace redirects the browser to WWV, which checks the user's existing login session.
|
||||
|
||||
```
|
||||
User clicks "Install" on marketplace
|
||||
↓
|
||||
Marketplace: check localStorage for instance URL
|
||||
↓ (if not configured)
|
||||
Show "Connect Your Instance" modal → user enters http://localhost:3000
|
||||
↓
|
||||
MP → GET /api/marketplace/grant-token?redirectTo=...
|
||||
↓
|
||||
WWV: check Auth.js session → issue 30-day JWT → redirect ?token=<jwt>
|
||||
↓
|
||||
MP stores JWT in localStorage
|
||||
↓
|
||||
MP: Navigate browser to /api/marketplace/install-redirect
|
||||
?pluginId=borders&manifest=<b64>&redirectTo=...
|
||||
↓
|
||||
WWV: check session → upsertPlugin() → issueMarketplaceToken()
|
||||
↓
|
||||
Redirect back ?installed=borders&token=<jwt>
|
||||
↓
|
||||
MP: Show ✓ Installed — store JWT for future Manage-page calls
|
||||
```
|
||||
|
||||
### Token Flow
|
||||
|
||||
After successful install, WWV issues a **30-day HS256 JWT** (`scope: "marketplace"`, signed with `AUTH_SECRET`). The marketplace stores it in `localStorage` and sends it as `Authorization: Bearer <token>` on all subsequent API calls.
|
||||
|
||||
`validateMarketplaceAuth` accepts auth in priority order:
|
||||
1. Active Auth.js session (same-origin browser)
|
||||
2. Marketplace JWT Bearer token (cross-origin Manage page)
|
||||
3. Legacy static `WWV_BRIDGE_TOKEN` (backward compat)
|
||||
|
||||
---
|
||||
|
||||
## WWV Bridge API Routes (Implemented)
|
||||
|
||||
| Route | Method | Purpose |
|
||||
|---|---|---|
|
||||
| `/api/marketplace/install-redirect` | GET | Browser redirect install — checks session, installs plugin, issues JWT |
|
||||
| `/api/marketplace/grant-token` | GET | Issues marketplace JWT without install (for Manage page) |
|
||||
| `/api/marketplace/status` | GET | Returns all installed plugins (session or JWT auth) |
|
||||
| `/api/marketplace/uninstall` | POST | Deletes an installed plugin record |
|
||||
| `/api/marketplace/load` | GET | Returns valid non-built-in manifests for client startup (no auth) |
|
||||
| `/api/auth/setup-status` | GET | CORS-enabled connection test endpoint |
|
||||
|
||||
### Auth Module: `src/lib/marketplace/`
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
| `auth.ts` | `validateMarketplaceAuth()` — session → JWT → legacy token |
|
||||
| `marketplaceToken.ts` | `issueMarketplaceToken()` / `verifyMarketplaceToken()` — HS256 JWT via jose |
|
||||
| `cors.ts` | CORS headers for marketplace bridge routes |
|
||||
| `repository.ts` | `upsertPlugin()`, `uninstallPlugin()`, `getInstalledPlugins()` |
|
||||
| `registryClient.ts` | Fetches and Ed25519-verifies the signed plugin registry. 5-min in-memory cache. Stamps trust at install time |
|
||||
| `trustedPlugins.ts` | `localStorage` helpers for tracking user-approved unverified plugins |
|
||||
|
||||
---
|
||||
|
||||
## Marketplace API Endpoints (Target State)
|
||||
|
||||
### Public
|
||||
| Method | Path | Description |
|
||||
|---|---|---|
|
||||
| GET | `/api/plugins` | List/search plugins |
|
||||
| GET | `/api/plugins/:id` | Plugin detail |
|
||||
| GET | `/api/plugins/:id/bundle` | Download plugin bundle |
|
||||
| GET | `/api/categories` | List categories |
|
||||
| GET | `/api/registry` | Ed25519-signed verified-plugins registry — fetched by WWV at install time |
|
||||
|
||||
### Authenticated (Consumer)
|
||||
| Method | Path | Description |
|
||||
|---|---|---|
|
||||
| POST | `/api/instances` | Register a WWV instance |
|
||||
| PUT | `/api/instances/:id/default` | Set default instance |
|
||||
| POST | `/api/plugins/:id/install` | Trigger install to default instance |
|
||||
| GET | `/api/me/plugins` | List user's installed plugins |
|
||||
|
||||
### Authenticated (Publisher)
|
||||
| Method | Path | Description |
|
||||
|---|---|---|
|
||||
| POST | `/api/publisher/plugins` | Submit a new plugin |
|
||||
| PUT | `/api/publisher/plugins/:id` | Update plugin |
|
||||
| POST | `/api/publisher/plugins/:id/versions` | Publish new version |
|
||||
| GET | `/api/publisher/analytics` | Publisher analytics |
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
### WWV Local DB (Prisma — current)
|
||||
|
||||
```prisma
|
||||
model InstalledPlugin {
|
||||
id String @id @default(uuid())
|
||||
pluginId String
|
||||
version String
|
||||
config String // Full manifest JSON
|
||||
installedAt DateTime @default(now())
|
||||
}
|
||||
|
||||
model NpmCache {
|
||||
id String @id @default(uuid())
|
||||
packageName String @unique
|
||||
metadata String // JSON — cached NPM registry response
|
||||
lastFetched DateTime @default(now())
|
||||
}
|
||||
```
|
||||
|
||||
### Marketplace DB (Supabase — target, Stage 5+)
|
||||
|
||||
```
|
||||
users ─── published_plugins ─── plugin_versions
|
||||
│
|
||||
reviews
|
||||
```
|
||||
|
||||
Key fields on `published_plugins`: `slug`, `publisher_namespace` (`publisher.plugin-name`), `status` (`draft | review | published | rejected`), `manifest` (jsonb).
|
||||
|
||||
### Cloud DB (Supabase PostgreSQL — RLS-scoped)
|
||||
|
||||
```
|
||||
tenants ─── installed_plugins
|
||||
└── settings
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
| Concern | Mitigation |
|
||||
|---|---|
|
||||
| No static API keys | Install flow uses session redirects — no token to leak |
|
||||
| Marketplace JWT | 30-day HS256, scope-locked, verified via `jose` |
|
||||
| CSRF | Install/grant-token are GET redirects — user explicitly navigates |
|
||||
| Open redirect | `redirectTo` validated against allowlist |
|
||||
| Manifest tampering | Base64 only — no code execution. Validated via `validateManifest()` |
|
||||
| Malicious plugins | Sandboxed in Web Workers (unverified). CSP headers. Code review (verified) |
|
||||
| Supply chain | Plugin bundles checksummed (SHA-256), integrity verified |
|
||||
| Plugin API keys | Stored encrypted in `settings` table, never exposed to browser |
|
||||
| Trust forgery | Registry signed with Ed25519 — `verified` cannot be claimed for unlisted plugins |
|
||||
| Trust stamping | WWV always overwrites `manifest.trust` server-side — client/marketplace input ignored |
|
||||
| Unverified consent | Warning dialog before any unverified plugin loads; approval stored per-plugin in `localStorage` |
|
||||
|
||||
---
|
||||
|
||||
## API Key Proxy & Rate Limiting (For `apikey` plugins)
|
||||
|
||||
Response caching makes server-as-proxy viable at scale:
|
||||
|
||||
```
|
||||
1000 users viewing earthquake plugin:
|
||||
→ 1000 requests hit your proxy
|
||||
→ Proxy: "I fetched this URL 3s ago, cache still valid"
|
||||
→ Returns cached response to all 1000
|
||||
→ 1 actual upstream request to USGS
|
||||
```
|
||||
|
||||
| Tier | Proxy req/min | Cache TTL |
|
||||
|---|---|---|
|
||||
| Free | 60 | 30s |
|
||||
| Pro | 300 | 10s |
|
||||
| Enterprise | Unlimited | 5s |
|
||||
|
||||
---
|
||||
|
||||
## History & Timeline
|
||||
|
||||
**Third-party history (`historyUrl`):** Plugin manifest declares a history URL with `%t` placeholder. WWV replaces it with the scrubber timestamp — third-party provides the endpoint. No storage on your side. Available on all tiers.
|
||||
|
||||
**WWV Snapshot Capture:** Your server periodically stores plugin data per tenant. Counts toward storage quota. Pro/Local only.
|
||||
|
||||
| Feature | Free (cloud) | Pro / Local |
|
||||
|---|---|---|
|
||||
| Live data (declarative `url`) | ✅ | ✅ |
|
||||
| Third-party history (`historyUrl`) | ✅ If supported by API | ✅ |
|
||||
| WWV snapshot capture | ❌ | ✅ Counts toward quota |
|
||||
| Built-in aviation/maritime history | ✅ Limited (24h) | ✅ Full |
|
||||
@@ -13,7 +13,7 @@ Strict rules for operating within the `pnpm` monorepo workspace environment stru
|
||||
|
||||
- The Next.js frontend is located at root `.`.
|
||||
- Individual standalone plugins are located at `packages/wwv-plugin-[name]`.
|
||||
- For heavy plugin processing, microservice backends are located at `packages/wwv-plugin-[name]/backend`.
|
||||
- For heavy plugin processing, data engine seeders are located at `local-seeders/community/[name]` or `local-seeders/private/[name]`.
|
||||
|
||||
## Critical Workspace Rule
|
||||
|
||||
@@ -23,7 +23,7 @@ Strict rules for operating within the `pnpm` monorepo workspace environment stru
|
||||
|
||||
## Start/Exec Flow
|
||||
|
||||
Running `pnpm start:backends` from the project root employs `concurrently` to spin up Fastify services attached to specific plugins containing `/backend` folders.
|
||||
Running `pnpm dev:all` from the project root employs `docker-compose` to spin up the data engine runner and your local seeders alongside the Next.js frontend.
|
||||
|
||||
## Next.js Monorepo Exceptions
|
||||
|
||||
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: High-level platform goals, product vision, business model, multi-repository layout, and the Edition System.
|
||||
---
|
||||
|
||||
# WorldWideView — Platform Architecture
|
||||
|
||||
|
||||
> **This folder is the canonical source of truth for the project. It is NOT committed to git.**
|
||||
> It contains live architectural decisions, future plans, and operational knowledge.
|
||||
|
||||
---
|
||||
|
||||
> [!TIP]
|
||||
> **For the fundamental system architecture, component layout, and data pipelines, please read [`docs/ARCHITECTURE.md`](../../../docs/ARCHITECTURE.md) first.**
|
||||
> This file focuses strictly on the advanced business vision, multi-repository layout, and the Edition System.
|
||||
|
||||
## Product Vision & Business Model
|
||||
|
||||
WorldWideView operates on a **VS Code distribution model**. It is a visualization platform, not a compute provider. Plugin authors bring their own backends to display real-time geospatial intelligence.
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
Five repositories, modelled after the n8n pattern:
|
||||
|
||||
| Repo | License | Purpose |
|
||||
|---|---|---|
|
||||
| `silvertakana/worldwideview` | Elastic License 2.0 | Core 3D globe app (Next.js + CesiumJS + Prisma) |
|
||||
| `silvertakana/wwv-data-engine` | Open Source | Generic runner (Fastify + Redis + WS) |
|
||||
| `silvertakana/wwv-seeders-community` | Open Source | Open-source community seeders |
|
||||
| `silvertakana/wwv-seeders-private` | **Private** | Proprietary seeder scripts (aviation, maritime, etc.) |
|
||||
| `silvertakana/worldwideview-marketplace` | Open Source | Plugin catalog, signed registry, admin UI |
|
||||
| `silvertakana/worldwideview-plugins` | Open Source | Published plugin frontend source |
|
||||
| `silvertakana/worldwideview-web` | Open Source | Landing page, docs, static content |
|
||||
| `silvertakana/worldwideview-cloud` | **Private** | Cloud deployment config — Docker Compose, nginx, provisioning scripts |
|
||||
| `silvertakana/plugin-sdk` | MIT | `@worldwideview/plugin-sdk` — shared types for repos + 3rd-party authors |
|
||||
|
||||
**n8n Parallel:**
|
||||
| n8n | WorldWideView |
|
||||
|---|---|
|
||||
| `n8n-io/n8n` | `silvertakana/worldwideview` |
|
||||
| `n8n-io/n8n-cloud` (private) | `silvertakana/worldwideview-cloud` (private) |
|
||||
| `n8n.io` landing | `worldwideview.dev` (static on Vercel) |
|
||||
| `app.n8n.cloud` dashboard | `app.worldwideview.dev` |
|
||||
| `[user].app.n8n.cloud` | `[user].app.worldwideview.dev` |
|
||||
| `@n8n/workflow` npm | `@worldwideview/plugin-sdk` npm |
|
||||
|
||||
---
|
||||
|
||||
## Domain Architecture
|
||||
|
||||
| URL | What | Stack |
|
||||
|---|---|---|
|
||||
| `worldwideview.dev` | Static marketing/landing | Next.js (static export) on Vercel |
|
||||
| `app.worldwideview.dev` | Auth, accounts, dashboard | Next.js + Supabase Auth |
|
||||
| `[user].app.worldwideview.dev` | User's cloud WWV instance | Next.js (multi-tenant, RLS) |
|
||||
| `marketplace.worldwideview.dev` | Plugin catalog, publishing, install | Next.js (SSO via WorldWideView auth) |
|
||||
| `demo.worldwideview.dev` | Public demo — pre-configured, read-only | Next.js (WWV app) |
|
||||
| `docs.worldwideview.dev` | Documentation | TBD (Mintlify/Nextra) |
|
||||
| `status.worldwideview.dev` | Uptime / incident | Uptime Kuma |
|
||||
| `api.worldwideview.dev` | Built-in data services (aviation, maritime) | Next.js API routes or standalone |
|
||||
| `cdn.worldwideview.dev` | Plugin bundle storage | Cloudflare R2 |
|
||||
|
||||
**Reserved subdomains:** `www`, `app`, `api`, `demo`, `marketplace`, `docs`, `status`, `admin`, `cdn`, `blog`, `changelog`
|
||||
|
||||
---
|
||||
|
||||
## Infrastructure
|
||||
|
||||
All on **Coolify** running on a repurposed **ThinkPad T480s** (i5-8350U, 16GB RAM, 256GB NVMe, Ubuntu). Zero monthly hosting cost.
|
||||
|
||||
```
|
||||
ThinkPad T480s (home server, $0/mo) Supabase (hosted)
|
||||
├── Coolify ──→ ├── PostgreSQL (cloud DB)
|
||||
│ ├── worldwideview.dev (landing, Vercel) ├── Auth (GoTrue)
|
||||
│ ├── app.worldwideview.dev (auth/dashboard) └── Storage (file uploads)
|
||||
│ ├── WWV Cloud App (Docker)
|
||||
│ ├── Marketplace App (Docker) Cloudflare (free)
|
||||
│ ├── Demo Instance (Docker) ├── DNS + wildcard routing
|
||||
│ ├── api.worldwideview.dev ├── CDN caching
|
||||
│ ├── Uptime Kuma ├── DDoS protection
|
||||
│ └── Plausible Analytics └── R2 (plugin bundle CDN)
|
||||
└── Ubuntu Server
|
||||
```
|
||||
|
||||
**CI/CD:** Push to `silvertakana/worldwideview` → GitHub Actions builds Docker image → pushes to `ghcr.io/silvertakana/worldwideview:latest` → Coolify webhook triggers rolling restart.
|
||||
|
||||
**Monitoring:** Uptime Kuma (all subdomains), Plausible/Umami analytics.
|
||||
|
||||
---
|
||||
|
||||
## Business Model
|
||||
|
||||
**Distribution platform, not compute provider.** Plugin authors handle their own backends.
|
||||
|
||||
| Revenue Stream | How |
|
||||
|---|---|
|
||||
| **Cloud hosting** | `[user].app.worldwideview.dev` — free/pro/enterprise tiers |
|
||||
| **Marketplace cut** | % of paid plugin subscriptions via Stripe Connect |
|
||||
| **Verified tier** | Plugin authors pay for review + verified badge |
|
||||
| **Pro/Enterprise license** | More quota, faster cache TTL, advanced features |
|
||||
| **Extension packs** | Curated bundles of related plugins |
|
||||
|
||||
Plugin authors can monetize independently (VS Code + GitHub Copilot model). Selling through the marketplace is **incentivized** (managed billing, featured placement, analytics) but not mandatory.
|
||||
|
||||
---
|
||||
|
||||
## Editions
|
||||
|
||||
Three editions; same codebase, gated by `NEXT_PUBLIC_WWV_EDITION`:
|
||||
|
||||
| Edition | Value | Database | Auth | Plugin Install |
|
||||
|---|---|---|---|---|
|
||||
| **Local** | `local` | PostgreSQL | Auth.js Credentials | Yes |
|
||||
| **Cloud** | `cloud` | PostgreSQL (Supabase) | Auth.js + Supabase | Yes |
|
||||
| **Demo** | `demo` | PostgreSQL (read-only) | Disabled | No |
|
||||
|
||||
Three thin adapter files handle edition differences: `src/core/auth.ts`, `src/core/storage.ts`, `src/core/tenant.ts`. Everything else is edition-unaware.
|
||||
@@ -78,6 +78,316 @@ DataBus.getInstance().emit('dataUpdated', {
|
||||
});
|
||||
```
|
||||
|
||||
## Local Plugin Development (Sandbox)
|
||||
|
||||
To rapidly iterate on plugins without polluting the core monorepo `packages/` directory or git history, use the local devkit:
|
||||
|
||||
1. **Create**: Run `node packages/wwv-cli/dist/index.js create <name> --local` to scaffold a full plugin structure inside the `local-plugins/` directory.
|
||||
2. **Develop**: Running `pnpm dev` or `pnpm dev:all` automatically spawns the `dev:plugins` watcher. Any changes made to plugins in `local-plugins/` will be instantly rebuilt using Vite (externalizing large globals) and synced to `public/plugins-local/` for hot-reloading.
|
||||
3. **Publish**: The `dev:plugins` script natively supports hot-reloading local plugins within the workspace. Once the plugin is ready, you can simply use `node packages/wwv-cli/dist/index.js publish <name> [--org <your-org>]` from the project root to publish it.
|
||||
|
||||
## When to Apply
|
||||
When writing `fetch` implementations for plugins, or tracing why an entity dropped off the map. Ensure missing data correctly triggers the cache fallback via the DataBus. Ensure all new external plugins use the `bundle` format and exist in the marketplace registry to avoid CDN 404 hydrating crashes.
|
||||
|
||||
|
||||
|
||||
## Capability Declarations
|
||||
|
||||
|
||||
Every plugin declares what it can access. Undeclared capabilities are **blocked at runtime**.
|
||||
|
||||
```typescript
|
||||
type PluginCapability =
|
||||
| "data:own" // Fetch and render its own data layer
|
||||
| "data:read:<id>" // Read entities from another plugin
|
||||
| "ui:detail-panel" // Inject UI into entity detail panel
|
||||
| "ui:sidebar" // Add a sidebar section
|
||||
| "ui:toolbar" // Add toolbar buttons
|
||||
| "ui:settings" // Add a settings page
|
||||
| "globe:overlay" // Draw on the globe (polylines, polygons, heatmaps)
|
||||
| "globe:camera" // Control camera movement
|
||||
| "storage:read" // Read from local/cloud storage
|
||||
| "storage:write" // Write to local/cloud storage
|
||||
| "network:fetch" // Make external HTTP requests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Trust Tiers
|
||||
|
||||
| Trust Tier | Who | Capabilities Allowed | How Determined |
|
||||
|---|---|---|---|
|
||||
| **Built-in** | Ships with WWV | All | Hardcoded in `AppShell` at build time |
|
||||
| **Verified** | WorldWideView-reviewed | Any declared capability | Plugin ID in the **signed registry** |
|
||||
| **Unverified** | Community / 3rd-party | `data:own`, `ui:settings` only | Plugin ID NOT in the registry |
|
||||
|
||||
### Signed Plugin Registry
|
||||
|
||||
Trust is determined by a cryptographically signed JSON file:
|
||||
|
||||
```
|
||||
GET marketplace.worldwideview.dev/api/registry
|
||||
→ { plugins: ["aviation", "maritime", ...], issuedAt, signature }
|
||||
```
|
||||
|
||||
- Signed with **Ed25519** private key (held only by registry maintainer)
|
||||
- WWV instances have the **public key hardcoded** — nobody can forge a fake verified list
|
||||
- WWV fetches and **verifies signature server-side** at install time
|
||||
- Trust is **always stamped server-side** — no client-side trust claims accepted
|
||||
- Registry response cached for **5 minutes** (in-memory on each WWV instance)
|
||||
- If registry unreachable, last cached result used; new unknowns default to `unverified`
|
||||
- **Managing:** Edit `src/data/verifiedPlugins.ts` in marketplace repo and redeploy
|
||||
- **Revoking:** Remove plugin ID and redeploy — WWV instances drop trust on next cache refresh
|
||||
|
||||
### Unverified Plugin Warning
|
||||
|
||||
When an unverified manifest is encountered:
|
||||
1. Plugin held in pending queue (not loaded)
|
||||
2. `UnverifiedPluginDialog` shown: "This plugin is unverified. Install at your own risk."
|
||||
3. User can Allow (stores approval in `localStorage`) or Deny
|
||||
4. Once approved, dialog won't reappear for that plugin ID
|
||||
|
||||
---
|
||||
|
||||
## VS Code Design Patterns Applied
|
||||
|
||||
**Activation events** — plugins declare when they activate, not at startup:
|
||||
```json
|
||||
"activationEvents": ["onView:aviationLayer", "onCommand:wwv.showCockpit"]
|
||||
```
|
||||
|
||||
**Contribution points** — declarative UI, no code needed for sidebar/menu entries:
|
||||
```json
|
||||
"contributes": {
|
||||
"commands": [{ "command": "wwv.enterCockpit", "title": "Enter Cockpit View" }],
|
||||
"settings": [{ "key": "refreshInterval", "type": "number", "default": 10 }]
|
||||
}
|
||||
```
|
||||
|
||||
**Extension dependencies** — plugins can require other plugins (auto-installed if missing):
|
||||
```json
|
||||
"extensionDependencies": ["worldwideview.aviation"]
|
||||
```
|
||||
|
||||
**Publisher namespaces** — `publisher.plugin-name` (e.g., `silvertakana.aviation`). Prevents naming conflicts.
|
||||
|
||||
**Extension packs** — bundles of related plugins:
|
||||
```json
|
||||
{ "id": "worldwideview.military-suite", "extensionPack": ["aviation", "military-bases", "radar-overlay"] }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plugin Auth Types
|
||||
|
||||
Plugins declare auth type in the manifest:
|
||||
|
||||
| Auth Type | Who Calls the API | Server Role |
|
||||
|---|---|---|
|
||||
| `none` | Browser, directly | Nothing |
|
||||
| `apikey` | Server proxy | Injects key from DB, caches response |
|
||||
| `token-exchange` | Browser, directly (after exchange) | One-time key→token swap |
|
||||
| `oauth` | Browser, directly (after OAuth) | OAuth callback handler, stores token |
|
||||
|
||||
**Recommended for scale:** `token-exchange` — your server is never in the hot path for data requests.
|
||||
|
||||
---
|
||||
|
||||
## Plugin Development Workflows
|
||||
|
||||
Starting in 2026, WorldWideView adopted the **Architect and Toolbox** paradigm using NPM global tools, ensuring a fully decoupled developer experience. Plugin repositories contain *pure code* with absolutely no platform hosting boilerplate (e.g. no embedded docker-compose files).
|
||||
|
||||
### The Developer Experience
|
||||
1. **Scaffold**: `node packages/wwv-cli/dist/index.js create <name> --local` (Creates sandbox inside `local-plugins/`)
|
||||
2. **Install**: `pnpm install` (Links dependencies via workspace)
|
||||
3. **Develop**: `pnpm dev:all` (Starts frontend, data engine, and plugin watcher dynamically)
|
||||
|
||||
### Local vs Docker Development
|
||||
The marketplace API natively supports hot-reloading for local plugins without rebuilding the core.
|
||||
|
||||
**Docker-Hosted Mode (Recommended for external devs):**
|
||||
If a developer wants to build a plugin without cloning the 1GB+ WorldWideView monorepo, they can pull the official WWV Docker image and mount their compiled plugin code:
|
||||
1. Run WWV with the development flag: `WWV_PLUGIN_DEV=true`
|
||||
2. Mount the local plugin's `dist/` folder into the container's `/app/local-plugins/` directory.
|
||||
3. Because the plugin is strictly code, Vite rebuilds in <100ms, and a browser refresh instantly loads the new plugin from the Docker volume.
|
||||
|
||||
**Core Contributor Mode:**
|
||||
If working inside a cloned `worldwideview` directory, scaffolding the plugin into `local-plugins/` makes it a pnpm workspace member. Running `pnpm dev:all` automatically spawns `pnpm dev:plugins`, which continuously transpiles local plugins so the Next.js frontend can hot-reload them without complex linking.
|
||||
|
||||
---
|
||||
|
||||
DB stores **references only** — never plugin files:
|
||||
|
||||
```prisma
|
||||
model InstalledPlugin {
|
||||
pluginId String
|
||||
version String
|
||||
manifestUrl String // "https://marketplace.../api/plugins/aviation/manifest"
|
||||
bundleUrl String? // local path or CDN URL (differs by edition)
|
||||
}
|
||||
```
|
||||
|
||||
| Edition | `bundleUrl` | How served |
|
||||
|---|---|---|
|
||||
| **Local** | `file:./plugins/cockpit-view/bundle.js` | Local filesystem (downloaded at install) |
|
||||
| **Cloud** | `https://cdn.worldwideview.dev/plugins/cockpit-view/bundle.js` | CDN at runtime |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables & Execution Agnosticism
|
||||
|
||||
WWV enforces a strictly decoupled execution context, allowing plugins to function reliably whether they are loading locally (`plugins-local`) or from a public CDN (`unpkg.com`).
|
||||
|
||||
### Dynamic Assets (`import.meta.url`)
|
||||
For file-based assets bundled alongside the plugin (such as JSON datasets or 3D GLTF models), the runtime relies on native ECMAScript relative resolution instead of hardcoded framework paths.
|
||||
- Plugins securely fetch their assets using `new URL('data/data.json', import.meta.url).href`.
|
||||
- **Impact:** Assets resolve properly directly from the domain they were executed on. No CORS bypasses or CDN fallbacks required.
|
||||
|
||||
### .env Passthrough Injection
|
||||
The WorldWideView core engine functions as a "blind pipe" for developer environment variables, allowing organizations to securely route plugins to custom backend microservices (local or cloud) without modifying the platform.
|
||||
1. The developer adds `NEXT_PUBLIC_WWV_PLUGIN_EXAMPLE_URL="http://localhost:5001"` to their `.env.local`.
|
||||
2. The engine detects the `NEXT_PUBLIC_WWV_PLUGIN_` prefix, strips it, and dynamically hydrates the `PluginContext`.
|
||||
3. The plugin natively retrieves `ctx.env.EXAMPLE_URL`.
|
||||
4. *Security Clause:* Variables accessible via `ctx.env` are exposed directly to the **client-side bundle**. Core secrets/API tokens must never be used here; they must exclusively use the server-side `ctx.getSecret()` workflow.
|
||||
|
||||
---
|
||||
|
||||
## Lazy Loading
|
||||
|
||||
Plugins load their code **only when activated**, not at startup:
|
||||
|
||||
```
|
||||
Startup: load manifests from DB (one query) → globe with built-in plugins only
|
||||
Toggle on "Aviation" → import() aviation bundle → register → fetch data
|
||||
Toggle on "Cockpit View" → import() cockpit bundle → register
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Stack
|
||||
|
||||
| Piece | Library |
|
||||
|---|---|
|
||||
| Bundle loading | Native `import()` or `@module-federation/enhanced/runtime` |
|
||||
| Manifest validation | `zod` |
|
||||
| Sandboxing (unverified plugins) | `comlink` + Web Workers |
|
||||
| Dependency resolution | `toposort` |
|
||||
| Event system | `mitt` (200 bytes) |
|
||||
| Plugin registry | Custom `PluginManager` class |
|
||||
|
||||
---
|
||||
|
||||
## Built-In Plugins (Current)
|
||||
|
||||
| Plugin | Format | Data Source |
|
||||
|---|---|---|
|
||||
| Aviation | bundle | OpenSky Network (ADS-B) |
|
||||
| Maritime | bundle | AIS (maritime tracking) |
|
||||
| Borders | bundle | GeoJSON from public API |
|
||||
| Wildfire | bundle | NASA FIRMS |
|
||||
| Military Bases | bundle (compiled) | OpenStreetMap (via Overpass) |
|
||||
| Nuclear Facilities | bundle (compiled) | OpenStreetMap |
|
||||
| Camera/CCTV | bundle | IP camera streams |
|
||||
| GeoJSON | bundle | User-supplied GeoJSON files |
|
||||
|
||||
Future direction: Aviation and maritime redesigned as **declarative plugins** pointing to `api.worldwideview.dev` — your own API server handles polling, persistence, and history for all tenants.
|
||||
|
||||
---
|
||||
|
||||
## Creating Static OSM Plugins
|
||||
|
||||
For static plugins built from OpenStreetMap data, use the scaffold script:
|
||||
|
||||
```bash
|
||||
node scripts/scaffold-osm-plugin.mjs '{
|
||||
"name": "volcanoes",
|
||||
"displayName": "Volcanoes",
|
||||
"description": "Active and dormant volcanoes worldwide from OSM",
|
||||
"osmTag": "natural=volcano",
|
||||
"icon": "Mountain",
|
||||
"color": "#ef4444",
|
||||
"category": "Natural Disaster"
|
||||
}'
|
||||
```
|
||||
|
||||
This queries Overpass API, converts to GeoJSON, scaffolds the package, and prints marketplace snippets.
|
||||
|
||||
**Common OSM tags:**
|
||||
|
||||
| Dataset | OSM Tag | ~Count |
|
||||
|---------|---------|--------|
|
||||
| Airports | `aeroway=aerodrome` | 40k |
|
||||
| Seaports | `harbour=yes` | 15k |
|
||||
| Nuclear facilities | `generator:source=nuclear` | 758 |
|
||||
| Volcanoes | `natural=volcano` | 1.5k |
|
||||
| Lighthouses | `man_made=lighthouse` | 20k |
|
||||
| Embassies | `amenity=embassy` | 10k |
|
||||
| Helipads | `aeroway=helipad` | 25k |
|
||||
| Power plants | `power=plant` | 15k |
|
||||
| Wind farms | `generator:source=wind` | 50k |
|
||||
|
||||
See skill: `.agents/skills/osm-static-plugin-creation.md`
|
||||
|
||||
---
|
||||
|
||||
## The Data Engine (Backend & Seeders)
|
||||
|
||||
When a plugin requires 24/7 background polling, long-term history (PostgreSQL), or high-frequency caching (Redis), it should leverage the **Data Engine**. The WWV architecture splits the frontend UI package and the backend data collection into two distinct tiers.
|
||||
|
||||
### 1. First-Party / Built-In Plugins
|
||||
For plugins developed directly inside the WWV monorepo:
|
||||
- **Seeder Module**: Developers write a single seeder (e.g. `seeders/aviation.ts`) inside the `wwv-data-engine` package.
|
||||
- **Unified Container**: All first-party seeders run inside one singular `wwv-data-engine` Docker container. This prevents background polling from being destroyed by Next.js edge isolation or HMR.
|
||||
|
||||
### 2. Third-Party / Community Plugins (The VPS Problem)
|
||||
Currently, **there is a high DX friction for third-party developers hosting their own heavy plugins.**
|
||||
- The `wwv-data-engine` is deeply coupled to the WWV host. Third-party developers cannot push their backend seeders into WWV's actual servers.
|
||||
- The `wwv-plugin-sdk` only assists with the frontend `WorldPlugin` interface.
|
||||
- Consequently, a sole developer with a VPS must write their own Node.js backend entirely from scratch to serve their custom data feeds, handle their own caching, and manage multiple Node instances if they create multiple plugins.
|
||||
|
||||
### 3. The Future: Distributable Data Engine Image
|
||||
To solve this friction and make third-party plugin hosting highly intuitive, the WWV roadmap includes publishing a **WWV Mini-Engine** as a standalone Docker image:
|
||||
1. **Lightweight Deployment:** Developers run `docker run worldwideview/mini-engine` on their VPS.
|
||||
2. **Backend SDK:** They write simple `.ts` fetch scripts returning `GeoEntity[]` and drop them into a mounted `/seeders` volume.
|
||||
3. **Zero Configuration:** The Docker engine hot-reloads these seeders, handles the Redis caching, and exposes standardized REST or WebSocket endpoints automatically. The developer focuses only on fetching data, avoiding all backend infrastructure setup.
|
||||
|
||||
See skill: `.agents/skills/data-engine-seeder-creation.md`
|
||||
|
||||
---
|
||||
|
||||
## Architectural Differences: WorldWideView (WWV) vs WorldMonitor (WM)
|
||||
|
||||
While WorldWideView draws UI/UX and feature inspiration from WorldMonitor as a baseline, the underlying plugin architectures are fundamentally different.
|
||||
|
||||
### WorldMonitor (The Inspiration)
|
||||
- **Monolithic Frontend**: Layers and datasets are typically hardcoded directly into the application's core logic.
|
||||
- **Custom Implementations**: Each data source usually requires its own bespoke API fetching, state management, and map rendering logic (e.g., raw Mapbox/Cesium objects).
|
||||
- **Coupled Backend**: Data ingestion is often tightly coupled to the monolithic application or spread across scattered, heterogeneous microservices without a unified cache.
|
||||
|
||||
### WorldWideView (The Reality)
|
||||
- **Extensible VS Code-Style Runtime**: Plugins are wholly independent, sandboxable modules loaded dynamically via activation events. The core map knows nothing about aviation or wildfires.
|
||||
- **Unified Data Contract (`GeoEntity`)**: All data layers map their bespoke formats into a strict, unified `GeoEntity` system. The core engine handles clustering, filtering, and timeline playback generically—no custom rendering trickery needed per dataset.
|
||||
- **Shared Data Engine**: WWV enforces a strict separation of concerns. All 24/7 API polling, data normalizations, and history retention happen off-thread in the singular `wwv-data-engine` (utilizing Redis hot cache + PostgreSQL history retention), providing a clean, unified REST interface for the plugin frontend.
|
||||
- **Cryptographic Trust**: WWV incorporates a signed marketplace registry and fine-grained capability declarations (`data:read`, `ui:sidebar`), establishing an enterprise-ready security posture for third-party extensions.
|
||||
|
||||
### Planned Features (Inspired by Monolithic Systems / WM)
|
||||
While avoiding monolithic coupling, WWV plans to implement the following high-UX features natively or via generic plugin capabilities:
|
||||
|
||||
1. **Decentralized Plugin Connections (Agnostic Client)**: WorldWideView is entirely agnostic to the backend. It does NOT enforce a single unified pipeline. If a user activates 30 different plugins hosted on 30 different custom servers, the frontend will happily open 30 separate WebSocket connections. The client application knows absolutely nothing about the Data Engine—it only reads the `streamUrl` provided by each individual plugin's manifest.
|
||||
2. **Cross-Layer Geofencing & Alerts**: A new `User Alert System` designed explicitly as a **plugin**. Utilizing the unified `GeoEntity` outputs, users can draw a polygon on the map and trigger webhooks/notifications if *any* entity from *any* active plugin crosses the boundary.
|
||||
3. **Advanced Dead-Reckoning Hooks**: Building a `useDeadReckoning()` hook directly into the `@worldwideview/wwv-plugin-sdk`. It will automatically use standard `speed` and `heading` props to smoothly glide vehicle entities across the Cesium globe at 60 FPS between data pings, preventing plugin authors from rewriting complex math logic.
|
||||
4. **Curated Workspaces / Scenarios**: The ability for users to save their current state as a "Workspace URL." This generates a shareable link that encodes the exact camera position, timeline bounds, activated plugins, and their respective layer configurations/filters.
|
||||
|
||||
|
||||
## Local Plugins & Seeders
|
||||
|
||||
### 1. Local Sandbox Workflow
|
||||
- **Scaffold**: `node packages/wwv-cli/dist/index.js create` (creates inside `local-plugins/wwv-plugin-<name>` by default, or `packages/` if `--core` is used).
|
||||
- **Develop**: `pnpm dev` triggers hot-reloading via `dev:plugins` watch script.
|
||||
- **Publish**: `node packages/wwv-cli/dist/index.js publish <name> [--org <your-org>]` publishes the plugin from the project root. (No linking is needed; the sandbox natively functions in the workspace).
|
||||
|
||||
### 2. Data Engine Seeders
|
||||
Seeders in `wwv-data-engine/src/seeders/` provide the backend data.
|
||||
- **Cron Seeder**: Uses `registerSeeder({ name: "plugin-id", cron: "..." })` and pushes to Redis via `setLiveSnapshot()`.
|
||||
- **Init Seeder**: High-frequency or persistent websockets via `init: () => void`.
|
||||
- **Constraint**: Seeder `name` MUST exactly match the frontend plugin `id`. Do not bundle workspace dependencies like `ws` or `zod` into the seeder `dist`.
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: Server development and debugging rules for the production/homelab server using SSH and Coolify MCP.
|
||||
---
|
||||
|
||||
# Server Management & Debugging
|
||||
|
||||
## 1. Coolify MCP (High-Level)
|
||||
Use the `coolify` MCP server for managed actions:
|
||||
- **Discovery**: `mcp_coolify_projects`, `mcp_coolify_environments`
|
||||
- **Inspection**: `mcp_coolify_application_logs`, `mcp_coolify_get_application`
|
||||
- **Actions**: `mcp_coolify_control` (restart, stop)
|
||||
|
||||
## 2. Direct SSH (Low-Level)
|
||||
For filesystem or network issues, use direct SSH to the production server:
|
||||
`ssh [email protected] "<command>"`
|
||||
|
||||
**Common Commands**:
|
||||
- `docker ps`
|
||||
- `docker logs --tail 100 <container_id>`
|
||||
- `df -h`
|
||||
- `top -b -n 1` (Never run interactive `top` or `nano` via agent commands).
|
||||
|
||||
## 3. Safety Precautions
|
||||
Always use non-interactive flags for SSH. Communicate clearly before executing high-risk actions like volume deletion or critical infrastructure restarts.
|
||||
@@ -0,0 +1,378 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: Human-centered design principles, stakeholder map, and decision matrix.
|
||||
---
|
||||
|
||||
# Stakeholders & Human-Centered Design
|
||||
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **This document is mandatory reading before any feature, UI, API, or architectural decision.**
|
||||
> Every line of code in this project ultimately serves a human being. The AI agent MUST identify which stakeholder(s) a change affects and design the solution around their needs, abilities, and constraints — not the other way around.
|
||||
|
||||
---
|
||||
|
||||
## Why This Document Exists
|
||||
|
||||
Software that doesn't consider its humans fails. Not technically — socially. A plugin API that's elegant internally but hostile to external developers will die with zero third-party plugins. A monetization tier that ignores what users actually value will generate zero revenue. A contribution process that assumes PhD-level Cesium knowledge will attract zero contributors.
|
||||
|
||||
**The directive is simple:** Before you write code, ask *"Who is this for, what do they need, and what will they actually experience?"*
|
||||
|
||||
---
|
||||
|
||||
## The Stakeholder Universe
|
||||
|
||||
WorldWideView is not a single-user tool. It is a **platform ecosystem** with at least nine distinct human roles, each with different goals, different technical abilities, different emotional states when they interact with the product, and different definitions of "success."
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ Owner / Founder │
|
||||
│ (silvertakana) │
|
||||
└────────┬─────────┘
|
||||
│ vision, architecture, deployment
|
||||
┌───────────────────┼───────────────────┐
|
||||
│ │ │
|
||||
┌──────┴──────┐ ┌───────┴───────┐ ┌───────┴───────┐
|
||||
│ Core Devs │ │ Contributors │ │ Plugin Devs │
|
||||
│ (team) │ │ (community) │ │ (3rd party) │
|
||||
└──────┬──────┘ └───────┬───────┘ └───────┬───────┘
|
||||
│ │ │
|
||||
└───────────┬───────┘ │
|
||||
│ build the product │ extend the product
|
||||
┌───────────┴────────────────────────────┘
|
||||
│
|
||||
┌──────┴──────────────────────────────────┐
|
||||
│ The Application │
|
||||
│ ┌────────┐ ┌────────┐ ┌───────────┐ │
|
||||
│ │ Demo │ │ Local │ │ Cloud │ │
|
||||
│ │Instance│ │Instance│ │ Instance │ │
|
||||
│ └───┬────┘ └───┬────┘ └─────┬─────┘ │
|
||||
└──────┼───────────┼─────────────┼────────┘
|
||||
│ │ │
|
||||
┌──────┴──┐ ┌─────┴────┐ ┌────┴─────┐
|
||||
│Casual │ │Power User│ │Paying │
|
||||
│Visitor │ │(self-host)│ │Customer │
|
||||
└─────────┘ └──────────┘ └────┬─────┘
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ Advertisers │
|
||||
│ (demo edition) │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stakeholder Profiles
|
||||
|
||||
### 1. Owner / Founder (silvertakana)
|
||||
|
||||
| Attribute | Description |
|
||||
|---|---|
|
||||
| **Role** | Solo founder, architect, deployer, and operator of the entire ecosystem |
|
||||
| **Goal** | Build a sustainable, revenue-generating geospatial intelligence platform that rivals WorldMonitor |
|
||||
| **Motivations** | Technical excellence, creative ownership, financial independence, community building |
|
||||
| **Technical Ability** | Expert — TypeScript, Next.js, CesiumJS, Docker, infrastructure, Prisma, AI-assisted development |
|
||||
| **Emotional State** | Ambitious but resource-constrained; every wasted hour counts double |
|
||||
| **Definition of Success** | Growing user base, marketplace with active plugin developers, recurring revenue, industry recognition |
|
||||
| **Pain Points** | Single point of failure for ops, deployment, and architecture decisions; time pressure; hosting cost sensitivity ($0/mo target) |
|
||||
| **Interaction Surface** | `.agents/` rules, ROADMAP.md, Coolify dashboard, code reviews, AI pair-programming sessions |
|
||||
|
||||
**Design implications:**
|
||||
- Automation is critical — CI/CD, self-healing databases, zero-config setup
|
||||
- AI agent rules must preserve the owner's vision even when the owner isn't in the conversation
|
||||
- Cost-efficient architecture (PostgreSQL, ThinkPad server, free-tier services) is a feature, not a compromise
|
||||
- Every architectural decision must consider the owner's ability to maintain it solo
|
||||
|
||||
---
|
||||
|
||||
### 2. Core Development Team (WWV Devs)
|
||||
|
||||
| Attribute | Description |
|
||||
|---|---|
|
||||
| **Role** | Trusted developers with direct commit access to the monorepo |
|
||||
| **Goal** | Ship features quickly without breaking existing functionality |
|
||||
| **Motivations** | Clean code, clear architecture, fast iteration, not getting paged at 2am |
|
||||
| **Technical Ability** | High — comfortable with TypeScript, Next.js App Router, Zustand, pnpm workspaces |
|
||||
| **Emotional State** | Productive when patterns are clear; frustrated by undocumented gotchas |
|
||||
| **Definition of Success** | PRs merged cleanly, features work on first deploy, zero regressions |
|
||||
| **Pain Points** | File bloat (>150 lines), implicit state dependencies, CesiumJS rendering quirks, Docker build complexity |
|
||||
| **Interaction Surface** | `src/core/`, `src/components/`, `packages/`, PR reviews, `pnpm dev` |
|
||||
|
||||
**Design implications:**
|
||||
- 150-line file limit is sacred — enforce it in every code change
|
||||
- Clear slice boundaries in Zustand store prevent cross-team conflicts
|
||||
- `AGENTS.md` and `.agents/` context must always be current so that AI-augmented devs have accurate context
|
||||
- Rendering rules (billboard vs. point, never mix properties) must be enforced systematically
|
||||
- Docker gotchas documented in `06-dev-workflows.md` prevent time-sink debugging
|
||||
|
||||
---
|
||||
|
||||
### 3. Open Source Contributors
|
||||
|
||||
| Attribute | Description |
|
||||
|---|---|
|
||||
| **Role** | External developers who fork, fix bugs, add features, or create plugins via PRs |
|
||||
| **Goal** | Contribute meaningfully without needing to understand the entire 50-package monorepo |
|
||||
| **Motivations** | Portfolio building, learning CesiumJS/geospatial tech, improving a tool they use, open source goodwill |
|
||||
| **Technical Ability** | **Variable** — ranges from junior devs submitting typo fixes to senior engineers contributing optimizations |
|
||||
| **Emotional State** | Enthusiastic but easily discouraged by onboarding friction; will abandon contribution if setup takes >15 minutes |
|
||||
| **Definition of Success** | PR accepted and merged; their name in the contributors list; feature actually ships |
|
||||
| **Pain Points** | Complex monorepo, CesiumJS learning curve, Elastic License 2.0 implications, unclear "where to start" |
|
||||
| **Interaction Surface** | `CONTRIBUTING.md`, `docs/SETUP.md`, `docs/PLUGIN_GUIDE.md`, GitHub Issues, PR templates |
|
||||
|
||||
**Design implications:**
|
||||
- **One-command setup** (`pnpm run setup && pnpm dev:all`) is non-negotiable — if it breaks, contributors leave
|
||||
- `CONTRIBUTING.md` must use `pnpm` (currently shows `npm` in places — this is a bug)
|
||||
- "Good first issue" labels on GitHub attract newcomers
|
||||
- Plugin creation is the #1 entry point for contributors — the scaffold script and Plugin Guide must be flawless
|
||||
- The Elastic License 2.0 must be clearly communicated (it's NOT fully open source — contributors need to understand what they're signing up for)
|
||||
|
||||
---
|
||||
|
||||
### 4. Third-Party Plugin Developers
|
||||
|
||||
| Attribute | Description |
|
||||
|---|---|
|
||||
| **Role** | External developers who build and publish plugins to the WorldWideView Marketplace |
|
||||
| **Goal** | Create a plugin that integrates their data source, potentially monetize it |
|
||||
| **Motivations** | Revenue (marketplace cut), reach (installed on many WWV instances), reputation, data evangelism |
|
||||
| **Technical Ability** | **Mid-to-high** — comfortable with TypeScript and npm, but NOT Cesium experts. They should never need to learn Cesium internals. |
|
||||
| **Emotional State** | Evaluating whether the platform is worth investing development time in. Extremely sensitive to DX friction. |
|
||||
| **Definition of Success** | Plugin published, visible in marketplace, installed by users, data renders correctly, optional revenue stream |
|
||||
| **Pain Points** | (1) Backend hosting burden — they need a VPS for active plugins (the "VPS Problem"), (2) No distributable mini-engine yet, (3) SDK docs may not cover edge cases, (4) Rendering bugs with billboard/point property mixing |
|
||||
| **Interaction Surface** | `@worldwideview/wwv-plugin-sdk`, `docs/PLUGIN_GUIDE.md`, `docs/creating-a-plugin.md`, marketplace submission UI, npm publishing |
|
||||
|
||||
**Design implications:**
|
||||
- The Plugin SDK is the **#1 most important public API surface** — it must be impeccably documented, versioned, and stable
|
||||
- `WorldPlugin` interface changes are breaking changes that affect real people with real published packages
|
||||
- Three plugin formats (Declarative, Static, Code Bundle) exist specifically to lower the barrier:
|
||||
- **Declarative** = zero code (JSON only) — anyone with a data URL can create a plugin
|
||||
- **Static** = GeoJSON file + manifest — data analysts who aren't developers
|
||||
- **Code Bundle** = full TypeScript — professional developers
|
||||
- The future **Mini-Engine Docker image** (§3 of `03-plugin-system.md`) is critical for reducing the VPS burden
|
||||
- Rendering must be abstracted — plugin devs define `renderEntity()`, and the engine handles GPU batching
|
||||
- Error messages from the plugin lifecycle must be clear, not cryptic Cesium stack traces
|
||||
- Marketplace analytics (install counts, usage) are what keep plugin developers motivated
|
||||
|
||||
---
|
||||
|
||||
### 5. Casual Visitors (Demo Users)
|
||||
|
||||
| Attribute | Description |
|
||||
|---|---|
|
||||
| **Role** | Anonymous visitors who land on `demo.worldwideview.dev` — no account, no setup |
|
||||
| **Goal** | Explore the globe, see cool real-time data, understand what WorldWideView is |
|
||||
| **Motivations** | Curiosity, news events (war, natural disasters, flight tracking), linked from social media or Reddit |
|
||||
| **Technical Ability** | **Low to none** — they don't know what ADS-B or GeoJSON means. They just want to see planes on a globe. |
|
||||
| **Emotional State** | Impatient. They will leave within 10 seconds if the globe doesn't load or the UI is confusing. |
|
||||
| **Definition of Success** | "Whoa, this is cool" → bookmark/share → return later → potentially convert to self-host or cloud user |
|
||||
| **Pain Points** | Slow boot time (Cesium asset loading), confusing UX, data not loading (API rate limits), ads disrupting experience |
|
||||
| **Interaction Surface** | Boot overlay, 3D globe, layer toggle panel, entity hover/click, info cards, timeline, ad strip |
|
||||
|
||||
**Design implications:**
|
||||
- **First 5 seconds are everything** — the boot overlay must feel cinematic, not broken
|
||||
- Pre-activate compelling default layers (aviation is the universal crowd-pleaser)
|
||||
- Globe interaction must work without instructions — left-click drag, scroll zoom, click entity
|
||||
- The "Why ads?" banner (`DemoAdStrip`) is a trust-building honesty moment — keep it human and transparent
|
||||
- Mobile layout must be flawless — many demo visitors come from social media on phones
|
||||
- No login walls, no setup wizards, no configuration prompts — demo is zero-friction
|
||||
- Performance on commodity hardware (integrated GPUs, 2017 laptops) must be acceptable
|
||||
- Error states must be invisible — if OpenSky is down, the layer just shows fewer planes, not an error dialog
|
||||
|
||||
---
|
||||
|
||||
### 6. Self-Hosted Power Users (Local Edition)
|
||||
|
||||
| Attribute | Description |
|
||||
|---|---|
|
||||
| **Role** | Technical users who run WorldWideView on their own hardware (Raspberry Pi, home server, VPS) |
|
||||
| **Goal** | Full control over their own geospatial intelligence dashboard, no cloud dependency |
|
||||
| **Motivations** | Privacy, customization, data sovereignty, OSINT hobbyism, professional intelligence work |
|
||||
| **Technical Ability** | **High** — comfortable with Docker, environment variables, CLI tools, possibly contributing plugins |
|
||||
| **Emotional State** | Empowered but demanding. They chose self-hosting for a reason — they expect it to work without phoning home. |
|
||||
| **Definition of Success** | Instance running 24/7, plugins installed and polling reliably, data persisted locally, zero external dependencies |
|
||||
| **Pain Points** | Docker build complexity, PostgreSQL connection pooling issues, Cesium token setup, Prisma migration gotchas, plugin data not loading |
|
||||
| **Interaction Surface** | `docker-compose.yml`, `.env.local`, Setup Wizard, Layers Panel, Config Panel, Marketplace Bridge, `pnpm run dev:all` |
|
||||
|
||||
**Design implications:**
|
||||
- **Zero-config first run** — `pnpm run setup && pnpm dev` or `docker-compose up` must "just work"
|
||||
- The Setup Wizard (Cesium token prompt) is the ONLY mandatory configuration step — minimize it
|
||||
- PostgreSQL must handle concurrent reads from the app + data engine efficiently
|
||||
- Self-hosted users are the most likely to become contributors — treat their issues as high-priority
|
||||
- Data engine self-healing (fallback seeds) ensures restarts don't lose data
|
||||
- Offline capability is a differentiator — cached entities in IndexedDB survive network outages
|
||||
- `NEXT_PUBLIC_WWV_EDITION=local` must be the default, most-tested path
|
||||
|
||||
---
|
||||
|
||||
### 7. Paying Customers (Cloud Pro/Enterprise)
|
||||
|
||||
| Attribute | Description |
|
||||
|---|---|
|
||||
| **Role** | Users or organizations paying for `[user].app.worldwideview.dev` — the revenue engine |
|
||||
| **Goal** | Reliable, always-on geospatial intelligence with history, higher rate limits, and team access |
|
||||
| **Motivations** | Professional OSINT, military/defense analysis, logistics monitoring, journalism, corporate security |
|
||||
| **Technical Ability** | **Variable** — from journalists who just need a globe to security analysts who want API access |
|
||||
| **Emotional State** | **Paying customers have the lowest tolerance for bugs.** They expect enterprise-grade uptime and support. |
|
||||
| **Definition of Success** | Data is live, history works, team members can access, exports work, it doesn't go down |
|
||||
| **Pain Points** | Downtime, stale data, missing features compared to competitors, unclear what "Pro" actually gives them |
|
||||
| **Interaction Surface** | Cloud dashboard, license key input, plugin marketplace, support channels, billing UI |
|
||||
|
||||
**Design implications:**
|
||||
- **Uptime is king** — Uptime Kuma monitoring, error alerting, and rollback procedures exist for this reason
|
||||
- Tier differentiation must be clear and valuable:
|
||||
- Free: 3 users, 500MB, 24h history
|
||||
- Pro: 20 users, 5GB, full history, snapshot capture
|
||||
- Enterprise: unlimited, 50GB+, custom domains
|
||||
- License key verification (RSA-signed JWT) prevents forgery but must not be onerous UX
|
||||
- RLS tenant isolation is non-negotiable — data leaks between tenants are existential
|
||||
- Response caching at the API proxy layer makes the $0/mo server viable for multiple tenants
|
||||
- The cloud edition must feel **identical** to local — same UI, same plugins, same experience
|
||||
|
||||
---
|
||||
|
||||
### 8. Advertisers (Demo Edition Revenue)
|
||||
|
||||
| Attribute | Description |
|
||||
|---|---|
|
||||
| **Role** | Google AdSense (programmatic) — automated ad placement on the demo instance |
|
||||
| **Goal** | Display relevant ads to engaged visitors, generate clicks/impressions |
|
||||
| **Motivations** | ROI on ad spend; relevant audience targeting |
|
||||
| **Technical Ability** | N/A — they interact through Google's ad platform, not with WWV directly |
|
||||
| **Emotional State** | N/A — algorithmic. But their platform (AdSense) has strict technical requirements. |
|
||||
| **Definition of Success** | Ads render correctly, non-intrusively, on viewable screen real estate |
|
||||
| **Pain Points** | AdSense script crashes on resize, ads failing to fill on localhost/tunnels, ads overlapping interactive content |
|
||||
| **Interaction Surface** | `DemoAdStrip.tsx`, `AdUnit.tsx`, Google AdSense publisher dashboard |
|
||||
|
||||
**Design implications:**
|
||||
- Ad strip is a **structurally separate sibling container** — never overlaps the globe viewport
|
||||
- Fixed-position elements (header, timeline, sidebars) use `--ad-strip-inset` CSS variable to avoid overlap
|
||||
- AdSense `push()` errors on resize are handled by fully unmounting ad units below 850px height
|
||||
- Ads are **demo edition only** — they never appear in local or cloud editions
|
||||
- The "Why ads?" banner is a conscious UX choice that builds trust with users and is dismissible
|
||||
- Ad revenue is a temporary bridge to sustainability, not the long-term business model
|
||||
|
||||
---
|
||||
|
||||
### 9. Data Source Providers (Upstream APIs)
|
||||
|
||||
| Attribute | Description |
|
||||
|---|---|
|
||||
| **Role** | External services that provide the raw data: OpenSky, AIS providers, NASA FIRMS, ACLED, CelesTrak, GPSJam, etc. |
|
||||
| **Goal** | Serve data within their rate limits and terms of service |
|
||||
| **Motivations** | Open data mission (NASA, CelesTrak), freemium conversion (OpenSky), research community |
|
||||
| **Technical Ability** | N/A — they expose APIs; WWV consumes them |
|
||||
| **Emotional State** | Hostile if rate-limited. Neutral if respected. |
|
||||
| **Definition of Success** | API consumers stay within rate limits, attribute correctly, and don't DDOS their endpoints |
|
||||
| **Pain Points** | Credential rotation failures (OpenSky), rate limit exhaustion, unattributed scraping |
|
||||
| **Interaction Surface** | Data Engine seeders, API route proxies, `OPENSKY_CREDENTIALS` rotation, `pollingIntervalMs` settings |
|
||||
|
||||
**Design implications:**
|
||||
- **Respect upstream rate limits** — this is an ethical and practical obligation
|
||||
- Credential rotation (`OPENSKY_CREDENTIALS` comma-separated pairs) prevents per-key throttling
|
||||
- The Data Engine's 5-minute Redis throttle (`setLiveSnapshot`) is specifically designed to stay within Upstash free-tier limits
|
||||
- API proxy caching (1000 users → 1 upstream request) is architecturally essential
|
||||
- Attribution (e.g., "Data: OpenSky Network") should be visible in entity detail panels
|
||||
- Graceful degradation when APIs go down — show cached data, not error modals
|
||||
|
||||
---
|
||||
|
||||
## The Stakeholder Decision Matrix
|
||||
|
||||
When making any decision, use this matrix to identify impact:
|
||||
|
||||
| Decision Area | Owner | Core Devs | Contributors | Plugin Devs | Casual Visitors | Power Users | Paying Customers | Advertisers | Data Providers |
|
||||
|---|---|---|---|---|---|---|---|---|---|
|
||||
| **Plugin SDK change** | ⚠️ | ⚠️ | ⬜ | 🔴 | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ |
|
||||
| **UI/UX redesign** | ⚠️ | ⬜ | ⬜ | ⬜ | 🔴 | ⚠️ | 🔴 | ⚠️ | ⬜ |
|
||||
| **Rendering pipeline change** | ⚠️ | 🔴 | ⬜ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⬜ | ⬜ |
|
||||
| **Database schema migration** | ⚠️ | ⚠️ | ⬜ | ⬜ | ⬜ | 🔴 | 🔴 | ⬜ | ⬜ |
|
||||
| **New data source plugin** | ✅ | ⬜ | ✅ | ⬜ | ✅ | ✅ | ✅ | ⬜ | ⚠️ |
|
||||
| **Pricing/tier change** | 🔴 | ⬜ | ⬜ | ⚠️ | ⬜ | ⚠️ | 🔴 | ⬜ | ⬜ |
|
||||
| **Ad placement change** | ⚠️ | ⬜ | ⬜ | ⬜ | ⚠️ | ⬜ | ⬜ | 🔴 | ⬜ |
|
||||
| **API rate limit adjustment** | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⚠️ | ⬜ | 🔴 |
|
||||
| **Marketplace policy** | 🔴 | ⬜ | ⬜ | 🔴 | ⬜ | ⬜ | ⚠️ | ⬜ | ⬜ |
|
||||
| **Docker/deployment change** | 🔴 | ⚠️ | ⬜ | ⬜ | ⬜ | 🔴 | ⚠️ | ⬜ | ⬜ |
|
||||
| **License change** | 🔴 | ⚠️ | 🔴 | 🔴 | ⬜ | ⚠️ | ⬜ | ⬜ | ⬜ |
|
||||
|
||||
**Legend:** 🔴 = Primary impact (design for this person) | ⚠️ = Secondary impact (consider carefully) | ✅ = Positive impact | ⬜ = Minimal/no impact
|
||||
|
||||
---
|
||||
|
||||
## The Golden Rules
|
||||
|
||||
### 1. Every Feature Has a Human
|
||||
|
||||
Before writing a single line of code, the AI agent MUST answer:
|
||||
- **WHO** is this for? (Name the stakeholder)
|
||||
- **WHY** do they need it? (What problem does it solve for them?)
|
||||
- **HOW** will they discover/use it? (What's their journey?)
|
||||
- **WHAT** happens when it breaks? (Graceful degradation plan)
|
||||
|
||||
### 2. Reduce Friction, Not Features
|
||||
|
||||
The most dangerous failure mode is building powerful systems with hostile interfaces. Apply the **Principle of Least Effort**:
|
||||
- Contributors: one-command setup, not a wiki page of prerequisites
|
||||
- Plugin devs: `renderEntity()` returns an object, not a Cesium Primitive
|
||||
- Casual visitors: zero onboarding, zero configuration
|
||||
- Power users: sensible defaults, optional configuration
|
||||
- Paying customers: it just works, always
|
||||
|
||||
### 3. Design for the Least Technical User in Each Cohort
|
||||
|
||||
| Cohort | Least Technical Member | Design Target |
|
||||
|---|---|---|
|
||||
| Plugin Developers | Data analyst who can write JSON | Declarative plugin format |
|
||||
| Contributors | Junior dev on their first open source PR | Scaffold scripts + clear CONTRIBUTING.md |
|
||||
| Casual Visitors | Non-technical person who followed a Twitter link | Auto-loading layers, intuitive globe controls |
|
||||
| Power Users | Sysadmin who can `docker-compose up` but doesn't know Next.js | Pre-built Docker images, `.env` only config |
|
||||
| Paying Customers | Journalist tracking a conflict | Clear UI, no jargon, exportable data |
|
||||
|
||||
### 4. Protect the Ecosystem Trust
|
||||
|
||||
The trust hierarchy is cryptographically enforced (Ed25519 signed registry), but trust is also social:
|
||||
- **Built-in plugins** must always work — they're the first impression
|
||||
- **Verified plugins** carry WorldWideView's reputation — review them seriously
|
||||
- **Unverified plugins** get a warning dialog — users make informed decisions
|
||||
- **Plugin developers** who see installs and analytics stay motivated
|
||||
- **Data providers** who aren't rate-limit abused will keep serving data
|
||||
|
||||
### 5. Revenue Serves Sustainability, Not Extraction
|
||||
|
||||
The business model exists to keep the project alive:
|
||||
- Ads on demo = temporary hosting cost recovery (transparent "Why ads?" banner)
|
||||
- Cloud Pro = value exchange (history, higher limits, team access)
|
||||
- Marketplace cut = sustainable ecosystem (Stripe Connect revenue split)
|
||||
- Plugin developer monetization = VS Code model (developers set their own prices)
|
||||
|
||||
Never design a feature that extracts value from users without returning it. The demo must always be useful, not crippled.
|
||||
|
||||
---
|
||||
|
||||
## Applying This Document
|
||||
|
||||
### For the AI Agent
|
||||
|
||||
When the agent is asked to implement a feature, modify architecture, or solve a bug, it MUST:
|
||||
|
||||
1. **Identify affected stakeholders** from the list above
|
||||
2. **Consider the least-technical user** in each affected cohort
|
||||
3. **Check the decision matrix** for impact severity
|
||||
4. **Apply the golden rules** to the implementation approach
|
||||
5. **Document stakeholder considerations** in PR descriptions and implementation plans
|
||||
|
||||
### For Human Developers
|
||||
|
||||
When reviewing PRs or proposing features, ask:
|
||||
- "Did we consider how this affects plugin developers?"
|
||||
- "Will a first-time contributor understand this?"
|
||||
- "Does this work on the demo without configuration?"
|
||||
- "Will this survive a Docker restart on the ThinkPad?"
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Change |
|
||||
|---|---|
|
||||
| 2026-04-05 | Initial stakeholder map created from comprehensive project research |
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: Troubleshooting and debugging guidelines for WorldWideView, covering latency, logging, and namespace collisions.
|
||||
---
|
||||
|
||||
# Troubleshooting and Debugging
|
||||
|
||||
## 1. Plugin Data Latency
|
||||
If there is a noticeable delay (e.g., ~1 second) between enabling a plugin and the initial data arriving on the globe, **do not assume the UI is blocking**.
|
||||
- **WebSocket Handshake**: Initial latency is often caused by the time it takes to establish a new WebSocket connection to the engine's `/stream`.
|
||||
- **Upstream Cooldowns**: Plugins querying external providers (like OpenSky for `aviation`) have strict rate limits. If a snapshot returns a `404`, it might mean the seeder is in a cooldown period or hasn't successfully fetched data yet. This is expected behavior.
|
||||
- **Diagnosis**: Instrument the `DataBusSubscriber` and `WsClient` with timing logs (`performance.now()`) to track exactly where the bottleneck occurs (manifest discovery vs connection establishment vs first payload).
|
||||
|
||||
## 2. Log Verbosity and Structured Logging
|
||||
We employ a **structured logging strategy** in the frontend to reduce noise and improve readability.
|
||||
- **Rule**: Do not add excessive `console.log` statements that dump raw JSON payloads or stream contents directly to the console in core files like `WsClient.ts` or `PluginManager.ts`.
|
||||
- **Implementation**: If detailed logs are needed, use conditional debug levels or summarize the output (e.g., logging payload sizes or entity counts instead of the full object array). This ensures critical diagnostic information remains visible without overflowing the terminal.
|
||||
|
||||
## 3. Namespace Collisions
|
||||
If a plugin fails to load in the Data Engine with a `404` or `Error [ERR_MODULE_NOT_FOUND]` error during startup:
|
||||
- **Root Cause**: The seeder may exist simultaneously in both the `wwv-seeders-community` and `wwv-seeders-private` repositories.
|
||||
- **Resolution**: Seeders must have a unique namespace. Ensure that private plugins (e.g., `aviation`, `maritime`, `military-aviation`) are explicitly removed from the community repository to prevent workspace-level module resolution failures when the V2 engine attempts to load them. Private seeders take priority, but overlapping names will cause dependency conflicts.
|
||||
@@ -1,5 +0,0 @@
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"code-review@claude-plugins-official": false
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"env": {
|
||||
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
|
||||
},
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Read(src/**)",
|
||||
"Bash(npm test)"
|
||||
],
|
||||
"deny": [
|
||||
"Read(.env)",
|
||||
"Write(config.json)"
|
||||
],
|
||||
"defaultMode": "bypassPermissions"
|
||||
},
|
||||
"prefersReducedMotion": false
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
name: architectural-decision-records
|
||||
description: Use when making significant architectural decisions, adding new patterns, or altering core workflows. This skill ensures that all major technical choices are documented via ADRs.
|
||||
---
|
||||
|
||||
# Architectural Decision Records (ADRs)
|
||||
|
||||
## When to use this skill
|
||||
Trigger this skill whenever you are about to introduce a new architectural pattern, make a load-bearing contract change, or bypass an established standard for a necessary reason.
|
||||
|
||||
## Guidelines
|
||||
1. **Never make a major architectural change without an ADR**.
|
||||
2. Store ADRs in `docs/architecture/decisions/` (create this directory if it doesn't exist).
|
||||
3. An ADR must follow this exact structure:
|
||||
- **Title**: Short, descriptive noun phrase.
|
||||
- **Context**: What is the problem we are solving? What forces are at play? (Be objective).
|
||||
- **Decision**: What is the specific change or pattern we are adopting?
|
||||
- **Consequences**: What becomes easier because of this change? What becomes harder? (There are always trade-offs).
|
||||
|
||||
## Actionable Steps
|
||||
When tasked with a major architecture change, pause and explicitly state: *"This requires an Architectural Decision Record."* Draft the ADR and ask the user to approve the reasoning *before* writing the implementation code.
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
name: bing-news-hydration
|
||||
description: Hydrate event attributes with news URLs and images via Bing RSS
|
||||
---
|
||||
|
||||
# Bing News Event Hydration Workflow
|
||||
|
||||
When enriching a simulation database or CSV dataset via automation, standard search engines like Google will aggressively block headless scrapers or `fetch` requests with CAPTCHA walls. This workflow uses **Bing News RSS** as an open, structured payload to discover news articles and then bypasses its tracking wrapper to scrape `og:image` tags.
|
||||
|
||||
### 1. Structure the Request
|
||||
Bing offers a developer-friendly RSS feed option that bypasses captchas. Construct the query string properly depending on whether you want an exact match or a broad categorical match (e.g. for fictional simulation events).
|
||||
|
||||
```javascript
|
||||
const query = encodeURIComponent("AIR STRIKE Tehran Iran Israel conflict");
|
||||
const url = `https://www.bing.com/news/search?q=${query}&format=rss`;
|
||||
```
|
||||
|
||||
### 2. Bypass Bing Click-Tracking
|
||||
When Bing RSS returns an article, the URL will be wrapped in a tracking link (`apiclick.aspx`). Fetching this URL directly will *fail* to return the article HTML, as Bing uses a client-side JavaScript redirect. To extract the real article link, you must unescape the XML, map the `url=` parameter, and decode it.
|
||||
|
||||
```javascript
|
||||
async function bingNewsSearch(query) {
|
||||
const res = await fetch(`https://www.bing.com/news/search?q=${encodeURIComponent(query)}&format=rss`, {
|
||||
headers: { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) WorldWideView-Hydrator" }
|
||||
});
|
||||
|
||||
const xml = await res.text();
|
||||
const itemMatch = xml.match(/<item>[\s\S]*?<link>(.*?)<\/link>/i);
|
||||
|
||||
if (itemMatch && itemMatch[1]) {
|
||||
// 1. Unescape XML entities
|
||||
let encodedUrl = itemMatch[1].trim().replace(/&/g, '&');
|
||||
|
||||
// 2. Extract the `url=` target and decode it
|
||||
const urlMatch = encodedUrl.match(/[?&]url=([^&]+)/i);
|
||||
if (urlMatch && urlMatch[1]) {
|
||||
return decodeURIComponent(urlMatch[1]);
|
||||
}
|
||||
return encodedUrl;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Fetch Article `og:image`
|
||||
Once you have the direct real article URL (e.g., Al Jazeera, MSN, etc.), make a standard HTTP fetch to the webpage. You can regex parse the HTML (without needing a full DOM parser or headless browser) to extract the Open Graph preview image.
|
||||
|
||||
```javascript
|
||||
async function scrapeOgImage(articleUrl) {
|
||||
// Note: Always sleep/wait a few hundred ms between requests to respect rate limits
|
||||
const res = await fetch(articleUrl, {
|
||||
headers: { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) WorldWideView-Hydrator" }
|
||||
});
|
||||
const html = await res.text();
|
||||
|
||||
const ogMatch = html.match(/<meta[^>]*property=["']og:image["'][^>]*content=["']([^"']+)["']/i)
|
||||
|| html.match(/<meta[^>]*content=["']([^"']+)["'][^>]*property=["']og:image["']/i);
|
||||
|
||||
return ogMatch ? ogMatch[1] : null;
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Apply to Dataset
|
||||
Wrap these utility functions in an async loop covering your DB output:
|
||||
1. Filter out broad non-searchable events (e.g. `POSTURING`).
|
||||
2. Run `bingNewsSearch(title)`.
|
||||
3. If successful, run `scrapeOgImage(target)`.
|
||||
4. Update the SQL DB via `UPDATE table SET ...` payload injection.
|
||||
|
||||
**Important**: Implement delays (`await sleep(500);`) between fetches to avoid being IP blocklisted by target news outlets.
|
||||
@@ -1,73 +0,0 @@
|
||||
---
|
||||
name: cesium-context7
|
||||
description: "Fetches up-to-date documentation for Cesium, CesiumJS, Cesium Viewer, 3D Tiles, Unreal Engine integration, Unity integration, cesium-unreal, cesium-unity, ACesium3DTileset, ACesiumGeoreference, Globe Anchor, Cesium plugin, georeferencing, and Cesium-related APIs using Context7 MCP tools. Useful for CesiumJS classes (Viewer, Entity, Camera, Scene, Cartesian3, etc.), Unreal Engine Cesium components, Unity Cesium components, 3D Tiles specification, and Cesium integrations. Use query-docs with library IDs: /cesiumgs/cesium (CesiumJS), /cesiumgs/cesium-unreal (Unreal), /cesiumgs/cesium-unity (Unity), /websites/ogc_cs_22-025r4 (3D Tiles spec)."
|
||||
---
|
||||
|
||||
# Context7 for Cesium Development
|
||||
|
||||
This skill provides access to up-to-date Cesium documentation for CesiumJS, Unreal Engine integration, and Unity integration.
|
||||
|
||||
When working with Cesium-related code, use Context7 MCP Server tools to fetch current documentation before providing answers or generating code.
|
||||
|
||||
## Available Tools
|
||||
|
||||
### 1. `resolve-library-id`
|
||||
|
||||
Search for libraries and retrieve their Context7 library IDs.
|
||||
|
||||
**⚠️ Only use this tool when it's unclear which library to use. For Cesium projects, use the Known Library IDs listed below.**
|
||||
|
||||
**Parameters**:
|
||||
|
||||
- `libraryName` (string, required): Name of the library to search
|
||||
- `query` (string, optional): Additional search context
|
||||
|
||||
**Example use case**: Find the correct library ID for an unfamiliar library or when the library ID is unknown.
|
||||
|
||||
### 2. `query-docs`
|
||||
|
||||
Retrieve documentation for a specific library and query.
|
||||
|
||||
**Parameters**:
|
||||
|
||||
- `libraryId` (string, required): Context7 library ID
|
||||
- `query` (string, required): Documentation query or topic
|
||||
- `version` (string, optional): Specific library version
|
||||
|
||||
**Example use case**: Get documentation for Cesium Viewer initialization using library `/cesiumgs/cesium`.
|
||||
|
||||
## Known Library IDs
|
||||
|
||||
### CesiumJS API Documentation
|
||||
|
||||
For class constructors, methods, and properties (e.g., Viewer, Entity, Cartesian3, Camera methods, Scene properties):
|
||||
|
||||
- Library ID: `/cesiumgs/cesium`
|
||||
|
||||
### Cesium for Unreal Engine
|
||||
|
||||
For Unreal Engine integration (e.g., ACesium3DTileset, ACesiumGeoreference, Blueprint integration):
|
||||
|
||||
- Library ID: `/cesiumgs/cesium-unreal`
|
||||
|
||||
### Cesium for Unity
|
||||
|
||||
For Unity integration (e.g., Cesium3DTileset component, CesiumCameraController, C# scripting):
|
||||
|
||||
- Library ID: `/cesiumgs/cesium-unity`
|
||||
|
||||
### 3D Tiles Specification
|
||||
|
||||
For tile formats and schema details (e.g., tileset JSON structure, refinement strategies, metadata schemas):
|
||||
|
||||
- Library ID: `/websites/ogc_cs_22-025r4`
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
- Use the Known Library IDs listed above for Cesium-related queries
|
||||
- When a question requires information from multiple sources (e.g., CesiumJS API + 3D Tiles spec, or Unreal integration + CesiumJS concepts), make separate `query-docs` calls with different library IDs to gather comprehensive documentation
|
||||
- Use `resolve-library-id` when the library is unknown, not listed in Known Library IDs, or when it's unclear which library best fits the question
|
||||
- Use `query-docs` to fetch documentation before generating code to ensure accuracy
|
||||
- Specify the `version` parameter when working with a specific version
|
||||
- Provide clear, specific queries to get the most relevant documentation
|
||||
- Avoid hallucinations by using current, version-specific documentation
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
name: commit
|
||||
description: Use before every git commit in the WorldWideView project. Enforces mandatory semantic version bumping and conventional commit message format per AGENTS.md §5.7.
|
||||
---
|
||||
|
||||
# Commit Workflow
|
||||
|
||||
> [!WARNING]
|
||||
> You **MUST** bump the version in the relevant `package.json` **before** running `git commit`. Skipping this will violate the project's versioning contract.
|
||||
|
||||
## Step 1 — Identify what changed
|
||||
|
||||
Determine which packages have been modified (`git diff --name-only`). The version bump goes in:
|
||||
- The **specific plugin's** `package.json` if only that plugin changed
|
||||
- The **root** `package.json` if the main app (`src/`) changed
|
||||
- The **data engine's** `package.json` (`packages/wwv-data-engine/package.json`) if the data engine changed
|
||||
- Multiple `package.json` files if multiple packages changed
|
||||
|
||||
## Step 2 — Determine the bump type
|
||||
|
||||
| Commit prefix | Version bump |
|
||||
|---|---|
|
||||
| `feat:` | **Minor** (x.**Y**.0) |
|
||||
| `fix:` / `refactor:` / `perf:` | **Patch** (x.y.**Z**) |
|
||||
| `BREAKING CHANGE` | **Major** (**X**.0.0) — rare, confirm with user |
|
||||
|
||||
## Step 3 — Handle multiple accumulated changes
|
||||
|
||||
If there are multiple uncommitted changes across different types:
|
||||
|
||||
**Option A — Individual commits** (preferred for clean history):
|
||||
Commit each logical change separately, bumping the version each time.
|
||||
|
||||
**Option B — Batch commit**:
|
||||
Commit all at once, but bump the version cumulatively. If changes include both a `feat:` and two `fix:`, that's a Minor bump (the highest level wins). Detail each change in the commit description.
|
||||
|
||||
## Step 4 — Write the commit message
|
||||
|
||||
Format:
|
||||
```
|
||||
<type>(<scope>): <short description> [<Level>]
|
||||
|
||||
- <change 1> [Minor/Patch/Major]
|
||||
- <change 2> [Minor/Patch/Major]
|
||||
```
|
||||
|
||||
The `[Level]` suffix at the end of the first line is the cumulative level for the commit.
|
||||
Each bullet in the body must label its individual level.
|
||||
|
||||
**Scope** = package name or area (e.g., `civil-unrest`, `data-engine`, `aviation`, `core`)
|
||||
|
||||
Examples:
|
||||
```
|
||||
feat(civil-unrest): add GDELT integration for protest feed [Minor]
|
||||
|
||||
- add GDELT API seeder to wwv-data-engine [Minor]
|
||||
- add civil-unrest proxy route in Next.js API [Patch]
|
||||
```
|
||||
|
||||
```
|
||||
fix(aviation): correct OpenSky credential rotation logic [Patch]
|
||||
```
|
||||
|
||||
## Step 5 — Execute
|
||||
|
||||
1. Bump version in relevant `package.json`(s)
|
||||
2. Stage all changes including the `package.json` bump
|
||||
3. Commit with the message above
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
name: context7
|
||||
description: Retrieve up-to-date documentation for software libraries, frameworks, and components via the Context7 API. This skill should be used when looking up documentation for any programming library or framework, finding code examples for specific APIs or features, verifying correct usage of library functions, or obtaining current information about library APIs that may have changed since training.
|
||||
---
|
||||
|
||||
# Context7
|
||||
|
||||
## Overview
|
||||
|
||||
This skill enables retrieval of current documentation for software libraries and components by querying the Context7 API via curl. Use it instead of relying on potentially outdated training data.
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Search for the Library
|
||||
|
||||
To find the Context7 library ID, query the search endpoint:
|
||||
|
||||
```bash
|
||||
curl -s "https://context7.com/api/v2/libs/search?libraryName=LIBRARY_NAME&query=TOPIC" | jq '.results[0]'
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `libraryName` (required): The library name to search for (e.g., "react", "nextjs", "fastapi", "axios")
|
||||
- `query` (required): A description of the topic for relevance ranking
|
||||
|
||||
**Response fields:**
|
||||
- `id`: Library identifier for the context endpoint (e.g., `/websites/react_dev_reference`)
|
||||
- `title`: Human-readable library name
|
||||
- `description`: Brief description of the library
|
||||
- `totalSnippets`: Number of documentation snippets available
|
||||
|
||||
### Step 2: Fetch Documentation
|
||||
|
||||
To retrieve documentation, use the library ID from step 1:
|
||||
|
||||
```bash
|
||||
curl -s "https://context7.com/api/v2/context?libraryId=LIBRARY_ID&query=TOPIC&type=txt"
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `libraryId` (required): The library ID from search results
|
||||
- `query` (required): The specific topic to retrieve documentation for
|
||||
- `type` (optional): Response format - `json` (default) or `txt` (plain text, more readable)
|
||||
|
||||
## Examples
|
||||
|
||||
### React hooks documentation
|
||||
|
||||
```bash
|
||||
# Find React library ID
|
||||
curl -s "https://context7.com/api/v2/libs/search?libraryName=react&query=hooks" | jq '.results[0].id'
|
||||
# Returns: "/websites/react_dev_reference"
|
||||
|
||||
# Fetch useState documentation
|
||||
curl -s "https://context7.com/api/v2/context?libraryId=/websites/react_dev_reference&query=useState&type=txt"
|
||||
```
|
||||
|
||||
### Next.js routing documentation
|
||||
|
||||
```bash
|
||||
# Find Next.js library ID
|
||||
curl -s "https://context7.com/api/v2/libs/search?libraryName=nextjs&query=routing" | jq '.results[0].id'
|
||||
|
||||
# Fetch app router documentation
|
||||
curl -s "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=app+router&type=txt"
|
||||
```
|
||||
|
||||
### FastAPI dependency injection
|
||||
|
||||
```bash
|
||||
# Find FastAPI library ID
|
||||
curl -s "https://context7.com/api/v2/libs/search?libraryName=fastapi&query=dependencies" | jq '.results[0].id'
|
||||
|
||||
# Fetch dependency injection documentation
|
||||
curl -s "https://context7.com/api/v2/context?libraryId=/fastapi/fastapi&query=dependency+injection&type=txt"
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `type=txt` for more readable output
|
||||
- Use `jq` to filter and format JSON responses
|
||||
- Be specific with the `query` parameter to improve relevance ranking
|
||||
- If the first search result is not correct, check additional results in the array
|
||||
- URL-encode query parameters containing spaces (use `+` or `%20`)
|
||||
- No API key is required for basic usage (rate-limited)
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
name: create-command
|
||||
description: Guide for creating new custom Claude commands with proper structure.
|
||||
---
|
||||
|
||||
# Create Command
|
||||
|
||||
Guide for creating new custom Claude commands with proper structure.
|
||||
|
||||
## Process:
|
||||
|
||||
### 1. Understanding Purpose
|
||||
- What problem does this command solve?
|
||||
- Who will use this command?
|
||||
- What is the expected output?
|
||||
- How will users interact with it?
|
||||
|
||||
### 2. Category Classification
|
||||
Determine command type:
|
||||
- **Planning**: Project setup, architecture decisions
|
||||
- **Implementation**: Code generation, feature development
|
||||
- **Analysis**: Code review, performance analysis
|
||||
- **Testing**: Test creation, validation
|
||||
- **Documentation**: Docs generation, updates
|
||||
- **Workflow**: Multi-step processes
|
||||
- **Utility**: Helper commands, tools
|
||||
|
||||
### 3. Pattern Selection
|
||||
Study similar existing commands:
|
||||
- Analyze structure and flow
|
||||
- Note common patterns
|
||||
- Identify reusable components
|
||||
- Follow established conventions
|
||||
|
||||
### 4. Command Location
|
||||
Choose appropriate location:
|
||||
- **Project-specific**: `.claude/commands/`
|
||||
- **User-level**: `~/.claude/commands/`
|
||||
- Consider reusability and context
|
||||
|
||||
### 5. Command Structure
|
||||
Create with these sections:
|
||||
- **Title**: Clear, action-oriented name
|
||||
- **Description**: One-line summary
|
||||
- **Usage**: How to invoke with parameters
|
||||
- **Process**: Step-by-step instructions
|
||||
- **Examples**: Concrete usage examples
|
||||
- **Output**: Expected results
|
||||
- **Notes**: Special considerations
|
||||
|
||||
## Template:
|
||||
```markdown
|
||||
# Command Name
|
||||
|
||||
Brief description of what this command does.
|
||||
|
||||
## Usage:
|
||||
`/command-name [arguments]`
|
||||
|
||||
## Process:
|
||||
1. First step
|
||||
2. Second step
|
||||
3. Third step
|
||||
|
||||
## Examples:
|
||||
- Example 1
|
||||
- Example 2
|
||||
|
||||
## Notes:
|
||||
- Important considerations
|
||||
- Limitations
|
||||
```
|
||||
|
||||
## Best Practices:
|
||||
- Keep commands focused and single-purpose
|
||||
- Include parameter validation
|
||||
- Provide helpful error messages
|
||||
- Document expected inputs/outputs
|
||||
- Consider edge cases
|
||||
- Test thoroughly before finalizing
|
||||
@@ -1,152 +0,0 @@
|
||||
---
|
||||
name: create-prd
|
||||
description: Create a Product Requirements Document from conversation
|
||||
argument-hint: [output-filename]
|
||||
---
|
||||
|
||||
# Create PRD: Generate Product Requirements Document
|
||||
|
||||
## Overview
|
||||
|
||||
Generate a comprehensive Product Requirements Document (PRD) based on the current conversation context and requirements discussed. Use the structure and sections defined below to create a thorough, professional PRD.
|
||||
|
||||
## Output File
|
||||
|
||||
Write the PRD to: `$ARGUMENTS` (default: `PRD.md`)
|
||||
|
||||
## PRD Structure
|
||||
|
||||
Create a well-structured PRD with the following sections. Adapt depth and detail based on available information:
|
||||
|
||||
### Required Sections
|
||||
|
||||
**1. Executive Summary**
|
||||
- Concise product overview (2-3 paragraphs)
|
||||
- Core value proposition
|
||||
- MVP goal statement
|
||||
|
||||
**2. Mission**
|
||||
- Product mission statement
|
||||
- Core principles (3-5 key principles)
|
||||
|
||||
**3. Target Users**
|
||||
- Primary user personas
|
||||
- Technical comfort level
|
||||
- Key user needs and pain points
|
||||
|
||||
**4. MVP Scope**
|
||||
- **In Scope:** Core functionality for MVP (use ✅ checkboxes)
|
||||
- **Out of Scope:** Features deferred to future phases (use ❌ checkboxes)
|
||||
- Group by categories (Core Functionality, Technical, Integration, Deployment)
|
||||
|
||||
**5. User Stories**
|
||||
- Primary user stories (5-8 stories) in format: "As a [user], I want to [action], so that [benefit]"
|
||||
- Include concrete examples for each story
|
||||
- Add technical user stories if relevant
|
||||
|
||||
**6. Core Architecture & Patterns**
|
||||
- High-level architecture approach
|
||||
- Directory structure (if applicable)
|
||||
- Key design patterns and principles
|
||||
- Technology-specific patterns
|
||||
|
||||
**7. Tools/Features**
|
||||
- Detailed feature specifications
|
||||
- If building an agent: Tool designs with purpose, operations, and key features
|
||||
- If building an app: Core feature breakdown
|
||||
|
||||
**8. Technology Stack**
|
||||
- Backend/Frontend technologies with versions
|
||||
- Dependencies and libraries
|
||||
- Optional dependencies
|
||||
- Third-party integrations
|
||||
|
||||
**9. Security & Configuration**
|
||||
- Authentication/authorization approach
|
||||
- Configuration management (environment variables, settings)
|
||||
- Security scope (in-scope and out-of-scope)
|
||||
- Deployment considerations
|
||||
|
||||
**10. API Specification** (if applicable)
|
||||
- Endpoint definitions
|
||||
- Request/response formats
|
||||
- Authentication requirements
|
||||
- Example payloads
|
||||
|
||||
**11. Success Criteria**
|
||||
- MVP success definition
|
||||
- Functional requirements (use ✅ checkboxes)
|
||||
- Quality indicators
|
||||
- User experience goals
|
||||
|
||||
**12. Implementation Phases**
|
||||
- Break down into 3-4 phases
|
||||
- Each phase includes: Goal, Deliverables (✅ checkboxes), Validation criteria
|
||||
- Realistic timeline estimates
|
||||
|
||||
**13. Future Considerations**
|
||||
- Post-MVP enhancements
|
||||
- Integration opportunities
|
||||
- Advanced features for later phases
|
||||
|
||||
**14. Risks & Mitigations**
|
||||
- 3-5 key risks with specific mitigation strategies
|
||||
|
||||
**15. Appendix** (if applicable)
|
||||
- Related documents
|
||||
- Key dependencies with links
|
||||
- Repository/project structure
|
||||
|
||||
## Instructions
|
||||
|
||||
### 1. Extract Requirements
|
||||
- Review the entire conversation history
|
||||
- Identify explicit requirements and implicit needs
|
||||
- Note technical constraints and preferences
|
||||
- Capture user goals and success criteria
|
||||
|
||||
### 2. Synthesize Information
|
||||
- Organize requirements into appropriate sections
|
||||
- Fill in reasonable assumptions where details are missing
|
||||
- Maintain consistency across sections
|
||||
- Ensure technical feasibility
|
||||
|
||||
### 3. Write the PRD
|
||||
- Use clear, professional language
|
||||
- Include concrete examples and specifics
|
||||
- Use markdown formatting (headings, lists, code blocks, checkboxes)
|
||||
- Add code snippets for technical sections where helpful
|
||||
- Keep Executive Summary concise but comprehensive
|
||||
|
||||
### 4. Quality Checks
|
||||
- ✅ All required sections present
|
||||
- ✅ User stories have clear benefits
|
||||
- ✅ MVP scope is realistic and well-defined
|
||||
- ✅ Technology choices are justified
|
||||
- ✅ Implementation phases are actionable
|
||||
- ✅ Success criteria are measurable
|
||||
- ✅ Consistent terminology throughout
|
||||
|
||||
## Style Guidelines
|
||||
|
||||
- **Tone:** Professional, clear, action-oriented
|
||||
- **Format:** Use markdown extensively (headings, lists, code blocks, tables)
|
||||
- **Checkboxes:** Use ✅ for in-scope items, ❌ for out-of-scope
|
||||
- **Specificity:** Prefer concrete examples over abstract descriptions
|
||||
- **Length:** Comprehensive but scannable (typically 30-60 sections worth of content)
|
||||
|
||||
## Output Confirmation
|
||||
|
||||
After creating the PRD:
|
||||
1. Confirm the file path where it was written
|
||||
2. Provide a brief summary of the PRD contents
|
||||
3. Highlight any assumptions made due to missing information
|
||||
4. Suggest next steps (e.g., review, refinement, planning)
|
||||
|
||||
## Notes
|
||||
|
||||
- If critical information is missing, ask clarifying questions before generating
|
||||
- Adapt section depth based on available details
|
||||
- For highly technical products, emphasize architecture and technical stack
|
||||
- For user-facing products, emphasize user stories and experience
|
||||
- This command contains the complete PRD template structure - no external references needed
|
||||
@@ -1,157 +0,0 @@
|
||||
---
|
||||
name: create-rules
|
||||
description: Create global rules (CLAUDE.md) from codebase analysis
|
||||
---
|
||||
|
||||
# Create Global Rules
|
||||
|
||||
Generate a CLAUDE.md file by analyzing the codebase and extracting patterns.
|
||||
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Create project-specific global rules that give Claude context about:
|
||||
- What this project is
|
||||
- Technologies used
|
||||
- How the code is organized
|
||||
- Patterns and conventions to follow
|
||||
- How to build, test, and validate
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: DISCOVER
|
||||
|
||||
### Identify Project Type
|
||||
|
||||
First, determine what kind of project this is:
|
||||
|
||||
| Type | Indicators |
|
||||
|------|------------|
|
||||
| Web App (Full-stack) | Separate client/server dirs, API routes |
|
||||
| Web App (Frontend) | React/Vue/Svelte, no server code |
|
||||
| API/Backend | Express/Fastify/etc, no frontend |
|
||||
| Library/Package | `main`/`exports` in package.json, publishable |
|
||||
| CLI Tool | `bin` in package.json, command-line interface |
|
||||
| Monorepo | Multiple packages, workspaces config |
|
||||
| Script/Automation | Standalone scripts, task-focused |
|
||||
|
||||
### Analyze Configuration
|
||||
|
||||
Look at root configuration files:
|
||||
|
||||
```
|
||||
package.json → dependencies, scripts, type
|
||||
tsconfig.json → TypeScript settings
|
||||
vite.config.* → Build tool
|
||||
*.config.js/ts → Various tool configs
|
||||
```
|
||||
|
||||
### Map Directory Structure
|
||||
|
||||
Explore the codebase to understand organization:
|
||||
- Where does source code live?
|
||||
- Where are tests?
|
||||
- Any shared code?
|
||||
- Configuration locations?
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: ANALYZE
|
||||
|
||||
### Extract Tech Stack
|
||||
|
||||
From package.json and config files, identify:
|
||||
- Runtime/Language (Node, Bun, Deno, browser)
|
||||
- Framework(s)
|
||||
- Database (if any)
|
||||
- Testing tools
|
||||
- Build tools
|
||||
- Linting/formatting
|
||||
|
||||
### Identify Patterns
|
||||
|
||||
Study existing code for:
|
||||
- **Naming**: How are files, functions, classes named?
|
||||
- **Structure**: How is code organized within files?
|
||||
- **Errors**: How are errors created and handled?
|
||||
- **Types**: How are types/interfaces defined?
|
||||
- **Tests**: How are tests structured?
|
||||
|
||||
### Find Key Files
|
||||
|
||||
Identify files that are important to understand:
|
||||
- Entry points
|
||||
- Configuration
|
||||
- Core business logic
|
||||
- Shared utilities
|
||||
- Type definitions
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: GENERATE
|
||||
|
||||
### Create CLAUDE.md
|
||||
|
||||
Use the template at `.agents/CLAUDE-template.md` as a starting point.
|
||||
|
||||
**Output path**: `CLAUDE.md` (project root)
|
||||
|
||||
**Adapt to the project:**
|
||||
- Remove sections that don't apply
|
||||
- Add sections specific to this project type
|
||||
- Keep it concise - focus on what's useful
|
||||
|
||||
**Key sections to include:**
|
||||
|
||||
1. **Project Overview** - What is this and what does it do?
|
||||
2. **Tech Stack** - What technologies are used?
|
||||
3. **Commands** - How to dev, build, test, lint?
|
||||
4. **Structure** - How is the code organized?
|
||||
5. **Patterns** - What conventions should be followed?
|
||||
6. **Key Files** - What files are important to know?
|
||||
|
||||
**Optional sections (add if relevant):**
|
||||
- Architecture (for complex apps)
|
||||
- API endpoints (for backends)
|
||||
- Component patterns (for frontends)
|
||||
- Database patterns (if using a DB)
|
||||
- On-demand context references
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: OUTPUT
|
||||
|
||||
```markdown
|
||||
## Global Rules Created
|
||||
|
||||
**File**: `CLAUDE.md`
|
||||
|
||||
### Project Type
|
||||
|
||||
{Detected project type}
|
||||
|
||||
### Tech Stack Summary
|
||||
|
||||
{Key technologies detected}
|
||||
|
||||
### Structure
|
||||
|
||||
{Brief structure overview}
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. Review the generated `CLAUDE.md`
|
||||
2. Add any project-specific notes
|
||||
3. Remove any sections that don't apply
|
||||
4. Optionally create reference docs in `.agents/reference/`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
- Keep CLAUDE.md focused and scannable
|
||||
- Don't duplicate information that's in other docs (link instead)
|
||||
- Focus on patterns and conventions, not exhaustive documentation
|
||||
- Update it as the project evolves
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
name: creating-github-issues
|
||||
description: Use when creating a new GitHub issue or Pull Request, or when capturing tasks, bugs, or feature proposals in the external issue tracker.
|
||||
---
|
||||
|
||||
# Creating GitHub Issues & PRs
|
||||
|
||||
## Overview
|
||||
Never invent issue structures or write generic Pull Request bodies. Always read and strictly adhere to the repository's `.github/ISSUE_TEMPLATE/` and `PULL_REQUEST_TEMPLATE.md` files.
|
||||
|
||||
## When to Use
|
||||
- You are about to run `gh issue create`.
|
||||
- You are about to run `gh pr create`.
|
||||
- The user asks you to log a bug, propose a feature, or create a PR.
|
||||
|
||||
## Core Pattern
|
||||
|
||||
### 1. Identify the Correct Template
|
||||
Before writing *any* issue or PR descriptions, stop and check the `.github` directory.
|
||||
- For PRs: Read `.github/PULL_REQUEST_TEMPLATE.md`.
|
||||
- For Issues: Read the contents of `.github/ISSUE_TEMPLATE/` and select the appropriate markdown file (e.g., `bug_report.md`, `plugin_proposal.md`).
|
||||
|
||||
### 2. Parse the Frontmatter (Issues Only)
|
||||
Issue templates contain YAML frontmatter. You must manually parse and apply these attributes when running the GitHub CLI command:
|
||||
- `title:` → Must use the required prefix (e.g., `[BUG] The title...`).
|
||||
- `labels:` → Pass these to the `--label` flag.
|
||||
- `assignees:` → Pass to `--assignee` if specified.
|
||||
|
||||
### 3. Populate the EXACT Markdown Body
|
||||
When constructing the body (e.g., using a temporary file or `$(cat <<'EOF')`), you must include **all** the markdown headers, questions, and checklists from the template. Answer the questions inline. Leave sections intact even if the content is "N/A" or empty.
|
||||
|
||||
## Before / After
|
||||
|
||||
❌ **BAD: Making up structure**
|
||||
```bash
|
||||
# Agent invents its own problem description format
|
||||
gh issue create \
|
||||
--title "Data engine bug" \
|
||||
--body "## Context
|
||||
It doesn't work.
|
||||
## Fix
|
||||
Need to update it." \
|
||||
--label "bug"
|
||||
```
|
||||
|
||||
✅ **GOOD: Using the exact template requirements**
|
||||
```bash
|
||||
# Agent read bug_report.md first, applying its frontmatter and body format
|
||||
gh issue create \
|
||||
--title "[BUG] Data engine extrapolation fails on landing" \
|
||||
--label "bug" \
|
||||
--body "$(cat <<'EOF'
|
||||
**Describe the bug**
|
||||
Extrapolation logic in animationHelpers.ts fails to halt when aircraft altitude reaches 0.
|
||||
|
||||
**To Reproduce**
|
||||
Steps to reproduce the behavior:
|
||||
1. Watch aircraft entity descend to airport.
|
||||
2. Observe it continues moving horizontally past the runway.
|
||||
|
||||
**Expected behavior**
|
||||
Entity should halt animation...
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Action | Target File to Read First |
|
||||
|--------|---------------------------|
|
||||
| Submitting a bug | `.github/ISSUE_TEMPLATE/bug_report.md` |
|
||||
| Proposing a feature | `.github/ISSUE_TEMPLATE/feature_request.md` |
|
||||
| New data source plan | `.github/ISSUE_TEMPLATE/plugin_proposal.md` |
|
||||
| Opening a PR | `.github/PULL_REQUEST_TEMPLATE.md` |
|
||||
|
||||
## Red Flags - STOP and Start Over
|
||||
|
||||
- Using `gh issue create` or `gh pr create` without explicitly navigating to and reading the template files first.
|
||||
- Dropping checkboxes or required sections from the template (e.g., `Plugin Checklist` in PRs).
|
||||
- Forgetting the prefix dictated by the issue template's frontmatter (like `[PLUGIN] `).
|
||||
- Assigning random labels not defined in the template frontmatter.
|
||||
|
||||
**All of these mean: Stop execution, use `view_file` on the respective template, and start over.**
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
name: data-engine-cli
|
||||
description: Instructions for using the wwv-data-engine CLI wrapper
|
||||
---
|
||||
|
||||
# Workflow: Data Engine CLI (`/data-engine-cli`)
|
||||
|
||||
The user has invoked the `/data-engine-cli` command to interact directly with the Fastify API or seeders.
|
||||
|
||||
## Action Protocol
|
||||
1. **Analyze Requirements:** Understand if the user wants to start the engine, ping its health, or debug a backend error.
|
||||
2. **Execute Wrapper:**
|
||||
- A wrapper script is present in the root folder at `scripts/data-engine.mjs`.
|
||||
- Run `node scripts/data-engine.mjs health` to fetch the status of the `/health` endpoint if running.
|
||||
- Run `node scripts/data-engine.mjs dev` to isolate the `wwv-data-engine` start logs inside your terminal.
|
||||
|
||||
## Restrictions
|
||||
> [!CAUTION]
|
||||
> - Do not guess endpoints. Always verify with `/health` or check the `routes` directory inside `packages/wwv-data-engine/src`.
|
||||
@@ -1,93 +0,0 @@
|
||||
---
|
||||
name: debugging-coolify
|
||||
description: Use when you need to troubleshoot deployed applications, services, databases, or deployment failures on a Coolify server using MCP tools, SSH into the instances, and mapping resource UUIDs to Docker host states.
|
||||
---
|
||||
|
||||
# Debugging Coolify
|
||||
|
||||
## Overview
|
||||
This workflow provides the exact methodology to cross-reference Coolify MCP data with raw Docker state on the host to effectively debug infrastructure and application issues. It outlines the host mapping ontology for the local Coolify server (e.g., accessible via `ssh [email protected]`) and how to bridge Coolify UUIDs to physical folders and volumes.
|
||||
|
||||
## When to Use
|
||||
- Applications failing to deploy or start on Coolify
|
||||
- Checking database or service logs
|
||||
- Verifying environment variables on running containers
|
||||
- Investigating 502 Bad Gateway errors from Coolify proxy
|
||||
- Finding where files and configuration are stored on the Docker host
|
||||
- "I need to check the database volume for..."
|
||||
- "SSH into the server and find the configuration for..."
|
||||
- "I can't find the source code on Coolify..."
|
||||
- "Check the local laptop server logs"
|
||||
|
||||
## Core Pattern: Correlate UUID to Raw State
|
||||
|
||||
Coolify abstracts Docker. When things break, you must correlate Coolify's UUIDs to the underlying Docker containers and volumes.
|
||||
|
||||
1. **Find the UUID** using Coolify MCP (`mcp_coolify_list_applications`, `mcp_coolify_list_services`, `mcp_coolify_list_databases`).
|
||||
2. **Diagnose via MCP** using `mcp_coolify_diagnose_app` or `mcp_coolify_application_logs(uuid, lines=200)`.
|
||||
3. **Map to Host Config** using the SSH host mapping pipeline. Container names and network configs are prefixed with the UUID.
|
||||
4. **Drop to Raw Docker** when MCP logs aren't enough (e.g., `docker inspect`, `docker exec`, proxy logs) over SSH.
|
||||
|
||||
## Host Mapping Reference
|
||||
|
||||
Here is the exact topology of the local Coolify server hosted on the laptop:
|
||||
|
||||
| Resource | Physical Path on Host (`192.168.68.69`) |
|
||||
|----------|-----------------------------------------|
|
||||
| **Base Coolify Data** | `/data/coolify` |
|
||||
| **Application Configs** | `/data/coolify/applications/<uuid>/` |
|
||||
| **Service Configs** | `/data/coolify/services/<uuid>/` |
|
||||
| **Proxy Details** | `/data/coolify/proxy/` |
|
||||
| **Docker Volumes** | `/var/lib/docker/volumes/<uuid>_<volume_name>/_data` |
|
||||
|
||||
## Discovery Pipeline
|
||||
|
||||
When requested to debug something on the Coolify server, follow this pipeline to accurately target the data without guessing:
|
||||
|
||||
1. **Get the UUID**: Use the `mcp_coolify_list_applications` or `mcp_coolify_list_services` tools to find the UUID of the target resource.
|
||||
- Example Application (`worldwideview-demo`): `nmn55t4io3myfubs72worn7k`
|
||||
- Example Service (`umami`): `s6iqy8m4mlf3x6e5u4agxsp0`
|
||||
2. **Access the Docker Compose File**: The raw compose configurations Coolify dynamically generates live at `/data/coolify/(applications|services)/<uuid>/docker-compose.yml`.
|
||||
- Command: `ssh [email protected] "cat /data/coolify/applications/<uuid>/docker-compose.yml"`
|
||||
3. **Inspect Volumes**: Coolify uses standard Docker local volumes mapping, prefixing the volume names with the UUID. Retrieve them directly through Docker or by accessing the mapped directory.
|
||||
- Command: `ssh [email protected] "docker volume ls | grep <uuid>"`
|
||||
- Example Volume Mount: `/var/lib/docker/volumes/nmn55t4io3myfubs72worn7k_engine-data/_data`
|
||||
|
||||
## Quick Reference For Issues
|
||||
|
||||
| Issue | First Action | Deep Dive |
|
||||
|-------|--------------|-----------|
|
||||
| App won't start | `mcp_coolify_application_logs(uuid)` | SSH into host, check `/data/coolify/applications/<uuid>/docker-compose.yml` |
|
||||
| Database connection error | `mcp_coolify_get_database(uuid)` | Query `docker ps \| grep <uuid>` then `docker logs <container>` |
|
||||
| Proxy routing 502 | `mcp_coolify_diagnose_app(uuid)` | SSH into host, check Traefik proxy logs: `ssh [email protected] "docker logs coolify-proxy"` |
|
||||
| Missing/corrupt data | Recall Host Mapping | SSH and inspect volumes: `/var/lib/docker/volumes/<uuid>_<name>/_data` |
|
||||
| Deployment failed | `mcp_coolify_list_deployments` | Find deployment UUID, use `mcp_coolify_deployment(action: get, uuid: <uuid>, lines: 200)` to get raw build logs |
|
||||
|
||||
## Common Mistakes & Red Flags
|
||||
|
||||
### Trying to find files in `/var/www` or `/home`
|
||||
- **What goes wrong:** Coolify does not use traditional host-bound document roots. Everything is containerized.
|
||||
- **Fix:** Access `/data/coolify` or directly jump into the container via `docker exec`.
|
||||
|
||||
### SSHing with a password
|
||||
- **What goes wrong:** The connection might hang or prompt interactively.
|
||||
- **Fix:** Your host agent is already keyed for `[email protected]`. Ensure you use non-interactive commands: `ssh [email protected] "your command here"`.
|
||||
|
||||
### Guessing Container Names
|
||||
- **What goes wrong:** Coolify generates container names dynamically based on internal routing (e.g., `wwv-data-engine-nmn55t4io3myfubs72worn7k-114309953928`).
|
||||
- **Fix:** Always query `docker ps --format '{{.Names}}'` and `grep` the UUID obtained from the Coolify MCP to accurately identify the target container.
|
||||
|
||||
### Editing Files on Host Direct
|
||||
- **What goes wrong:** Coolify will overwrite generated files.
|
||||
- **Fix:** Update via MCP settings/environment variables or repo commits to trigger redeploy. Never modify raw `docker-compose.yml` under `/data/coolify/`.
|
||||
|
||||
### Re-running Deployment Repeatedly
|
||||
- **What goes wrong:** The deployment failed, but standard logs are empty, and restarting repeats the error. standard runtime logs are distinct.
|
||||
- **Fix:** Use deployment MCP tools to check the build log.
|
||||
|
||||
**Red Flags - STOP and Start Over:**
|
||||
- Guessing container paths or volume names.
|
||||
- Using standard `systemctl` commands to check application status instead of docker.
|
||||
- Modifying docker-compose rather than relying on standard git updates.
|
||||
|
||||
**All of these mean: Stop. Get the UUID via Coolify MCP. Inspect via Docker using that UUID, or use deployment-specific logs.**
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
name: developing-plugins
|
||||
description: Use when modifying existing plugins, creating new plugins, or troubleshooting why plugin UI/fetch changes are not showing up in the local development environment
|
||||
---
|
||||
|
||||
# Developing Plugins
|
||||
|
||||
## Overview
|
||||
This skill defines the modern `wwv-cli` based workflow for developing plugins in WorldWideView. It completely replaces the legacy methods of manual database syncing, manually patching SQLite, and editing `next.config.ts`. The modern workflow uses hot-reloading Vite bundlers and automated database linking via the `dev-link` API.
|
||||
|
||||
## When to Use
|
||||
- You are writing or modifying code inside `packages/wwv-plugin-*`
|
||||
- You need to test your plugin changes on the main `localhost:3000` engine
|
||||
- You are debugging why a plugin UI component (Sidebar, Overlay, fetch logic) is not updating after you changed the code
|
||||
|
||||
## Core Pattern: The Sync Workflow
|
||||
|
||||
**DO NOT edit Next.js configurations or manually patch SQLite for local plugin dev.**
|
||||
|
||||
Instead, use the `link` workflow.
|
||||
|
||||
1. **Start the Main Engine:**
|
||||
In your engine directory (e.g., `c:\dev\worldwideview`):
|
||||
```bash
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
2. **Start the Plugin Watcher:**
|
||||
In your plugins directory (e.g., `c:\dev\worldwideview-plugins`):
|
||||
```bash
|
||||
pnpm run sync:all
|
||||
```
|
||||
*Alternatively, if working inside a single plugin package, run:*
|
||||
```bash
|
||||
node ../wwv-cli/dist/index.mjs link
|
||||
```
|
||||
|
||||
3. **How it Works:**
|
||||
The `link` command automates two critical steps:
|
||||
- Starts a Vite bundler in watch mode that recompiles your plugin instantly on every save.
|
||||
- Pings `/api/plugins/dev-link` on the main engine to inject the local manifest into the engine's SQLite database. This points the engine directly to your local watch bundle.
|
||||
|
||||
4. **Verify:**
|
||||
Because plugins are dynamically imported external bundles, Next.js Fast Refresh does not apply to them. **You MUST manually refresh your browser** at `localhost:3000` to see changes after Vite recompiles.
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
| Excuse / Mistake | Reality |
|
||||
|------------------|---------|
|
||||
| "I ran `pnpm build` in the plugin" | The engine won't know about the new bundle unless the database is linked. Use the `link` command or `sync:all`. |
|
||||
| "I'll manually update the SQLite DB to point to my local file" | The `dev-link` API handles upserting automatically during the link process. |
|
||||
| "I'm waiting for Next.js to hot-reload my plugin" | External ES modules do not trigger Next.js HMR. You must refresh the browser page manually. |
|
||||
| "I'll just add my plugin to `transpilePackages`" | This is the legacy declarative workflow. Modern plugins are independent dynamic bundles. |
|
||||
|
||||
## Red Flags - STOP and Start Over
|
||||
- Modifying `next.config.ts` to add a plugin.
|
||||
- Opening the SQLite database to manually change a plugin URL.
|
||||
- Writing a script to copy files over without using `wwv-cli link`.
|
||||
|
||||
**All of these mean: Revert your manual changes. Start over with `wwv-cli link`.**
|
||||
@@ -1,190 +0,0 @@
|
||||
---
|
||||
name: dispatching-parallel-agents
|
||||
description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
|
||||
---
|
||||
|
||||
# Dispatching Parallel Agents
|
||||
|
||||
## Overview
|
||||
|
||||
You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
|
||||
|
||||
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
|
||||
|
||||
**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
|
||||
|
||||
## When to Use
|
||||
|
||||
```dot
|
||||
digraph when_to_use {
|
||||
"Multiple failures?" [shape=diamond];
|
||||
"Are they independent?" [shape=diamond];
|
||||
"Single agent investigates all" [shape=box];
|
||||
"One agent per problem domain" [shape=box];
|
||||
"Can they work in parallel?" [shape=diamond];
|
||||
"Sequential agents" [shape=box];
|
||||
"Parallel dispatch" [shape=box];
|
||||
|
||||
"Multiple failures?" -> "Are they independent?" [label="yes"];
|
||||
"Are they independent?" -> "Single agent investigates all" [label="no - related"];
|
||||
"Are they independent?" -> "Can they work in parallel?" [label="yes"];
|
||||
"Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
|
||||
"Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
|
||||
}
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- 3+ test files failing with different root causes
|
||||
- Multiple subsystems broken independently
|
||||
- Each problem can be understood without context from others
|
||||
- No shared state between investigations
|
||||
|
||||
**Don't use when:**
|
||||
- Failures are related (fix one might fix others)
|
||||
- Need to understand full system state
|
||||
- Agents would interfere with each other
|
||||
|
||||
## The Pattern
|
||||
|
||||
### 1. Identify Independent Domains
|
||||
|
||||
Group failures by what's broken:
|
||||
- File A tests: Tool approval flow
|
||||
- File B tests: Batch completion behavior
|
||||
- File C tests: Abort functionality
|
||||
|
||||
Each domain is independent - fixing tool approval doesn't affect abort tests.
|
||||
|
||||
### 2. Create Focused Agent Tasks
|
||||
|
||||
Each agent gets:
|
||||
- **Specific scope:** One test file or subsystem
|
||||
- **Clear goal:** Make these tests pass
|
||||
- **Constraints:** Don't change other code
|
||||
- **Expected output:** Summary of what you found and fixed
|
||||
|
||||
### 3. Dispatch in Parallel
|
||||
|
||||
```typescript
|
||||
// In Antigravity / Gemini CLI environment
|
||||
Task("Fix agent-tool-abort.test.ts failures")
|
||||
Task("Fix batch-completion-behavior.test.ts failures")
|
||||
Task("Fix tool-approval-race-conditions.test.ts failures")
|
||||
// Dispatch them in parallel using run_command with background capabilities
|
||||
```
|
||||
|
||||
### 4. Review and Integrate
|
||||
|
||||
When agents return:
|
||||
- Read each summary
|
||||
- Verify fixes don't conflict
|
||||
- Run full test suite
|
||||
- Integrate all changes
|
||||
|
||||
## Agent Prompt Structure
|
||||
|
||||
Good agent prompts are:
|
||||
1. **Focused** - One clear problem domain
|
||||
2. **Self-contained** - All context needed to understand the problem
|
||||
3. **Specific about output** - What should the agent return?
|
||||
|
||||
```markdown
|
||||
Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
|
||||
|
||||
1. "should abort tool with partial output capture" - expects 'interrupted at' in message
|
||||
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
|
||||
3. "should properly track pendingToolCount" - expects 3 results but gets 0
|
||||
|
||||
These are timing/race condition issues. Your task:
|
||||
|
||||
1. Read the test file and understand what each test verifies
|
||||
2. Identify root cause - timing issues or actual bugs?
|
||||
3. Fix by:
|
||||
- Replacing arbitrary timeouts with event-based waiting
|
||||
- Fixing bugs in abort implementation if found
|
||||
- Adjusting test expectations if testing changed behavior
|
||||
|
||||
Do NOT just increase timeouts - find the real issue.
|
||||
|
||||
Return: Summary of what you found and what you fixed.
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
**❌ Too broad:** "Fix all the tests" - agent gets lost
|
||||
**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
|
||||
|
||||
**❌ No context:** "Fix the race condition" - agent doesn't know where
|
||||
**✅ Context:** Paste the error messages and test names
|
||||
|
||||
**❌ No constraints:** Agent might refactor everything
|
||||
**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
|
||||
|
||||
**❌ Vague output:** "Fix it" - you don't know what changed
|
||||
**✅ Specific:** "Return summary of root cause and changes"
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
**Related failures:** Fixing one might fix others - investigate together first
|
||||
**Need full context:** Understanding requires seeing entire system
|
||||
**Exploratory debugging:** You don't know what's broken yet
|
||||
**Shared state:** Agents would interfere (editing same files, using same resources)
|
||||
|
||||
## Real Example from Session
|
||||
|
||||
**Scenario:** 6 test failures across 3 files after major refactoring
|
||||
|
||||
**Failures:**
|
||||
- agent-tool-abort.test.ts: 3 failures (timing issues)
|
||||
- batch-completion-behavior.test.ts: 2 failures (tools not executing)
|
||||
- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
|
||||
|
||||
**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
|
||||
|
||||
**Dispatch:**
|
||||
```
|
||||
Agent 1 → Fix agent-tool-abort.test.ts
|
||||
Agent 2 → Fix batch-completion-behavior.test.ts
|
||||
Agent 3 → Fix tool-approval-race-conditions.test.ts
|
||||
```
|
||||
|
||||
**Results:**
|
||||
- Agent 1: Replaced timeouts with event-based waiting
|
||||
- Agent 2: Fixed event structure bug (threadId in wrong place)
|
||||
- Agent 3: Added wait for async tool execution to complete
|
||||
|
||||
**Integration:** All fixes independent, no conflicts, full suite green
|
||||
|
||||
**Time saved:** 3 problems solved in parallel vs sequentially
|
||||
|
||||
## Key Benefits
|
||||
|
||||
1. **Parallelization** - Multiple investigations happen simultaneously
|
||||
2. **Focus** - Each agent has narrow scope, less context to track
|
||||
3. **Independence** - Agents don't interfere with each other
|
||||
4. **Speed** - 3 problems solved in time of 1
|
||||
|
||||
## Verification
|
||||
|
||||
After agents return:
|
||||
1. **Review each summary** - Understand what changed
|
||||
2. **Check for conflicts** - Did agents edit same code?
|
||||
3. **Run full suite** - Verify all fixes work together
|
||||
4. **Spot check** - Agents can make systematic errors
|
||||
|
||||
## Real-World Impact
|
||||
|
||||
From debugging session (2025-10-03):
|
||||
- 6 failures across 3 files
|
||||
- 3 agents dispatched in parallel
|
||||
- All investigations completed concurrently
|
||||
- All fixes integrated successfully
|
||||
- Zero conflicts between agent changes
|
||||
|
||||
## Antigravity CLI Orchestration
|
||||
|
||||
As Antigravity, you can orchestrate this fully autonomously using the `run_command` tool to spawn `gemini` CLI subagents in the background.
|
||||
|
||||
1. **Dispatch:** Use `run_command` with a high enough `WaitMsBeforeAsync` so the processes run in the background (e.g., `gemini -p task1.md`, `gemini -p task2.md`).
|
||||
2. **Monitor:** Periodically check their progress via the `command_status` tool.
|
||||
3. **Merge:** When all background commands complete, review their outputs and integrate their fixes.
|
||||
@@ -1,102 +0,0 @@
|
||||
---
|
||||
name: execute
|
||||
description: Execute an implementation plan
|
||||
argument-hint: [path-to-plan]
|
||||
---
|
||||
|
||||
# Execute: Implement from Plan
|
||||
|
||||
## Plan to Execute
|
||||
|
||||
Read plan file: `$ARGUMENTS`
|
||||
|
||||
## Execution Instructions
|
||||
|
||||
### 1. Read and Understand
|
||||
|
||||
- Read the ENTIRE plan carefully
|
||||
- Understand all tasks and their dependencies
|
||||
- Note the validation commands to run
|
||||
- Review the testing strategy
|
||||
|
||||
### 2. Execute Tasks in Order
|
||||
|
||||
For EACH task in "Step by Step Tasks":
|
||||
|
||||
#### a. Navigate to the task
|
||||
- Identify the file and action required
|
||||
- Read existing related files if modifying
|
||||
|
||||
#### b. Implement the task
|
||||
- Follow the detailed specifications exactly
|
||||
- Maintain consistency with existing code patterns
|
||||
- Include proper type hints and documentation
|
||||
- Add structured logging where appropriate
|
||||
|
||||
#### c. Verify as you go
|
||||
- After each file change, check syntax
|
||||
- Ensure imports are correct
|
||||
- Verify types are properly defined
|
||||
|
||||
### 3. Implement Testing Strategy
|
||||
|
||||
After completing implementation tasks:
|
||||
|
||||
- Create all test files specified in the plan
|
||||
- Implement all test cases mentioned
|
||||
- Follow the testing approach outlined
|
||||
- Ensure tests cover edge cases
|
||||
|
||||
### 4. Run Validation Commands
|
||||
|
||||
Execute ALL validation commands from the plan in order:
|
||||
|
||||
```bash
|
||||
# Run each command exactly as specified in plan
|
||||
```
|
||||
|
||||
If any command fails:
|
||||
- Fix the issue
|
||||
- Re-run the command
|
||||
- Continue only when it passes
|
||||
|
||||
### 5. Final Verification
|
||||
|
||||
Before completing:
|
||||
|
||||
- ✅ All tasks from plan completed
|
||||
- ✅ All tests created and passing
|
||||
- ✅ All validation commands pass
|
||||
- ✅ Code follows project conventions
|
||||
- ✅ Documentation added/updated as needed
|
||||
|
||||
## Output Report
|
||||
|
||||
Provide summary:
|
||||
|
||||
### Completed Tasks
|
||||
- List of all tasks completed
|
||||
- Files created (with paths)
|
||||
- Files modified (with paths)
|
||||
|
||||
### Tests Added
|
||||
- Test files created
|
||||
- Test cases implemented
|
||||
- Test results
|
||||
|
||||
### Validation Results
|
||||
```bash
|
||||
# Output from each validation command
|
||||
```
|
||||
|
||||
### Ready for Commit
|
||||
- Confirm all changes are complete
|
||||
- Confirm all validations pass
|
||||
- Ready for `/commit` command
|
||||
|
||||
## Notes
|
||||
|
||||
- If you encounter issues not addressed in the plan, document them
|
||||
- If you need to deviate from the plan, explain why
|
||||
- If tests fail, fix implementation until they pass
|
||||
- Don't skip validation steps
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
name: five
|
||||
description: Use the "Five Whys" root cause analysis technique to deeply understand problems.
|
||||
---
|
||||
|
||||
# Five Whys Analysis
|
||||
|
||||
Use the "Five Whys" root cause analysis technique to deeply understand problems.
|
||||
|
||||
## Process:
|
||||
|
||||
### 1. Define the Problem
|
||||
Clearly state the issue or symptom
|
||||
|
||||
### 2. Ask "Why?" Five Times
|
||||
- Why did this problem occur? → Answer 1
|
||||
- Why did Answer 1 happen? → Answer 2
|
||||
- Why did Answer 2 happen? → Answer 3
|
||||
- Why did Answer 3 happen? → Answer 4
|
||||
- Why did Answer 4 happen? → Answer 5 (Root Cause)
|
||||
|
||||
### 3. Validate Root Cause
|
||||
- Verify the logical chain
|
||||
- Check if addressing root cause prevents recurrence
|
||||
- Consider multiple root causes if applicable
|
||||
|
||||
### 4. Develop Solutions
|
||||
- Address the root cause, not just symptoms
|
||||
- Create preventive measures
|
||||
- Consider systemic improvements
|
||||
|
||||
## Example:
|
||||
**Problem**: Application crashes when processing large files
|
||||
|
||||
1. **Why?** → The application runs out of memory
|
||||
2. **Why?** → It loads entire file into memory at once
|
||||
3. **Why?** → The file parser wasn't designed for streaming
|
||||
4. **Why?** → Initial requirements only specified small files
|
||||
5. **Why?** → Requirements gathering didn't consider future growth
|
||||
|
||||
**Root Cause**: Incomplete requirements gathering process
|
||||
**Solution**: Implement streaming parser and improve requirements process
|
||||
|
||||
## Best Practices:
|
||||
- Focus on process, not people
|
||||
- Look for systemic issues
|
||||
- Document the analysis
|
||||
- Involve relevant stakeholders
|
||||
- Test solutions address root cause
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
name: generate-user-roadmap
|
||||
description: Generate an updated user-facing roadmap
|
||||
---
|
||||
|
||||
# Generate User-Facing Roadmap Workflow
|
||||
|
||||
Use this workflow to translate the project's technical `ROADMAP.md` into a clear, user-facing summary of future features.
|
||||
|
||||
1. **Read the Technical Roadmap**
|
||||
- Read the contents of `ROADMAP.md` to discover new planned stages and unchecked items.
|
||||
|
||||
2. **Filter for End-Users**
|
||||
- Extract only the features that impact the daily usage of the globe for an end-user.
|
||||
- Ignore backend infrastructure, publisher workflows, and CI/CD tasks unless they directly translate to a user-facing capability.
|
||||
|
||||
3. **Format and Structure**
|
||||
- Group the extracted features into three sections, in this exact order:
|
||||
1. `### Major Features`
|
||||
2. `### Minor Features`
|
||||
3. `### Recently Implemented` (Keep this at the very bottom of the document).
|
||||
|
||||
4. **Apply Target Tone and Formatting**
|
||||
- **No Fluff:** Remove marketing buzzwords, corporate language, and overly technical descriptions.
|
||||
- **Plugin Formatting:** Format plugins as `[Short Name] Plugin`. Keep the name 2-3 words. If the name isn't clear enough, use `[Short Name] Plugin for [short description]`.
|
||||
- **Example Good:** `* Conflict Zones Plugin` or `* GPS Jamming Plugin`
|
||||
- **One-Liners:** Keep each feature strictly to a single, concise line. Do NOT use a `Title: Description` format.
|
||||
- **Tag New Items:** Prefix completely new features with a `[NEW]` tag (e.g. `* [NEW] AI Copilot`).
|
||||
- **Strikethrough Implemented:** Any features that have been completed must be moved to the `### Recently Implemented` section at the bottom and formatted with markdown strikethrough (e.g. `* ~~Conflict Zones Plugin~~`).
|
||||
|
||||
5. **Update Context**
|
||||
- After generating the new list, update `c:\dev\worldwideview\.agents\context\07-user-facing-roadmap.md` using the `/update-context` skill to ensure persistent knowledge remains accurate.
|
||||
@@ -1,179 +0,0 @@
|
||||
---
|
||||
name: github-workflow
|
||||
description: Use when the user invokes /github-workflow to manage GitHub — issue creation, branching, committing, pushing, and PR opening. Accepts flags to modify behavior. Do NOT invoke automatically; this skill is always user-initiated.
|
||||
---
|
||||
|
||||
# GitHub Workflow
|
||||
|
||||
## Overview
|
||||
Single entry point for all GitHub work. Detects current branch state, accepts flags to control behavior, and proposes a PR when work is done.
|
||||
|
||||
**Default behavior (no flags):** issue → branch → code → push → PR
|
||||
|
||||
---
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Effect |
|
||||
|---|---|
|
||||
| `--worktree` | Creates an isolated worktree checkout instead of a plain branch (in `.worktrees/` or an AI agent directory) |
|
||||
| `--no-pr` | Stops after push, skips PR creation |
|
||||
| `--pr` | Jumps straight to PR phase. **Note:** If invoked with uncommitted changes on `main`, automatically run Phases 1-6 retroactively (create branch, commit, push) before opening the PR. |
|
||||
| `--no-issue` | Skips issue creation (for tiny untracked changes) |
|
||||
| `--continue` | Skips branch detection, resumes the current branch as-is |
|
||||
| `--merge-cleanup` | Completes the lifecycle: merges the PR, prunes worktree, and deletes local branch |
|
||||
| `--direct-main` | **(Shortcut)** Bypasses branching and PR entirely. Commits and pushes straight to `main`. Allowed **ONLY** for low-risk `chore`, `docs`, and strictly typed `fix` changes that do not alter core logic. |
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Branch Detection (always runs first, unless `--continue`)
|
||||
|
||||
```bash
|
||||
git branch --show-current
|
||||
```
|
||||
|
||||
**If on `main`:** proceed to Phase 1.
|
||||
|
||||
**If on a branch matching `(feature|bug|chore)/(\d+)-.*`:**
|
||||
|
||||
1. Extract the issue number `N` from the branch name
|
||||
2. Fetch issue context:
|
||||
```bash
|
||||
gh issue view {N} --json title,state,labels
|
||||
```
|
||||
3. Compare the issue title/labels to the user's current request:
|
||||
- **Clearly related** (same feature/bug, issue still open) → offer to continue:
|
||||
> "You're already on `{branch}` tracking issue #{N}: '{title}'. Continue working here?"
|
||||
> Options: **[Y] Continue on this branch** | **[W] Open a new worktree instead** | **[N] Start fresh on main**
|
||||
- **Clearly unrelated** (different feature, issue closed, or wrong type) → warn:
|
||||
> "⚠️ You're on `{branch}` (issue #{N}: '{title}'), which appears unrelated to this task. Recommend switching to main first."
|
||||
> Options: **[S] Switch to main and start fresh** | **[W] Keep this branch, create a worktree for new work** | **[I] Ignore and continue here**
|
||||
- **Ambiguous** → ask the user to clarify before proceeding
|
||||
|
||||
**If on an unrecognized branch (no issue number):**
|
||||
> "You're on branch `{branch}` which doesn't follow the naming convention. Is this intentional?"
|
||||
> Options: **[C] Continue here** | **[M] Switch to main first**
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Create Issue (skip with `--no-issue`)
|
||||
|
||||
**REQUIRED SUB-SKILL:** You MUST use the `/creating-github-issues` skill. Read the appropriate template from `.github/ISSUE_TEMPLATE/` (if it exists), parse its frontmatter for title formats and labels, and write a temporary Markdown file to use as the issue body.
|
||||
|
||||
Example command structure:
|
||||
```bash
|
||||
gh issue create --title "[PREFIX] {title}" --label "{labels}" --body-file /path/to/generated/temp_body.md
|
||||
# ALWAYS delete temp_body.md after successful creation
|
||||
```
|
||||
|
||||
Save the returned number: `ISSUE=<number>`
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Create Branch or Worktree
|
||||
|
||||
**Without `--worktree`:**
|
||||
```bash
|
||||
git checkout main && git pull origin main
|
||||
git checkout -b {type}/${ISSUE}-{kebab-desc}
|
||||
# type = feature | bug | chore
|
||||
```
|
||||
|
||||
**With `--worktree`:** invoke `/worktree-dev` skill, passing branch name `{type}/${ISSUE}-{kebab-desc}`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Implement
|
||||
|
||||
(User codes. Agent assists. Normal development loop.)
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Validate
|
||||
|
||||
```bash
|
||||
pnpm build # must pass
|
||||
pnpm test # must pass
|
||||
```
|
||||
|
||||
Both must pass before committing. Fix any failures before proceeding.
|
||||
*(Note: For strictly Markdown/documentation changes, you may skip the build/test cycle to save time.)*
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Commit
|
||||
|
||||
Invoke `/commit` skill — bumps semver, enforces conventional commit format.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Push
|
||||
|
||||
```bash
|
||||
git push -u origin {branch-name}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: PR or Stop
|
||||
|
||||
### Auto-detection of readiness
|
||||
After Phase 6, check:
|
||||
```bash
|
||||
git status # working tree clean?
|
||||
pnpm build # still passes?
|
||||
pnpm test # still passes?
|
||||
```
|
||||
|
||||
If all three are clean and no open TODOs appear in recently changed files, propose:
|
||||
> "Build and tests pass, working tree is clean. Ready to open a PR?"
|
||||
|
||||
### `--no-pr` flag
|
||||
If `--no-pr` was passed, **stop here** after push. Do not propose a PR.
|
||||
|
||||
### Opening the PR (default or `--pr`)
|
||||
**REQUIRED SUB-SKILL:** You MUST use the `/creating-github-issues` skill. Read `.github/PULL_REQUEST_TEMPLATE.md` (if it exists) and ensure the PR body contains the exact checklists and sections required by the project. Write this to a temporary markdown file.
|
||||
|
||||
Example command structure:
|
||||
```bash
|
||||
gh pr create --title "{type}: {description}" --body-file /path/to/generated/temp_pr_body.md
|
||||
# ALWAYS delete temp_pr_body.md after successful creation
|
||||
```
|
||||
|
||||
### Auto-merge decision
|
||||
- **Low-risk** (chore, docs, config — no logic changes):
|
||||
```bash
|
||||
gh pr merge --auto --squash
|
||||
```
|
||||
- **Feature or bug PRs:** invoke `/pr-review` and wait for human approval.
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Merge and Cleanup (with `--merge-cleanup`)
|
||||
|
||||
When explicitly invoked with `--merge-cleanup` after a PR is approved and CI is green:
|
||||
|
||||
1. Merge PR on GitHub: `gh pr merge {PR_NUMBER} --squash --delete-branch`
|
||||
2. If using a worktree, ensure no background processes (like `pnpm test-worktree`) are locking files, then remove it:
|
||||
```bash
|
||||
# Note: The worktree could be in .worktrees/ or an AI agent directory (.gemini/antigravity/worktrees)
|
||||
# Use `git worktree list` to find the correct absolute path before removing it.
|
||||
git worktree remove <actual-path-to-worktree> --force
|
||||
git worktree prune
|
||||
```
|
||||
3. Delete local branch: `git branch -D {branch-name}`
|
||||
4. Sync main: `git checkout main && git pull origin main`
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```
|
||||
/github-workflow # standard: issue → branch → code → PR
|
||||
/github-workflow --worktree # same, isolated in a worktree
|
||||
/github-workflow --no-pr # stop after push, no PR
|
||||
/github-workflow --pr # work done, just open the PR now
|
||||
/github-workflow --no-issue # skip issue creation
|
||||
/github-workflow --continue # skip branch detection, resume current branch
|
||||
/github-workflow --merge-cleanup # merges PR, cleans up branch and worktree
|
||||
```
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
name: init-project
|
||||
description: Use when initializing a new project locally — runs setup commands to configure environment, install dependencies, start databases, and validate the dev server is working.
|
||||
---
|
||||
|
||||
# Initialize Project
|
||||
|
||||
Run the following commands to set up and start the project locally:
|
||||
|
||||
## 1. Create Environment File
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
Creates your local environment configuration from the example template.
|
||||
|
||||
## 2. Install Dependencies
|
||||
```bash
|
||||
uv sync
|
||||
```
|
||||
Installs all Python packages defined in pyproject.toml.
|
||||
|
||||
## 3. Start Database
|
||||
```bash
|
||||
docker-compose up -d db
|
||||
```
|
||||
Starts PostgreSQL 18 in a Docker container on port 5433.
|
||||
|
||||
## 4. Run Database Migrations
|
||||
```bash
|
||||
uv run alembic upgrade head
|
||||
```
|
||||
Applies all pending database migrations.
|
||||
|
||||
## 5. Start Development Server
|
||||
```bash
|
||||
uv run uvicorn app.main:app --reload --port 8123
|
||||
```
|
||||
Starts the FastAPI server with hot-reload on port 8123.
|
||||
|
||||
## 6. Validate Setup
|
||||
|
||||
Check that everything is working:
|
||||
|
||||
```bash
|
||||
# Test API health
|
||||
curl -s http://localhost:8123/health
|
||||
|
||||
# Test database connection
|
||||
curl -s http://localhost:8123/health/db
|
||||
```
|
||||
|
||||
Both should return `{"status":"healthy"}` responses.
|
||||
|
||||
## Access Points
|
||||
|
||||
- Swagger UI: http://localhost:8123/docs
|
||||
- Health Check: http://localhost:8123/health
|
||||
- Database: localhost:5433
|
||||
|
||||
## Cleanup
|
||||
|
||||
To stop services:
|
||||
```bash
|
||||
# Stop dev server: Ctrl+C
|
||||
# Stop database: docker-compose down
|
||||
```
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
name: local-dev
|
||||
description: Instructions for checking, starting, and troubleshooting local dev
|
||||
---
|
||||
|
||||
# Workflow: Local Development (`/local-dev`)
|
||||
|
||||
The user has invoked the `/local-dev` command to start the unified local development environment or troubleshoot backend issues.
|
||||
|
||||
## 1. Action Protocol
|
||||
1. **Analyze Requirements:** Understand if the user wants to start everything (Frontend and all Backends) or just debug specific issues.
|
||||
2. **Setup DB:** If they just cloned or encountered schema mismatch, run `pnpm run db:reset`.
|
||||
3. **Start Servers:**
|
||||
- You can start everything using `pnpm run dev:all`.
|
||||
- Note: The VS Code `tasks.json` has this set up if the user prefers attaching a graphical debugger! Let them know.
|
||||
|
||||
## 2. Troubleshooting Backend Connectivity
|
||||
- If the data engine is not responding, check running process status using `node scripts/data-engine.mjs health`
|
||||
- You may also verify if Prisma or SQLite files are locked by stopping the server and clearing `.next` (`pnpm run clean`).
|
||||
|
||||
## 3. General Debugging Tips
|
||||
- Next.js Client errors are best handled using the VSCode Chrome Debugger.
|
||||
- Fastify backend (Data Engine) errors can be caught via VS Code `WWV Data Engine: debug` launch config.
|
||||
@@ -0,0 +1,257 @@
|
||||
---
|
||||
name: migrate-legacy-plugin
|
||||
description: Use when moving a WorldWideView plugin from packages/ (or ../worldwideview-plugins/packages/) to local-plugins/, converting legacy plugins to the new Engine & Payload architecture, or when a plugin hardcodes engine URLs, bundles Node.js built-ins, or uses import.meta.url for file paths inside Docker containers
|
||||
---
|
||||
|
||||
# Migrate Legacy Plugin to Modern Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
Moves a WorldWideView plugin from the old `packages/` monorepo location (or the external `worldwideview-plugins` repository) into the `local-plugins/` directory (which is itself a publishable Git repository). Simultaneously fixes two **independent** concerns that legacy plugins always have:
|
||||
|
||||
1. **Frontend routing** — hardcoded engine URLs must be replaced with `resolveEngineUrl()`
|
||||
2. **Backend seeder build** — ESM bundling and container-aware file paths
|
||||
|
||||
**Core principle:** These are two separate problems in two separate codebases. Never fix one and forget the other.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Moving a plugin from `packages/wwv-plugin-<name>/` (or `../worldwideview-plugins/packages/wwv-plugin-<name>/`) to `local-plugins/wwv-plugin-<name>/`
|
||||
- Plugin's `fetch()` hardcodes a URL like `https://dataengine.worldwideview.dev`
|
||||
- Plugin uses `this.context?.apiBaseUrl` instead of `resolveEngineUrl()`
|
||||
- Backend seeder crashes with `Dynamic require` or `ERR_INVALID_FILE_URL_PATH` in Docker
|
||||
- Seeder uses `fileURLToPath(import.meta.url)` for locating seed data files
|
||||
- Plugin builds with `tsc` instead of `tsup`/`vite`
|
||||
|
||||
**Do NOT use for:**
|
||||
- Creating a brand-new plugin from scratch → use `worldwideview-plugin-creation` skill
|
||||
- Modifying rendering or Cesium primitives → see `cesium-rendering` rule
|
||||
- Debugging state management → see `state-management` rule
|
||||
|
||||
## The Two Independent Concerns
|
||||
|
||||
> [!TIP]
|
||||
> **Automated Migration Script**
|
||||
> A new automation script is available! Before doing this manually, simply run:
|
||||
> ```bash
|
||||
> node scripts/migrate-plugin.mjs <plugin-name>
|
||||
> ```
|
||||
> Example: `node scripts/migrate-plugin.mjs gps-jamming`
|
||||
>
|
||||
> The script will automatically copy the frontend plugin, inject peerDependencies, refactor `index.tsx` routing, fix the backend seeder's build settings and `SEEDERS_DIR` paths, and register the plugin in `defaultPlugins.ts`.
|
||||
> **You still need to run `pnpm install` and verify the builds manually as described below.**
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Legacy plugins always have BOTH of these problems. They are independent — you can fix one without the other, but you MUST fix both. Do not get tunnel-visioned into only fixing one.
|
||||
|
||||
| Concern | Where | Symptom | Fix |
|
||||
|---|---|---|---|
|
||||
| **Frontend routing** | `local-plugins/wwv-plugin-<name>/src/index.ts` | Plugin always hits cloud engine, ignores local dev engine | Use `context.getEngineUrl()` |
|
||||
| **Backend build** | `local-seeders/<namespace>/packages/<name>/` | Container crashes on startup with ESM errors | `tsup --format esm --target es2022`, use `SEEDERS_DIR` |
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Move the Plugin Directory
|
||||
|
||||
Copy the plugin from `packages/` (or the external plugins repo) to `local-plugins/`:
|
||||
|
||||
```bash
|
||||
# From project root (if in local packages/)
|
||||
cp -r packages/wwv-plugin-<name> local-plugins/wwv-plugin-<name>
|
||||
|
||||
# OR from external plugins repository:
|
||||
cp -r ../worldwideview-plugins/packages/wwv-plugin-<name> local-plugins/wwv-plugin-<name>
|
||||
```
|
||||
|
||||
The `local-plugins/` directory is:
|
||||
- Part of the pnpm workspace (`pnpm-workspace.yaml` includes `local-plugins/*`)
|
||||
- Gitignored from the main worldwideview repo (it IS its own Git repo — `worldwideview-plugins`)
|
||||
- Auto-discovered by the `dev:plugins` watcher during `pnpm dev`
|
||||
|
||||
## Step 2: Fix Frontend Routing (getEngineUrl)
|
||||
|
||||
This is the fix that gets missed most often. Legacy plugins typically hardcode their engine URL or use messy dynamic imports.
|
||||
|
||||
```typescript
|
||||
// ❌ LEGACY — always hits cloud, ignores local engine
|
||||
const baseUrl = this.context?.apiBaseUrl || "https://dataengine.worldwideview.dev";
|
||||
const res = await fetch(`${baseUrl}/api/myplugin`);
|
||||
|
||||
// ❌ BAD (Previous Workaround) — creates bundling chunks and causes 404s
|
||||
const { resolveEngineUrl } = await import("@/core/data/resolveEngineUrl");
|
||||
const wsUrl = resolveEngineUrl(this.id);
|
||||
const engineBase = wsUrl.replace(/^ws/, 'http').replace(/\/stream$/, '');
|
||||
const res = await fetch(`${engineBase}/api/myplugin`);
|
||||
```
|
||||
|
||||
The correct approach uses `this.context.getEngineUrl()` provided by the Host when the plugin is initialized. The Host automatically handles checking `localhost:5000/manifest`, applying `getServerConfig().streamUrl`, reading `plugin.json`, or falling back to the cloud.
|
||||
|
||||
```typescript
|
||||
// ✅ MODERN — resolves local-first, respects split-routing, clean code
|
||||
async fetch(_timeRange: TimeRange): Promise<GeoEntity[]> {
|
||||
try {
|
||||
const engineBase = this.context!.getEngineUrl();
|
||||
const res = await globalThis.fetch(`${engineBase}/api/${this.id}`);
|
||||
if (!res.ok) throw new Error(`Backend returned ${res.status}`);
|
||||
|
||||
const data = await res.json();
|
||||
return this.mapPayloadToEntities(data);
|
||||
} catch (err) {
|
||||
console.error(`[${this.id}] Fetch error:`, err);
|
||||
return [];
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If the plugin is WebSocket-only (`getPollingInterval()` returns 0 and `fetch()` returns `[]`), the frontend routing is handled automatically by `DataBusSubscriber` and `WsClient`. No changes needed to the plugin class — but verify the seeder ID matches.
|
||||
|
||||
### Why This Matters
|
||||
|
||||
Without this fix, running `pnpm dev:all` starts a local engine at `localhost:5000` with your seeder, but the frontend plugin ignores it and hits the cloud. You'll see stale or missing data and waste time debugging the wrong layer.
|
||||
|
||||
## Step 3: Update package.json
|
||||
|
||||
Ensure the plugin's `package.json` follows the modern format:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@worldwideview/wwv-plugin-<name>",
|
||||
"version": "1.0.0",
|
||||
"main": "dist/frontend.mjs",
|
||||
"types": "src/index.ts",
|
||||
"type": "module",
|
||||
"module": "dist/frontend.mjs",
|
||||
"files": ["src"],
|
||||
"worldwideview": {
|
||||
"id": "<name>",
|
||||
"icon": "IconName",
|
||||
"category": "category-name",
|
||||
"format": "bundle",
|
||||
"capabilities": ["layer"]
|
||||
},
|
||||
"peerDependencies": {
|
||||
"@worldwideview/wwv-plugin-sdk": "^1.4.10"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Key differences from legacy:
|
||||
- `"main"` points to `dist/frontend.mjs` (not `src/index.ts`)
|
||||
- Has `"type": "module"` and `"module"` field
|
||||
- Uses `peerDependencies` (not `dependencies`) for SDK
|
||||
- Uses `"workspace:*"` only for libraries that must be linked locally (e.g., `wwv-lib-incidents`)
|
||||
|
||||
## Step 4: Ensure Vite Build Config
|
||||
|
||||
Every `local-plugins/` plugin needs this `vite.config.ts`:
|
||||
|
||||
```typescript
|
||||
import { defineConfig } from "vite";
|
||||
import { wwvPluginGlobals } from "@worldwideview/wwv-plugin-sdk";
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [wwvPluginGlobals()],
|
||||
build: {
|
||||
lib: {
|
||||
entry: "src/index.ts",
|
||||
formats: ["es"],
|
||||
fileName: () => "frontend.mjs",
|
||||
},
|
||||
minify: true,
|
||||
sourcemap: false,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
`wwvPluginGlobals()` externalizes React, Cesium, Resium, zustand, and the SDK so the plugin doesn't bundle its own copies.
|
||||
|
||||
## Step 5: Fix Backend Seeder (if applicable)
|
||||
|
||||
If the plugin has a corresponding seeder in `local-seeders/`, fix two things:
|
||||
|
||||
### 5a. ESM Build
|
||||
|
||||
Legacy seeders built with `tsc` or bundled Node built-ins. Fix:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"build": "tsup src/index.ts --format esm --target es2022 --clean"
|
||||
}
|
||||
```
|
||||
|
||||
This produces clean ESM that the data engine can `import()` without `Dynamic require` errors.
|
||||
|
||||
### 5b. Container-Aware File Paths
|
||||
|
||||
Legacy seeders used `fileURLToPath(import.meta.url)` to locate seed data. This breaks inside Docker because the transpiled path doesn't match the container filesystem.
|
||||
|
||||
```typescript
|
||||
// ❌ LEGACY — breaks in Docker container
|
||||
import { fileURLToPath } from "url";
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const dataPath = path.join(__dirname, "data", "seed.json");
|
||||
|
||||
// ✅ MODERN — works everywhere
|
||||
const dataPath = process.env.SEEDERS_DIR
|
||||
? path.join(process.env.SEEDERS_DIR, "community", "packages", "<name>", "data", "seed.json")
|
||||
: path.resolve(process.cwd(), "data", "seed.json");
|
||||
```
|
||||
|
||||
`SEEDERS_DIR` is set by the Docker container to `/app/seeders`. When running locally outside Docker, the fallback uses `process.cwd()`.
|
||||
|
||||
### 5c. Seeder Directory Naming
|
||||
|
||||
The folder name inside `local-seeders/community/packages/` or `local-seeders/private/packages/` **must exactly match** the plugin's string ID (`this.id` in `index.tsx`).
|
||||
|
||||
The `wwv-data-engine`'s auto-discovery logic (`seeder-loader.ts`) derives the internal plugin ID from the directory name. If the folder is named `gpsjam` but the frontend plugin expects `gps-jamming`, the frontend will not find it in the `/manifest` and will silently fall back to the cloud engine, breaking local testing.
|
||||
|
||||
```bash
|
||||
# ❌ INCORRECT (Frontend expects "gps-jamming")
|
||||
local-seeders/community/packages/gpsjam/
|
||||
|
||||
# ✅ CORRECT
|
||||
local-seeders/community/packages/gps-jamming/
|
||||
```
|
||||
|
||||
## Step 6: Clean Up packages/ References
|
||||
|
||||
After moving to `local-plugins/`, remove the old references:
|
||||
|
||||
- [ ] Delete `packages/wwv-plugin-<name>/` directory (or the source directory in `../worldwideview-plugins/packages/`)
|
||||
- [ ] Remove from `transpilePackages` in `next.config.ts` (if present)
|
||||
- [ ] Remove path alias from `tsconfig.json` `paths` (if present)
|
||||
- [ ] Remove any registration in `AppShell.tsx` (now loaded dynamically)
|
||||
- [ ] Run `pnpm install` from project root
|
||||
|
||||
## Step 7: Verify
|
||||
|
||||
```bash
|
||||
# 1. Start everything
|
||||
pnpm dev:all
|
||||
|
||||
# 2. Check engine discovered the seeder (if applicable)
|
||||
curl http://localhost:5000/manifest
|
||||
# Should include your plugin ID
|
||||
|
||||
# 3. Check frontend console — should show:
|
||||
# [EngineManifest] Local engine detected: N seeders ["your-plugin", ...]
|
||||
# NOT: fetching from https://dataengine.worldwideview.dev
|
||||
|
||||
# 4. Toggle the layer on the globe — entities should render
|
||||
```
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
- [ ] Plugin copied from `packages/` (or external repo) to `local-plugins/`
|
||||
- [ ] Frontend `fetch()` uses `this.context.getEngineUrl()` (not hardcoded URLs or dynamic imports)
|
||||
- [ ] `package.json` has `"type": "module"`, `"main": "dist/frontend.mjs"`
|
||||
- [ ] `vite.config.ts` uses `wwvPluginGlobals()` externalization
|
||||
- [ ] Backend seeder builds with `tsup --format esm --target es2022` (if applicable)
|
||||
- [ ] Backend seeder uses `process.env.SEEDERS_DIR` for file paths (if applicable)
|
||||
- [ ] Old source directory deleted
|
||||
- [ ] Old `transpilePackages`/`tsconfig paths` entries removed
|
||||
- [ ] `pnpm install` run from root
|
||||
- [ ] `pnpm dev:all` → local engine detected → data renders on globe
|
||||
@@ -1,170 +0,0 @@
|
||||
---
|
||||
name: plan-feature
|
||||
description: "Create comprehensive feature plan with deep codebase analysis and research"
|
||||
---
|
||||
|
||||
# Plan a new task
|
||||
|
||||
## Feature: $ARGUMENTS
|
||||
|
||||
## Mission
|
||||
|
||||
Transform a feature request into a **comprehensive implementation plan** through systematic codebase analysis, external research, and strategic planning.
|
||||
|
||||
**Core Principle**: We do NOT write code in this phase. Our goal is to create a context-rich implementation plan that enables one-pass implementation success for ai agents.
|
||||
|
||||
**Key Philosophy**: Context is King. The plan must contain ALL information needed for implementation - patterns, mandatory reading, documentation, validation commands - so the execution agent succeeds on the first attempt.
|
||||
|
||||
## Planning Process
|
||||
|
||||
### Phase 1: Feature Understanding
|
||||
|
||||
**Deep Feature Analysis:**
|
||||
|
||||
- Extract the core problem being solved
|
||||
- Identify user value and business impact
|
||||
- Determine feature type: New Capability/Enhancement/Refactor/Bug Fix
|
||||
- Assess complexity: Low/Medium/High
|
||||
- Map affected systems and components
|
||||
|
||||
**Create User Story Format Or Refine If Story Was Provided By The User:**
|
||||
|
||||
```
|
||||
As a <type of user>
|
||||
I want to <action/goal>
|
||||
So that <benefit/value>
|
||||
```
|
||||
|
||||
### Phase 2: Codebase Intelligence Gathering
|
||||
|
||||
**Use specialized agents and parallel analysis:**
|
||||
|
||||
**1. Project Structure Analysis**
|
||||
|
||||
- Detect primary language(s), frameworks, and runtime versions
|
||||
- Map directory structure and architectural patterns
|
||||
- Identify service/component boundaries and integration points
|
||||
- Locate configuration files (pyproject.toml, package.json, etc.)
|
||||
- Find environment setup and build processes
|
||||
|
||||
**2. Pattern Recognition** (Use specialized subagents when beneficial)
|
||||
|
||||
- Search for similar implementations in codebase
|
||||
- Identify coding conventions:
|
||||
- Naming patterns (CamelCase, snake_case, kebab-case)
|
||||
- File organization and module structure
|
||||
- Error handling approaches
|
||||
- Logging patterns and standards
|
||||
- Extract common patterns for the feature's domain
|
||||
- Document anti-patterns to avoid
|
||||
- Check CLAUDE.md for project-specific rules and conventions
|
||||
|
||||
**3. Dependency Analysis**
|
||||
|
||||
- Catalog external libraries relevant to feature
|
||||
- Understand how libraries are integrated (check imports, configs)
|
||||
- Find relevant documentation in docs/, ai_docs/, .agents/reference or ai-wiki if available
|
||||
- Note library versions and compatibility requirements
|
||||
|
||||
**4. Testing Patterns**
|
||||
|
||||
- Identify test framework and structure (pytest, jest, etc.)
|
||||
- Find similar test examples for reference
|
||||
- Understand test organization (unit vs integration)
|
||||
- Note coverage requirements and testing standards
|
||||
|
||||
**5. Integration Points**
|
||||
|
||||
- Identify existing files that need updates
|
||||
- Determine new files that need creation and their locations
|
||||
- Map router/API registration patterns
|
||||
- Understand database/model patterns if applicable
|
||||
- Identify authentication/authorization patterns if relevant
|
||||
|
||||
**Clarify Ambiguities:**
|
||||
|
||||
- If requirements are unclear at this point, ask the user to clarify before you continue
|
||||
- Get specific implementation preferences (libraries, approaches, patterns)
|
||||
- Resolve architectural decisions before proceeding
|
||||
|
||||
### Phase 3: External Research & Documentation
|
||||
|
||||
**Documentation Gathering:**
|
||||
|
||||
- Research latest library versions and best practices
|
||||
- Find official documentation with specific section anchors
|
||||
- Locate implementation examples and tutorials
|
||||
- Identify common gotchas and known issues
|
||||
- Check for breaking changes and migration guides
|
||||
|
||||
**Compile Research References:**
|
||||
|
||||
```markdown
|
||||
## Relevant Documentation
|
||||
|
||||
- [Library Official Docs](https://example.com/docs#section)
|
||||
- Specific feature implementation guide
|
||||
- Why: Needed for X functionality
|
||||
- [Framework Guide](https://example.com/guide#integration)
|
||||
- Integration patterns section
|
||||
- Why: Shows how to connect components
|
||||
```
|
||||
|
||||
### Phase 4: Deep Strategic Thinking
|
||||
|
||||
**Think Harder About:**
|
||||
|
||||
- How does this feature fit into the existing architecture?
|
||||
- What are the critical dependencies and order of operations?
|
||||
- What could go wrong? (Edge cases, race conditions, errors)
|
||||
- How will this be tested comprehensively?
|
||||
- What performance implications exist?
|
||||
- Are there security considerations?
|
||||
- How maintainable is this approach?
|
||||
|
||||
### Phase 5: Plan Structure Generation
|
||||
|
||||
**Output Filename**: `.agents/plans/{kebab-case-descriptive-name}.md`
|
||||
|
||||
**Plan Template:**
|
||||
|
||||
```markdown
|
||||
# Feature: <feature-name>
|
||||
|
||||
## Feature Description
|
||||
<Detailed description>
|
||||
|
||||
## User Story
|
||||
As a <type of user>
|
||||
I want to <action/goal>
|
||||
So that <benefit/value>
|
||||
|
||||
## CONTEXT REFERENCES
|
||||
|
||||
### Relevant Codebase Files
|
||||
- `path/to/file.py` (lines 15-45) - Why: Contains pattern for X
|
||||
|
||||
### New Files to Create
|
||||
- `path/to/new_service.py` - Service implementation
|
||||
|
||||
## STEP-BY-STEP TASKS
|
||||
|
||||
### Task N: {ACTION} {target_file}
|
||||
- **IMPLEMENT**: {Specific detail}
|
||||
- **PATTERN**: {Reference - file:line}
|
||||
- **VALIDATE**: `{executable command}`
|
||||
|
||||
## VALIDATION COMMANDS
|
||||
|
||||
## ACCEPTANCE CRITERIA
|
||||
- [ ] Feature implements all specified functionality
|
||||
- [ ] All validation commands pass
|
||||
```
|
||||
|
||||
## Quality Criteria
|
||||
|
||||
- Another developer could execute without additional context
|
||||
- Tasks ordered by dependency
|
||||
- Each task is atomic and independently testable
|
||||
- Pattern references include specific file:line numbers
|
||||
- No generic references — all specific and actionable
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
description: Comprehensive pull request review from multiple perspectives.
|
||||
---
|
||||
|
||||
# Pull Request Review
|
||||
|
||||
Comprehensive pull request review from multiple perspectives.
|
||||
|
||||
## Review Roles:
|
||||
|
||||
### 1. Product Manager Review
|
||||
- **Business Value**: Does this deliver promised value?
|
||||
- **User Experience**: Will users benefit from this change?
|
||||
- **Strategic Alignment**: Does it align with product goals?
|
||||
- **Feature Completeness**: Are all requirements met?
|
||||
- **Action**: Provide directives for maximum impact
|
||||
|
||||
### 2. Developer Review
|
||||
- **Code Quality**: Is code clean and maintainable?
|
||||
- **Standards**: Does it follow coding conventions?
|
||||
- **Performance**: Are there efficiency concerns?
|
||||
- **Scalability**: Will it handle growth?
|
||||
- **Refactoring**: Any code that needs improvement?
|
||||
- **Action**: Suggest specific code improvements
|
||||
|
||||
### 3. Quality Engineer Review
|
||||
- **Test Coverage**: Are all paths tested?
|
||||
- **Edge Cases**: Are boundary conditions handled?
|
||||
- **Regression Risk**: Could this break existing features?
|
||||
- **Test Quality**: Are tests comprehensive and clear?
|
||||
- **Action**: Identify missing tests and scenarios
|
||||
|
||||
### 4. Security Engineer Review
|
||||
- **Vulnerabilities**: Any security risks?
|
||||
- **Data Handling**: Is sensitive data protected?
|
||||
- **Authentication**: Are auth checks proper?
|
||||
- **Input Validation**: Is user input sanitized?
|
||||
- **Compliance**: Does it meet security standards?
|
||||
- **Action**: Flag security concerns immediately
|
||||
|
||||
### 5. DevOps Review
|
||||
- **CI/CD Integration**: Will builds succeed?
|
||||
- **Configuration**: Are configs properly managed?
|
||||
- **Infrastructure**: Any deployment concerns?
|
||||
- **Monitoring**: Are metrics and logs adequate?
|
||||
- **Rollback**: Can changes be safely reverted?
|
||||
- **Action**: Ensure smooth deployment
|
||||
|
||||
### 6. UI/UX Designer Review
|
||||
- **Visual Consistency**: Does it match design system?
|
||||
- **Usability**: Is it intuitive to use?
|
||||
- **Accessibility**: Is it accessible to all users?
|
||||
- **Responsive**: Does it work on all devices?
|
||||
- **Polish**: Any rough edges to smooth?
|
||||
- **Action**: Ensure delightful user experience
|
||||
|
||||
## Review Process:
|
||||
1. Read PR description and linked issues
|
||||
2. Review code changes systematically
|
||||
3. Test functionality locally if applicable
|
||||
4. Consider each perspective above
|
||||
5. Leave constructive feedback
|
||||
6. Approve or request changes
|
||||
|
||||
## Key Principle:
|
||||
**Improvements scheduled for "later" must be addressed NOW!**
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
name: prime
|
||||
description: Use when loading project context at the start of a session — analyzes structure, reads core documentation, and provides an overview of the codebase state.
|
||||
---
|
||||
|
||||
# Prime: Load Project Context
|
||||
|
||||
## Objective
|
||||
|
||||
Build comprehensive understanding of the codebase by analyzing structure, documentation, and key files.
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Analyze Project Structure
|
||||
|
||||
List all tracked files:
|
||||
!`git ls-files`
|
||||
|
||||
Show directory structure:
|
||||
On Linux, run: `tree -L 3 -I 'node_modules|__pycache__|.git|dist|build'`
|
||||
|
||||
### 2. Read Core Documentation
|
||||
|
||||
- Read the PRD.md or similar spec file
|
||||
- Read CLAUDE.md or similar global rules file
|
||||
- Read README files at project root and major directories
|
||||
- Read any architecture documentation
|
||||
- Read the drizzle config so you understand the database schema
|
||||
|
||||
### 3. Identify Key Files
|
||||
|
||||
Based on the structure, identify and read:
|
||||
- Main entry points (main.py, index.ts, app.py, etc.)
|
||||
- Core configuration files (pyproject.toml, package.json, tsconfig.json)
|
||||
- Key model/schema definitions
|
||||
- Important service or controller files
|
||||
|
||||
### 4. Understand Current State
|
||||
|
||||
Check recent activity:
|
||||
!`git log -10 --oneline`
|
||||
|
||||
Check current branch and status:
|
||||
!`git status`
|
||||
|
||||
## Output Report
|
||||
|
||||
Provide a concise summary covering:
|
||||
|
||||
### Project Overview
|
||||
- Purpose and type of application
|
||||
- Primary technologies and frameworks
|
||||
- Current version/state
|
||||
|
||||
### Architecture
|
||||
- Overall structure and organization
|
||||
- Key architectural patterns identified
|
||||
- Important directories and their purposes
|
||||
|
||||
### Tech Stack
|
||||
- Languages and versions
|
||||
- Frameworks and major libraries
|
||||
- Build tools and package managers
|
||||
- Testing frameworks
|
||||
|
||||
### Core Principles
|
||||
- Code style and conventions observed
|
||||
- Documentation standards
|
||||
- Testing approach
|
||||
|
||||
### Current State
|
||||
- Active branch
|
||||
- Recent changes or development focus
|
||||
- Any immediate observations or concerns
|
||||
|
||||
**Make this summary easy to scan - use bullet points and clear headers.**
|
||||
@@ -1,192 +0,0 @@
|
||||
---
|
||||
name: prisma-database-setup
|
||||
description: Guides for configuring Prisma with different database providers (PostgreSQL, MySQL, SQLite, MongoDB, etc.). Use when setting up a new project, changing databases, or troubleshooting connection issues. Triggers on "configure postgres", "connect to mysql", "setup mongodb", "sqlite setup".
|
||||
license: MIT
|
||||
metadata:
|
||||
author: prisma
|
||||
version: "7.6.0"
|
||||
---
|
||||
|
||||
# Prisma Database Setup
|
||||
|
||||
Comprehensive guides for configuring Prisma ORM with various database providers.
|
||||
|
||||
## When to Apply
|
||||
|
||||
Reference this skill when:
|
||||
- Initializing a new Prisma project
|
||||
- Switching database providers
|
||||
- Configuring connection strings and environment variables
|
||||
- Troubleshooting database connection issues
|
||||
- Setting up database-specific features
|
||||
- Generating and instantiating Prisma Client
|
||||
|
||||
## Rule Categories by Priority
|
||||
|
||||
| Priority | Category | Impact | Prefix |
|
||||
|----------|----------|--------|--------|
|
||||
| 1 | Provider Guides | CRITICAL | provider names |
|
||||
| 2 | Prisma Postgres | HIGH | `prisma-postgres` |
|
||||
| 3 | Client Setup | CRITICAL | `prisma-client-setup` |
|
||||
|
||||
## System Prerequisites
|
||||
|
||||
- **Node.js 20.19.0+**
|
||||
- **TypeScript 5.4.0+**
|
||||
|
||||
## Bun Runtime
|
||||
|
||||
If you're using Bun, run Prisma CLI commands with `bunx --bun prisma ...` so Prisma uses the Bun runtime instead of falling back to Node.js.
|
||||
|
||||
## Supported Databases
|
||||
|
||||
| Database | Provider String | Notes |
|
||||
|----------|-----------------|-------|
|
||||
| PostgreSQL | `postgresql` | Default, full feature support |
|
||||
| MySQL | `mysql` | Widespread support, some JSON diffs |
|
||||
| SQLite | `sqlite` | Local file-based, no enum/scalar lists |
|
||||
| MongoDB | `mongodb` | Mongo-specific workflow; do not apply SQL driver-adapter guidance |
|
||||
| SQL Server | `sqlserver` | Microsoft ecosystem |
|
||||
| CockroachDB | `cockroachdb` | Distributed SQL, Postgres-compatible |
|
||||
| Prisma Postgres | `postgresql` | Managed serverless database |
|
||||
|
||||
## Configuration Files
|
||||
|
||||
Your configuration shape depends on the provider and Prisma major version:
|
||||
|
||||
1. **All providers** use **`prisma/schema.prisma`**.
|
||||
2. **Prisma 7 SQL setups** typically use **`prisma.config.ts`** for datasource URLs.
|
||||
3. **MongoDB projects should stay on Prisma 6.x**, keep `url = env("DATABASE_URL")` in the schema, and continue using the classic MongoDB setup.
|
||||
|
||||
## Driver Adapters
|
||||
|
||||
The standard SQL workflow uses a driver adapter. Choose the adapter and driver for your database and pass the adapter to `PrismaClient`.
|
||||
|
||||
| Database | Adapter | JS Driver |
|
||||
|----------|---------|-----------|
|
||||
| PostgreSQL | `@prisma/adapter-pg` | `pg` |
|
||||
| CockroachDB | `@prisma/adapter-pg` | `pg` |
|
||||
| Prisma Postgres (Node.js) | `@prisma/adapter-pg` | `pg` |
|
||||
| Prisma Postgres (edge/serverless) | `@prisma/adapter-ppg` | `@prisma/ppg` |
|
||||
| MySQL / MariaDB | `@prisma/adapter-mariadb` | `mariadb` |
|
||||
| SQLite | `@prisma/adapter-better-sqlite3` | `better-sqlite3` |
|
||||
| SQLite (Turso/LibSQL) | `@prisma/adapter-libsql` | `@libsql/client` |
|
||||
| SQL Server | `@prisma/adapter-mssql` | `node-mssql` |
|
||||
|
||||
MongoDB should not follow the Prisma 7 SQL adapter workflow. Use the latest Prisma 6.x release for MongoDB projects and do not install a SQL `@prisma/adapter-*` package for it.
|
||||
|
||||
Example (PostgreSQL):
|
||||
|
||||
```ts
|
||||
import 'dotenv/config'
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
## Prisma Client Setup (Required)
|
||||
|
||||
Prisma Client must be installed and generated for any database.
|
||||
|
||||
1. Install Prisma CLI and Prisma Client:
|
||||
```bash
|
||||
npm install prisma --save-dev
|
||||
npm install @prisma/client
|
||||
```
|
||||
|
||||
1. Add a generator block (`prisma-client` requires an explicit output path):
|
||||
```prisma
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
1. Generate Prisma Client:
|
||||
```bash
|
||||
npx prisma generate
|
||||
```
|
||||
|
||||
1. For SQL providers, instantiate Prisma Client with the database-specific driver adapter:
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
1. Re-run `prisma generate` after every schema change.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### PostgreSQL
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
### MySQL
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "mysql"
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
### SQLite
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "sqlite"
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
### MongoDB
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "mongodb"
|
||||
url = env("DATABASE_URL")
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client-js"
|
||||
}
|
||||
```
|
||||
|
||||
For MongoDB, stay on the latest Prisma 6.x line and keep the connection URL in `schema.prisma`. Do not move a MongoDB project to the Prisma 7 SQL adapter setup.
|
||||
|
||||
## Rule Files
|
||||
|
||||
See individual rule files for detailed setup instructions:
|
||||
|
||||
```
|
||||
references/postgresql.md
|
||||
references/mysql.md
|
||||
references/sqlite.md
|
||||
references/mongodb.md
|
||||
references/sqlserver.md
|
||||
references/cockroachdb.md
|
||||
references/prisma-postgres.md
|
||||
references/prisma-client-setup.md
|
||||
```
|
||||
|
||||
## How to Use
|
||||
|
||||
Choose the provider reference file for your database, then apply `references/prisma-client-setup.md` to complete client generation and adapter setup. For MongoDB, use `references/mongodb.md` instead of copying the SQL adapter examples or Prisma 7 config pattern.
|
||||
@@ -1,89 +0,0 @@
|
||||
# CockroachDB Setup
|
||||
|
||||
Configure Prisma with CockroachDB.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- CockroachDB cluster
|
||||
|
||||
## 1. Schema Configuration
|
||||
|
||||
In `prisma/schema.prisma`:
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "cockroachdb"
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Config Configuration
|
||||
|
||||
In `prisma.config.ts`:
|
||||
|
||||
```typescript
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
schema: 'prisma/schema.prisma',
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## 3. Environment Variable
|
||||
|
||||
In `.env`:
|
||||
|
||||
```env
|
||||
DATABASE_URL="postgresql://user:password@host:26257/db?sslmode=verify-full"
|
||||
```
|
||||
|
||||
Note: CockroachDB uses the PostgreSQL wire protocol, so the URL often looks like postgresql, but the provider **MUST** be `cockroachdb` in the schema to handle specific CRDB features correctly.
|
||||
|
||||
## Driver Adapter
|
||||
|
||||
Use a driver adapter for the standard SQL workflow. CockroachDB is PostgreSQL-compatible, so use the PostgreSQL adapter.
|
||||
|
||||
1. Install adapter and driver:
|
||||
```bash
|
||||
npm install @prisma/adapter-pg pg
|
||||
```
|
||||
|
||||
2. Instantiate Prisma Client with the adapter:
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
## ID Generation
|
||||
|
||||
CockroachDB uses `BigInt` or `UUID` for IDs efficiently.
|
||||
|
||||
```prisma
|
||||
model User {
|
||||
id BigInt @id @default(autoincrement()) // Uses unique_rowid()
|
||||
}
|
||||
```
|
||||
|
||||
Or using string UUIDs:
|
||||
|
||||
```prisma
|
||||
model User {
|
||||
id String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
|
||||
}
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Schema Introspection
|
||||
Always use `provider = "cockroachdb"` to ensure correct type mapping during `db pull`.
|
||||
@@ -1,90 +0,0 @@
|
||||
# MongoDB Setup
|
||||
|
||||
MongoDB projects should stay on the latest Prisma 6.x release. Do not upgrade a MongoDB app to Prisma 7's SQL client path.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- MongoDB 4.2+
|
||||
- Replica Set configured (required for transactions)
|
||||
- Latest Prisma 6.x release, or your team's pinned Prisma 6 version
|
||||
- Node.js 20.19.0+
|
||||
- TypeScript 5.4.0+
|
||||
|
||||
## 1. Schema Configuration
|
||||
|
||||
Use the standard Prisma 6 MongoDB setup with `prisma-client-js`.
|
||||
|
||||
In `prisma/schema.prisma`:
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "mongodb"
|
||||
url = env("DATABASE_URL")
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client-js"
|
||||
}
|
||||
```
|
||||
|
||||
### Driver Adapters
|
||||
|
||||
Do **not** apply the Prisma 7 SQL adapter setup here. MongoDB does not use a SQL `@prisma/adapter-*` package.
|
||||
|
||||
### ID Field Requirement
|
||||
|
||||
MongoDB models **must** have a mapped `_id` field using `@id` and `@map("_id")`, usually of type `String` with `auto()` and `db.ObjectId`.
|
||||
|
||||
```prisma
|
||||
model User {
|
||||
id String @id @default(auto()) @map("_id") @db.ObjectId
|
||||
email String @unique
|
||||
name String?
|
||||
}
|
||||
```
|
||||
|
||||
### Relations
|
||||
|
||||
Relations in MongoDB expect IDs to be `db.ObjectId` type.
|
||||
|
||||
```prisma
|
||||
model Post {
|
||||
id String @id @default(auto()) @map("_id") @db.ObjectId
|
||||
author User @relation(fields: [authorId], references: [id])
|
||||
authorId String @db.ObjectId
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Environment Variable
|
||||
|
||||
In `.env`:
|
||||
|
||||
```env
|
||||
DATABASE_URL="mongodb+srv://user:[email protected]/mydb?retryWrites=true&w=majority"
|
||||
```
|
||||
|
||||
## Migrations vs Introspection
|
||||
|
||||
- **No Migrations**: MongoDB is schema-less. `prisma migrate` commands **do not work**.
|
||||
- **db push**: Use `prisma db push` to sync indexes and constraints.
|
||||
- **db pull**: Use `prisma db pull` to generate schema from existing data (sampling).
|
||||
|
||||
## Current Verification Notes
|
||||
|
||||
- `prisma init --datasource-provider mongodb` is still implemented in Prisma's CLI source.
|
||||
- Prisma's upstream repo still contains MongoDB fixtures and tests.
|
||||
- Local verification shows Prisma 7 can still recognize MongoDB inputs, but the generated client path does not provide a supported MongoDB upgrade path.
|
||||
- Local verification shows Prisma 6.x works end to end with `prisma-client-js`, `prisma db push`, and `new PrismaClient()` against a MongoDB replica set.
|
||||
|
||||
## Version Guidance
|
||||
|
||||
- For MongoDB, stay on the latest available Prisma 6.x release.
|
||||
- Treat Prisma 7 MongoDB migration attempts as unsupported until Prisma ships a real MongoDB upgrade path.
|
||||
|
||||
## Common Issues
|
||||
|
||||
### "Transactions not supported"
|
||||
Ensure your MongoDB instance is a **Replica Set**. Standalone instances do not support transactions. Atlas clusters are replica sets by default.
|
||||
|
||||
### "Invalid ObjectID"
|
||||
Ensure fields referencing IDs are decorated with `@db.ObjectId` if the target is an ObjectID.
|
||||
@@ -1,126 +0,0 @@
|
||||
# MySQL Setup
|
||||
|
||||
Configure Prisma with MySQL (or MariaDB).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- MySQL or MariaDB database
|
||||
- Connection string
|
||||
|
||||
## 1. Schema Configuration
|
||||
|
||||
In `prisma/schema.prisma`:
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "mysql"
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Config Configuration
|
||||
|
||||
In `prisma.config.ts`:
|
||||
|
||||
```typescript
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
schema: 'prisma/schema.prisma',
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## 3. Environment Variable
|
||||
|
||||
In `.env`:
|
||||
|
||||
```env
|
||||
DATABASE_URL="mysql://user:password@localhost:3306/mydb"
|
||||
```
|
||||
|
||||
### Connection String Format
|
||||
|
||||
```
|
||||
mysql://USER:PASSWORD@HOST:PORT/DATABASE
|
||||
```
|
||||
|
||||
- **USER**: Database user
|
||||
- **PASSWORD**: Password
|
||||
- **HOST**: Hostname
|
||||
- **PORT**: Port (default 3306)
|
||||
- **DATABASE**: Database name
|
||||
|
||||
## Driver Adapter
|
||||
|
||||
Use a driver adapter for the standard SQL workflow.
|
||||
|
||||
1. Install adapter and driver:
|
||||
```bash
|
||||
npm install @prisma/adapter-mariadb mariadb
|
||||
```
|
||||
|
||||
2. Instantiate Prisma Client with the adapter:
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaMariaDb } from '@prisma/adapter-mariadb'
|
||||
|
||||
const adapter = new PrismaMariaDb({
|
||||
host: 'localhost',
|
||||
port: 3306,
|
||||
connectionLimit: 5,
|
||||
user: process.env.MYSQL_USER,
|
||||
password: process.env.MYSQL_PASSWORD,
|
||||
database: process.env.MYSQL_DATABASE,
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
### Text protocol option
|
||||
|
||||
If you need the MariaDB driver's text protocol instead of the default binary `execute()` path, enable `useTextProtocol` explicitly:
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaMariaDb } from '@prisma/adapter-mariadb'
|
||||
|
||||
const adapter = new PrismaMariaDb(process.env.DATABASE_URL!, {
|
||||
useTextProtocol: true,
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
Use this only when you specifically need text-protocol compatibility for your MariaDB setup.
|
||||
|
||||
## PlanetScale Setup
|
||||
|
||||
PlanetScale uses MySQL but requires specific settings because it doesn't support foreign key constraints.
|
||||
|
||||
In `prisma/schema.prisma`:
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "mysql"
|
||||
relationMode = "prisma" // Emulate foreign keys in Prisma
|
||||
}
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### "Too many connections"
|
||||
MySQL has a connection limit. Adjust connection pool size in URL:
|
||||
```env
|
||||
DATABASE_URL="mysql://...?connection_limit=5"
|
||||
```
|
||||
|
||||
### JSON Support
|
||||
MySQL 5.7+ supports JSON. MariaDB 10.2+ supports JSON (as an alias for LONGTEXT with check constraints). Prisma handles this, but verify your version.
|
||||
@@ -1,92 +0,0 @@
|
||||
# PostgreSQL Setup
|
||||
|
||||
Configure Prisma with PostgreSQL.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- PostgreSQL database (local or cloud)
|
||||
- Connection string
|
||||
|
||||
## 1. Schema Configuration
|
||||
|
||||
In `prisma/schema.prisma`:
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Config Configuration
|
||||
|
||||
In `prisma.config.ts`:
|
||||
|
||||
```typescript
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
schema: 'prisma/schema.prisma',
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## 3. Environment Variable
|
||||
|
||||
In `.env`:
|
||||
|
||||
```env
|
||||
DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"
|
||||
```
|
||||
|
||||
### Connection String Format
|
||||
|
||||
```
|
||||
postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA
|
||||
```
|
||||
|
||||
- **USER**: Database user
|
||||
- **PASSWORD**: Password (URL encoded if special chars)
|
||||
- **HOST**: Hostname (localhost, IP, or domain)
|
||||
- **PORT**: Port (default 5432)
|
||||
- **DATABASE**: Database name
|
||||
- **SCHEMA**: Schema name (default `public`)
|
||||
|
||||
## Driver Adapter
|
||||
|
||||
Use a driver adapter for the standard SQL workflow.
|
||||
|
||||
1. Install adapter and driver:
|
||||
```bash
|
||||
npm install @prisma/adapter-pg pg
|
||||
```
|
||||
|
||||
2. Instantiate Prisma Client with the adapter:
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### "Can't reach database server"
|
||||
- Check host and port
|
||||
- Check firewall settings
|
||||
- Ensure database is running
|
||||
|
||||
### "Authentication failed"
|
||||
- Check user/password
|
||||
- Special characters in password must be URL-encoded
|
||||
|
||||
### "Schema does not exist"
|
||||
- Ensure `?schema=public` (or your schema) is in the URL
|
||||
@@ -1,47 +0,0 @@
|
||||
# Prisma Client Setup
|
||||
|
||||
Generate and instantiate Prisma Client for Prisma's standard SQL provider workflow. For MongoDB, follow the provider-specific notes in `references/mongodb.md` instead of copying the SQL adapter example below.
|
||||
|
||||
## 1. Install dependencies
|
||||
|
||||
```bash
|
||||
npm install prisma --save-dev
|
||||
npm install @prisma/client
|
||||
```
|
||||
|
||||
## 2. Add generator block
|
||||
|
||||
In `prisma/schema.prisma`:
|
||||
|
||||
```prisma
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
`prisma-client` requires an explicit `output` path and does not generate into `node_modules` by default.
|
||||
|
||||
## 3. Generate Prisma Client
|
||||
|
||||
```bash
|
||||
npx prisma generate
|
||||
```
|
||||
|
||||
Re-run `prisma generate` after every schema change to keep the client in sync.
|
||||
|
||||
## 4. Instantiate Prisma Client
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
If you change the generator `output`, update the import path to match. For the SQL provider workflow, replace `PrismaPg` with the adapter for your database.
|
||||
|
||||
## 5. Use a single instance
|
||||
|
||||
Each `PrismaClient` instance creates a connection pool. Reuse a single instance per app process to avoid exhausting database connections.
|
||||
@@ -1,130 +0,0 @@
|
||||
# Prisma Postgres Setup
|
||||
|
||||
Configure Prisma with Prisma Postgres (Managed).
|
||||
|
||||
## Overview
|
||||
|
||||
Prisma Postgres is a serverless, managed PostgreSQL database optimized for Prisma.
|
||||
|
||||
## Setup via CLI
|
||||
|
||||
You can provision a Prisma Postgres instance directly via the CLI:
|
||||
|
||||
```bash
|
||||
prisma init --db
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Log you into Prisma Data Platform.
|
||||
2. Create a new project and database instance.
|
||||
3. Update your `.env` with the connection string.
|
||||
|
||||
## Connection String
|
||||
|
||||
For Prisma CLI flows and Accelerate-style usage, you may see a `prisma+postgres://` URL.
|
||||
|
||||
For Prisma Client with a driver adapter in Node.js, prefer the direct TCP connection string from the Prisma Postgres dashboard:
|
||||
|
||||
```env
|
||||
DATABASE_URL="postgres://identifier:[email protected]:5432/postgres?sslmode=require"
|
||||
```
|
||||
|
||||
## 1. Schema Configuration
|
||||
|
||||
In `prisma/schema.prisma`:
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "postgresql" // Use postgresql provider
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Config Configuration
|
||||
|
||||
In `prisma.config.ts`:
|
||||
|
||||
```typescript
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
schema: 'prisma/schema.prisma',
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Driver Adapter
|
||||
|
||||
Use a driver adapter for Prisma Postgres in the standard SQL workflow.
|
||||
|
||||
### Recommended for standard Node.js apps
|
||||
|
||||
1. Install adapter and driver:
|
||||
```bash
|
||||
npm install @prisma/adapter-pg pg
|
||||
```
|
||||
|
||||
2. Use the direct TCP connection string from Prisma Console:
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
`PrismaPg` also accepts the connection string directly:
|
||||
|
||||
```typescript
|
||||
const adapter = new PrismaPg(process.env.DATABASE_URL!)
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
For PostgreSQL prepared statement naming, pass adapter options as the second argument:
|
||||
|
||||
```typescript
|
||||
import { createHash } from 'node:crypto'
|
||||
|
||||
const adapter = new PrismaPg(process.env.DATABASE_URL!, {
|
||||
statementNameGenerator: ({ sql }) =>
|
||||
`prisma_${createHash('sha1').update(sql).digest('hex').slice(0, 16)}`,
|
||||
})
|
||||
```
|
||||
|
||||
### Edge/serverless option
|
||||
|
||||
Use the Prisma Postgres serverless driver only when you need HTTP/WebSocket transport in environments like Workers or Edge Functions:
|
||||
|
||||
```bash
|
||||
npm install @prisma/adapter-ppg @prisma/ppg
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPostgresAdapter } from '@prisma/adapter-ppg'
|
||||
|
||||
const prisma = new PrismaClient({
|
||||
adapter: new PrismaPostgresAdapter({
|
||||
connectionString: process.env.PRISMA_DIRECT_TCP_URL,
|
||||
}),
|
||||
})
|
||||
```
|
||||
|
||||
This serverless driver is the specialized path for HTTP/WebSocket-based edge and serverless runtimes, not the default recommendation for standard Node.js apps.
|
||||
|
||||
## Features
|
||||
|
||||
- **Serverless**: Scales to zero.
|
||||
- **Caching**: Integrated query caching (Accelerate).
|
||||
- **Real-time**: Database events (Pulse).
|
||||
|
||||
## Using with Prisma Client
|
||||
|
||||
Use the Prisma Postgres adapter shown above when instantiating Prisma Client.
|
||||
@@ -1,106 +0,0 @@
|
||||
# SQLite Setup
|
||||
|
||||
Configure Prisma with SQLite.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- None (file-based)
|
||||
|
||||
## 1. Schema Configuration
|
||||
|
||||
In `prisma/schema.prisma`:
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "sqlite"
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Config Configuration
|
||||
|
||||
In `prisma.config.ts`:
|
||||
|
||||
```typescript
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
schema: 'prisma/schema.prisma',
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## 3. Environment Variable
|
||||
|
||||
In `.env`:
|
||||
|
||||
```env
|
||||
DATABASE_URL="file:./dev.db"
|
||||
```
|
||||
|
||||
### Connection String Format
|
||||
|
||||
```
|
||||
file:PATH
|
||||
```
|
||||
|
||||
- **PATH**: Relative path to the database file. Check `prisma.config.ts` if you need to confirm how your app resolves it.
|
||||
|
||||
## Driver Adapter
|
||||
|
||||
Use a driver adapter for the standard SQL workflow.
|
||||
|
||||
1. Install adapter and driver:
|
||||
```bash
|
||||
npm install @prisma/adapter-better-sqlite3 better-sqlite3
|
||||
```
|
||||
|
||||
2. Instantiate Prisma Client with the adapter:
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3'
|
||||
|
||||
const adapter = new PrismaBetterSqlite3({
|
||||
url: process.env.DATABASE_URL ?? 'file:./dev.db',
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
## Using Driver Adapter (LibSQL / Turso)
|
||||
|
||||
For edge compatibility or Turso:
|
||||
|
||||
1. Install:
|
||||
```bash
|
||||
npm install @prisma/adapter-libsql @libsql/client
|
||||
```
|
||||
|
||||
2. Instantiate:
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaLibSql } from '@prisma/adapter-libsql'
|
||||
|
||||
const adapter = new PrismaLibSql({
|
||||
url: process.env.TURSO_DATABASE_URL,
|
||||
authToken: process.env.TURSO_AUTH_TOKEN,
|
||||
})
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
- **No Enums**: SQLite doesn't support enums (Prisma polyfills them or treats as String).
|
||||
- **No Scalar Lists**: `String[]` is not supported directly.
|
||||
- **Concurrency**: Write operations lock the file.
|
||||
|
||||
## Common Issues
|
||||
|
||||
### "Database file not found"
|
||||
Ensure the path in `DATABASE_URL` is correct relative to where Prisma is running or the schema file. `file:./dev.db` creates it next to schema.
|
||||
@@ -1,94 +0,0 @@
|
||||
# SQL Server Setup
|
||||
|
||||
Configure Prisma with Microsoft SQL Server.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- SQL Server 2017, 2019, 2022, or Azure SQL
|
||||
- TCP/IP enabled
|
||||
|
||||
## 1. Schema Configuration
|
||||
|
||||
In `prisma/schema.prisma`:
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "sqlserver"
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Config Configuration
|
||||
|
||||
In `prisma.config.ts`:
|
||||
|
||||
```typescript
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
schema: 'prisma/schema.prisma',
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## 3. Environment Variable
|
||||
|
||||
In `.env`:
|
||||
|
||||
```env
|
||||
DATABASE_URL="sqlserver://localhost:1433;database=mydb;user=sa;password=Password123;encrypt=true;trustServerCertificate=true"
|
||||
```
|
||||
|
||||
### Connection String Format
|
||||
|
||||
```
|
||||
sqlserver://HOST:PORT;database=DB;user=USER;password=PASS;encrypt=true;trustServerCertificate=true
|
||||
```
|
||||
|
||||
- **encrypt**: Required for Azure (true).
|
||||
- **trustServerCertificate**: True for self-signed certs (local dev).
|
||||
|
||||
## Driver Adapter
|
||||
|
||||
Use a driver adapter for the standard SQL workflow.
|
||||
|
||||
1. Install adapter and driver:
|
||||
```bash
|
||||
npm install @prisma/adapter-mssql mssql
|
||||
```
|
||||
|
||||
2. Instantiate Prisma Client with the adapter:
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaMssql } from '@prisma/adapter-mssql'
|
||||
|
||||
const adapter = new PrismaMssql({
|
||||
server: 'localhost',
|
||||
port: 1433,
|
||||
database: 'mydb',
|
||||
user: process.env.SQLSERVER_USER,
|
||||
password: process.env.SQLSERVER_PASSWORD,
|
||||
options: {
|
||||
encrypt: true,
|
||||
trustServerCertificate: true,
|
||||
},
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### "Login failed for user"
|
||||
- SQL Server auth vs Windows auth. Prisma typically uses SQL Server authentication (username/password).
|
||||
- Ensure TCP/IP is enabled in SQL Server Configuration Manager.
|
||||
|
||||
### "Table not found" (dbo schema)
|
||||
Prisma assumes `dbo` schema by default. If using another schema, update the model or connection string? SQL Server provider mostly sticks to default schema.
|
||||
@@ -1,253 +0,0 @@
|
||||
---
|
||||
name: prisma-upgrade-v7
|
||||
description: Complete migration guide from Prisma ORM v6 to v7 covering all breaking changes. Use when upgrading Prisma versions, encountering v7 errors, or migrating existing projects. Triggers on "upgrade to prisma 7", "prisma 7 migration", "prisma-client generator", "driver adapter required".
|
||||
license: MIT
|
||||
metadata:
|
||||
author: prisma
|
||||
version: "7.6.0"
|
||||
---
|
||||
|
||||
# Upgrade to Prisma ORM 7
|
||||
|
||||
Complete guide for migrating from Prisma ORM v6 to v7. This upgrade introduces significant breaking changes around the new `prisma-client` generator, driver adapters, `prisma.config.ts`, explicit environment loading, and generated client entrypoints.
|
||||
|
||||
## When to Apply
|
||||
|
||||
Reference this skill when:
|
||||
- Upgrading from Prisma v6 to v7
|
||||
- Updating to the `prisma-client` generator
|
||||
- Setting up driver adapters
|
||||
- Configuring `prisma.config.ts`
|
||||
- Fixing import errors after upgrade
|
||||
|
||||
## Rule Categories by Priority
|
||||
|
||||
| Priority | Category | Impact | Prefix |
|
||||
|----------|----------|--------|--------|
|
||||
| 1 | Schema Migration | CRITICAL | `schema-changes` |
|
||||
| 2 | Database Connectivity | CRITICAL | `driver-adapters` |
|
||||
| 3 | Module System | CRITICAL | `esm-support` |
|
||||
| 4 | Config and Env | HIGH | `prisma-config`, `env-variables` |
|
||||
| 5 | Removed Features | HIGH | `removed-features` |
|
||||
| 6 | Accelerate | HIGH | `accelerate-users` |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- `schema-changes` - generator migration, required output paths, generated entrypoints, and `Prisma.validator` replacement
|
||||
- `driver-adapters` - required adapter installation for SQL providers, pool differences, and Prisma Postgres adapter choices
|
||||
- `esm-support` - ESM-first setup plus CommonJS fallback with `moduleFormat = "cjs"`
|
||||
- `prisma-config` - creating and using `prisma.config.ts`
|
||||
- `env-variables` - explicit environment loading
|
||||
- `removed-features` - removed middleware, metrics, and legacy CLI behavior
|
||||
- `accelerate-users` - migration notes for Accelerate users
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **MongoDB projects should stay on Prisma 6.x** - do not migrate MongoDB apps to Prisma 7's SQL client path
|
||||
- **Node.js 20.19.0+** required
|
||||
- **TypeScript 5.4.0+** required
|
||||
- **Latest stable Prisma ORM version**: `7.6.0`
|
||||
|
||||
## Upgrade Steps Overview
|
||||
|
||||
1. Update packages to v7
|
||||
2. Choose your module format (`esm` by default, `cjs` if needed)
|
||||
3. Update TypeScript configuration
|
||||
4. Update the schema generator block
|
||||
5. Create `prisma.config.ts`
|
||||
6. Install and configure a driver adapter for SQL providers
|
||||
7. Update Prisma Client imports
|
||||
8. Update client instantiation
|
||||
9. Replace deprecated helper patterns like `Prisma.validator`
|
||||
10. Run `prisma generate` and test
|
||||
|
||||
## Quick Upgrade Commands
|
||||
|
||||
```bash
|
||||
# Update packages
|
||||
npm install @prisma/client@7
|
||||
npm install -D prisma@7
|
||||
|
||||
# Install a driver adapter (PostgreSQL or Prisma Postgres via direct TCP)
|
||||
npm install @prisma/adapter-pg pg
|
||||
|
||||
# Install dotenv for env loading
|
||||
npm install dotenv
|
||||
|
||||
# Regenerate client
|
||||
npx prisma generate
|
||||
```
|
||||
|
||||
## Breaking Changes Summary
|
||||
|
||||
| Change | v6 | v7 |
|
||||
|--------|----|----|
|
||||
| Module format | Implicit / mixed | ESM-first, `moduleFormat = "cjs"` supported |
|
||||
| Generator provider | `prisma-client-js` | `prisma-client` is the default, while `prisma-client-js` still exists for legacy setups |
|
||||
| Output path | Auto (node_modules) | Required explicit |
|
||||
| Driver adapters | Optional | Required for SQL providers |
|
||||
| Config file | `.env` + schema | `prisma.config.ts` |
|
||||
| Env loading | Automatic | Manual (dotenv) |
|
||||
| Generated entrypoints | Single package export | `client`, `browser`, `models`, `enums` entrypoints |
|
||||
| Type-safe query fragments | `Prisma.validator()` | TypeScript `satisfies` |
|
||||
| Middleware | `$use()` | Client Extensions |
|
||||
| Metrics | Preview feature | Removed |
|
||||
|
||||
## Rule Files
|
||||
|
||||
Detailed migration guides for each breaking change:
|
||||
|
||||
```
|
||||
references/esm-support.md - ESM and CommonJS configuration
|
||||
references/schema-changes.md - Generator, output, imports, and generated entrypoints
|
||||
references/driver-adapters.md - Required driver adapter setup
|
||||
references/prisma-config.md - New configuration file
|
||||
references/env-variables.md - Environment variable loading
|
||||
references/removed-features.md - Middleware, metrics, and CLI flags
|
||||
references/accelerate-users.md - Special handling for Accelerate
|
||||
```
|
||||
|
||||
## Step-by-Step Migration
|
||||
|
||||
### 1. Update package.json for ESM-first projects
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "module"
|
||||
}
|
||||
```
|
||||
|
||||
If you need to stay on CommonJS, keep your app as CJS and set `moduleFormat = "cjs"` in the generator block instead of forcing ESM.
|
||||
|
||||
### 2. Update tsconfig.json
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "bundler",
|
||||
"target": "ES2023",
|
||||
"strict": true,
|
||||
"esModuleInterop": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Update schema.prisma
|
||||
|
||||
```prisma
|
||||
// Before (v6)
|
||||
generator client {
|
||||
provider = "prisma-client-js"
|
||||
}
|
||||
|
||||
// After (v7)
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated/prisma"
|
||||
// Optional if you need CommonJS:
|
||||
// moduleFormat = "cjs"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Create prisma.config.ts
|
||||
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
schema: 'prisma/schema.prisma',
|
||||
migrations: {
|
||||
path: 'prisma/migrations',
|
||||
},
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### 5. Install a driver adapter (SQL providers only)
|
||||
|
||||
```bash
|
||||
# PostgreSQL
|
||||
npm install @prisma/adapter-pg pg
|
||||
|
||||
# MySQL
|
||||
npm install @prisma/adapter-mariadb mariadb
|
||||
|
||||
# SQLite
|
||||
npm install @prisma/adapter-better-sqlite3 better-sqlite3
|
||||
|
||||
# Prisma Postgres in standard Node.js apps (recommended)
|
||||
npm install @prisma/adapter-pg pg
|
||||
|
||||
# Prisma Postgres serverless driver (edge/serverless)
|
||||
npm install @prisma/adapter-ppg @prisma/ppg
|
||||
|
||||
# Neon
|
||||
npm install @prisma/adapter-neon
|
||||
```
|
||||
|
||||
MongoDB does not have a SQL `@prisma/adapter-*` package in the published Prisma 7.6.0 packages. If you're upgrading a MongoDB project, stop and keep that project on the latest Prisma 6.x release instead of following the standard Prisma 7 migration path.
|
||||
|
||||
### 6. Update client instantiation
|
||||
|
||||
```typescript
|
||||
// Before (v6)
|
||||
import { PrismaClient } from '@prisma/client'
|
||||
const prisma = new PrismaClient()
|
||||
|
||||
// After (v7)
|
||||
import { PrismaClient } from '../generated/prisma/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
### 7. Replace Prisma.validator with satisfies
|
||||
|
||||
```typescript
|
||||
import { Prisma } from '../generated/prisma/client'
|
||||
|
||||
const userSelect = {
|
||||
id: true,
|
||||
email: true,
|
||||
name: true,
|
||||
} satisfies Prisma.UserSelect
|
||||
```
|
||||
|
||||
### 8. Run migrations and generate
|
||||
|
||||
```bash
|
||||
npx prisma generate
|
||||
npx prisma migrate dev # if needed
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Cannot find module" errors
|
||||
- Check that the generator `output` path matches your import path
|
||||
- Ensure `prisma generate` ran successfully
|
||||
|
||||
### SSL certificate errors
|
||||
- Add `ssl: { rejectUnauthorized: false }` to the adapter config if you need to preserve old behavior
|
||||
- Or configure your certificates properly with `NODE_EXTRA_CA_CERTS` / OpenSSL CA settings
|
||||
|
||||
### Connection timeout issues
|
||||
- Driver adapters use the underlying driver's defaults, which differ from v6
|
||||
- Configure pool settings explicitly on the adapter if needed
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official v7 Upgrade Guide](https://www.prisma.io/docs/orm/more/upgrades/to-v7)
|
||||
- [Driver Adapters Documentation](https://www.prisma.io/docs/orm/core-concepts/supported-databases/database-drivers)
|
||||
- [Prisma Config Reference](https://www.prisma.io/docs/orm/reference/prisma-config-reference)
|
||||
|
||||
## How to Use
|
||||
|
||||
Follow `references/schema-changes.md` and `references/driver-adapters.md` first, then apply the remaining reference files based on your project setup.
|
||||
@@ -1,151 +0,0 @@
|
||||
# Prisma Accelerate Users
|
||||
|
||||
Special migration instructions for users of Prisma Accelerate or Prisma Postgres with `prisma://` or `prisma+postgres://` URLs.
|
||||
|
||||
## Important
|
||||
|
||||
**Do NOT pass Accelerate URLs to driver adapters.**
|
||||
|
||||
Driver adapters (like `PrismaPg`) expect direct database connection strings. They will fail with `prisma://` or `prisma+postgres://` URLs.
|
||||
|
||||
## Correct v7 Setup for Accelerate
|
||||
|
||||
### 1. Keep your Accelerate URL
|
||||
|
||||
```env
|
||||
# .env
|
||||
DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=..."
|
||||
# or
|
||||
DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/..."
|
||||
```
|
||||
|
||||
### 2. Install Accelerate extension
|
||||
|
||||
```bash
|
||||
npm install @prisma/extension-accelerate
|
||||
```
|
||||
|
||||
### 3. Configure prisma.config.ts
|
||||
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
schema: 'prisma/schema.prisma',
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'), // Accelerate URL works here
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### 4. Instantiate client with accelerateUrl
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { withAccelerate } from '@prisma/extension-accelerate'
|
||||
|
||||
// Use accelerateUrl instead of adapter
|
||||
export const prisma = new PrismaClient({
|
||||
accelerateUrl: process.env.DATABASE_URL,
|
||||
}).$extends(withAccelerate())
|
||||
```
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG - Don't use adapter with Accelerate URL
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL // This will fail with prisma://
|
||||
})
|
||||
```
|
||||
|
||||
## Migrations with Accelerate
|
||||
|
||||
For migrations, you may need a direct database connection:
|
||||
|
||||
### Option 1: Use Accelerate URL for everything
|
||||
|
||||
Accelerate URLs work with Prisma CLI commands:
|
||||
|
||||
```bash
|
||||
# Works with Accelerate URL
|
||||
prisma migrate deploy
|
||||
prisma db push
|
||||
```
|
||||
|
||||
### Option 2: Use direct URL for migrations
|
||||
|
||||
```env
|
||||
DATABASE_URL="prisma+postgres://..." # For app
|
||||
DIRECT_DATABASE_URL="postgresql://..." # For migrations
|
||||
```
|
||||
|
||||
```typescript
|
||||
// prisma.config.ts
|
||||
export default defineConfig({
|
||||
datasource: {
|
||||
url: env('DIRECT_DATABASE_URL'), // Direct URL for CLI
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Prisma Postgres (Cloud)
|
||||
|
||||
If using Prisma Postgres cloud database:
|
||||
|
||||
### Same approach
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { withAccelerate } from '@prisma/extension-accelerate'
|
||||
|
||||
export const prisma = new PrismaClient({
|
||||
accelerateUrl: process.env.DATABASE_URL, // prisma+postgres:// URL
|
||||
}).$extends(withAccelerate())
|
||||
```
|
||||
|
||||
## Switching Away from Accelerate
|
||||
|
||||
If you later switch to direct TCP connection:
|
||||
|
||||
```typescript
|
||||
// Change from accelerateUrl to adapter
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL // Direct postgres:// URL
|
||||
})
|
||||
|
||||
export const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
## Caching with Accelerate
|
||||
|
||||
The extension enables caching:
|
||||
|
||||
```typescript
|
||||
const users = await prisma.user.findMany({
|
||||
cacheStrategy: {
|
||||
ttl: 60, // Cache for 60 seconds
|
||||
swr: 120, // Stale-while-revalidate for 120 seconds
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Edge Runtime
|
||||
|
||||
Accelerate works great in edge runtimes:
|
||||
|
||||
```typescript
|
||||
// Works in Vercel Edge, Cloudflare Workers, etc.
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { withAccelerate } from '@prisma/extension-accelerate'
|
||||
|
||||
export const prisma = new PrismaClient({
|
||||
accelerateUrl: process.env.DATABASE_URL,
|
||||
}).$extends(withAccelerate())
|
||||
```
|
||||
@@ -1,267 +0,0 @@
|
||||
# Driver Adapters
|
||||
|
||||
Prisma v7 requires driver adapters for SQL database connections. This is the standard SQL execution path in current Prisma releases.
|
||||
|
||||
MongoDB should not follow this path. There is no published MongoDB `@prisma/adapter-*` package, and MongoDB projects should remain on the latest Prisma 6.x release instead of trying to fit into the Prisma 7 SQL adapter model.
|
||||
|
||||
## Why Driver Adapters?
|
||||
|
||||
- No native engine binary in the Prisma Client SQL path
|
||||
- Smaller bundle size
|
||||
- Better serverless/edge compatibility
|
||||
- Uses native Node.js database drivers
|
||||
- More control over connection pooling
|
||||
|
||||
## Available Adapters
|
||||
|
||||
| Database | Adapter Package | Underlying Driver |
|
||||
|----------|-----------------|-------------------|
|
||||
| PostgreSQL | `@prisma/adapter-pg` | `pg` |
|
||||
| MySQL / MariaDB | `@prisma/adapter-mariadb` | `mariadb` |
|
||||
| SQLite | `@prisma/adapter-better-sqlite3` | `better-sqlite3` |
|
||||
| Prisma Postgres (Node.js) | `@prisma/adapter-pg` | `pg` |
|
||||
| Prisma Postgres (edge/serverless) | `@prisma/adapter-ppg` | `@prisma/ppg` |
|
||||
| SQL Server | `@prisma/adapter-mssql` | `mssql` |
|
||||
| Neon | `@prisma/adapter-neon` | `@neondatabase/serverless` |
|
||||
| PlanetScale | `@prisma/adapter-planetscale` | `@planetscale/database` |
|
||||
| Turso/libSQL | `@prisma/adapter-libsql` | `@libsql/client` |
|
||||
| D1 (Cloudflare) | `@prisma/adapter-d1` | Cloudflare D1 |
|
||||
|
||||
## Installation
|
||||
|
||||
### PostgreSQL
|
||||
|
||||
```bash
|
||||
npm install @prisma/adapter-pg
|
||||
```
|
||||
|
||||
### MySQL
|
||||
|
||||
```bash
|
||||
npm install @prisma/adapter-mariadb mariadb
|
||||
```
|
||||
|
||||
### SQLite
|
||||
|
||||
```bash
|
||||
npm install @prisma/adapter-better-sqlite3
|
||||
```
|
||||
|
||||
### Prisma Postgres
|
||||
|
||||
```bash
|
||||
npm install @prisma/adapter-pg pg
|
||||
```
|
||||
|
||||
### SQL Server
|
||||
|
||||
```bash
|
||||
npm install @prisma/adapter-mssql mssql
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### PostgreSQL
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
### MySQL
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaMariaDb } from '@prisma/adapter-mariadb'
|
||||
|
||||
const adapter = new PrismaMariaDb({
|
||||
host: 'localhost',
|
||||
port: 3306,
|
||||
connectionLimit: 5,
|
||||
user: process.env.MYSQL_USER,
|
||||
password: process.env.MYSQL_PASSWORD,
|
||||
database: process.env.MYSQL_DATABASE,
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
### SQLite
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3'
|
||||
|
||||
const adapter = new PrismaBetterSqlite3({
|
||||
url: process.env.DATABASE_URL || 'file:./dev.db'
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
### Neon (Serverless PostgreSQL)
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaNeon } from '@prisma/adapter-neon'
|
||||
|
||||
const adapter = new PrismaNeon({
|
||||
connectionString: process.env.DATABASE_URL
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
### Prisma Postgres
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL,
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
### Prisma Postgres serverless driver
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPostgresAdapter } from '@prisma/adapter-ppg'
|
||||
|
||||
const prisma = new PrismaClient({
|
||||
adapter: new PrismaPostgresAdapter({
|
||||
connectionString: process.env.PRISMA_DIRECT_TCP_URL,
|
||||
}),
|
||||
})
|
||||
```
|
||||
|
||||
### SQL Server
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaMssql } from '@prisma/adapter-mssql'
|
||||
|
||||
const adapter = new PrismaMssql({
|
||||
server: 'localhost',
|
||||
port: 1433,
|
||||
database: 'mydb',
|
||||
user: process.env.SQLSERVER_USER,
|
||||
password: process.env.SQLSERVER_PASSWORD,
|
||||
options: {
|
||||
encrypt: true,
|
||||
trustServerCertificate: true,
|
||||
},
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
## Connection Pool Configuration
|
||||
|
||||
Driver adapters use the underlying driver's pool settings, which differ from v6 defaults.
|
||||
|
||||
### PostgreSQL with custom pool
|
||||
|
||||
```typescript
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL,
|
||||
// Pool configuration
|
||||
max: 10, // Maximum connections
|
||||
idleTimeoutMillis: 30000, // Close idle connections after 30s
|
||||
connectionTimeoutMillis: 5000, // Connection timeout (v6 default was 5s)
|
||||
})
|
||||
```
|
||||
|
||||
### Matching v6 behavior
|
||||
|
||||
```typescript
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL,
|
||||
connectionTimeoutMillis: 5000, // v6 used 5 second timeout
|
||||
})
|
||||
```
|
||||
|
||||
## SSL Configuration
|
||||
|
||||
### Accept self-signed certificates
|
||||
|
||||
```typescript
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL,
|
||||
ssl: {
|
||||
rejectUnauthorized: false // Accept self-signed certs
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Proper SSL configuration
|
||||
|
||||
```typescript
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL,
|
||||
ssl: {
|
||||
ca: fs.readFileSync('/path/to/ca-cert.pem'),
|
||||
rejectUnauthorized: true
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Migration from v6
|
||||
|
||||
### Before (v6)
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '@prisma/client'
|
||||
|
||||
const prisma = new PrismaClient({
|
||||
datasources: {
|
||||
db: { url: process.env.DATABASE_URL }
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### After (v7)
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
## Singleton Pattern
|
||||
|
||||
```typescript
|
||||
// lib/prisma.ts
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const globalForPrisma = globalThis as unknown as {
|
||||
prisma: PrismaClient | undefined
|
||||
}
|
||||
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL!
|
||||
})
|
||||
|
||||
export const prisma = globalForPrisma.prisma ?? new PrismaClient({ adapter })
|
||||
|
||||
if (process.env.NODE_ENV !== 'production') {
|
||||
globalForPrisma.prisma = prisma
|
||||
}
|
||||
```
|
||||
@@ -1,161 +0,0 @@
|
||||
# Environment Variables
|
||||
|
||||
Prisma v7 no longer automatically loads environment variables. You must load them explicitly.
|
||||
|
||||
## The Change
|
||||
|
||||
### v6 Behavior
|
||||
|
||||
Prisma CLI automatically loaded `.env` files.
|
||||
|
||||
### v7 Behavior
|
||||
|
||||
You must manually load environment variables using `dotenv` or similar.
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Install dotenv
|
||||
|
||||
```bash
|
||||
npm install dotenv
|
||||
```
|
||||
|
||||
### 2. Import in prisma.config.ts
|
||||
|
||||
```typescript
|
||||
import 'dotenv/config' // Must be first import
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Bun Users
|
||||
|
||||
Bun automatically loads `.env` files. No additional setup needed:
|
||||
|
||||
```typescript
|
||||
// prisma.config.ts (Bun)
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Multiple .env Files
|
||||
|
||||
### Using dotenv-cli
|
||||
|
||||
```bash
|
||||
npm install -D dotenv-cli
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"db:migrate": "dotenv -e .env.local -- prisma migrate dev",
|
||||
"db:push": "dotenv -e .env.development -- prisma db push"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using dotenv with path
|
||||
|
||||
```typescript
|
||||
// prisma.config.ts
|
||||
import { config } from 'dotenv'
|
||||
import path from 'path'
|
||||
|
||||
// Load specific .env file
|
||||
config({ path: path.join(__dirname, '.env.local') })
|
||||
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Application Code
|
||||
|
||||
For your application, load env vars at startup:
|
||||
|
||||
### Entry point
|
||||
|
||||
```typescript
|
||||
// index.ts
|
||||
import 'dotenv/config'
|
||||
|
||||
import { PrismaClient } from '../generated/client'
|
||||
import { PrismaPg } from '@prisma/adapter-pg'
|
||||
|
||||
const adapter = new PrismaPg({
|
||||
connectionString: process.env.DATABASE_URL!
|
||||
})
|
||||
|
||||
const prisma = new PrismaClient({ adapter })
|
||||
```
|
||||
|
||||
### Or use dotenv explicitly
|
||||
|
||||
```typescript
|
||||
import { config } from 'dotenv'
|
||||
config()
|
||||
|
||||
// Now process.env.DATABASE_URL is available
|
||||
```
|
||||
|
||||
## Removed Environment Variables
|
||||
|
||||
These Prisma-specific env vars are removed in v7:
|
||||
|
||||
| Removed Variable | Alternative |
|
||||
|-----------------|-------------|
|
||||
| `PRISMA_CLI_QUERY_ENGINE_TYPE` | Not needed (no engines) |
|
||||
| `PRISMA_CLIENT_ENGINE_TYPE` | Not needed (no engines) |
|
||||
| `PRISMA_QUERY_ENGINE_BINARY` | Not needed |
|
||||
| `PRISMA_QUERY_ENGINE_LIBRARY` | Not needed |
|
||||
| `PRISMA_GENERATE_SKIP_AUTOINSTALL` | Not needed |
|
||||
| `PRISMA_SKIP_POSTINSTALL_GENERATE` | Not needed |
|
||||
| `PRISMA_GENERATE_IN_POSTINSTALL` | Not needed |
|
||||
| `PRISMA_GENERATE_DATAPROXY` | Migrate to `prisma-client` with driver adapters |
|
||||
| `PRISMA_GENERATE_NO_ENGINE` | Migrate to `prisma-client` with driver adapters |
|
||||
| `PRISMA_CLIENT_NO_RETRY` | Configure on adapter |
|
||||
| `PRISMA_MIGRATE_SKIP_GENERATE` | Not needed (auto-generate removed) |
|
||||
| `PRISMA_MIGRATE_SKIP_SEED` | Not needed (auto-seed removed) |
|
||||
|
||||
## TypeScript env() Helper
|
||||
|
||||
The `env()` function from `prisma/config` provides type safety:
|
||||
|
||||
```typescript
|
||||
import { env } from 'prisma/config'
|
||||
|
||||
// Type-safe environment variable access
|
||||
const url = env('DATABASE_URL') // string
|
||||
```
|
||||
|
||||
Note: This only works within `prisma.config.ts`, not in your application code.
|
||||
|
||||
## CI/CD Considerations
|
||||
|
||||
Ensure environment variables are set in your CI environment:
|
||||
|
||||
```yaml
|
||||
# GitHub Actions
|
||||
env:
|
||||
DATABASE_URL: ${{ secrets.DATABASE_URL }}
|
||||
|
||||
steps:
|
||||
- run: npx prisma migrate deploy
|
||||
```
|
||||
|
||||
No need for dotenv in CI if variables are set directly.
|
||||
@@ -1,128 +0,0 @@
|
||||
# ESM and CommonJS Support
|
||||
|
||||
Prisma ORM v7 is ESM-first, but the `prisma-client` generator can target either ESM or CommonJS. Use ESM by default, and opt into CommonJS with `moduleFormat = "cjs"` if your project still needs it.
|
||||
|
||||
## ESM Projects
|
||||
|
||||
Add `"type": "module"` to `package.json` and use an ESM-compatible `tsconfig.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"start": "node dist/index.js"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "bundler",
|
||||
"target": "ES2023",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"outDir": "dist"
|
||||
},
|
||||
"include": ["src/**/*", "prisma/**/*"]
|
||||
}
|
||||
```
|
||||
|
||||
## CommonJS Projects
|
||||
|
||||
If the rest of your app is still CommonJS, keep that setup and make the generated Prisma Client CommonJS too:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"module": "CommonJS",
|
||||
"moduleResolution": "node",
|
||||
"target": "ES2022",
|
||||
"esModuleInterop": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```prisma
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated/prisma"
|
||||
moduleFormat = "cjs"
|
||||
}
|
||||
```
|
||||
|
||||
## Generator Fields That Matter
|
||||
|
||||
- `moduleFormat`: `esm` or `cjs`
|
||||
- `runtime`: `nodejs`, `bun`, `deno`, `workerd`, `vercel-edge`, `react-native`
|
||||
- `generatedFileExtension`: `ts`, `mts`, or `cts`
|
||||
- `importFileExtension`: `ts`, `mts`, `cts`, `js`, `mjs`, `cjs`, or empty
|
||||
|
||||
Example:
|
||||
|
||||
```prisma
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated/prisma"
|
||||
runtime = "nodejs"
|
||||
moduleFormat = "esm"
|
||||
generatedFileExtension = "ts"
|
||||
importFileExtension = "ts"
|
||||
}
|
||||
```
|
||||
|
||||
## Import Paths
|
||||
|
||||
### Server Code
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/prisma/client'
|
||||
```
|
||||
|
||||
### Browser-Safe Types
|
||||
|
||||
```typescript
|
||||
import { Prisma } from '../generated/prisma/browser'
|
||||
import { Role } from '../generated/prisma/enums'
|
||||
import type { UserModel } from '../generated/prisma/models/User'
|
||||
```
|
||||
|
||||
## File Extensions
|
||||
|
||||
With `moduleResolution: "Node16"` or `"NodeNext"`, use `.js`/`.mjs`/`.cjs` extensions that match your emitted files.
|
||||
|
||||
With `moduleResolution: "bundler"`, bare relative imports are usually fine.
|
||||
|
||||
## Minimum Versions
|
||||
|
||||
| Requirement | Minimum Version |
|
||||
|-------------|-----------------|
|
||||
| Node.js | 20.19.0 |
|
||||
| TypeScript | 5.4.0 |
|
||||
|
||||
## Framework Considerations
|
||||
|
||||
### Next.js
|
||||
|
||||
Next.js works well with the default ESM output. If you need generated types in client components, import them from `browser`, `models`, or `enums`, not from `client`.
|
||||
|
||||
### Bun
|
||||
|
||||
Bun loads `.env` files automatically, so ESM plus `env()` is the smoothest default. You can still choose `moduleFormat = "cjs"` if the rest of your project requires it.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "ERR_REQUIRE_ESM"
|
||||
|
||||
Your generated client is ESM, but your app is requiring it as CommonJS. Either switch the project to ESM or set `moduleFormat = "cjs"` and regenerate.
|
||||
|
||||
### "Cannot use import statement outside a module"
|
||||
|
||||
Your app is still being executed as CommonJS. Add `"type": "module"` or use `moduleFormat = "cjs"` instead.
|
||||
|
||||
### TypeScript compilation errors
|
||||
|
||||
Ensure `module`, `moduleResolution`, and your generator's `moduleFormat` agree with one another.
|
||||
@@ -1,203 +0,0 @@
|
||||
# Prisma Config
|
||||
|
||||
Prisma v7 introduces `prisma.config.ts` as the central configuration file for the Prisma CLI.
|
||||
|
||||
## Location
|
||||
|
||||
Place `prisma.config.ts` at your project root (next to `package.json`).
|
||||
|
||||
## Basic Configuration
|
||||
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
schema: 'prisma/schema.prisma',
|
||||
migrations: {
|
||||
path: 'prisma/migrations',
|
||||
},
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### schema
|
||||
|
||||
Path to your Prisma schema file:
|
||||
|
||||
```typescript
|
||||
schema: 'prisma/schema.prisma'
|
||||
```
|
||||
|
||||
### datasource.url
|
||||
|
||||
Database connection URL:
|
||||
|
||||
```typescript
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
}
|
||||
```
|
||||
|
||||
### datasource.directUrl
|
||||
|
||||
Direct connection URL (bypassing connection pooler):
|
||||
|
||||
```typescript
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
directUrl: env('DIRECT_DATABASE_URL'),
|
||||
}
|
||||
```
|
||||
|
||||
### datasource.shadowDatabaseUrl
|
||||
|
||||
Shadow database for migrations:
|
||||
|
||||
```typescript
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
shadowDatabaseUrl: env('SHADOW_DATABASE_URL'),
|
||||
}
|
||||
```
|
||||
|
||||
### migrations.path
|
||||
|
||||
Directory for migration files:
|
||||
|
||||
```typescript
|
||||
migrations: {
|
||||
path: 'prisma/migrations',
|
||||
}
|
||||
```
|
||||
|
||||
### migrations.seed
|
||||
|
||||
Seed command for `prisma db seed`:
|
||||
|
||||
```typescript
|
||||
migrations: {
|
||||
path: 'prisma/migrations',
|
||||
seed: 'tsx prisma/seed.ts',
|
||||
}
|
||||
```
|
||||
|
||||
## Full Example
|
||||
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
// Schema location
|
||||
schema: 'prisma/schema.prisma',
|
||||
|
||||
// Migration configuration
|
||||
migrations: {
|
||||
path: 'prisma/migrations',
|
||||
seed: 'tsx prisma/seed.ts',
|
||||
},
|
||||
|
||||
// Database connection
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
directUrl: env('DIRECT_DATABASE_URL'),
|
||||
shadowDatabaseUrl: env('SHADOW_DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### The env() helper
|
||||
|
||||
Use `env()` to reference environment variables:
|
||||
|
||||
```typescript
|
||||
import { env } from 'prisma/config'
|
||||
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
}
|
||||
```
|
||||
|
||||
This provides type safety but does NOT load .env files automatically.
|
||||
|
||||
### Loading .env files
|
||||
|
||||
Install and import dotenv:
|
||||
|
||||
```bash
|
||||
npm install dotenv
|
||||
```
|
||||
|
||||
```typescript
|
||||
import 'dotenv/config' // Must be first import
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
```
|
||||
|
||||
## Migrating from v6
|
||||
|
||||
### Before (v6) - schema.prisma
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
url = env("DATABASE_URL")
|
||||
directUrl = env("DIRECT_URL")
|
||||
}
|
||||
```
|
||||
|
||||
### After (v7) - prisma.config.ts
|
||||
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
|
||||
export default defineConfig({
|
||||
schema: 'prisma/schema.prisma',
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
directUrl: env('DIRECT_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
And update schema.prisma:
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
// URLs now in prisma.config.ts
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Config Path
|
||||
|
||||
Use `--config` flag with CLI commands:
|
||||
|
||||
```bash
|
||||
prisma migrate dev --config ./config/prisma.config.ts
|
||||
```
|
||||
|
||||
## Monorepo Configuration
|
||||
|
||||
```typescript
|
||||
import 'dotenv/config'
|
||||
import { defineConfig, env } from 'prisma/config'
|
||||
import path from 'path'
|
||||
|
||||
export default defineConfig({
|
||||
schema: path.join(__dirname, 'packages/database/prisma/schema.prisma'),
|
||||
migrations: {
|
||||
path: path.join(__dirname, 'packages/database/prisma/migrations'),
|
||||
},
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
@@ -1,230 +0,0 @@
|
||||
# Removed Features
|
||||
|
||||
Several features have been removed in Prisma v7. Here's how to migrate.
|
||||
|
||||
## Client Middleware
|
||||
|
||||
### Removed
|
||||
|
||||
```typescript
|
||||
// ❌ No longer works in v7
|
||||
prisma.$use(async (params, next) => {
|
||||
const before = Date.now()
|
||||
const result = await next(params)
|
||||
const after = Date.now()
|
||||
console.log(`Query took ${after - before}ms`)
|
||||
return result
|
||||
})
|
||||
```
|
||||
|
||||
### Use Client Extensions Instead
|
||||
|
||||
```typescript
|
||||
// ✅ v7 approach
|
||||
const prisma = new PrismaClient({ adapter }).$extends({
|
||||
query: {
|
||||
$allModels: {
|
||||
async $allOperations({ operation, model, args, query }) {
|
||||
const before = Date.now()
|
||||
const result = await query(args)
|
||||
const after = Date.now()
|
||||
console.log(`${model}.${operation} took ${after - before}ms`)
|
||||
return result
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### Common Middleware Patterns
|
||||
|
||||
#### Soft delete
|
||||
|
||||
```typescript
|
||||
const prisma = new PrismaClient({ adapter }).$extends({
|
||||
query: {
|
||||
user: {
|
||||
async delete({ args, query }) {
|
||||
// Convert delete to soft delete
|
||||
return prisma.user.update({
|
||||
where: args.where,
|
||||
data: { deletedAt: new Date() },
|
||||
})
|
||||
},
|
||||
async findMany({ args, query }) {
|
||||
// Filter out soft-deleted records
|
||||
args.where = { ...args.where, deletedAt: null }
|
||||
return query(args)
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
#### Logging
|
||||
|
||||
```typescript
|
||||
const prisma = new PrismaClient({ adapter }).$extends({
|
||||
query: {
|
||||
$allModels: {
|
||||
async $allOperations({ operation, model, args, query }) {
|
||||
console.log(`${model}.${operation}`, JSON.stringify(args))
|
||||
return query(args)
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Metrics
|
||||
|
||||
### Removed
|
||||
|
||||
The Metrics preview feature has been removed.
|
||||
|
||||
```typescript
|
||||
// ❌ No longer works
|
||||
const metrics = await prisma.$metrics.json()
|
||||
```
|
||||
|
||||
### Alternatives
|
||||
|
||||
#### Custom counter with extensions
|
||||
|
||||
```typescript
|
||||
let totalQueries = 0
|
||||
|
||||
const prisma = new PrismaClient({ adapter }).$extends({
|
||||
client: {
|
||||
async $totalQueries() {
|
||||
return totalQueries
|
||||
},
|
||||
},
|
||||
query: {
|
||||
$allModels: {
|
||||
async $allOperations({ query, args }) {
|
||||
totalQueries += 1
|
||||
return query(args)
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
// Usage
|
||||
const count = await prisma.$totalQueries()
|
||||
```
|
||||
|
||||
#### Use driver-level metrics
|
||||
|
||||
Access metrics from the underlying driver adapter.
|
||||
|
||||
## CLI Flags Removed
|
||||
|
||||
### --skip-generate
|
||||
|
||||
Removed from `migrate dev` and `db push`.
|
||||
|
||||
```bash
|
||||
# v6
|
||||
prisma migrate dev --skip-generate
|
||||
|
||||
# v7 - generate is not run automatically
|
||||
prisma migrate dev
|
||||
prisma generate # Run explicitly if needed
|
||||
```
|
||||
|
||||
Local verification with Prisma `7.6.0` showed no generated client files emitted by `migrate dev` or `db push`, even though some CLI help text still says `migrate dev` "trigger[s] generators".
|
||||
|
||||
### --skip-seed
|
||||
|
||||
Removed from `migrate dev`. More importantly, Prisma v7 no longer auto-runs seeds during `migrate dev` or `migrate reset`, so seed explicitly when you need it.
|
||||
|
||||
```bash
|
||||
# v6
|
||||
prisma migrate dev --skip-seed
|
||||
|
||||
# v7 - seed is not run automatically
|
||||
prisma migrate dev
|
||||
prisma db seed # Run explicitly if needed
|
||||
```
|
||||
|
||||
### --schema and --url from db execute
|
||||
|
||||
```bash
|
||||
# v6
|
||||
prisma db execute --file ./script.sql --url "$DATABASE_URL"
|
||||
|
||||
# v7 - configure in prisma.config.ts
|
||||
prisma db execute --file ./script.sql
|
||||
```
|
||||
|
||||
## migrate diff Options
|
||||
|
||||
| Removed | Replacement |
|
||||
|---------|-------------|
|
||||
| `--from-url` | `--from-config-datasource` |
|
||||
| `--to-url` | `--to-config-datasource` |
|
||||
| `--from-schema-datasource` | `--from-config-datasource` |
|
||||
| `--to-schema-datasource` | `--to-config-datasource` |
|
||||
| `--shadow-database-url` | Configure in `prisma.config.ts` |
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
# v6
|
||||
prisma migrate diff --from-url "$DATABASE_URL" --to-schema schema.prisma
|
||||
|
||||
# v7
|
||||
prisma migrate diff --from-config-datasource --to-schema schema.prisma
|
||||
```
|
||||
|
||||
## Automatic Behaviors Removed
|
||||
|
||||
### Auto-generate after migrate
|
||||
|
||||
```bash
|
||||
# v7 workflow
|
||||
prisma migrate dev --name add_field
|
||||
prisma generate # Must run explicitly
|
||||
```
|
||||
|
||||
### Auto-seed after migrate
|
||||
|
||||
```bash
|
||||
# v7 workflow
|
||||
prisma migrate reset --force
|
||||
prisma db seed # Must run explicitly
|
||||
```
|
||||
|
||||
## Prisma.validator
|
||||
|
||||
The `prisma-client` generator no longer exposes `Prisma.validator`. Use TypeScript's `satisfies` operator instead.
|
||||
|
||||
```typescript
|
||||
import { Prisma } from '../generated/prisma/client'
|
||||
|
||||
const userSelect = {
|
||||
id: true,
|
||||
email: true,
|
||||
} satisfies Prisma.UserSelect
|
||||
```
|
||||
|
||||
## rejectOnNotFound
|
||||
|
||||
Removed in v5.0.0 (already deprecated).
|
||||
|
||||
```typescript
|
||||
// ❌ Removed
|
||||
const prisma = new PrismaClient({
|
||||
rejectOnNotFound: true,
|
||||
})
|
||||
|
||||
// ✅ Use OrThrow methods
|
||||
const user = await prisma.user.findUniqueOrThrow({
|
||||
where: { id: 1 },
|
||||
})
|
||||
|
||||
const user = await prisma.user.findFirstOrThrow({
|
||||
where: { email: '[email protected]' },
|
||||
})
|
||||
```
|
||||
@@ -1,164 +0,0 @@
|
||||
# Schema Changes
|
||||
|
||||
Prisma v7 promotes `prisma-client` to the default generator. Update your generator block, output path, and imports accordingly.
|
||||
|
||||
This guide is for projects that are actually migrating to Prisma 7. Do not apply these schema changes to MongoDB projects; keep those on Prisma 6.x.
|
||||
|
||||
## Generator Block (v7)
|
||||
|
||||
```prisma
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated/prisma"
|
||||
}
|
||||
```
|
||||
|
||||
## Key Changes
|
||||
|
||||
### 1. Provider name
|
||||
|
||||
Use `prisma-client` in Prisma v7. The older `prisma-client-js` generator still exists in the repo for legacy setups, but `prisma-client` is the default path for current projects.
|
||||
|
||||
### 2. Output is required
|
||||
|
||||
The `output` field is mandatory when using `prisma-client`. Prisma Client no longer generates to `node_modules` with this generator.
|
||||
|
||||
```prisma
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated/prisma"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. engineType changed
|
||||
|
||||
Legacy Rust engine settings are gone. With `prisma-client`, the relevant value is `engineType = "client"` if you want to state it explicitly, although it is typically inferred and can be omitted.
|
||||
|
||||
```prisma
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated/prisma"
|
||||
engineType = "client"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. moduleFormat is explicit when needed
|
||||
|
||||
If you must stay on CommonJS:
|
||||
|
||||
```prisma
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated/prisma"
|
||||
moduleFormat = "cjs"
|
||||
}
|
||||
```
|
||||
|
||||
## Example Output Paths
|
||||
|
||||
### Standard project
|
||||
|
||||
```prisma
|
||||
output = "../generated/prisma"
|
||||
```
|
||||
|
||||
Creates files like:
|
||||
|
||||
```text
|
||||
generated/prisma/
|
||||
client.ts
|
||||
browser.ts
|
||||
enums.ts
|
||||
models.ts
|
||||
models/
|
||||
```
|
||||
|
||||
### Monorepo
|
||||
|
||||
```prisma
|
||||
output = "../../packages/database/generated/prisma"
|
||||
```
|
||||
|
||||
### Same directory as schema
|
||||
|
||||
```prisma
|
||||
output = "./generated/prisma"
|
||||
```
|
||||
|
||||
Creates: `prisma/generated/prisma/client.ts`
|
||||
|
||||
## Datasource Block
|
||||
|
||||
The `url`, `directUrl`, and `shadowDatabaseUrl` fields in the `datasource` block are deprecated in Prisma v7. Move them to `prisma.config.ts` and keep only the provider in `schema.prisma`:
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
export default defineConfig({
|
||||
datasource: {
|
||||
url: env('DATABASE_URL'),
|
||||
directUrl: env('DIRECT_URL'),
|
||||
shadowDatabaseUrl: env('SHADOW_DATABASE_URL'),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## After Schema Changes
|
||||
|
||||
1. Run `prisma generate`:
|
||||
```bash
|
||||
npx prisma generate
|
||||
```
|
||||
|
||||
2. Update imports throughout your codebase:
|
||||
```typescript
|
||||
import { PrismaClient } from '../generated/prisma/client'
|
||||
```
|
||||
|
||||
3. Update `.gitignore` if you manage this manually:
|
||||
```
|
||||
/generated/prisma
|
||||
```
|
||||
|
||||
4. Replace `Prisma.validator()` with TypeScript `satisfies` when using `prisma-client`:
|
||||
```typescript
|
||||
import { Prisma } from '../generated/prisma/client'
|
||||
|
||||
const userSelect = {
|
||||
id: true,
|
||||
email: true,
|
||||
} satisfies Prisma.UserSelect
|
||||
```
|
||||
|
||||
## Generated Entrypoints
|
||||
|
||||
- `client` - server-side Prisma Client and Prisma namespace
|
||||
- `browser` - browser-safe types and enums without a real `PrismaClient`
|
||||
- `enums` - slim enum-only entrypoint
|
||||
- `models` - model types and derived helper types
|
||||
|
||||
## Preview Features
|
||||
|
||||
Preview features still work as before:
|
||||
|
||||
```prisma
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated/prisma"
|
||||
previewFeatures = ["relationJoins", "fullTextSearch"]
|
||||
}
|
||||
```
|
||||
|
||||
Recent preview-feature examples also include `partialIndexes` for PostgreSQL, SQLite, SQL Server, and CockroachDB:
|
||||
|
||||
```prisma
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
output = "../generated/prisma"
|
||||
previewFeatures = ["partialIndexes"]
|
||||
}
|
||||
```
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
name: remember
|
||||
description: Save a lesson, constraint, guardrail, design inspiration, or project fact into permanent .agents/ memory in the WorldWideView project. Use when the user says "remember that", "don't forget", or when a hard-won lesson should be persisted.
|
||||
---
|
||||
|
||||
@.agents/workflows/remember.md
|
||||
@@ -1,84 +0,0 @@
|
||||
---
|
||||
name: stakeholder-analysis
|
||||
description: Use when designing systems, creating features, or making architectural decisions to ensure all WorldWideView stakeholders' needs and constraints are properly considered.
|
||||
---
|
||||
|
||||
# Stakeholder Analysis & Considerations
|
||||
|
||||
## Overview
|
||||
Every architectural change, new feature, and design decision in WorldWideView affects multiple stakeholders. Before finalizing a design or starting an implementation, you MUST evaluate the impact against this list of stakeholders to ensure their specific needs, preferences, and constraints are respected.
|
||||
|
||||
## System Responsibilities & The Stakeholder Relationship
|
||||
The design of the architecture directly relates to how the stakeholders are needed and what they need. System responsibilities are detailed in this file because the strict decoupling of the architecture guarantees a level playing field across all stakeholder roles:
|
||||
|
||||
* **Data Engine**: Must operate as an independent server that complements the plugin. The data from the Data Engine is streamed directly into the plugins and used to display on the map. It can be created by anyone and hosted on their own infrastructure, remaining entirely unrelated to the Platform—acting much like a developer's proprietary API that feeds their plugins. It should not receive any preferential treatment, and should not even be explicitly acknowledged by the platform.
|
||||
* **The Platform**: Maintained strictly by the **Internal Developers** and the **Owner**. It must remain completely agnostic to which plugins are installed and must never give any plugins preferential treatment.
|
||||
* **Plugins**: Must be purely "plug-and-play". The plugins themselves contain the path and instructions on how to connect to their respective Data Engine and process the streamed data. The platform must be able to support any type of plugin developed by anyone—the original creator, the owner, an internal developer, or an external developer. It does not matter who created the plugin or whether or not they actually have access to the platform's internal codebase.
|
||||
|
||||
Because of these architectural rules, an *External Developer* has the exact same integration power and constraints as an *Internal Developer*.
|
||||
|
||||
## Stakeholders
|
||||
|
||||
### 1. Internal Developer
|
||||
* **Role**: Core team maintainers who manage the central engine, data engine, and core plugin codebase.
|
||||
* **Access**: Push access straight to `main`.
|
||||
* **Focus**: Large architectural changes, bug fixes across the entire stack (frontend, backend, data engine).
|
||||
* **Needs/Preferences**: Requires clean abstractions, maintainable code, and the ability to rapidly iterate on complex core systems without breaking downstream consumers.
|
||||
|
||||
### 2. External Developer (Contributor)
|
||||
* **Role**: Community or third-party developers contributing to the ecosystem.
|
||||
* **Access**: Pull Request (PR) access only. Never pushes directly to `main`.
|
||||
* **Focus**: Bug fixes and introducing small new features or plugins.
|
||||
* **Needs/Preferences**: Requires clear documentation, strict templates, and strong CI/CD guardrails. The system must prevent them from accidentally breaking the core engine during PR integration.
|
||||
|
||||
### 3. Plugin Developer (Simple)
|
||||
* **Role**: Users who want to quickly visualize static datasets or basic feeds with minimal effort.
|
||||
* **Focus**: Moving from an idea to a working plugin development instantly.
|
||||
* **Needs/Preferences**: Demands an absolutely frictionless, straightforward process. They want simple CLI tools (scaffolds), easy ways to host/upload data, and zero structural complexity. The barrier to entry must be as low as possible.
|
||||
|
||||
### 4. Plugin Developer (Advanced)
|
||||
* **Role**: Power users or organizations building complex integrations.
|
||||
* **Focus**: Managing their own backend servers/data pipelines, and piping real-time data directly into WWV.
|
||||
* **Needs/Preferences**: Requires high extensibility and deep access. They need the ability to manipulate the WWV frontend directly, inject custom layers, interact with the raw CesiumJS instance, and hook into the React state to build highly customized experiences.
|
||||
|
||||
### 5. The User
|
||||
Users are fragmented into sub-personas based on their engagement level and goals. Designs must cater to these overlapping but distinct segments:
|
||||
|
||||
#### Engagement Types:
|
||||
* **Casual Users (Demo)**: Just trying out the public demo. They expect an immediate visual "wow factor", zero setup, and intuitive navigation.
|
||||
* **Cloud Subscribers**: Paying customers with their own hosted WWV instance. They expect stability, secure management, and the ability to install and orchestrate their own custom ecosystem of plugins.
|
||||
|
||||
#### Operational Goals:
|
||||
* **OSINT Researchers**: Need deep filtering, real-time alerting, historical timelines, high data accuracy, and spatial intelligence tools.
|
||||
* **Data Analysts**: Require data density, aggregation, performance with massive datasets, and relational insights.
|
||||
* **Journalists**: Prioritize narrative building, visual clarity for audiences, verifiable sourcing, and ease of capturing aesthetics (screenshots/video).
|
||||
|
||||
### 6. Data Provider
|
||||
* **Role**: The source or distributor of the raw intelligence data.
|
||||
* **Types**: Third-party APIs (e.g., OpenSky), official partner organizations, or copyright holders.
|
||||
* **Needs/Preferences**:
|
||||
* Strict adherence to API rate limits, backoffs, and fair use.
|
||||
* Guaranteed data security and proper visual attribution on the globe.
|
||||
* Compliance with their Terms of Service (ToS) and usage tracking.
|
||||
|
||||
### 7. The Owner
|
||||
* **Role**: The product owner / business leader of WorldWideView.
|
||||
* **Needs/Preferences**: Cares deeply about a holistic balance. Every decision must weigh:
|
||||
* System stability, scalability, and minimizing long-term maintenance costs.
|
||||
* Rapid feature delivery and flexibility (moving fast).
|
||||
* Ecosystem growth, monetization, and attracting more plugin developers and users.
|
||||
* Maintaining a premium "wow factor" and elite visual aesthetic across all components.
|
||||
|
||||
### 8. Locally Hosted Developer/User
|
||||
* **Role**: A user or hobbyist developer running their own independent instance of WWV locally (bypassing the official managed cloud instances).
|
||||
* **Focus**: Maintaining full control, data privacy, and self-sovereignty over their intelligence environment while still accessing the community plugin registry.
|
||||
* **Needs/Preferences**:
|
||||
* Needs an extremely straightforward, lightweight setup process (e.g., pre-compiled, Dockerized releases rather than building raw source code).
|
||||
* Requires the infrastructure to seamlessly support direct CORS/WebSocket connections to external plugin servers without proxying through WWV official servers.
|
||||
* Wants the instance stripped of unnecessary development cruft (like hot-reloading tooling), but formatted in a way where they can still easily inspect the application logic if they wish to modify it.
|
||||
|
||||
## How to Use This Skill
|
||||
When tasked with system design, architectural planning, or complex feature implementation:
|
||||
1. Review this list and identify which stakeholders will be affected by your proposed changes.
|
||||
2. Explicitly detail how your design mitigates friction for the Simple Plugin Developer, protects the External Developer from breaking the platform, and satisfies the Owner's multi-faceted priorities.
|
||||
3. Validate that your approach doesn't compromise the Advanced Plugin Developer's need for deep control or the Data Provider's strict ToS requirements.
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
name: stitch-to-nextjs
|
||||
description: How to generate UI with Stitch MCP and port it robustly into Next.js
|
||||
---
|
||||
|
||||
# Stitch MCP to Next.js Workflow
|
||||
|
||||
This guide outlines the streamlined, highly-efficient process for using the Google Stitch MCP to generate web designs and successfully implement them into a Next.js application.
|
||||
|
||||
Because Stitch operates with limited context and can produce inconsistent code, this workflow heavily emphasizes the "After Checks"—the critical refinement phase where you enforce design consistency, mobile responsiveness, and accurate content.
|
||||
|
||||
## Phase 1: Generation & Validation
|
||||
|
||||
1. **Prompting Stitch**
|
||||
- Provide clear, contextual information about the project (brand identity, colors, typography).
|
||||
- **Content Injection (Crucial):** Stitch lacks full project understanding and will hallucinate false information if left to guess.
|
||||
- *Recreating an existing site:* Provide the exact content from the original page and instruct Stitch to use it verbatim.
|
||||
- *Creating a new site:* Write out all the necessary copy, headlines, and data points first, then feed that complete information to Stitch.
|
||||
- **Keep it simple:** Instruct Stitch not to overcomplicate the UI layout natively. Clean, standard layouts port easier.
|
||||
- **Image prompting:** Explicitly request *photorealistic images* rather than abstract or "AI-looking" stock photos for placeholders.
|
||||
2. **Retrieve & Validate**
|
||||
- Access the generated Stitch URL.
|
||||
- **Important:** There is no need to screen record or take photos/screenshots of the site.
|
||||
- Simply provide the generated Stitch link to the user so they can open it and review it themselves for immediate feedback. **Do not write code until the design is approved.**
|
||||
|
||||
## Phase 2: Efficient Implementation
|
||||
|
||||
1. **Extract Design Tokens First**
|
||||
- Before porting components, extract the core aesthetic from the approved Stitch page (background colors, primary/accent colors, font families, base border radii).
|
||||
- Implement these as CSS variables in `globals.css` to create a stable foundation.
|
||||
2. **Download and Port**
|
||||
- Download the raw HTML/CSS from Stitch to use as a local reference.
|
||||
- Break the HTML structure into Next.js React components (e.g., `HeroSection`, `FeaturesSection`, `Header`, `Footer`).
|
||||
- Translate inline styles or utility classes into your project's styling solution (e.g., Vanilla CSS Modules).
|
||||
|
||||
## Phase 3: The "After Checks" (Refinement & Verification)
|
||||
|
||||
Stitch focuses on visual surface area, not production-readiness. You **must** perform these post-implementation checks:
|
||||
|
||||
1. **Content & Accuracy Verification**
|
||||
- **Text:** Stitch hallucinates placeholder text. Replace all copy with coherent, accurate, and relevant information.
|
||||
- **Links & CTAs:** Ensure all buttons and navigation links route to the correct pages using Next.js `<Link>`.
|
||||
- **Footer/Header details:** Update copyright years, legal links, and brand names to reflect the actual product.
|
||||
2. **Visual Consistency & Stabilization**
|
||||
- **Icons & Logos:** Stitch uses text placeholders for icons (like "check_circle" or "diamond"). Replace these with actual SVGs or ensure the Material Symbols font is loaded in `layout.tsx`. Apply the real brand logo.
|
||||
- **Alignment:** Look out for broken flex/grid layouts. If elements overlap or fail to align evenly, manually rewrite the layout CSS to be structurally sound.
|
||||
- **Design Synchronization:** Stitch may generate inconsistent styles across different pages. It is your job to **stabilize** the design by forcing new pages to use the global design tokens established in Phase 2.
|
||||
4. **Mobile Responsiveness**
|
||||
- Stitch designs are often desktop-only.
|
||||
- Write media queries (`@media (max-width: 768px)`) for every component.
|
||||
- Implement hamburger menus for headers.
|
||||
- Force CSS Grids into single-column (`grid-template-columns: 1fr`) on mobile.
|
||||
- Adjust font sizes (`clamp()` or typography scaling) and padding for smaller viewports.
|
||||
5. **Subtle Animations & Polish**
|
||||
- Stitch designs can feel static. Add "just enough" animation to impress without overwhelming the user or hurting performance.
|
||||
- Implement simple hover states (e.g., card lifts `transform: translateY(-4px)`, interactive glows, or image transitions).
|
||||
- Consider gentle fade-in animations on scroll for major sections to make the interface feel premium and alive.
|
||||
- **Rule of thumb:** Keep interactions snappy and subtle. Avoid long, complex, or janky animations that distract from the core product story.
|
||||
|
||||
---
|
||||
|
||||
## Handling Divergent Cases & Failures
|
||||
|
||||
### Case 1: Stitch Generates Inconsistent Aesthetics Across Multiple Pages
|
||||
**The Problem:** The homepage uses one shade of dark mode, but the pricing page generates with a completely different background color and border radius.
|
||||
**The Solution:** Discard the specific CSS variables generated by the divergent page. Map its HTML structure to the centralized CSS custom properties (`var(--surface-container)`, `var(--primary)`) you established in `globals.css` during the first successful generation.
|
||||
|
||||
### Case 2: Broken Layouts or Overlapping Content
|
||||
**The Problem:** Stitch uses absolute positioning or complex margins that break when real text is inserted.
|
||||
**The Solution:** Strip out the problematic positioning CSS entirely. Replace it with modern, robust layout primitives—use `display: grid` with `gap` for alignment, and `display: flex` with `justify-content: space-between` and `height: 100%` for equal-height cards.
|
||||
|
||||
### Case 3: Missing or Broken Icons Rendering as Text
|
||||
**The Problem:** The UI shows the literal word "home" instead of a house icon.
|
||||
**The Solution:** Ensure `<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined..." rel="stylesheet">` is injected into the root HTML `<head>`.
|
||||
|
||||
### Case 4: AI Images Look Unprofessional
|
||||
**The Problem:** Stitch generated cartoonish or confusing abstract images that distract from a premium UI.
|
||||
**The Solution:** Use the `generate_image` tool independently to create photorealistic replacements, or use a reliable external service. Substitute the `src` attribute in the Next.js component.
|
||||
@@ -1,289 +0,0 @@
|
||||
---
|
||||
name: subagent-driven-development
|
||||
description: Use when executing implementation plans with independent tasks in the current session
|
||||
---
|
||||
|
||||
# Subagent-Driven Development
|
||||
|
||||
Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
|
||||
|
||||
**Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
|
||||
|
||||
**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
|
||||
|
||||
## When to Use
|
||||
|
||||
```dot
|
||||
digraph when_to_use {
|
||||
"Have implementation plan?" [shape=diamond];
|
||||
"Tasks mostly independent?" [shape=diamond];
|
||||
"Stay in this session?" [shape=diamond];
|
||||
"subagent-driven-development" [shape=box];
|
||||
"executing-plans" [shape=box];
|
||||
"Manual execution or brainstorm first" [shape=box];
|
||||
|
||||
"Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
|
||||
"Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
|
||||
"Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
|
||||
"Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
|
||||
"Stay in this session?" -> "subagent-driven-development" [label="yes"];
|
||||
"Stay in this session?" -> "executing-plans" [label="no - parallel session"];
|
||||
}
|
||||
```
|
||||
|
||||
**vs. Executing Plans (parallel session):**
|
||||
- Same session (no context switch)
|
||||
- Fresh subagent per task (no context pollution)
|
||||
- Two-stage review after each task: spec compliance first, then code quality
|
||||
- Faster iteration (no human-in-loop between tasks)
|
||||
|
||||
## The Process
|
||||
|
||||
```dot
|
||||
digraph process {
|
||||
rankdir=TB;
|
||||
|
||||
subgraph cluster_per_task {
|
||||
label="Per Task";
|
||||
"Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
|
||||
"Implementer subagent asks questions?" [shape=diamond];
|
||||
"Answer questions, provide context" [shape=box];
|
||||
"Implementer subagent implements, tests, commits, self-reviews" [shape=box];
|
||||
"Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
|
||||
"Spec reviewer subagent confirms code matches spec?" [shape=diamond];
|
||||
"Implementer subagent fixes spec gaps" [shape=box];
|
||||
"Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
|
||||
"Code quality reviewer subagent approves?" [shape=diamond];
|
||||
"Implementer subagent fixes quality issues" [shape=box];
|
||||
"Mark task complete in TodoWrite" [shape=box];
|
||||
}
|
||||
|
||||
"Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
|
||||
"More tasks remain?" [shape=diamond];
|
||||
"Dispatch final code reviewer subagent for entire implementation" [shape=box];
|
||||
"Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
|
||||
|
||||
"Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
|
||||
"Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
|
||||
"Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
|
||||
"Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
|
||||
"Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
|
||||
"Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
|
||||
"Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
|
||||
"Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
|
||||
"Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
|
||||
"Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
|
||||
"Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
|
||||
"Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
|
||||
"Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
|
||||
"Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
|
||||
"Mark task complete in TodoWrite" -> "More tasks remain?";
|
||||
"More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
|
||||
"More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
|
||||
"Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
|
||||
}
|
||||
```
|
||||
|
||||
## Model Selection
|
||||
|
||||
Use the least powerful model that can handle each role to conserve cost and increase speed.
|
||||
|
||||
**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
|
||||
|
||||
**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
|
||||
|
||||
**Architecture, design, and review tasks**: use the most capable available model.
|
||||
|
||||
**Task complexity signals:**
|
||||
- Touches 1-2 files with a complete spec → cheap model
|
||||
- Touches multiple files with integration concerns → standard model
|
||||
- Requires design judgment or broad codebase understanding → most capable model
|
||||
|
||||
## Handling Implementer Status
|
||||
|
||||
Implementer subagents report one of four statuses. Handle each appropriately:
|
||||
|
||||
**DONE:** Proceed to spec compliance review.
|
||||
|
||||
**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
|
||||
|
||||
**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
|
||||
|
||||
**BLOCKED:** The implementer cannot complete the task. Assess the blocker:
|
||||
1. If it's a context problem, provide more context and re-dispatch with the same model
|
||||
2. If the task requires more reasoning, re-dispatch with a more capable model
|
||||
3. If the task is too large, break it into smaller pieces
|
||||
4. If the plan itself is wrong, escalate to the human
|
||||
|
||||
**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
|
||||
|
||||
## Prompt Templates
|
||||
|
||||
- `./implementer-prompt.md` - Dispatch implementer subagent
|
||||
- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
|
||||
- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```
|
||||
You: I'm using Subagent-Driven Development to execute this plan.
|
||||
|
||||
[Read plan file once: docs/superpowers/plans/feature-plan.md]
|
||||
[Extract all 5 tasks with full text and context]
|
||||
[Create TodoWrite with all tasks]
|
||||
|
||||
Task 1: Hook installation script
|
||||
|
||||
[Get Task 1 text and context (already extracted)]
|
||||
[Dispatch implementation subagent with full task text + context]
|
||||
|
||||
Implementer: "Before I begin - should the hook be installed at user or system level?"
|
||||
|
||||
You: "User level (~/.config/superpowers/hooks/)"
|
||||
|
||||
Implementer: "Got it. Implementing now..."
|
||||
[Later] Implementer:
|
||||
- Implemented install-hook command
|
||||
- Added tests, 5/5 passing
|
||||
- Self-review: Found I missed --force flag, added it
|
||||
- Committed
|
||||
|
||||
[Dispatch spec compliance reviewer]
|
||||
Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra
|
||||
|
||||
[Get git SHAs, dispatch code quality reviewer]
|
||||
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
|
||||
|
||||
[Mark Task 1 complete]
|
||||
|
||||
Task 2: Recovery modes
|
||||
|
||||
[Get Task 2 text and context (already extracted)]
|
||||
[Dispatch implementation subagent with full task text + context]
|
||||
|
||||
Implementer: [No questions, proceeds]
|
||||
Implementer:
|
||||
- Added verify/repair modes
|
||||
- 8/8 tests passing
|
||||
- Self-review: All good
|
||||
- Committed
|
||||
|
||||
[Dispatch spec compliance reviewer]
|
||||
Spec reviewer: ❌ Issues:
|
||||
- Missing: Progress reporting (spec says "report every 100 items")
|
||||
- Extra: Added --json flag (not requested)
|
||||
|
||||
[Implementer fixes issues]
|
||||
Implementer: Removed --json flag, added progress reporting
|
||||
|
||||
[Spec reviewer reviews again]
|
||||
Spec reviewer: ✅ Spec compliant now
|
||||
|
||||
[Dispatch code quality reviewer]
|
||||
Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
|
||||
|
||||
[Implementer fixes]
|
||||
Implementer: Extracted PROGRESS_INTERVAL constant
|
||||
|
||||
[Code reviewer reviews again]
|
||||
Code reviewer: ✅ Approved
|
||||
|
||||
[Mark Task 2 complete]
|
||||
|
||||
...
|
||||
|
||||
[After all tasks]
|
||||
[Dispatch final code-reviewer]
|
||||
Final reviewer: All requirements met, ready to merge
|
||||
|
||||
Done!
|
||||
```
|
||||
|
||||
## Advantages
|
||||
|
||||
**vs. Manual execution:**
|
||||
- Subagents follow TDD naturally
|
||||
- Fresh context per task (no confusion)
|
||||
- Parallel-safe (subagents don't interfere)
|
||||
- Subagent can ask questions (before AND during work)
|
||||
|
||||
**vs. Executing Plans:**
|
||||
- Same session (no handoff)
|
||||
- Continuous progress (no waiting)
|
||||
- Review checkpoints automatic
|
||||
|
||||
**Efficiency gains:**
|
||||
- No file reading overhead (controller provides full text)
|
||||
- Controller curates exactly what context is needed
|
||||
- Subagent gets complete information upfront
|
||||
- Questions surfaced before work begins (not after)
|
||||
|
||||
**Quality gates:**
|
||||
- Self-review catches issues before handoff
|
||||
- Two-stage review: spec compliance, then code quality
|
||||
- Review loops ensure fixes actually work
|
||||
- Spec compliance prevents over/under-building
|
||||
- Code quality ensures implementation is well-built
|
||||
|
||||
**Cost:**
|
||||
- More subagent invocations (implementer + 2 reviewers per task)
|
||||
- Controller does more prep work (extracting all tasks upfront)
|
||||
- Review loops add iterations
|
||||
- But catches issues early (cheaper than debugging later)
|
||||
|
||||
## Red Flags
|
||||
|
||||
**Never:**
|
||||
- Start implementation on main/master branch without explicit user consent
|
||||
- Skip reviews (spec compliance OR code quality)
|
||||
- Proceed with unfixed issues
|
||||
- Dispatch multiple implementation subagents in parallel (conflicts)
|
||||
- Make subagent read plan file (provide full text instead)
|
||||
- Skip scene-setting context (subagent needs to understand where task fits)
|
||||
- Ignore subagent questions (answer before letting them proceed)
|
||||
- Accept "close enough" on spec compliance (spec reviewer found issues = not done)
|
||||
- Skip review loops (reviewer found issues = implementer fixes = review again)
|
||||
- Let implementer self-review replace actual review (both are needed)
|
||||
- **Start code quality review before spec compliance is ✅** (wrong order)
|
||||
- Move to next task while either review has open issues
|
||||
|
||||
**If subagent asks questions:**
|
||||
- Answer clearly and completely
|
||||
- Provide additional context if needed
|
||||
- Don't rush them into implementation
|
||||
|
||||
**If reviewer finds issues:**
|
||||
- Implementer (same subagent) fixes them
|
||||
- Reviewer reviews again
|
||||
- Repeat until approved
|
||||
- Don't skip the re-review
|
||||
|
||||
**If subagent fails task:**
|
||||
- Dispatch fix subagent with specific instructions
|
||||
- Don't try to fix manually (context pollution)
|
||||
|
||||
## Antigravity CLI Orchestration
|
||||
|
||||
As Antigravity (running directly in the IDE with terminal tools), **you can fully automate this entire process**.
|
||||
You do not need to wait for the human to dispatch the subagents. Instead:
|
||||
|
||||
1. **Dispatch:** Use your `run_command` tool to spawn the Gemini CLI subagents as background processes (e.g. `cat task.md | gemini -p .agents/skills/subagent-driven-development/implementer-prompt.md`).
|
||||
2. **Monitor:** Use your `command_status` and `send_command_input` tools to actively monitor the subagent's standard output.
|
||||
3. **Review Loop:** Once a background command finishes, immediately read the output/diffs and dispatch the reviewer subagent scripts via the CLI.
|
||||
4. **Manage:** If a subagent reports a blocker or asks a question in stdout, you read it via `command_status`, provide the context, and re-dispatch.
|
||||
|
||||
**You act as the fully autonomous Manager**, watching the terminal logs while the CLI subagents mechanically burn through the tasks.
|
||||
|
||||
## Integration
|
||||
|
||||
**Required workflow skills:**
|
||||
- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
|
||||
- **superpowers:writing-plans** - Creates the plan this skill executes
|
||||
- **superpowers:requesting-code-review** - Code review template for reviewer subagents
|
||||
- **superpowers:finishing-a-development-branch** - Complete development after all tasks
|
||||
|
||||
**Subagents should use:**
|
||||
- **superpowers:test-driven-development** - Subagents follow TDD for each task
|
||||
|
||||
**Alternative workflow:**
|
||||
- **superpowers:executing-plans** - Use for parallel session instead of same-session execution
|
||||
@@ -1,26 +0,0 @@
|
||||
# Code Quality Reviewer Prompt Template
|
||||
|
||||
Use this template when dispatching a code quality reviewer subagent.
|
||||
|
||||
**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
|
||||
|
||||
**Only dispatch after spec compliance review passes.**
|
||||
|
||||
```
|
||||
Task tool (superpowers:code-reviewer):
|
||||
Use template at requesting-code-review/code-reviewer.md
|
||||
|
||||
WHAT_WAS_IMPLEMENTED: [from implementer's report]
|
||||
PLAN_OR_REQUIREMENTS: Task N from [plan-file]
|
||||
BASE_SHA: [commit before task]
|
||||
HEAD_SHA: [current commit]
|
||||
DESCRIPTION: [task summary]
|
||||
```
|
||||
|
||||
**In addition to standard code quality concerns, the reviewer should check:**
|
||||
- Does each file have one clear responsibility with a well-defined interface?
|
||||
- Are units decomposed so they can be understood and tested independently?
|
||||
- Is the implementation following the file structure from the plan?
|
||||
- Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)
|
||||
|
||||
**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment
|
||||
@@ -1,116 +0,0 @@
|
||||
# Implementer Subagent Prompt Template
|
||||
|
||||
Use this template when dispatching an implementer subagent.
|
||||
|
||||
```
|
||||
Task tool (general-purpose):
|
||||
description: "Implement Task N: [task name]"
|
||||
prompt: |
|
||||
You are implementing Task N: [task name]
|
||||
|
||||
## Task Description
|
||||
|
||||
[FULL TEXT of task from plan - paste it here, don't make subagent read file]
|
||||
|
||||
## Context
|
||||
|
||||
[Scene-setting: where this fits, dependencies, architectural context]
|
||||
|
||||
## Before You Begin
|
||||
|
||||
If you have questions about:
|
||||
- The requirements or acceptance criteria
|
||||
- The approach or implementation strategy
|
||||
- Dependencies or assumptions
|
||||
- Anything unclear in the task description
|
||||
|
||||
**Ask them now.** Raise any concerns before starting work.
|
||||
|
||||
## Your Job
|
||||
|
||||
Once you're clear on requirements:
|
||||
1. Implement exactly what the task specifies
|
||||
2. Write tests (following TDD if task says to)
|
||||
3. Verify implementation works
|
||||
4. Commit your work
|
||||
5. Self-review (see below)
|
||||
6. Report back
|
||||
|
||||
Work from: [directory]
|
||||
|
||||
**While you work:** If you encounter something unexpected or unclear, **ask questions**.
|
||||
It's always OK to pause and clarify. Don't guess or make assumptions.
|
||||
|
||||
## Code Organization
|
||||
|
||||
You reason best about code you can hold in context at once, and your edits are more
|
||||
reliable when files are focused. Keep this in mind:
|
||||
- Follow the file structure defined in the plan
|
||||
- Each file should have one clear responsibility with a well-defined interface
|
||||
- If a file you're creating is growing beyond the plan's intent, stop and report
|
||||
it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
|
||||
- If an existing file you're modifying is already large or tangled, work carefully
|
||||
and note it as a concern in your report
|
||||
- In existing codebases, follow established patterns. Improve code you're touching
|
||||
the way a good developer would, but don't restructure things outside your task.
|
||||
|
||||
## When You're in Over Your Head
|
||||
|
||||
It is always OK to stop and say "this is too hard for me." Bad work is worse than
|
||||
no work. You will not be penalized for escalating.
|
||||
|
||||
**STOP and escalate when:**
|
||||
- The task requires architectural decisions with multiple valid approaches
|
||||
- You need to understand code beyond what was provided and can't find clarity
|
||||
- You feel uncertain about whether your approach is correct
|
||||
- The task involves restructuring existing code in ways the plan didn't anticipate
|
||||
- You've been reading file after file trying to understand the system without progress
|
||||
|
||||
**How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
|
||||
specifically what you're stuck on, what you've tried, and what kind of help you need.
|
||||
The controller can provide more context, re-dispatch with a more capable model,
|
||||
or break the task into smaller pieces.
|
||||
|
||||
## Before Reporting Back: Self-Review
|
||||
|
||||
Review your work with fresh eyes. Ask yourself:
|
||||
|
||||
**Completeness:**
|
||||
- Did I fully implement everything in the spec?
|
||||
- Did I miss any requirements?
|
||||
- Are there edge cases I didn't handle?
|
||||
|
||||
**Quality:**
|
||||
- Is this my best work?
|
||||
- Are names clear and accurate (match what things do, not how they work)?
|
||||
- Is the code clean and maintainable?
|
||||
|
||||
**Discipline:**
|
||||
- Did I avoid overbuilding (YAGNI)?
|
||||
- Did I only build what was requested?
|
||||
- Did I follow existing patterns in the codebase?
|
||||
|
||||
**Testing:**
|
||||
- Do tests actually verify behavior (not just mock behavior)?
|
||||
- Did I follow TDD if required?
|
||||
- Are tests comprehensive?
|
||||
|
||||
If you find issues during self-review, fix them now before reporting.
|
||||
|
||||
## Report Format
|
||||
|
||||
When done, report:
|
||||
- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
|
||||
- What you implemented (or what you attempted, if blocked)
|
||||
- What you tested and test results
|
||||
- Files changed
|
||||
- Self-review findings (if any)
|
||||
- Any issues or concerns
|
||||
|
||||
Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
|
||||
Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
|
||||
information that wasn't provided. Never silently produce work you're unsure about.
|
||||
```
|
||||
## Skills
|
||||
You have access to the following skills in `C:\Users\silve\.agents\skills`: [list of skills]. You can use the `view_file` tool to read the `SKILL.md` file in any of these directories to learn how to do things.
|
||||
|
||||
@@ -1,61 +0,0 @@
|
||||
# Spec Compliance Reviewer Prompt Template
|
||||
|
||||
Use this template when dispatching a spec compliance reviewer subagent.
|
||||
|
||||
**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
|
||||
|
||||
```
|
||||
Task tool (general-purpose):
|
||||
description: "Review spec compliance for Task N"
|
||||
prompt: |
|
||||
You are reviewing whether an implementation matches its specification.
|
||||
|
||||
## What Was Requested
|
||||
|
||||
[FULL TEXT of task requirements]
|
||||
|
||||
## What Implementer Claims They Built
|
||||
|
||||
[From implementer's report]
|
||||
|
||||
## CRITICAL: Do Not Trust the Report
|
||||
|
||||
The implementer finished suspiciously quickly. Their report may be incomplete,
|
||||
inaccurate, or optimistic. You MUST verify everything independently.
|
||||
|
||||
**DO NOT:**
|
||||
- Take their word for what they implemented
|
||||
- Trust their claims about completeness
|
||||
- Accept their interpretation of requirements
|
||||
|
||||
**DO:**
|
||||
- Read the actual code they wrote
|
||||
- Compare actual implementation to requirements line by line
|
||||
- Check for missing pieces they claimed to implement
|
||||
- Look for extra features they didn't mention
|
||||
|
||||
## Your Job
|
||||
|
||||
Read the implementation code and verify:
|
||||
|
||||
**Missing requirements:**
|
||||
- Did they implement everything that was requested?
|
||||
- Are there requirements they skipped or missed?
|
||||
- Did they claim something works but didn't actually implement it?
|
||||
|
||||
**Extra/unneeded work:**
|
||||
- Did they build things that weren't requested?
|
||||
- Did they over-engineer or add unnecessary features?
|
||||
- Did they add "nice to haves" that weren't in spec?
|
||||
|
||||
**Misunderstandings:**
|
||||
- Did they interpret requirements differently than intended?
|
||||
- Did they solve the wrong problem?
|
||||
- Did they implement the right feature but wrong way?
|
||||
|
||||
**Verify by reading code, not by trusting report.**
|
||||
|
||||
Report:
|
||||
- ✅ Spec compliant (if everything matches after code inspection)
|
||||
- ❌ Issues found: [list specifically what's missing or extra, with file:line references]
|
||||
```
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
name: supabase-postgres-best-practices
|
||||
description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
|
||||
license: MIT
|
||||
metadata:
|
||||
author: supabase
|
||||
version: "1.1.1"
|
||||
organization: Supabase
|
||||
date: January 2026
|
||||
abstract: Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized by impact from critical (query performance, connection management) to incremental (advanced features). Each rule includes detailed explanations, incorrect vs. correct SQL examples, query plan analysis, and specific performance metrics to guide automated optimization and code generation.
|
||||
---
|
||||
|
||||
# Supabase Postgres Best Practices
|
||||
|
||||
Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
|
||||
|
||||
## When to Apply
|
||||
|
||||
Reference these guidelines when:
|
||||
- Writing SQL queries or designing schemas
|
||||
- Implementing indexes or query optimization
|
||||
- Reviewing database performance issues
|
||||
- Configuring connection pooling or scaling
|
||||
- Optimizing for Postgres-specific features
|
||||
- Working with Row-Level Security (RLS)
|
||||
|
||||
## Rule Categories by Priority
|
||||
|
||||
| Priority | Category | Impact | Prefix |
|
||||
|----------|----------|--------|--------|
|
||||
| 1 | Query Performance | CRITICAL | `query-` |
|
||||
| 2 | Connection Management | CRITICAL | `conn-` |
|
||||
| 3 | Security & RLS | CRITICAL | `security-` |
|
||||
| 4 | Schema Design | HIGH | `schema-` |
|
||||
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
|
||||
| 6 | Data Access Patterns | MEDIUM | `data-` |
|
||||
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
|
||||
| 8 | Advanced Features | LOW | `advanced-` |
|
||||
|
||||
## How to Use
|
||||
|
||||
Read individual rule files for detailed explanations and SQL examples:
|
||||
|
||||
```
|
||||
references/query-missing-indexes.md
|
||||
references/query-partial-indexes.md
|
||||
references/_sections.md
|
||||
```
|
||||
|
||||
Each rule file contains:
|
||||
- Brief explanation of why it matters
|
||||
- Incorrect SQL example with explanation
|
||||
- Correct SQL example with explanation
|
||||
- Optional EXPLAIN output or metrics
|
||||
- Additional context and references
|
||||
- Supabase-specific notes (when applicable)
|
||||
|
||||
## References
|
||||
|
||||
- https://www.postgresql.org/docs/current/
|
||||
- https://supabase.com/docs
|
||||
- https://wiki.postgresql.org/wiki/Performance_Optimization
|
||||
- https://supabase.com/docs/guides/database/overview
|
||||
- https://supabase.com/docs/guides/auth/row-level-security
|
||||
@@ -0,0 +1,170 @@
|
||||
# Writing Guidelines for Postgres References
|
||||
|
||||
This document provides guidelines for creating effective Postgres best
|
||||
practice references that work well with AI agents and LLMs.
|
||||
|
||||
## Key Principles
|
||||
|
||||
### 1. Concrete Transformation Patterns
|
||||
|
||||
Show exact SQL rewrites. Avoid philosophical advice.
|
||||
|
||||
**Good:** "Use `WHERE id = ANY(ARRAY[...])` instead of
|
||||
`WHERE id IN (SELECT ...)`" **Bad:** "Design good schemas"
|
||||
|
||||
### 2. Error-First Structure
|
||||
|
||||
Always show the problematic pattern first, then the solution. This trains agents
|
||||
to recognize anti-patterns.
|
||||
|
||||
```markdown
|
||||
**Incorrect (sequential queries):** [bad example]
|
||||
|
||||
**Correct (batched query):** [good example]
|
||||
```
|
||||
|
||||
### 3. Quantified Impact
|
||||
|
||||
Include specific metrics. Helps agents prioritize fixes.
|
||||
|
||||
**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1"
|
||||
**Bad:** "Faster", "Better", "More efficient"
|
||||
|
||||
### 4. Self-Contained Examples
|
||||
|
||||
Examples should be complete and runnable (or close to it). Include `CREATE TABLE`
|
||||
if context is needed.
|
||||
|
||||
```sql
|
||||
-- Include table definition when needed for clarity
|
||||
CREATE TABLE users (
|
||||
id bigint PRIMARY KEY,
|
||||
email text NOT NULL,
|
||||
deleted_at timestamptz
|
||||
);
|
||||
|
||||
-- Now show the index
|
||||
CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL;
|
||||
```
|
||||
|
||||
### 5. Semantic Naming
|
||||
|
||||
Use meaningful table/column names. Names carry intent for LLMs.
|
||||
|
||||
**Good:** `users`, `email`, `created_at`, `is_active`
|
||||
**Bad:** `table1`, `col1`, `field`, `flag`
|
||||
|
||||
---
|
||||
|
||||
## Code Example Standards
|
||||
|
||||
### SQL Formatting
|
||||
|
||||
```sql
|
||||
-- Use lowercase keywords, clear formatting
|
||||
CREATE INDEX CONCURRENTLY users_email_idx
|
||||
ON users(email)
|
||||
WHERE deleted_at IS NULL;
|
||||
|
||||
-- Not cramped or ALL CAPS
|
||||
CREATE INDEX CONCURRENTLY USERS_EMAIL_IDX ON USERS(EMAIL) WHERE DELETED_AT IS NULL;
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
- Explain _why_, not _what_
|
||||
- Highlight performance implications
|
||||
- Point out common pitfalls
|
||||
|
||||
### Language Tags
|
||||
|
||||
- `sql` - Standard SQL queries
|
||||
- `plpgsql` - Stored procedures/functions
|
||||
- `typescript` - Application code (when needed)
|
||||
- `python` - Application code (when needed)
|
||||
|
||||
---
|
||||
|
||||
## When to Include Application Code
|
||||
|
||||
**Default: SQL Only**
|
||||
|
||||
Most references should focus on pure SQL patterns. This keeps examples portable.
|
||||
|
||||
**Include Application Code When:**
|
||||
|
||||
- Connection pooling configuration
|
||||
- Transaction management in application context
|
||||
- ORM anti-patterns (N+1 in Prisma/TypeORM)
|
||||
- Prepared statement usage
|
||||
|
||||
**Format for Mixed Examples:**
|
||||
|
||||
````markdown
|
||||
**Incorrect (N+1 in application):**
|
||||
|
||||
```typescript
|
||||
for (const user of users) {
|
||||
const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [
|
||||
user.id,
|
||||
]);
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Correct (batch query):**
|
||||
|
||||
```typescript
|
||||
const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [
|
||||
userIds,
|
||||
]);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact Level Guidelines
|
||||
|
||||
| Level | Improvement | Use When |
|
||||
|-------|-------------|----------|
|
||||
| **CRITICAL** | 10-100x | Missing indexes, connection exhaustion, sequential scans on large tables |
|
||||
| **HIGH** | 5-20x | Wrong index types, poor partitioning, missing covering indexes |
|
||||
| **MEDIUM-HIGH** | 2-5x | N+1 queries, inefficient pagination, RLS optimization |
|
||||
| **MEDIUM** | 1.5-3x | Redundant indexes, query plan instability |
|
||||
| **LOW-MEDIUM** | 1.2-2x | VACUUM tuning, configuration tweaks |
|
||||
| **LOW** | Incremental | Advanced patterns, edge cases |
|
||||
|
||||
---
|
||||
|
||||
## Reference Standards
|
||||
|
||||
**Primary Sources:**
|
||||
|
||||
- Official Postgres documentation
|
||||
- Supabase documentation
|
||||
- Postgres wiki
|
||||
- Established blogs (2ndQuadrant, Crunchy Data)
|
||||
|
||||
**Format:**
|
||||
|
||||
```markdown
|
||||
Reference:
|
||||
[Postgres Indexes](https://www.postgresql.org/docs/current/indexes.html)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Review Checklist
|
||||
|
||||
Before submitting a reference:
|
||||
|
||||
- [ ] Title is clear and action-oriented
|
||||
- [ ] Impact level matches the performance gain
|
||||
- [ ] impactDescription includes quantification
|
||||
- [ ] Explanation is concise (1-2 sentences)
|
||||
- [ ] Has at least 1 **Incorrect** SQL example
|
||||
- [ ] Has at least 1 **Correct** SQL example
|
||||
- [ ] SQL uses semantic naming
|
||||
- [ ] Comments explain _why_, not _what_
|
||||
- [ ] Trade-offs mentioned if applicable
|
||||
- [ ] Reference links included
|
||||
- [ ] `pnpm test` passes
|
||||
@@ -0,0 +1,39 @@
|
||||
# Section Definitions
|
||||
|
||||
This file defines the rule categories for Postgres best practices. Rules are automatically assigned to sections based on their filename prefix.
|
||||
|
||||
Take the examples below as pure demonstrative. Replace each section with the actual rule categories for Postgres best practices.
|
||||
|
||||
---
|
||||
|
||||
## 1. Query Performance (query)
|
||||
**Impact:** CRITICAL
|
||||
**Description:** Slow queries, missing indexes, inefficient query plans. The most common source of Postgres performance issues.
|
||||
|
||||
## 2. Connection Management (conn)
|
||||
**Impact:** CRITICAL
|
||||
**Description:** Connection pooling, limits, and serverless strategies. Critical for applications with high concurrency or serverless deployments.
|
||||
|
||||
## 3. Security & RLS (security)
|
||||
**Impact:** CRITICAL
|
||||
**Description:** Row-Level Security policies, privilege management, and authentication patterns.
|
||||
|
||||
## 4. Schema Design (schema)
|
||||
**Impact:** HIGH
|
||||
**Description:** Table design, index strategies, partitioning, and data type selection. Foundation for long-term performance.
|
||||
|
||||
## 5. Concurrency & Locking (lock)
|
||||
**Impact:** MEDIUM-HIGH
|
||||
**Description:** Transaction management, isolation levels, deadlock prevention, and lock contention patterns.
|
||||
|
||||
## 6. Data Access Patterns (data)
|
||||
**Impact:** MEDIUM
|
||||
**Description:** N+1 query elimination, batch operations, cursor-based pagination, and efficient data fetching.
|
||||
|
||||
## 7. Monitoring & Diagnostics (monitor)
|
||||
**Impact:** LOW-MEDIUM
|
||||
**Description:** Using pg_stat_statements, EXPLAIN ANALYZE, metrics collection, and performance diagnostics.
|
||||
|
||||
## 8. Advanced Features (advanced)
|
||||
**Impact:** LOW
|
||||
**Description:** Full-text search, JSONB optimization, PostGIS, extensions, and advanced Postgres features.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Clear, Action-Oriented Title (e.g., "Use Partial Indexes for Filtered Queries")
|
||||
impact: MEDIUM
|
||||
impactDescription: 5-20x query speedup for filtered queries
|
||||
tags: indexes, query-optimization, performance
|
||||
---
|
||||
|
||||
## [Rule Title]
|
||||
|
||||
[1-2 sentence explanation of the problem and why it matters. Focus on performance impact.]
|
||||
|
||||
**Incorrect (describe the problem):**
|
||||
|
||||
```sql
|
||||
-- Comment explaining what makes this slow/problematic
|
||||
CREATE INDEX users_email_idx ON users(email);
|
||||
|
||||
SELECT * FROM users WHERE email = '[email protected]' AND deleted_at IS NULL;
|
||||
-- This scans deleted records unnecessarily
|
||||
```
|
||||
|
||||
**Correct (describe the solution):**
|
||||
|
||||
```sql
|
||||
-- Comment explaining why this is better
|
||||
CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL;
|
||||
|
||||
SELECT * FROM users WHERE email = '[email protected]' AND deleted_at IS NULL;
|
||||
-- Only indexes active users, 10x smaller index, faster queries
|
||||
```
|
||||
|
||||
[Optional: Additional context, edge cases, or trade-offs]
|
||||
|
||||
Reference: [Postgres Docs](https://www.postgresql.org/docs/current/)
|
||||
+55
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Use tsvector for Full-Text Search
|
||||
impact: MEDIUM
|
||||
impactDescription: 100x faster than LIKE, with ranking support
|
||||
tags: full-text-search, tsvector, gin, search
|
||||
---
|
||||
|
||||
## Use tsvector for Full-Text Search
|
||||
|
||||
LIKE with wildcards can't use indexes. Full-text search with tsvector is orders of magnitude faster.
|
||||
|
||||
**Incorrect (LIKE pattern matching):**
|
||||
|
||||
```sql
|
||||
-- Cannot use index, scans all rows
|
||||
select * from articles where content like '%postgresql%';
|
||||
|
||||
-- Case-insensitive makes it worse
|
||||
select * from articles where lower(content) like '%postgresql%';
|
||||
```
|
||||
|
||||
**Correct (full-text search with tsvector):**
|
||||
|
||||
```sql
|
||||
-- Add tsvector column and index
|
||||
alter table articles add column search_vector tsvector
|
||||
generated always as (to_tsvector('english', coalesce(title,'') || ' ' || coalesce(content,''))) stored;
|
||||
|
||||
create index articles_search_idx on articles using gin (search_vector);
|
||||
|
||||
-- Fast full-text search
|
||||
select * from articles
|
||||
where search_vector @@ to_tsquery('english', 'postgresql & performance');
|
||||
|
||||
-- With ranking
|
||||
select *, ts_rank(search_vector, query) as rank
|
||||
from articles, to_tsquery('english', 'postgresql') query
|
||||
where search_vector @@ query
|
||||
order by rank desc;
|
||||
```
|
||||
|
||||
Search multiple terms:
|
||||
|
||||
```sql
|
||||
-- AND: both terms required
|
||||
to_tsquery('postgresql & performance')
|
||||
|
||||
-- OR: either term
|
||||
to_tsquery('postgresql | mysql')
|
||||
|
||||
-- Prefix matching
|
||||
to_tsquery('post:*')
|
||||
```
|
||||
|
||||
Reference: [Full Text Search](https://supabase.com/docs/guides/database/full-text-search)
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Index JSONB Columns for Efficient Querying
|
||||
impact: MEDIUM
|
||||
impactDescription: 10-100x faster JSONB queries with proper indexing
|
||||
tags: jsonb, gin, indexes, json
|
||||
---
|
||||
|
||||
## Index JSONB Columns for Efficient Querying
|
||||
|
||||
JSONB queries without indexes scan the entire table. Use GIN indexes for containment queries.
|
||||
|
||||
**Incorrect (no index on JSONB):**
|
||||
|
||||
```sql
|
||||
create table products (
|
||||
id bigint primary key,
|
||||
attributes jsonb
|
||||
);
|
||||
|
||||
-- Full table scan for every query
|
||||
select * from products where attributes @> '{"color": "red"}';
|
||||
select * from products where attributes->>'brand' = 'Nike';
|
||||
```
|
||||
|
||||
**Correct (GIN index for JSONB):**
|
||||
|
||||
```sql
|
||||
-- GIN index for containment operators (@>, ?, ?&, ?|)
|
||||
create index products_attrs_gin on products using gin (attributes);
|
||||
|
||||
-- Now containment queries use the index
|
||||
select * from products where attributes @> '{"color": "red"}';
|
||||
|
||||
-- For specific key lookups, use expression index
|
||||
create index products_brand_idx on products ((attributes->>'brand'));
|
||||
select * from products where attributes->>'brand' = 'Nike';
|
||||
```
|
||||
|
||||
Choose the right operator class:
|
||||
|
||||
```sql
|
||||
-- jsonb_ops (default): supports all operators, larger index
|
||||
create index idx1 on products using gin (attributes);
|
||||
|
||||
-- jsonb_path_ops: only @> operator, but 2-3x smaller index
|
||||
create index idx2 on products using gin (attributes jsonb_path_ops);
|
||||
```
|
||||
|
||||
Reference: [JSONB Indexes](https://www.postgresql.org/docs/current/datatype-json.html#JSON-INDEXING)
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Configure Idle Connection Timeouts
|
||||
impact: HIGH
|
||||
impactDescription: Reclaim 30-50% of connection slots from idle clients
|
||||
tags: connections, timeout, idle, resource-management
|
||||
---
|
||||
|
||||
## Configure Idle Connection Timeouts
|
||||
|
||||
Idle connections waste resources. Configure timeouts to automatically reclaim them.
|
||||
|
||||
**Incorrect (connections held indefinitely):**
|
||||
|
||||
```sql
|
||||
-- No timeout configured
|
||||
show idle_in_transaction_session_timeout; -- 0 (disabled)
|
||||
|
||||
-- Connections stay open forever, even when idle
|
||||
select pid, state, state_change, query
|
||||
from pg_stat_activity
|
||||
where state = 'idle in transaction';
|
||||
-- Shows transactions idle for hours, holding locks
|
||||
```
|
||||
|
||||
**Correct (automatic cleanup of idle connections):**
|
||||
|
||||
```sql
|
||||
-- Terminate connections idle in transaction after 30 seconds
|
||||
alter system set idle_in_transaction_session_timeout = '30s';
|
||||
|
||||
-- Terminate completely idle connections after 10 minutes
|
||||
alter system set idle_session_timeout = '10min';
|
||||
|
||||
-- Reload configuration
|
||||
select pg_reload_conf();
|
||||
```
|
||||
|
||||
For pooled connections, configure at the pooler level:
|
||||
|
||||
```ini
|
||||
# pgbouncer.ini
|
||||
server_idle_timeout = 60
|
||||
client_idle_timeout = 300
|
||||
```
|
||||
|
||||
Reference: [Connection Timeouts](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-IDLE-IN-TRANSACTION-SESSION-TIMEOUT)
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Set Appropriate Connection Limits
|
||||
impact: CRITICAL
|
||||
impactDescription: Prevent database crashes and memory exhaustion
|
||||
tags: connections, max-connections, limits, stability
|
||||
---
|
||||
|
||||
## Set Appropriate Connection Limits
|
||||
|
||||
Too many connections exhaust memory and degrade performance. Set limits based on available resources.
|
||||
|
||||
**Incorrect (unlimited or excessive connections):**
|
||||
|
||||
```sql
|
||||
-- Default max_connections = 100, but often increased blindly
|
||||
show max_connections; -- 500 (way too high for 4GB RAM)
|
||||
|
||||
-- Each connection uses 1-3MB RAM
|
||||
-- 500 connections * 2MB = 1GB just for connections!
|
||||
-- Out of memory errors under load
|
||||
```
|
||||
|
||||
**Correct (calculate based on resources):**
|
||||
|
||||
```sql
|
||||
-- Formula: max_connections = (RAM in MB / 5MB per connection) - reserved
|
||||
-- For 4GB RAM: (4096 / 5) - 10 = ~800 theoretical max
|
||||
-- But practically, 100-200 is better for query performance
|
||||
|
||||
-- Recommended settings for 4GB RAM
|
||||
alter system set max_connections = 100;
|
||||
|
||||
-- Also set work_mem appropriately
|
||||
-- work_mem * max_connections should not exceed 25% of RAM
|
||||
alter system set work_mem = '8MB'; -- 8MB * 100 = 800MB max
|
||||
```
|
||||
|
||||
Monitor connection usage:
|
||||
|
||||
```sql
|
||||
select count(*), state from pg_stat_activity group by state;
|
||||
```
|
||||
|
||||
Reference: [Database Connections](https://supabase.com/docs/guides/platform/performance#connection-management)
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Use Connection Pooling for All Applications
|
||||
impact: CRITICAL
|
||||
impactDescription: Handle 10-100x more concurrent users
|
||||
tags: connection-pooling, pgbouncer, performance, scalability
|
||||
---
|
||||
|
||||
## Use Connection Pooling for All Applications
|
||||
|
||||
Postgres connections are expensive (1-3MB RAM each). Without pooling, applications exhaust connections under load.
|
||||
|
||||
**Incorrect (new connection per request):**
|
||||
|
||||
```sql
|
||||
-- Each request creates a new connection
|
||||
-- Application code: db.connect() per request
|
||||
-- Result: 500 concurrent users = 500 connections = crashed database
|
||||
|
||||
-- Check current connections
|
||||
select count(*) from pg_stat_activity; -- 487 connections!
|
||||
```
|
||||
|
||||
**Correct (connection pooling):**
|
||||
|
||||
```sql
|
||||
-- Use a pooler like PgBouncer between app and database
|
||||
-- Application connects to pooler, pooler reuses a small pool to Postgres
|
||||
|
||||
-- Configure pool_size based on: (CPU cores * 2) + spindle_count
|
||||
-- Example for 4 cores: pool_size = 10
|
||||
|
||||
-- Result: 500 concurrent users share 10 actual connections
|
||||
select count(*) from pg_stat_activity; -- 10 connections
|
||||
```
|
||||
|
||||
Pool modes:
|
||||
|
||||
- **Transaction mode**: connection returned after each transaction (best for most apps)
|
||||
- **Session mode**: connection held for entire session (needed for prepared statements, temp tables)
|
||||
|
||||
Reference: [Connection Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler)
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Use Prepared Statements Correctly with Pooling
|
||||
impact: HIGH
|
||||
impactDescription: Avoid prepared statement conflicts in pooled environments
|
||||
tags: prepared-statements, connection-pooling, transaction-mode
|
||||
---
|
||||
|
||||
## Use Prepared Statements Correctly with Pooling
|
||||
|
||||
Prepared statements are tied to individual database connections. In transaction-mode pooling, connections are shared, causing conflicts.
|
||||
|
||||
**Incorrect (named prepared statements with transaction pooling):**
|
||||
|
||||
```sql
|
||||
-- Named prepared statement
|
||||
prepare get_user as select * from users where id = $1;
|
||||
|
||||
-- In transaction mode pooling, next request may get different connection
|
||||
execute get_user(123);
|
||||
-- ERROR: prepared statement "get_user" does not exist
|
||||
```
|
||||
|
||||
**Correct (use unnamed statements or session mode):**
|
||||
|
||||
```sql
|
||||
-- Option 1: Use unnamed prepared statements (most ORMs do this automatically)
|
||||
-- The query is prepared and executed in a single protocol message
|
||||
|
||||
-- Option 2: Deallocate after use in transaction mode
|
||||
prepare get_user as select * from users where id = $1;
|
||||
execute get_user(123);
|
||||
deallocate get_user;
|
||||
|
||||
-- Option 3: Use session mode pooling (port 5432 vs 6543)
|
||||
-- Connection is held for entire session, prepared statements persist
|
||||
```
|
||||
|
||||
Check your driver settings:
|
||||
|
||||
```sql
|
||||
-- Many drivers use prepared statements by default
|
||||
-- Node.js pg: { prepare: false } to disable
|
||||
-- JDBC: prepareThreshold=0 to disable
|
||||
```
|
||||
|
||||
Reference: [Prepared Statements with Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pool-modes)
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Batch INSERT Statements for Bulk Data
|
||||
impact: MEDIUM
|
||||
impactDescription: 10-50x faster bulk inserts
|
||||
tags: batch, insert, bulk, performance, copy
|
||||
---
|
||||
|
||||
## Batch INSERT Statements for Bulk Data
|
||||
|
||||
Individual INSERT statements have high overhead. Batch multiple rows in single statements or use COPY.
|
||||
|
||||
**Incorrect (individual inserts):**
|
||||
|
||||
```sql
|
||||
-- Each insert is a separate transaction and round trip
|
||||
insert into events (user_id, action) values (1, 'click');
|
||||
insert into events (user_id, action) values (1, 'view');
|
||||
insert into events (user_id, action) values (2, 'click');
|
||||
-- ... 1000 more individual inserts
|
||||
|
||||
-- 1000 inserts = 1000 round trips = slow
|
||||
```
|
||||
|
||||
**Correct (batch insert):**
|
||||
|
||||
```sql
|
||||
-- Multiple rows in single statement
|
||||
insert into events (user_id, action) values
|
||||
(1, 'click'),
|
||||
(1, 'view'),
|
||||
(2, 'click'),
|
||||
-- ... up to ~1000 rows per batch
|
||||
(999, 'view');
|
||||
|
||||
-- One round trip for 1000 rows
|
||||
```
|
||||
|
||||
For large imports, use COPY:
|
||||
|
||||
```sql
|
||||
-- COPY is fastest for bulk loading
|
||||
copy events (user_id, action, created_at)
|
||||
from '/path/to/data.csv'
|
||||
with (format csv, header true);
|
||||
|
||||
-- Or from stdin in application
|
||||
copy events (user_id, action) from stdin with (format csv);
|
||||
1,click
|
||||
1,view
|
||||
2,click
|
||||
\.
|
||||
```
|
||||
|
||||
Reference: [COPY](https://www.postgresql.org/docs/current/sql-copy.html)
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Eliminate N+1 Queries with Batch Loading
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: 10-100x fewer database round trips
|
||||
tags: n-plus-one, batch, performance, queries
|
||||
---
|
||||
|
||||
## Eliminate N+1 Queries with Batch Loading
|
||||
|
||||
N+1 queries execute one query per item in a loop. Batch them into a single query using arrays or JOINs.
|
||||
|
||||
**Incorrect (N+1 queries):**
|
||||
|
||||
```sql
|
||||
-- First query: get all users
|
||||
select id from users where active = true; -- Returns 100 IDs
|
||||
|
||||
-- Then N queries, one per user
|
||||
select * from orders where user_id = 1;
|
||||
select * from orders where user_id = 2;
|
||||
select * from orders where user_id = 3;
|
||||
-- ... 97 more queries!
|
||||
|
||||
-- Total: 101 round trips to database
|
||||
```
|
||||
|
||||
**Correct (single batch query):**
|
||||
|
||||
```sql
|
||||
-- Collect IDs and query once with ANY
|
||||
select * from orders where user_id = any(array[1, 2, 3, ...]);
|
||||
|
||||
-- Or use JOIN instead of loop
|
||||
select u.id, u.name, o.*
|
||||
from users u
|
||||
left join orders o on o.user_id = u.id
|
||||
where u.active = true;
|
||||
|
||||
-- Total: 1 round trip
|
||||
```
|
||||
|
||||
Application pattern:
|
||||
|
||||
```sql
|
||||
-- Instead of looping in application code:
|
||||
-- for user in users: db.query("SELECT * FROM orders WHERE user_id = $1", user.id)
|
||||
|
||||
-- Pass array parameter:
|
||||
select * from orders where user_id = any($1::bigint[]);
|
||||
-- Application passes: [1, 2, 3, 4, 5, ...]
|
||||
```
|
||||
|
||||
Reference: [N+1 Query Problem](https://supabase.com/docs/guides/database/query-optimization)
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Use Cursor-Based Pagination Instead of OFFSET
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: Consistent O(1) performance regardless of page depth
|
||||
tags: pagination, cursor, keyset, offset, performance
|
||||
---
|
||||
|
||||
## Use Cursor-Based Pagination Instead of OFFSET
|
||||
|
||||
OFFSET-based pagination scans all skipped rows, getting slower on deeper pages. Cursor pagination is O(1).
|
||||
|
||||
**Incorrect (OFFSET pagination):**
|
||||
|
||||
```sql
|
||||
-- Page 1: scans 20 rows
|
||||
select * from products order by id limit 20 offset 0;
|
||||
|
||||
-- Page 100: scans 2000 rows to skip 1980
|
||||
select * from products order by id limit 20 offset 1980;
|
||||
|
||||
-- Page 10000: scans 200,000 rows!
|
||||
select * from products order by id limit 20 offset 199980;
|
||||
```
|
||||
|
||||
**Correct (cursor/keyset pagination):**
|
||||
|
||||
```sql
|
||||
-- Page 1: get first 20
|
||||
select * from products order by id limit 20;
|
||||
-- Application stores last_id = 20
|
||||
|
||||
-- Page 2: start after last ID
|
||||
select * from products where id > 20 order by id limit 20;
|
||||
-- Uses index, always fast regardless of page depth
|
||||
|
||||
-- Page 10000: same speed as page 1
|
||||
select * from products where id > 199980 order by id limit 20;
|
||||
```
|
||||
|
||||
For multi-column sorting:
|
||||
|
||||
```sql
|
||||
-- Cursor must include all sort columns
|
||||
select * from products
|
||||
where (created_at, id) > ('2024-01-15 10:00:00', 12345)
|
||||
order by created_at, id
|
||||
limit 20;
|
||||
```
|
||||
|
||||
Reference: [Pagination](https://supabase.com/docs/guides/database/pagination)
|
||||
Loaded 100 of 809 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user