ts-procedures 8.1.1 → 8.2.1

package/src/codegen/targets/_shared/write-files.test.ts

@@ -1,8 +1,14 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { mkdir, readFile, rm, writeFile, stat, mkdtemp } from 'node:fs/promises'
+import { mkdir, readFile, rm, writeFile, stat, mkdtemp, readdir } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { writeGeneratedFiles } from './write-files.js'
+import { CODEGEN_HEADER } from '../../constants.js'
+
+/** Build file contents that carry the package signature (a generated file). */
+function signed(body = 'export const x = 1\n'): string {
+  return `${CODEGEN_HEADER}\n\n${body}`
+}
 
 describe('writeGeneratedFiles', () => {
   describe('dryRun mode', () => {
@@ -32,22 +38,46 @@ describe('writeGeneratedFiles', () => {
       await expect(stat(dir)).rejects.toBeInstanceOf(Error)
     })
 
-    it('logs a clean-outDir notice when cleanOutDir is true', async () => {
-      await writeGeneratedFiles([], '/out', { dryRun: true, cleanOutDir: true })
-      expect(logSpy).toHaveBeenCalledWith('[dry-run] Would clean outDir: /out')
-    })
-
-    it('does not log clean-outDir when cleanOutDir is false', async () => {
-      await writeGeneratedFiles([{ path: '/out/x', code: 'x' }], '/out', { dryRun: true })
-      const messages = logSpy.mock.calls.map((c: unknown[]) => c[0])
-      expect(messages.find((m: unknown) => String(m).includes('Would clean'))).toBeUndefined()
-    })
-
     it('counts bytes as utf-8', async () => {
       // "é" is 2 bytes in utf-8.
       await writeGeneratedFiles([{ path: '/x/e.txt', code: 'é' }], '/x', { dryRun: true })
       expect(logSpy).toHaveBeenCalledWith('[dry-run] Would write: /x/e.txt (2 bytes)')
     })
+
+    it('logs would-remove for an orphaned generated file under cleanOutDir, without deleting it', async () => {
+      const outDir = await mkdtemp(join(tmpdir(), 'write-files-dry-'))
+      try {
+        await writeFile(join(outDir, 'orphan.ts'), signed(), 'utf-8')
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'fresh.ts'), code: signed() }],
+          outDir,
+          { dryRun: true, cleanOutDir: true },
+        )
+
+        expect(logSpy).toHaveBeenCalledWith(
+          `[dry-run] Would remove orphaned generated file: ${join(outDir, 'orphan.ts')}`,
+        )
+        // Nothing was actually removed.
+        expect(await readFile(join(outDir, 'orphan.ts'), 'utf-8')).toBe(signed())
+      } finally {
+        await rm(outDir, { recursive: true, force: true })
+      }
+    })
+
+    it('does not log a would-remove notice when cleanOutDir is false', async () => {
+      const outDir = await mkdtemp(join(tmpdir(), 'write-files-dry-'))
+      try {
+        await writeFile(join(outDir, 'orphan.ts'), signed(), 'utf-8')
+        await writeGeneratedFiles([{ path: join(outDir, 'x.ts'), code: signed() }], outDir, {
+          dryRun: true,
+        })
+        const messages = logSpy.mock.calls.map((c: unknown[]) => String(c[0]))
+        expect(messages.find((m: string) => m.includes('Would remove'))).toBeUndefined()
+      } finally {
+        await rm(outDir, { recursive: true, force: true })
+      }
+    })
   })
 
   describe('real write mode', () => {
@@ -79,32 +109,113 @@ describe('writeGeneratedFiles', () => {
       expect(await readFile(join(nested, 'x.txt'), 'utf-8')).toBe('x')
     })
 
-    it('removes outDir when cleanOutDir is true before writing', async () => {
-      // Pre-populate a stale file.
-      await mkdir(outDir, { recursive: true })
-      await writeFile(join(outDir, 'stale.txt'), 'stale', 'utf-8')
-
-      await writeGeneratedFiles(
-        [{ path: join(outDir, 'fresh.txt'), code: 'fresh' }],
-        outDir,
-        { cleanOutDir: true },
-      )
-
-      await expect(readFile(join(outDir, 'stale.txt'), 'utf-8')).rejects.toBeInstanceOf(Error)
-      expect(await readFile(join(outDir, 'fresh.txt'), 'utf-8')).toBe('fresh')
+    describe('cleanOutDir (marker-based prune)', () => {
+      it('removes an orphaned generated file that is no longer emitted', async () => {
+        // A previously-generated scope file that this run does not re-emit.
+        await writeFile(join(outDir, 'orphan-scope.ts'), signed(), 'utf-8')
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'fresh.ts'), code: signed() }],
+          outDir,
+          { cleanOutDir: true },
+        )
+
+        await expect(readFile(join(outDir, 'orphan-scope.ts'), 'utf-8')).rejects.toBeInstanceOf(
+          Error,
+        )
+        expect(await readFile(join(outDir, 'fresh.ts'), 'utf-8')).toBe(signed())
+      })
+
+      it('never deletes a file that lacks the package signature', async () => {
+        // Hand-written file the developer co-located in the output dir.
+        await writeFile(join(outDir, 'hand-written.ts'), 'export const mine = 1\n', 'utf-8')
+        // Even a file that merely imports from ts-procedures (no -codegen token).
+        await writeFile(
+          join(outDir, 'helper.ts'),
+          "import { createClient } from 'ts-procedures/client'\n",
+          'utf-8',
+        )
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'fresh.ts'), code: signed() }],
+          outDir,
+          { cleanOutDir: true },
+        )
+
+        expect(await readFile(join(outDir, 'hand-written.ts'), 'utf-8')).toBe(
+          'export const mine = 1\n',
+        )
+        expect(await readFile(join(outDir, 'helper.ts'), 'utf-8')).toBe(
+          "import { createClient } from 'ts-procedures/client'\n",
+        )
+      })
+
+      it('does not delete a signed file that is part of the current output', async () => {
+        // Pre-existing signed file that IS re-emitted this run — it should be
+        // overwritten, not removed-then-rewritten in a way that loses it.
+        await writeFile(join(outDir, 'users.ts'), signed('old'), 'utf-8')
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'users.ts'), code: signed('new') }],
+          outDir,
+          { cleanOutDir: true },
+        )
+
+        expect(await readFile(join(outDir, 'users.ts'), 'utf-8')).toBe(signed('new'))
+      })
+
+      it('prunes orphans left by a different package version (version-agnostic)', async () => {
+        // A file generated by an older release: different version in the header.
+        const oldHeader = '// Auto-generated by ts-procedures-codegen (v0.0.1) — do not edit'
+        await writeFile(join(outDir, 'legacy.ts'), `${oldHeader}\n\nexport const y = 2\n`, 'utf-8')
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'fresh.ts'), code: signed() }],
+          outDir,
+          { cleanOutDir: true },
+        )
+
+        await expect(readFile(join(outDir, 'legacy.ts'), 'utf-8')).rejects.toBeInstanceOf(Error)
+      })
+
+      it('skips subdirectories entirely', async () => {
+        const sub = join(outDir, 'nested')
+        await mkdir(sub, { recursive: true })
+        await writeFile(join(sub, 'inner.ts'), signed(), 'utf-8')
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'fresh.ts'), code: signed() }],
+          outDir,
+          { cleanOutDir: true },
+        )
+
+        // The nested dir and its signed file are untouched.
+        expect(await readFile(join(sub, 'inner.ts'), 'utf-8')).toBe(signed())
+        const entries = await readdir(outDir)
+        expect(entries).toContain('nested')
+      })
+
+      it('does not throw when outDir does not exist yet', async () => {
+        const fresh = join(outDir, 'brand-new')
+        await expect(
+          writeGeneratedFiles([{ path: join(fresh, 'a.ts'), code: signed() }], fresh, {
+            cleanOutDir: true,
+          }),
+        ).resolves.toBeUndefined()
+        expect(await readFile(join(fresh, 'a.ts'), 'utf-8')).toBe(signed())
+      })
     })
 
-    it('does not remove outDir when cleanOutDir is false', async () => {
-      await mkdir(outDir, { recursive: true })
+    it('does not remove anything when cleanOutDir is false', async () => {
+      await writeFile(join(outDir, 'orphan.ts'), signed(), 'utf-8')
       await writeFile(join(outDir, 'keep.txt'), 'keep', 'utf-8')
 
-      await writeGeneratedFiles(
-        [{ path: join(outDir, 'new.txt'), code: 'new' }],
-        outDir,
-      )
+      await writeGeneratedFiles([{ path: join(outDir, 'new.ts'), code: signed() }], outDir)
 
+      // Even a signed orphan stays put when cleanOutDir is not requested.
+      expect(await readFile(join(outDir, 'orphan.ts'), 'utf-8')).toBe(signed())
       expect(await readFile(join(outDir, 'keep.txt'), 'utf-8')).toBe('keep')
-      expect(await readFile(join(outDir, 'new.txt'), 'utf-8')).toBe('new')
+      expect(await readFile(join(outDir, 'new.ts'), 'utf-8')).toBe(signed())
     })
   })
 })

package/src/codegen/targets/_shared/write-files.ts

@@ -1,4 +1,6 @@
-import { mkdir, rm, writeFile } from 'node:fs/promises'
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { CODEGEN_SIGNATURE } from '../../constants.js'
 
 export interface GeneratedFile {
   path: string
@@ -8,10 +10,46 @@ export interface GeneratedFile {
 export interface WriteOptions {
   /** When true, log what would happen instead of touching the filesystem. */
   dryRun?: boolean
-  /** When true, recursively delete `outDir` before writing. */
+  /**
+   * When true, remove orphaned generated files from `outDir` before writing —
+   * i.e. files this run no longer emits that carry the `ts-procedures-codegen`
+   * signature. Files lacking the signature (hand-written, other tools' output)
+   * are never touched.
+   */
   cleanOutDir?: boolean
 }
 
+/** Only the head of a file is read to detect the signature; it lives at the top. */
+const SIGNATURE_SCAN_BYTES = 512
+
+/**
+ * Returns the top-level files in `outDir` that carry the package signature but
+ * are NOT part of `written` — the orphans left behind by a prior run whose
+ * scope/route no longer exists. Subdirectories are skipped (targets emit flat),
+ * and any file without the signature is left untouched.
+ */
+async function findOrphans(outDir: string, written: Set<string>): Promise<string[]> {
+  let entries
+  try {
+    entries = await readdir(outDir, { withFileTypes: true })
+  } catch (err) {
+    // Nothing to prune if the dir doesn't exist yet (first run).
+    if ((err as { code?: string }).code === 'ENOENT') return []
+    throw err
+  }
+
+  const orphans: string[] = []
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const path = join(outDir, entry.name)
+    if (written.has(path)) continue // re-emitted this run — it will be overwritten
+    const buf = await readFile(path)
+    const head = buf.subarray(0, SIGNATURE_SCAN_BYTES).toString('utf-8')
+    if (head.includes(CODEGEN_SIGNATURE)) orphans.push(path)
+  }
+  return orphans
+}
+
 /**
  * Persists the generated files to disk (or simulates the writes under
  * `dryRun`). Centralises the dryRun / cleanOutDir / mkdir / writeFile
@@ -20,10 +58,11 @@ export interface WriteOptions {
  *
  * Behaviour:
  * - `dryRun: true` — logs `[dry-run] Would write: <path> (<bytes> bytes)` per
- *   file, plus a leading `[dry-run] Would clean outDir: <outDir>` when
- *   `cleanOutDir: true`. No filesystem mutation.
- * - `dryRun: false` (default) — when `cleanOutDir`, recursively removes
- *   `outDir`; then ensures it exists; then writes each file as utf-8.
+ *   file, plus `[dry-run] Would remove orphaned generated file: <path>` for
+ *   each prunable orphan when `cleanOutDir: true`. No filesystem mutation.
+ * - `dryRun: false` (default) — when `cleanOutDir`, removes orphaned generated
+ *   files (signed by `ts-procedures-codegen`, no longer emitted); then ensures
+ *   `outDir` exists; then writes each file as utf-8.
  */
 export async function writeGeneratedFiles(
   files: readonly GeneratedFile[],
@@ -31,10 +70,13 @@ export async function writeGeneratedFiles(
   opts: WriteOptions = {},
 ): Promise<void> {
   const { dryRun = false, cleanOutDir = false } = opts
+  const written = new Set(files.map((f) => f.path))
 
   if (dryRun) {
     if (cleanOutDir) {
-      console.log(`[dry-run] Would clean outDir: ${outDir}`)
+      for (const orphan of await findOrphans(outDir, written)) {
+        console.log(`[dry-run] Would remove orphaned generated file: ${orphan}`)
+      }
     }
     for (const f of files) {
       const bytes = Buffer.byteLength(f.code, 'utf-8')
@@ -44,7 +86,10 @@ export async function writeGeneratedFiles(
   }
 
   if (cleanOutDir) {
-    await rm(outDir, { recursive: true, force: true })
+    for (const orphan of await findOrphans(outDir, written)) {
+      await rm(orphan, { force: true })
+      console.log(`[ts-procedures-codegen] Removed orphaned generated file: ${orphan}`)
+    }
   }
   await mkdir(outDir, { recursive: true })
   for (const f of files) {

package/src/codegen/targets/kotlin/__fixtures__/users-golden.kt

@@ -1,5 +1,6 @@
 package com.example.api
 
+// ts-procedures-codegen — do not edit
 // Source hash: <PLACEHOLDER>
 
 import kotlinx.serialization.Contextual

package/src/codegen/targets/kotlin/emit-scope-kotlin.ts

@@ -1,7 +1,7 @@
 import type { ScopeGroup } from '../../group-routes.js'
 import type { KotlinEmitter } from './ajsc-adapter.js'
 import { emitKotlinRoute, type EmitRouteOpts } from './emit-route-kotlin.js'
-import { kotlinPackageDecl, kotlinSourceHashHeader, kotlinImports } from './format-kotlin.js'
+import { kotlinPackageDecl, kotlinSignatureHeader, kotlinSourceHashHeader, kotlinImports } from './format-kotlin.js'
 import { indent } from '../_shared/indent.js'
 import { pickDefined } from '../_shared/pick-defined.js'
 import { pascalCase } from '../_shared/pascal-case.js'
@@ -49,9 +49,10 @@ export function emitKotlinScope(
     : `object ${scopeName} {\n${innerScope}\n}`
 
   const importsBlock = kotlinImports(allImports)
+  const headerBlock = [kotlinSignatureHeader(), kotlinSourceHashHeader(opts.sourceHash)].join('\n')
   const parts = [
     kotlinPackageDecl(opts.kotlinPackage),
-    kotlinSourceHashHeader(opts.sourceHash),
+    headerBlock,
     importsBlock,
     scopeBlock,
   ].filter((p) => p.length > 0)

package/src/codegen/targets/kotlin/format-kotlin.test.ts

@@ -1,15 +1,24 @@
 import { describe, expect, it } from 'vitest'
 import {
   kotlinPackageDecl,
+  kotlinSignatureHeader,
   kotlinSourceHashHeader,
   kotlinImports,
 } from './format-kotlin.js'
+import { CODEGEN_SIGNATURE } from '../../constants.js'
 
 describe('format-kotlin', () => {
   it('emits a package declaration', () => {
     expect(kotlinPackageDecl('com.example.api')).toBe('package com.example.api')
   })
 
+  it('emits a signature header line carrying the package token', () => {
+    const header = kotlinSignatureHeader()
+    expect(header).toBe(`// ${CODEGEN_SIGNATURE} — do not edit`)
+    // The marker-based prune depends on this token being present.
+    expect(header).toContain(CODEGEN_SIGNATURE)
+  })
+
   it('emits a source-hash header line', () => {
     expect(kotlinSourceHashHeader('abc123')).toBe('// Source hash: abc123')
   })

package/src/codegen/targets/kotlin/format-kotlin.ts

@@ -1,7 +1,18 @@
+import { CODEGEN_SIGNATURE } from '../../constants.js'
+
 export function kotlinPackageDecl(pkg: string): string {
   return `package ${pkg}`
 }
 
+/**
+ * Stable signature comment embedded at the top of every generated Kotlin file.
+ * Carries the version-agnostic `ts-procedures-codegen` token so the marker-based
+ * prune in `writeGeneratedFiles` can recognise generated Kotlin files as owned.
+ */
+export function kotlinSignatureHeader(): string {
+  return `// ${CODEGEN_SIGNATURE} — do not edit`
+}
+
 export function kotlinSourceHashHeader(hash: string): string {
   return `// Source hash: ${hash}`
 }

package/src/codegen/targets/swift/format-swift.ts

@@ -1,5 +1,9 @@
+import { CODEGEN_SIGNATURE } from '../../constants.js'
+
 export function swiftHeader(sourceHash: string): string {
-  return `// Generated by ts-procedures-codegen — do not edit.\n// Source hash: ${sourceHash}`
+  // The marker-based prune in `writeGeneratedFiles` relies on CODEGEN_SIGNATURE
+  // appearing in this header.
+  return `// Generated by ${CODEGEN_SIGNATURE} — do not edit.\n// Source hash: ${sourceHash}`
 }
 
 export function swiftImports(imports: string[]): string {

package/agent_config/claude-code/skills/ts-procedures-kotlin/SKILL.md

@@ -1,106 +0,0 @@
----
-name: ts-procedures-kotlin
-description: "Kotlin client codegen for ts-procedures — generate types-only Kotlin source from a ts-procedures DocEnvelope for Android/JVM consumers. Use when the user mentions Kotlin, Android, mobile clients, kotlinx-serialization, or asks how to generate non-TypeScript types from a ts-procedures server."
-user-invocable: false
----
-
-# ts-procedures — Kotlin Client Codegen
-
-You are assisting a developer who needs to generate Kotlin types from a `ts-procedures` server's `DocEnvelope`. The Kotlin target is **types-only** — no runtime, no adapter, no error registry. Mobile/Android consumers own the HTTP layer.
-
-## When this skill applies
-
-- The user mentions Kotlin, Android, kotlinx-serialization, mobile client, or `--target kotlin`.
-- The user wants to share API types between a `ts-procedures` server and a Kotlin/JVM consumer.
-- The user is debugging Kotlin codegen output, Gradle setup, or contextual serializer registration.
-
-If the user is generating a **TypeScript** client, redirect them to the main `ts-procedures` skill. For **Swift / iOS / macOS / Apple-platform** consumers, redirect to `ts-procedures-swift`.
-
-## Quickstart
-
-```bash
-npx ts-procedures-codegen \
-  --target kotlin \
-  --kotlin-package com.example.api \
-  --url https://api.example.com/_ts-procedures.json \
-  --out ./src/main/kotlin/com/example/api
-```
-
-One `.kt` file per scope. Types accessed as `Users.GetUser.Response`, `Users.GetUser.Body.Address` (nested classes via `inlineTypes: true`), `Users.GetUser.Errors.NotFound`.
-
-## CLI flags (Kotlin-specific)
-
-| Flag | Default | Purpose |
-|---|---|---|
-| `--target kotlin` | `ts` | Switch to the Kotlin codegen path |
-| `--kotlin-package <com.example.api>` | required | Sets the `package` declaration on every emitted `.kt` file |
-| `--kotlin-serializer <kotlinx\|none>` | `kotlinx` | `kotlinx` emits `@Serializable`; `none` emits plain data classes for Moshi/Gson/hand-written serialization |
-| `--unsupported-unions <throw\|fallback>` | `throw` | **Currently a no-op for Kotlin** — ajsc v7.2 silently emits an empty `data class` for untagged `oneOf` regardless. CLI warns when set |
-
-`--array-item-naming`, `--depluralize`, `--uncountable-words` also apply to the Kotlin target.
-
-## Output shape (what consumers see)
-
-```kotlin
-package com.example.api
-
-import kotlinx.serialization.Serializable
-import kotlinx.serialization.SerialName
-import kotlinx.serialization.Contextual
-import kotlinx.serialization.json.JsonClassDiscriminator
-
-object Users {
-    object GetUser {
-        const val method = "GET"
-        const val pathTemplate = "/users/{id}"
-        fun path(p: PathParams): String = "/users/${p.id}"
-
-        @Serializable data class PathParams(val id: String)
-
-        @Serializable
-        data class Response(
-            val id: String,
-            @SerialName("created-at") @Contextual val createdAt: java.time.Instant,
-            val address: Address,
-        ) {
-            @Serializable data class Address(val street: String, val city: String)
-        }
-
-        object Errors {
-            @Serializable
-            data class NotFound(val name: String = "NotFound", val message: String)
-        }
-    }
-}
-```
-
-For routes without path params, `path` is a `const val`, not a function.
-
-## Consumer-side setup the dev MUST do
-
-The generated code requires these on the Android/JVM side. **Don't let the user assume the codegen handles them.**
-
-1. **Gradle:** `kotlin("plugin.serialization")` plugin + `org.jetbrains.kotlinx:kotlinx-serialization-json` dependency. (`kotlinx-serialization-core` is a transitive dep; no need to declare it explicitly.)
-
-2. **Contextual serializers:** `format: date-time`/`uuid`/`uri`/`date`/`time` map to JVM stdlib types annotated with `@Contextual`. The consumer's `Json` configuration MUST register `contextual(java.time.Instant::class, ...)` etc., otherwise decoding fails. We don't ship the serializers — choice between ISO-8601 and epoch ms is application-specific.
-
-3. **Discriminated unions:** `@JsonClassDiscriminator` is read automatically by `kotlinx-serialization-json` — no extra config needed.
-
-4. **No runtime dispatch:** error types are emitted as nested data classes (`Users.GetUser.Errors.NotFound`), but there's no `instanceof`-style registry, no `dispatchTypedError`. Consumers catch HTTP failures themselves and inspect `body.name` (a regular `String` field, not a type-system discriminator) to decide which error data class to deserialize against. This is by design; don't suggest implementing it.
-
-The full setup guide lives at `docs/codegen-kotlin.md` in the `ts-procedures` repo.
-
-## Documented limitations to flag during reviews
-
-- **Untagged `oneOf` produces an empty `data class`.** Won't round-trip. Add a server-side discriminator, hand-write a `KSerializer`, or pre-process the envelope.
-- **Tuples > 3 elements throw** at codegen time. Refactor to a struct schema upstream.
-- **`additionalProperties: { type: T }` is silently dropped** with a KDoc note. Add a sibling `Map<String, T>` field by hand if your contract uses extra keys.
-- **Schema-level `examples` are not modeled.** They're documentation-only on the server side; consumers don't see them.
-
-## Anti-patterns
-
-- Suggesting the Kotlin target ships an HTTP adapter or error registry.
-- Recommending `--kotlin-serializer none` without noting the consumer is responsible for adapter setup.
-- Treating `--unsupported-unions fallback` as functional for Kotlin — it's a no-op (the CLI itself warns when set).
-- Saying KMP (Kotlin Multiplatform) is supported — JVM only for now.
-- Mixing `--target kotlin` flags into a TypeScript-target invocation; some flags are silently ignored, others (like `--kotlin-package`) are required only for kotlin.

package/agent_config/claude-code/skills/ts-procedures-review/SKILL.md

@@ -1,48 +0,0 @@
----
-name: ts-procedures-review
-description: "Review ts-procedures code for pattern adherence, schema correctness, error handling, and signal propagation."
-argument-hint: "<path>"
-allowed-tools: Read Grep Glob
-context: fork
-effort: high
----
-
-# Review ts-procedures Code
-
-Parse `$ARGUMENTS` as a file or directory path. If a directory, review all `.ts` and `.tsx` files within it.
-
-## Instructions
-
-1. Read the target file(s).
-2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/hono`, `ts-procedures/http`, `ts-procedures/http-docs`, `ts-procedures/http-errors`, `ts-procedures/client`, `ts-procedures/codegen`) to determine file types.
-3. Check each file against the categorized checklist in [checklist.md](checklist.md).
-4. For detailed code examples of each violation pattern, reference [anti-patterns.md](../ts-procedures/anti-patterns.md) — it shows 20 common mistakes with before/after code fixes and severity ratings.
-5. Output findings grouped by severity.
-
-## Output Format
-
-For each finding:
-
-```
-[SEVERITY] file:line — Violation
-  Problem: What's wrong
-  Fix: Concrete before/after code
-```
-
-Severity levels:
-- **CRITICAL** — Will cause bugs, silent failures, resource leaks, or runtime errors. Must fix.
-- **WARNING** — Anti-pattern that hurts maintainability or correctness. Should fix.
-- **SUGGESTION** — Improvement for readability, type safety, or DX. Nice to have.
-
-## Summary
-
-After individual findings, provide:
-- Total findings by severity
-- Overall assessment (healthy / needs attention / significant issues)
-- Top 3 priorities to address
-- If structural issues found, suggest `/ts-procedures:scaffold <type> <Name>` to generate correct implementations
-
-## Reference
-
-See [checklist.md](checklist.md) for the complete categorized checklist by file type.
-See [anti-patterns.md](../ts-procedures/anti-patterns.md) for detailed code examples of each violation.

package/agent_config/claude-code/skills/ts-procedures-scaffold/SKILL.md

@@ -1,50 +0,0 @@
----
-name: ts-procedures-scaffold
-description: "Generate ts-procedures implementations with correct patterns — procedures, streams, Hono apps (RPC, streams, REST in one builder), and client setup."
-argument-hint: "<type> <Name>"
-allowed-tools: Read Write
----
-
-# Scaffold ts-procedures Code
-
-Scaffold a `$0` ts-procedures implementation named `$1`.
-
-If either argument is missing, ask the user for `<type>` and `<Name>`.
-
-## Instructions
-
-1. Validate `$0` is a recognized type (see table below). Case-insensitive.
-2. Validate `$1` is PascalCase (e.g., `UserProfile`).
-3. Derive placeholder variants from the provided PascalCase Name:
-   - `{{Name}}` — PascalCase as given (e.g., `UserProfile`)
-   - `{{name}}` — camelCase (e.g., `userProfile`)
-   - `{{kebab}}` — kebab-case (e.g., `user-profile`)
-4. Read the template file from `templates/$0.md` (relative to this skill directory).
-5. Replace all `{{Name}}`, `{{name}}`, and `{{kebab}}` placeholders with the appropriate variants.
-6. Generate the implementation file(s) following the template exactly.
-7. Also generate a colocated test file following ts-procedures test conventions.
-
-## Valid Types
-
-| Type | Template | Files Generated |
-|------|----------|----------------|
-| `procedure` | `templates/procedure.md` | `{{Name}}.procedure.ts`, `{{Name}}.procedure.test.ts` |
-| `stream-procedure` | `templates/stream-procedure.md` | `{{Name}}.stream.ts`, `{{Name}}.stream.test.ts` |
-| `hono` | `templates/hono.md` | `{{Name}}.hono.ts`, `{{Name}}.hono.test.ts` |
-| `client` | `templates/client.md` | `{{Name}}.client.ts`, `{{Name}}.client.test.ts` |
-| `astro-catchall` | `templates/astro-catchall.md` | `src/pages/api/[...rest].ts` |
-
-## Rules
-
-- Use `ctx.error()` for ad-hoc business errors; for structured errors with status codes and typed client dispatch, throw custom error classes and register them via `defineErrorTaxonomy` in the builder's `errors` config (see the HTTP builder templates).
-- Never throw raw `Error` — either use `ctx.error()` or a typed class registered in the taxonomy.
-- `schema.params` is validated at runtime; `schema.returnType` is documentation only.
-- Pass `ctx.signal` to all downstream async calls.
-- Stream handlers always have `ctx.signal` (guaranteed `AbortSignal`).
-- Use TypeBox for schema definitions (`import { Type } from 'typebox'`).
-- AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
-- Test files use `describe`/`test` from vitest.
-
-## Workflow
-
-Use the **ts-procedures-architect** agent to plan your API structure first, then scaffold each procedure. After scaffolding, use `/ts-procedures:review <path>` to validate the implementation.