@defai.digital/ax-cli 3.8.8 → 3.8.10

package/node_modules/@ax-cli/schemas/README.md

@@ -0,0 +1,388 @@
+# @ax-cli/schemas
+
+Single Source of Truth (SSOT) Type System for AX CLI.
+
+This package provides centralized Zod schemas, brand types, and enums for the entire ax-cli ecosystem, ensuring type safety and runtime validation across all modules.
+
+## Installation
+
+```bash
+npm install @ax-cli/schemas
+```
+
+## What is Single Source of Truth (SSOT)?
+
+**Single Source of Truth (SSOT)**: All modules (API / MCP / Usage) share the same type definition contract.
+
+Before @ax-cli/schemas, type definitions were scattered across the codebase, leading to:
+- Duplicated schema definitions
+- Inconsistent validation logic
+- Type mismatches between modules
+- High refactoring costs
+
+### Architecture: Before vs. After
+
+**BEFORE** (Distributed, Inconsistent):
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   API Handler   │     │   MCP Adapter   │     │  Usage Module   │
+├─────────────────┤     ├─────────────────┤     ├─────────────────┤
+│ • Own schemas   │     │ • Own schemas   │     │ • Own schemas   │
+│ • Own types     │     │ • Own types     │     │ • Own types     │
+│ • Own enums     │     │ • Own enums     │     │ • Own enums     │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+      ❌                       ❌                       ❌
+   Duplicated              Duplicated              Duplicated
+   Diverges over time      Diverges over time      Diverges over time
+```
+
+**AFTER** (Centralized, Consistent):
+```
+                    ┌──────────────────────────────┐
+                    │      @ax-cli/schemas         │
+                    ├──────────────────────────────┤
+                    │ • Brand Types (ID safety)    │
+                    │ • Centralized Enums          │
+                    │ • Zod Schemas (validation)   │
+                    │ • TypeScript Types           │
+                    └───────────────┬──────────────┘
+                                    │
+                      ┌─────────────┼─────────────┐
+                      │             │             │
+                      ▼             ▼             ▼
+            ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+            │ API Handler │ │ MCP Adapter │ │Usage Module │
+            ├─────────────┤ ├─────────────┤ ├─────────────┤
+            │ import {...}│ │ import {...}│ │ import {...}│
+            │ from        │ │ from        │ │ from        │
+            │ '@ax-cli/   │ │ '@ax-cli/   │ │ '@ax-cli/   │
+            │  schemas'   │ │  schemas'   │ │  schemas'   │
+            └─────────────┘ └─────────────┘ └─────────────┘
+                  ✅               ✅               ✅
+              Same contract   Same contract   Same contract
+```
+
+### Benefits
+
+**1. Zero Divergence**
+All modules consume the same source - when you update `ModelId` schema, all consumers get the update automatically.
+
+**2. Reduced Refactoring Cost**
+Change once in `@ax-cli/schemas`, propagate everywhere. No need to hunt down all duplicate definitions.
+
+**3. Compile-Time Safety**
+TypeScript catches type mismatches across module boundaries:
+```typescript
+// API handler expects ModelId
+function handleRequest(model: ModelId) { ... }
+
+// MCP adapter provides ModelId (same type!)
+const mcpModel = ModelIdSchema.parse(input);
+handleRequest(mcpModel);  // ✅ Type-safe!
+
+// Usage module also uses ModelId (same type!)
+const usageModel = getModelFromDB();  // Returns ModelId
+handleRequest(usageModel);  // ✅ Type-safe!
+```
+
+**4. Runtime Validation Consistency**
+All modules use the same Zod schemas, ensuring consistent validation rules across API boundaries, MCP adapters, and usage tracking.
+
+## Features
+
+- **Brand Types**: Compile-time nominal typing for ID types to prevent mixing
+- **Centralized Enums**: Single source of truth for all enum values
+- **Zod Schemas**: Runtime validation with TypeScript type inference
+- **Zero Runtime Cost**: Brand types are compile-time only (erased during compilation)
+- **100% Test Coverage**: Comprehensive test suite (123 tests)
+
+## Quick Start
+
+### Using Brand Types
+
+```typescript
+import { ModelId, ModelIdSchema } from '@ax-cli/schemas';
+
+// ✅ Safe: Runtime validation + branding
+const modelId = ModelIdSchema.parse('glm-4.6');
+
+// ✅ Type-safe function signatures
+function getModelConfig(id: ModelId) {
+  // TypeScript prevents passing other ID types here
+}
+
+// ❌ Compile error: Can't pass plain string
+getModelConfig('glm-4.6'); // TypeScript error!
+
+// ✅ Correct: Parse first
+getModelConfig(ModelIdSchema.parse('glm-4.6'));
+```
+
+### Using Enums
+
+```typescript
+import { MessageRoleEnum, type MessageRole } from '@ax-cli/schemas';
+
+// ✅ Use in Zod schemas
+const MessageSchema = z.object({
+  role: MessageRoleEnum,
+  content: z.string(),
+});
+
+// ✅ Use type for function signatures
+function handleMessage(role: MessageRole, content: string) {
+  // role is typed as 'system' | 'user' | 'assistant' | 'tool'
+}
+```
+
+## API Reference
+
+### Brand Types
+
+All ID types are branded to prevent accidental mixing:
+
+```typescript
+import {
+  ApiResponseId,
+  ToolCallId,
+  ModelId,
+  MCPServerId,
+  // ... and their corresponding schemas
+  ApiResponseIdSchema,
+  ToolCallIdSchema,
+  ModelIdSchema,
+  MCPServerIdSchema,
+} from '@ax-cli/schemas';
+```
+
+**Available Brand Types:**
+- `ApiResponseId` / `ApiResponseIdSchema`
+- `ToolCallId` / `ToolCallIdSchema`
+- `ModelId` / `ModelIdSchema`
+- `TenantId` / `TenantIdSchema`
+- `ApiKeyId` / `ApiKeyIdSchema`
+- `MCPServerId` / `MCPServerIdSchema`
+- `UsageRecordId` / `UsageRecordIdSchema`
+- `PlanId` / `PlanIdSchema`
+- `SessionId` / `SessionIdSchema`
+- `RequestId` / `RequestIdSchema`
+
+### Enums
+
+```typescript
+import {
+  MessageRoleEnum,
+  FinishReasonEnum,
+  TransportEnum,
+  EditorCommandEnum,
+} from '@ax-cli/schemas';
+```
+
+**MessageRoleEnum**: `'system' | 'user' | 'assistant' | 'tool'`
+
+**FinishReasonEnum**: `'stop' | 'length' | 'tool_calls' | 'content_filter'`
+
+**TransportEnum**: `'stdio' | 'http' | 'sse'`
+
+**EditorCommandEnum**: `'view' | 'create' | 'str_replace' | 'insert' | 'undo_edit'`
+
+### Brand Type Utilities
+
+```typescript
+import {
+  brand,
+  unbrand,
+  isBranded,
+  createBrandFactory,
+  type Brand,
+} from '@ax-cli/schemas';
+
+// Create custom brand types
+const MyIdSchema = z.string().transform((val) => brand<string, 'MyId'>(val));
+type MyId = Brand<string, 'MyId'>;
+
+// Remove branding (use sparingly!)
+const plainString = unbrand(brandedId);
+
+// Check if value is branded
+if (isBranded(value, 'ModelId')) {
+  // TypeScript knows this is a ModelId
+}
+```
+
+## Security Best Practices
+
+### CRITICAL: Brand Types Are Compile-Time Only
+
+Brand types provide **ZERO runtime validation**. You **MUST** validate all external inputs at system boundaries.
+
+```typescript
+// ❌ UNSAFE: No runtime validation!
+const tenantId = userInput as TenantId; // DON'T DO THIS!
+
+// ✅ SAFE: Validates with Zod
+const result = TenantIdSchema.safeParse(userInput);
+if (result.success) {
+  const tenantId = result.data; // Type-safe AND runtime-safe
+}
+```
+
+### When to Validate
+
+Always validate at these boundaries:
+
+- **API boundaries**: HTTP requests, MCP inputs
+- **File I/O**: Reading configs, user settings
+- **Database queries**: WHERE clauses with user IDs
+- **Environment variables**
+- **Command-line arguments**
+
+### Safe Validation Pattern
+
+```typescript
+import { ModelIdSchema, type ModelId } from '@ax-cli/schemas';
+
+function updateModel(modelName: string): void {
+  // ✅ Validate at boundary
+  const result = ModelIdSchema.safeParse(modelName);
+
+  if (!result.success) {
+    throw new Error(`Invalid model ID: ${result.error.message}`);
+  }
+
+  // Now we have a branded ModelId
+  const modelId: ModelId = result.data;
+
+  // Use in type-safe functions
+  processModel(modelId);
+}
+
+function processModel(id: ModelId): void {
+  // TypeScript ensures only ModelId can be passed here
+  // No accidental mixing with other ID types!
+}
+```
+
+## Migration Guide
+
+### Adding Brand Types to Existing Code
+
+**Step 1**: Import the schema
+
+```typescript
+import { ModelIdSchema } from '@ax-cli/schemas';
+```
+
+**Step 2**: Use `.parse()` at object creation boundaries
+
+```typescript
+// Before
+const config = {
+  model: 'glm-4.6',  // Plain string
+};
+
+// After
+const config = {
+  model: ModelIdSchema.parse('glm-4.6'),  // Branded ModelId
+};
+```
+
+**Step 3**: Update function signatures
+
+```typescript
+// Before
+function getConfig(model: string) { }
+
+// After
+function getConfig(model: ModelId) { }
+```
+
+**Step 4**: Fix TypeScript errors by adding `.parse()` at call sites
+
+```typescript
+// Before
+getConfig('glm-4.6');  // Now causes TypeScript error
+
+// After
+getConfig(ModelIdSchema.parse('glm-4.6'));  // Type-safe!
+```
+
+### Default Values
+
+For constants and defaults, parse at definition:
+
+```typescript
+import { ModelIdSchema } from '@ax-cli/schemas';
+
+const DEFAULT_CONFIG = {
+  model: ModelIdSchema.parse('glm-4.6'),
+  // ... other fields
+};
+```
+
+## Performance
+
+- **Brand types**: Zero runtime cost (compile-time only)
+- **Zod validation**: ~1-2μs per validation (negligible)
+- **Test performance**: 123 tests in <20ms
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Type checking
+npm run typecheck
+
+# Build
+npm run build
+```
+
+## Architecture
+
+```
+packages/schemas/
+├── src/
+│   ├── index.ts                    # Public API
+│   ├── public/
+│   │   └── core/
+│   │       ├── brand-types.ts      # Brand type utilities
+│   │       ├── enums.ts            # Centralized enums
+│   │       └── id-types.ts         # ID brand types
+│   └── __tests__/
+│       ├── brand-types.test.ts     # 40 tests
+│       ├── enums.test.ts           # 31 tests
+│       └── id-types.test.ts        # 52 tests
+└── dist/                           # Compiled output
+```
+
+## Version
+
+Current version: 1.0.0
+
+## License
+
+MIT
+
+## Related Packages
+
+- `@ax-cli/schemas` (this package): Type system foundation
+- `ax-cli`: Main CLI application
+
+## Contributing
+
+When adding new brand types or enums:
+
+1. Add implementation to `src/public/core/`
+2. Export from `src/index.ts`
+3. Add comprehensive tests
+4. Update this README
+5. Run `npm test` and `npm run typecheck`
+
+## Support
+
+For issues and questions, please open an issue in the main ax-cli repository.

package/node_modules/@ax-cli/schemas/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ax-cli/schemas",
+  "version": "1.0.0",
+  "description": "Single Source of Truth (SSOT) type system for ax-cli - Zod schemas, brand types, and OpenAPI generation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "zod",
+    "schemas",
+    "validation",
+    "types",
+    "openapi",
+    "brand-types",
+    "type-safety"
+  ],
+  "author": "DEFAI Digital <https://defai.digital>",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "eslint": "^8.54.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/node_modules/zod/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/zod/README.md

@@ -0,0 +1,208 @@
+<p align="center">
+  <img src="logo.svg" width="200px" align="center" alt="Zod logo" />
+  <h1 align="center">Zod</h1>
+  <p align="center">
+    TypeScript-first schema validation with static type inference
+    <br/>
+    by <a href="https://x.com/colinhacks">@colinhacks</a>
+  </p>
+</p>
+<br/>
+
+<p align="center">
+<a href="https://github.com/colinhacks/zod/actions?query=branch%3Amaster"><img src="https://github.com/colinhacks/zod/actions/workflows/test.yml/badge.svg?event=push&branch=master" alt="Zod CI status" /></a>
+<a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/colinhacks/zod" alt="License"></a>
+<a href="https://www.npmjs.com/package/zod" rel="nofollow"><img src="https://img.shields.io/npm/dw/zod.svg" alt="npm"></a>
+<a href="https://discord.gg/KaSRdyX2vc" rel="nofollow"><img src="https://img.shields.io/discord/893487829802418277?label=Discord&logo=discord&logoColor=white" alt="discord server"></a>
+<a href="https://github.com/colinhacks/zod" rel="nofollow"><img src="https://img.shields.io/github/stars/colinhacks/zod" alt="stars"></a>
+</p>
+
+<div align="center">
+  <a href="https://zod.dev/api">Docs</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://discord.gg/RcG33DQJdf">Discord</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://twitter.com/colinhacks">𝕏</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://bsky.app/profile/zod.dev">Bluesky</a>
+  <br />
+</div>
+
+<br/>
+<br/>
+
+<h2 align="center">Featured sponsor: Jazz</h2>
+
+<div align="center">
+  <a href="https://jazz.tools/?utm_source=zod">
+    <picture width="85%" >
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/garden-co/jazz/938f6767e46cdfded60e50d99bf3b533f4809c68/homepage/homepage/public/Zod%20sponsor%20message.png">
+      <img alt="jazz logo" src="https://raw.githubusercontent.com/garden-co/jazz/938f6767e46cdfded60e50d99bf3b533f4809c68/homepage/homepage/public/Zod%20sponsor%20message.png" width="85%">
+    </picture>
+  </a>
+  <br/>
+  <p><sub>Learn more about <a target="_blank" rel="noopener noreferrer" href="mailto:sponsorship@colinhacks.com">featured sponsorships</a></sub></p>
+</div>
+
+<br/>
+<br/>
+<br/>
+
+### [Read the docs →](https://zod.dev/api)
+
+<br/>
+<br/>
+
+## What is Zod?
+
+Zod is a TypeScript-first validation library. Define a schema and parse some data with it. You'll get back a strongly typed, validated result.
+
+```ts
+import * as z from "zod/v4";
+
+const User = z.object({
+  name: z.string(),
+});
+
+// some untrusted data...
+const input = {
+  /* stuff */
+};
+
+// the parsed result is validated and type safe!
+const data = User.parse(input);
+
+// so you can use it with confidence :)
+console.log(data.name);
+```
+
+<br/>
+
+## Features
+
+- Zero external dependencies
+- Works in Node.js and all modern browsers
+- Tiny: `2kb` core bundle (gzipped)
+- Immutable API: methods return a new instance
+- Concise interface
+- Works with TypeScript and plain JS
+- Built-in JSON Schema conversion
+- Extensive ecosystem
+
+<br/>
+
+## Installation
+
+```sh
+npm install zod
+```
+
+<br/>
+
+## Basic usage
+
+Before you can do anything else, you need to define a schema. For the purposes of this guide, we'll use a simple object schema.
+
+```ts
+import * as z from "zod/v4";
+
+const Player = z.object({
+  username: z.string(),
+  xp: z.number(),
+});
+```
+
+### Parsing data
+
+Given any Zod schema, use `.parse` to validate an input. If it's valid, Zod returns a strongly-typed _deep clone_ of the input.
+
+```ts
+Player.parse({ username: "billie", xp: 100 });
+// => returns { username: "billie", xp: 100 }
+```
+
+**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](#refine) or [transforms](#transform), you'll need to use the `.parseAsync()` method instead.
+
+```ts
+const schema = z.string().refine(async (val) => val.length <= 8);
+
+await schema.parseAsync("hello");
+// => "hello"
+```
+
+### Handling errors
+
+When validation fails, the `.parse()` method will throw a `ZodError` instance with granular information about the validation issues.
+
+```ts
+try {
+  Player.parse({ username: 42, xp: "100" });
+} catch (err) {
+  if (err instanceof z.ZodError) {
+    err.issues;
+    /* [
+      {
+        expected: 'string',
+        code: 'invalid_type',
+        path: [ 'username' ],
+        message: 'Invalid input: expected string'
+      },
+      {
+        expected: 'number',
+        code: 'invalid_type',
+        path: [ 'xp' ],
+        message: 'Invalid input: expected number'
+      }
+    ] */
+  }
+}
+```
+
+To avoid a `try/catch` block, you can use the `.safeParse()` method to get back a plain result object containing either the successfully parsed data or a `ZodError`. The result type is a [discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions), so you can handle both cases conveniently.
+
+```ts
+const result = Player.safeParse({ username: 42, xp: "100" });
+if (!result.success) {
+  result.error; // ZodError instance
+} else {
+  result.data; // { username: string; xp: number }
+}
+```
+
+**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](#refine) or [transforms](#transform), you'll need to use the `.safeParseAsync()` method instead.
+
+```ts
+const schema = z.string().refine(async (val) => val.length <= 8);
+
+await schema.safeParseAsync("hello");
+// => { success: true; data: "hello" }
+```
+
+### Inferring types
+
+Zod infers a static type from your schema definitions. You can extract this type with the `z.infer<>` utility and use it however you like.
+
+```ts
+const Player = z.object({
+  username: z.string(),
+  xp: z.number(),
+});
+
+// extract the inferred type
+type Player = z.infer<typeof Player>;
+
+// use it in your code
+const player: Player = { username: "billie", xp: 100 };
+```
+
+In some cases, the input & output types of a schema can diverge. For instance, the `.transform()` API can convert the input from one type to another. In these cases, you can extract the input and output types independently:
+
+```ts
+const mySchema = z.string().transform((val) => val.length);
+
+type MySchemaIn = z.input<typeof mySchema>;
+// => string
+
+type MySchemaOut = z.output<typeof mySchema>; // equivalent to z.infer<typeof mySchema>
+// number
+```

package/node_modules/zod/index.cjs

@@ -0,0 +1,33 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.z = void 0;
+const z = __importStar(require("./v3/external.cjs"));
+exports.z = z;
+__exportStar(require("./v3/external.cjs"), exports);
+exports.default = z;