claude-toolkit 0.10.0 → 0.15.0

package/docs/skills/testing-patterns.md

@@ -1,6 +1,6 @@
 # Testing Patterns
 
-> Generic test-driven development practices and patterns applicable to any language or test framework.
+> Generic test-driven development practices and patterns applicable to any language or test framework. Use when writing tests, setting up a test suite, or deciding what to test at which layer
 
 **Type:** Core Skill (always included)
 **Source:** [`core/skills/ct-testing-patterns/SKILL.md`](../core/skills/ct-testing-patterns/SKILL.md)
@@ -11,77 +11,90 @@ Principles and patterns for writing tests that catch bugs, enable refactoring, a
 
 ## TDD Cycle: Red, Green, Refactor
 
-1. **Red** -- Write a failing test that describes the desired behavior. Confirm it fails for the right reason.
-2. **Green** -- Write the minimal code to make the test pass. Do not optimize yet.
-3. **Refactor** -- Improve the code while keeping all tests green. Remove duplication, improve naming, simplify logic.
+1. **Red** -- Write a failing test for the desired behavior. Confirm it fails for the right reason.
+2. **Green** -- Write the minimal code to make it pass. No optimization yet.
+3. **Refactor** -- Clean up while keeping tests green.
 
 Commit at each stage. The cycle keeps scope small and provides a safety net for every change.
 
-## Key Principles
+## 3-Layer Testing Strategy
 
-### Test Behavior, Not Implementation
+```
+          /  E2E  \           Real browsers, full user flows
+         /----------\
+        / Interaction \       Component sandbox, behavior, a11y
+       /----------------\
+      /      Unit        \    Pure logic, signals, utilities
+     /--------------------\
+```
+
+| Layer       | Target Ratio | What to Cover                                                                |
+| ----------- | ------------ | ---------------------------------------------------------------------------- |
+| Unit        | ~70%         | Business logic, utilities, data transforms, reactive primitives, error paths |
+| Interaction | ~20%         | Component variants, user interactions, accessibility, visual regression      |
+| E2E         | ~10%         | Critical user journeys, authentication flows, cross-page workflows           |
 
-Tests should describe *what* the code does, not *how* it does it internally.
+> **Scope:** This core skill owns the layering decision below, the unit and interaction layers, and the cross-cutting E2E principles. Runner-specific E2E setup and execution live in the stack skills (e.g. `ct-playwright-patterns`) when a matching stack is installed.
 
-- **Good:** "returns the user's full name when first and last name are provided"
-- **Bad:** "calls `String.prototype.concat` with first name and space and last name"
+### When to Use Which Layer
 
-### Factory Pattern for Test Data
+| Question                                          | Layer                                  |
+| ------------------------------------------------- | -------------------------------------- |
+| Does this logic need a DOM?                       | **Unit** if no, **Interaction** if yes |
+| Does it involve multiple pages or navigation?     | **E2E**                                |
+| Am I testing a single component's visual states?  | **Interaction**                        |
+| Am I testing a reactive primitive (signal, memo)? | **Unit**                               |
+| Does it require authentication or real network?   | **E2E**                                |
+| Am I testing component accessibility?             | **Interaction** (axe-core)             |
+| Does it need the full server running?             | **E2E**                                |
 
-Create factory functions that produce valid test objects with sensible defaults. Accept overrides for the fields relevant to each test.
+## Test Behavior, Not Implementation
+
+Test _what_ code does (public interface, observable outputs), not _how_ (internal state, call counts). Implementation-coupled tests break on every refactor.
+
+## Factory Pattern
 
 ```
 function getMockUser(overrides = {}) {
-  return {
-    id: "user-1",
-    email: "test@example.com",
-    name: "Test User",
-    role: "member",
-    createdAt: new Date("2024-01-01"),
-    ...overrides,
-  };
+  return { id: "user-1", email: "test@example.com", name: "Test User", role: "member", ...overrides };
 }
-
-// Usage: only specify what matters for this test
 const admin = getMockUser({ role: "admin" });
 ```
 
-### Test File Organization
+New required fields update the factory once, not every test.
 
-- **Co-locate tests with source** or mirror the source directory structure
-- **One test file per module** -- name it `module.test.ext` or `module.spec.ext`
-- **Group related tests** using `describe` blocks
-- **Use descriptive test names** that read as sentences
+## Organization
 
-### Mocking Strategies
+- Co-locate tests or mirror source structure. One test file per module (`module.test.ext`).
+- Group with `describe`, name as sentences: `it("rejects expired tokens")`.
 
-- **Prefer real dependencies** when feasible (in-memory database, local test server)
-- **Mock at boundaries** -- external services only, not internal modules
-- **Keep mocks minimal** -- only mock the methods your code actually calls
-- **Verify mock contracts** -- ensure mocks match real API behavior
-- **Reset mocks between tests** -- prevent shared state and order-dependent failures
+## Shared Principles
 
-## Test Categories
+- **Prefer role-based queries.** Use `getByRole`, `getByLabel`, `getByText` over test IDs or CSS selectors.
+- **Never sleep.** Use framework-provided waiting mechanisms (`waitFor`, `findBy*`, web-first assertions).
+- **One assertion focus per test.** Multiple assertions are fine if they verify facets of the same behavior.
+- **Isolate tests.** No test should depend on another test's side effects. Reset state between tests.
 
-| Category | Scope | Speed | Quantity |
-|---|---|---|---|
-| **Unit tests** | Single function or class | Fast | Many |
-| **Integration tests** | Multiple components together | Slower | Some |
-| **End-to-end tests** | Full user flow | Slowest | Few |
+## Mocking Rules
 
-The ratio should be roughly pyramid-shaped: many unit tests, some integration tests, few E2E tests.
+- Prefer real dependencies (in-memory DB, local server) when feasible.
+- Mock at boundaries only (external APIs, email, payments), not internal modules.
+- Keep mocks minimal -- only methods your code calls. Reset between tests.
+- Verify mocks match the real API. Update when APIs change.
 
 ## Property-Based Testing
 
-When a function has a contract ("for all valid inputs X, property Y holds"), use property-based tests to verify across generated inputs instead of hand-picked examples:
+When a function has a contract ("for all valid inputs X, property Y holds"), use property-based tests to verify it across generated inputs instead of hand-picked examples:
 
 ```typescript
 // Instead of testing 3-4 specific inputs:
 test("sort is idempotent", () => {
-  fc.assert(fc.property(fc.array(fc.integer()), (arr) => {
-    const sorted = mySort(arr);
-    expect(mySort(sorted)).toEqual(sorted);
-  }));
+  fc.assert(
+    fc.property(fc.array(fc.integer()), (arr) => {
+      const sorted = mySort(arr);
+      expect(mySort(sorted)).toEqual(sorted);
+    }),
+  );
 });
 ```
 
@@ -89,7 +102,7 @@ Good candidates: serialization round-trips, math properties, parsers, encoding/d
 
 ## Bun Test Runner
 
-Bun includes a built-in test runner with no additional dependencies:
+Bun includes a built-in test runner. Use `bun test` for projects on the Bun runtime:
 
 ```bash
 bun test                       # run all *.test.ts files
@@ -98,21 +111,30 @@ bun test --coverage            # with code coverage
 bun test path/to/file.test.ts  # single file
 ```
 
-Supports `describe`, `it`/`test`, `expect`, lifecycle hooks, and snapshot testing out of the box.
+Bun supports `describe`, `it`/`test`, `expect`, lifecycle hooks, and snapshot testing out of the box with no additional dependencies.
+
+## Test Speed
+
+Three levers recur across common runners (Vitest, Playwright, Storybook browser mode). Stated once here; each stack skill carries the framework-specific syntax.
+
+- **Parallelism sized to the runner.** Enable file-level parallelism (Vitest `fileParallelism`, Playwright `fullyParallel`), but cap workers to the runner's _real_ vCPUs (`"50%"` or a measured count). GitHub standard runners are 2 vCPU (private) / 4 (public); oversubscribing thrashes.
+- **Shard across CI jobs, then merge the blob reports.** Sharding splits at the _file_ level (`--shard=i/n`), so wall-clock is gated by the slowest shard -- balance file sizes. Always emit a blob report per shard (`--reporter=blob`) and merge it (`merge-reports` / `--merge-reports`) in a dependent job, or results and coverage are fragmented and incomplete.
+- **Skip isolation where state is clean.** Per-file environment isolation is the safe default but the biggest run-speed cost. Disable it (Vitest `isolate: false`, `pool: 'threads'`) only for side-effect-free logic suites; keep it where tests mutate globals/env/timers.
+
+Profile before tuning, and never `sleep` to mask timing -- use the framework's auto-waiting (see Shared Principles).
+
+Per-runner config (if the stack is installed): `ct-vite-vitest-patterns`, `ct-playwright-patterns`, `ct-storybook-patterns`.
 
-## Anti-patterns
+## Anti-Patterns
 
-| Anti-pattern | Description |
-|---|---|
-| **Testing implementation details** | Asserting on internal state or private methods. Breaks on every refactor. |
-| **Overmocking** | When most of the test is mock setup, you are testing mocks, not code. |
-| **Copy-paste test cases** | Duplicated test code becomes a maintenance burden. Use factories and parameterized tests. |
-| **No assertions** | A test that runs code but asserts nothing provides false confidence. |
-| **Ignoring flaky tests** | A sometimes-failing test is either wrong or exposing a real bug. Fix or delete it. |
-| **Testing only the happy path** | Error cases, edge cases, and boundary conditions are where bugs live. |
+1. **Testing implementation** -- Asserting internal state or call counts breaks on refactors.
+2. **Overmocking** -- If most of the test is mock setup, you're testing mocks.
+3. **Copy-paste tests** -- Use factories and parameterized tests.
+4. **No assertions** -- Worse than no test. False confidence.
+5. **Ignoring flaky tests** -- Fix or delete; never skip indefinitely.
+6. **Happy path only** -- Error cases and boundary conditions are where bugs live.
 
 ## Trigger Conditions
 
 - **Keywords:** `test`, `spec`, `tdd`, `mock`, `factory`
 - **File patterns:** `**/*.test.ts`, `**/*.spec.ts`
-- **Excludes:** "e2e", "end-to-end"

package/docs/skills/typescript-conventions.md

@@ -1,6 +1,6 @@
 # TypeScript Conventions
 
-> Strict TypeScript patterns for type safety, readability, and maintainable codebases.
+> Strict TypeScript patterns for type safety, readability, and maintainable codebases. Use when writing or reviewing TypeScript, adding or tightening types, or deciding between type and interface
 
 **Type:** Core Skill (always included)
 **Source:** [`core/skills/ct-typescript-conventions/SKILL.md`](../core/skills/ct-typescript-conventions/SKILL.md)
@@ -36,21 +36,29 @@ Never use `any`. It disables type checking entirely.
 - Use generics when the type varies but has a consistent shape
 - Use specific types when you know the data shape
 
-### Interface vs Type
+### Type vs Interface
 
-- **Prefer `interface`** for object shapes -- extendable, clearer error messages
-- **Use `type`** for unions, intersections, mapped types, and utility types
+- **Default to `type`.** It covers object shapes, unions, intersections, mapped types, and utility types.
+- **Use `interface` only when you need `extends`** (an inheritance hierarchy or declaration merging).
 
 ```typescript
-// Object shape: use interface
-interface User {
+// Default: use type for object shapes
+type User = {
   id: string;
   email: string;
   role: UserRole;
-}
+};
 
-// Union: use type
+// Unions, intersections, utilities: type
 type UserRole = "admin" | "member" | "guest";
+
+// interface only when you need extends
+interface Animal {
+  name: string;
+}
+interface Dog extends Animal {
+  breed: string;
+}
 ```
 
 ### `as const` for Literal Types
@@ -96,7 +104,7 @@ type AsyncState<T> =
 
 ### `satisfies` Operator
 
-Validate a value conforms to a type without widening its inferred type:
+Validate a value conforms to a type while keeping the value's own narrower inferred type instead of collapsing to the annotation. Here it preserves the exact key set (`home`, `user`) rather than the index signature `Record<string, Route>`:
 
 ```typescript
 type Route = { path: string; children?: Route[] };
@@ -106,7 +114,9 @@ const routes = {
   user: { path: "/user/:id", children: [{ path: "settings" }] },
 } satisfies Record<string, Route>;
 
-// routes.home.path is "/" (literal), not string
+// routes.home and routes.user are known keys -- not `Route | undefined` from the index signature.
+// Note: routes.home.path is `string`, NOT the literal "/", because `Route` declares `path: string`,
+// which widens the literal. To keep a literal, target a narrower type (e.g. a union) or add `as const`.
 ```
 
 ### `const` Type Parameters
@@ -115,6 +125,9 @@ Infer literal types from arguments without requiring callers to write `as const`
 
 ```typescript
 function createConfig<const T extends readonly string[]>(names: T): Record<T[number], boolean> {
+  // `Object.fromEntries` is typed to return a wide `Record<string, boolean>`, so a single
+  // localized `as` at a generic helper's return boundary is acceptable here -- it keeps the
+  // public signature precise. This is the narrow exception to the "no `as` casts" anti-pattern.
   return Object.fromEntries(names.map(n => [n, false])) as Record<T[number], boolean>;
 }
 

package/docs/skills/verification-before-completion.md

@@ -1,6 +1,6 @@
 # Verification Before Completion
 
-> Evidence-based completion claims -- never say "done" without proof that the work is correct.
+> Evidence-based completion claims -- never say "done" without proof that the work is correct. Use when about to claim a task is done, fixed, or passing, or before committing or opening a PR
 
 **Type:** Core Skill (always included)
 **Source:** [`core/skills/ct-verification-before-completion/SKILL.md`](../core/skills/ct-verification-before-completion/SKILL.md)

package/docs/stacks/esnext-idioms.md

@@ -0,0 +1,25 @@
+# ESNext Idioms
+
+> Modern ECMAScript runtime idioms — Temporal, iterator helpers, `using`, structuredClone.
+
+**Type:** Stack Skill (requires `esnext` stack)
+**Source:** [`stacks/esnext/skills/ct-esnext-idioms/SKILL.md`](../../stacks/esnext/skills/ct-esnext-idioms/SKILL.md)
+**Detected by:** tsconfig `target`/`module`/`lib` = `ESNext`/`ES2022+`, package.json `"type":"module"`, `engines.node >= 20`, or a `.mjs` file
+**File Extensions:** `.mjs`, `.cjs`
+
+## Overview
+
+Guidance for preferring current ECMAScript **runtime features** over legacy patterns and hand-rolled polyfills. It is availability-aware: each newer feature notes the runtime/polyfill it needs, so the recommendation never generates code the target can't run. Types are covered by `ct-typescript-conventions`; general code structure by `ct-code-style`.
+
+## Topics
+
+- **Dates → `Temporal`** — immutable, timezone-correct calendar/clock math (polyfill until baseline).
+- **Resource management → `using` / `await using`** — deterministic cleanup via `Symbol.dispose`/`asyncDispose`.
+- **Iterator helpers** — lazy `map`/`filter`/`take`, `Iterator.concat`, `Array.fromAsync`.
+- **Clone & group** — `structuredClone`, `Object.groupBy` / `Map.groupBy`.
+- **Async ergonomics** — `Promise.withResolvers`, `AbortSignal.timeout`/`any`, top-level await.
+- **Immutable array ops** — `at`, `findLast`, `toSorted`/`toReversed`/`with`.
+- **Errors** — `Error({ cause })`, `AggregateError`.
+- **ESM hygiene** — `import.meta.dirname` over `__dirname`, dynamic `import()`.
+
+See the [skill source](../../stacks/esnext/skills/ct-esnext-idioms/SKILL.md) for the full patterns, availability notes, and anti-patterns table.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-toolkit",
-	"version": "0.10.0",
+	"version": "0.15.0",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {
@@ -25,6 +25,7 @@
 		"typecheck": "tsc --noEmit",
 		"lint": "biome check --write",
 		"lint:check": "biome check",
+		"test": "bun test",
 		"postinstall": "bun bin/postinstall.mjs || node bin/postinstall.mjs || exit 0",
 		"prepare": "npx husky"
 	},

package/src/detect.ts

@@ -12,6 +12,8 @@ interface PackageJson {
 	dependencies?: Record<string, string>;
 	devDependencies?: Record<string, string>;
 	workspaces?: string[] | { packages?: string[] };
+	type?: string;
+	engines?: { node?: string };
 }
 
 /** A directory to inspect for stack markers, with its project-relative label */
@@ -54,6 +56,9 @@ const IGNORE_DIRS = new Set([
 	"test-results",
 ]);
 
+/** Node major version at/above which modern ESNext runtime features are assumed available. */
+const MIN_MODERN_NODE_MAJOR = 20;
+
 function readPackageJson(dir: string): PackageJson | null {
 	const pkgPath = join(dir, "package.json");
 	if (!existsSync(pkgPath)) return null;
@@ -174,6 +179,57 @@ function findProtoFiles(ctx: DetectContext): string | null {
 	return null;
 }
 
+/** Read a file's text, or null if missing/unreadable (tolerates comments/trailing commas). */
+function readTextFile(path: string): string | null {
+	try {
+		return readFileSync(path, "utf-8");
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * First scan root whose tsconfig.json sets target/module/lib to ESNext or ES2022+.
+ * Uses a lenient text scan because tsconfig files routinely carry comments and
+ * trailing commas that would break JSON.parse.
+ */
+function tsconfigTargetsEsnext(ctx: DetectContext): string | null {
+	const modern = /es(?:next|20(?:2[2-9]|[3-9]\d))/i; // ESNext or ES2022..ES2099
+	const keyValue = /"(?:target|module|lib)"\s*:\s*(?:"([^"]*)"|\[([^\]]*)\])/gi;
+	for (const { rel, dir } of ctx.scanRoots) {
+		const text = readTextFile(join(dir, "tsconfig.json"));
+		if (!text) continue;
+		for (const m of text.matchAll(keyValue)) {
+			if (modern.test(m[1] ?? m[2] ?? "")) return relPath(rel, "tsconfig.json");
+		}
+	}
+	return null;
+}
+
+/** Whether a package.json's engines.node floor is >= `major` (first integer in the range). */
+function enginesNodeAtLeast(pkg: PackageJson, major: number): boolean {
+	const range = pkg.engines?.node;
+	if (!range) return false;
+	const m = range.match(/(\d+)/);
+	return m ? Number(m[1]) >= major : false;
+}
+
+/** First `.mjs` file in a bounded search: each scan root's top level + bin/, src/, scripts/. */
+function findMjs(ctx: DetectContext): string | null {
+	const subs = ["", "bin", "src", "scripts"];
+	for (const { rel, dir } of ctx.scanRoots) {
+		for (const sub of subs) {
+			const searchDir = sub ? join(dir, sub) : dir;
+			if (!existsSync(searchDir)) continue;
+			const glob = new Bun.Glob("*.mjs"); // non-recursive: never descends into node_modules
+			for (const match of glob.scanSync({ cwd: searchDir, onlyFiles: true })) {
+				return relPath(rel, sub ? `${sub}/${match}` : match);
+			}
+		}
+	}
+	return null;
+}
+
 const DETECTORS: StackDetector[] = [
 	{
 		name: "solidjs",
@@ -271,6 +327,24 @@ const DETECTORS: StackDetector[] = [
 			return config ? { name: "capacitor", reason: `found ${config}` } : null;
 		},
 	},
+	{
+		name: "esnext",
+		detect: (ctx) => {
+			const ts = tsconfigTargetsEsnext(ctx);
+			if (ts) return { name: "esnext", reason: `found ESNext target in ${ts}` };
+			const mod = ctx.packages.find(({ pkg }) => pkg.type === "module");
+			if (mod) return { name: "esnext", reason: `found "type":"module" in ${pkgLabel(mod.rel)}` };
+			const eng = ctx.packages.find(({ pkg }) => enginesNodeAtLeast(pkg, MIN_MODERN_NODE_MAJOR));
+			if (eng)
+				return {
+					name: "esnext",
+					reason: `found engines.node >=${MIN_MODERN_NODE_MAJOR} in ${pkgLabel(eng.rel)}`,
+				};
+			const mjs = findMjs(ctx);
+			if (mjs) return { name: "esnext", reason: `found ${mjs}` };
+			return null;
+		},
+	},
 ];
 
 /** Scan a project directory (root + subdirs + workspace packages) and detect which stacks are present */

package/src/generator.ts

@@ -42,7 +42,7 @@ async function resolveConfig(config: ClaudeToolkitConfig): Promise<ResolvedConfi
 		"ct-testing-patterns",
 		"ct-typescript-conventions",
 		"ct-verification-before-completion",
-		...(config.excludeSkills ? [] : []),
+		"ct-code-style",
 	].filter((s) => !config.excludeSkills?.includes(s));
 
 	return { config, skills, directoryMappings: allMappings, hooks, stacks };
@@ -79,6 +79,10 @@ async function removeGenerated(claudeDir: string): Promise<void> {
 		// Toolkit hook files (copied from core/hooks) + the generated skill-rules.json.
 		...hookFiles.map((f) => removePath(join(claudeDir, "hooks", f))),
 		removePath(join(claudeDir, "hooks", "skill-rules.json")),
+		// Stale files from prior installs: skill-eval.js was renamed to .cjs, and the
+		// skill-eval.sh wrapper was dropped in favour of exec-form node registration.
+		removePath(join(claudeDir, "hooks", "skill-eval.js")),
+		removePath(join(claudeDir, "hooks", "skill-eval.sh")),
 	]);
 }
 
@@ -114,6 +118,16 @@ export async function generate(
 		}
 	}
 
+	// 5b. Copy stack-specific commands into the ct/ namespace. Only installs when
+	//     the owning stack is active; removeGenerated() already deletes the whole
+	//     .claude/commands/ct dir each rebuild, so a removed stack leaves no orphan.
+	for (const stackName of config.stacks) {
+		const stackCommandsDir = join(TOOLKIT_ROOT, "stacks", stackName, "commands");
+		if (exists(stackCommandsDir)) {
+			await copyDir(stackCommandsDir, join(claudeDir, "commands", "ct"));
+		}
+	}
+
 	// 6. Generate skill-rules.json
 	await generateSkillRules(claudeDir, resolved);
 
@@ -292,7 +306,8 @@ async function generateSettings(claudeDir: string, resolved: ResolvedConfig): Pr
 					hooks: [
 						{
 							type: "command",
-							command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/skill-eval.sh',
+							// biome-ignore lint/suspicious/noTemplateCurlyInString: Claude Code substitutes ${CLAUDE_PROJECT_DIR} at hook-run time; this must be a literal placeholder string.
+							command: 'node "${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-eval.cjs"',
 							timeout: 5,
 						},
 					],
@@ -360,6 +375,8 @@ async function generateSkillsReadme(claudeDir: string, resolved: ResolvedConfig)
 	content += "| ct-testing-patterns | Test-driven development workflow and patterns |\n";
 	content += "| ct-typescript-conventions | TypeScript strict mode and conventions |\n";
 	content += "| ct-verification-before-completion | Evidence-based completion claims protocol |\n";
+	content +=
+		"| ct-code-style | Code structure & style: guard clauses, lookup tables, no magic values |\n";
 	content += "\n## Stack Skills\n\n";
 	content += "| Skill | Stack | Description |\n";
 	content += "|-------|-------|-------------|\n";

package/src/types.ts

@@ -10,6 +10,7 @@ export type StackName =
 	| "playwright"
 	| "storybook"
 	| "capacitor"
+	| "esnext"
 	| (string & {});
 
 /** Hook configuration for post-tool-use automation */

package/stacks/esnext/skills/ct-esnext-idioms/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: ct-esnext-idioms
+description: Modern ECMAScript runtime idioms — Temporal, iterator helpers, using, structuredClone
+---
+
+# Modern ESNext Idioms
+
+Prefer current ECMAScript runtime features over legacy patterns and hand-rolled polyfills. Types live in `ct-typescript-conventions`; code structure lives in `ct-code-style`; this skill is about *runtime features*.
+
+> Some features below are newer than the Node/browser baseline. Each is tagged with what it needs. When a target can't guarantee it, use the noted polyfill/flag rather than dropping back to the legacy pattern.
+
+## Dates & time → `Temporal`
+
+`Date` is mutable, timezone-naive, and error-prone for math. Use `Temporal` for calendar/clock work.
+
+```ts
+const today = Temporal.Now.plainDateISO();               // no time, no tz confusion
+const due = today.add({ days: 30 });                     // immutable — returns a new value
+const start = Temporal.ZonedDateTime.from("2026-07-04T09:00[Europe/Paris]");
+const mins = start.until(Temporal.Now.zonedDateTimeISO()).total("minutes");
+```
+
+_Availability: Stage 3 — not yet baseline in Node. Add `temporal-polyfill` (or `@js-temporal/polyfill`) until it ships._ Avoid `Date` mutation, manual `getTime()` ms math, and moment.js.
+
+## Deterministic cleanup → `using` / `await using`
+
+`Symbol.dispose` / `Symbol.asyncDispose` free resources when scope exits — no `try/finally` ladder.
+
+```ts
+const openFile = (path: string) => {
+  const handle = fs.openSync(path, "r");
+  return { handle, [Symbol.dispose]: () => fs.closeSync(handle) };
+};
+
+const readHead = (path: string) => {
+  using file = openFile(path);       // closed automatically at end of block
+  return fs.readSync(file.handle, Buffer.alloc(16), 0, 16, 0);
+};                                    // ← dispose runs here, even on throw
+```
+
+`await using` awaits `Symbol.asyncDispose` (db connections, locks, spans). _Availability: TS 5.2+ (downlevels) or Node 24+._
+
+## Iterator helpers → lazy, no intermediate arrays
+
+```ts
+const firstThree = users.values()
+  .filter((u) => u.active)
+  .map((u) => u.name)
+  .take(3)
+  .toArray();                        // only 3 names ever materialised
+
+const merged = Iterator.concat(pageA.values(), pageB.values()); // Iterator Sequencing — Stage 4 (2025); polyfill on older runtimes
+const rows = await Array.fromAsync(streamRows());   // async iterable → array
+```
+
+_Availability: standard iterator helpers (`.filter`/`.map`/`.take`) and `Array.fromAsync` are Node 22+ / modern browsers; `Iterator.concat` is newer (Iterator Sequencing, 2025) — polyfill until it lands._ Replaces `[...a, ...b].filter().map().slice()`, which allocates at every step.
+
+## Clone & group
+
+```ts
+const copy = structuredClone(state);                 // deep clone — Map/Set/Date/typed arrays
+const byRole = Object.groupBy(users, (u) => u.role); // { admin: [...], guest: [...] }
+const byId = Map.groupBy(users, (u) => u.id);        // Map keys (any type)
+```
+
+Avoid `JSON.parse(JSON.stringify(x))` (drops `undefined`, turns `Date` into a string, throws on cycles) and manual `reduce` grouping.
+
+## Promise & async ergonomics
+
+```ts
+const { promise, resolve, reject } = Promise.withResolvers<Data>();   // no deferred-hack closure
+const res = await fetch(url, { signal: AbortSignal.timeout(5_000) }); // auto-abort
+const signal = AbortSignal.any([userAbort, AbortSignal.timeout(30_000)]);
+```
+
+Top-level `await` is available in ESM modules — no IIFE wrapper.
+
+## Immutable array ops
+
+```ts
+const last = items.at(-1);                           // negative index
+const newest = orders.findLast((o) => o.settled);
+const sorted = scores.toSorted((a, b) => b - a);     // non-mutating; also toReversed/toSpliced/with
+const patched = row.with(2, "x");                    // copy with index 2 replaced
+```
+
+## Errors with cause
+
+```ts
+try {
+  await save();
+} catch (err) {
+  throw new Error("Checkout failed", { cause: err }); // preserve the chain
+}
+throw new AggregateError(errors, "Some uploads failed"); // aggregate independent failures
+```
+
+## ESM hygiene
+
+```ts
+const here = import.meta.dirname;          // replaces __dirname (Node 20.11+/21.2+)
+const url = import.meta.url;
+const mod = await import("./plugin.js");    // dynamic import, not require()
+```
+
+## Performance
+
+> _Verified against ECMAScript 2024 / Node 22 (2026-07)._
+
+- **Iterator helpers are lazy** — `take(3)` stops the pipeline after 3 items; the array form processes everything first. Use them for early-exit and large/infinite sequences.
+- **`structuredClone` is a native deep copy** — faster and more correct than `JSON.parse(JSON.stringify())`, with no string round-trip.
+- **`AbortSignal.timeout`** removes `setTimeout` bookkeeping and leaks; the runtime clears the timer when the signal settles.
+
+## Anti-Patterns
+
+| Legacy | Modern |
+| --- | --- |
+| `new Date()` math / moment.js | `Temporal` (via polyfill) |
+| `try { } finally { close() }` | `using` / `await using` |
+| `[...a, ...b].filter().map().slice()` | iterator helpers + `Iterator.concat` |
+| `JSON.parse(JSON.stringify(x))` | `structuredClone(x)` |
+| manual `reduce` grouping | `Object.groupBy` / `Map.groupBy` |
+| deferred `let resolve; new Promise(...)` | `Promise.withResolvers()` |
+| `arr[arr.length - 1]` | `arr.at(-1)` |
+| `__dirname` / `require()` | `import.meta.dirname` / `import()` |
+
+## See Also
+
+- `ct-typescript-conventions` — typing these values (`satisfies`, discriminated unions for async state).
+- `ct-code-style` — structure around these features (guard clauses, no magic numbers, `??`).

package/stacks/esnext/stack.json

@@ -0,0 +1,37 @@
+{
+	"name": "ct-esnext-idioms",
+	"description": "Modern ECMAScript runtime idioms — Temporal, iterator helpers, using, structuredClone",
+	"defaultMappings": {},
+	"fileExtensions": ["mjs", "cjs"],
+	"skillRules": {
+		"ct-esnext-idioms": {
+			"description": "Modern ECMAScript runtime idioms and features",
+			"priority": 5,
+			"triggers": {
+				"keywords": [
+					"Temporal",
+					"structuredClone",
+					"iterator",
+					"using",
+					"dispose",
+					"groupBy",
+					"withResolvers",
+					"AbortSignal",
+					"fromAsync",
+					"esnext",
+					"moment",
+					"date"
+				],
+				"keywordPatterns": ["\\bTemporal\\b", "\\busing\\b", "\\bstructuredClone\\b"],
+				"contentPatterns": [
+					"new Date\\(",
+					"JSON\\.parse\\(JSON\\.stringify",
+					"__dirname",
+					"\\.groupBy\\("
+				],
+				"intentPatterns": ["(?:format|parse|manipulate).*date", "(?:clone|copy).*(?:object|deep)"]
+			},
+			"relatedSkills": ["ct-typescript-conventions", "ct-code-style"]
+		}
+	}
+}