prizmkit 1.1.156 → 1.1.160

package/bundled/skills/prizmkit-deploy/references/ssh-adapter-flow.md

@@ -1,221 +0,0 @@
-# SSH Adapter Flow
-
-Read this file when Discovery routes `/prizmkit-deploy` to SSH Linux full automation.
-
-The SSH adapter supports Node.js projects using PM2 + Nginx blue/green deployment.
-
-## 1. Deployment Mode Selection
-
-Before entering the configuration wizard, ask how the user wants to deploy:
-
-1. **Direct Upload** — build locally, transfer artifacts to the server, start with PM2. Best for first deployment and low-spec servers.
-2. **CI/CD Auto-Deploy** — configure GitHub Actions so pushes deploy automatically.
-
-If the user chooses CI/CD, ask which mode:
-
-- **Push mode** — GitHub Actions builds and SCPs artifacts to server. Low server load.
-- **Pull mode** — server pulls code and builds itself. Simpler workflow but requires a deploy key and build tools on the server.
-
-Read `references/deployment-modes.md` when the user needs the full comparison.
-
-Config field: `deployStrategy` in `deploy.config.json` is `direct-upload`, `ci-cd-push`, or `ci-cd-pull`. Existing configs without this field default to `ci-cd-pull` for backward compatibility.
-
-## 2. Server Model
-
-A valid SSH target:
-
-- Is reachable over SSH.
-- Provides a Linux shell.
-- Can install or already has Node.js, npm, PM2, Nginx, and Git.
-- Can access the configured repository when using CI/CD Pull mode.
-
-Roles:
-
-- `bootstrapUser`: usually root; installs packages and creates users/directories.
-- `runtimeUser`: default `deploy`; app processes run as this user and never as root.
-
-Server-side layout:
-
-```text
-/var/www/<project>/
-  releases/
-    <release-id>/
-  shared/
-    .env.production
-    deploy-metadata.json
-  current -> releases/<release-id>
-  deploy-logs/
-```
-
-`shared/.env.production` is strict UTF-8 dotenv data with one unique `KEY=value` assignment per line; update it atomically, keep mode `600`, and require runtime-user ownership. `shared/deploy-metadata.json` must conform to `${SKILL_DIR}/references/deploy-metadata-schema.json`, be written atomically after successful live verification, and contain no secrets.
-
-## 3. First-Run Configuration Wizard
-
-Flow: deployment mode → collect → validate → confirm → persist.
-
-Collect:
-
-1. SSH server host/port, bootstrap user, runtime user, auth method.
-2. Repository access only for `ci-cd-pull`: Git URL, branch, deploy-key or other auth.
-3. App configuration: app id, path, package manager, install/build/start commands, blue/green port pair, health checks.
-4. Environment variables: scan source for env references, ask for values or storage strategy.
-5. Persist `deploy.config.json` and render/update `deploy.md` from `${SKILL_DIR}/assets/deploy-document-template.md`.
-
-Validate SSH immediately with a harmless connectivity command before collecting deeper config. If SSH fails, stop and fix connectivity first.
-
-## 4. Bootstrap
-
-Before privileged bootstrap, present an action plan listing:
-
-- packages to install
-- users/groups to create
-- SSH keys to generate
-- Nginx config files to create/update
-- directories and permissions
-- services that may restart
-
-Rules:
-
-- User gives one explicit approval for the bootstrap plan.
-- If the plan changes during execution, pause and ask again.
-- Bootstrap operations must be idempotent.
-- Existing config files must be backed up before modification.
-- Failed bootstrap stops before deployment and provides recovery instructions.
-
-Read `references/ssh-bootstrap-flow.md` for the detailed bootstrap procedure. It routes to `references/firewall-setup.md` and `references/database-setup.md` when those branches are selected.
-
-## 5. Strategy-Specific Setup
-
-Direct upload:
-- Build locally and transfer artifacts.
-- No Git operation is required on the server.
-- Read `references/direct-upload.md`.
-
-CI/CD push or pull:
-- Generate `.github/workflows/deploy.yml` from `references/ci-cd-workflows.md`.
-- Verify the first push to the configured branch will trigger deployment.
-- Pull mode requires a deploy key on the server; show the public key and wait for the user to add it to GitHub Deploy Keys before verifying clone access.
-
-After a successful direct-upload deployment, offer CI/CD setup so future `git push` can deploy automatically.
-
-## 6. DNS and SSL
-
-Before SSL, ask whether the user has a domain for the project.
-
-- If no domain, skip DNS + SSL and note it in `deploy.md`.
-- If a domain exists, check DNS before SSL.
-- Read `references/dns-setup.md` for DNS instructions.
-- Read `references/ssl-setup.md` for Let's Encrypt / certificate guidance.
-
-Always verify certificate renewal when Let's Encrypt is configured.
-
-## 7. Deployment Execution
-
-Read `references/ssh-execution-flow.md` for the full pipeline.
-
-Core sequence:
-
-1. Pre-flight and prepare release.
-2. Fetch/build or receive artifact.
-3. Stage new process on inactive blue/green port.
-4. Health-check inactive port.
-5. Switch Nginx upstream only after staged health checks pass.
-6. Verify public endpoint.
-7. Stop old process, cleanup old releases, record history.
-
-Failure rules:
-
-- If any step before traffic switch fails, stop and leave the live version unchanged.
-- If a public health check fails after traffic switch, rollback immediately.
-- Do not delete failed release logs; preserve them for debugging.
-
-## 8. Blue/Green PM2 + Nginx Invariants
-
-- Default ports: blue `3101`, green `3102`.
-- Active color is persisted in `shared/deploy-metadata.json` using `${SKILL_DIR}/references/deploy-metadata-schema.json`.
-- PM2 process name: `<project>-<app>-<color>`.
-- Nginx managed blocks include `# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY`.
-- First creation or modification of non-PrizmKit Nginx config requires user confirmation.
-- Always run `nginx -t` before reload.
-
-Read `references/nginx-blue-green.md` for config templates and traffic switch details.
-
-## 9. Rollback
-
-Rollback can be automatic or manual.
-
-Manual command:
-
-```text
-/prizmkit-deploy rollback --app <id> [--to <releaseId>]
-```
-
-Steps:
-
-1. Identify target release.
-2. Verify build artifacts exist.
-3. Start PM2 on the target release/port.
-4. Update Nginx upstream.
-5. Run `nginx -t` and reload.
-6. Run public health checks; if they fail, restore the prior verified upstream.
-7. Allocate and atomically write the rollback history event through `${SKILL_DIR}/references/deploy-history-schema.md`.
-8. Atomically update `shared/deploy-metadata.json` through `${SKILL_DIR}/references/deploy-metadata-schema.json` with the restored release/color/port and rollback event identity.
-
-If no previous release exists, state clearly that rollback is not possible.
-
-## 10. Operations Commands
-
-- `status`: PM2 list, active release, active color/port, last deploy.
-- `logs --app <id>`: recent PM2 logs for active process.
-- `restart --app <id>`: restart active PM2 process and run health checks.
-- `health --app <id>`: run configured health checks.
-- `history`: list deploy history events chronologically.
-
-Run app commands as `runtimeUser`.
-
-## 11. Secrets Management
-
-Supported storage modes:
-
-- `ask-every-time`
-- `ignored-local-env`
-- `user-managed-on-server-only`
-
-Rules:
-
-- `ignored-local-env` uses `.prizmkit/deploy/secrets.local.env`, must be ignored by Git and current-user-only, and follows `${SKILL_DIR}/references/database-setup.md` dotenv/migration safety.
-- Legacy `plaintext-local` requires explicit migration to `ignored-local-env`; legacy `encrypted-local` is unsupported and requires user selection of a supported mode before deployment.
-- Server runtime secrets live in `shared/.env.production` with mode `600`.
-- Deploy history records secret presence metadata only.
-- Never record raw secret values, passphrases, decryption keys, or unsalted hashes.
-
-## 12. Existing Deployment Takeover
-
-When the target server already has deployment assets, read `references/ssh-takeover.md`.
-
-Record takeover decisions and validation results in config and history.
-
-Before modifying non-PrizmKit-managed Nginx config, ask for confirmation.
-
-## 13. Multi-App Coordination
-
-An all-app deploy creates one release group.
-
-Rules:
-
-- Pre-traffic phases must complete for all selected apps before any app switches traffic.
-- If any app fails before traffic switch, no app switches traffic.
-- If any app fails after traffic switch, default to group rollback.
-- Single-app deploys do not affect unrelated apps.
-
-## 14. History and Validation
-
-Write a deploy-history record for every deploy, rollback, takeover, validation, user-abort, failed deploy, or adapter gap.
-
-Read:
-
-- `references/deploy-history-schema.md`
-- `references/deploy-config-schema.md`
-- `references/live-validation-notes.md` when troubleshooting bootstrap or deploy failures
-
-Validation is mandatory before production deploy.

package/bundled/skills/prizmkit-deploy/references/ssh-bootstrap-flow.md

@@ -1,49 +0,0 @@
-# SSH Bootstrap Flow
-
-Bootstraps the server before first deployment. Present a plan showing every privileged action before executing anything.
-
-## Always-Run Preflight
-
-```
-locale-gen en_US.UTF-8           # fix locale warnings on bare Ubuntu
-apt-get update -qq               # refresh package list
-```
-
-## Check-and-Install (idempotent)
-
-Node.js, npm, PM2, Nginx, Git. Use v22 LTS if v25 not available.
-
-## Detect Port Conflicts
-
-`ss -tlnp | grep :80 || true`. If port 80/443 is occupied, report and ask how to resolve.
-
-## User and Directory Setup
-
-```
-useradd -m -s /bin/bash <runtimeUser>   # if not exists
-mkdir -p /var/www/<project>/{releases,shared,deploy-logs}
-chown -R <runtimeUser>:<runtimeUser> /var/www/<project>
-```
-
-## PM2 Startup
-
-```
-env PATH=$PATH:/usr/bin pm2 startup systemd -u <runtimeUser> --hp /home/<runtimeUser>
-```
-
-## Deploy Key (Pull mode only)
-
-```
-sudo -u <runtimeUser> ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
-sudo -u <runtimeUser> ssh-keyscan -H github.com >> ~/.ssh/known_hosts
-```
-
-## Security Baseline (Firewall)
-
-After core tools are installed, ask whether to configure ufw. If user agrees, read `references/firewall-setup.md` for the full interactive flow and rule templates.
-
-## Database Setup
-
-If Discovery detected database drivers, ask whether to install the database on the server. If user agrees, read `references/database-setup.md` for platform-specific setup commands and security notes.
-
-After each bootstrap step, record the result. Bootstrap operations must be idempotent. Back up any existing config files before modifying them.

package/bundled/skills/prizmkit-deploy/references/ssh-execution-flow.md

@@ -1,41 +0,0 @@
-# SSH: Deployment Execution Flow
-
-Pipeline runs in strict order. Each group must complete before the next begins. If any step before traffic switch fails, STOP — do not touch the live version.
-
-## Pre-flight — Change Summary
-
-Show what will be deployed using `git log --oneline <last-deployed-commit>..HEAD`. If first deployment, show last 5 commits. If no new commits, warn "No new code changes. Are you sure you want to redeploy?"
-
-## Group 1 — Pre-flight & Prepare
-
-- Verify SSH, runtime user, tools, deploy key, port availability.
-- Generate `releaseId`: `YYYYMMDDTHHMMSSZ-<short-commit-sha>` in UTC. If that release directory already exists, select the lowest free suffix from `-01` through `-99`; never reuse or overwrite a release directory, and stop if the suffix space is exhausted. Create `releases/<releaseId>`.
-- Determine target color: read `activeColor` from `shared/deploy-metadata.json` and use the opposite. If first deploy (no metadata, no `current` symlink), default to blue (port 3101).
-
-## Group 2 — Fetch & Build
-
-- **CI/CD Pull mode** (server-side build): git clone → install → copy `.env.production` before build (NEXT_PUBLIC_* vars are baked at build time) → build. If build fails: STOP.
-- **CI/CD Push mode** (runner-side build): extract tarball, skip install/build.
-- **Direct-upload mode**: build was already done locally and SCP'd. Skip this group.
-
-## Group 3 — Stage & Health Check
-
-- Start new version on inactive port via PM2: `pm2 start npm --name <project>-<app>-<color> -- run start -- -p <inactivePort>`.
-- PM2 process naming: `<project>-<app>-<color>` (e.g., `prizm-ideas-web-green`).
-- Wait 3-5 seconds, run health checks against new port. If any fails: STOP, do NOT switch traffic.
-
-## Group 4 — Switch & Verify
-
-- Update Nginx upstream to new port. Run `nginx -t` — abort on failure.
-- `systemctl reload nginx`. Update `current` symlink to new release.
-- Run health checks against the public endpoint. If any fails, rollback immediately and do not record the candidate as active.
-
-## Group 5 — Cleanup & Record
-
-- Allocate the collision-safe deploy event ID and atomically write deploy-history JSON using `${SKILL_DIR}/references/deploy-history-schema.md`, with event identity separate from `releaseId`.
-- After the history record succeeds, atomically write `shared/deploy-metadata.json` from `${SKILL_DIR}/references/deploy-metadata-schema.json` with the verified `activeColor`, `activePort`, `lastReleaseId`, operation event ID, and UTC update time. If either record write fails, preserve both processes/releases, report a recording failure, and require the next operation to rediscover active state from Nginx plus the `current` symlink before retrying metadata repair.
-- Stop the old PM2 process. Remove oldest releases beyond `releaseRetention` count. Run `pm2 save` and update `deploy.config.json` validation status.
-
-## Post-deploy — Completion Summary
-
-Output a summary (project, URL, version, duration, health status) and update the matching sections of `deploy.md` from `${SKILL_DIR}/assets/deploy-document-template.md`; do not append duplicate headings or an event log. If `deployStrategy` is `"direct-upload"`, offer CI/CD upgrade (see §SSH: Post-Deploy CI/CD Upgrade).

package/bundled/skills/prizmkit-deploy/references/ssh-takeover.md

@@ -1,20 +0,0 @@
-# SSH: Existing Deployment Takeover
-
-When deploying to a server that already has deployment assets.
-
-## Detection
-
-1. Check for existing `/var/www/<project>` directory
-2. Check for existing PM2 processes with similar names
-3. Check Nginx config referencing the same domain/IP
-4. Check for port conflicts
-
-## Decision Flow
-
-Report findings and ask for takeover decision:
-
-- **Take over and backup**: Back up existing config, then proceed.
-- **Coexist**: Use different directory/ports/process names.
-- **Manual resolve**: Stop and let the user handle it.
-
-Record takeover decision and validation results in config and history.

package/bundled/skills/prizmkit-deploy/references/ssl-setup.md

@@ -1,56 +0,0 @@
-# SSL/HTTPS Configuration (Let's Encrypt + Certbot)
-
-Read this file when DNS is confirmed pointing to the server and SSL needs to be configured.
-
-## Step 1 — Detect cloud vendor
-
-```
-# Try metadata endpoints to detect cloud vendor
-curl -s --connect-timeout 2 http://100.100.100.200/latest/meta-data/ && echo "ALIBABA"
-curl -s --connect-timeout 2 http://metadata.tencentyun.com/latest/meta-data/ && echo "TENCENT"
-curl -s --connect-timeout 2 http://169.254.169.254/latest/meta-data/ && echo "AWS/GCP/AZURE"
-```
-Also check `/etc/hostname` for vendor patterns.
-
-## Step 2 — Choose SSL strategy
-
-- **Cloud vendor detected** → ask user:
-  > "Detected the server is running on <cloud-vendor>. Which SSL approach?"
-  > - **A. Let's Encrypt free certificate (recommended)** — one command for permanent auto-renewal, hassle-free
-  > - **B. <cloud-vendor> native certificate** — manual download/config, 1-year validity requires manual renewal
-  >
-  > Choose A and I'll set it up for you; choose B and you'll need to download the certificate from the cloud console and tell me the path.
-- **No cloud vendor / unknown** → use certbot directly, no choice needed.
-
-## Step 3 — Certbot install & certificate request
-
-```
-# Install certbot (idempotent)
-which certbot || apt-get install -y certbot python3-certbot-nginx
-
-# Request certificate
-certbot --nginx -d <domain> -d www.<domain> --non-interactive --agree-tos --email <user-email>
-```
-
-**Collect from user before running:**
-- Email address (Let's Encrypt expiry notifications)
-- Confirm domain list (e.g., `example.com, www.example.com`)
-
-## Step 4 — Verify auto-renewal
-
-```
-systemctl status certbot.timer
-certbot renew --dry-run
-```
-If timer is inactive, enable it: `systemctl enable --now certbot.timer`.
-
-## Step 5 — Record
-
-- Write SSL configuration summary to deploy.md: certificate paths, auto-renewal status, expiry date.
-- Record a `"ssl-setup"` event in deploy history.
-
-## Edge cases
-
-- **DNS not yet propagated** → certbot challenge fails. Tell user to wait and retry: `/prizmkit-deploy setup-ssl`.
-- **Existing certificate found** → check expiry date (`certbot certificates`). If expiring within 30 days, warn. Otherwise skip.
-- **Port 80/443 occupied by non-Nginx process** → report and ask how to resolve before proceeding.