@cubis/foundry 0.3.83 → 0.3.84

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

@@ -1,81 +0,0 @@
----
-name: javascript-best-practices
-description: "Use when writing, refactoring, or reviewing modern JavaScript across Node.js, Bun, Deno, and browsers, including modules, async orchestration, compatibility, bundling, and testing."
----
-# JavaScript Best Practices
-
-## Purpose
-
-Production-grade guidance for modern JavaScript development targeting ES2024+ features across all major runtimes (Node.js 22+, Bun, Deno, and browsers). Covers module architecture, async patterns with structured cancellation, runtime-aware API selection, bundling for tree-shaking, and testing strategies that work across environments.
-
-## When to Use
-
-- Writing new JavaScript modules, services, or libraries.
-- Migrating CommonJS codebases to ESM or dual-format packages.
-- Building code that must run across Node.js, Bun, Deno, or browsers.
-- Designing async pipelines with cancellation, retry, and backpressure.
-- Optimizing bundle size, startup time, or runtime performance.
-- Establishing testing and linting standards for a JavaScript project.
-
-## Instructions
-
-1. **Identify the target runtime(s) before writing any code** because Node.js, Bun, Deno, and browsers expose different global APIs, module resolution rules, and performance characteristics. Pin the minimum runtime version in `package.json` engines or `deno.json` and use it to gate feature choices.
-
-2. **Use ESM as the default module format** because it enables static analysis, tree-shaking, and top-level await. Set `"type": "module"` in `package.json`. For libraries that must support CJS consumers, use a dual-export strategy with `"exports"` field mapping `"import"` and `"require"` conditions. Do not mix `require()` and `import` in the same module because it creates resolution ambiguity.
-
-3. **Structure modules around single responsibilities with explicit public APIs** because barrel files that re-export everything defeat tree-shaking and increase bundle size. Export only the intended public surface from `index.js`. Keep internal helpers in unexported files. Use `package.json` `"exports"` to enforce encapsulation.
-
-4. **Prefer native runtime APIs over third-party equivalents** because they reduce dependency surface and improve performance. Use `fetch()` (available in Node 22+, Bun, Deno, browsers), `crypto.subtle` for hashing, `structuredClone()` for deep copies, `URL` and `URLSearchParams` for URL handling. Check runtime availability with feature detection, not user-agent sniffing.
-
-5. **Design async flows with AbortSignal for cancellation and timeout** because uncontrolled async operations leak resources and cause cascading failures. Pass `AbortSignal` through the entire call chain. Use `AbortSignal.timeout(ms)` for deadline-based cancellation. Use `AbortSignal.any()` to compose multiple cancellation sources. Always check `signal.aborted` before expensive operations in loops.
-
-6. **Choose the right Promise combinator for the concurrency model** because incorrect choice causes either premature failure or unnecessary waiting. Use `Promise.all()` when all results are needed and any failure should abort. Use `Promise.allSettled()` when partial results are acceptable. Use `Promise.any()` for redundant sources. Use `Promise.race()` for timeout racing. Limit concurrency with semaphore patterns when fan-out could exhaust connections.
-
-7. **Handle errors at boundaries, not everywhere** because scattered try-catch obscures control flow. Catch at HTTP handler level, CLI entry point, or queue consumer. Let errors propagate through intermediate layers. Use custom error classes with `cause` chaining (`new Error('msg', { cause })`) for root-cause tracing. Never swallow errors silently.
-
-8. **Use iterators and generators for lazy data processing** because loading entire datasets into memory causes OOM in production. Use `for await...of` with async generators for paginated APIs. Use `ReadableStream` and `TransformStream` for byte-level processing. In Node.js, prefer `pipeline()` from `node:stream/promises` for backpressure-safe piping.
-
-9. **Configure bundling for the deployment target** because server bundles and browser bundles have different optimization goals. Use Vite or esbuild for browser builds with code-splitting via dynamic `import()`. Use `--conditions` flags for runtime-specific export resolution. Externalize `node:*` built-ins in server bundles. Enable source maps in production for debugging without shipping unminified code.
-
-10. **Write tests that run in the target runtime** because cross-runtime bugs hide when tests only run in Node. Use Vitest for browser and Node testing with its built-in coverage. Use `node:test` for zero-dependency Node-only testing. Use `Deno.test()` in Deno projects. Mock timers, fetch, and filesystem at the test runner level, not with global monkey-patches.
-
-11. **Lint and format with zero-config-first tooling** because configuration sprawl causes inconsistency across contributors. Use Biome for combined linting and formatting (faster than ESLint + Prettier). If ESLint is required, use flat config (`eslint.config.js`) with `@eslint/js` recommended rules. Enable `no-unused-vars`, `no-floating-promises` (via typescript-eslint if TS is present), and `eqeqeq`.
-
-12. **Use `structuredClone()` instead of JSON parse/stringify round-trips** because `structuredClone` handles `Date`, `RegExp`, `Map`, `Set`, `ArrayBuffer`, and circular references correctly. Use the `transfer` option for zero-copy handoff of `ArrayBuffer` to workers.
-
-13. **Isolate side effects at module edges** because top-level side effects prevent tree-shaking, break test isolation, and make modules order-dependent. Initialize connections, register handlers, and read environment variables in explicit setup functions, not at import time.
-
-14. **Use `using` declarations (ES2024 Explicit Resource Management) for deterministic cleanup** because manual `try/finally` is error-prone and verbose. Implement `Symbol.dispose` or `Symbol.asyncDispose` on resources that need cleanup (database connections, file handles, temp directories). Use `await using` for async cleanup in server code.
-
-15. **Validate all external input at system boundaries** because trusting unvalidated data causes injection, type confusion, and crashes. Use schema validation (Zod, Valibot, or AJV) at API endpoints, CLI argument parsing, and configuration loading. Return structured error responses with field-level details.
-
-16. **Profile before optimizing and optimize the right layer** because micro-benchmarks mislead when the bottleneck is I/O or architecture. Use Chrome DevTools Performance tab for browser code, `node --prof` and `clinic.js` for Node, and `Deno.bench()` for Deno. Focus on reducing allocations in hot loops and eliminating unnecessary serialization round-trips.
-
-## Output Format
-
-Produces JavaScript code using ESM modules, native runtime APIs, explicit async error handling with AbortSignal, and structured resource management. Includes runtime-conditional logic where cross-platform support is needed. Code uses `const`/`let` (never `var`), optional chaining, nullish coalescing, and modern syntax appropriate to the target runtime.
-
-## References
-
-| File | Load when |
-| --- | --- |
-| `references/modules-bundling.md` | ESM/CJS migration, dual-format packages, tree-shaking, or bundler configuration is needed. |
-| `references/runtime-apis.md` | Choosing between Node, Bun, Deno, or browser APIs, or writing cross-runtime code. |
-| `references/async-patterns.md` | Cancellation, retry, concurrency limiting, streaming, or generator patterns need detail. |
-| `references/testing.md` | Setting up test runners, mocking strategies, or cross-runtime test execution. |
-| `references/performance.md` | Profiling, memory optimization, startup time, or bundle size reduction. |
-
-## Codex Platform Notes
-
-- Codex supports native subagents via `.codex/agents/*.toml` files with `name`, `description`, and `developer_instructions`.
-- Each subagent TOML can specify `model` and `model_reasoning_effort` to optimize cost per task difficulty:
-  - Light tasks (exploration, docs): `model = "gpt-5.3-codex-spark"`, `model_reasoning_effort = "medium"`
-  - Heavy tasks (security audit, orchestration): `model = "gpt-5.4"`, `model_reasoning_effort = "high"`
-  - Standard tasks (implementation): inherit parent model (omit `model` field).
-- Built-in agents: `default`, `worker`, `explorer`. Custom agents extend these via TOML definitions.
-- Codex operates under network restrictions — skills should not assume outbound HTTP access.
-- Use `$ARGUMENTS` to access user-provided arguments when the skill is invoked.
-- All skill guidance executes within the sandbox; file I/O is confined to the workspace.
-- Skills are installed at `.agents/skills/<skill-id>/SKILL.md`. Workflow skills can also be compiled to `.agents/skills/<workflow-id>/SKILL.md` as `generatedSkills`.
-- Codex supports three autonomy levels: `suggest`, `auto-edit`, `full-auto`.
-- MCP skill tools are available when the Cubis Foundry MCP server is connected.

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.