@litfamily/litcodex 1.0.0

package/node_modules/@litcodex/lit-loop/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/node_modules/@litcodex/lit-loop/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/node_modules/@litcodex/lit-loop/skills/lit-code/scripts/go/check-no-excuse-rules.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# No-excuse rule checker for Go files.
+# Mirrors the philosophy of python-programmer / typescript-programmer / rust-programmer scripts:
+# only rules that can be enforced via pure text matching live here.
+# Everything semantic is on golangci-lint + nilaway + go test -race.
+
+set -euo pipefail
+
+if [ $# -eq 0 ]; then
+    echo "Usage: $0 <file.go> [file.go ...]" >&2
+    exit 2
+fi
+
+violations=0
+report() {
+    local file="$1"
+    local line="$2"
+    local rule="$3"
+    local detail="$4"
+    echo "::error file=${file},line=${line}::[${rule}] ${detail}" >&2
+    violations=$((violations + 1))
+}
+
+is_test_file() {
+    case "$1" in
+        *_test.go) return 0 ;;
+    esac
+    return 1
+}
+
+is_generated_file() {
+    local file="$1"
+    case "$file" in
+        *.pb.go|*.connect.go|*.gen.go) return 0 ;;
+        *_string.go) return 0 ;;
+    esac
+    # First-line check for "Code generated ... DO NOT EDIT." (the official marker)
+    if [ -f "$file" ]; then
+        head -n 5 "$file" 2>/dev/null | grep -qE "^// Code generated .* DO NOT EDIT\.$" && return 0
+    fi
+    return 1
+}
+
+for file in "$@"; do
+    [ -f "$file" ] || continue
+    case "$file" in
+        *.go) ;;
+        *) continue ;;
+    esac
+
+    if is_generated_file "$file"; then
+        continue
+    fi
+
+    in_test=0
+    if is_test_file "$file"; then
+        in_test=1
+    fi
+
+    line_no=0
+    while IFS= read -r raw_line || [ -n "$raw_line" ]; do
+        line_no=$((line_no + 1))
+        line="$raw_line"
+
+        # Strip line comments before pattern checks
+        # (block comments are not handled — keep the rules robust to that limitation).
+        code_only="${line%%//*}"
+
+        # ── Exemption marker: // no-excuse-ok: <reason> ──────────────────
+        if [[ "$line" =~ //[[:space:]]*no-excuse-ok:[[:space:]]*.+ ]]; then
+            continue
+        fi
+
+        # ── Rule: no `_ = err` (silent error swallow) ────────────────────
+        # The errcheck linter catches most of these but the `_ = err` form
+        # specifically slips through if used with named returns.
+        if [[ "$code_only" =~ ^[[:space:]]*_[[:space:]]*=[[:space:]]*err[[:space:]]*$ ]] ||
+           [[ "$code_only" =~ ^[[:space:]]*_[[:space:]]*=[[:space:]]*err[[:space:]]*[^a-zA-Z0-9_].*$ ]]; then
+            if [ "$in_test" -eq 0 ]; then
+                report "$file" "$line_no" "silent-err" "discarding err with '_ = err' — handle the error"
+            fi
+        fi
+
+        # ── Rule: no `panic(` in non-test, non-main code ─────────────────
+        # Allowed in main(), allowed in tests, allowed with explicit marker.
+        if [[ "$code_only" =~ [^a-zA-Z0-9_]panic\( ]] || [[ "$code_only" =~ ^[[:space:]]*panic\( ]]; then
+            if [ "$in_test" -eq 0 ]; then
+                # main package main.go is the one exception
+                pkg_line=$(head -n 5 "$file" 2>/dev/null | grep -m1 "^package ")
+                if [[ "$pkg_line" != "package main" ]]; then
+                    report "$file" "$line_no" "panic-in-lib" "panic outside main/test — return error instead"
+                fi
+            fi
+        fi
+
+        # ── Rule: no `log.Fatal` / `log.Panic` in library code ───────────
+        if [[ "$code_only" =~ log\.(Fatal|Panic)(f|ln)?\( ]]; then
+            if [ "$in_test" -eq 0 ]; then
+                pkg_line=$(head -n 5 "$file" 2>/dev/null | grep -m1 "^package ")
+                if [[ "$pkg_line" != "package main" ]]; then
+                    report "$file" "$line_no" "log-fatal-in-lib" "log.Fatal/Panic outside main — return error"
+                fi
+            fi
+        fi
+
+        # ── Rule: no init() functions ─────────────────────────────────
+        # init() ruins testability and creates hidden global state.
+        # Exception: //go:build constraint files and generated code.
+        if [[ "$code_only" =~ ^func[[:space:]]+init\(\)[[:space:]]*\{ ]]; then
+            report "$file" "$line_no" "no-init-func" "init() ruins testability — use explicit constructor"
+        fi
+
+        # ── Rule: no `time.Sleep` in non-test code ──────────────────────
+        if [[ "$code_only" =~ time\.Sleep\( ]]; then
+            if [ "$in_test" -eq 0 ]; then
+                report "$file" "$line_no" "time-sleep" "time.Sleep in production code — use ticker/timer with ctx"
+            fi
+        fi
+
+        # ── Rule: no `context.Background()` inside functions (only in main/init/test) ──
+        if [[ "$code_only" =~ context\.Background\(\) ]]; then
+            if [ "$in_test" -eq 0 ]; then
+                pkg_line=$(head -n 5 "$file" 2>/dev/null | grep -m1 "^package ")
+                if [[ "$pkg_line" != "package main" ]]; then
+                    report "$file" "$line_no" "ctx-background-in-lib" "context.Background() outside main — propagate ctx as parameter"
+                fi
+            fi
+        fi
+
+        # ── Rule: no `interface{}` (use `any`, the alias from Go 1.18+) ──
+        if [[ "$code_only" =~ interface\{\} ]]; then
+            report "$file" "$line_no" "old-interface-empty" "use 'any' instead of 'interface{}' (Go 1.18+)"
+        fi
+
+        # ── Rule: no bare `fmt.Println` for logging (use slog) ───────────
+        # Acceptable in main.go (CLI output) and tests. Reject in libraries.
+        if [[ "$code_only" =~ fmt\.(Print|Println|Printf)\( ]]; then
+            if [ "$in_test" -eq 0 ]; then
+                pkg_line=$(head -n 5 "$file" 2>/dev/null | grep -m1 "^package ")
+                if [[ "$pkg_line" != "package main" ]]; then
+                    report "$file" "$line_no" "fmt-print-in-lib" "fmt.Print* in library — use slog for structured logs"
+                fi
+            fi
+        fi
+
+        # ── Rule: no `nolint` directive without reason ───────────────────
+        if [[ "$line" =~ //nolint(:|$| ) ]]; then
+            if ! [[ "$line" =~ //nolint:[a-zA-Z0-9_,-]+[[:space:]]+//[[:space:]]*[^[:space:]] ]]; then
+                report "$file" "$line_no" "nolint-no-reason" "//nolint requires a // reason after the linter list"
+            fi
+        fi
+
+        # ── Rule: no TODO / FIXME without an issue link or owner ─────────
+        # Check the full line — TODOs live in comments, which $code_only has stripped.
+        if echo "$line" | grep -qE '(TODO|FIXME|XXX)([[:space:]]|:)'; then
+            if ! echo "$line" | grep -qE '(TODO|FIXME|XXX).*[(@[]'; then
+                report "$file" "$line_no" "todo-no-owner" "TODO/FIXME requires (#issue) or @owner attribution"
+            fi
+        fi
+    done < "$file"
+done
+
+if [ "$violations" -gt 0 ]; then
+    echo "" >&2
+    echo "go-programmer: $violations violation(s). Run also:" >&2
+    echo "  gofumpt -l ." >&2
+    echo "  golangci-lint run --timeout 5m ./..." >&2
+    echo "  nilaway ./..." >&2
+    echo "  go test -race -shuffle=on -count=1 ./..." >&2
+    exit 1
+fi
+
+echo "go-programmer: no-excuse rules passed for $# file(s)."

package/node_modules/@litcodex/lit-loop/skills/lit-code/scripts/go/new-project.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "typer",
+#     "rich",
+# ]
+# ///
+
+# ─── How to run ───
+# 1. Install uv (if not installed):
+#      curl -LsSf https://astral.sh/uv/install.sh | sh
+# 2. Run:
+#      uv run new-project.py myservice
+#      uv run new-project.py myservice --module github.com/your-org/myservice
+# ──────────────────
+#
+# Creates a new Go project with the canonical strict layout:
+#   - go.mod with go 1.23
+#   - .golangci.yml (v2, strict bundle)
+#   - Taskfile.yml (fmt + lint + test + build)
+#   - cmd/server/main.go entrypoint
+#   - internal/{cmd,config,api,domain,obs} skeletons
+#   - .github/workflows/ci.yml
+#
+# Templates live in ./templates/ — keep this script under 250 pure LOC.
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from string import Template
+
+import typer
+from rich.console import Console
+
+console = Console(stderr=True)
+
+TEMPLATES_DIR = Path(__file__).parent / "templates"
+
+
+def _render(template_file: str, **subs: str) -> str:
+    """Read a template file and apply $placeholder substitutions.
+
+    Uses string.Template ($name) so Go/YAML curly braces stay literal.
+    """
+    raw = (TEMPLATES_DIR / template_file).read_text()
+    if not subs:
+        return raw
+    return Template(raw).substitute(**subs)
+
+
+# (template-file → relative output path; is_format = .format() is run)
+FILES: list[tuple[str, str, bool]] = [
+    (".golangci.yml",   ".golangci.yml",                   False),
+    ("Taskfile.yml",    "Taskfile.yml",                    False),
+    (".editorconfig",   ".editorconfig",                   False),
+    ("gitignore",       ".gitignore",                      False),
+    ("ci.yml",          ".github/workflows/ci.yml",        False),
+    ("run.go",          "internal/cmd/run.go",             False),
+    ("config.go",       "internal/config/config.go",       False),
+    ("main.go.tmpl",    "cmd/server/main.go",              True),
+    ("AGENTS.md.tmpl",  "AGENTS.md",                       True),
+    ("README.md.tmpl",  "README.md",                       True),
+]
+
+
+def _init_go_module(project_dir: Path, module: str) -> None:
+    try:
+        subprocess.run(
+            ["go", "mod", "init", module],
+            cwd=project_dir,
+            check=True,
+            capture_output=True,
+        )
+        console.print(f"  [dim]ran[/] go mod init {module}")
+    except (subprocess.CalledProcessError, FileNotFoundError) as e:
+        console.print(f"  [yellow]warn[/] go mod init failed ({e}); writing fallback go.mod")
+        (project_dir / "go.mod").write_text(f"module {module}\n\ngo 1.23\n")
+
+
+def _create_layout(project_dir: Path) -> None:
+    """Create the canonical internal/ tree."""
+    subdirs = [
+        "cmd/server",
+        "internal/cmd",
+        "internal/config",
+        "internal/api",
+        "internal/domain",
+        "internal/obs",
+        ".github/workflows",
+    ]
+    for sd in subdirs:
+        (project_dir / sd).mkdir(parents=True)
+
+
+def _write_files(project_dir: Path, name: str, module: str, purpose: str) -> None:
+    """Render every template into the project tree."""
+    for tmpl_name, out_rel, is_format in FILES:
+        subs = (
+            {"name": name, "module": module, "short_purpose": purpose}
+            if is_format
+            else {}
+        )
+        content = _render(tmpl_name, **subs)
+        out_path = project_dir / out_rel
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(content)
+        console.print(f"  [dim]wrote[/] {out_rel}")
+
+
+def main(
+    name: str,
+    path: str = typer.Option(".", help="Parent dir"),
+    module: str = typer.Option("", help="Go module path; default: <name>"),
+    purpose: str = typer.Option("HTTP", help="Short purpose for AGENTS.md"),
+) -> None:
+    """Scaffold a new Go project with the strict toolchain."""
+    project_dir = Path(path) / name
+    if project_dir.exists():
+        console.print(f"[red]✗[/red] {project_dir} already exists")
+        sys.exit(1)
+
+    module_path = module or name
+
+    project_dir.mkdir(parents=True)
+    _create_layout(project_dir)
+    _init_go_module(project_dir, module_path)
+    _write_files(project_dir, name, module_path, purpose)
+
+    console.print(f"\n[bold green]Done![/] cd {project_dir}")
+    console.print("  go get github.com/caarlos0/env/v11")
+    console.print("  task        # fmt + lint + test")
+
+
+if __name__ == "__main__":
+    typer.run(main)

package/node_modules/@litcodex/lit-loop/skills/lit-code/scripts/go/templates/.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yml,yaml,json,md}]
+indent_style = space
+indent_size = 2