wordpress-agent-kit 0.4.0 → 0.6.0

package/CLI_REVIEW.md

@@ -1,250 +0,0 @@
-# WordPress Agent Kit CLI - Accessibility & Agent-Friendly Review
-
-**Date**: 2026-06-08  
-**Version**: 0.2.1
-
----
-
-## Executive Summary
-
-The current CLI is functional for **human developers** using interactive prompts (`@clack/prompts`), but lacks features for **programmatic/agent usage**:
-
-- ❌ No JSON output mode
-- ❌ No machine-readable result objects
-- ❌ No programmatic API (only CLI entrypoint)
-- ❌ No non-interactive "headless" mode for all commands
-- ❌ No structured logging/event streaming
-- ❌ Exit codes not consistently semantic
-
----
-
-## Current Architecture
-
-```
-src/
-├── cli.ts                    # Entry point, Commander setup
-├── commands/
-│   ├── install.ts           # Non-interactive (args + flags only) ✓
-│   ├── setup.ts             # Interactive (prompts only) ✗
-│   ├── sync-skills.ts       # Non-interactive (args + flags only) ✓
-│   └── run-playground.ts    # Non-interactive ✓
-├── lib/
-│   ├── installer.ts         # Core logic (pure functions) ✓
-│   └── triage-mapper.ts     # Pure mappers ✓
-└── utils/
-    ├── paths.ts             # Path resolution
-    └── run.ts              # Command runner
-```
-
-**Good**: Core logic (`installKit`, mappers) is pure and testable.  
-**Gap**: `setup.ts` couples interactive prompts with business logic.
-
----
-
-## Recommendations
-
-### 1. Add JSON Output Mode (--json)
-
-**Goal**: Every command outputs structured JSON to stdout when requested.
-
-```bash
-# Success
-wp-agent-kit install /path/to/project --platform github --json
-# {"success":true,"targetDir":"/path/to/project","platform":"github","filesCopied":["AGENTS.md",".github/..."],"durationMs":142}
-
-# Failure
-wp-agent-kit install /nonexistent --json
-# {"success":false,"error":"E_NOT_FOUND","message":"Target directory does not exist","code":"ENOENT"}
-```
-
-**Implementation**:
-- Add `--json` / `--output json` global flag in `cli.ts`
-- Create `OutputFormatter` utility: `json`, `human`, `quiet`
-- Return structured result objects from all command actions
-- Separate stdout (JSON) from stderr (human diagnostics)
-
-### 2. Add Machine-Readable Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error |
-| 2 | Invalid arguments / usage |
-| 3 | Target not found / ENOENT |
-| 4 | Permission denied / EACCES |
-| 5 | Already exists (without --force) |
-| 6 | Git/submodule error |
-| 7 | Network/fetch error |
-| 8 | Validation failed |
-| 130 | Cancelled (SIGINT) |
-
-### 3. Extract Programmatic API
-
-Expose core functions for direct import by agents/scripts:
-
-```typescript
-// src/api.ts (new)
-export interface InstallOptions {
-  targetDir: string;
-  platform: Platform;
-  force?: boolean;
-  dryRun?: boolean;
-}
-
-export interface InstallResult {
-  success: boolean;
-  targetDir: string;
-  platform: Platform;
-  filesCreated: string[];
-  filesSkipped: string[];
-  errors: string[];
-  durationMs: number;
-}
-
-export async function installKit(options: InstallOptions): Promise<InstallResult>;
-export async function syncSkills(options: SyncOptions): Promise<SyncResult>;
-export async function runTriage(targetDir: string): Promise<TriageResult>;
-export async function configureAgentsMd(options: ConfigureOptions): Promise<ConfigureResult>;
-```
-
-**Benefits**:
-- Agents can import and call directly: `import { installKit } from 'wordpress-agent-kit'`
-- No subprocess overhead
-- Full TypeScript types
-- Testable in isolation
-
-### 4. Make `setup` Command Headless-Capable
-
-Current `setup.ts` is prompt-driven. Add non-interactive mode:
-
-```bash
-# Full non-interactive (requires all flags)
-wp-agent-kit setup /path/to/project \
-  --project-type plugin \
-  --tech-stack gutenberg,rest-api,composer \
-  --platform github \
-  --yes \
-  --json
-
-# Hybrid: run triage, apply detected values, no prompts
-wp-agent-kit setup /path/to/project --auto --json
-```
-
-**Flag Matrix for `setup`**:
-| Flag | Description |
-|------|-------------|
-| `--project-type <type>` | plugin \| theme \| block-theme \| site \| blocks \| other |
-| `--tech-stack <list>` | Comma-separated: gutenberg,interactivity,rest-api,wpcli,composer,phpstan,npm,playground |
-| `--platform <platform>` | github \| cursor \| claude \| agent \| pi |
-| `--package-manager <pm>` | npm \| pnpm \| yarn |
-| `--auto` | Run triage, apply detected values, skip prompts |
-| `--yes` / `-y` | Accept all confirmations (requires other flags) |
-| `--reset` | Overwrite existing |
-| `--dry-run` | Show what would be done |
-
-### 5. Add Structured Logging / Event Stream
-
-For long-running operations (sync-skills, playground), emit NDJSON events:
-
-```bash
-wp-agent-kit sync-skills --json-stream
-# {"event":"start","phase":"clone","timestamp":"..."}
-# {"event":"progress","phase":"fetch","message":"Fetching tags...","timestamp":"..."}
-# {"event":"complete","phase":"install","result":{"skillsSynced":42,"timestamp":"..."}}
-```
-
-**Events**: `start`, `progress`, `phase-change`, `warning`, `complete`, `error`
-
-### 6. Add Dry-Run / Preview Mode
-
-```bash
-wp-agent-kit install /path --dry-run --json
-# {"wouldCopy":[{"src":"AGENTS.template.md","dest":"/path/AGENTS.md"},{"src":".github/...","dest":"/path/.github/..."}],"wouldCreateDirs":[]}
-
-wp-agent-kit setup /path --dry-run --auto --json
-# {"wouldInstall":true,"detectedType":"plugin","detectedTech":["gutenberg","npm"],"wouldModify":["AGENTS.md"]}
-```
-
-### 7. Add Shell Completion (Modern CLI Standard)
-
-```bash
-# Generate completion scripts
-wp-agent-kit completion bash > /etc/bash_completion.d/wp-agent-kit
-wp-agent-kit completion zsh > ~/.zsh/completions/_wp-agent-kit
-wp-agent-kit completion fish > ~/.config/fish/completions/wp-agent-kit.fish
-```
-
-Commander.js supports this natively: `program.enablePositionalOptions().addHelpCommand().configureOutput({ writeOut: ... })`
-
-### 8. Add `--version` JSON Output
-
-```bash
-wp-agent-kit --version --json
-# {"name":"wp-agent-kit","version":"0.2.1","node":"20.18.0","platform":"linux"}
-```
-
----
-
-## Priority Matrix
-
-| Priority | Feature | Effort | Impact |
-|----------|---------|--------|--------|
-| **P0** | JSON output (`--json`) | Low | High |
-| **P0** | Semantic exit codes | Low | High |
-| **P0** | Programmatic API export | Medium | High |
-| **P1** | Headless `setup` mode | Medium | High |
-| **P1** | Dry-run/preview | Low | Medium |
-| **P2** | NDJSON event streaming | Medium | Medium |
-| **P2** | Shell completions | Low | Medium |
-| **P3** | Man page generation | Low | Low |
-
----
-
-## Example: Agent-Friendly Workflow
-
-```bash
-# 1. Agent detects WordPress project
-wp-agent-kit setup /workspace/my-plugin --auto --json
-# {"success":true,"applied":{"projectType":"plugin","techStack":["gutenberg","npm"]},"filesModified":["AGENTS.md"]}
-
-# 2. Agent syncs latest skills
-wp-agent-kit sync-skills --json
-# {"success":true,"skillsSynced":47,"source":"WordPress/agent-skills@trunk"}
-
-# 3. Agent installs for specific platform (e.g., Cursor)
-wp-agent-kit install /workspace/my-plugin --platform cursor --json
-# {"success":true,"platform":"cursor","targetDir":"/workspace/my-plugin","filesCreated":[".cursor/...","AGENTS.md"]}
-```
-
----
-
-## Implementation Notes
-
-### Minimal Changes for P0
-
-1. **cli.ts**: Add global `--json` flag, result formatter
-2. **commands/*.ts**: Return structured results instead of `process.exit()`
-3. **lib/installer.ts**: Return `InstallResult` object (already close)
-4. **package.json**: Add `"exports": { ".": "./dist/cli.js", "./api": "./dist/api.js" }`
-
-### Testing Strategy
-
-```typescript
-// tests/api/install.api.test.ts
-import { installKit } from '../../src/api.js';
-
-it('returns structured result on success', async () => {
-  const result = await installKit({ targetDir: '/tmp/test', platform: 'github' });
-  expect(result.success).toBe(true);
-  expect(result.filesCreated).toContain('AGENTS.md');
-});
-```
-
----
-
-## References
-
-- [Commander.js JSON output patterns](https://github.com/tj/commander.js/blob/master/Examples/options-json.ts)
-- [CLI Guidelines - Output](https://clig.dev/#output)
-- [12-factor CLI apps](https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46)
-- [GitHub CLI `gh` JSON patterns](https://cli.github.com/manual/gh_help_formatting)

package/biome.json

@@ -1,39 +0,0 @@
-{
-	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-	"vcs": {
-		"enabled": true,
-		"clientKind": "git",
-		"useIgnoreFile": true
-	},
-	"files": {
-		"include": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts", "extensions/**/*.ts"],
-		"ignoreUnknown": true
-	},
-	"organizeImports": {
-		"enabled": true
-	},
-	"linter": {
-		"enabled": true,
-		"rules": {
-			"recommended": true,
-			"suspicious": {
-				"noExplicitAny": "warn"
-			},
-			"correctness": {
-				"noUnusedVariables": "error"
-			}
-		}
-	},
-	"formatter": {
-		"enabled": true,
-		"indentStyle": "tab",
-		"lineWidth": 100
-	},
-	"javascript": {
-		"formatter": {
-			"quoteStyle": "single",
-			"trailingCommas": "es5",
-			"semicolons": "always"
-		}
-	}
-}