@litfamily/litgrok 1.0.0

package/.grok/skills/lit-code/references/typescript/tsconfig-strict.md

@@ -0,0 +1,152 @@
+# Strict tsconfig + Biome
+
+The canonical ultra-strict config. Copy-paste, then add your own paths.
+
+---
+
+## tsconfig.json
+
+```jsonc
+{
+  "compilerOptions": {
+    // ── Strict core ──────────────────────────────────────────
+    "strict": true,                            // enables all strict* flags below
+    // strict includes: strictNullChecks, strictFunctionTypes,
+    // strictBindCallApply, strictPropertyInitialization,
+    // noImplicitAny, noImplicitThis, alwaysStrict, useUnknownInCatchVariables
+
+    // ── Additional strict flags (NOT included in "strict") ──
+    "noUncheckedIndexedAccess": true,           // obj[key] is T | undefined, not T
+    "exactOptionalPropertyTypes": true,         // { x?: string } !== { x: string | undefined }
+    "noFallthroughCasesInSwitch": true,         // switch fall-through is an error
+    "noPropertyAccessFromIndexSignature": true, // forces bracket notation for index sigs
+    "forceConsistentCasingInFileNames": true,   // prevents case-sensitivity bugs on macOS/Win
+
+    // ── Module system ────────────────────────────────────────
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true,               // forces `import type` for type-only imports
+    "isolatedModules": true,                    // safe for esbuild / swc / Bun transpilation
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+
+    // ── Target ───────────────────────────────────────────────
+    "target": "ESNext",
+    "lib": ["ESNext"],
+
+    // ── Emit ─────────────────────────────────────────────────
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+
+    // ── Performance ──────────────────────────────────────────
+    "skipLibCheck": true,                       // skip checking .d.ts files for speed
+    "incremental": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### What each extra flag catches
+
+| Flag | What it prevents |
+|---|---|
+| `noUncheckedIndexedAccess` | `arr[0]` is `T \| undefined`, not `T`. Forces you to check before using. |
+| `exactOptionalPropertyTypes` | `{ x?: string }` means "missing or string", NOT "string \| undefined". Assigns `undefined` explicitly? Type error. |
+| `noFallthroughCasesInSwitch` | Forgetting `break` / `return` in a switch case. |
+| `noPropertyAccessFromIndexSignature` | `obj.foo` on `Record<string, X>` is an error. Use `obj["foo"]`. |
+| `verbatimModuleSyntax` | Forces `import type { X }` for type-only imports. Prevents runtime import of types. |
+
+### Bun-specific additions
+
+For Bun projects, add to `compilerOptions`:
+```jsonc
+{
+  "types": ["bun-types"],
+  "moduleDetection": "force"
+}
+```
+
+---
+
+## biome.jsonc
+
+```jsonc
+{
+  "$schema": "https://biomejs.dev/schemas/2.0.6/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noConfusingVoidType": "error",
+        "noFallthroughSwitchClause": "error"
+      },
+      "style": {
+        "noDefaultExport": "error",
+        "useImportType": "error",
+        "noNonNullAssertion": "error",
+        "useEnumInitializers": "off",
+        "noParameterAssign": "error"
+      },
+      "correctness": {
+        "noUnusedVariables": "error",
+        "noUnusedImports": "error"
+      },
+      "complexity": {
+        "noBannedTypes": "error"
+      }
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "asNeeded"
+    }
+  },
+  "files": {
+    "ignore": ["node_modules", "dist", "build", ".next", ".nuxt", "coverage"]
+  }
+}
+```
+
+### Key Biome rules
+
+| Rule | What |
+|---|---|
+| `noExplicitAny` | `any` in annotations is an error |
+| `noNonNullAssertion` | `x!` is an error |
+| `noDefaultExport` | Forces named exports |
+| `useImportType` | Forces `import type` for type-only imports |
+| `noParameterAssign` | No mutation of function parameters |
+
+---
+
+## CI gate
+
+```bash
+bunx biome check .
+bunx tsc --noEmit
+bun test
+```
+
+---
+
+## Sources
+
+- TypeScript: [tsconfig reference](https://www.typescriptlang.org/tsconfig)
+- Biome: [configuration](https://biomejs.dev/reference/configuration/)
+- Total TypeScript: [tsconfig cheat sheet](https://www.totaltypescript.com/tsconfig-cheat-sheet)

package/.grok/skills/lit-code/references/typescript/type-patterns.md

@@ -0,0 +1,196 @@
+# Type Patterns
+
+How to use TypeScript's type system to catch bugs at compile time.
+
+---
+
+## Branded types — distinct primitives
+
+Same runtime type, different meaning. The compiler prevents mixing.
+
+```typescript
+declare const brand: unique symbol
+type Brand<T, B extends string> = T & { readonly [brand]: B }
+
+type UserId = Brand<string, "UserId">
+type OrderId = Brand<string, "OrderId">
+type Milliseconds = Brand<number, "Milliseconds">
+type Seconds = Brand<number, "Seconds">
+
+function UserId(value: string): UserId { return value as UserId }
+function OrderId(value: string): OrderId { return value as OrderId }
+
+function getUser(id: UserId): User { ... }
+
+getUser(UserId("abc"))    // OK
+getUser(OrderId("abc"))   // type error: OrderId is not UserId
+getUser("abc")            // type error: string is not UserId
+```
+
+With Zod (preferred at boundaries):
+```typescript
+import { z } from "zod"
+
+const UserIdSchema = z.string().uuid().brand("UserId")
+type UserId = z.infer<typeof UserIdSchema>
+```
+
+**Use when**: IDs, indices, units of measurement — any pair where swapping is a bug.
+
+---
+
+## as const — literal types from values
+
+Freezes a value to its narrowest possible type. The foundation for enum-free TypeScript.
+
+```typescript
+const ROLES = ["admin", "user", "guest"] as const
+type Role = (typeof ROLES)[number]  // "admin" | "user" | "guest"
+
+const HTTP_STATUS = {
+  OK: 200,
+  NOT_FOUND: 404,
+  INTERNAL: 500,
+} as const
+type HttpStatus = (typeof HTTP_STATUS)[keyof typeof HTTP_STATUS]  // 200 | 404 | 500
+```
+
+**Use when**: fixed set of constants. Replaces `enum` entirely.
+**Skip when**: the set is open-ended or user-defined.
+
+---
+
+## satisfies — validate without widening
+
+Type-checks a value against a type while preserving the literal type. Best of both worlds.
+
+```typescript
+type Config = Record<string, string | number>
+
+// BAD — widens to Record<string, string | number>
+const config: Config = { api: "https://api.example.com", timeout: 30 }
+config.api  // string | number — lost the narrowing
+
+// GOOD — validates AND preserves literal types
+const config = {
+  api: "https://api.example.com",
+  timeout: 30,
+} satisfies Config
+config.api      // string (narrowed)
+config.timeout  // number (narrowed)
+```
+
+**Use when**: you want type validation on a value without losing narrowing.
+
+---
+
+## Discriminated unions — algebraic data types
+
+Model every outcome as a type. Force the caller to handle all cases.
+
+```typescript
+type GetUserResult =
+  | { readonly kind: "found"; readonly user: User }
+  | { readonly kind: "not_found"; readonly id: UserId }
+  | { readonly kind: "forbidden"; readonly reason: string }
+```
+
+The `kind` field (or `type`, `status`, `_tag`) is the discriminant. TypeScript narrows on it automatically.
+
+---
+
+## Exhaustive switch — assertNever
+
+Every switch on a discriminated union ends with a default that calls `assertNever`.
+
+```typescript
+function assertNever(x: never): never {
+  throw new Error(`Unexpected value: ${JSON.stringify(x)}`)
+}
+
+function handleResult(result: GetUserResult): string {
+  switch (result.kind) {
+    case "found":
+      return result.user.name
+    case "not_found":
+      return `No user ${result.id}`
+    case "forbidden":
+      return `Denied: ${result.reason}`
+    default:
+      return assertNever(result)
+  }
+}
+```
+
+Add a new variant to `GetUserResult`? The compiler errors on the `assertNever` call until you handle it.
+
+---
+
+## Narrowing — let the compiler follow your logic
+
+TypeScript narrows types through `typeof`, `instanceof`, `in`, equality checks, and discriminants.
+
+```typescript
+function process(value: string | number | null): string {
+  if (value === null) return "nothing"
+  // compiler knows: string | number
+
+  if (typeof value === "string") return value.toUpperCase()
+  // compiler knows: number
+
+  return String(value * 2)
+}
+```
+
+### Custom type guards
+
+```typescript
+function isNonNull<T>(value: T | null | undefined): value is T {
+  return value != null
+}
+
+const items = [1, null, 2, undefined, 3]
+const clean = items.filter(isNonNull)  // number[]
+```
+
+---
+
+## import type — separate values from types
+
+Always use `import type` for type-only imports. Enforced by `verbatimModuleSyntax`.
+
+```typescript
+import type { User, Config } from "./types"   // erased at runtime
+import { createUser } from "./services"        // kept at runtime
+```
+
+For mixed imports:
+```typescript
+import { createUser, type User } from "./users"
+```
+
+---
+
+## Utility types — quick reference
+
+| Need | Use |
+|---|---|
+| All properties readonly | `Readonly<T>` |
+| All properties optional | `Partial<T>` |
+| All properties required | `Required<T>` |
+| Pick specific properties | `Pick<T, "a" \| "b">` |
+| Omit specific properties | `Omit<T, "a" \| "b">` |
+| Key-value map | `Record<K, V>` |
+| Extract from union | `Extract<T, U>` |
+| Exclude from union | `Exclude<T, U>` |
+| Return type of function | `ReturnType<typeof fn>` |
+| Parameters of function | `Parameters<typeof fn>` |
+| Awaited type | `Awaited<Promise<T>>` → `T` |
+
+---
+
+## Sources
+
+- TypeScript Handbook: [Narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html)
+- TypeScript Handbook: [Template Literal Types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html)
+- Total TypeScript: [as const](https://www.totaltypescript.com/as-const)

package/.grok/skills/lit-code/references/worked-cases.md

@@ -0,0 +1,190 @@
+# Worked programming boundary cases
+
+Load these cases when a programming request combines implementation with permission, sandbox, dirty-tree, packaging, or release boundaries. Each case gives concrete input and the expected response shape. Paths and commands are examples; inspect the live repository before using them.
+
+## Case 1 — Allowed edit inside a workspace sandbox
+
+### Input
+
+```text
+Goal: make parseMode("AUTO") return auto.
+Scope: src/parse-mode.mjs and test/parse-mode.test.mjs.
+Sandbox: workspace.
+Permission: Read and Edit for src/** and test/**; Bash(npm test) asks.
+Dirty state: README.md is already modified and unrelated.
+```
+
+### Decision
+
+Read the local rules, source, and nearest test. Preserve `README.md`. Add a focused uppercase-input assertion and run it to RED. Patch only the parser. Request approval for the named test command if the host asks. The workspace profile permits writes under cwd but does not itself authorize them.
+
+### Expected output
+
+```text
+CHANGED: src/parse-mode.mjs; test/parse-mode.test.mjs
+RED: node --test test/parse-mode.test.mjs, cwd=<repo>, exit 1, 1 failed
+GREEN: node --test test/parse-mode.test.mjs, cwd=<repo>, exit 0, 6 passed
+PRESERVED: README.md remained modified and untouched
+BOUNDARIES: permission rules and sandbox configuration unchanged
+```
+
+## Case 2 — Explicit allow but read-only sandbox
+
+### Input
+
+```text
+Goal: update src/config.mjs.
+Permission: Edit(src/**) allowed.
+Sandbox: read-only.
+```
+
+### Decision
+
+Do not attempt the source write and do not disable the sandbox. An explicit allow permits the tool call, while `read-only` permits writes only to `~/.grok/` and temp. Read-only reconnaissance may continue within scope.
+
+### Expected output
+
+```text
+BLOCKED: src/config.mjs is inside the repository, which the active read-only
+sandbox does not permit writing. Edit permission is present but does not expand
+sandbox reach. No configuration was changed.
+```
+
+## Case 3 — Installer conflict with a foreign file
+
+### Input
+
+```text
+Goal: make reinstall idempotent.
+Destination: <temp-project>/.grok/rules/00-product.md
+Existing bytes: "local team rule\n"
+Packaged bytes: "package rule\n"
+Contract: never overwrite a foreign file silently.
+```
+
+### Decision
+
+Write a failing installer test that creates the foreign destination and asserts that the entire install refuses before mutation. Implement a preflight comparison across all payload paths. Do not add a force option unless the user requested a replacement policy.
+
+### Expected output
+
+```text
+exit: non-zero
+stderr: names .grok/rules/00-product.md as a conflict
+destination after run: byte-identical "local team rule\n"
+other payload paths after run: absent
+temporary fixture: removed by test cleanup
+```
+
+## Case 4 — Documentation reference added to a package
+
+### Input
+
+```text
+Goal: add skills/example/references/contract.md and route to it from SKILL.md.
+Package files include the whole .grok/skills tree.
+No runtime code changes.
+```
+
+### Decision
+
+Add a structural test that fails while the reference is missing or unreachable. Write the reference only if it holds an earned contract, table, taxonomy, worked case, or primary-source schema. Update the entry point with a load condition. Run docs tests and inspect dry-pack JSON for the exact path.
+
+### Expected output
+
+```text
+RED: structural test reports missing references/contract.md
+GREEN: structural test passes and entry point names when to load it
+PACK: .grok/skills/example/references/contract.md appears exactly once
+CLAIM LIMIT: static and package evidence only; no live-host activation claimed
+```
+
+## Case 5 — Test requires child network under strict sandbox
+
+### Input
+
+```text
+Goal: run an integration test that downloads a fixture.
+Permission: Bash(npm test) allowed.
+Sandbox: strict.
+Fixture is not cached.
+```
+
+### Decision
+
+Do not turn the profile off and do not replace the fixture with guessed data. Check for an offline fixture or narrower test. If none exists, report the child-network boundary.
+
+### Expected output
+
+```text
+BLOCKED GATE: npm run test:integration requires a child-network download that
+the strict profile is intended to block. The fixture is unavailable locally.
+Permission and sandbox settings remain unchanged.
+```
+
+## Case 6 — Version preparation without release authority
+
+### Input
+
+```text
+Goal: prepare version 0.4.0 and verify the tarball.
+Authorized: package metadata edit and dry-pack checks.
+Hard stops: no commit, tag, push, publish, or release.
+```
+
+### Decision
+
+Update only lockstep fields in scope. Run version checks, tests, and dry pack. Do not authenticate to the registry and do not infer that preparation authorizes publication.
+
+### Expected output
+
+```text
+VERSION: all owned metadata reports 0.4.0
+TEST: package suite exit 0 with counts
+PACK: dry-run JSON inspected; no archive retained
+NOT RUN: commit, tag, push, publish, release
+```
+
+## Case 7 — Denied tool and tempting substitute
+
+### Input
+
+```text
+Goal: edit config/settings.toml.
+Permission: Edit(config/**) denied; Bash is allowed.
+```
+
+### Decision
+
+Do not use shell redirection, a formatter, or a generator to write the denied path. The effect remains an edit even when the tool label changes.
+
+### Expected output
+
+```text
+BLOCKED: the mutation matches an explicit edit denial.
+No alternate tool was used to bypass it. Read-only inspection can continue.
+```
+
+## Case 8 — Focused test passes but shipped surface is unproven
+
+### Input
+
+```text
+Goal: add a command script under .grok/hooks/.
+Focused stdin driver: passes.
+Package installer: walks the payload tree.
+```
+
+### Decision
+
+Run the hook configuration test, verify the command bit, inspect the dry-pack listing, and invoke a temp install. Keep the live-host claim bounded unless a documented event actually drove it.
+
+### Expected output
+
+```text
+DRIVER: event JSON -> exit/status/stdout contract passed
+CONFIG: event and executable-command validation passed
+PACK: hook JSON and executable both listed
+INSTALL: both files landed byte-identically in a temporary project
+LIMIT: no live Grok Build event was observed in this run
+```