baobox 0.1.0 → 0.1.1-rc.1

package/README.md

@@ -1,6 +1,32 @@
 # Baobox
 
-Baobox is a Bun-first, TypeScript-first schema library that targets TypeBox parity while leaving room for Bun-native improvements.
+[![CI](https://github.com/d4551/baobox/actions/workflows/publish.yml/badge.svg)](https://github.com/d4551/baobox/actions/workflows/publish.yml)
+[![License](https://img.shields.io/github/license/d4551/baobox)](https://github.com/d4551/baobox)
+[![Bun](https://img.shields.io/badge/bun-%3E%3D1.3.11-black?logo=bun)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/typescript-%3E%3D6.0.0-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+Baobox is a Bun-first, TypeScript-first schema library that keeps the familiar TypeBox-style authoring surface while adding result-first runtime APIs, scoped runtime contexts, compile caching, portable validator artifacts, and schema-interop helpers.
+
+## ELI5
+
+- You describe what valid data looks like once.
+- Baobox can then answer different questions with the same schema:
+  - Is this value valid: `Check`
+  - Can you clean and coerce it safely: `TryParse`
+  - What exactly failed: `Explain` or `Errors`
+  - Can I reuse this on a hot path: `CompileCached`
+  - Can another tool consume the same schema: `StandardSchemaV1`
+- If you do not want exception-driven control flow, use the `Try*` family.
+
+## Why Baobox
+
+- TypeBox-compatible root surface with baobox-only additions at the root entrypoint.
+- Result-first runtime helpers: `TryParse`, `TryDecode`, `TryEncode`, `TryCreate`, and `TryRepair`.
+- Scoped runtime contexts so locale catalogs, registries, settings, and compile caches do not have to be process-global.
+- Compiled validators with cache reuse and portable `Validator.Artifact()` output.
+- Standard Schema V1 adapters for typed baobox schemas and raw JSON-schema-style objects.
+- Built-in codecs for common interop-heavy values: `Uint8Array`, `Date`, `URL`, and `bigint`.
+- Localized validation errors with official bundles for every declared locale code through `baobox/locale`.
 
 ## Install
 
@@ -29,15 +55,17 @@ const User = Type.Object({
   id: Type.String(),
   email: Type.String({ format: 'email' }),
   age: Type.Number({ minimum: 0 }),
-}, { required: ['id', 'email', 'age'] })
+})
 
 Check(User, { id: 'usr_1', email: 'ada@example.com', age: 37 })
+// true
 
 TryParse(Type.Object({ count: Type.Number() }), { count: '5' })
 // { success: true, value: { count: 5 } }
 
 const validator = CompileCached(User)
 validator.Check({ id: 'usr_1', email: 'ada@example.com', age: 37 })
+// true
 
 TryDecode(DateCodec(), '2024-01-01T00:00:00.000Z')
 // { success: true, value: new Date('2024-01-01T00:00:00.000Z') }
@@ -47,68 +75,103 @@ StandardUser['~standard'].validate({ id: 'usr_1', email: 'ada@example.com', age:
 // { value: { id: 'usr_1', email: 'ada@example.com', age: 37 } }
 ```
 
-## Choose A Workflow
-
-- `Check(schema, value)` returns a boolean. Use it when you only need pass/fail validation.
-- `TryParse(schema, value)` runs the full normalization pipeline and returns `{ success, value | errors }`. Use it when the caller needs a non-throwing normalization path.
-- `TryDecode`, `TryEncode`, `TryCreate`, and `TryRepair` extend the same result-first contract to codecs, default generation, and repair flows.
-- `Parse(schema, value)` runs the full value pipeline: clone, default, convert, clean, then validate. It throws `ParseError` when validation still fails.
-- `Explain(schema, value)` returns raw issue metadata plus the localized message and active locale.
-- `Compile(schema)` creates a reusable validator for hot paths, now with per-context compile caching and portable `Validator.Artifact()` output. `Validator.Errors()` uses the same localized error messages as `Value.Errors()`.
+## API Map
 
-## Standard Schema Adapter
+| Problem | API | Result |
+| --- | --- | --- |
+| Fast pass/fail validation | `Check(schema, value)` | `boolean` |
+| Normalize without exceptions | `TryParse(schema, value)` | `ParseResult<T>` |
+| Throwing parity path | `Parse(schema, value)` | normalized value or `ParseError` |
+| Codec decode without exceptions | `TryDecode(schema, value)` | `ParseResult<T>` |
+| Codec encode without exceptions | `TryEncode(schema, value)` | `ParseResult<T>` |
+| Default generation without exceptions | `TryCreate(schema)` | `ParseResult<T>` |
+| Repair without exceptions | `TryRepair(schema, value)` | `ParseResult<T>` |
+| Raw issue metadata plus localized messages | `Explain(schema, value)` | diagnostics array |
+| Reusable hot-path validator | `Compile(schema)` or `CompileCached(schema)` | `Validator` |
+| Reload a prebuilt validator body | `CompileFromArtifact(schema, artifact)` | `Validator` |
+| TypeBox-compatible error iterator | `ErrorsIterator(schema, value)` | `IterableIterator<ValueError>` |
+| Adapt to Standard Schema V1 | `StandardSchemaV1(schema)` | standard-compatible wrapper |
 
-```ts
-import { StandardSchemaV1, Type } from 'baobox'
+## Result-First Runtime
 
-const User = StandardSchemaV1(Type.Object({
-  name: Type.String(),
-  age: Type.Number(),
-}, { required: ['name', 'age'] }))
+Baobox keeps `Parse(schema, value)` as the upstream-style throwing path, but the default baobox direction is result-first:
 
-User['~standard'].validate({ name: 'Ada', age: '37' })
-// { value: { name: 'Ada', age: 37 } }
-```
+- `TryParse` runs `Clone -> Default -> Convert -> Clean -> Check`
+- `TryDecode` and `TryEncode` apply codec transforms without exception control flow
+- `TryCreate` and `TryRepair` make default-generation and corrective flows explicit
+- `Explain` preserves issue codes, params, locale, and final message
 
-Baobox also ships the dedicated `baobox/standard` subpath for schema-agnostic integrations.
+If you are writing request handling, config loading, env parsing, or service boundaries, the `Try*` APIs are usually the better fit.
 
-`ToStandardSchema()` is the generic alias when you already have either a baobox schema or a raw JSON schema object. `FromJsonSchema()` is the explicit raw-schema entry point.
+## Compiled Validators
 
-## Localized Validation Errors
+`Compile()` builds a reusable validator object. `CompileCached()` adds per-runtime-context cache reuse. `CompileFromArtifact()` reloads previously emitted validator code.
 
 ```ts
-import { Errors, String } from 'baobox'
-import { System } from 'baobox/system'
+import { CompileCached, CompileFromArtifact, Number, Object } from 'baobox'
 
-System.Locale.Set(System.Locale.ko_KR)
+const schema = Object({
+  count: Number({ minimum: 1 }),
+})
 
-Errors(String(), 42)
-// [{ path: '/', code: 'INVALID_TYPE', message: 'string이어야 합니다. 현재 값 유형: number' }]
+const validator = CompileCached(schema)
+const artifact = validator.Artifact()
+const loaded = CompileFromArtifact(schema, artifact)
+
+loaded.TryParse({ count: '2' })
+// { success: true, value: { count: 2 } }
 ```
 
-`en_US` is the default locale. Baobox now ships an official bundle for every declared locale code through `baobox/locale`, so declared locales no longer fall back through the registry lookup path. The translated catalog families currently include `de_DE`, `en_US`, the Spanish family (`es_419`, `es_AR`, `es_ES`, `es_MX`), the French family (`fr_CA`, `fr_FR`), `ja_JP`, `ko_KR`, the Portuguese family (`pt_BR`, `pt_PT`), and both Chinese packs (`zh_Hans`, `zh_Hant`). The remaining official bundles currently alias the English catalog until native translations are added.
+Technical details:
 
-You can also register scoped or process-default catalogs directly:
+- compile caching is scoped to the active runtime context
+- artifacts let you ship emitted validator code instead of regenerating it at startup
+- Bun-specific byte-oriented fast paths are used only when the schema shape makes that safe
+
+## Standard Schema Interop
+
+Baobox can expose the same validation logic through the Standard Schema V1 contract.
 
 ```ts
-import { CreateRuntimeContext, LocaleCodes, String, Errors } from 'baobox'
+import { FromJsonSchema, StandardSchemaV1, Type, ToStandardSchema } from 'baobox'
 
-const context = CreateRuntimeContext()
-context.Locale.Register('en_TEST', {
-  ...context.Locale.GetCatalog(LocaleCodes.en_US),
-  INVALID_TYPE: () => 'yarrr-invalid-type',
+const typed = StandardSchemaV1(Type.Object({
+  name: Type.String(),
+  age: Type.Number(),
+}))
+
+const raw = FromJsonSchema({
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    age: { type: 'number' },
+  },
+  required: ['name', 'age'],
 })
-context.Locale.Set('en_TEST')
 
-Errors(String(), 42, context)
-// [{ path: '/', code: 'INVALID_TYPE', message: 'yarrr-invalid-type' }]
+ToStandardSchema(raw)['~standard'].validate({ name: 'Ada', age: 37 })
 ```
 
-If you want to seed a scoped runtime with one of the official bundles explicitly, import it from `baobox/locale`:
+Use:
+
+- `StandardSchemaV1()` when you want the canonical baobox adapter
+- `ToStandardSchema()` when the input may already be typed or raw
+- `FromJsonSchema()` when the source is explicitly a raw JSON-schema-style object
+
+For schema-agnostic integrations, you can also import from `baobox/standard`.
+
+## Locales And Runtime Contexts
+
+The default runtime context is preloaded with an official bundle for every declared locale code. Native translated catalogs currently ship for `de_DE`, `en_US`, the Spanish family, the French family, `ja_JP`, `ko_KR`, the Portuguese family, and both Chinese packs. Remaining official bundles currently alias the English catalog until native translations are added.
 
 ```ts
 import LocalePacks from 'baobox/locale'
 import { CreateRuntimeContext, Errors, LocaleCodes, String } from 'baobox'
+import { System } from 'baobox/system'
+
+System.Locale.Set(System.Locale.ko_KR)
+Errors(String(), 42)
+// [{ path: '/', code: 'INVALID_TYPE', message: 'string이어야 합니다. 현재 값 유형: number' }]
 
 const context = CreateRuntimeContext({ localeCatalogs: [] })
 context.Locale.Register(LocaleCodes.it_IT, LocalePacks.it_IT)
@@ -118,25 +181,87 @@ Errors(String(), 42, context)
 // [{ path: '/', code: 'INVALID_TYPE', message: 'Expected string, got number' }]
 ```
 
-## Package Contract
-
-- Bun resolves public package entrypoints through the `bun` export condition to raw `src/*.ts` files.
-- Standard ESM consumers resolve to built `dist/*.js` files plus generated declarations.
-- The published JS layout is `dist/index.js`, `dist/value/index.js`, and matching subpath directories, which now aligns with the export map exactly.
-- Supported public entrypoints are:
-  - `baobox`
-  - `baobox/type`
-  - `baobox/value`
-  - `baobox/schema`
-  - `baobox/error`
-  - `baobox/compile`
-  - `baobox/format`
-  - `baobox/guard`
-  - `baobox/system`
-  - `baobox/script`
-  - `baobox/locale`
-  - `baobox/standard`
-- Direct `src/*` imports are used by this repository's tests and local development. They are not part of the published package contract.
+Use runtime contexts when you need:
+
+- per-test or per-worker isolation
+- tenant-specific registries or locale catalogs
+- explicit compile-cache boundaries
+- non-global settings and type-policy changes
+
+## Elysia Integration
+
+Baobox ships a dedicated Elysia adapter at `baobox/elysia`. It re-exports all type builders through a `t` namespace that automatically stamps the `[Kind]` symbol property required by Elysia's TypeBox 0.x type guards, alongside the standard `'~kind'` string.
+
+```ts
+import { t } from 'baobox/elysia'
+
+const UserBody = t.Object({
+  name: t.String({ minLength: 1 }),
+  email: t.Email(),
+  role: t.Enum(['admin', 'user']),
+})
+
+// Use with Elysia routes:
+// app.post('/user', handler, { body: UserBody })
+```
+
+The adapter also re-exports `Value`, `Compile`, and `decorateSchema()` for manual decoration of custom schemas. Eden Treaty type inference works because the `t.*` wrappers preserve full generic type parameters.
+
+## TypeBox Migration
+
+The `baobox migrate` CLI rewrites TypeBox imports and API calls to their baobox equivalents.
+
+```bash
+# Preview changes without writing files
+baobox migrate --dry-run --path ./src
+
+# Apply changes
+baobox migrate --write --path ./src
+```
+
+The migration tool:
+- Rewrites `@sinclair/typebox` imports to `baobox` equivalents
+- Rewrites `@sinclair/typebox/value` to `baobox/value`, `/compiler` to `baobox/compile`, etc.
+- Transforms `TypeCompiler.Compile(schema)` to `Compile(schema)`
+- Flags patterns that need manual review (e.g., `[Kind]` symbol usage, `Value.Errors()` iterator differences)
+
+For incremental migration, the `baobox/typebox` subpath provides a TypeBox-compatible surface:
+
+```ts
+import { Value, Compile, Object, String } from 'baobox/typebox'
+```
+
+## Built-In Codecs
+
+Baobox ships codec helpers for common wire-format boundaries:
+
+- `Uint8ArrayCodec()` for base64 JSON payloads and runtime byte arrays
+- `DateCodec()` for ISO datetime strings to `Date`
+- `URLCodec()` for string to `URL`
+- `BigIntCodec()` for integer-string to `bigint`
+
+These work with the same value and compile APIs as ordinary schemas.
+
+## Public Entrypoints
+
+| Entrypoint | Purpose |
+| --- | --- |
+| `baobox` | Root builders, value helpers, compile helpers, and baobox additions |
+| `baobox/type` | Type builders and static type exports |
+| `baobox/value` | Runtime value operations such as `Check`, `Parse`, `Errors`, `Repair`, `Diff`, and `Patch` |
+| `baobox/schema` | Raw schema runtime plus baobox schema-emitter helpers |
+| `baobox/error` | Structured validation error surface |
+| `baobox/compile` | `Compile`, `Code`, and `Validator` |
+| `baobox/format` | Format registry and format helpers |
+| `baobox/guard` | Guard namespaces aligned with the TypeBox-style guard surface |
+| `baobox/system` | Runtime settings, locale, hashing, memory, and environment helpers |
+| `baobox/script` | Script DSL helpers |
+| `baobox/locale` | Official locale bundles for the declared locale registry |
+| `baobox/standard` | Standard Schema V1 adapter helpers |
+| `baobox/typebox` | TypeBox-compatible re-export surface with `Value` and `Compile` |
+| `baobox/elysia` | Elysia adapter with `[Kind]` symbol decoration and `t` namespace |
+
+Published consumers should only rely on package entrypoints. Direct `src/*` imports are internal to this repository and its tests.
 
 ## Guides
 
@@ -146,21 +271,6 @@ Errors(String(), 42, context)
 - [Package contract and supported imports](docs/package-contract.md)
 - [Parity policy and baobox-only additions](docs/parity-and-extensions.md)
 
-## Parity Policy
-
-- Root exports are maintained as an upstream-complete superset.
-- The `compile`, `error`, `format`, `guard`, `system`, and `value` subpaths are parity-tested against the installed `typebox` package.
-- `baobox/schema` intentionally combines a `typebox/schema`-style raw schema runtime with baobox's schema emitter helpers.
-
-## Bun-Native Fast Paths
-
-- `Compile()` can specialize hot validation paths for Bun when the schema shape makes that safe.
-- `CompileCached()` is the root convenience wrapper for cached validators, and `CompileFromArtifact()` reloads portable artifacts without re-emitting code.
-- `Uint8ArrayCodec()` adds a Bun-first base64 codec surface for binary payloads and supports constant-payload specialization in compiled validators.
-- `DateCodec()`, `URLCodec()`, and `BigIntCodec()` provide built-in codec surfaces for common interop-heavy values.
-- Raw `Uint8Array` constant-byte comparisons can use a Bun `bun:ffi` memcmp fast path when the platform supports it.
-- Bun documents `bun:ffi` as experimental, so baobox keeps the fast path narrow and falls back to non-FFI compiled validation whenever the schema does not require native byte comparison.
-
 ## Repository Scripts
 
 ```bash
@@ -168,25 +278,9 @@ bun run build
 bun run typecheck
 bun test
 bun run bench
-bun run publish:dry-run
-```
-
-`bun run bench` prints comparative validation and codec throughput against the installed `typebox` package so benchmark output stays tied to the current upstream implementation.
-
-## Publishing
-
-Baobox is configured to publish to npm with `bun`.
-
-```bash
-bun run publish:dry-run
-bun publish --access public
 ```
 
-- `prepublishOnly` runs `bun run verify`, so a live publish always rebuilds and reruns the test suite first.
-- GitHub Actions will attempt a publish on pushes to `main`, on published GitHub releases, and through manual workflow dispatch when `package.json` contains a version that is not already on npm.
-- The workflow configures the npm registry on the runner and then requires the repository secret `NPM_TOKEN` before attempting a live publish.
-- For a local first publish, authenticate once with `bunx npm login` before running `bun publish --access public`.
-- Local `.npmrc` files are gitignored so auth tokens do not end up in the repository.
+`bun run bench` compares validation and codec throughput against the installed `typebox` package so performance numbers stay tied to the current upstream implementation.
 
 ## License
 

package/dist/cli/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+/** baobox CLI — migration tool for TypeBox to baobox */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,wDAAwD"}

package/dist/cli/index.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env bun
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __require = import.meta.require;
+
+// src/cli/transforms/imports.ts
+var IMPORT_TRANSFORMS = [
+  { from: /['"]@sinclair\/typebox\/value['"]/, to: "'baobox/value'" },
+  { from: /['"]@sinclair\/typebox\/compiler['"]/, to: "'baobox/compile'" },
+  { from: /['"]@sinclair\/typebox\/type['"]/, to: "'baobox/type'" },
+  { from: /['"]@sinclair\/typebox\/errors['"]/, to: "'baobox/error'" },
+  { from: /['"]@sinclair\/typebox['"]/, to: "'baobox'" }
+];
+function transformImport(line) {
+  for (const rule of IMPORT_TRANSFORMS) {
+    if (rule.from.test(line)) {
+      return {
+        line: line.replace(rule.from, rule.to),
+        changed: true
+      };
+    }
+  }
+  return { line, changed: false };
+}
+
+// src/cli/transforms/api-calls.ts
+var API_TRANSFORMS = [
+  {
+    pattern: /TypeCompiler\.Compile\(/g,
+    replacement: "Compile(",
+    note: "TypeCompiler.Compile \u2192 Compile (add import from baobox/compile)"
+  },
+  {
+    pattern: /TypeCompiler\.Code\(/g,
+    replacement: "Code(",
+    note: "TypeCompiler.Code \u2192 Code (add import from baobox/compile)"
+  }
+];
+var MANUAL_REVIEW_PATTERNS = [
+  { pattern: /\[Kind\]/, message: "Uses [Kind] symbol \u2014 baobox uses '~kind' string property instead" },
+  { pattern: /\[Hint\]/, message: "Uses [Hint] symbol \u2014 baobox does not use Hint symbols" },
+  { pattern: /Value\.Errors\(/, message: "Value.Errors() returns SchemaError[] in baobox (not an iterator). Use ErrorsIterator() for TypeBox-compatible iterator format" },
+  { pattern: /FormatRegistry\.Set/, message: "Format registry is scoped to RuntimeContext in baobox \u2014 use CreateRuntimeContext() instead of global registry" },
+  { pattern: /TypeRegistry\.Set/, message: "Type registry is scoped to RuntimeContext in baobox" }
+];
+function isCodeLine(line) {
+  const trimmed = line.trimStart();
+  if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
+    return false;
+  }
+  return true;
+}
+function transformApiCalls(line) {
+  if (!isCodeLine(line)) {
+    return { line, changed: false };
+  }
+  let result = line;
+  let changed = false;
+  const notes = [];
+  for (const rule of API_TRANSFORMS) {
+    const replaced = result.replace(rule.pattern, rule.replacement);
+    if (replaced !== result) {
+      result = replaced;
+      changed = true;
+      if (rule.note)
+        notes.push(rule.note);
+    }
+  }
+  return { line: result, changed, note: notes.length > 0 ? notes.join("; ") : undefined };
+}
+function detectManualReviewItems(line, lineNumber) {
+  const items = [];
+  for (const rule of MANUAL_REVIEW_PATTERNS) {
+    if (rule.pattern.test(line)) {
+      items.push(`Line ${lineNumber}: ${rule.message}`);
+    }
+  }
+  return items;
+}
+
+// src/cli/migrate.ts
+var SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".turbo",
+  ".cache",
+  ".next",
+  ".nuxt",
+  ".output"
+]);
+function isTypeScriptFile(path) {
+  return path.endsWith(".ts") || path.endsWith(".tsx");
+}
+function hasTypeBoxImport(content) {
+  return content.includes("@sinclair/typebox");
+}
+async function scanDirectory(dir) {
+  const { readdir } = await import("fs/promises");
+  const { join } = await import("path");
+  const results = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (SKIP_DIRS.has(entry.name)) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      results.push(...await scanDirectory(fullPath));
+    } else if (isTypeScriptFile(entry.name)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+function migrateFileContent(content, filePath) {
+  const lines = content.split(`
+`);
+  const transformedLines = [];
+  const changedLineNumbers = [];
+  const notes = [];
+  const manualReviewItems = [];
+  for (let i = 0;i < lines.length; i++) {
+    const originalLine = lines[i];
+    let line = originalLine;
+    let changed = false;
+    manualReviewItems.push(...detectManualReviewItems(originalLine, i + 1));
+    const importResult = transformImport(line);
+    if (importResult.changed) {
+      line = importResult.line;
+      changed = true;
+      if (importResult.note)
+        notes.push(`Line ${i + 1}: ${importResult.note}`);
+    }
+    const apiResult = transformApiCalls(line);
+    if (apiResult.changed) {
+      line = apiResult.line;
+      changed = true;
+      if (apiResult.note)
+        notes.push(`Line ${i + 1}: ${apiResult.note}`);
+    }
+    transformedLines.push(line);
+    if (changed)
+      changedLineNumbers.push(i + 1);
+  }
+  return {
+    filePath,
+    originalLines: lines,
+    transformedLines,
+    changedLineNumbers,
+    notes,
+    manualReviewItems
+  };
+}
+async function migrate(options) {
+  const { readFile, writeFile } = await import("fs/promises");
+  const files = await scanDirectory(options.path);
+  const changes = [];
+  let totalTransforms = 0;
+  let totalManualReviewItems = 0;
+  for (const filePath of files) {
+    const content = await readFile(filePath, "utf8");
+    if (!hasTypeBoxImport(content))
+      continue;
+    const change = migrateFileContent(content, filePath);
+    if (change.changedLineNumbers.length > 0 || change.manualReviewItems.length > 0) {
+      changes.push(change);
+      totalTransforms += change.changedLineNumbers.length;
+      totalManualReviewItems += change.manualReviewItems.length;
+      if (!options.dryRun && change.changedLineNumbers.length > 0) {
+        await writeFile(filePath, change.transformedLines.join(`
+`));
+      }
+    }
+  }
+  return {
+    filesScanned: files.length,
+    filesChanged: changes.filter((c) => c.changedLineNumbers.length > 0).length,
+    changes,
+    totalTransforms,
+    totalManualReviewItems
+  };
+}
+
+// src/cli/report.ts
+function formatDiff(change) {
+  const lines = [];
+  lines.push(`  ${change.filePath}`);
+  for (const lineNum of change.changedLineNumbers) {
+    const original = change.originalLines[lineNum - 1];
+    const transformed = change.transformedLines[lineNum - 1];
+    lines.push(`    L${lineNum}:`);
+    lines.push(`    - ${original}`);
+    lines.push(`    + ${transformed}`);
+  }
+  if (change.manualReviewItems.length > 0) {
+    lines.push("    Manual review needed:");
+    for (const item of change.manualReviewItems) {
+      lines.push(`      ! ${item}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function formatMigrationReport(report, dryRun) {
+  const lines = [];
+  lines.push("");
+  lines.push(`baobox migrate${dryRun ? " (dry run)" : ""}`);
+  lines.push("=".repeat(40));
+  lines.push("");
+  lines.push(`Files scanned: ${report.filesScanned}`);
+  lines.push(`Files ${dryRun ? "would change" : "changed"}: ${report.filesChanged}`);
+  lines.push(`Total transforms: ${report.totalTransforms}`);
+  lines.push(`Manual review items: ${report.totalManualReviewItems}`);
+  lines.push("");
+  if (report.changes.length > 0) {
+    lines.push("Changes:");
+    lines.push("");
+    for (const change of report.changes) {
+      lines.push(formatDiff(change));
+      lines.push("");
+    }
+  }
+  if (report.totalManualReviewItems > 0) {
+    lines.push("Note: Items flagged for manual review need human attention.");
+    lines.push("These patterns have no direct baobox equivalent or behave differently.");
+    lines.push("");
+  }
+  return lines.join(`
+`);
+}
+
+// src/cli/index.ts
+import { resolve } from "path";
+function printUsage() {
+  const usage = `
+Usage: baobox migrate [options]
+
+Migrate TypeBox imports and API calls to baobox equivalents.
+
+Options:
+  --dry-run    Show what would change without writing files (default)
+  --write      Apply changes to files
+  --path <dir> Target directory to scan (default: current directory)
+  --help       Show this help message
+
+Examples:
+  baobox migrate                    # dry run in current directory
+  baobox migrate --path ./src       # dry run in ./src
+  baobox migrate --write            # apply changes
+  baobox migrate --dry-run --path . # explicit dry run
+`;
+  process.stdout.write(usage);
+}
+function parseArgs(args) {
+  let command = "";
+  let dryRun = true;
+  let path = process.cwd();
+  let help = false;
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "migrate") {
+      command = "migrate";
+    } else if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg === "--write") {
+      dryRun = false;
+    } else if (arg === "--path" && i + 1 < args.length) {
+      path = resolve(args[++i]);
+    } else if (arg === "--help" || arg === "-h") {
+      help = true;
+    }
+  }
+  return { command, dryRun, path, help };
+}
+async function main() {
+  const cliArgs = process.argv.slice(2);
+  const { command, dryRun, path, help } = parseArgs(cliArgs);
+  if (help || !command) {
+    printUsage();
+    process.exit(help ? 0 : 1);
+  }
+  if (command === "migrate") {
+    const report = await migrate({ dryRun, path, report: true });
+    process.stdout.write(formatMigrationReport(report, dryRun));
+    if (report.filesChanged === 0 && report.totalManualReviewItems === 0) {
+      process.stdout.write(`No TypeBox imports found.
+`);
+    }
+  }
+}
+main().catch((error) => {
+  process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+  process.exit(1);
+});
+
+//# debugId=444B65DC8107EF7D64756E2164756E21
+//# sourceMappingURL=index.js.map