@horka/app-forge 0.1.0

package/templates/packs/swift-ios/pack.json

@@ -0,0 +1,11 @@
+{
+  "id": "swift-ios",
+  "label": "iOS app — Swift 6.2 / SwiftUI / CloudKit",
+  "languages": ["swift"],
+  "idPrompt": "Bundle identifier",
+  "requirements": [
+    "Xcode 26+",
+    "XcodeGen (brew install xcodegen) — run `xcodegen generate` to create the .xcodeproj"
+  ],
+  "notes": "Packages build day one: swift test --package-path Packages/{{PROJECT_NAME}}Core"
+}

package/templates/packs/swift-ios/project.yml

@@ -0,0 +1,33 @@
+# XcodeGen manifest — run `xcodegen generate` to (re)create {{PROJECT_NAME}}.xcodeproj.
+# The .xcodeproj is gitignored: this file is the source of truth (merge-conflict-free).
+name: {{PROJECT_NAME}}
+options:
+  bundleIdPrefix: {{BUNDLE_ID}}
+  deploymentTarget:
+    iOS: "26.0"
+packages:
+  {{PROJECT_NAME}}DS:
+    path: Packages/{{PROJECT_NAME}}DS
+  {{PROJECT_NAME}}Core:
+    path: Packages/{{PROJECT_NAME}}Core
+  DataLayer:
+    path: Packages/DataLayer
+targets:
+  {{PROJECT_NAME}}:
+    type: application
+    platform: iOS
+    sources: [{{PROJECT_NAME}}]
+    dependencies:
+      - package: {{PROJECT_NAME}}DS
+      - package: {{PROJECT_NAME}}Core
+      - package: DataLayer
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: {{BUNDLE_ID}}
+        SWIFT_VERSION: "6.2"
+        SWIFT_STRICT_CONCURRENCY: complete
+        SWIFT_DEFAULT_ACTOR_ISOLATION: MainActor
+        GENERATE_INFOPLIST_FILE: true
+        INFOPLIST_KEY_UILaunchScreen_Generation: true
+        CURRENT_PROJECT_VERSION: 1
+        MARKETING_VERSION: 0.1.0

package/templates/packs/swift-ios/{{PROJECT_NAME}}/App/App.swift

@@ -0,0 +1,32 @@
+import SwiftUI
+import {{PROJECT_NAME}}DS
+
+@main
+struct {{PROJECT_NAME}}App: SwiftUI.App {   // qualified: `App` (unqualified) is our namespace enum
+    var body: some Scene {
+        WindowGroup {
+            RootView()
+                // Dark-first: lock the scheme so system chrome (sheets, alerts, keyboard) matches
+                // the dark token palette — see docs-architecture/DESIGN_SYSTEM.md.
+                .preferredColorScheme(.dark)
+        }
+    }
+}
+
+/// Root gate — grows at kickoff into: !isReady → Splash, needsOnboarding → Welcome, else → tabs.
+/// (See docs-architecture/NAVIGATION.md.)
+struct RootView: View {
+    var body: some View {
+        ZStack {
+            Color.DS.background.ignoresSafeArea()
+            VStack(spacing: DS.Padding.m) {
+                Text("{{PROJECT_NAME}}")
+                    .designSystem(font: .largeTitle)
+                    .foregroundStyle(DS.Gradients.brand)
+                Text("Hello 👋")
+                    .designSystem(font: .callout)
+                    .foregroundStyle(Color.DS.textSecondary)
+            }
+        }
+    }
+}

package/templates/packs/swift-ios/{{PROJECT_NAME}}/App/AppNamespace.swift

@@ -0,0 +1,4 @@
+/// Namespace for app screens: `extension App { struct Feed: View }` → call sites read `App.Feed`.
+/// IMPORTANT: this enum collides with the `SwiftUI.App` protocol by design — the @main entry point
+/// must declare `struct {{PROJECT_NAME}}App: SwiftUI.App` (fully qualified). See CONVENTIONS.md §4.
+enum App {}

package/templates/packs/ts-sdk/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — {{BUNDLE_ID}}
+
+All notable changes, newest first. Versions are git tags (`vX.Y.Z`); clients pin them.
+
+## [0.1.0]
+
+- Initial scaffold: fetch transport with normalized `ApiError`, injected storage
+  (`SDKContext`) and logger (`SDKLogger`) ports, `AuthClient` with single-flight token
+  refresh, types-only `./types` subpath, dist verification gate.

package/templates/packs/ts-sdk/CLAUDE.md

@@ -0,0 +1,72 @@
+# {{PROJECT_NAME}} — Claude Code Operating Manual
+
+This project was scaffolded by **AppForge** (pack: TypeScript SDK): a Claude-Code-first
+architecture extracted from production SDKs. You (Claude) are the team lead AND the
+primary developer. Follow this manual exactly — it encodes hard-won lessons, not preferences.
+
+## Identity
+- Package: **`{{BUNDLE_ID}}`** ({{PROJECT_NAME}}) · TypeScript, strict · Node 20+ / evergreen browsers
+- This is a **typed SDK**: the single client library between an API and all of its consumers
+  (web, SSR, CLI, CI…).
+
+## Multi-repo position — this repo is the CONTRACT layer
+The product spans repos: `backend → SDK (this repo) → clients`. Everything here follows
+`docs-architecture/MULTI_REPO_CONTRACT.md`:
+- **Backend changes land here second** — never start SDK work against a backend whose tests
+  are red; never let clients start before this SDK builds, type-checks, tests green and is
+  **tagged**.
+- **Clients consume tagged releases only** (`#vX.Y.Z` or a registry pin) — never a branch.
+- **Breaking change ⇒ MIGRATION.md entry + version bump + tag**, in the same change.
+- The public surface is the `exports` map. Anything not exported does not exist.
+
+## Session protocol (MANDATORY)
+1. **Session start**: run the `restore-context` skill — read `.claude/memory/*.md` before doing anything. Never invent project facts.
+2. **Empty project / new idea**: run the `kickoff` skill — it interviews the user, writes the PRD, plans slices, then builds autonomously.
+3. **After significant work**: update `.claude/memory/PROJECT_STATE.md` (and DECISIONS/NEXT_STEPS when relevant) — `save-context` skill.
+
+## Architecture (read the docs before coding)
+The knowledge base lives in `docs-architecture/`. Read the relevant doc BEFORE touching that area:
+
+| You are about to… | Read first |
+|---|---|
+| understand the layer model (stack-agnostic) | `ARCHITECTURE_PRINCIPLES.md` |
+| plan/deliver slices, validate, update memory | `DELIVERY.md` |
+| coordinate with the backend or a client repo | `MULTI_REPO_CONTRACT.md` |
+| anything SDK-shaped (this whole repo) | `SDK_CONTRACT.md` — this pack instantiates it |
+| add/move any file, add a resource client | `ARCHITECTURE.md` |
+| write any TypeScript code | `CONVENTIONS_TS.md` |
+| accept user-supplied URLs (webhooks…) | `SECURITY_USER_URLS.md` |
+| write any documentation | `DOCS_PLACEMENT.md` |
+| add caching/feature flags/auth shortcuts | `ANTI_PATTERNS.md` |
+
+Layer summary (universal contract in ARCHITECTURE_PRINCIPLES.md, TS mapping in ARCHITECTURE.md):
+L0 `src/types/` + `src/errors/` (wire types, ApiError — import nothing above) · L1 logger port ·
+L2 `src/core/` (fetch transport, storage adapters) · L3 `src/clients/` (resource clients +
+single-flight auth use case) · L5 `src/index.ts` (composition root, sole public surface).
+From the consumer's seat, this whole package is **their L2 Data brick**.
+
+## Non-negotiable rules
+- **Never claim done without proof**: `npm run typecheck` + `npx vitest run` + `npm run build`
+  (which runs the dist/types verification) all green, outputs shown.
+- **The single-flight tests are the spec.** `tests/singleFlight.test.ts` must never be
+  weakened or skipped — the concurrency bug it pins reappears every time someone
+  "simplifies" the auth use case.
+- **Zero `console.*` in `src/`** — logging goes through the injected `SDKLogger` port,
+  debug-gated, and never logs token values.
+- **`.ts` sources only** — never author `.d.ts` files in `src/` (declaration generators
+  silently skip them; see SDK_CONTRACT.md §4). Never commit `dist/`.
+- **`dependencies` stays `{}`** unless a DECISIONS.md entry justifies a runtime dep.
+  Build tooling lives in `devDependencies`, always.
+- **Tagged releases only**; every breaking change ships its MIGRATION.md entry.
+
+## Build commands
+```bash
+npm install
+npm run typecheck      # tsc --noEmit — fastest signal
+npx vitest run         # full suite, includes the single-flight regression test
+npm run build          # tsup (esm+cjs+d.ts) THEN scripts/verify-dist.mjs gate
+```
+
+## Git
+- Never push without explicit user approval. Feature branches; commit format `add/update/fix(scope) - description`.
+- No AI attribution in commits or file headers.

package/templates/packs/ts-sdk/MIGRATION.md

@@ -0,0 +1,28 @@
+# Migration Guide — {{BUNDLE_ID}}
+
+One dated section per **breaking change**, newest first, written in the same change that
+breaks (CONVENTIONS_TS.md §8, MULTI_REPO_CONTRACT.md breaking-change protocol). Every code
+sample must compile against the real SDK surface — invented samples are worse than no docs.
+
+Template:
+
+```markdown
+## vX.Y.0 — <one-line summary> (YYYY-MM-DD)
+
+### What changed
+Before / after code blocks, copied from real consumer usage.
+
+### Why
+The constraint that forced the break.
+
+### Impact
+What consumers must do, per platform if it differs.
+
+### Security implications
+Mandatory when auth, tokens or cookies are involved — state the new tradeoff and the
+required mitigations.
+```
+
+---
+
+*No entries yet — v0.1.0 is the initial scaffold.*

package/templates/packs/ts-sdk/claude/memory/COMMANDS.md

@@ -0,0 +1,21 @@
+# {{PROJECT_NAME}} — Commands
+
+> Only commands proven to work in THIS project, with exact flags.
+
+## Fast loop (always in this order)
+npm run typecheck                          # tsc --noEmit — fastest signal
+npx vitest run                             # full suite (CI mode)
+npx vitest run tests/singleFlight.test.ts  # the auth concurrency regression suite alone
+
+## Build + dist verification
+npm run build         # tsup (esm+cjs+d.ts, "." and "./types" entries) THEN scripts/verify-dist.mjs
+ls dist dist/types    # eyeball the artifacts when in doubt
+
+## Release gate (before tagging — see CONVENTIONS_TS.md §8)
+npm pkg get dependencies     # must be the expected object (ideally {})
+npm pack --dry-run           # tarball must contain dist + manifest only
+git tag v0.X.Y               # clients pin THIS, never a branch
+
+## Consumer-side linking (lives in the CLIENT repo — SDK_CONTRACT.md §6)
+# sdk:local / sdk:prod scripts switch between file:../ and the pinned tag;
+# a file: link must never reach a shared branch.

package/templates/packs/ts-sdk/docs-architecture/ARCHITECTURE.md

@@ -0,0 +1,132 @@
+# ARCHITECTURE — Typed TypeScript SDK (the contract package)
+
+This package is the **contract layer** of a multi-repo product: `backend → SDK → clients`
+(MULTI_REPO_CONTRACT.md). From any consumer's seat, the whole package is **their L2 Data
+brick** — the network client behind their repository implementations. Internally it runs
+the universal L0–L5 lattice (ARCHITECTURE_PRINCIPLES.md) in miniature, exactly as
+SDK_CONTRACT.md prescribes. Read both before touching this repo; this file maps them onto
+TypeScript files.
+
+## 1. Layer model — TS instantiation
+
+```
+L5  src/index.ts        composition root: constructs adapters, wires transport → auth →
+                        resource clients, re-exports the ENTIRE public surface (and only it)
+L3  src/clients/        one typed client per API resource + the secure-request use case
+                        (single-flight token refresh lives in AuthClient)
+L2  src/core/           adapters & ports: HttpClient (fetch transport), SDKContext
+                        (storage port + adapters), withTimeout primitive
+L1  src/core/Logger.ts  ops port: SDKLogger, no-op by default, debug-gated at the root
+L0  src/types/          wire types mirroring backend DTOs — import NOTHING in the package
+    src/errors/         ApiError + fromResponse normalization — imports types only
+```
+
+Tests live in `tests/`, stub the ports, and exercise the **public surface**
+(`import … from '../src/index'`) so they double as compile-time proof of the exports.
+
+## 2. Dependency direction
+
+| Directory | may import | must NEVER import |
+|---|---|---|
+| `types/` | nothing | anything — a `types/` file with an import is a bug |
+| `errors/` | `types/` | `core/`, `clients/`, `index.ts` |
+| `core/` | `types/`, `errors/` | `clients/`, `index.ts` |
+| `clients/` | core **ports** (`HttpTransport`, `SDKContext`, `SDKLogger`), `types/`, `errors/` | `fetch`/`document` directly, sibling clients, `index.ts` |
+| `index.ts` | everything | — (sole assembly point) |
+
+The import graph is the architecture — every violation is grep-visible:
+
+```bash
+grep -rn "fetch("        src/clients/ src/errors/ src/types/   # must be empty (transport port only)
+grep -rn "console\."     src/                                  # must be empty (injected logger only)
+grep -rn "from '.*clients" src/types/ src/errors/ src/core/    # must be empty (no upward imports)
+grep -rln "document\.\|window\." src/ --include='*.ts'         # browser APIs only inside a storage adapter
+```
+
+> ⚠️ **Gotcha:** Symptom — a "tiny helper" in `types/` starts importing `ApiError`, then a
+> client, and suddenly the types-only subpath drags the HTTP runtime into the consumer's
+> pure L3 layer. Cause — runtime code creeping into `types/`. Fix — `types/` holds
+> declarations only (interfaces, type aliases, string-literal unions); anything with a
+> runtime body lives in `core/` or above.
+
+## 3. The SDK from the consumer's seat
+
+- Consumers import **`{{BUNDLE_ID}}`** (runtime: clients, errors, adapters) or
+  **`{{BUNDLE_ID}}/types`** (wire types only, erased at compile time). Nothing else exists —
+  the `exports` map is the law (MULTI_REPO_CONTRACT.md "Never bypass the SDK").
+- Consumer L3 declares repository contracts and may reference `{{BUNDLE_ID}}/types`;
+  consumer L2 implements those contracts by calling this SDK and mapping wire → domain.
+  No consumer L3+ brick instantiates the SDK; their composition root (L5) wires it.
+- Clients pin a **tag**, never a branch (MULTI_REPO_CONTRACT.md). Cutting a release here is
+  what unblocks client work — see the release checklist in CONVENTIONS_TS.md.
+
+## 4. Adding a resource client — the recipe
+
+Backend first (its tests green, DTOs frozen), then here, then clients — always in that order.
+
+1. **`src/types/`** — add wire types mirroring the new DTOs (plain `.ts`, no imports).
+2. **`src/clients/FooClient.ts`** — thin, typed methods; secure endpoints take the
+   `AuthClient`, public endpoints take the `HttpTransport` port directly:
+
+   ```ts
+   export class ProjectClient {
+     constructor(private readonly auth: AuthClient) {}
+     list(): Promise<Project[]> { return this.auth.request('GET', '/projects'); }
+     create(draft: ProjectDraft): Promise<Project> { return this.auth.request('POST', '/projects', draft); }
+   }
+   ```
+
+   No URL building beyond the path, no response re-parsing, no error catching — the
+   transport normalizes errors (`ApiError`), the consumer maps them to UX (SDK_CONTRACT.md §2).
+3. **`src/index.ts`** — construct it in the composition root, expose it as a readonly
+   field, re-export the class and its wire types.
+4. **`scripts/verify-dist.mjs`** — add the new public names to the surface list so the
+   build gate proves the types actually shipped.
+5. **`tests/`** — stub `HttpTransport`, assert method/path/payload and error mapping.
+6. Build green → version bump → tag (CONVENTIONS_TS.md §8).
+
+## 5. Auth — why `clients/AuthClient.ts` looks the way it does
+
+The single-flight refresh contract (shared inflight promise, bounded wait, retry exactly
+once, clear-tokens-on-failure) is specified in **SDK_CONTRACT.md §3** — read it before
+touching `AuthClient`. Local invariants on top:
+
+- `tests/singleFlight.test.ts` is the executable spec: N concurrent 401s ⇒ **exactly one**
+  refresh call against a fake API that enforces *single-use* rotating refresh tokens. It
+  also pins the timeout and failure paths. Never weaken or skip these tests.
+- The refresh call itself goes through the raw transport, never through `request()` —
+  a refresh that 401s must not trigger another refresh.
+- Token storage goes through the `SDKContext` port. The skeleton ships the **memory
+  adapter** only; adding a browser/SSR adapter is a recorded decision (token-storage
+  tradeoff table in SDK_CONTRACT.md §3 → `DECISIONS.md`), never a copied default.
+
+## 6. Build pipeline — dual output, verified types
+
+```
+npm run build  =  tsup (entries: src/index.ts + src/types/index.ts → esm + cjs + .d.ts)
+                  THEN node scripts/verify-dist.mjs
+```
+
+`verify-dist.mjs` fails the build unless every expected `dist/` artifact exists **and**
+every name on the public-surface list appears in the emitted declarations. "It built" is
+not proof the types shipped (SDK_CONTRACT.md §4) — this gate makes the proof mechanical.
+
+> ⚠️ **Gotcha:** Symptom — consumers report "module has no exported member" for types that
+> visibly exist in `src/`. Cause — the types were authored as `.d.ts` files; declaration
+> generators treat those as already-compiled and emit nothing for them. Fix — author all
+> types as plain `.ts`; the verify-dist gate catches any regression at build time.
+
+> ⚠️ **Gotcha:** Symptom — the SDK behaves differently in the consumer than in this repo's
+> tests, and `git diff` is clean. Cause — a stale committed `dist/` shadowing fresh sources.
+> Fix — `dist/` is gitignored here and must stay that way; artifacts are built at tag time,
+> never reviewed, never committed.
+
+## 7. Why this works with AI agents
+
+- **Seconds-fast ground truth**: `npm run typecheck` and `npx vitest run` give precise
+  feedback without any consumer app — iterate here before touching client repos.
+- **Ports make tests cheap**: every client is testable by stubbing `HttpTransport`; no
+  network, no mock servers, no global-fetch patching.
+- **Grep-visible boundaries** (§2): an agent can verify the architecture with four greps.
+- **Mechanical release gates**: verify-dist + the single-flight suite encode the two
+  historical production failures as automated checks, so no session re-learns them.

package/templates/packs/ts-sdk/docs-architecture/CONVENTIONS_TS.md

@@ -0,0 +1,152 @@
+# CONVENTIONS — TypeScript for a typed SDK
+
+House rules for every line of TypeScript in this repo. They instantiate SDK_CONTRACT.md
+for this package — when in doubt, that file wins. Each rule below was paid for in
+production; none is style preference.
+
+## 1. Compiler discipline
+
+- `strict: true`, no `any` (use `unknown` + narrowing). A cast (`as`) needs a comment
+  explaining why narrowing is impossible.
+- `verbatimModuleSyntax: true` — type-only imports are written `import type { … }`. This
+  keeps the types-only subpath genuinely runtime-free.
+- `npm run typecheck` (`tsc --noEmit`) is the fastest signal — run it before the test
+  suite, run both before any build.
+
+### `.ts` sources only — never author `.d.ts`
+
+All of `src/` is plain `.ts`, **including every file in `src/types/`**. Declarations are
+*generated* into `dist/` by the build, never written by hand.
+
+> ⚠️ **Gotcha:** Symptom — consumers get "module has no exported member" for roughly half
+> the public types while the source visibly contains them. Cause — types authored as
+> `.d.ts` files: declaration generators treat them as already-compiled output and silently
+> emit nothing, and a committed `dist/` masked the hole for months (a production team
+> shipped 13 of 21 type modules missing this way). Fix — `.ts` sources only, `dist/`
+> gitignored, and the `scripts/verify-dist.mjs` gate (run by `npm run build`) failing the
+> build when a public name is absent from the emitted declarations.
+
+## 2. Exports map — the public surface, and the types-only subpath
+
+`package.json#exports` defines what exists. This SDK exposes exactly two entries:
+
+- `"."` — the runtime surface (composition root, clients, errors, adapters).
+- `"./types"` — **types only**, so a consumer's pure L3 layer can reference wire types
+  without dragging the HTTP client into it (type imports erase at compile time).
+
+Rules:
+- Adding/removing/renaming a subpath is an architectural decision → `DECISIONS.md` entry
+  + semver impact assessed. Deep paths (`/src/*`, `/dist/internal/*`) are never exposed.
+- Everything public is re-exported from `src/index.ts` (or `src/types/index.ts`); a type
+  reachable only through a deep import is a bug.
+- `"sideEffects": false` stays true: no module-level statements with effects — module load
+  must be free (no env reads, no global patching, no top-level `await`).
+
+## 3. Dependencies policy — runtime deps target zero
+
+- `"dependencies": {}` — the transport is built-in `fetch`; an SDK drags its runtime deps
+  into every consumer's tree. Adding one requires a `DECISIONS.md` entry justifying it.
+- Build/test tooling (`tsup`, `typescript`, `vitest`) lives in `devDependencies`, always.
+- Release audit (it's in the checklist, §8): `npm pkg get dependencies` must print the
+  expected object — ideally `{}`.
+
+> ⚠️ **Gotcha:** Symptom — every consumer install pulls a bundler plugin (and its whole
+> dependency tree) they never use. Cause — a declaration-generator plugin added under
+> `dependencies` instead of `devDependencies`; nothing fails, so it ships for months.
+> Fix — `dependencies` may contain only what `src/` actually imports at runtime; audit at
+> every release (see SDK_CONTRACT.md §1).
+
+## 4. Logging — injected port, silent by default
+
+- **Zero `console.*` in `src/`** — grep-enforced (`grep -rn "console\." src/` must be
+  empty); add `no-console: error` if you introduce a linter. Build scripts (`scripts/`)
+  may print — they run on developer machines, not inside consumers.
+- All logging goes through the `SDKLogger` port; the default is a no-op, and `debug()`
+  only fires when the consumer passes `debug: true`. The *consumer* owns the switch.
+- **Never log token values, `Authorization` headers, or token-presence booleans.** A
+  production team once logged method + URL + which auth tokens were present on every
+  request: unfilterable console noise for every consumer and a free map of the auth
+  topology in devtools (SDK_CONTRACT.md §5). Log method + path, nothing from headers.
+
+## 5. Errors — normalize once, never re-parse
+
+- Every non-2xx response becomes an `ApiError` via `ApiError.fromResponse(status, text)` —
+  thrown by the transport, the single place that reads response bodies on failure.
+- The wire error shape `{ code, name, description }` is frozen contract: renaming a field
+  is a **breaking change in two repos** (SDK_CONTRACT.md §2) — major bump + MIGRATION entry.
+- Clients (`src/clients/`) never catch-and-rewrap, never inspect bodies; consumers map
+  `statusCode` → UX in one shared handler, never re-parse raw responses.
+- Genuine network failures (DNS, refused connection) propagate as-is — inventing a fake
+  status code for them would lie to the consumer's error handler.
+
+## 6. Auth invariants — single-flight or nothing
+
+The contract is SDK_CONTRACT.md §3; the local law:
+
+- One shared inflight refresh promise; latecomers await it; the wait is **bounded** by a
+  timeout that rejects (never hang waiters forever).
+- On 401: join/start the refresh, then retry the original request **exactly once**. Two
+  retries hide real auth breakage; zero retries logs users out on every token expiry.
+- On any refresh failure: **fail every waiter** — a half-authenticated session is worse than
+  a clean error. But **clear tokens ONLY on a real auth rejection** (a 401, or a 400 carrying
+  `invalid_grant`): that is the server's verdict that the refresh token is dead. A transport
+  failure — offline, DNS, connection refused, timeout (`RefreshTimeout`/408), or 5xx — never
+  reached a verdict, so the tokens are **kept**; clearing them would force a gratuitous logout
+  on a session that may still be valid (this matches §5: network failures propagate as-is).
+- The refresh call uses the raw transport, never the secure `request()` path (a 401 from
+  the refresh endpoint must not recurse).
+- `tests/singleFlight.test.ts` pins all of this against a fake API with *single-use*
+  rotating refresh tokens. It is the regression test for a real production bug
+  (N parallel 401s → N refreshes → N−1 failures → random logouts) and is non-negotiable.
+
+> ⚠️ **Gotcha:** Symptom — intermittent logouts return months after the fix. Cause —
+> someone "simplified" the auth use case and dropped the shared inflight promise; the bug
+> is invisible in manual testing because it needs concurrent expiry. Fix — the concurrency
+> test stays, and any `AuthClient` refactor runs it first.
+
+## 7. Testing conventions
+
+- **vitest**, plain `node` environment. `npx vitest run` (CI mode) is the gate; watch mode
+  is for development only.
+- **Stub the `HttpTransport` port** in client/use-case tests — never patch global `fetch`
+  there (only a transport adapter test may). Fakes enforce realistic API behavior (e.g.
+  single-use refresh tokens), not just canned responses.
+- Concurrency tests use `Promise.all` / `Promise.allSettled` over real async boundaries —
+  no fake timers for the single-flight suite (timing is the point; keep timeouts short).
+- Every test asserts observable behavior (calls, payloads, thrown `ApiError` fields).
+  A test without a meaningful assertion is deleted, not kept for coverage.
+- Tests import from `../src/index` wherever possible — they double as proof that the
+  public surface actually exports what consumers need.
+
+## 8. Releases & versioning
+
+- **Semver, tagged.** While `0.x`: breaking ⇒ **minor** bump; from `1.0.0`: breaking ⇒
+  **major**. (This convention is stated here so clients can rely on it — changing it is a
+  DECISIONS.md entry.)
+- **Never commit `dist/`** — built at tag time. Consumers pin tags or registry versions,
+  never a branch (MULTI_REPO_CONTRACT.md — branch pins broke a production deploy with an
+  empty diff).
+- Every breaking change ships a dated **MIGRATION.md** section in the same change: what
+  changed (before/after code), why, impact, and security implications when auth/cookies
+  are involved. Every sample in it must compile against the real surface
+  (SDK_CONTRACT.md §7 — invented samples convert knowledge gaps into false confidence).
+
+Release checklist (all outputs shown, per DELIVERY.md proof discipline):
+
+```bash
+npm run typecheck && npx vitest run     # green
+npm run build                           # tsup + verify-dist gate green
+npm pkg get dependencies                # expected (ideally {})
+npm pack --dry-run                      # tarball = dist + manifest, nothing else
+# CHANGELOG entry (+ MIGRATION entry if breaking) → bump version → git tag vX.Y.Z
+```
+
+## 9. Naming & style
+
+- One exported class per file, file named after it: `AuthClient.ts`, `ProjectClient.ts`.
+  Resource clients end in `Client`; ports are interfaces named for the capability
+  (`HttpTransport`, `SDKContext`, `SDKLogger`).
+- Names express intent, not technology (`ProjectClient.list()`, not `getProjectsHTTP`).
+- String-literal unions over `enum` (erasable, tree-shakeable, JSON-friendly).
+- `async/await` over `.then()` chains; no default exports; no module-level mutable state
+  outside class instances (the inflight refresh promise lives on the client instance).

package/templates/packs/ts-sdk/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+*.tgz
+npm-debug.log*

package/templates/packs/ts-sdk/pack.json

@@ -0,0 +1,11 @@
+{
+  "id": "ts-sdk",
+  "label": "TypeScript SDK — typed client between API and front(s)",
+  "languages": ["typescript"],
+  "idPrompt": "Package name (npm-style, e.g. @org/myapp-sdk)",
+  "requirements": [
+    "Node.js 20+ (built-in fetch)",
+    "npm 10+"
+  ],
+  "notes": "SDK builds and tests day one: npm install && npm run build && npm test"
+}

package/templates/packs/ts-sdk/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "{{BUNDLE_ID}}",
+  "version": "0.1.0",
+  "description": "{{PROJECT_NAME}} — typed SDK between the API and its clients",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "types": ["./dist/types/index.d.ts"]
+    }
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./types": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/types/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.cts",
+        "default": "./dist/types/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup && node scripts/verify-dist.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}

package/templates/packs/ts-sdk/scripts/verify-dist.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Build gate: "it built" is NOT proof the types shipped (SDK_CONTRACT.md §4).
+ * A production team once shipped 13 of 21 type modules silently missing from
+ * dist/ because the declaration generator skipped .d.ts sources and a committed
+ * dist/ masked the hole. This script makes the proof mechanical:
+ *   1. every expected dist/ artifact exists;
+ *   2. every public name is present in the emitted declarations.
+ *
+ * Runs as part of `npm run build`. Add new public names when you extend index.ts.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+
+const REQUIRED_FILES = [
+  'dist/index.js',
+  'dist/index.cjs',
+  'dist/index.d.ts',
+  'dist/index.d.cts',
+  'dist/types/index.js',
+  'dist/types/index.cjs',
+  'dist/types/index.d.ts',
+  'dist/types/index.d.cts',
+];
+
+// Names that consumers import — keep in sync with src/index.ts and src/types/index.ts.
+const PUBLIC_SURFACE = {
+  'dist/index.d.ts': [
+    'createSdk',
+    'SDKOptions',
+    'ApiError',
+    'AuthClient',
+    'HttpClient',
+    'HttpTransport',
+    'createMemoryContext',
+    'SDKContext',
+    'SDKLogger',
+    'TokenPair',
+  ],
+  'dist/types/index.d.ts': ['HttpMethod', 'TokenPair', 'ApiErrorBody'],
+};
+
+let failed = false;
+
+for (const file of REQUIRED_FILES) {
+  if (!existsSync(file)) {
+    console.error(`✗ missing build artifact: ${file}`);
+    failed = true;
+  }
+}
+
+if (!failed) {
+  for (const [file, names] of Object.entries(PUBLIC_SURFACE)) {
+    const dts = readFileSync(file, 'utf8');
+    for (const name of names) {
+      if (!dts.includes(name)) {
+        console.error(`✗ ${file}: public name "${name}" not found in emitted declarations`);
+        failed = true;
+      }
+    }
+  }
+}
+
+if (failed) {
+  console.error('\ndist verification FAILED — do not tag this build.');
+  process.exit(1);
+}
+console.log(`✓ dist verification OK (${REQUIRED_FILES.length} artifacts, declarations contain the public surface)`);