cli: implement jscodeshift transforms for add command

Adds per-repo-type codemods (mcp-server, langchain-tool, rest-api) that
insert `settlegrid.init()` and wrap handlers with `sg.wrap()`. Transforms
are idempotent, respect dry-run, and mutate target package.json to add
@settlegrid/mcp. Includes fixture-based tests covering 6 before/after
pairs and idempotency assertions.

New module: packages/settlegrid-cli/src/transforms/
  - shared.ts — jscodeshift helpers: ensureSettlegridImport,
    buildSettlegridInitStatement, buildSgWrapCall, isAlreadySgWrap,
    extractMcpMethodName (kebab-cased name from schema identifier),
    findEnclosingStatement.
  - add-mcp.ts — finds `new Server(...)` + `server.setRequestHandler(
    schema, handler)` and wraps the handler arg in `sg.wrap(handler,
    { method: '<schema-derived>' })`. Adds import + `const sg =
    settlegrid.init({ toolSlug, pricing: { defaultCostCents: 1 } })`
    before the first Server construction.
  - add-langchain.ts — finds classes extending StructuredTool /
    DynamicStructuredTool / Tool and wraps each `_call` / `invoke`
    method body with `return await sg.wrap(async () => { <original
    body> }, { method: this.name })()`. Init is inserted before the
    first tool class.
  - add-rest.ts — wraps every `app.<verb>(path, ..., handler)` call
    for express/hono/fastify/koa, using `<verb>:<path>` as the method
    key. Init is inserted before the first route.
  - runner.ts — TransformInput/TransformOutput interface from spec,
    dispatches by detect.type, enumerates source files via fast-glob
    (500-file cap, deep:5, no-symlinks), respects dryRun, mutates
    package.json deterministically (alphabetical key sort, preserves
    original indent + trailing newline).
  - __testfixtures__/ — 6 before/after pairs: mcp-basic, mcp-multi-
    handler, mcp-already-wrapped (after === before, idempotent),
    langchain-tool, rest-express, rest-hono.
  - transforms.test.ts — 13 tests: per-fixture before→after equality
    + per-fixture idempotency + explicit already-wrapped no-op.
  - runner.test.ts — 12 tests: 3 isAlreadyWrapped, 4 addPackageDependency
    (sort, no-op, 4-space indent preservation, malformed safety),
    5 runTransform contracts (mcp dispatch, unknown no-op, already-
    wrapped skip, dry-run mtime unchanged, write-mode updates both
    source and pkg.json).

Spec divergences (cited per step 1 "confirm the exact signatures")
  @settlegrid/mcp API differs from the prompt's pseudocode:
    - settlegrid.init() requires { toolSlug, pricing: { defaultCostCents } },
      not { apiKey } (see packages/mcp/src/index.ts:289).
    - sg.wrap(handler, { method }), not sg.wrap('method', handler)
      (packages/mcp/src/index.ts:322).
  Generated code emits the real-API shape; the spec-as-written code
  would not compile against @settlegrid/mcp@0.1.1.

Updated: src/commands/add.ts
  Calls runTransform after detection, prints a transform summary
  (changed files, skipped files with reasons, dep to add, env required),
  emits truncated per-file preview for dry-run, and exits with:
    • dry-run + changes → "dry-run complete — re-run without --dry-run"
    • apply + 0 changes → "no files changed (already wrapped or nothing
      matched the codemod)"
    • apply + N changes → "wrapped N file(s). Next: npm install, set
      SETTLEGRID_API_KEY, and push"
  The `--force` flag remains the unknown-type override.

Updated: src/index.test.ts
  Smoke-test expectations updated for the new transform output —
  assert on "transform summary", "@settlegrid/mcp@^0.1.1",
  "SETTLEGRID_API_KEY", "dry-run complete", and "no files changed"
  (the new outros) instead of the P2.2 "not yet implemented" sentinel.

Updated: tsconfig.json
  Added src/transforms/__testfixtures__ to exclude — fixtures import
  uninstalled packages (@modelcontextprotocol/sdk, @langchain/core,
  express, hono) for realistic before-state content, and tsc would
  flag them otherwise.

Verification
  - npm --workspace @settlegrid/cli run {typecheck,build,test}: green
  - 6 test files / 61 tests / 0 failures (up from 36 at end of P2.2 arc)
  - Manual DoD #3 smoke: `node dist/index.js add --path fixtures/
    mcp-sample --dry-run` prints detection + transform summary +
    preview, exit 0 ✓
  - DoD mtime check: runner.test.ts proves dryRun:true never touches
    server.ts or package.json on disk
  - apps/web tsc: 0 errors (baseline intact)
  - `npx turbo test --concurrency=1`: 5/5 tasks successful

Pre-existing turbo-parallel flake on apps/web (documented in
docs/audit-failures/P2.2-apps-web-concurrent-flake-2026-04-15.md)
is unchanged by this commit — cli's fileParallelism:false mitigation
from P2.2 continues to partially suppress it.

Refs: P2.3
Audits: spec-diff PASS, hostile PASS, tests PASS

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lexwhiting

packages/settlegrid-cli/src/commands/add.ts

@@ -7,6 +7,7 @@ import {
   type ResolvedSource,
 } from '../lib/source-resolver.js'
 import { detectRepoType } from '../detect/index.js'
+import { runTransform } from '../transforms/runner.js'
 
 interface AddOptions {
   github?: string
@@ -36,10 +37,6 @@ export function addCommand(program: Command): void {
     .action(async (source: string | undefined, options: AddOptions) => {
       intro(kleur.cyan('settlegrid add'))
 
-      // The positional [source] argument is a convenience: if it looks
-      // like a remote URL, route it into resolveSource's `github` opt;
-      // otherwise treat it as a local path. Explicit --github / --path
-      // flags always win over the positional.
       const githubFromSource =
         source && isGithubUrl(source) ? source : undefined
       const pathFromSource =
@@ -62,7 +59,7 @@ export function addCommand(program: Command): void {
             ? detection.reasons.map((r) => `\n                 - ${r}`).join('')
             : ` ${kleur.dim('(none)')}`
 
-        const lines = [
+        const detectionLines = [
           `source:       ${source ?? kleur.dim('(none)')}`,
           `resolved dir: ${resolved.dir}`,
           `type:         ${detection.type}`,
@@ -78,7 +75,7 @@ export function addCommand(program: Command): void {
           `--out-branch: ${options.outBranch ?? kleur.dim('(unset)')}`,
           `--force:      ${options.force ? 'yes' : 'no'}`,
         ]
-        note(lines.join('\n'), 'detection + parsed options')
+        note(detectionLines.join('\n'), 'detection + parsed options')
 
         if (detection.type === 'unknown' && !options.force) {
           outro(
@@ -90,11 +87,78 @@ export function addCommand(program: Command): void {
           return
         }
 
-        outro(
-          kleur.yellow(
-            'not yet implemented — codemod and PR creation land in P2.3 through P2.4.',
-          ),
-        )
+        const transform = await runTransform({
+          rootDir: resolved.dir,
+          detect: detection,
+          dryRun: options.dryRun === true,
+        })
+
+        const addedDeps = Object.entries(transform.addedDependencies)
+          .map(([n, r]) => `${n}@${r}`)
+          .join(', ')
+        const changedList =
+          transform.changedFiles.length > 0
+            ? transform.changedFiles
+                .map((c) => `\n                 - ${c.path}`)
+                .join('')
+            : ` ${kleur.dim('(none)')}`
+        const skippedList =
+          transform.skipped.length > 0
+            ? transform.skipped
+                .map((s) => `\n                 - ${s.path} (${s.reason})`)
+                .join('')
+            : ` ${kleur.dim('(none)')}`
+        const envList =
+          transform.envVarsRequired.length > 0
+            ? transform.envVarsRequired.join(', ')
+            : kleur.dim('(none)')
+
+        const transformLines = [
+          `mode:          ${options.dryRun ? kleur.yellow('dry-run (no files written)') : kleur.green('apply (files written)')}`,
+          `changed files: ${changedList}`,
+          `skipped files: ${skippedList}`,
+          `deps to add:   ${addedDeps || kleur.dim('(none)')}`,
+          `env required:  ${envList}`,
+        ]
+        note(transformLines.join('\n'), 'transform summary')
+
+        // Emit an inline diff preview for dry-run so the user can eyeball
+        // what would change without touching their working tree. Truncate
+        // so the terminal doesn't get flooded on larger repos.
+        if (options.dryRun === true && transform.changedFiles.length > 0) {
+          const previewCount = Math.min(transform.changedFiles.length, 3)
+          for (let i = 0; i < previewCount; i++) {
+            const { path: rel, after } = transform.changedFiles[i]
+            const truncated = after.length > 1200 ? after.slice(0, 1200) + '\n…' : after
+            note(truncated, `preview: ${rel}`)
+          }
+          if (transform.changedFiles.length > previewCount) {
+            note(
+              `${transform.changedFiles.length - previewCount} more file(s) would change — re-run without --dry-run to apply.`,
+              'preview (truncated)',
+            )
+          }
+        }
+
+        if (options.dryRun === true) {
+          outro(
+            kleur.yellow(
+              'dry-run complete — re-run without --dry-run to write changes and update package.json.',
+            ),
+          )
+        } else if (transform.changedFiles.length === 0) {
+          outro(
+            kleur.dim(
+              'no files changed (already wrapped or nothing matched the codemod).',
+            ),
+          )
+        } else {
+          outro(
+            kleur.green(
+              `wrapped ${transform.changedFiles.length} file(s). Next: run \`npm install\` in the target repo, set ${transform.envVarsRequired.join(', ')}, and push.`,
+            ),
+          )
+        }
         process.exitCode = 0
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)

packages/settlegrid-cli/src/index.test.ts

@@ -82,6 +82,7 @@ describe('settlegrid add — detection + source resolution smoke tests', () => {
   //   • P2.1-style option echoing: every parsed flag is displayed in the
   //     @clack/prompts note block.
   //   • --force on a non-unknown type is inert (exit 0 regardless).
+  //   • P2.3: dry-run runs the codemod and emits a transform summary.
   // Consolidated into one spawn to reduce subprocess load when multiple
   // workspace tests run in parallel under turbo.
   it('detects mcp-server on --path fixture, echoes all flags, exits 0', () => {
@@ -115,7 +116,11 @@ describe('settlegrid add — detection + source resolution smoke tests', () => {
     expect(result.stdout).toContain('no-pr:      yes (PR skipped)')
     expect(result.stdout).toContain('settlegrid/monetize')
     expect(result.stdout).toContain('--force:      yes')
-    expect(result.stdout).toContain('not yet implemented')
+    // P2.3: transform summary + dry-run outro.
+    expect(result.stdout).toContain('transform summary')
+    expect(result.stdout).toContain('@settlegrid/mcp@^0.1.1')
+    expect(result.stdout).toContain('SETTLEGRID_API_KEY')
+    expect(result.stdout).toContain('dry-run complete')
   })
 
   // Per P2.2 step 6: unknown-type classification exits 1 without --force,
@@ -140,7 +145,9 @@ describe('settlegrid add — detection + source resolution smoke tests', () => {
     )
     expect(withForce.status).toBe(0)
     expect(withForce.stdout).toContain('type:         unknown')
-    expect(withForce.stdout).toContain('not yet implemented')
+    // --force with unknown type → runner dispatches no codemod → 0 changes.
+    // Outro message acknowledges nothing matched.
+    expect(withForce.stdout).toContain('no files changed')
   })
 
   // Error path: no source / --path / --github supplied. resolveSource

packages/settlegrid-cli/src/transforms/__testfixtures__/langchain-tool.after.ts

@@ -0,0 +1,28 @@
+import { StructuredTool } from '@langchain/core/tools'
+import { z } from 'zod'
+
+import { settlegrid } from '@settlegrid/mcp';
+
+const sg = settlegrid.init({
+  toolSlug: 'langchain-tool',
+
+  pricing: {
+    defaultCostCents: 1
+  }
+});
+
+class SearchTool extends StructuredTool {
+  name = 'search'
+  description = 'Search the web.'
+  schema = z.object({ query: z.string() })
+
+  async _call(input: { query: string }): Promise<string> {
+    return await sg.wrap(async () => {
+      return `result for ${input.query}`
+    }, {
+      method: this.name
+    })();
+  }
+}
+
+export { SearchTool }

packages/settlegrid-cli/src/transforms/__testfixtures__/langchain-tool.before.ts

@@ -0,0 +1,14 @@
+import { StructuredTool } from '@langchain/core/tools'
+import { z } from 'zod'
+
+class SearchTool extends StructuredTool {
+  name = 'search'
+  description = 'Search the web.'
+  schema = z.object({ query: z.string() })
+
+  async _call(input: { query: string }): Promise<string> {
+    return `result for ${input.query}`
+  }
+}
+
+export { SearchTool }

packages/settlegrid-cli/src/transforms/__testfixtures__/mcp-already-wrapped.after.ts

@@ -0,0 +1,20 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { settlegrid } from '@settlegrid/mcp'
+
+const sg = settlegrid.init({
+  toolSlug: 'mcp-already',
+  pricing: { defaultCostCents: 1 },
+})
+
+const server = new Server(
+  { name: 'mcp-already', version: '0.0.0' },
+  { capabilities: { tools: {} } },
+)
+
+server.setRequestHandler(
+  ListToolsRequestSchema,
+  sg.wrap(async () => ({ tools: [] }), { method: 'list-tools' }),
+)
+
+export { server }

packages/settlegrid-cli/src/transforms/__testfixtures__/mcp-already-wrapped.before.ts

@@ -0,0 +1,20 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { settlegrid } from '@settlegrid/mcp'
+
+const sg = settlegrid.init({
+  toolSlug: 'mcp-already',
+  pricing: { defaultCostCents: 1 },
+})
+
+const server = new Server(
+  { name: 'mcp-already', version: '0.0.0' },
+  { capabilities: { tools: {} } },
+)
+
+server.setRequestHandler(
+  ListToolsRequestSchema,
+  sg.wrap(async () => ({ tools: [] }), { method: 'list-tools' }),
+)
+
+export { server }

packages/settlegrid-cli/src/transforms/__testfixtures__/mcp-basic.after.ts

@@ -0,0 +1,34 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+import { settlegrid } from '@settlegrid/mcp';
+
+const sg = settlegrid.init({
+  toolSlug: 'mcp-basic',
+
+  pricing: {
+    defaultCostCents: 1
+  }
+});
+
+const server = new Server(
+  { name: 'mcp-basic', version: '0.0.0' },
+  { capabilities: { tools: {} } },
+)
+
+server.setRequestHandler(ListToolsRequestSchema, sg.wrap(async () => {
+  return { tools: [] }
+}, {
+  method: 'list-tools'
+}))
+
+server.setRequestHandler(CallToolRequestSchema, sg.wrap(async (req) => {
+  return { content: [{ type: 'text', text: 'ok' }] }
+}, {
+  method: 'call-tool'
+}))
+
+export { server }

packages/settlegrid-cli/src/transforms/__testfixtures__/mcp-basic.before.ts

@@ -0,0 +1,20 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+const server = new Server(
+  { name: 'mcp-basic', version: '0.0.0' },
+  { capabilities: { tools: {} } },
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: [] }
+})
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  return { content: [{ type: 'text', text: 'ok' }] }
+})
+
+export { server }

packages/settlegrid-cli/src/transforms/__testfixtures__/mcp-multi-handler.after.ts

@@ -0,0 +1,39 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+import { settlegrid } from '@settlegrid/mcp';
+
+const sg = settlegrid.init({
+  toolSlug: 'mcp-multi-handler',
+
+  pricing: {
+    defaultCostCents: 1
+  }
+});
+
+const server = new Server(
+  { name: 'mcp-multi', version: '0.0.0' },
+  { capabilities: { tools: {}, resources: {} } },
+)
+
+server.setRequestHandler(ListToolsRequestSchema, sg.wrap(async () => ({ tools: [] }), {
+  method: 'list-tools'
+}))
+server.setRequestHandler(CallToolRequestSchema, sg.wrap(async (req) => {
+  return { content: [{ type: 'text', text: 'call' }] }
+}, {
+  method: 'call-tool'
+}))
+server.setRequestHandler(ListResourcesRequestSchema, sg.wrap(async () => ({ resources: [] }), {
+  method: 'list-resources'
+}))
+server.setRequestHandler(ReadResourceRequestSchema, sg.wrap(async (req) => ({ contents: [] }), {
+  method: 'read-resource'
+}))
+
+export { server }

packages/settlegrid-cli/src/transforms/__testfixtures__/mcp-multi-handler.before.ts

@@ -0,0 +1,21 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+const server = new Server(
+  { name: 'mcp-multi', version: '0.0.0' },
+  { capabilities: { tools: {}, resources: {} } },
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [] }))
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  return { content: [{ type: 'text', text: 'call' }] }
+})
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [] }))
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => ({ contents: [] }))
+
+export { server }