@podosoft/podokit 0.16.4 → 0.17.0

package/dist/templates/todo/dot-agents/skills/podokit-deploy-fast/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: podokit-deploy-fast
+description: Push locally built artifacts into a running Docker Compose deployment and restart it, without building or publishing an image. Use when iterating on code against a deployed environment and a full release round trip is too slow. Not for releases, migrations, dependency changes, or anything going to real users.
+---
+
+# Sync code into a running deployment
+
+`podo deploy sync` copies this project's build output into the containers that are
+already running and restarts them. `docker-compose` driver only — read the profile's
+`driver` first and stop if it is `kubernetes-helm`, where the equivalent would have
+to reach every node and would stop being a shortcut.
+
+```bash
+npx @podosoft/podokit deploy sync --profile <name> --build
+```
+
+## Say what this does before doing it
+
+It is not a release, and the user has to understand three consequences before you run
+it:
+
+1. **The deployment will run code its image tag does not describe.** A marker file
+   records the sync and `podo deploy status` reports it under `syncDrift`.
+2. **Every connection the restarted containers hold is dropped** — WebSocket sessions,
+   in-flight requests, anything attached.
+3. **It disappears on the next release.** Container writable layers do not survive
+   recreation, so `podo deploy apply` restores the image with no cleanup step. That is
+   the property that makes this safe; do not build anything that depends on the copy
+   persisting.
+
+## When NOT to use it
+
+Use a release instead — build the images and `podo deploy apply` — when any of these
+is true. The first three are refusals the command makes itself; the last two it
+cannot detect, which is why they are your job.
+
+| Situation | Why |
+| --- | --- |
+| runtime dependencies changed | the container's `node_modules` was installed `--omit=dev` from the old manifest, so the new code imports something that is not there |
+| a release holds the deployment lock | an apply is in progress |
+| nothing is running for that project | there is no container to copy into |
+| **the change needs a migration** | sync never migrates, and a migration belongs with the release whose code needs it |
+| **the change is going to real users** | nothing is pushed, so nothing is reproducible from it |
+
+## Procedure
+
+1. Read the profile's `driver`. Stop unless it is `docker-compose`.
+2. Tell the user what will restart and that connections drop. Get agreement if anyone
+   is using the deployment.
+3. Run with `--build` unless the project is already built. `--build` compiles in the
+   order the images do — every `packages/*` before the apps — because a root build
+   script runs workspaces in manifest order and an app listed first would compile
+   against a workspace package's previous output.
+4. Report what was copied, which containers restarted, and that the deployment is now
+   in sync drift.
+5. Verify against the running deployment, not against the build: request a path the
+   change affects. If part of the build output is excluded (below), check one of
+   those paths too — that is the failure this exclusion exists to prevent, and it
+   does not make the page look broken.
+
+## Restoring the image
+
+```bash
+npx @podosoft/podokit deploy sync --profile <name> --revert
+```
+
+This recreates the containers from the Compose project **already on the target**,
+which is the description of what was actually applied — not a fresh render, which
+would reproduce the profile as it is now.
+
+A release does the same thing as a side effect, so `--revert` is for abandoning a
+sync, not a required cleanup step.
+
+## Excluding part of the build output
+
+Some of a build output can come from a toolchain the developer's machine does not
+have. Overwriting that part replaces real artifacts with an index of artifacts that
+are no longer there, and the application keeps serving pages while the missing files
+404 — so nothing looks broken. Those paths belong in the profile:
+
+```json
+{ "sync": { "exclude": ["apps/web/build/static-assets/generated"] } }
+```
+
+If you find yourself about to sync over something this machine cannot rebuild, add it
+here rather than remembering not to. `--clean` refuses while an exclude sits beneath
+a synced path, for the same reason.
+
+## Boundary
+
+Never use this to ship. Never run migrations alongside it. Never create or rotate
+credentials, and never print a secret value.

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

@@ -1,6 +1,6 @@
 ---
 name: podokit-deploy
-description: Plan, inspect, apply, verify, and roll back PodoKit Kubernetes releases with an explicit profile and confirmation hash. Use for Kubernetes deployment and rollback work in a generated PodoKit project.
+description: Plan, inspect, apply, verify, and roll back PodoKit releases with an explicit profile and confirmation hash, on Kubernetes or Docker Compose. Use for release, rollout, and rollback work in a generated PodoKit project.
 ---
 
 # PodoKit deployment

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

@@ -0,0 +1,8 @@
+---
+name: podokit-deploy-fast
+description: Push locally built artifacts into a running Docker Compose deployment and restart it, without building or publishing an image. Use when iterating on code against a deployed environment and a full release round trip is too slow. Not for releases, migrations, dependency changes, or anything going to real users.
+---
+
+# PodoKit fast deployment sync
+
+Read and follow the canonical skill at `../../../.agents/skills/podokit-deploy-fast/SKILL.md`.

package/dist/templates/todo/dot-dockerignore

@@ -6,3 +6,10 @@ dist
 **/.svelte-kit
 .git
 *.log
+
+# Real environment files never enter a build context. The build stages copy the
+# whole repository, so an .env left here is baked into an image layer even when the
+# runtime stage does not copy it -- and getting-started tells you to create one.
+.env
+.env.*
+!.env.example

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

@@ -12,6 +12,13 @@ POSTGRES_DB=podokit
 
 # Web -> API boundary (server-side only; not exposed to the browser)
 BACKEND_INTERNAL_URL=http://localhost:5002
+
+# Exact paths the web server may proxy as WebSocket upgrades to the API, comma
+# separated. Empty means none: a SvelteKit route cannot answer an upgrade, so a
+# WebSocket gateway on the API is unreachable until it is named here. Each path is
+# matched whole and must be authorised by the API at handshake time -- a relay that
+# forwards anything is an open tunnel to every private route.
+WS_PROXY_PATHS=
 CORS_ORIGIN=http://localhost:5001
 
 # ── Optional / development ───────────────────────────────────────────

package/dist/templates/todo/dot-github/workflows/release.yml

@@ -0,0 +1,142 @@
+# Build and publish the release images for a tag.
+#
+# `podo deploy` consumes images; it does not build them. This is the other half:
+# tagging a commit produces the two images that `podo deploy apply` then rolls out.
+# It stops at the push, because rolling out requires confirming a plan hash and that
+# approval belongs to a person.
+#
+# ── Which runner, and what it costs ──────────────────────────────────────────────
+#
+# GitHub-hosted runners are free for PUBLIC repositories only. In a PRIVATE
+# repository every minute is metered against the account's included Actions minutes
+# and billed beyond them -- and image builds are the most expensive job most
+# projects run. A self-hosted runner consumes no Actions minutes at all, whatever
+# the repository's visibility.
+#
+# So the runner is a variable rather than a constant:
+#
+#   PODOKIT_RUNNER   repository or organization variable, a JSON array of labels.
+#                    Unset -> ["ubuntu-latest"], which is right for a public
+#                    repository and costs money in a private one.
+#                    Self-hosted example: ["self-hosted","Linux","X64"]
+#
+# Set it before the first tag if this repository is private. Nothing here warns you
+# when you have not: the workflow succeeds either way, and the difference shows up
+# on a bill.
+#
+# ── The other two variables ──────────────────────────────────────────────────────
+#
+#   PODOKIT_DEPLOY_PROFILE   which .podokit/deploy/<name>.json names the image
+#                            repositories. Unset -> production.
+#   PODOKIT_IMAGE_PLATFORM   the architecture the deployment target runs.
+#                            Unset -> linux/amd64. Building for the wrong one
+#                            produces "exec format error" at rollout, after the
+#                            migration has already run.
+#
+# ── Secrets ──────────────────────────────────────────────────────────────────────
+#
+#   REGISTRY_USERNAME / REGISTRY_PASSWORD   credentials for the registry named by
+#   the profile. A robot or deploy account is enough, but note that some registries
+#   refuse to let a robot CREATE a repository -- push the first tag of a new
+#   repository with an account that can, or create it in the registry first.
+
+name: release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  images:
+    # One job builds both images rather than a matrix of two. A self-hosted pool is
+    # usually small, and fanning out here takes runners away from every other
+    # repository that shares it for no wall-clock gain on a multi-core machine.
+    runs-on: ${{ fromJSON(vars.PODOKIT_RUNNER || '["ubuntu-latest"]') }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci --no-audit --no-fund
+
+      # Verify before publishing. An image built from a commit that never passed is
+      # indistinguishable from one that did, once it is in the registry.
+      - run: npm run lint
+      - run: npm test
+
+      - name: Read the release target from the deployment profile
+        id: profile
+        run: |
+          node --input-type=module -e '
+            import { readFileSync } from "node:fs";
+            const name = process.env.PROFILE || "production";
+            const path = `.podokit/deploy/${name}.json`;
+            let profile;
+            try {
+              profile = JSON.parse(readFileSync(path, "utf8"));
+            } catch {
+              throw new Error(`No deployment profile at ${path}. Run podo deploy init first.`);
+            }
+            const { apiRepository, webRepository } = profile.release ?? {};
+            if (!apiRepository || !webRepository) {
+              throw new Error(`${path} does not declare release.apiRepository and release.webRepository.`);
+            }
+            // Everything before the first slash is a registry host only when it
+            // looks like one; otherwise the reference is a Docker Hub short name.
+            const first = apiRepository.split("/")[0];
+            const registry = /[.:]/.test(first) ? first : "";
+            const out = [
+              `api=${apiRepository}`,
+              `web=${webRepository}`,
+              `registry=${registry}`,
+              `tag=${process.env.GITHUB_REF_NAME}`,
+            ].join("\n");
+            process.stdout.write(out + "\n");
+          ' >> "$GITHUB_OUTPUT"
+        env:
+          PROFILE: ${{ vars.PODOKIT_DEPLOY_PROFILE }}
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ steps.profile.outputs.registry }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+
+      - name: Build and push the API image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: apps/api/Dockerfile
+          platforms: ${{ vars.PODOKIT_IMAGE_PLATFORM || 'linux/amd64' }}
+          push: true
+          tags: ${{ steps.profile.outputs.api }}:${{ steps.profile.outputs.tag }}
+          cache-from: type=gha,scope=api
+          cache-to: type=gha,scope=api,mode=max
+
+      - name: Build and push the web image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: apps/web/Dockerfile
+          platforms: ${{ vars.PODOKIT_IMAGE_PLATFORM || 'linux/amd64' }}
+          push: true
+          tags: ${{ steps.profile.outputs.web }}:${{ steps.profile.outputs.tag }}
+          cache-from: type=gha,scope=web
+          cache-to: type=gha,scope=web,mode=max
+
+      - name: Report what to deploy
+        run: |
+          echo "Pushed ${{ steps.profile.outputs.api }}:${{ steps.profile.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "Pushed ${{ steps.profile.outputs.web }}:${{ steps.profile.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo 'Roll out with `podo deploy plan --profile <name> --release ${{ steps.profile.outputs.tag }}`, then apply the printed hash.' >> "$GITHUB_STEP_SUMMARY"

package/dist/templates/todo/infra/k3s/README.md

@@ -0,0 +1,18 @@
+# Example k3s manifests
+
+These are **illustrative**. `podo deploy` does not read or apply them.
+
+For a real deployment, initialize a profile and let PodoKit render the manifests it
+will actually apply — with image digests, probes, disruption budgets, a migration
+Job, and a confirmation hash:
+
+```bash
+podo deploy init --profile production --context production --host app.example.com
+podo deploy render --profile production --release v1.2.3
+```
+
+Keep these files if you want a starting point for hand-managed manifests, or delete
+the directory if you deploy with `podo deploy`. If you do apply them by hand, replace
+every `example.com` and `ghcr.io/example/...` placeholder first, and note that the
+image tags below are placeholders too: the deployment tooling rejects `latest`,
+branch tags, and empty tags, and so should you.

package/dist/templates/todo/infra/k3s/api-deployment.yaml

@@ -1,3 +1,4 @@
+# Example only. See README.md in this directory; `podo deploy` renders its own.
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -13,7 +14,8 @@ spec:
     spec:
       containers:
         - name: api
-          image: ghcr.io/example/podokit-api:latest
+          # Placeholder. Use one immutable, stable SemVer tag for api and web.
+          image: ghcr.io/example/podokit-api:v0.0.0
           ports:
             - containerPort: 3000
           envFrom:
@@ -22,3 +24,6 @@ spec:
           readinessProbe:
             httpGet: { path: /health/ready, port: 3000 }
             initialDelaySeconds: 5
+          livenessProbe:
+            httpGet: { path: /health, port: 3000 }
+            initialDelaySeconds: 15

package/dist/templates/todo/infra/k3s/ingress.yaml

@@ -1,3 +1,4 @@
+# Example only. See README.md in this directory; `podo deploy` renders its own.
 apiVersion: traefik.io/v1alpha1
 kind: Middleware
 metadata:
@@ -14,6 +15,13 @@ metadata:
   annotations:
     traefik.ingress.kubernetes.io/router.middlewares: podokit-compression@kubernetescrd
 spec:
+  # Name the controller explicitly rather than relying on a default IngressClass.
+  ingressClassName: traefik
+  # app-config sets an https:// origin, so the route has to terminate TLS. Create the
+  # Secret out of band (cert-manager, or an existing certificate) and name it here.
+  tls:
+    - hosts: [example.com]
+      secretName: app-tls
   rules:
     - host: example.com
       http:

package/dist/templates/todo/infra/k3s/web-deployment.yaml

@@ -1,3 +1,4 @@
+# Example only. See README.md in this directory; `podo deploy` renders its own.
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -13,8 +14,17 @@ spec:
     spec:
       containers:
         - name: web
-          image: ghcr.io/example/podokit-web:latest
+          # Placeholder. Use one immutable, stable SemVer tag for api and web.
+          image: ghcr.io/example/podokit-web:v0.0.0
           ports:
             - containerPort: 3000
           envFrom:
             - configMapRef: { name: app-config }
+          # Without these a rolling update sends traffic to a process that has not
+          # bound its port yet.
+          readinessProbe:
+            httpGet: { path: /, port: 3000 }
+            initialDelaySeconds: 5
+          livenessProbe:
+            httpGet: { path: /, port: 3000 }
+            initialDelaySeconds: 15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.16.4",
+  "version": "0.17.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": {