@deftai/directive-content 0.55.0

package/deployments/cloudflare/via-wrangler.md

@@ -0,0 +1,165 @@
+# Deploy to Cloudflare via Wrangler CLI
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [README.md](./README.md) | [via-git.md](./via-git.md) | [via-github-actions.md](./via-github-actions.md)
+
+## Overview
+
+Wrangler is Cloudflare's official CLI for deploying to both Pages (static assets)
+and Workers (serverless functions). It provides full control over the deployment
+process and is the foundation for all CLI-based and CI/CD workflows.
+
+**Best for**: Developers wanting full local control, custom CI pipelines, or Workers deployments.
+
+## Prerequisites
+
+- Cloudflare account
+- Node.js ≥ 16.17.0
+- `wrangler` installed (project dev dependency preferred)
+
+## Installation
+
+```bash
+# Project dev dependency (recommended)
+npm install -D wrangler
+
+# Or globally
+npm install -g wrangler
+```
+
+## Authentication
+
+```bash
+# Interactive (opens browser)
+npx wrangler login
+
+# Non-interactive (CI/CD) — use API token
+export CLOUDFLARE_API_TOKEN=<token>
+export CLOUDFLARE_ACCOUNT_ID=<account-id>
+```
+
+## Deploy Workflows
+
+### Pages (Static Assets / Direct Upload)
+
+```bash
+# Build your project first
+npm run build
+
+# Deploy to Pages
+npx wrangler pages deploy <BUILD_OUTPUT_DIR>
+
+# Deploy to a specific branch (preview)
+npx wrangler pages deploy <BUILD_OUTPUT_DIR> --branch=staging
+```
+
+### Workers
+
+```bash
+# Scaffold a new Worker (uses C3 / create-cloudflare)
+npm create cloudflare@latest my-worker
+
+# Local development
+npx wrangler dev
+
+# Deploy to production
+npx wrangler deploy
+```
+
+### Configuration (`wrangler.toml` / `wrangler.jsonc`)
+
+Minimum for Workers:
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2025-01-01"
+```
+
+Minimum for Pages with static assets:
+```toml
+name = "my-site"
+compatibility_date = "2025-01-01"
+pages_build_output_dir = "dist"
+```
+
+## Standards
+
+### Installation & Versioning
+- ! Install Wrangler as a project dev dependency (`npm install -D wrangler`)
+- ! Pin the Wrangler version in `package.json` for reproducible deploys
+- ≉ Install Wrangler globally as the sole installation — team members will drift on versions
+
+### Authentication
+- ! Use API tokens (not legacy API keys) for all non-interactive environments
+- ! Store `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` as environment variables in CI
+- ⊗ Commit API tokens or credentials to the repository
+- ~ Scope API tokens to the minimum required permissions
+
+### Configuration
+- ! Include a `wrangler.toml` or `wrangler.jsonc` in the project root
+- ! Set `compatibility_date` to a recent date and update periodically
+- ~ Use Wrangler environments (`[env.staging]`, `[env.production]`) for multi-stage deploys
+- ~ Treat `wrangler.toml` as the source of truth — dashboard changes are overwritten on deploy
+- ? Use `--dry-run --outdir=dist` to inspect the build output before deploying
+
+### Deployment
+- ! Run `npx wrangler pages deploy <dir>` for Pages projects
+- ! Run `npx wrangler deploy` for Workers projects
+- ! Build the project before deploying (`npm run build` or equivalent)
+- ~ Use `--branch=<name>` for preview deployments on Pages
+- ~ Verify deployment URL after deploy (`<project>.pages.dev` or `<worker>.workers.dev`)
+
+### Local Development
+- ~ Use `npx wrangler dev` for local development with hot reload
+- ~ Use `.dev.vars` for local secrets (gitignored)
+- ⊗ Use `wrangler dev` with production bindings unless explicitly intended
+
+### Secrets
+- ! Use `npx wrangler secret put <NAME>` to set secrets (never in config files)
+- ! Use `.dev.vars` for local development secrets
+- ⊗ Store secrets in `wrangler.toml` — use `wrangler secret` commands instead
+
+## 🔧 Patterns
+
+**Deploy Pages with custom project name**:
+```bash
+npx wrangler pages project create my-site
+npx wrangler pages deploy dist --project-name=my-site
+```
+
+**Multi-environment Workers**:
+```toml
+[env.staging]
+name = "my-worker-staging"
+route = "staging.example.com/*"
+
+[env.production]
+name = "my-worker-production"
+route = "example.com/*"
+```
+```bash
+npx wrangler deploy --env=staging
+npx wrangler deploy --env=production
+```
+
+**Strict mode deploy (CI safety)**:
+```bash
+npx wrangler deploy --strict
+```
+
+## Anti-Patterns
+
+- ⊗ Modify Workers settings in the dashboard when using Wrangler (Wrangler overwrites on deploy)
+- ⊗ Deploy without building first — Wrangler deploys the directory as-is
+- ⊗ Hardcode `account_id` with secrets in the same file
+- ≉ Use `wrangler publish` (deprecated — use `wrangler deploy`)
+- ≉ Skip `compatibility_date` — this controls runtime behavior and breaking changes
+
+## Compliance Checklist
+
+- ! Wrangler installed as dev dependency with pinned version
+- ! `wrangler.toml` present with `name`, `main` (Workers) or `pages_build_output_dir` (Pages)
+- ! `compatibility_date` set
+- ! Secrets managed via `wrangler secret`, not config files
+- ! API token scoped to minimum permissions

package/deployments/fly-io/README.md

@@ -0,0 +1,37 @@
+# Fly.io Deployment Module
+
+Deft guidance for deploying applications to Fly.io.
+
+## Status
+
+- ! Optional module
+- ~ Good for Deft usage
+
+## Overview
+
+Fly.io runs Docker containers on physical servers close to your users worldwide. Edge deployment platform with 30+ regions and automatic global routing.
+
+## Deployment Methods
+
+| File | Method | Best For |
+|------|--------|----------|
+| `via-flyctl.md` | flyctl CLI | Primary deployment method, full control (default) |
+| `via-github-actions.md` | GitHub Actions CI/CD | Automated pipelines with testing and deployments |
+| `via-dockerfile.md` | Custom Dockerfile | Advanced Docker builds, multi-stage optimization |
+| `via-multi-region.md` | Multi-Region Deployment | Global apps with low latency and high availability |
+
+## Quick Decision Guide
+
+- **Default path**: `via-flyctl.md` — `fly launch` and `fly deploy` for most apps
+- **CI/CD pipelines**: `via-github-actions.md` — automated deployments with tests
+- **Custom containers**: `via-dockerfile.md` — full Docker control and optimization
+- **Global deployment**: `via-multi-region.md` — deploy to multiple regions worldwide
+
+## References
+
+- [Fly.io Documentation](https://fly.io/docs/)
+- [flyctl CLI Reference](https://fly.io/docs/flyctl/)
+- [Fly Launch](https://fly.io/docs/reference/fly-launch/)
+- [Multi-region Deployment](https://fly.io/docs/reference/regions/)
+- [Fly Postgres](https://fly.io/docs/postgres/)
+- [Fly Machines](https://fly.io/docs/machines/)