shapecraft 1.0.0

package/CLAUDE.md

@@ -0,0 +1,227 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository layout
+
+pnpm workspace (`pnpm-workspace.yaml`) with three members:
+
+- `packages/core` — `@shapecraft/core`, the shape/type-validation library. This is where ~all real code lives.
+- `packages/samples` — `@shapecraft/samples`, hand-written `B.mapping`/`B.module` examples (`user`, `relational`, `blog`, `ecommerce`, `geometry`, `events`, `config`, `embeddings`) used as fixtures for the transforms.
+- `apps/cli` — `@shapecraft/cli`, a [`citty`](https://github.com/unjs/citty)-based CLI. Currently exposes a single `transform` subcommand: reads a JSON Schema file, runs `fromJSONSchema` → `toSQL` (default) or `toTypescript`, and prints (or writes with `--output`) the result.
+
+The root `package.json` has no production deps; it just fans scripts out to the workspace. `pnpm-workspace.yaml` globs both `packages/*` and `apps/*`.
+
+## Commands
+
+From the repo root:
+
+- `pnpm run check` — recursive `tsc --noEmit` across all workspace packages.
+- `pnpm run test` — recursive `vitest --passWithNoTests` across all workspace packages.
+- `pnpm run format` — recursive `prettier --experimental-ternaries ./src --write`.
+- `pnpm run cli` — runs `apps/cli/src/index.ts` via `./apps/cli/node_modules/.bin/tsx` (the path is hard-coded; don't replace with bare `tsx`).
+
+Per-package (run inside `packages/core`, `packages/samples`, or `apps/cli`):
+
+- `pnpm test` — `vitest --passWithNoTests` (interactive watch). For a single file: `pnpm test path/to/file.test.ts`. For one test: `pnpm test -t "test name"`.
+- `pnpm run check` — type-check only (`tsc -p ./tsconfig.json --noEmit`).
+- `pnpm run format` — prettier (note: the project uses `--experimental-ternaries`).
+- `pnpm run build` — emits dual ESM/CJS (`tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json`). The CLI package omits this script.
+
+The recursive root scripts use `pnpm run -recursive -filter "./packages/**" -filter "./apps/**" <script>` — keep that filter shape if you add new workspaces.
+
+## Build outputs
+
+Each package ships **dual ESM/CJS** via two configs:
+
+- `tsconfig.esm.json` → `dist/esm` (module: esnext)
+- `tsconfig.cjs.json` → `dist/cjs` (module: commonjs, moduleResolution: node10)
+
+Both extend `tsconfig.json` and exclude `*.test.ts`; the CJS config additionally excludes `*.sample.ts`. `package.json` `publishConfig.exports` wires the dual entry points, and `packages/core` and `packages/samples` have a `build` script that runs both `tsc` invocations.
+
+The dev `main` field points at `./src/index.ts` so workspace consumers (e.g. `apps/cli` depending on `@shapecraft/core` via `workspace:*`) get TS sources directly. Only `publishConfig` switches to `dist/` — don't add a top-level `main: dist/...` or you'll break in-repo consumers.
+
+## TypeScript strictness
+
+`packages/core/tsconfig.json` enables: `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `isolatedModules`, `noUncheckedSideEffectImports`, `moduleDetection: force`. New code is expected to type-check under all of these — in particular, `exactOptionalPropertyTypes` means `{ x?: T }` and `{ x?: T | undefined }` are different, and `noUncheckedIndexedAccess` means indexed access returns `T | undefined`.
+
+## Core architecture: the shape system
+
+Everything in `packages/core/src/` is in service of one idea: a shape value is both a TypeScript type carrier and a runtime descriptor that can validate, parse, and translate data. The shape code lives in `packages/core/src/shape/`:
+
+```
+shape/
+  base.ts            phantom-typed shape carrier
+  annotation.ts      Annotation type (optional/min/max/unique/uniqueItems/primary/
+                     autoIncrement/pattern/format/foreign/default/title/description/
+                     comment/uuidVersion/meta)
+  shape.ts           the `shapes` namespace + `annotate` namespace
+                     — constructors, Shape union, InferShapeOut, validate/is/parse, auto
+  builder.ts         the `B` namespace — fluent builder wrappers around `shapes`
+  error.ts           ValidationError type
+  number.ts          number-tag inference, widening rules, cast-compatibility
+  tags.ts            NumberTag / IntTag / FloatTag string literal unions
+  transforms/
+    json-schema/     toJSONSchema / fromJSONSchema (with `x-shapecraft` meta)
+    sql/             toSQL — emits PostgreSQL DDL from a mapping (table) or module (schema)
+    typescript/      toTypescript — emits TS type declarations from a shape
+```
+
+Supporting utilities are in `packages/core/src/common/`:
+
+- `phantom.ts` (`PhantomType = any`)
+- `result.ts` (`R.Result<T, E>` + `R.ok` / `R.err` / `R.isOk` / `R.isErr` / `R.isResult`)
+- `is.ts` (`isPlainObject`, `isNumeric`, `isSafeNumber`, `isSafeFloat`)
+- `object.ts` (`remapObjectValues`, `remapObjectEntries`)
+- `array.ts` (`range`, `uniqueBy`)
+- `string.ts` (`repeat`, `forceString`)
+- `types.ts` (`Tuple`, `Arrayish`, `Prettify`, `LooseRecord`, `Binary`, `UnionToTuple`)
+
+### 1. `base.ts` — phantom-typed shape carrier
+
+Every shape is a runtime object of the form:
+
+```ts
+{ type: "<kind>", _shape: true, anno: Annotation, input: <ctor arg>, _: { output } }
+```
+
+The `_` field is a **phantom**: `PhantomType = any` at runtime (see `common/phantom.ts`), but its TS type carries the shape's `output` (the inferred runtime type). Nothing reads `_` at runtime — it exists purely so the type system can recover `Output` from a `Shape` value. `input` *is* read at runtime (it holds the child shape for `array`, the record for `mapping` and `module`, the `[key, value]` tuple for `record`, the `{ dims, format }` for `vector`, the variants for `union`, the literal value for `literal(...)`, etc.).
+
+`createBaseWithPhantom` (scalars; `input: null`) and `createBaseWithInput` (containers; carries a concrete `input`) are the two ways shapes get built.
+
+### 2. `shape.ts` — the `shapes` namespace
+
+Constructors:
+
+- Scalars: `string()`, `boolean()`, `notDefined()` (= undefined), `nil()` (= null), `unknown()`, `date()`, `binary()` (`Uint8Array | number[]`).
+- Numbers: `number()` plus tagged variants `int()`, `int8/16/32/64`, `uint8/16/32/64`, `float()`, `float32/64`. Each carries `tag: NumberTag`; `validate` enforces the tag via `numberTagCanBeCastedTo` (see `number.ts` — widening is allowed, narrowing is not, ints and floats don't mix except via the open-ended `number` tag).
+- Literals: `literal(value)` for `string | number | boolean` — produces a shape with `literal: true` and `input` set to the value. The inferred output type is narrowed to the literal.
+- Containers: `array(item)`, `mapping(record)`, `record(keyShape, valueShape)`, `vector(dims, format?)` (defaults to `number()`), `union(...of)` — `union` is overloaded and also accepts a single array for `const` inference: `union([a, b])`.
+- `module(rec)` — top-level container of named `ShapeMapping`s. Conceptually a schema/database of tables; consumed by `toSQL` to emit multi-table DDL with FK-aware topological sort, and by `toTypescript` to emit a `namespace`.
+- `auto(input, options?)` — infers a shape from a runtime value. Walks plain objects/arrays recursively, picks a number tag from the value, and (per options) optionally produces literal shapes for strings/numbers/booleans. Arrays of numbers collapse to `array(number)` with the merged tag.
+
+Type utilities:
+
+- `Shape` — discriminated union of every shape interface (including `ShapeModule` and `ShapeBinary`).
+- `ShapeKeyable` — `ShapeString | ShapeNumber | ShapeBoolean` (what `record` keys allow).
+- `ShapeWithLength` — `ShapeString | ShapeNumber | ShapeArray` (what `min`/`max` accept).
+- `InferShapeOut<S>` — `S["_"]["output"]`. The central type-to-runtime-type bridge.
+- `Annotated<S, A>`, `MakeLiteral<S>`, `IsOptional<S>` — internal helpers used by the constructors and by `ShapeMapping`'s split-required-vs-optional output type.
+
+`ShapeMapping`'s output type splits required vs. optional keys based on `IsOptional<Rec[P]>` (which reads `anno.optional`), so `annotate.optional(...)` on a field at the value level produces an optional property in the inferred type. The split-and-recombine pattern with `Prettify` flattens the intersection for nicer IDE display.
+
+Runtime entry points (all in `shapes`):
+
+- `validate(shape, input): ValidationError[]` — returns errors with a `path: PropertyKey[]` trail. Empty array means valid. Handles `module` by requiring every named mapping (table) to be present and valid.
+- `is(shape, input): input is InferShapeOut<S>` — type predicate built on `validate`.
+- `parse(shape, input): R.Result<InferShapeOut<S>, ValidationError[]>` — runs `autoCast` *first*, then validates. `autoCast` coerces strings into numbers/booleans/dates/JSON when the target shape calls for it, and recursively casts values inside mappings/records. So `parse(number(), "42")` succeeds with `42`; `validate(number(), "42")` does not.
+
+### 3. `annotation.ts` + `annotate` namespace (in `shape.ts`)
+
+`Annotation` models:
+
+- Constraints used at validation time: `optional`, `min`, `max`, `pattern` (`string | RegExp`).
+- Constraints surfaced only via transforms: `unique`, `uniqueItems` (array-element uniqueness), `primary`, `autoIncrement`, `format`, `foreign: { table, column }`, `default`, `uuidVersion`.
+- Documentation/metadata: `title`, `description`, `comment`, `meta: Record<string, any>`.
+
+The `annotate` helpers — `as`, `optional`, `unique`, `uniqueItems`, `primary`, `autoIncremented`, `foreign(table, column)`, `defaulted`, `described`, `titled`, `commented`, `min(n)`, `max(n)`, `pattern(p)`, `format(f)`, `uuid(version?)`, `meta(rec)` — all wrap `annotate.as(shape, anno)` which merges into the existing `shape.anno`. `uuid` is sugar that sets `pattern` to a UUID regex (versioned if `version` is supplied) and records the version in `uuidVersion`. `meta` deep-merges into `anno.meta` rather than replacing it.
+
+`min`/`max` are validated against length for `string`/`array`, against value for `number`. `pattern` is validated against the string via `new RegExp(...)`/`.test(...)`. `unique`, `uniqueItems`, `primary`, `autoIncrement`, `foreign`, `default`, `format`, `title`, `description`, `comment`, `meta`, `uuidVersion` are metadata only at the moment — `validate` does not check them, but `toJSONSchema`, `toSQL`, and `toTypescript` consume them (e.g. `primary` → `PRIMARY KEY`, `autoIncrement` → `GENERATED ALWAYS AS IDENTITY`, `uniqueItems` on a non-jsonb array → emits a `shapecraft_array_is_unique` helper function and a `CHECK`, etc.).
+
+When extending the annotation model: add to the `Annotation` type, add a helper to `annotate`, wire it through `validate` if it should affect runtime checking, wire it through `toJSONSchema`/`fromJSONSchema` if it should round-trip through JSON Schema, wire it through `toSQL`/`toTypescript` if it should appear in those outputs, and (if it should affect the inferred output type) thread it through `shapes.ShapeMapping` / a new `Is<...>` utility analogous to `IsOptional`.
+
+### 4. `builder.ts` — the `B` namespace
+
+`B` is a parallel, fluent surface over `shapes` for ergonomic definitions:
+
+```ts
+const userShape = B.mapping({
+  id: B.uint32().primary().autoIncrement(),
+  email: B.string().regex(/.+@.+/).optional(),
+  tags: B.array(B.string()).min(1).max(10).uniqueItems(),
+}).shape; // .shape gets you the underlying shapes.Shape
+```
+
+Each builder wraps a `shapes.Shape` and exposes:
+
+- `.shape`, `.type` — accessors.
+- `.is(x)`, `.parse(x)` — runtime entry points.
+- Annotation methods, each returning a *new* builder with the merged annotation: `optional()`, `unique()`, `primary()`, `default(v)`, `title(t)`, `describe(t)`, `comment(t)`, `autoIncrement()`, `foreign(table, column)`, `references(targetBuilder, field)` (type-safe FK: picks a field from another builder's mapping whose column type matches this builder's `type`), `meta(rec)`.
+- Transform methods: `.toJSONSchema()`, `.toSQL()`, `.toTypescript()`.
+
+Three specialized builders extend the base:
+
+- `ShapeBuilderForString` — adds `min`, `max`, `regex`, `format`, `uuid(version?)`.
+- `ShapeBuilderForNumber` — adds `min`, `max`.
+- `ShapeBuilderForArray` — adds `min`, `max`, `uniqueItems`.
+
+`createBuilder(shape)` dispatches on `shape.type` to pick the right specialized builder. `B.module({ name: B.mapping(...) })` wraps `shapes.module` to define a multi-table schema.
+
+If you add a new shape kind to `shapes`, also add a `B.<kind>(...)` constructor; if you add a new annotation, add a method on the appropriate builder interface and (if it should be a transform) thread it through the transform methods.
+
+### 5. `transforms/json-schema/` — JSON Schema bridge
+
+`toJSONSchema(shape)` and `fromJSONSchema(schema)` round-trip shapes through Draft-compatible JSON Schema. Shape-specific information that JSON Schema can't natively express (number tags, vector dims, the `date`/`binary`/`undefined` distinction, top-level optional, `unique`/`primary`/`foreign`) is preserved on an `x-shapecraft` meta object (`ShapecraftMeta` in `transforms/json-schema/types.ts`).
+
+Notable behaviors: integer-tag numbers emit `type: "integer"` with the natural `minimum`/`maximum` for the tag plus the user's `anno.min`/`max` intersected in; `record` with a number key shape emits a numeric `propertyNames.pattern`; literal scalars and literal-only unions emit `const`/`enum`; `date` → `string + format: date-time`; `binary` → `string + contentEncoding: base64`.
+
+### 6. `transforms/sql/` — PostgreSQL DDL emitter
+
+`toSQL(shape): R.Result<string, string[]>` accepts a `ShapeMapping` (single table) or a `ShapeModule` (multi-table schema) and emits PostgreSQL DDL. Top-level mappings require `anno.title` (used as the table name). Integer tags map to `smallint`/`integer`/`bigint`/`numeric(20,0)`; floats to `real`/`double precision`; `date` → `timestamptz`; `binary` → `bytea`; `vector` → `vector(N)` (pgvector); records/mappings/unknown values fall back to `jsonb`. Unions of string literals emit either a named `CREATE TYPE … AS ENUM` (when the union has a `title`) or a `text` column with a `CHECK … IN (…)` constraint. `min`/`max` on integers intersects with the natural tag range to decide whether a `CHECK` is needed beyond the column type's implicit bounds. `uniqueItems: true` on a non-jsonb array column emits a `shapecraft_array_is_unique` SQL function once (in the prelude) and a `CHECK` referencing it. `autoIncrement` becomes `GENERATED ALWAYS AS IDENTITY` (and errors on non-int / `uint64`). For `module`, tables are topologically sorted by `foreign` references; FK cycles return an error.
+
+### 7. `transforms/typescript/` — TS type emitter
+
+`toTypescript(shape): string` produces TS type declarations. Top-level `module` emits `export namespace <Title> { … }` when titled; top-level titled `mapping` emits `export type <Title> = { … }`; bare shapes emit an inline type. Annotation hints surface as comments: `description`, `comment`, `primary`, `pattern`, `format`, `min`/`max`, `foreign`, `unique`/`uniqueItems`, `default`. Unions of differently-formatted strings collapse to `string` at the type level, but their `format` annotations are lifted into a single hint comment so the information isn't lost.
+
+### Usage shape
+
+Using the `shapes` namespace directly:
+
+```ts
+const myShape = shapes.mapping({
+  foo: annotate.optional(shapes.union(shapes.string(), shapes.number())),
+  bar: shapes.record(shapes.string(), shapes.number()),
+  baz: shapes.unknown(),
+});
+type T = shapes.InferShapeOut<typeof myShape>;
+// { foo?: string | number; bar: Record<string, number>; baz: unknown }
+
+const result = shapes.parse(myShape, someInput); // R.Result<T, ValidationError[]>
+```
+
+Equivalent via `B`:
+
+```ts
+const myShape = B.mapping({
+  foo: B.union(B.string(), B.number()).optional(),
+  bar: B.record(B.string(), B.number()),
+  baz: B.unknown(),
+});
+type T = shapes.InferShapeOut<typeof myShape.shape>;
+const result = myShape.parse(someInput);
+```
+
+Multi-table schema via `B.module` (see `packages/samples/src/blog.ts` and `relational.ts` for full examples):
+
+```ts
+const User = B.mapping({
+  id: B.uint64().primary().autoIncrement(),
+  email: B.string(),
+}).title("User");
+
+const Post = B.mapping({
+  id: B.uint64().primary().autoIncrement(),
+  author: B.uint64().references(User, "id"),
+  title: B.string().min(1).max(200),
+}).title("Post");
+
+const schema = B.module({ User, Post });
+const sql = schema.toSQL(); // R.Result<string, string[]>
+```
+
+## Style notes pulled from the existing code
+
+- The `package.json` scripts in `packages/core` and `packages/samples` are written with `"test": "vitest --passWithNoTests","check":` on one line — valid JSON, just unusual formatting. If you reformat package.json, preserve the script values.
+- Prettier is invoked with `--experimental-ternaries`; formatted ternary blocks (see `IsOptional` in `shape.ts`, or the dispatch in `transforms/json-schema/transform.ts`) will look unusual. Don't "fix" them.
+- `.~undo-tree~` files are local editor state (Emacs undo-tree). They're gitignored — ignore them when searching.
+- `test-data/json-schema/` holds reference JSON Schemas used as fixtures by the JSON-Schema transform tests and as inputs for `pnpm run cli transform`.

package/README.md

@@ -0,0 +1,22 @@
+# shapecraft
+- type validations
+- schema definitions
+- ... WIP
+
+
+## Example
+```typescript
+
+const myShape = shapes.mapping({
+  foo: annotate.optional(shapes.union(shapes.string(), shapes.number())),
+  bar: shapes.record(shapes.string(), shapes.number()),
+  baz: shapes.unknown()
+});
+
+```
+
+## Project Structure
+- `./packages` - shared packages
+- `./apps` - runnable programs
+- `./packages/core` - the core shape library
+- `./apps/cli` - command-line interface (WIP)

package/apps/cli/node_modules/.bin/prettier

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/prettier@3.8.3/node_modules/prettier/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/prettier@3.8.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/prettier@3.8.3/node_modules/prettier/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/prettier@3.8.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../prettier/bin/prettier.cjs" "$@"
+else
+  exec node  "$basedir/../prettier/bin/prettier.cjs" "$@"
+fi

package/apps/cli/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/apps/cli/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/apps/cli/node_modules/.bin/tsx

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/tsx@4.22.0/node_modules/tsx/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/tsx@4.22.0/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/tsx@4.22.0/node_modules/tsx/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/tsx@4.22.0/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
+fi

package/apps/cli/node_modules/.bin/vitest

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/vitest@4.1.6_@types+node@25.8.0_vite@8.0.13_@types+node@25.8.0_esbuild@0.28.0_tsx@4.22.0_/node_modules/vitest/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/vitest@4.1.6_@types+node@25.8.0_vite@8.0.13_@types+node@25.8.0_esbuild@0.28.0_tsx@4.22.0_/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/vitest@4.1.6_@types+node@25.8.0_vite@8.0.13_@types+node@25.8.0_esbuild@0.28.0_tsx@4.22.0_/node_modules/vitest/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/vitest@4.1.6_@types+node@25.8.0_vite@8.0.13_@types+node@25.8.0_esbuild@0.28.0_tsx@4.22.0_/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"
+else
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+fi

package/apps/cli/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@shapecraft/cli",
+  "version": "1.0.0",
+  "description": "",
+  "main": "./src/index.ts",
+  "scripts": {
+    "test": "vitest --passWithNoTests",
+    "check": "tsc -p ./tsconfig.json --noEmit",
+    "format": "prettier --experimental-ternaries ./src --write"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@10.33.2",
+  "dependencies": {
+    "@shapecraft/core": "workspace:*",
+    "citty": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "prettier": "^3.8.3",
+    "tsx": "^4.22.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "publishConfig": {
+    "main": "./dist/cjs/index.js",
+    "types": "./dist/cjs/index.d.ts",
+    "typings": "./dist/cjs/index.d.ts",
+    "exports": {
+      ".": {
+        "import": {
+          "types": "./dist/esm/index.d.ts",
+          "default": "./dist/esm/index.js"
+        },
+        "require": {
+          "types": "./dist/cjs/index.d.ts",
+          "default": "./dist/cjs/index.js"
+        },
+        "default": {
+          "types": "./dist/cjs/index.d.ts",
+          "default": "./dist/cjs/index.js"
+        }
+      }
+    }
+  }
+}

package/apps/cli/src/index.ts

@@ -0,0 +1,98 @@
+import {
+  fromJSONSchema,
+  fromSQL,
+  shapes,
+  SQLDialect,
+  toSQL,
+  toTypescript,
+} from "@shapecraft/core";
+import { defineCommand, runMain } from "citty";
+import fs from "fs";
+
+const cmdTransform = defineCommand({
+  args: {
+    input: {
+      type: "positional",
+      required: true,
+    },
+    output: {
+      type: "string",
+      required: false,
+    },
+    format: {
+      type: "enum",
+      options: ["sql", "typescript"],
+      default: "sql",
+      required: false,
+    },
+    dialect: {
+      type: "enum",
+      options: ["postgres", "sqlite"],
+      default: "postgres",
+      required: false,
+    },
+  },
+  run: (ctx) => {
+    const contents = fs.readFileSync(ctx.args.input, "utf-8");
+    const dialect = ctx.args.dialect as SQLDialect;
+
+    let shape: shapes.Shape | null = null;
+    let errors: string[] | null = null;
+    let output: string = "";
+
+    if (ctx.args.input.toLowerCase().endsWith(".sql")) {
+      const parsed = fromSQL(contents, { dialect });
+      if (parsed.ok) {
+        shape = parsed.value;
+      } else {
+        errors = parsed.error;
+      }
+    } else {
+      shape = fromJSONSchema(JSON.parse(contents));
+    }
+
+    if (shape) {
+      switch (ctx.args.format) {
+        case "typescript":
+          {
+            output = toTypescript(shape);
+          }
+          break;
+        default:
+        case "sql":
+          {
+            const sql = toSQL(shape, { dialect });
+            if (sql.ok) {
+              output = sql.value;
+            } else {
+              errors = sql.error;
+            }
+          }
+          break;
+      }
+    }
+
+    if (!errors) {
+      if (ctx.args.output) {
+        fs.writeFileSync(ctx.args.output, output, "utf-8");
+        console.log(`Wrote to: ${ctx.args.output}`);
+      } else {
+        console.log(output);
+      }
+    } else {
+      console.error(`Error!`);
+      console.error(`total errors: ${errors.length}`);
+      for (const err of errors) {
+        console.error(`- ${err}`);
+      }
+    }
+  },
+});
+
+runMain(
+  defineCommand({
+    subCommands: {
+      transform: cmdTransform,
+    },
+  }),
+);

package/apps/cli/tsconfig.cjs.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist/cjs",
+    "module": "commonjs",
+    "moduleResolution": "node10"
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["./src/**/*.test.ts", "./src/**/*.sample.ts"]
+}

package/apps/cli/tsconfig.esm.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "module": "esnext",
+    "target": "esnext"
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["./src/**/*.test.ts"]
+}

package/apps/cli/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "module": "esnext",
+    "target": "esnext",
+    "lib": ["esnext"],
+    "types": ["node"],
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "strict": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "shapecraft",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "scripts": {
+    "cli": "./apps/cli/node_modules/.bin/tsx ./apps/cli/src/index.ts",
+    "check": "pnpm run -recursive -filter \"./packages/**\" -filter \"./apps/**\" check",
+    "test": "pnpm run -recursive -filter \"./packages/**\" -filter \"./apps/**\" test",
+    "format": "pnpm run -recursive -filter \"./packages/**\" -filter \"./apps/**\" format",
+    "build": "pnpm run -recursive -filter \"./packages/**\" build"
+  }
+}

package/packages/core/node_modules/.bin/prettier

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/prettier@3.8.3/node_modules/prettier/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/prettier@3.8.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/prettier@3.8.3/node_modules/prettier/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/prettier@3.8.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../prettier/bin/prettier.cjs" "$@"
+else
+  exec node  "$basedir/../prettier/bin/prettier.cjs" "$@"
+fi

package/packages/core/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/packages/core/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/ianertson/workspace/shapecraft/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi