feat: npx @graplix/codegen

Author: tonyfromundefined

.changeset/afraid-gifts-greet.md

@@ -0,0 +1,5 @@
+---
+"@graplix/codegen": minor
+---
+
+feat: npx @graplix/codegen

AGENTS.md

@@ -142,7 +142,7 @@ From `biome.json`:
 - CLI supports config discovery via `cosmiconfig`.
 - Supported config names include `graplix.codegen.*` and `graplix-codegen.config.*`.
 - CLI precedence: command-line args override config values.
-- Prefer `defineConfig` from `@graplix/codegen` for typed config files.
+- Prefer JSON config with `$schema` for editor-validated codegen settings.
 
 ## Tech Spec Workflow
 

README.md

@@ -31,6 +31,7 @@ Runtime evaluator for schema-defined relations.
 TypeScript generator for Graplix schemas.
 
 - Generates typed helpers from `.graplix` input.
+- Run from npm with `npx @graplix/codegen`.
 - Supports mapper configuration and config-file discovery.
 - README: [`packages/codegen/README.md`](packages/codegen/README.md)
 

packages/codegen/README.md

@@ -5,14 +5,13 @@ Generates TypeScript helpers from Graplix schema files.
 ## CLI
 
 ```bash
-yarn workspace @graplix/codegen build
-yarn workspace @graplix/codegen codegen ./schema.graplix
+npx @graplix/codegen ./schema.graplix
 ```
 
 With mapper overrides:
 
 ```bash
-yarn workspace @graplix/codegen codegen ./schema.graplix ./schema.generated.ts --mapper user=./models#User --mapper repository=./models#Repository
+npx @graplix/codegen ./schema.graplix ./schema.generated.ts --mapper user=./models#User --mapper repository=./models#Repository
 ```
 
 Config files are also supported (`cosmiconfig`):
@@ -21,10 +20,15 @@ Config files are also supported (`cosmiconfig`):
 - `graplix-codegen.config.json|yaml|yml|js|cjs|mjs|ts|cts|mts`
 - `package.json` with `"graplix-codegen"` key
 
+JSON Schema for editor auto-complete/validation:
+
+- `https://unpkg.com/@graplix/codegen@latest/schema.json`
+
 Example (`graplix.codegen.json`):
 
 ```json
 {
+  "$schema": "https://unpkg.com/@graplix/codegen@latest/schema.json",
   "schema": "./schema.graplix",
   "output": "./schema.generated.ts",
   "mappers": {
@@ -35,20 +39,6 @@ Example (`graplix.codegen.json`):
 
 CLI args override config values.
 
-Typed config helper:
-
-```ts
-import { defineConfig } from "@graplix/codegen";
-
-export default defineConfig({
-  schema: "./schema.graplix",
-  output: "./schema.generated.ts",
-  mappers: {
-    user: "./models#User",
-  },
-});
-```
-
 ## Programmatic API
 
 ```ts

packages/codegen/package.json

@@ -24,16 +24,16 @@
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./schema.json": "./schema.json"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
-  "bin": {
-    "graplix-codegen": "./dist/cli.mjs"
-  },
+  "bin": "./dist/cli.mjs",
   "files": [
-    "dist"
+    "dist",
+    "schema.json"
   ],
   "scripts": {
     "build": "tsdown",

packages/codegen/schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@graplix/codegen@latest/schema.json",
+  "title": "@graplix/codegen configuration",
+  "description": "Configuration for Graplix TypeScript code generation.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional schema URL for editor auto-completion and validation."
+    },
+    "schema": {
+      "type": "string",
+      "description": "Path to the .graplix schema file."
+    },
+    "output": {
+      "type": "string",
+      "description": "Output file path for generated TypeScript."
+    },
+    "mappers": {
+      "type": "object",
+      "description": "Map Graplix type names to TypeScript type references.",
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  },
+  "required": ["schema"],
+  "additionalProperties": false
+}

packages/codegen/src/cli.ts

@@ -22,7 +22,7 @@ interface ResolvedArguments {
 
 function fail(message: string): never {
   throw new Error(
-    `${message}\nUsage: graplix-codegen [schema.graplix] [output.ts] [--config graplix.codegen.json] [--mapper Type=./module#Type]`,
+    `${message}\nUsage: npx @graplix/codegen [schema.graplix] [output.ts] [--config graplix.codegen.json] [--mapper Type=./module#Type]`,
   );
 }
 

packages/codegen/src/config.ts

@@ -1,11 +1,8 @@
 import type { MapperConfig } from "./generate";
 
 export interface CodegenConfig {
+  readonly $schema?: string;
   readonly schema: string;
   readonly output?: string;
   readonly mappers?: MapperConfig;
 }
-
-export function defineConfig(config: CodegenConfig): CodegenConfig {
-  return config;
-}

packages/codegen/src/index.ts

@@ -1,4 +1,4 @@
-export { type CodegenConfig, defineConfig } from "./config";
+export type { CodegenConfig } from "./config";
 export {
   type GenerateTypeScriptFromFileOptions,
   type GenerateTypeScriptOptions,