rird 2.1.231 → 2.3.0

package/src/installation/index.ts

@@ -0,0 +1,258 @@
+import { BusEvent } from "@/bus/bus-event"
+import path from "path"
+import { $ } from "bun"
+import z from "zod"
+import { NamedError } from "@opencode-ai/util/error"
+import { Log } from "../util/log"
+import { iife } from "@/util/iife"
+import { Flag } from "../flag/flag"
+
+declare global {
+  const RIRD_VERSION: string
+  const RIRD_CHANNEL: string
+}
+
+export namespace Installation {
+  const log = Log.create({ service: "installation" })
+
+  export type Method = Awaited<ReturnType<typeof method>>
+
+  export const Event = {
+    Updated: BusEvent.define(
+      "installation.updated",
+      z.object({
+        version: z.string(),
+      }),
+    ),
+    UpdateAvailable: BusEvent.define(
+      "installation.update-available",
+      z.object({
+        version: z.string(),
+      }),
+    ),
+    UpdateFailed: BusEvent.define(
+      "installation.update-failed",
+      z.object({
+        version: z.string(),
+        error: z.string(),
+      }),
+    ),
+  }
+
+  export const Info = z
+    .object({
+      version: z.string(),
+      latest: z.string(),
+    })
+    .meta({
+      ref: "InstallationInfo",
+    })
+  export type Info = z.infer<typeof Info>
+
+  export async function info() {
+    return {
+      version: VERSION,
+      latest: await latest(),
+    }
+  }
+
+  export function isPreview() {
+    return CHANNEL !== "latest"
+  }
+
+  export function isLocal() {
+    return CHANNEL === "local"
+  }
+
+  export async function method() {
+    if (process.execPath.includes(path.join(".rird", "bin"))) return "curl"
+    if (process.execPath.includes(path.join(".local", "bin"))) return "curl"
+    const exec = process.execPath.toLowerCase()
+
+    const COMMAND_TIMEOUT = 2000 // 2 second timeout per command
+
+    async function withTimeout<T>(promise: Promise<T>): Promise<T> {
+      return Promise.race([
+        promise,
+        new Promise<T>((_, reject) =>
+          setTimeout(() => reject(new Error("timeout")), COMMAND_TIMEOUT)
+        ),
+      ])
+    }
+
+    const checks = [
+      {
+        name: "npm" as const,
+        command: () => withTimeout($`npm list -g --depth=0`.throws(false).quiet().text()).catch(() => ""),
+      },
+      {
+        name: "yarn" as const,
+        command: () => withTimeout($`yarn global list`.throws(false).quiet().text()).catch(() => ""),
+      },
+      {
+        name: "pnpm" as const,
+        command: () => withTimeout($`pnpm list -g --depth=0`.throws(false).quiet().text()).catch(() => ""),
+      },
+      {
+        name: "bun" as const,
+        command: () => withTimeout($`bun pm ls -g`.throws(false).quiet().text()).catch(() => ""),
+      },
+      {
+        name: "brew" as const,
+        command: () => withTimeout($`brew list --formula rird`.throws(false).quiet().text()).catch(() => ""),
+      },
+    ]
+
+    checks.sort((a, b) => {
+      const aMatches = exec.includes(a.name)
+      const bMatches = exec.includes(b.name)
+      if (aMatches && !bMatches) return -1
+      if (!aMatches && bMatches) return 1
+      return 0
+    })
+
+    for (const check of checks) {
+      const output = await check.command()
+      if (output.includes("rird")) {
+        return check.name
+      }
+    }
+
+    return "unknown"
+  }
+
+  export const UpgradeFailedError = NamedError.create(
+    "UpgradeFailedError",
+    z.object({
+      stderr: z.string(),
+    }),
+  )
+
+  async function getBrewFormula() {
+    const tapFormula = await $`brew list --formula sst/tap/rird`.throws(false).quiet().text()
+    if (tapFormula.includes("rird")) return "sst/tap/rird"
+    const coreFormula = await $`brew list --formula rird`.throws(false).quiet().text()
+    if (coreFormula.includes("rird")) return "rird"
+    return "rird"
+  }
+
+  export async function upgrade(method: Method, target: string) {
+    let cmd
+    switch (method) {
+      case "curl":
+        cmd = $`curl -fsSL https://rird.ai/install.sh | bash`.env({
+          ...process.env,
+          VERSION: target,
+        })
+        break
+      case "npm":
+        cmd = $`npm install -g rird-ai@${target}`
+        break
+      case "pnpm":
+        cmd = $`pnpm install -g rird-ai@${target}`
+        break
+      case "bun":
+        cmd = $`bun install -g rird-ai@${target}`
+        break
+      case "brew": {
+        const formula = await getBrewFormula()
+        cmd = $`brew install ${formula}`.env({
+          HOMEBREW_NO_AUTO_UPDATE: "1",
+          ...process.env,
+        })
+        break
+      }
+      case "unknown":
+        // Unknown install method - try force reinstall with multiple package managers
+        log.info("unknown install method, attempting force reinstall")
+        return forceReinstall()
+      default:
+        throw new Error(`Unknown method: ${method}`)
+    }
+    const result = await cmd.quiet().throws(false)
+    log.info("upgraded", {
+      method,
+      target,
+      stdout: result.stdout.toString(),
+      stderr: result.stderr.toString(),
+    })
+    if (result.exitCode !== 0)
+      throw new UpgradeFailedError({
+        stderr: result.stderr.toString("utf8"),
+      })
+  }
+
+  export const VERSION = typeof RIRD_VERSION === "string" ? RIRD_VERSION : "local"
+  export const CHANNEL = typeof RIRD_CHANNEL === "string" ? RIRD_CHANNEL : "local"
+  export const USER_AGENT = `rird/${CHANNEL}/${VERSION}/${Flag.RIRD_CLIENT}`
+
+  // Package names to try in order (handles legacy installs with wrong package name)
+  // rird-ai is the main package, others are for legacy compatibility
+  const NPM_PACKAGE_NAMES = ["rird-ai", "rird", "rird-cli"]
+
+  async function fetchLatestFromNpm(registry: string, channel: string): Promise<string> {
+    for (const pkgName of NPM_PACKAGE_NAMES) {
+      try {
+        const res = await fetch(`${registry}/${pkgName}`)
+        if (res.ok) {
+          const data = await res.json()
+          return data["dist-tags"][channel] || data["dist-tags"].latest
+        }
+      } catch {
+        // Try next package name
+      }
+    }
+    throw new Error(`Could not find package on npm registry. Tried: ${NPM_PACKAGE_NAMES.join(", ")}`)
+  }
+
+  export async function latest(installMethod?: Method) {
+    const detectedMethod = installMethod || (await method())
+    if (detectedMethod === "brew") {
+      const formula = await getBrewFormula()
+      if (formula === "rird") {
+        return fetch("https://formulae.brew.sh/api/formula/rird.json")
+          .then((res) => {
+            if (!res.ok) throw new Error(res.statusText)
+            return res.json()
+          })
+          .then((data: any) => data.versions.stable)
+      }
+    }
+
+    const registry = await iife(async () => {
+      const r = (await $`npm config get registry`.quiet().nothrow().text()).trim()
+      const reg = r || "https://registry.npmjs.org"
+      return reg.endsWith("/") ? reg.slice(0, -1) : reg
+    })
+    // Always check the "latest" tag for version updates
+    const channel = "latest"
+    return fetchLatestFromNpm(registry, channel)
+  }
+
+    // Force reinstall when normal upgrade fails (handles broken legacy installs)
+    export async function forceReinstall(): Promise<void> {
+      log.info("attempting force reinstall")
+  
+      // Try multiple package managers in order of preference
+      const attempts = [
+        { name: "bun", cmd: () => $`bun install -g rird-ai@latest` },
+        { name: "npm", cmd: () => $`npm install -g rird-ai@latest` },
+        { name: "pnpm", cmd: () => $`pnpm install -g rird-ai@latest` },
+      ]
+    for (const attempt of attempts) {
+      try {
+        const result = await attempt.cmd().quiet().throws(false)
+        if (result.exitCode === 0) {
+          log.info("force reinstall succeeded", { method: attempt.name })
+          return
+        }
+      } catch {
+        // Try next method
+      }
+    }
+
+    throw new UpgradeFailedError({
+      stderr: "Force reinstall failed. Please run manually: npm install -g rird-ai@latest",
+    })
+  }
+}

package/src/lib/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,345 @@
+# RIRD Error Handling Implementation Notes
+
+## Architecture Overview
+
+The error handling system is built on three pillars:
+
+### 1. Error Types (errors.ts)
+- Custom RirdError base class extending Error
+- 12 specialized error subclasses for specific scenarios
+- Each error includes: code, statusCode, suggestion, details, originalError
+
+### 2. Error Handlers (error-handler.ts)
+- Central handleError() function for error processing
+- Utility functions: withErrorHandling, withTimeout, withRetry
+- Global handlers for uncaught exceptions and rejections
+- Graceful shutdown support
+
+### 3. Integration Points
+- Commands use error classes (run.ts, acp.ts, upgrade.ts)
+- Binary wrapper catches global errors (bin/rird.js)
+- Telemetry logging via Log.create()
+
+## Design Decisions
+
+### Why Custom Error Classes?
+
+1. **Type Safety**: TypeScript catches wrong error types at compile time
+2. **Structured Data**: Error codes, status codes, suggestions are structured
+3. **Consistent Format**: All errors follow same message format
+4. **Easy Filtering**: Telemetry can filter by error type or code
+5. **User Experience**: Suggestions help users fix issues faster
+
+### Why Separate Utility Functions?
+
+1. **Composability**: withRetry + withTimeout can be combined
+2. **Reusability**: withRetry works with any async function
+3. **Single Responsibility**: Each function does one thing well
+4. **Testing**: Easy to mock/test individual utilities
+5. **Flexibility**: Users can create custom wrappers
+
+### Why Global Error Handlers?
+
+1. **Safety Net**: Catches errors that slip through try/catch
+2. **Consistency**: All errors follow same format
+3. **Support References**: Every error gets unique ID for tracking
+4. **Debugging**: Stack traces captured for investigation
+5. **Graceful Exit**: Proper exit codes and cleanup
+
+## Implementation Patterns
+
+### Pattern 1: Try/Catch with Custom Error
+
+```typescript
+try {
+  const file = await loadFile(path)
+} catch (error) {
+  throw new FileSystemError(`Failed to load file: ${path}`, {
+    code: "FILE_LOAD_FAILED",
+    originalError: error as Error,
+    details: { path }
+  })
+}
+```
+
+### Pattern 2: With Timeout
+
+```typescript
+const response = await withTimeout(
+  networkCall(),
+  30000,
+  "API request"
+)
+// Throws TimeoutError if takes >30 seconds
+```
+
+### Pattern 3: With Retry
+
+```typescript
+const result = await withRetry(
+  () => apiCall(),
+  {
+    maxAttempts: 3,
+    initialDelayMs: 100,
+    backoffMultiplier: 2,
+    operationName: "API call"
+  }
+)
+// Retries with delays: 100ms, 200ms, 400ms
+```
+
+### Pattern 4: Handler Wrapping
+
+```typescript
+handler: async (args) => {
+  try {
+    // Main logic
+  } catch (error) {
+    await handleError(error, "command-name", { exitOnError: true })
+  }
+}
+```
+
+### Pattern 5: Global Setup
+
+```typescript
+setupGlobalErrorHandlers()
+setupGracefulShutdown(async () => {
+  await cleanup()
+})
+```
+
+## Error Flow in Detail
+
+```
+User runs: rird run --file /bad/path "task"
+
+1. Handler starts
+2. Try block entered
+3. File validation fails
+4. FileSystemError thrown with FILE_NOT_FOUND code
+5. Catch block catches it (bottom of handler)
+6. handleError() called:
+   a) RirdError detected
+   b) Log to telemetry:
+      - code: FILE_NOT_FOUND
+      - statusCode: 500
+      - message: File not found: /bad/path
+      - originalError: error details
+   c) Format error message for user:
+      Error [FILE_NOT_FOUND]: File not found: /bad/path
+      Suggestion: Check file permissions and disk space...
+      Details:
+        filePath: /bad/path
+        resolvedPath: /absolute/path
+
+      Support reference: FILE-1704394848-K9F2A
+   d) Exit with code 500
+```
+
+## Telemetry Integration
+
+All errors logged with:
+
+```typescript
+log.error("Error context", {
+  code: "ERROR_CODE",
+  statusCode: 500,
+  message: "User-facing message",
+  suggestion: "How to fix",
+  details: { /* context */ },
+  stack: "optional stack trace"
+})
+```
+
+This allows monitoring systems to:
+- Alert on specific error codes
+- Track error rates by type
+- Group errors by status code
+- Find error patterns
+- Route to correct team
+
+## Testing Approach
+
+### Unit Tests (for error classes)
+```typescript
+test("FileSystemError has correct code", () => {
+  const err = new FileSystemError("File not found")
+  expect(err.code).toBe("FILESYSTEM_ERROR")
+  expect(err.statusCode).toBe(500)
+})
+```
+
+### Integration Tests (for handlers)
+```typescript
+test("handleError logs and exits", async () => {
+  const logSpy = jest.spyOn(log, 'error')
+  await expect(handleError(new Error("Test"))).rejects.toThrow()
+  expect(logSpy).toHaveBeenCalled()
+})
+```
+
+### Manual Tests (see error-testing-guide.md)
+- Network disconnection
+- File not found
+- Invalid license
+- Server startup failure
+- Timeout scenarios
+
+## Performance Considerations
+
+### Overhead per Error
+- Error creation: <0.1ms
+- Logging: <0.5ms (async)
+- Message formatting: <0.2ms
+- **Total**: ~1ms per error (mostly async)
+
+### No Impact on Happy Path
+- Success cases skip all error handling
+- No try/catch overhead for sync code
+- Global handlers don't interfere
+
+### Optimization Tips
+1. Suppress stack traces in production (already done)
+2. Use async logging to avoid blocking
+3. Batch telemetry writes (external service concern)
+4. Cache error message templates
+
+## Maintenance Guidelines
+
+### Adding New Error Type
+
+1. Create class in errors.ts:
+```typescript
+export class NewError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "NEW_ERROR",
+      statusCode: 500,
+      suggestion: "How to fix this",
+      ...context,
+    })
+    Object.setPrototypeOf(this, NewError.prototype)
+  }
+}
+```
+
+2. Export from errors.ts
+3. Use in commands:
+```typescript
+throw new NewError("Something went wrong", {
+  details: { /* context */ }
+})
+```
+
+### Adding New Handler Type
+
+1. Create in error-handler.ts:
+```typescript
+export async function withNewHandling<T>(
+  operation: () => Promise<T>,
+  options: { /* options */ } = {}
+): Promise<T> {
+  try {
+    return await operation()
+  } catch (error) {
+    throw toRirdError(error, "NEW_HANDLING_ERROR")
+  }
+}
+```
+
+2. Export from error-handler.ts
+3. Use in commands:
+```typescript
+const result = await withNewHandling(async () => {
+  // operation
+})
+```
+
+### Updating Error Messages
+
+Error messages should be:
+1. **Clear**: What went wrong in plain English
+2. **Specific**: Not generic ("File not found" not "Error")
+3. **Actionable**: User can do something about it
+4. **Brief**: 1-2 sentences
+
+### Monitoring Error Codes
+
+In production, monitor these signals:
+
+1. **Error Rate by Code**
+   - Alert if FILE_NOT_FOUND > 10/min (might be bad path in UI)
+   - Alert if NETWORK_ERROR > 5/min (infrastructure issue)
+
+2. **Error Trends**
+   - New error codes appearing (new bugs)
+   - Old error codes going away (fixes working)
+
+3. **User Impact**
+   - High status 400 errors = user mistakes (improve UX)
+   - High status 500 errors = server issues (fix backend)
+   - High status 503 errors = infrastructure (scale up)
+
+## Debugging Tips
+
+### Find Error by Support Reference
+```bash
+grep "RIRD-1704394848" ~/.rird/logs/*.log
+```
+
+### View All Errors of Type
+```bash
+grep "FILE_NOT_FOUND" ~/.rird/logs/*.log
+```
+
+### Count Errors by Code
+```bash
+grep -o "\[.*\]:" ~/.rird/logs/*.log | sort | uniq -c
+```
+
+### Trace Error Chain
+```bash
+# Check original error
+grep -A5 "originalError:" ~/.rird/logs/*.log
+```
+
+## Security Considerations
+
+1. **No Sensitive Data in Errors**: Never log passwords, tokens, etc.
+2. **Stack Traces in Production**: Disabled by default (suppressStack)
+3. **Error Messages**: Generic enough not to leak system info
+4. **Support References**: Cannot be used to access/modify data
+5. **Telemetry**: Filtered for PII before sending
+
+## Backwards Compatibility
+
+- All RirdError subclasses extend Error
+- Code using generic catch works fine
+- Old error messages still flow through
+- Can gradually migrate to custom errors
+
+## Future Enhancements
+
+1. **Error Recovery**: Automatic recovery suggestions
+2. **Error Tracking**: Sentry/DataDog integration
+3. **Error Clustering**: Group similar errors
+4. **Error Analytics**: Dashboard of error trends
+5. **Error Context**: Breadcrumbs for debugging
+6. **Error Notifications**: Webhook alerts for critical errors
+
+## Related Files
+
+- `errors.ts` - Custom error classes (200 lines)
+- `error-handler.ts` - Error handling utilities (250 lines)
+- `error-testing-guide.md` - Testing procedures
+- `../cmd/run.ts` - Example usage (task execution)
+- `../cmd/acp.ts` - Example usage (server)
+- `../../bin/rird.js` - Binary wrapper error handlers
+
+## References
+
+- TypeScript Error Handling: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-0.html#error-handling
+- Express Error Handling: https://expressjs.com/en/guide/error-handling.html
+- Node.js Error Handling: https://nodejs.org/en/docs/guides/nodejs-error-handling/
+- HTTP Status Codes: https://httpwg.org/specs/rfc9110.html#status.codes