safeword 0.2.4 → 0.2.5

package/packages/cli/ARCHITECTURE.md

@@ -1,279 +0,0 @@
-# Safeword CLI Architecture
-
-**Version:** 1.0
-**Last Updated:** 2025-11-27
-**Status:** Design
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Tech Stack](#tech-stack)
-- [Project Structure](#project-structure)
-- [Key Decisions](#key-decisions)
-- [Best Practices](#best-practices)
-- [Migration Strategy](#migration-strategy)
-
----
-
-## Overview
-
-The Safeword CLI is a TypeScript Node.js application that replaces bash scripts for project setup, verification, and maintenance. It provides commands for setting up development environments with linting, Claude Code hooks, and configuration management.
-
-**Design Philosophy:**
-
-- **npx-first**: Always run via npx for latest version
-- **Stateless**: No global config, all state in project files
-- **Idempotent**: Safe to re-run commands (with appropriate guards)
-- **Non-interactive capable**: Full functionality via flags for CI/automation
-
----
-
-## Tech Stack
-
-| Category    | Choice                 | Rationale                                          |
-| ----------- | ---------------------- | -------------------------------------------------- |
-| Language    | TypeScript 5.x         | Type safety, IDE support, matches target projects  |
-| Runtime     | Node.js 18+            | LTS, native fetch, stable fs/promises              |
-| Arg parsing | Commander.js           | Industry standard, TypeScript support, subcommands |
-| Build       | tsup                   | Fast, zero-config, ESM + CJS output                |
-| Testing     | Vitest                 | Fast, TypeScript-native, compatible with Node      |
-| Linting     | ESLint 9 (flat config) | What we install for users, dogfood ourselves       |
-
----
-
-## Project Structure
-
-```
-packages/cli/
-├── src/
-│   ├── cli.ts              # Entry point, arg parsing
-│   ├── commands/
-│   │   ├── setup.ts        # Setup command
-│   │   ├── check.ts        # Health check command
-│   │   ├── upgrade.ts      # Upgrade command
-│   │   ├── diff.ts         # Diff preview command
-│   │   └── reset.ts        # Reset/uninstall command
-│   ├── utils/
-│   │   ├── file-manager.ts # File operations
-│   │   ├── hook-manager.ts # Claude + git hooks
-│   │   ├── prompter.ts     # Interactive prompts
-│   │   ├── project-detector.ts # Project type detection
-│   │   ├── linting-setup.ts    # ESLint/Prettier config
-│   │   └── output.ts       # Colored output, spinners
-│   └── templates/          # Bundled templates (copied to .safeword/)
-├── tests/
-│   ├── commands/           # Integration tests per command
-│   └── utils/              # Unit tests for utilities
-├── ARCHITECTURE.md         # This file
-├── package.json
-└── tsconfig.json
-```
-
----
-
-## Key Decisions
-
-### Decision 1: TypeScript over JavaScript
-
-**Status:** Active
-**Date:** 2025-11-27
-
-| Field          | Value                                                                                                                  |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| What           | Write CLI in TypeScript, compile to JavaScript for distribution                                                        |
-| Why            | Type safety catches bugs early, better IDE support, self-documents interfaces. Target users are TypeScript developers. |
-| Trade-off      | Build step required, but tsup makes this trivial                                                                       |
-| Alternatives   | Pure JS (rejected: lose type safety), Bun (rejected: not ubiquitous enough)                                            |
-| Implementation | `packages/cli/src/**/*.ts`                                                                                             |
-
-### Decision 2: ESM-only
-
-**Status:** Active
-**Date:** 2025-11-27
-
-| Field          | Value                                                                      |
-| -------------- | -------------------------------------------------------------------------- |
-| What           | Package uses `"type": "module"`, tsup outputs ESM only                     |
-| Why            | Node 18+ has full ESM support, CJS adds bloat for shrinking use case       |
-| Trade-off      | Won't work with very old tooling that requires CJS                         |
-| Alternatives   | CJS-only (rejected: legacy), dual ESM+CJS (rejected: unnecessary bloat)    |
-| Implementation | `tsup.config.ts`: `format: ['esm']`                                        |
-
-### Decision 3: Bundle templates in package
-
-**Status:** Active
-**Date:** 2025-11-27
-
-| Field          | Value                                                                   |
-| -------------- | ----------------------------------------------------------------------- |
-| What           | Ship `.safeword/` templates as part of npm package, copy on setup       |
-| Why            | Works offline, version-locked to CLI, no network dependency for setup   |
-| Trade-off      | Larger package (~500KB), templates update requires CLI update           |
-| Alternatives   | Fetch from GitHub (rejected: network dependency, version mismatch risk) |
-| Implementation | `src/templates/` copied to dist, read at runtime                        |
-
-### Decision 4: Commander.js for CLI framework
-
-**Status:** Active
-**Date:** 2025-11-27
-
-| Field          | Value                                                                                                     |
-| -------------- | --------------------------------------------------------------------------------------------------------- |
-| What           | Use Commander.js for argument parsing, help generation, subcommands                                       |
-| Why            | Most popular (40k+ stars), excellent TypeScript support, minimal bundle impact                            |
-| Trade-off      | External dependency, but arg parsing complexity justifies it                                              |
-| Alternatives   | yargs (rejected: heavier), meow (rejected: less TypeScript support), manual (rejected: reinventing wheel) |
-| Implementation | `src/cli.ts`                                                                                              |
-
-### Decision 5: Vitest for testing
-
-**Status:** Active
-**Date:** 2025-11-27
-
-| Field          | Value                                                                           |
-| -------------- | ------------------------------------------------------------------------------- |
-| What           | Use Vitest for unit and integration tests                                       |
-| Why            | Fast, TypeScript-native, watch mode, compatible with Node fs operations         |
-| Trade-off      | Another test runner to know (but API is Jest-compatible)                        |
-| Alternatives   | Jest (rejected: slower, config heavy), Node test runner (rejected: less mature) |
-| Implementation | `tests/**/*.test.ts`                                                            |
-
-### Decision 6: No runtime dependencies beyond Commander
-
-**Status:** Active
-**Date:** 2025-11-27
-
-| Field          | Value                                                                             |
-| -------------- | --------------------------------------------------------------------------------- |
-| What           | Minimize runtime deps - only Commander.js, use Node built-ins for everything else |
-| Why            | Faster install, fewer security audit concerns, smaller attack surface             |
-| Trade-off      | May need to implement utilities that libraries provide                            |
-| Alternatives   | Use chalk, ora, inquirer, etc. (rejected: bloat for simple CLI)                   |
-| Implementation | Use Node readline for prompts, ANSI codes directly for colors                     |
-
----
-
-## Best Practices
-
-### Error Handling Pattern
-
-**What:** Use custom error classes with exit codes
-**Why:** Consistent error handling, testable exit behavior
-**Example:** See `src/utils/errors.ts`
-
-```typescript
-// Define error types
-class SafewordError extends Error {
-  constructor(
-    message: string,
-    public exitCode: number = 1,
-  ) {
-    super(message);
-  }
-}
-
-class SetupError extends SafewordError {}
-class ConfigError extends SafewordError {}
-
-// Use in commands
-try {
-  await setup(options);
-} catch (e) {
-  if (e instanceof SafewordError) {
-    console.error(e.message);
-    process.exit(e.exitCode);
-  }
-  throw e; // Re-throw unexpected errors
-}
-```
-
-### File Operations Pattern
-
-**What:** Always use async fs operations, handle errors explicitly
-**Why:** Non-blocking, better error messages
-**Example:** See `src/utils/file-manager.ts`
-
-```typescript
-import { readFile, writeFile, mkdir } from 'fs/promises';
-
-async function safeWrite(path: string, content: string): Promise<void> {
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, content, 'utf-8');
-}
-```
-
-### Output Pattern
-
-**What:** Use symbols for status, no emoji by default
-**Why:** Works in all terminals, professional appearance
-**Example:** See `src/utils/output.ts`
-
-```typescript
-const symbols = {
-  success: '✓',
-  warning: '⚠',
-  error: '✗',
-  info: '→',
-};
-
-function success(msg: string) {
-  console.log(`${symbols.success} ${msg}`);
-}
-```
-
----
-
-## Migration Strategy
-
-### From Bash Scripts to CLI
-
-**Trigger:** User has existing bash-based safeword setup
-**Steps:**
-
-1. User runs `npx safeword upgrade`
-2. CLI detects `.safeword/` exists
-3. CLI overwrites all files with bundled templates
-4. CLI updates hooks in `.claude/settings.json`
-5. CLI preserves user's AGENTS.md content (only updates link)
-
-**Rollback:** Run `npx safeword reset`, then re-run old bash scripts
-
-### Future: v1 to v2
-
-**Trigger:** Breaking changes to template structure or hook format
-**Steps:**
-
-1. v2 CLI detects v1 version in `.safeword/version`
-2. Runs migration logic before normal upgrade
-3. Updates version file to v2
-
-**Rollback:** Document breaking changes, provide migration guide
-
----
-
-## Appendix
-
-### References
-
-- [Design Doc](../../.safeword/planning/design/005-cli-implementation.md)
-- [User Stories](../../.safeword/planning/user-stories/005-cli-implementation.md)
-- [Test Definitions](../../.safeword/planning/test-definitions/005-cli-implementation.md)
-- [CLI UX Vision](../../.safeword/planning/011-cli-ux-vision.md)
-
-### Package.json (key fields)
-
-```json
-{
-  "name": "safeword",
-  "type": "module",
-  "bin": {
-    "safeword": "./dist/cli.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "files": ["dist", "templates"]
-}
-```

package/packages/cli/package.json

@@ -1,51 +0,0 @@
-{
-  "name": "safeword",
-  "version": "0.2.3",
-  "description": "CLI for setting up and managing safeword development environments",
-  "type": "module",
-  "bin": {
-    "safeword": "./dist/cli.js"
-  },
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "templates"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src tests",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm audit --audit-level=high && npm run build && npm test"
-  },
-  "dependencies": {
-    "commander": "^12.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.10.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^2.0.0"
-  },
-  "keywords": [
-    "cli",
-    "safeword",
-    "developer-experience",
-    "linting",
-    "claude-code"
-  ],
-  "author": "",
-  "license": "MIT"
-}

package/packages/cli/src/cli.ts

@@ -1,63 +0,0 @@
-#!/usr/bin/env node
-
-import { Command } from 'commander';
-import { VERSION } from './version.js';
-
-const program = new Command();
-
-program
-  .name('safeword')
-  .description('CLI for setting up and managing safeword development environments')
-  .version(VERSION);
-
-program
-  .command('setup')
-  .description('Set up safeword in the current project')
-  .option('-y, --yes', 'Accept all defaults (non-interactive mode)')
-  .action(async options => {
-    const { setup } = await import('./commands/setup.js');
-    await setup(options);
-  });
-
-program
-  .command('check')
-  .description('Check project health and versions')
-  .option('--offline', 'Skip remote version check')
-  .action(async options => {
-    const { check } = await import('./commands/check.js');
-    await check(options);
-  });
-
-program
-  .command('upgrade')
-  .description('Upgrade safeword configuration to latest version')
-  .action(async () => {
-    const { upgrade } = await import('./commands/upgrade.js');
-    await upgrade();
-  });
-
-program
-  .command('diff')
-  .description('Preview changes that would be made by upgrade')
-  .option('-v, --verbose', 'Show full diff output')
-  .action(async options => {
-    const { diff } = await import('./commands/diff.js');
-    await diff(options);
-  });
-
-program
-  .command('reset')
-  .description('Remove safeword configuration from project')
-  .option('-y, --yes', 'Skip confirmation prompt')
-  .action(async options => {
-    const { reset } = await import('./commands/reset.js');
-    await reset(options);
-  });
-
-// Show help if no arguments provided
-if (process.argv.length === 2) {
-  program.help();
-}
-
-// Parse arguments
-program.parse();

package/packages/cli/src/commands/check.ts

@@ -1,166 +0,0 @@
-/**
- * Check command - Verify project health and configuration
- */
-
-import { join } from 'node:path';
-import { VERSION } from '../version.js';
-import { exists, readFile, readFileSafe } from '../utils/fs.js';
-import { info, success, warn, header, keyValue } from '../utils/output.js';
-import { isNewerVersion } from '../utils/version.js';
-
-export interface CheckOptions {
-  offline?: boolean;
-}
-
-interface HealthStatus {
-  configured: boolean;
-  projectVersion: string | null;
-  cliVersion: string;
-  updateAvailable: boolean;
-  latestVersion: string | null;
-  issues: string[];
-}
-
-/**
- * Check for latest version from npm (with timeout)
- */
-async function checkLatestVersion(timeout = 3000): Promise<string | null> {
-  try {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
-
-    const response = await fetch('https://registry.npmjs.org/safeword/latest', {
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
-
-    if (!response.ok) return null;
-
-    const data = (await response.json()) as { version?: string };
-    return data.version ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check project configuration health
- */
-function checkHealth(cwd: string): HealthStatus {
-  const safewordDir = join(cwd, '.safeword');
-  const issues: string[] = [];
-
-  // Check if configured
-  if (!exists(safewordDir)) {
-    return {
-      configured: false,
-      projectVersion: null,
-      cliVersion: VERSION,
-      updateAvailable: false,
-      latestVersion: null,
-      issues: [],
-    };
-  }
-
-  // Read project version
-  const versionPath = join(safewordDir, 'version');
-  const projectVersion = readFileSafe(versionPath)?.trim() ?? null;
-
-  // Check for required files
-  const requiredFiles = ['SAFEWORD.md', 'version', 'hooks/agents-md-check.sh'];
-
-  for (const file of requiredFiles) {
-    if (!exists(join(safewordDir, file))) {
-      issues.push(`Missing: .safeword/${file}`);
-    }
-  }
-
-  // Check AGENTS.md link
-  const agentsMdPath = join(cwd, 'AGENTS.md');
-  if (exists(agentsMdPath)) {
-    const content = readFile(agentsMdPath);
-    if (!content.includes('@./.safeword/SAFEWORD.md')) {
-      issues.push('AGENTS.md missing safeword link');
-    }
-  } else {
-    issues.push('AGENTS.md file missing');
-  }
-
-  // Check .claude/settings.json
-  const settingsPath = join(cwd, '.claude', 'settings.json');
-  if (!exists(settingsPath)) {
-    issues.push('Missing: .claude/settings.json');
-  }
-
-  return {
-    configured: true,
-    projectVersion,
-    cliVersion: VERSION,
-    updateAvailable: false,
-    latestVersion: null,
-    issues,
-  };
-}
-
-export async function check(options: CheckOptions): Promise<void> {
-  const cwd = process.cwd();
-
-  header('Safeword Health Check');
-
-  const health = checkHealth(cwd);
-
-  // Not configured
-  if (!health.configured) {
-    info('Not configured. Run `safeword setup` to initialize.');
-    return;
-  }
-
-  // Show versions
-  keyValue('Safeword CLI', `v${health.cliVersion}`);
-  keyValue('Project config', health.projectVersion ? `v${health.projectVersion}` : 'unknown');
-
-  // Check for updates (unless offline)
-  if (!options.offline) {
-    info('\nChecking for updates...');
-    const latestVersion = await checkLatestVersion();
-
-    if (latestVersion) {
-      health.latestVersion = latestVersion;
-      health.updateAvailable = isNewerVersion(health.cliVersion, latestVersion);
-
-      if (health.updateAvailable) {
-        warn(`Update available: v${latestVersion}`);
-        info('Run `npm install -g safeword` to upgrade');
-      } else {
-        success('CLI is up to date');
-      }
-    } else {
-      warn("Couldn't check for updates (offline?)");
-    }
-  } else {
-    info('\nSkipped update check (offline mode)');
-  }
-
-  // Check project version vs CLI version
-  if (health.projectVersion && isNewerVersion(health.cliVersion, health.projectVersion)) {
-    warn(`Project config (v${health.projectVersion}) is newer than CLI (v${health.cliVersion})`);
-    info('Consider upgrading the CLI');
-  } else if (health.projectVersion && isNewerVersion(health.projectVersion, health.cliVersion)) {
-    info(`\nUpgrade available for project config`);
-    info(
-      `Run \`safeword upgrade\` to update from v${health.projectVersion} to v${health.cliVersion}`,
-    );
-  }
-
-  // Show issues
-  if (health.issues.length > 0) {
-    header('Issues Found');
-    for (const issue of health.issues) {
-      warn(issue);
-    }
-    info('\nRun `safeword upgrade` to repair configuration');
-  } else {
-    success('\nConfiguration is healthy');
-  }
-}