@defai.digital/ax-cli 1.1.1 → 1.1.3

package/.ax-cli/CUSTOM.md

@@ -0,0 +1,97 @@
+# Custom Instructions for AX CLI
+
+**Project**: @defai.digital/ax-cli v1.1.0
+**Type**: cli
+**Language**: TypeScript
+**Stack**: React, Vitest, Zod, Commander, Ink, ESM, TypeScript
+
+Generated: 11/19/2025, 2:45:34 AM
+
+## Project Context
+
+- **Entry Point**: `dist/index.js`
+- **Package Manager**: npm
+- **Module System**: ESM
+- **CLI Tool**: This is a command-line interface application
+
+## Code Conventions
+
+### TypeScript
+- Use explicit type annotations for function parameters and returns
+- Prefer `const` and `let` over `var`
+- Use strict mode (strict type checking enabled)
+- **CRITICAL**: Always use `.js` extension in import statements (ESM requirement)
+  - Example: `import { foo } from "./bar.js"` (NOT "./bar" or "./bar.ts")
+
+### ES Modules
+- Use `import/export` syntax (not `require/module.exports`)
+- Top-level await is supported
+
+### Validation
+- Use **zod** for runtime validation
+- Validate all external inputs (API requests, file reads, user input)
+- Use `.safeParse()` for error handling
+
+## File Structure
+
+- **Source Code**: `src/`
+- **Tests**: `tests/`
+- **Tools**: `src/tools/`
+
+### Typical Structure
+- Commands: `src/commands/`
+- Utilities: `src/utils/`
+- Types: `src/types/`
+
+### Key Files
+- `package.json`: Node.js package configuration
+- `tsconfig.json`: TypeScript configuration
+- `vitest.config.ts`: Vitest test configuration
+- `.eslintrc.js`: ESLint configuration
+- `README.md`: Project documentation
+- `CLAUDE.md`: Claude-specific instructions
+
+## Development Workflow
+
+### Before Making Changes
+1. Read relevant files with `view_file` to understand current implementation
+2. Use `search` to find related code or patterns
+3. Check existing tests to understand expected behavior
+
+### Making Changes
+1. **NEVER** use `create_file` on existing files - use `str_replace_editor` instead
+2. Make focused, atomic changes
+3. Preserve existing code style and patterns
+4. Update related tests when modifying functionality
+
+### After Changes
+1. Run linter: `eslint . --ext .js,.jsx,.ts,.tsx`
+2. Run tests: `vitest run`
+3. Build: `tsc`
+
+## Testing Guidelines
+
+### Vitest
+- Use `describe`, `it`, `expect` for test structure
+- Place tests in `tests/` directory or `*.test.ts` files
+- Test edge cases: empty inputs, null/undefined, boundary conditions
+- Include Unicode and special character tests where relevant
+
+### Coverage Requirements
+- Aim for high test coverage (80%+ for new code)
+- Always test error paths and edge cases
+- Test both success and failure scenarios
+
+## Available Scripts
+
+- **Development**: `bun run src/index.ts`
+- **Build**: `tsc`
+- **Test**: `vitest run`
+- **Lint**: `eslint . --ext .js,.jsx,.ts,.tsx`
+
+### Quick Commands
+```bash
+npm run dev    # Start development
+npm test   # Run tests
+npm run build  # Build for production
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defai.digital/ax-cli",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Enterprise-Class AI Command Line Interface - Primary support for GLM (General Language Model) with multi-provider AI orchestration powered by AutomatosX.",
   "type": "module",
   "workspaces": [
@@ -16,6 +16,17 @@
   "bin": {
     "ax-cli": "dist/index.js"
   },
+  "files": [
+    "dist",
+    "packages/schemas/dist",
+    "packages/schemas/package.json",
+    ".ax-cli",
+    "LICENSE",
+    "README.md",
+    "automatosx.config.json",
+    "eslint.config.js",
+    "vitest.config.ts"
+  ],
   "scripts": {
     "build": "tsc",
     "build:bun": "bun run tsc",

package/packages/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)?
+
+**單一真相來源（SSOT）**：所有模組 (API / MCP / Usage) 共享同一套型別定義契約。
+
+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: 0.1.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/packages/schemas/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @ax-cli/schemas - Single Source of Truth Type System
+ *
+ * This package provides centralized Zod schemas, brand types, and enums
+ * for the entire ax-cli ecosystem.
+ *
+ * SECURITY: All exports are controlled. Internal helpers are not exposed.
+ *
+ * @packageDocumentation
+ */
+export { brand, unbrand, isBranded, createBrandFactory, type __brand, type Brand, type ExtractBrand, type ExtractBase, } from './public/core/brand-types.js';
+export { ApiResponseId, ToolCallId, ToolCallIdSchema, ModelId, ModelIdSchema, TenantId, ApiKeyId, MCPServerId, MCPServerIdSchema, UsageRecordId, PlanId, SessionId, RequestId, type ApiResponseId as ApiResponseIdType, type ToolCallId as ToolCallIdType, type ModelId as ModelIdType, type TenantId as TenantIdType, type ApiKeyId as ApiKeyIdType, type MCPServerId as MCPServerIdType, type UsageRecordId as UsageRecordIdType, type PlanId as PlanIdType, type SessionId as SessionIdType, type RequestId as RequestIdType, } from './public/core/id-types.js';
+export { MessageRoleEnum, FinishReasonEnum, TransportEnum, EditorCommandEnum, type MessageRole, type FinishReason, type Transport, type EditorCommand, } from './public/core/enums.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/schemas/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACL,KAAK,EACL,OAAO,EACP,SAAS,EACT,kBAAkB,EAClB,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,MAAM,EACN,SAAS,EACT,SAAS,EACT,KAAK,aAAa,IAAI,iBAAiB,EACvC,KAAK,UAAU,IAAI,cAAc,EACjC,KAAK,OAAO,IAAI,WAAW,EAC3B,KAAK,QAAQ,IAAI,YAAY,EAC7B,KAAK,QAAQ,IAAI,YAAY,EAC7B,KAAK,WAAW,IAAI,eAAe,EACnC,KAAK,aAAa,IAAI,iBAAiB,EACvC,KAAK,MAAM,IAAI,UAAU,EACzB,KAAK,SAAS,IAAI,aAAa,EAC/B,KAAK,SAAS,IAAI,aAAa,GAChC,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC"}

package/packages/schemas/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @ax-cli/schemas - Single Source of Truth Type System
+ *
+ * This package provides centralized Zod schemas, brand types, and enums
+ * for the entire ax-cli ecosystem.
+ *
+ * SECURITY: All exports are controlled. Internal helpers are not exposed.
+ *
+ * @packageDocumentation
+ */
+// Core brand type utilities
+export { brand, unbrand, isBranded, createBrandFactory, } from './public/core/brand-types.js';
+// ID Brand Types
+export { ApiResponseId, ToolCallId, ToolCallIdSchema, ModelId, ModelIdSchema, TenantId, ApiKeyId, MCPServerId, MCPServerIdSchema, UsageRecordId, PlanId, SessionId, RequestId, } from './public/core/id-types.js';
+// Centralized Enums
+export { MessageRoleEnum, FinishReasonEnum, TransportEnum, EditorCommandEnum, } from './public/core/enums.js';
+// Additional exports will be added as we implement them:
+// - Domain schemas (Usage, API, MCP)
+//# sourceMappingURL=index.js.map

package/packages/schemas/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4BAA4B;AAC5B,OAAO,EACL,KAAK,EACL,OAAO,EACP,SAAS,EACT,kBAAkB,GAKnB,MAAM,8BAA8B,CAAC;AAEtC,iBAAiB;AACjB,OAAO,EACL,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,MAAM,EACN,SAAS,EACT,SAAS,GAWV,MAAM,2BAA2B,CAAC;AAEnC,oBAAoB;AACpB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAKlB,MAAM,wBAAwB,CAAC;AAEhC,yDAAyD;AACzD,qCAAqC"}