@podosoft/podokit 0.5.0 → 0.6.0

package/dist/templates/todo/compose.dev.yaml

@@ -0,0 +1,150 @@
+# Containerized development environment.
+#
+#   docker compose -f compose.dev.yaml watch                       # core stack
+#   docker compose -f compose.dev.yaml --profile cache \
+#     --profile storage --profile queue watch                     # with modules
+#
+# Only Traefik binds a host port (80). The app is at http://app.localhost.
+# api/postgres/redis/minio have NO published ports — they talk by service name
+# on the internal network, so this stack never collides with other projects.
+#
+# Core services (traefik, web, api, postgres) always run. Module-specific
+# services are behind profiles — enable the ones your app uses:
+#   --profile cache    redis    (redis / rate-limit / bullmq modules)
+#   --profile storage  minio    (object-storage-s3 / file-upload modules)
+#   --profile queue    worker   (bullmq / job-progress modules)
+#
+# `watch` syncs your edits into the containers: the web has instant vite HMR;
+# an API source change restarts the api service (~5s), which is the stable
+# approach for nest inside a container.
+name: {{projectName}}-dev
+
+services:
+  traefik:
+    image: traefik:v3.5
+    command:
+      - --providers.file.filename=/etc/traefik/dynamic.yml
+      - --providers.file.watch=true
+      - --entrypoints.web.address=:80
+      - --api.dashboard=true
+      - --api.insecure=true
+    ports:
+      - "80:80"
+      - "127.0.0.1:8080:8080" # Traefik dashboard (dev only)
+    volumes:
+      - ./infra/traefik/dynamic.yml:/etc/traefik/dynamic.yml:ro
+    networks: [podokit]
+
+  web:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    command: npm run dev -w {{projectName}}-web -- --host 0.0.0.0
+    working_dir: /app
+    env_file: .env.docker
+    environment:
+      - VITE_DOCKER=1
+      - BACKEND_INTERNAL_URL=http://api:5002
+    depends_on: [api]
+    networks: [podokit]
+    develop:
+      watch:
+        - { action: sync, path: ./apps/web/src, target: /app/apps/web/src }
+        - { action: sync, path: ./apps/web/static, target: /app/apps/web/static }
+        - { action: sync+restart, path: ./apps/web/vite.config.ts, target: /app/apps/web/vite.config.ts }
+        - { action: rebuild, path: ./apps/web/package.json }
+
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    init: true
+    command: npm run dev -w {{projectName}}-api
+    working_dir: /app
+    env_file: .env.docker
+    depends_on:
+      postgres: { condition: service_healthy }
+    networks: [podokit]
+    develop:
+      watch:
+        # nest-cli's in-container watch does not reliably respawn the app process,
+        # so restart the service on an API source change (~5s). The Docker docs'
+        # sync+restart is the stable, recommended approach; the web keeps instant
+        # HMR via plain sync.
+        - { action: sync+restart, path: ./apps/api/src, target: /app/apps/api/src }
+        - { action: rebuild, path: ./apps/api/package.json }
+
+  worker:
+    # started only with the bullmq / job-progress modules: --profile queue
+    profiles: [queue]
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    init: true
+    command: npm run dev:worker -w {{projectName}}-api
+    working_dir: /app
+    env_file: .env.docker
+    depends_on:
+      redis: { condition: service_started }
+    networks: [podokit]
+    develop:
+      watch:
+        # nest-cli's in-container watch does not reliably respawn the app process,
+        # so restart the service on an API source change (~5s). The Docker docs'
+        # sync+restart is the stable, recommended approach; the web keeps instant
+        # HMR via plain sync.
+        - { action: sync+restart, path: ./apps/api/src, target: /app/apps/api/src }
+        - { action: rebuild, path: ./apps/api/package.json }
+
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: podokit
+      POSTGRES_PASSWORD: podokit
+      POSTGRES_DB: podokit
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U podokit"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    networks: [podokit] # no published ports — internal only
+
+  redis:
+    # started only with the redis / rate-limit / bullmq modules: --profile cache
+    profiles: [cache]
+    image: redis:7-alpine
+    networks: [podokit] # internal only
+
+  minio:
+    # started only with the object-storage-s3 / file-upload modules: --profile storage
+    profiles: [storage]
+    image: minio/minio:latest
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: podokit
+      MINIO_ROOT_PASSWORD: podokitsecret
+    volumes:
+      - miniodata:/data
+    networks: [podokit] # internal only
+
+  minio-init:
+    profiles: [storage]
+    image: minio/mc:latest
+    depends_on:
+      minio: { condition: service_started }
+    entrypoint:
+      - sh
+      - -c
+      - |
+        until mc alias set loc http://minio:9000 podokit podokitsecret; do sleep 1; done
+        mc mb -p loc/podokit || true
+    networks: [podokit]
+
+networks:
+  podokit: {}
+
+volumes:
+  pgdata: {}
+  miniodata: {}

package/dist/templates/todo/dot-claude/skills/podokit-add-module/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: podokit-add-module
+description: Use when the user wants a feature that a PodoKit module already provides (authentication, an admin dashboard, Redis, background jobs/queues, object storage, file uploads, SSE, rate limiting, logging). Prefer adding the module over hand-writing it.
+---
+
+# Add a PodoKit module
+
+Before building auth, an admin panel, queues, storage, etc. by hand, check
+whether a module provides it — modules wire themselves into the app correctly.
+
+```bash
+podo add                 # list available modules
+podo add <module>        # e.g. auth, admin-dashboard, redis, bullmq, file-upload
+npm install              # install newly-added dependencies
+```
+
+Common modules: `auth` (better-auth: email/password, sessions, OAuth, 2FA,
+secure-by-default), `admin-dashboard` (user/session/org management + audit +
+runtime settings, requires auth), `redis`, `bullmq` (queue + worker),
+`job-progress` (SSE progress), `object-storage-s3`, `file-upload`, `sse`,
+`rate-limit`, `logging`, `api-key-auth`.
+
+Notes:
+- A module auto-adds its required modules (e.g. `admin-dashboard` adds `auth`).
+- After adding, follow the printed next steps (often DB migrations, e.g.
+  `npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts`).
+- Module wiring lands inside `// podokit:` fenced regions — don't hand-edit those.

package/dist/templates/todo/dot-claude/skills/podokit-nest-endpoint/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: podokit-nest-endpoint
+description: Use when adding or changing a NestJS REST endpoint in apps/api — a controller/service with DTO validation, the standard error envelope, and a test. Follow this for any new backend route in a PodoKit project.
+---
+
+# Add a NestJS endpoint (PodoKit conventions)
+
+1. **Module**: create/extend a Nest module under `apps/api/src/<feature>/`
+   (`<feature>.module.ts`, `.controller.ts`, `.service.ts`, `dto/`). Register the
+   module in `apps/api/src/app.module.ts` — add it **inside** the
+   `// podokit:begin:module-imports … end` fence, never outside it.
+2. **DTOs**: validate every input with `class-validator` decorators on a DTO
+   class. No `any`; give explicit return types.
+3. **Errors**: throw `AppException("STABLE_CODE", "message", statusCode)` (from
+   `@podosoft/podokit-contracts` / the app's `common/`). The global filter renders
+   it as `{ success: false, error: { code, message, statusCode, path, timestamp } }`.
+   Pick a stable, UPPER_SNAKE `code` — the frontend branches on it.
+4. **Auth**: if the `auth` module is installed the API is secure by default; mark
+   public routes with `@Public()` and read the user with `@Session()`.
+5. **Swagger**: annotate with `@ApiTags` so it shows under `/api-docs`.
+6. **Test**: add an e2e/unit test under `apps/api` or the `tests/` workspace
+   (Nest e2e or Vitest + supertest). Verify with
+   `npm run build -w {{projectName}}-api` and the test.

package/dist/templates/todo/dot-claude/skills/podokit-sveltekit-route/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: podokit-sveltekit-route
+description: Use when adding or changing a SvelteKit page/route in apps/web — pages that call the API, use shadcn-svelte components, and localize text. Follow this for any new frontend screen in a PodoKit project.
+---
+
+# Add a SvelteKit route (PodoKit conventions)
+
+1. **Route**: add a folder under `apps/web/src/routes/`. Load data in
+   `+page.server.ts` / `+layout.server.ts` (SSR), not in the browser.
+2. **Call the API only through the server proxy** — never a direct browser
+   `fetch` to `:5002`. Use the app's `ApiClient`: `$lib/api.ts` (browser,
+   same-origin `/api/*` proxy) and `$lib/server/api.ts` (SSR, internal URL +
+   cookie forwarding). It throws `ApiError` — branch on `err.code`.
+3. **Svelte 5 runes only**: `$state`, `$derived`, `$effect`, `$props`. Never `$:`.
+4. **UI**: use shadcn-svelte components (`$lib/components/ui/*`) over raw HTML.
+   Do **not** edit `ui/**` — wrap it if you need to customize. Semantic Tailwind
+   classes (`bg-background`, `text-foreground`); responsive (`sm:`/`md:`/`lg:`).
+   For any list/table, use the shared `DataTable` (see the podokit-data-table
+   skill, added with the admin-dashboard module).
+5. **i18n**: no hardcoded user-facing strings — add keys to
+   `apps/web/src/lib/i18n/messages.ts` for **every** locale.
+6. **Verify**: `npm run build -w {{projectName}}-web` (includes `svelte-check`)
+   and add/adjust a Playwright test in `tests/`.

package/dist/templates/todo/dot-claude/skills/podokit-update/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: podokit-update
+description: Use when the user wants to update the project to a newer PodoKit version, pull in template/module improvements, check what they've changed vs the generated code, or take ownership of a managed file. Covers podo status/diff/doctor/update/eject.
+---
+
+# Keep a PodoKit project up to date
+
+The project records how it was assembled in `.podokit/` so the toolkit can update
+its own files while keeping the user's changes.
+
+```bash
+podo status          # version, modules, file tiers, and how many managed files were edited
+podo diff            # list the PodoKit-managed files you've edited (owned files ignored)
+podo doctor          # check framework versions vs. the supported ranges
+podo update          # dry-run: preview what a newer version would change (writes nothing)
+podo update --apply  # apply it — clean updates are written; your edits are 3-way merged
+podo eject <path>    # take ownership of a managed file so update skips it
+```
+
+Rules to respect:
+- **owned** files (routes, your components, `AGENTS.md`, shadcn `ui/**`) are never
+  touched by `update`.
+- **assembled** files are recomputed from the module set — keep edits **outside**
+  the `// podokit:begin…end` fences.
+- Run `podo update` (dry-run) first and read the plan before `--apply`. Commit or
+  stash your work beforehand so a merge is easy to review.

package/dist/templates/todo/dot-cursor/rules/podokit.mdc

@@ -0,0 +1,11 @@
+---
+description: PodoKit project conventions (stack, commands, code style, tooling)
+alwaysApply: true
+---
+
+The conventions for this project are documented in [`AGENTS.md`](../../AGENTS.md)
+at the repository root. Follow them: web runs on :5001 and api on :5002; use
+shadcn-svelte components and the shared `DataTable`/`TableToolbar` for lists;
+Svelte 5 runes only; branch on the error `code`, not the message; keep strings in
+i18n; and respect the `.podokit/` file-ownership tiers (never hand-edit
+`// podokit:` fenced regions or `src/lib/components/ui/**`).

package/dist/templates/todo/dot-devcontainer/devcontainer.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{projectName}} (containerized dev)",
+  "dockerComposeFile": ["../compose.dev.yaml"],
+  "service": "api",
+  "workspaceFolder": "/app",
+  "runServices": ["traefik", "web", "api", "worker", "postgres", "redis", "minio", "minio-init"],
+  "shutdownAction": "stopCompose",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "svelte.svelte-vscode",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "bradlc.vscode-tailwindcss"
+      ]
+    }
+  },
+  "forwardPorts": [],
+  "remoteUser": "node"
+}

package/dist/templates/todo/dot-dockerignore

@@ -0,0 +1,8 @@
+node_modules
+**/node_modules
+dist
+**/dist
+.svelte-kit
+**/.svelte-kit
+.git
+*.log

package/dist/templates/todo/dot-env.docker

@@ -0,0 +1,26 @@
+NODE_ENV=development
+PORT=5002
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+POSTGRES_USER=podokit
+POSTGRES_PASSWORD=podokit
+POSTGRES_DB=podokit
+BACKEND_INTERNAL_URL=http://api:5002
+CORS_ORIGIN=http://app.localhost
+REDIS_HOST=redis
+REDIS_PORT=6379
+BETTER_AUTH_SECRET=change-me-in-container-min-32-characters
+BETTER_AUTH_URL=http://app.localhost
+ADMIN_EMAILS=admin@example.com
+AUDIT_LOG_ENABLED=true
+RATE_LIMIT_TTL=60
+RATE_LIMIT_MAX=100
+API_KEYS=dev-key-please-change
+LOG_LEVEL=info
+STORAGE_PROVIDER=minio
+S3_ENDPOINT=http://minio:9000
+S3_REGION=us-east-1
+S3_BUCKET=podokit
+S3_ACCESS_KEY_ID=podokit
+S3_SECRET_ACCESS_KEY=podokitsecret
+S3_FORCE_PATH_STYLE=true

package/dist/templates/todo/dot-github/copilot-instructions.md

@@ -0,0 +1,6 @@
+# Copilot instructions
+
+This project's coding conventions for AI agents live in [`AGENTS.md`](../AGENTS.md).
+Read it before making changes — it covers the stack, commands (web :5001 / api
+:5002), TypeScript/Svelte 5/shadcn-svelte rules, the error-code envelope, and the
+`podo` tooling.

package/dist/templates/todo/dot-mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "podokit": {
+      "command": "npx",
+      "args": ["-y", "@podosoft/podokit-mcp"]
+    }
+  }
+}

package/dist/templates/todo/infra/traefik/dynamic.yml

@@ -0,0 +1,13 @@
+# Traefik dynamic config (file provider). Routes the browser-facing web app;
+# api/postgres/redis/minio stay internal (reached by service name).
+http:
+  routers:
+    web:
+      rule: "PathPrefix(`/`)"  # any host on this dedicated proxy -> web
+      entryPoints: [web]
+      service: web
+  services:
+    web:
+      loadBalancer:
+        servers:
+          - url: "http://web:5001"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "An opinionated but extensible starter toolkit and CLI for full-stack TypeScript apps with NestJS, SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {
@@ -20,6 +20,14 @@
   "bin": {
     "podo": "dist/index.js"
   },
+  "main": "dist/lib.js",
+  "types": "dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "default": "./dist/lib.js"
+    }
+  },
   "files": [
     "dist"
   ],