sync-cf-secrets 0.1.0 → 0.2.0

package/README.md

@@ -172,6 +172,24 @@ interface SecretProvider {
 }
 ```
 
+## AI Skill
+
+Installing this package automatically registers a [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code) at `~/.claude/skills/sync-cf-secrets/`. This teaches AI assistants the full command reference and workflow patterns so they can help manage your secrets.
+
+## Contributing
+
+This project uses [changesets](https://github.com/changesets/changesets) for version management.
+
+```bash
+# After making changes, create a changeset
+npm run changeset
+# → interactive prompt: pick patch/minor/major, write a summary
+
+# When ready to release
+npm run version    # bumps package.json version, updates CHANGELOG.md
+npm run release    # builds and publishes to npm
+```
+
 ## Security
 
 - Secret values are piped to wrangler via stdin — never exposed in CLI arguments or process listings

package/package.json

@@ -1,18 +1,24 @@
 {
   "name": "sync-cf-secrets",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Sync Cloudflare Workers secrets from 1Password or Bitwarden. Push, pull, and diff secrets across environments.",
   "type": "module",
   "bin": {
     "sync-cf-secrets": "./dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skill",
+    "scripts/postinstall.js"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "prepublishOnly": "tsc"
+    "postinstall": "node scripts/postinstall.js",
+    "prepublishOnly": "tsc",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "npm run build && changeset publish"
   },
   "keywords": [
     "cloudflare",
@@ -46,6 +52,7 @@
     }
   },
   "devDependencies": {
+    "@changesets/cli": "^2.30.0",
     "@types/node": "^25.5.2",
     "typescript": "^5.7.0"
   }

package/scripts/postinstall.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+// Copies the skill file to ~/.claude/skills/sync-cf-secrets/
+// so Claude Code auto-discovers it.
+
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillSource = join(__dirname, "..", "skill", "SKILL.md");
+const skillTarget = join(homedir(), ".claude", "skills", "sync-cf-secrets", "SKILL.md");
+
+try {
+  if (!existsSync(skillSource)) {
+    // Silently skip if skill file not found (e.g. in CI)
+    process.exit(0);
+  }
+
+  const targetDir = dirname(skillTarget);
+  mkdirSync(targetDir, { recursive: true });
+  copyFileSync(skillSource, skillTarget);
+  console.log("sync-cf-secrets: Installed Claude Code skill");
+} catch {
+  // Don't fail the install if skill copy fails
+}

package/skill/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: sync-cf-secrets
+version: 0.1.0
+description: Sync Cloudflare Workers secrets from a password manager (1Password, Bitwarden). Use when the user asks about managing, pushing, pulling, or diffing Cloudflare secrets, or setting up environment variables for Cloudflare Workers.
+requires:
+  bins: ["sync-cf-secrets"]
+  auth: true
+---
+
+# Cloudflare Secrets Manager
+
+Help users manage Cloudflare Workers secrets using the `sync-cf-secrets` CLI, which syncs secrets between a password manager (1Password or Bitwarden) and Cloudflare Workers environments.
+
+## Agent Guidance
+
+### Key Principles
+
+- **Always use `--dry-run` first** — preview any destructive operation before committing
+- **Never log or display secret values** — only show field names
+- **Confirm before `init` or `copy`** — these delete and recreate password manager items
+- **The password manager is the source of truth** — Cloudflare is the deployment target; Cloudflare does not expose secret values
+- **Wrangler vars are excluded automatically** — variables defined as `vars` in the wrangler config are non-secret config; `init`, `copy`, and `push` skip them
+
+### Design Principles
+
+- Auto-discovers environments from the wrangler config (`wrangler.toml` / `wrangler.jsonc`)
+- Auto-detects the password manager CLI (`op` for 1Password, `bw` for Bitwarden)
+- Config is optional — sensible defaults from `package.json` and wrangler config
+- Secret values are piped via stdin to wrangler, never exposed in CLI arguments
+
+### Safety Rules
+
+- Always use `--dry-run` before `push`, `init`, or `copy` to preview changes
+- Never run `init` without the user confirming they want to replace existing items
+- Never display secret values in output — only field names
+- Verify the correct vault and environment before pushing
+
+### Workflow Patterns
+
+#### First-time Setup
+
+```bash
+# 1. Create password manager items from existing .dev.vars
+sync-cf-secrets init --dry-run    # preview first
+sync-cf-secrets init
+
+# 2. Copy local values to staging (most are the same)
+sync-cf-secrets copy local staging
+
+# 3. User edits staging item in password manager (change AUTH_SECRET, etc.)
+
+# 4. Push to Cloudflare
+sync-cf-secrets push staging --dry-run
+sync-cf-secrets push staging
+
+# 5. Repeat for production
+sync-cf-secrets copy staging production
+# User edits production item (swap test keys for live keys)
+sync-cf-secrets push production
+```
+
+#### Onboarding a New Developer
+
+```bash
+# Pull local dev secrets from the shared password manager vault
+sync-cf-secrets pull local
+```
+
+#### Adding a New Secret
+
+```bash
+# 1. Add the field to the password manager item(s) manually
+# 2. Push the updated secrets
+sync-cf-secrets push staging
+sync-cf-secrets push production
+```
+
+#### Auditing After a Deployment
+
+```bash
+sync-cf-secrets diff staging
+sync-cf-secrets diff production
+```
+
+---
+
+## Command Reference
+
+### `init`
+
+Create password manager items for all environments discovered from the wrangler config. Reads field names and values from `.dev.vars`. The `local` item gets actual values; other environments get `CHANGE_ME` placeholders. Excludes wrangler `vars`. Prompts before replacing existing items.
+
+```bash
+sync-cf-secrets init
+sync-cf-secrets init --dry-run
+```
+
+### `copy <from> <to>`
+
+Copy secrets from one environment's password manager item to another. Excludes wrangler `vars` for the target environment. Prompts before replacing the target.
+
+```bash
+sync-cf-secrets copy local staging
+sync-cf-secrets copy staging production
+sync-cf-secrets copy local staging --dry-run
+```
+
+### `push <env>`
+
+Push secrets from the password manager to Cloudflare via `wrangler secret put`. Skips wrangler `vars`. Reports progress per secret and continues on individual failures.
+
+```bash
+sync-cf-secrets push staging
+sync-cf-secrets push production
+sync-cf-secrets push staging --dry-run
+```
+
+### `pull <env>`
+
+Fetch secrets from the password manager and write a `.dev.vars` file.
+
+```bash
+sync-cf-secrets pull local
+sync-cf-secrets pull staging --dry-run
+```
+
+### `list <env>`
+
+List secret names deployed to a Cloudflare Workers environment. Values are never exposed.
+
+```bash
+sync-cf-secrets list staging
+sync-cf-secrets list production
+```
+
+### `diff <env>`
+
+Compare secret names in the password manager vs what's deployed to Cloudflare. Shows missing, extra, and matching secrets.
+
+```bash
+sync-cf-secrets diff staging
+sync-cf-secrets diff production --verbose
+```
+
+### Global Options
+
+| Option | Description |
+|---|---|
+| `--provider <name>` | Force a provider: `1password`, `bitwarden` |
+| `--vault <name>` | Override the vault name |
+| `--dry-run` | Preview without making changes |
+| `--verbose` | Show more detail |
+
+---
+
+## Configuration
+
+Optional `.sync-cf-secrets.json` in project root:
+
+```json
+{
+  "provider": "1password",
+  "vault": "myproject",
+  "prefix": "myproject",
+  "wranglerConfig": "apps/web/wrangler.jsonc",
+  "devVarsPath": "apps/web/.dev.vars"
+}
+```
+
+All fields have defaults: `provider` auto-detected, `vault`/`prefix` from `package.json` name, `wranglerConfig` auto-searched, `devVarsPath` next to wrangler config, environments auto-discovered from wrangler config `env` block.
+
+## Prerequisites
+
+- **1Password**: `op` CLI installed, authenticated via the desktop app (biometric)
+- **Bitwarden**: `bw` CLI installed, `bw login` + `export BW_SESSION=$(bw unlock --raw)`
+- `wrangler` installed (for `push`, `list`, `diff` commands)