@coralai/sps-cli 0.55.12 → 0.56.0

package/skills/typescript/references/async.md

@@ -1,241 +0,0 @@
-# TypeScript — Async
-
-Promises, async/await, error propagation, cancellation, concurrency.
-
-## `async/await` is sugar for promises
-
-```ts
-// These are equivalent
-async function f() { const x = await g(); return x + 1; }
-function f()      { return g().then(x => x + 1); }
-```
-
-Prefer `async/await` for linear flows, `.then` chains for pipelines on a single value.
-
-## Every promise must be awaited or handled
-
-Unhandled rejections crash Node (in strict mode) or log cryptic warnings.
-
-```ts
-// ❌ fire-and-forget
-sendEmail(user.email);           // if it rejects → unhandled
-doThing().then(logSuccess);      // no .catch
-
-// ✅
-await sendEmail(user.email);
-
-// ✅ intentional fire-and-forget: use .catch
-void sendEmail(user.email).catch(err => log.error(err));
-```
-
-TS/ESLint rules: `@typescript-eslint/no-floating-promises` catches these.
-
-## Error propagation
-
-Throws inside `async` become rejections. `try/catch` catches them.
-
-```ts
-async function load() {
-  try {
-    const r = await fetch(url);
-    if (!r.ok) throw new HttpError(r.status);
-    return await r.json();
-  } catch (e) {
-    if (e instanceof HttpError && e.status === 404) return null;
-    throw e;
-  }
-}
-```
-
-`catch (e: unknown)` — always. `e` is not an `Error` in JS; could be anything thrown.
-
-```ts
-try { ... } catch (e) {
-  if (e instanceof Error) log.error(e.message);
-  else log.error('non-Error thrown', { e });
-}
-```
-
-## Concurrency
-
-### Parallel, all must succeed
-
-```ts
-const [u, o, p] = await Promise.all([
-  getUser(id),
-  getOrders(id),
-  getPrefs(id),
-]);
-```
-
-One rejection → whole thing rejects; other in-flight promises continue but their results are discarded.
-
-### Parallel, any may fail
-
-```ts
-const results = await Promise.allSettled(tasks);
-for (const r of results) {
-  if (r.status === 'fulfilled') use(r.value);
-  else log.warn(r.reason);
-}
-```
-
-### First to finish wins
-
-```ts
-const winner = await Promise.race([req, timeout(5000)]);
-```
-
-### First to succeed (any)
-
-```ts
-const first = await Promise.any([primary(), secondary(), tertiary()]);
-// rejects only if all fail
-```
-
-## Sequential vs. parallel — don't accidentally serialize
-
-```ts
-// ❌ serial (each waits for the prior)
-for (const id of ids) {
-  await fetchUser(id);
-}
-
-// ✅ parallel
-await Promise.all(ids.map(fetchUser));
-```
-
-Sequential is correct when order matters or when you want backpressure. Parallel is often what you wanted but wrote wrong.
-
-## Bounded parallelism
-
-Unlimited parallelism blows up memory and hammers downstreams. Bound it.
-
-```ts
-import pLimit from 'p-limit';
-
-const limit = pLimit(10);
-const results = await Promise.all(ids.map(id => limit(() => fetchUser(id))));
-```
-
-Or chunk manually:
-
-```ts
-async function inChunks<T, R>(xs: T[], size: number, fn: (x: T) => Promise<R>) {
-  const out: R[] = [];
-  for (let i = 0; i < xs.length; i += size) {
-    const chunk = xs.slice(i, i + size);
-    out.push(...await Promise.all(chunk.map(fn)));
-  }
-  return out;
-}
-```
-
-## Cancellation — `AbortController`
-
-The standard cancellation primitive for fetch, streams, timers.
-
-```ts
-const ac = new AbortController();
-setTimeout(() => ac.abort(), 5000);
-
-try {
-  const r = await fetch(url, { signal: ac.signal });
-  return await r.json();
-} catch (e) {
-  if (e instanceof DOMException && e.name === 'AbortError') {
-    // cancelled
-  } else {
-    throw e;
-  }
-}
-```
-
-For your own async functions, accept a `signal` and check / propagate it:
-
-```ts
-async function work({ signal }: { signal?: AbortSignal }) {
-  if (signal?.aborted) throw new DOMException('aborted', 'AbortError');
-  signal?.addEventListener('abort', () => { /* clean up */ }, { once: true });
-  ...
-}
-```
-
-## Timeouts — `AbortSignal.timeout` (modern)
-
-```ts
-const r = await fetch(url, { signal: AbortSignal.timeout(5000) });
-```
-
-Falls back to `AbortController` + `setTimeout` on older runtimes.
-
-## Retry with backoff
-
-```ts
-async function withRetry<T>(
-  fn: () => Promise<T>,
-  { attempts = 3, baseMs = 100, maxMs = 10_000 } = {},
-): Promise<T> {
-  for (let i = 0; i < attempts; i++) {
-    try { return await fn(); }
-    catch (e) {
-      if (i === attempts - 1) throw e;
-      const delay = Math.min(maxMs, baseMs * 2 ** i) * (0.5 + Math.random());
-      await new Promise(r => setTimeout(r, delay));
-    }
-  }
-  throw new Error('unreachable');
-}
-```
-
-Only retry idempotent operations. See `backend/references/resilience.md`.
-
-## Async iterators & streams
-
-For data you consume one chunk at a time.
-
-```ts
-async function* readLines(stream: ReadableStream<Uint8Array>) {
-  const decoder = new TextDecoder();
-  const reader = stream.getReader();
-  let buf = '';
-  while (true) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    buf += decoder.decode(value, { stream: true });
-    const lines = buf.split('\n');
-    buf = lines.pop()!;
-    for (const line of lines) yield line;
-  }
-  if (buf) yield buf;
-}
-
-for await (const line of readLines(resp.body!)) {
-  process(line);
-}
-```
-
-## Microtasks & the event loop
-
-`await` queues continuation as a microtask — runs before macro-tasks (`setTimeout`) even at delay 0.
-
-```ts
-Promise.resolve().then(() => console.log('A'));   // microtask
-setTimeout(() => console.log('B'), 0);             // macrotask
-// A then B
-```
-
-You rarely need to know this, until you're debugging an out-of-order log.
-
-## Anti-patterns
-
-| Anti-pattern | Fix |
-|---|---|
-| `new Promise((res) => { ... res(x) })` wrapping a callback API | Use `util.promisify` (Node) or a library wrapper |
-| Rejecting with a string | Always `new Error(...)` |
-| Nested `.then` chains | Flatten with `await` |
-| `.catch` without re-throw on unknown errors | Narrow or rethrow |
-| `await` inside a `.forEach` | Use `for...of` or `Promise.all` |
-| `async` function returning `Promise<Promise<T>>` | Unnecessary; one `async` is enough |
-| Dangling `setTimeout`/`setInterval` in React effects | Return cleanup or use a library |
-| Fire-and-forget without `.catch` | Silent failures; add `.catch(log)` |

package/skills/typescript/references/errors.md

@@ -1,208 +0,0 @@
-# TypeScript — Errors
-
-Error classes, `Result` types, catch semantics. For general strategy (when to raise vs return, where to log), see `coding-standards/references/error-strategy.md`.
-
-## Custom error classes
-
-Subclass `Error`. Always set `name`. Use `cause` to chain.
-
-```ts
-export class AppError extends Error {
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options);
-    this.name = 'AppError';
-  }
-}
-
-export class NotFoundError extends AppError {
-  constructor(resource: string) {
-    super(`${resource} not found`);
-    this.name = 'NotFoundError';
-  }
-}
-
-export class ValidationError extends AppError {
-  constructor(public issues: { path: string; message: string }[]) {
-    super('validation failed');
-    this.name = 'ValidationError';
-  }
-}
-```
-
-Why `name`: stack traces use it, and `instanceof` can be unreliable across realms / duplicated module loads — the name string survives.
-
-## Chain with `cause`
-
-Preserve the original error (available in every modern runtime).
-
-```ts
-try {
-  await db.query(...);
-} catch (e) {
-  throw new AppError('failed to load user', { cause: e });
-}
-```
-
-Stack and `.cause` are both available for debugging / logging.
-
-## Catch `unknown`
-
-`catch (e)` in modern TS types `e` as `unknown`. Narrow before use.
-
-```ts
-try { ... } catch (e) {
-  if (e instanceof NotFoundError) return null;
-  if (e instanceof ValidationError) return { errors: e.issues };
-  throw e;                       // propagate the rest
-}
-```
-
-Never assume `e instanceof Error` without checking. Anything can be thrown — strings, numbers, `{}`, `null`.
-
-## `Result` types — optional, not always
-
-For operations where a failure is **expected**, a `Result` type makes the possibility visible in the signature and skips `try/catch`.
-
-```ts
-type Result<T, E> =
-  | { ok: true; value: T }
-  | { ok: false; error: E };
-
-async function findUser(id: string): Promise<Result<User, 'not_found' | 'db_down'>> {
-  try {
-    const u = await db.users.find(id);
-    if (!u) return { ok: false, error: 'not_found' };
-    return { ok: true, value: u };
-  } catch (e) {
-    return { ok: false, error: 'db_down' };
-  }
-}
-
-const r = await findUser(id);
-if (!r.ok) return handle(r.error);
-use(r.value);
-```
-
-Libraries (`neverthrow`, `true-myth`) give you chainable `Result`s with more ergonomics.
-
-**When NOT to use**: if every caller re-throws the error anyway, `Result` just adds noise. Use it when the choice is local and important.
-
-## Mapping errors at the edge
-
-Internal: throw freely. Edge (HTTP handler, CLI main, queue consumer): translate into response.
-
-```ts
-// The one translation layer
-export function toHttpResponse(e: unknown): Response {
-  if (e instanceof ValidationError)
-    return json({ errors: e.issues }, { status: 422 });
-  if (e instanceof NotFoundError)
-    return json({ error: e.message }, { status: 404 });
-  if (e instanceof AuthError)
-    return json({ error: 'unauthorized' }, { status: 401 });
-
-  log.error('unexpected', { err: e });
-  return json({ error: 'internal error' }, { status: 500 });
-}
-```
-
-One place for the mapping. Handlers just throw.
-
-## Never silently swallow
-
-```ts
-// ❌ swallow
-try { doThing(); } catch { /* oops, silently ignored */ }
-
-// ✅ log and continue if that's really what you want
-try { doThing(); }
-catch (e) { log.warn('doThing failed', { err: e }); }
-
-// ✅ best: the caller decides
-```
-
-## `finally` for cleanup
-
-```ts
-const conn = await pool.acquire();
-try {
-  await work(conn);
-} finally {
-  conn.release();
-}
-```
-
-Don't put business logic in `finally` — it runs even on error.
-
-## Assertion helpers
-
-Cheap way to narrow + fail fast.
-
-```ts
-export function invariant(c: unknown, msg: string): asserts c {
-  if (!c) throw new AppError(`invariant failed: ${msg}`);
-}
-
-invariant(user.active, 'user must be active by this point');
-user.email;     // narrowed; no null check needed
-```
-
-Keep messages short and specific. `"user must be active"` beats `"check failed"`.
-
-## Error handling across async boundaries
-
-An error in an async function becomes a rejected promise. Don't mix sync `throw` with async rejection in a way callers can't predict.
-
-```ts
-// ❌ sometimes throws synchronously, sometimes rejects
-async function bad(x: unknown) {
-  if (!x) throw new Error('bad');    // rejection (we're in async)
-  return await f(x);                  // rejection
-}
-
-function worse(x: unknown) {
-  if (!x) throw new Error('bad');    // sync throw
-  return f(x);                        // returns a rejected promise
-}
-
-// ✅ consistently one or the other
-async function good(x: unknown) {
-  if (!x) throw new Error('bad');
-  return await f(x);
-}
-// callers can always `await good(x)` and catch both cases with try/catch
-```
-
-## Validation at boundaries
-
-Validate at parse time, never deep inside.
-
-```ts
-import { z } from 'zod';
-
-const Body = z.object({ email: z.string().email(), age: z.number().int().min(0) });
-
-export async function POST(req: Request) {
-  let input;
-  try {
-    input = Body.parse(await req.json());
-  } catch (e) {
-    return json({ errors: (e as z.ZodError).issues }, { status: 422 });
-  }
-  // inside the function, `input` is strongly typed and trusted
-  await service.signup(input);
-  return json({ ok: true });
-}
-```
-
-## Anti-patterns
-
-| Anti-pattern | Fix |
-|---|---|
-| `throw 'bad'` (string) | Always `throw new Error(...)` — strings lose stack |
-| `catch (e: any)` | Use `catch (e)` (unknown) + narrow |
-| `catch { return null }` | Log + handle specifically, or rethrow |
-| Checking error with `.message.includes('...')` | Use instanceof + a typed error class |
-| `Promise.reject('...')` with a string | Reject with an `Error` |
-| Over-broad error class hierarchy with 40 subtypes | Usually 5–8 is enough |
-| Error messages leaking PII / secrets | Redact before logging; never in client response |

package/skills/typescript/references/idioms.md

@@ -1,246 +0,0 @@
-# TypeScript — Idioms
-
-Destructuring, optional chaining, nullish coalescing, modules.
-
-## `const` / `let` / `var`
-
-`const` by default. `let` only when reassigning. Never `var` — it has function scope and hoisting surprises.
-
-```ts
-const MAX = 10;
-let count = 0;
-for (const x of xs) count += x;
-```
-
-## Destructuring
-
-```ts
-// Object
-const { id, email, name = 'unknown' } = user;
-
-// Array
-const [first, second, ...rest] = xs;
-
-// Rename + default
-const { id: userId, role = 'user' } = req;
-
-// Nested
-const { user: { id, email } } = response;
-```
-
-Avoid deep destructuring across many levels — it becomes hard to read. Two levels max.
-
-## Optional chaining (`?.`) and nullish coalescing (`??`)
-
-```ts
-const city = user?.address?.city;                 // undefined if any part is null/undef
-const port = config.port ?? 3000;                 // only falls back on null/undef
-const items = maybeResponse?.items ?? [];
-```
-
-Don't confuse `??` with `||`:
-
-```ts
-const port = config.port || 3000;   // also falls back on 0, '', false
-const port = config.port ?? 3000;   // only on null/undef
-```
-
-Use `||` when any falsy value should fall back; `??` when only "nothing" should.
-
-## Spread & rest
-
-```ts
-// Spread — copy + override
-const updated = { ...user, email: newEmail };
-const concat = [...xs, ...ys];
-
-// Rest in params
-function log(first: string, ...rest: unknown[]) { ... }
-
-// Rest in destructuring
-const { password, ...publicUser } = user;
-```
-
-Rest destructuring is a cheap way to drop a field (`publicUser` above).
-
-## Arrow vs. `function`
-
-- Arrow for callbacks, one-liners, closures that need lexical `this`.
-- `function` for top-level named functions that might be hoisted or recursive.
-
-```ts
-const double = (x: number) => x * 2;
-
-function fibonacci(n: number): number {
-  return n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
-}
-```
-
-## Immutable updates
-
-```ts
-// ❌ mutation
-user.email = newEmail;
-xs.push(item);
-
-// ✅ new value
-const updated = { ...user, email: newEmail };
-const next = [...xs, item];
-```
-
-Mutation is cheap but makes change hard to trace. In frontends (React, Vue) and any concurrent code, immutable updates are usually required, not optional.
-
-Use `structuredClone(x)` (global, Node 17+, browsers) for deep clones. Avoid `JSON.parse(JSON.stringify(x))` — loses dates, maps, undefined.
-
-## Modules — ESM, named exports
-
-Use ESM (`import` / `export`) everywhere. No `require` in new code (TS emits `require` if the target is CommonJS; that's a toolchain choice, not a source style).
-
-```ts
-// ✅ named exports — grep-friendly, IDEs auto-import
-export function parse(raw: string): Config { ... }
-export const DEFAULT_TIMEOUT = 5000;
-
-// ❌ default export + anonymous
-export default function (raw: string): Config { ... }
-```
-
-Default exports make renames invisible (`import Foo from './x'`) and break auto-import. Use named exports and let the import name match the export name.
-
-Allow `default` only when the language / framework demands it (React lazy routes, JSX component files by convention — team choice).
-
-## `for...of` over `.forEach`
-
-```ts
-// ✅ — supports `await`, `break`, `continue`, `return`
-for (const x of xs) {
-  await process(x);
-  if (done) break;
-}
-
-// ⚠️ .forEach ignores `return` and can't be awaited
-xs.forEach(async x => await process(x));   // fires in parallel; next line doesn't wait
-```
-
-`forEach` is fine for pure synchronous side effects on small arrays. For anything else, `for...of`.
-
-## Map / Set over object / array when keys aren't known strings
-
-```ts
-// ❌ object-as-map
-const counts: Record<string, number> = {};
-counts[key] = (counts[key] ?? 0) + 1;
-// keys stringified; `constructor`, `__proto__` are footguns
-
-// ✅ Map
-const counts = new Map<string, number>();
-counts.set(key, (counts.get(key) ?? 0) + 1);
-```
-
-Use `Map` when keys are dynamic, need iteration in insertion order, or aren't strings. Use `Set` for unique values.
-
-## JSON at boundaries
-
-Parse with a schema; never trust `JSON.parse(raw) as Config`.
-
-```ts
-// ❌
-const config: Config = JSON.parse(raw);    // wrong at runtime; TS can't stop it
-
-// ✅
-const config = ConfigSchema.parse(JSON.parse(raw));   // zod throws on bad data
-```
-
-## String templates
-
-Backticks for interpolation and multi-line.
-
-```ts
-const msg = `Hello ${name}, you have ${count} messages`;
-
-const html = `
-  <div>
-    ${items.map(i => `<li>${i.name}</li>`).join('')}
-  </div>
-`;
-```
-
-For anything user-controlled rendered into HTML/SQL/shell, you need escaping, not templates. Templates are for formatting, not safety.
-
-## Narrowing with `in`
-
-```ts
-function area(s: Circle | Square) {
-  if ('radius' in s) return Math.PI * s.radius ** 2;
-  return s.side ** 2;
-}
-```
-
-`in` narrows to the variant that has the property. Works well with discriminated unions too, but `.kind` / `.type` discriminators are clearer.
-
-## Short-circuit guards
-
-Prefer guards at the top to deep nesting.
-
-```ts
-function process(user: User | null) {
-  if (!user) return null;
-  if (!user.active) return null;
-  return doWork(user);
-}
-```
-
-## Assertion functions
-
-Marks a path as unreachable without narrowing.
-
-```ts
-function assert(c: unknown, msg: string): asserts c {
-  if (!c) throw new Error(msg);
-}
-
-const x: string | null = maybe();
-assert(x !== null, 'x must be set by now');
-x.toLowerCase();           // narrowed to string
-```
-
-## `bigint`, `Date`, and friends
-
-- `Date` has sharp edges (month 0-indexed, mutation). Prefer a lib (`date-fns`, `luxon`, native `Temporal` when widely available).
-- `bigint` for integers > 2^53. Mixing `bigint` and `number` is a type error — good.
-- `Symbol` — useful for unique keys and well-known protocols. Rarely needed in application code.
-
-## `void` vs `undefined` in return types
-
-- `void` for "I don't care what you return" (callbacks whose return is ignored).
-- `undefined` when the function explicitly returns nothing.
-
-```ts
-function subscribe(cb: () => void) { ... }
-// subscriber may return something; we ignore it.
-
-function log(msg: string): undefined {
-  console.log(msg);
-  return;
-}
-```
-
-Trivia, but CR-worthy in library code.
-
-## `this` — lexical or bound, never `function` inside callbacks
-
-```ts
-// ❌ `this` is whatever called the callback
-btn.addEventListener('click', function() { this.count++ });
-
-// ✅ lexical `this` via arrow
-btn.addEventListener('click', () => { this.count++ });
-```
-
-In classes, use `.bind(this)` at construction time, or use arrow-method field syntax:
-
-```ts
-class X {
-  handle = () => { /* `this` is X, always */ };
-}
-```