oh-my-customcode 0.49.0 → 0.50.0

package/templates/.claude/skills/systematic-debugging/condition-based-waiting-example.ts

@@ -0,0 +1,278 @@
+// Source: https://github.com/tmdgusya/engineering-disciplines (MIT License)
+// Complete implementation of condition-based waiting utilities
+
+import { access, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// ============================================================
+// Core waitUntil implementation
+// ============================================================
+
+export interface WaitOptions {
+  /** Maximum wait time in milliseconds. Default: 5000 */
+  timeout?: number;
+  /** Polling interval in milliseconds. Default: 100 */
+  interval?: number;
+  /** Error message to show on timeout */
+  message?: string;
+}
+
+/**
+ * Waits until the condition returns true, polling at the specified interval.
+ * Throws a timeout error if the condition is not met within the timeout period.
+ *
+ * @example
+ * // Wait for a file to exist
+ * await waitUntil(
+ *   () => fileExists('/path/to/file'),
+ *   { timeout: 5000, message: 'File was not created' }
+ * );
+ */
+export async function waitUntil(
+  condition: () => boolean | Promise<boolean>,
+  options: WaitOptions = {}
+): Promise<void> {
+  const { timeout = 5000, interval = 100, message = 'Condition was not met' } = options;
+  const deadline = Date.now() + timeout;
+
+  while (Date.now() < deadline) {
+    const result = await condition();
+    if (result) return;
+    await sleep(interval);
+  }
+
+  throw new Error(`waitUntil timeout after ${timeout}ms: ${message}`);
+}
+
+/**
+ * Waits until the condition returns a truthy value (not undefined/null/false),
+ * then returns that value.
+ *
+ * @example
+ * const record = await waitFor(
+ *   () => db.find({ id: 'expected-id' }),
+ *   { timeout: 3000, message: 'Record was not created' }
+ * );
+ */
+export async function waitFor<T>(
+  condition: () => T | Promise<T>,
+  options: WaitOptions = {}
+): Promise<T> {
+  const { timeout = 5000, interval = 100, message = 'Value was not available' } = options;
+  const deadline = Date.now() + timeout;
+
+  while (Date.now() < deadline) {
+    const result = await condition();
+    if (result) return result;
+    await sleep(interval);
+  }
+
+  throw new Error(`waitFor timeout after ${timeout}ms: ${message}`);
+}
+
+// ============================================================
+// Common condition helpers
+// ============================================================
+
+/**
+ * Returns true if the file exists and is accessible.
+ */
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if the file exists and has content (size > 0).
+ */
+export async function fileHasContent(filePath: string): Promise<boolean> {
+  try {
+    const stats = await stat(filePath);
+    return stats.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if the file exists and contains the expected text.
+ */
+export async function fileContains(filePath: string, text: string): Promise<boolean> {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    return content.includes(text);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if the HTTP endpoint responds with a successful status code.
+ */
+export async function httpEndpointReady(url: string): Promise<boolean> {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(1000) });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if all files in the list exist.
+ */
+export async function allFilesExist(filePaths: string[]): Promise<boolean> {
+  const results = await Promise.all(filePaths.map(fileExists));
+  return results.every(Boolean);
+}
+
+// ============================================================
+// Convenience waiters
+// ============================================================
+
+/**
+ * Waits for a file to exist.
+ *
+ * @example
+ * await waitForFile('/path/to/output.json', { timeout: 5000 });
+ */
+export async function waitForFile(filePath: string, options: WaitOptions = {}): Promise<void> {
+  await waitUntil(() => fileExists(filePath), {
+    timeout: 5000,
+    message: `File not created: ${filePath}`,
+    ...options,
+  });
+}
+
+/**
+ * Waits for a file to contain specific text.
+ *
+ * @example
+ * await waitForFileContent('/path/to/log.txt', 'Server started', { timeout: 10000 });
+ */
+export async function waitForFileContent(
+  filePath: string,
+  text: string,
+  options: WaitOptions = {}
+): Promise<void> {
+  await waitUntil(() => fileContains(filePath, text), {
+    timeout: 5000,
+    message: `File ${filePath} did not contain: ${text}`,
+    ...options,
+  });
+}
+
+/**
+ * Waits for an HTTP endpoint to respond with a successful status.
+ *
+ * @example
+ * await waitForServer('http://localhost:3000/health', { timeout: 15000 });
+ */
+export async function waitForServer(url: string, options: WaitOptions = {}): Promise<void> {
+  await waitUntil(() => httpEndpointReady(url), {
+    timeout: 15000,
+    interval: 300,
+    message: `Server at ${url} did not become ready`,
+    ...options,
+  });
+}
+
+/**
+ * Waits for a directory to contain at least minCount files.
+ *
+ * @example
+ * await waitForDirectoryCount('/output/dir', 3, { timeout: 5000 });
+ */
+export async function waitForDirectoryCount(
+  dirPath: string,
+  minCount: number,
+  options: WaitOptions = {}
+): Promise<void> {
+  const { readdir } = await import('node:fs/promises');
+  await waitUntil(
+    async () => {
+      try {
+        const entries = await readdir(dirPath);
+        return entries.length >= minCount;
+      } catch {
+        return false;
+      }
+    },
+    {
+      timeout: 5000,
+      message: `Directory ${dirPath} did not reach ${minCount} files`,
+      ...options,
+    }
+  );
+}
+
+// ============================================================
+// Utilities
+// ============================================================
+
+/**
+ * Sleep for the specified number of milliseconds.
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ============================================================
+// Usage examples (not for import, documentation only)
+// ============================================================
+
+/*
+// Example 1: Wait for build output file
+await waitForFile(join(outputDir, 'bundle.js'), { timeout: 30000 });
+
+// Example 2: Wait for server to start
+await waitForServer('http://localhost:8080/health', { timeout: 20000 });
+
+// Example 3: Wait for database record with custom condition
+const user = await waitFor(
+  async () => {
+    const u = await db.users.findUnique({ where: { email: 'test@example.com' } });
+    return u?.emailVerified ? u : null;
+  },
+  { timeout: 5000, message: 'User email was not verified' }
+);
+
+// Example 4: Wait for process output
+const logs: string[] = [];
+const proc = spawn('npm', ['start']);
+proc.stdout.on('data', (chunk) => logs.push(chunk.toString()));
+
+await waitUntil(
+  () => logs.some((line) => line.includes('Listening on port')),
+  { timeout: 15000, interval: 200, message: 'Server did not log startup message' }
+);
+
+// Example 5: Wait for all output files to be generated
+const expectedFiles = ['report.json', 'summary.txt', 'data.csv'].map((f) =>
+  join(outputDir, f)
+);
+await waitUntil(() => allFilesExist(expectedFiles), {
+  timeout: 10000,
+  message: `Not all output files were generated in ${outputDir}`,
+});
+
+// Example 6: Test that verifies count reaches expected value
+it('should process all items', async () => {
+  await triggerBatchProcessing(items);
+
+  await waitUntil(
+    async () => {
+      const processed = await db.items.count({ where: { status: 'done' } });
+      return processed >= items.length;
+    },
+    { timeout: 5000, message: `Expected ${items.length} items to be processed` }
+  );
+
+  const processed = await db.items.count({ where: { status: 'done' } });
+  expect(processed).toBe(items.length);
+});
+*/

package/templates/.claude/skills/systematic-debugging/condition-based-waiting.md

@@ -0,0 +1,240 @@
+# Condition-Based Waiting
+
+<!-- Source: https://github.com/tmdgusya/engineering-disciplines (MIT License) -->
+
+## Overview
+
+Arbitrary delays (`sleep`, `setTimeout`, `await new Promise(r => setTimeout(r, 1000))`) are a debugging anti-pattern. They hide timing issues, make tests slow, and still fail intermittently.
+
+**Core principle:** Replace arbitrary delays with condition-based polling that waits for the actual state you need.
+
+## When to Use
+
+**Use when:**
+- Tests use `await sleep(1000)` or similar arbitrary waits
+- Code has `setTimeout` for "giving time" to async operations
+- Tests are flaky because timing depends on system speed
+- You need to wait for: file to exist, process to start, server to be ready, database record to appear
+
+## The Problem with Arbitrary Delays
+
+```typescript
+// ❌ Arbitrary delay - fragile and slow
+await fs.writeFile(path, content);
+await sleep(500); // "Give it time to write"
+const result = await fs.readFile(path);
+
+// Problems:
+// 1. 500ms may not be enough on slow systems
+// 2. 500ms is always wasted on fast systems
+// 3. The actual condition (file readable) is never verified
+```
+
+## The Solution: Condition-Based Waiting
+
+```typescript
+// ✓ Condition-based - fast and reliable
+await fs.writeFile(path, content);
+await waitUntil(() => fs.access(path).then(() => true).catch(() => false));
+const result = await fs.readFile(path);
+
+// Benefits:
+// 1. Proceeds as soon as condition is met (fast on fast systems)
+// 2. Has a timeout for safety (catches real failures)
+// 3. The actual condition is explicit and verified
+```
+
+## Core Implementation
+
+```typescript
+interface WaitOptions {
+  timeout?: number;      // Max wait time in ms (default: 5000)
+  interval?: number;     // Poll interval in ms (default: 100)
+  message?: string;      // Error message on timeout
+}
+
+async function waitUntil(
+  condition: () => boolean | Promise<boolean>,
+  options: WaitOptions = {}
+): Promise<void> {
+  const { timeout = 5000, interval = 100, message = 'Condition not met' } = options;
+  const deadline = Date.now() + timeout;
+
+  while (Date.now() < deadline) {
+    const result = await condition();
+    if (result) return;
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+
+  throw new Error(`waitUntil timeout after ${timeout}ms: ${message}`);
+}
+```
+
+See `condition-based-waiting-example.ts` for the complete implementation with all utilities.
+
+## Common Patterns
+
+### Wait for File to Exist
+
+```typescript
+// ❌ Arbitrary delay
+await triggerFileCreation();
+await sleep(1000);
+const content = await fs.readFile(outputPath, 'utf-8');
+
+// ✓ Condition-based
+await triggerFileCreation();
+await waitUntil(
+  () => fs.access(outputPath).then(() => true).catch(() => false),
+  { timeout: 5000, message: `File not created: ${outputPath}` }
+);
+const content = await fs.readFile(outputPath, 'utf-8');
+```
+
+### Wait for Process to Start
+
+```typescript
+// ❌ Arbitrary delay
+startServer();
+await sleep(2000); // "Give server time to start"
+const response = await fetch('http://localhost:3000/health');
+
+// ✓ Condition-based
+startServer();
+await waitUntil(
+  async () => {
+    try {
+      const res = await fetch('http://localhost:3000/health');
+      return res.ok;
+    } catch {
+      return false;
+    }
+  },
+  { timeout: 10000, message: 'Server did not start within 10s' }
+);
+const response = await fetch('http://localhost:3000/health');
+```
+
+### Wait for Database Record
+
+```typescript
+// ❌ Arbitrary delay
+await triggerAsyncOperation();
+await sleep(500);
+const record = await db.find({ id: expectedId });
+
+// ✓ Condition-based
+await triggerAsyncOperation();
+await waitUntil(
+  async () => {
+    const record = await db.find({ id: expectedId });
+    return record !== null;
+  },
+  { timeout: 3000, message: `Record ${expectedId} not created` }
+);
+const record = await db.find({ id: expectedId });
+```
+
+### Wait for Log Output
+
+```typescript
+// ❌ Arbitrary delay
+process.spawn('my-command');
+await sleep(1000);
+expect(logOutput).toContain('Server started');
+
+// ✓ Condition-based
+const logOutput: string[] = [];
+const proc = process.spawn('my-command');
+proc.stdout.on('data', (chunk) => logOutput.push(chunk.toString()));
+
+await waitUntil(
+  () => logOutput.some(line => line.includes('Server started')),
+  { timeout: 10000, message: 'Server start message not seen in logs' }
+);
+```
+
+### Wait for Count to Reach Expected Value
+
+```typescript
+// ❌ Arbitrary delay
+await triggerBatchOperation();
+await sleep(2000);
+const items = await db.findAll();
+expect(items.length).toBe(10);
+
+// ✓ Condition-based
+await triggerBatchOperation();
+await waitUntil(
+  async () => {
+    const items = await db.findAll();
+    return items.length >= 10;
+  },
+  { timeout: 5000, message: 'Batch did not complete: expected 10 items' }
+);
+const items = await db.findAll();
+expect(items.length).toBe(10);
+```
+
+## Choosing Timeout and Interval Values
+
+| Scenario | Timeout | Interval | Rationale |
+|----------|---------|----------|-----------|
+| File write | 2s | 50ms | Fast local I/O |
+| Process start | 10s | 200ms | Process startup varies |
+| HTTP server ready | 15s | 300ms | Server may need to compile |
+| Database record | 3s | 100ms | DB writes are fast |
+| CI environment | 2-3x local | same | CI is often slower |
+
+**Rule of thumb:**
+- Interval: 10-20% of expected wait time, minimum 50ms
+- Timeout: 3-5x the typical wait time
+- Add a buffer for CI: multiply timeout by 2-3x
+
+## Testing the Waiters Themselves
+
+```typescript
+// Test that waitUntil resolves when condition becomes true
+it('resolves when condition becomes true', async () => {
+  let ready = false;
+  setTimeout(() => { ready = true; }, 100);
+
+  await expect(
+    waitUntil(() => ready, { timeout: 1000 })
+  ).resolves.toBeUndefined();
+});
+
+// Test that waitUntil rejects on timeout
+it('rejects with timeout error when condition never met', async () => {
+  await expect(
+    waitUntil(() => false, { timeout: 100, message: 'test condition' })
+  ).rejects.toThrow('waitUntil timeout after 100ms: test condition');
+});
+```
+
+## Migration Guide
+
+When refactoring existing `sleep` calls:
+
+1. **Identify what the sleep is "waiting for"** — read surrounding code
+2. **Find the observable state change** — what becomes true when the operation completes?
+3. **Replace with `waitUntil(condition)`** — poll for that state
+4. **Set appropriate timeout** — 3-5x the typical wait time
+5. **Add descriptive message** — what should have happened?
+
+```typescript
+// Before
+await startProcess();
+await sleep(2000);
+checkResult();
+
+// After - step 1: what is sleep waiting for? Process to be ready.
+// After - step 2: observable state? Process responds to health check.
+// After - step 3-5:
+await startProcess();
+await waitUntil(
+  () => isProcessReady(),
+  { timeout: 10000, message: 'Process did not become ready' }
+);
+checkResult();
+```