@cubis/foundry 0.3.82 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/javascript-best-practices/evals/assertions.md

@@ -1,33 +0,0 @@
-# JavaScript Best Practices - Eval Assertions
-
-## Eval 1: ESM Module Migration
-
-This eval tests the skill's ability to guide a CommonJS-to-ESM migration for a dual-format library.
-
-### Assertions
-
-1. **Sets "type": "module" in package.json** -- The migration must establish ESM as the default module format. Without this, `.js` files are treated as CJS by Node.js, which defeats the purpose of the migration.
-
-2. **Configures dual-format exports** -- The `"exports"` field in `package.json` must map both `"import"` (for ESM consumers) and `"require"` (for CJS consumers) conditions. This is the standard mechanism for libraries that need to support both ecosystems during the transition period.
-
-3. **Replaces require() with import and handles __dirname** -- The actual code changes must convert `require()` to `import` statements and replace `__dirname`/`__filename` with `import.meta.url` + `URL` or `path.dirname(fileURLToPath(import.meta.url))`. These are the most common migration stumbling blocks.
-
-4. **Addresses barrel exports and tree-shaking** -- A production-grade migration considers the public API surface. Barrel files that blindly re-export everything prevent bundlers from tree-shaking unused code. The guidance should recommend explicit exports.
-
-5. **Includes testing for both formats** -- A dual-format package that only tests one format will ship broken code. The response should mention testing or verifying that both CJS `require()` and ESM `import` resolve correctly against the published package.
-
-## Eval 2: Cross-Runtime Data Processing
-
-This eval tests the skill's ability to design a concurrent, cancellable data pipeline that works across Node.js and Deno.
-
-### Assertions
-
-1. **Uses AbortSignal for cancellation** -- Structured cancellation via `AbortController`/`AbortSignal` is the cross-runtime standard. The signal must be threaded through the entire fetch chain so that all in-flight requests are cancelled when the user aborts.
-
-2. **Implements retry with backoff** -- Transient failures (HTTP 429, 503, network errors) should be retried with exponential backoff. The retry logic must check the abort signal before retrying, so cancellation is not delayed by retry waits.
-
-3. **Limits concurrency to 5** -- Unbounded `Promise.all()` over hundreds of URLs will exhaust connections and memory. A semaphore, queue, or pool pattern must cap active requests at 5 while keeping the pipeline flowing.
-
-4. **Handles runtime-specific file I/O** -- File writing differs between Node.js (`node:fs`) and Deno (`Deno.writeFile`). The response should use runtime detection, conditional imports, or an abstraction layer to handle this difference.
-
-5. **Uses lazy data processing** -- Processing paginated data should use async generators, `for await...of`, or `ReadableStream` rather than collecting all pages into an array first. This prevents OOM on large datasets.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/javascript-best-practices/evals/evals.json

@@ -1,32 +0,0 @@
-{
-  "skill_name": "javascript-best-practices",
-  "platform": "claude-code",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "I have a Node.js Express API that uses CommonJS require() throughout. I need to migrate it to ESM modules. The project also needs to work as a library consumed by both ESM and CJS users. Show me how to restructure the package.json, update the module imports, and set up dual-format exports.",
-      "expected_output": "A migration plan with package.json exports field configuration for dual ESM/CJS, updated import statements, and guidance on handling __dirname/__filename replacements in ESM.",
-      "files": [],
-      "assertions": [
-        "Sets \"type\": \"module\" in package.json or explains the ESM entry point strategy",
-        "Configures the \"exports\" field with both \"import\" and \"require\" conditions for dual-format support",
-        "Replaces require() calls with import statements and explains __dirname replacement using import.meta.url",
-        "Addresses barrel exports and tree-shaking implications for the library surface",
-        "Includes or references testing the dual-format output to verify both CJS and ESM consumers work"
-      ]
-    },
-    {
-      "id": 2,
-      "prompt": "I'm building a data processing service that needs to run on both Node.js and Deno. It fetches paginated data from a REST API, transforms each page, and writes results to a file. I need it to handle cancellation (user presses Ctrl+C), retry transient failures, and limit concurrency to 5 parallel requests. Show me how to write this cross-runtime.",
-      "expected_output": "A cross-runtime implementation using fetch(), AbortSignal for cancellation, async generators for pagination, a concurrency limiter, and conditional runtime-specific file I/O.",
-      "files": [],
-      "assertions": [
-        "Uses AbortController/AbortSignal for cancellation with signal propagation through the fetch chain",
-        "Implements retry logic with exponential backoff that respects the abort signal",
-        "Limits concurrent requests to 5 using a semaphore or queue pattern rather than unbounded Promise.all",
-        "Uses runtime detection or conditional imports for file system operations (node:fs vs Deno.writeFile)",
-        "Uses async generators or ReadableStream for paginated data processing instead of loading all pages into memory"
-      ]
-    }
-  ]
-}

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/javascript-best-practices/examples/01-esm-cjs-migration.md

@@ -1,93 +0,0 @@
-# Example: Migrating a CommonJS Library to Dual-Format ESM/CJS
-
-## Scenario
-
-A utility library `@acme/http-utils` is published as CommonJS. Consumers are migrating to ESM, but some still use CJS. The library needs to ship both formats from a single source.
-
-## Before (CommonJS only)
-
-```javascript
-// package.json
-{
-  "name": "@acme/http-utils",
-  "main": "src/index.js"
-}
-
-// src/index.js
-const { URL } = require('url');
-const fetch = require('node-fetch');
-
-const buildUrl = (base, path, params) => {
-  const url = new URL(path, base);
-  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
-  return url.toString();
-};
-
-const fetchJson = async (url) => {
-  const res = await fetch(url);
-  if (!res.ok) throw new Error(`HTTP ${res.status}`);
-  return res.json();
-};
-
-module.exports = { buildUrl, fetchJson };
-```
-
-## After (Dual ESM/CJS)
-
-### package.json
-
-```json
-{
-  "name": "@acme/http-utils",
-  "version": "2.0.0",
-  "type": "module",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "files": ["dist"],
-  "engines": { "node": ">=22.0.0" },
-  "scripts": {
-    "build": "tsup src/index.js --format esm,cjs --clean",
-    "test": "vitest run",
-    "test:cjs": "node --eval \"const { buildUrl } = require('./dist/index.cjs'); console.log(buildUrl('https://api.example.com', '/users', { page: '1' }))\""
-  }
-}
-```
-
-### src/index.js (ESM source)
-
-```javascript
-// No more require() -- use native fetch and URL (available in Node 22+)
-// No more node-fetch dependency
-
-export const buildUrl = (base, path, params = {}) => {
-  const url = new URL(path, base);
-  for (const [key, value] of Object.entries(params)) {
-    url.searchParams.set(key, String(value));
-  }
-  return url.toString();
-};
-
-export const fetchJson = async (url, { signal } = {}) => {
-  const response = await fetch(url, { signal });
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}: ${response.statusText}`, {
-      cause: { status: response.status, url },
-    });
-  }
-  return response.json();
-};
-```
-
-## Key Decisions
-
-1. **`"type": "module"`** makes all `.js` files ESM by default. CJS output uses `.cjs` extension.
-2. **`"exports"` field** with `import` and `require` conditions lets Node resolve the right format automatically.
-3. **Native `fetch` and `URL`** eliminate the `node-fetch` and `url` dependencies (Node 22+ has both globally).
-4. **`{ signal }` parameter** on `fetchJson` enables cancellation via `AbortController`.
-5. **`Error` with `cause`** preserves the original error context for debugging.
-6. **tsup** handles the dual-format build from a single ESM source, generating both `.js` (ESM) and `.cjs` (CJS) outputs.
-7. **`test:cjs` script** verifies the CJS output works, catching dual-format packaging bugs before publish.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/javascript-best-practices/examples/02-cross-runtime-pipeline.md

@@ -1,158 +0,0 @@
-# Example: Cross-Runtime Data Pipeline with Cancellation
-
-## Scenario
-
-A CLI tool fetches paginated data from a REST API, transforms each record, and writes results to a JSONL file. It must work on both Node.js and Deno, handle Ctrl+C gracefully, retry transient failures, and limit concurrency to avoid overloading the API.
-
-## Implementation
-
-### pipeline.js
-
-```javascript
-// Cross-runtime file writing abstraction
-const writeFile = async (path, data) => {
-  if (typeof Deno !== 'undefined') {
-    await Deno.writeTextFile(path, data);
-  } else {
-    const { writeFile: fsWrite } = await import('node:fs/promises');
-    await fsWrite(path, data, 'utf-8');
-  }
-};
-
-// Concurrency limiter -- caps parallel operations at `limit`
-const createPool = (limit) => {
-  let active = 0;
-  const queue = [];
-
-  return async (fn) => {
-    while (active >= limit) {
-      await new Promise((resolve) => queue.push(resolve));
-    }
-    active++;
-    try {
-      return await fn();
-    } finally {
-      active--;
-      queue.shift()?.();
-    }
-  };
-};
-
-// Retry with exponential backoff that respects abort signals
-const fetchWithRetry = async (url, signal, maxRetries = 3) => {
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      const response = await fetch(url, { signal });
-      if (response.status === 429 || response.status >= 500) {
-        if (attempt === maxRetries) {
-          throw new Error(`HTTP ${response.status} after ${maxRetries} retries`);
-        }
-        const delay = Math.min(1000 * 2 ** attempt, 10_000);
-        await new Promise((resolve, reject) => {
-          const timer = setTimeout(resolve, delay);
-          signal?.addEventListener('abort', () => {
-            clearTimeout(timer);
-            reject(signal.reason);
-          }, { once: true });
-        });
-        continue;
-      }
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-      }
-      return response.json();
-    } catch (error) {
-      if (error.name === 'AbortError') throw error;
-      if (attempt === maxRetries) throw error;
-    }
-  }
-};
-
-// Async generator for paginated data -- processes one page at a time
-async function* fetchPages(baseUrl, signal) {
-  let cursor = null;
-  let hasMore = true;
-
-  while (hasMore) {
-    const url = cursor
-      ? `${baseUrl}?cursor=${encodeURIComponent(cursor)}`
-      : baseUrl;
-
-    const page = await fetchWithRetry(url, signal);
-    yield page.items;
-
-    cursor = page.nextCursor;
-    hasMore = Boolean(cursor);
-  }
-}
-
-// Transform records in parallel with concurrency limit
-const processPage = async (items, pool, signal) => {
-  const tasks = items.map((item) =>
-    pool(async () => {
-      signal?.throwIfAborted();
-      return {
-        id: item.id,
-        name: item.name.trim().toLowerCase(),
-        processedAt: new Date().toISOString(),
-      };
-    })
-  );
-  return Promise.all(tasks);
-};
-
-// Main pipeline
-const run = async () => {
-  const controller = new AbortController();
-  const { signal } = controller;
-
-  // Handle Ctrl+C
-  const onShutdown = () => {
-    console.log('\nShutting down gracefully...');
-    controller.abort(new Error('User cancelled'));
-  };
-
-  if (typeof Deno !== 'undefined') {
-    Deno.addSignalListener('SIGINT', onShutdown);
-  } else {
-    process.on('SIGINT', onShutdown);
-  }
-
-  const pool = createPool(5);
-  const lines = [];
-
-  try {
-    for await (const items of fetchPages('https://api.example.com/records', signal)) {
-      const processed = await processPage(items, pool, signal);
-      for (const record of processed) {
-        lines.push(JSON.stringify(record));
-      }
-      console.log(`Processed ${lines.length} records...`);
-    }
-
-    await writeFile('output.jsonl', lines.join('\n') + '\n');
-    console.log(`Done. Wrote ${lines.length} records to output.jsonl`);
-  } catch (error) {
-    if (error.name === 'AbortError' || error.message === 'User cancelled') {
-      // Write partial results on cancellation
-      if (lines.length > 0) {
-        await writeFile('output.partial.jsonl', lines.join('\n') + '\n');
-        console.log(`Cancelled. Wrote ${lines.length} partial records.`);
-      }
-    } else {
-      throw error;
-    }
-  }
-};
-
-run();
-```
-
-## Key Decisions
-
-1. **Runtime detection** for file I/O uses `typeof Deno !== 'undefined'` rather than user-agent sniffing. `fetch()` is available natively in both runtimes.
-2. **AbortSignal propagation** flows from the top-level controller through every fetch call and into the processing pool, ensuring immediate cleanup on Ctrl+C.
-3. **Retry backoff respects the abort signal** -- the delay `setTimeout` is cancelled if the signal fires, preventing cancelled operations from waiting through retry delays.
-4. **Async generator `fetchPages`** processes one page at a time, keeping memory usage proportional to page size rather than total dataset size.
-5. **Concurrency pool** limits to 5 parallel operations using a simple semaphore pattern, preventing connection exhaustion against the API.
-6. **Partial result writes** on cancellation ensure that work already completed is not lost.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/javascript-best-practices/references/async-patterns.md

@@ -1,296 +0,0 @@
-# Async Patterns Reference
-
-## AbortController and AbortSignal
-
-### Basic Cancellation
-
-```javascript
-const controller = new AbortController();
-const { signal } = controller;
-
-// Cancel after 5 seconds
-const timeout = setTimeout(() => controller.abort(), 5_000);
-
-try {
-  const response = await fetch('/api/data', { signal });
-  clearTimeout(timeout);
-  return await response.json();
-} catch (error) {
-  if (error.name === 'AbortError') {
-    console.log('Request was cancelled');
-    return null;
-  }
-  throw error;
-}
-```
-
-### AbortSignal.timeout (ES2024)
-
-```javascript
-// Built-in timeout signal -- no manual AbortController needed
-const response = await fetch('/api/data', {
-  signal: AbortSignal.timeout(5_000),
-});
-```
-
-### AbortSignal.any -- Composing Multiple Signals
-
-```javascript
-// Cancel on either user action OR timeout
-const userController = new AbortController();
-
-const signal = AbortSignal.any([
-  userController.signal,           // User clicks "Cancel"
-  AbortSignal.timeout(30_000),     // 30-second deadline
-]);
-
-try {
-  const data = await fetchLargeDataset('/api/export', { signal });
-} catch (error) {
-  if (error.name === 'AbortError') {
-    // Determine which signal triggered
-    console.log('Operation cancelled or timed out');
-  }
-}
-```
-
-### Propagating Signals Through Call Chains
-
-```javascript
-// Thread the signal through every async operation
-const fetchUserWithPosts = async (userId, { signal } = {}) => {
-  const user = await fetchJson(`/users/${userId}`, { signal });
-
-  // Check signal before starting the next operation
-  signal?.throwIfAborted();
-
-  const posts = await fetchJson(`/users/${userId}/posts`, { signal });
-  return { user, posts };
-};
-```
-
-## Retry with Exponential Backoff
-
-```javascript
-const retry = async (fn, { maxAttempts = 3, baseDelay = 1_000, signal } = {}) => {
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return await fn({ signal });
-    } catch (error) {
-      // Never retry abort errors
-      if (error.name === 'AbortError') throw error;
-
-      // Don't retry on the last attempt
-      if (attempt === maxAttempts) throw error;
-
-      // Exponential backoff with jitter
-      const delay = baseDelay * 2 ** (attempt - 1) + Math.random() * 500;
-      await abortableDelay(delay, signal);
-    }
-  }
-};
-
-// Delay that can be cancelled
-const abortableDelay = (ms, signal) =>
-  new Promise((resolve, reject) => {
-    signal?.throwIfAborted();
-    const timer = setTimeout(resolve, ms);
-    signal?.addEventListener('abort', () => {
-      clearTimeout(timer);
-      reject(signal.reason);
-    }, { once: true });
-  });
-```
-
-## Concurrency Limiting
-
-### Semaphore Pattern
-
-```javascript
-class Semaphore {
-  #permits;
-  #queue = [];
-
-  constructor(permits) {
-    this.#permits = permits;
-  }
-
-  async acquire() {
-    if (this.#permits > 0) {
-      this.#permits--;
-      return;
-    }
-    await new Promise((resolve) => this.#queue.push(resolve));
-  }
-
-  release() {
-    const next = this.#queue.shift();
-    if (next) {
-      next();
-    } else {
-      this.#permits++;
-    }
-  }
-
-  async run(fn) {
-    await this.acquire();
-    try {
-      return await fn();
-    } finally {
-      this.release();
-    }
-  }
-}
-
-// Usage: process 100 URLs with max 5 concurrent requests
-const semaphore = new Semaphore(5);
-const results = await Promise.all(
-  urls.map((url) => semaphore.run(() => fetch(url)))
-);
-```
-
-### Pool Pattern with Results
-
-```javascript
-const pool = async (tasks, concurrency) => {
-  const results = new Array(tasks.length);
-  let index = 0;
-
-  const worker = async () => {
-    while (index < tasks.length) {
-      const i = index++;
-      results[i] = await tasks[i]();
-    }
-  };
-
-  await Promise.all(Array.from({ length: concurrency }, worker));
-  return results;
-};
-```
-
-## Async Generators for Streaming Data
-
-### Paginated API Consumer
-
-```javascript
-async function* fetchAllPages(baseUrl, { signal } = {}) {
-  let cursor = undefined;
-
-  while (true) {
-    signal?.throwIfAborted();
-
-    const url = new URL(baseUrl);
-    if (cursor) url.searchParams.set('cursor', cursor);
-
-    const response = await fetch(url, { signal });
-    if (!response.ok) throw new Error(`HTTP ${response.status}`);
-
-    const page = await response.json();
-    yield* page.items;  // Yield individual items, not pages
-
-    if (!page.nextCursor) break;
-    cursor = page.nextCursor;
-  }
-}
-
-// Consumer processes one item at a time -- constant memory
-for await (const item of fetchAllPages('https://api.example.com/items', { signal })) {
-  await processItem(item);
-}
-```
-
-### Transform Pipeline with Generators
-
-```javascript
-async function* map(source, fn) {
-  for await (const item of source) {
-    yield fn(item);
-  }
-}
-
-async function* filter(source, predicate) {
-  for await (const item of source) {
-    if (predicate(item)) yield item;
-  }
-}
-
-async function* batch(source, size) {
-  let chunk = [];
-  for await (const item of source) {
-    chunk.push(item);
-    if (chunk.length >= size) {
-      yield chunk;
-      chunk = [];
-    }
-  }
-  if (chunk.length > 0) yield chunk;
-}
-
-// Compose a pipeline
-const items = fetchAllPages(url, { signal });
-const active = filter(items, (item) => item.status === 'active');
-const transformed = map(active, (item) => ({ ...item, processedAt: Date.now() }));
-const batches = batch(transformed, 50);
-
-for await (const chunk of batches) {
-  await bulkInsert(chunk);
-}
-```
-
-## Explicit Resource Management (ES2024)
-
-```javascript
-class DatabaseConnection {
-  #connection;
-
-  static async open(url) {
-    const conn = new DatabaseConnection();
-    conn.#connection = await connect(url);
-    return conn;
-  }
-
-  async query(sql, params) {
-    return this.#connection.query(sql, params);
-  }
-
-  // Async dispose -- called automatically by `await using`
-  async [Symbol.asyncDispose]() {
-    await this.#connection.close();
-  }
-}
-
-// Connection is automatically closed when scope exits
-async function getUser(id) {
-  await using db = await DatabaseConnection.open(DATABASE_URL);
-  return db.query('SELECT * FROM users WHERE id = $1', [id]);
-  // db[Symbol.asyncDispose]() called automatically here
-}
-```
-
-## Promise Combinator Selection Guide
-
-| Combinator | Behavior | Use When |
-| --- | --- | --- |
-| `Promise.all(ps)` | Resolves when ALL resolve; rejects on FIRST rejection | All results needed, fail-fast on any error |
-| `Promise.allSettled(ps)` | Resolves when ALL settle (resolve or reject) | Need all outcomes, partial failure acceptable |
-| `Promise.race(ps)` | Settles with FIRST settled promise | Timeout racing, cache vs network |
-| `Promise.any(ps)` | Resolves with FIRST fulfilled; rejects if ALL reject | Redundant sources, fastest mirror |
-
-## Event Loop Yielding for Long Tasks
-
-```javascript
-// Yield to the event loop in CPU-intensive loops
-const processLargeArray = async (items, batchSize = 1_000) => {
-  const results = [];
-  for (let i = 0; i < items.length; i += batchSize) {
-    const batch = items.slice(i, i + batchSize);
-    results.push(...batch.map(transform));
-
-    // Yield to prevent blocking the event loop
-    if (i + batchSize < items.length) {
-      await scheduler?.yield?.() ?? new Promise((r) => setTimeout(r, 0));
-    }
-  }
-  return results;
-};
-```