@curenorway/kode-cli 1.9.2 → 1.10.0

package/README.md

@@ -2,6 +2,16 @@
 
 Command-line tool for managing JavaScript and CSS scripts for Webflow sites via Cure Kode CDN.
 
+## Features
+
+- **Pull/Push scripts** - Sync scripts between local files and remote CDN
+- **Watch mode** - Auto-sync on file changes with retry on failure
+- **Staging/Production** - Separate environments with explicit production enable
+- **Rollback** - Quick recovery to previous deployments
+- **AI Context** - Generate and manage context for AI agents
+- **Page Context Caching** - Save page structures for AI development
+- **MCP Integration** - Works with Cure Kode MCP for AI agents
+
 ## Installation
 
 ```bash
@@ -13,13 +23,13 @@ pnpm add -g @curenorway/kode-cli
 ## Quick Start
 
 ```bash
-# Initialize a new project
+# Initialize a new project (creates config + AI context)
 kode init
 
 # Pull existing scripts from remote
 kode pull
 
-# Edit your scripts locally...
+# Edit your scripts locally in .cure-kode-scripts/
 
 # Push changes
 kode push
@@ -41,7 +51,12 @@ Initialize a Cure Kode project in the current directory.
 kode init
 ```
 
-This creates a `.cure-kode/config.json` file with your site configuration.
+Creates:
+- `.cure-kode/config.json` - Site configuration and API key
+- `.cure-kode/context.md` - AI context file
+- `.cure-kode-scripts/` - Scripts directory
+- `CLAUDE.md` - AI agent instructions (with metadata documentation)
+- `.mcp.json` - MCP server configuration (cure-kode, webflow, playwright)
 
 ### `kode pull`
 
@@ -52,6 +67,10 @@ kode pull           # Pull all scripts
 kode pull --force   # Overwrite local changes
 ```
 
+Output shows script status:
+- `[G]` = Global scope, `[P]` = Page-specific
+- `⚡` = Auto-load enabled, `○` = Manual load only
+
 ### `kode push`
 
 Upload local scripts to remote.
@@ -61,6 +80,8 @@ kode push                           # Push all changed scripts
 kode push my-script.js              # Push specific script
 kode push --all                     # Push all scripts
 kode push -m "Fixed bug"            # Add change message
+kode push --auto-load               # Enable auto-load for new scripts
+kode push --no-auto-load            # Disable auto-load
 ```
 
 ### `kode watch`
@@ -69,30 +90,77 @@ Watch for file changes and automatically push to remote.
 
 ```bash
 kode watch                  # Watch and push
-kode watch --deploy         # Watch, push, and deploy
-kode watch --env production # Watch with specific environment
+kode watch --deploy         # Watch, push, and deploy on changes
 ```
 
+Features:
+- Retry on network failure with exponential backoff
+- Session summary on exit (Ctrl+C)
+- Debounced uploads to prevent rapid-fire pushes
+
 ### `kode deploy`
 
 Deploy scripts to staging or production.
 
 ```bash
 kode deploy                 # Deploy to staging (default)
-kode deploy --env production # Deploy to production
 kode deploy --promote       # Promote staging to production
+kode deploy --force         # Force release stale deploy lock
 kode deploy -n "Release v2" # Deploy with notes
 ```
 
+**Note:** Production must be enabled before promoting. See `kode production`.
+
+### `kode rollback`
+
+Rollback to a previous deployment.
+
+```bash
+kode rollback               # Rollback staging to previous version
+kode rollback production    # Rollback production to previous version
+```
+
+### `kode production`
+
+Manage production environment (disabled by default for safety).
+
+```bash
+kode production status                    # Check if production is enabled
+kode production enable                    # Enable production environment
+kode production enable --domain example.com  # Enable with specific domain
+kode production disable                   # Disable production environment
+```
+
 ### `kode html <url>`
 
 Fetch and analyze HTML from a URL.
 
 ```bash
-kode html https://mysite.com
-kode html https://mysite.com --json     # Output as JSON
-kode html https://mysite.com --scripts  # Show scripts only
-kode html https://mysite.com --styles   # Show styles only
+kode html https://mysite.com              # Analyze page
+kode html https://mysite.com --json       # Output as JSON
+kode html https://mysite.com --scripts    # Show scripts only
+kode html https://mysite.com --styles     # Show styles only
+kode html https://mysite.com --save       # Cache page context for AI
+```
+
+### `kode pages`
+
+List cached page contexts.
+
+```bash
+kode pages                  # List all cached pages
+kode pages --json           # Output as JSON
+```
+
+### `kode context`
+
+View and manage AI context.
+
+```bash
+kode context                # View current context
+kode context --edit         # Open context in editor
+kode context --refresh      # Refresh context from remote
+kode context --json         # Output as JSON
 ```
 
 ### `kode status`
@@ -103,6 +171,12 @@ Show current project status.
 kode status
 ```
 
+Shows:
+- Site info and CDN URL
+- Production enabled state
+- Script sync status
+- Deployment versions
+
 ## Configuration
 
 ### Project Config (`.cure-kode/config.json`)
@@ -113,37 +187,34 @@ kode status
   "siteSlug": "my-site",
   "siteName": "My Site",
   "apiKey": "ck_...",
-  "scriptsDir": "kode",
+  "scriptsDir": ".cure-kode-scripts",
   "environment": "staging"
 }
 ```
 
-### Global Config
+### Scripts Directory
 
-Global configuration is stored in `~/.config/cure-kode/config.json`:
-
-```json
-{
-  "apiUrl": "https://app.cure.no"
-}
-```
+Default: `.cure-kode-scripts/` (avoids conflicts with AI-generated `scripts/` folders)
 
 ### Environment Variables
 
 - `CURE_KODE_API_KEY` - API key (overrides project config)
-- `CURE_KODE_API_URL` - API URL (overrides global config)
+- `CURE_KODE_API_URL` - API URL (default: `https://app.cure.no`)
 
 ## Project Structure
 
 ```
 your-project/
 ├── .cure-kode/
-│   ├── config.json      # Project configuration
-│   └── scripts.json     # Script metadata (versions, sync status)
-└── kode/                # Your scripts directory
-    ├── init.js
-    ├── tracking.js
-    └── styles.css
+│   ├── config.json       # Project configuration
+│   ├── context.md        # AI context (notes, discoveries)
+│   └── pages/            # Cached page contexts
+├── .cure-kode-scripts/   # Your scripts directory
+│   ├── init.js
+│   ├── tracking.js
+│   └── styles.css
+├── .mcp.json             # MCP server configuration
+└── CLAUDE.md             # AI agent instructions
 ```
 
 ## Workflow Examples
@@ -160,10 +231,31 @@ kode pull
 # 3. Start watch mode
 kode watch
 
-# 4. Edit files in your editor - they auto-push on save
+# 4. Edit files - they auto-push on save
 
-# 5. When ready, deploy
+# 5. When ready, deploy to staging
 kode deploy
+
+# 6. Test, then promote to production
+kode production enable
+kode deploy --promote
+```
+
+### AI-Assisted Development
+
+```bash
+# 1. Initialize with MCP support
+kode init
+
+# 2. Cache page structures for AI context
+kode html https://mysite.com/page1 --save
+kode html https://mysite.com/page2 --save
+
+# 3. AI can now use MCP tools to:
+#    - Read page structure: kode_get_page_context
+#    - Create scripts: kode_create_script
+#    - Push changes: kode_push
+#    - Deploy: kode_deploy
 ```
 
 ### CI/CD Integration
@@ -171,25 +263,19 @@ kode deploy
 ```bash
 # In your CI pipeline
 kode push --all
-kode deploy --env staging
+kode deploy
 # Run tests...
 kode deploy --promote
 ```
 
-### Team Workflow
+### Emergency Rollback
 
 ```bash
-# Developer 1: Pull latest
-kode pull --force
-
-# Developer 2: Push changes
-kode push -m "Added new animation"
-
-# Deploy to staging for review
-kode deploy -n "Review build"
+# Something went wrong in production
+kode rollback production
 
-# After approval, promote to production
-kode deploy --promote
+# Or if deploy is stuck
+kode deploy --force
 ```
 
 ## API Key
@@ -201,15 +287,12 @@ Get your API key from the Cure app:
 
 ### Permissions
 
-- `read` - Pull scripts, view status
-- `write` - Push scripts
-- `deploy` - Deploy to staging/production
-- `delete` - Delete scripts
-
-## Requirements
-
-- Node.js 18 or later
-- Cure Kode API key
+| Permission | CLI Commands |
+|------------|--------------|
+| `read` | `pull`, `status`, `html`, `pages`, `context` |
+| `write` | `push`, `watch` |
+| `deploy` | `deploy`, `rollback`, `production` |
+| `delete` | (delete scripts) |
 
 ## Security
 
@@ -217,23 +300,11 @@ Get your API key from the Cure app:
 
 - API keys stored locally in `.cure-kode/config.json`
 - Directory is automatically gitignored during `kode init`
-- Keys are **SHA256 hashed** before server storage
-
-### Permissions Model
+- Keys are **SHA256/HMAC hashed** before server storage (V2 keys use salt)
 
-API keys have granular, site-scoped permissions:
-
-| Permission | CLI Commands |
-|------------|--------------|
-| `read` | `pull`, `status`, `html`, `pages`, `context` |
-| `write` | `push`, `watch` |
-| `deploy` | `deploy` |
-| `delete` | (delete scripts) |
-
-### Network Security
-
-The HTML fetch feature (`kode html`) includes **SSRF protection**:
+### SSRF Protection
 
+The HTML fetch feature includes protection against Server-Side Request Forgery:
 - Blocks private IP ranges (127.x.x.x, 10.x.x.x, 172.16-31.x.x, 192.168.x.x)
 - Blocks localhost and internal domain names
 - Blocks cloud metadata endpoints (169.254.169.254)
@@ -244,7 +315,7 @@ The HTML fetch feature (`kode html`) includes **SSRF protection**:
 1. **Never commit** `.cure-kode/config.json` to version control
 2. Use **separate keys** for different environments
 3. Use **read-only keys** when possible
-4. **Rotate keys** periodically and when team members leave
+4. **Rotate keys** periodically
 
 ## Troubleshooting
 
@@ -259,9 +330,25 @@ Check that your API key:
 - Has not expired
 - Has the required permissions
 
-### "Script not found"
+### "Deploy lock held"
+
+Another deployment may be in progress. Wait or use:
+```bash
+kode deploy --force
+```
+
+### "Production not enabled"
+
+Enable production before promoting:
+```bash
+kode production enable
+kode deploy --promote
+```
 
-The script may not exist on remote. Use `kode push` to create it.
+## Requirements
+
+- Node.js 18 or later
+- Cure Kode API key
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@curenorway/kode-cli",
-  "version": "1.9.2",
-  "description": "CLI tool for Cure Kode - manage JS/CSS scripts for Webflow sites",
+  "version": "1.10.0",
+  "description": "CLI for Cure Kode CDN - manage, deploy, and sync JS/CSS scripts for Webflow sites with AI agent support",
   "type": "module",
   "bin": {
     "cure-kode": "./dist/cli.js",