@porchestra/cli 1.0.0

package/src/utils/errors.ts

@@ -0,0 +1,38 @@
+export class PorchestraError extends Error {
+  constructor(message: string, public code: string) {
+    super(message);
+    this.name = 'PorchestraError';
+  }
+}
+
+export class AuthenticationError extends PorchestraError {
+  constructor(message: string, public retryable = false) {
+    super(message, 'AUTH_ERROR');
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class NetworkError extends PorchestraError {
+  constructor(
+    message: string,
+    public statusCode?: number,
+    public retryable = true
+  ) {
+    super(message, 'NETWORK_ERROR');
+    this.name = 'NetworkError';
+  }
+}
+
+export class ValidationError extends PorchestraError {
+  constructor(message: string, public field?: string) {
+    super(message, 'VALIDATION_ERROR');
+    this.name = 'ValidationError';
+  }
+}
+
+export class FileSystemError extends PorchestraError {
+  constructor(message: string, public path: string) {
+    super(message, 'FS_ERROR');
+    this.name = 'FileSystemError';
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,11 @@
+import pc from 'picocolors';
+
+export const logger = {
+  info: (msg: string) => console.log(msg),
+  success: (msg: string) => console.log(pc.green(msg)),
+  error: (msg: string) => console.error(pc.red(msg)),
+  warn: (msg: string) => console.log(pc.yellow(msg)),
+  gray: (msg: string) => console.log(pc.gray(msg)),
+  bold: (msg: string) => console.log(pc.bold(msg)),
+  cyan: (msg: string) => console.log(pc.cyan(msg)),
+};

package/src/utils/path-utils.ts

@@ -0,0 +1,47 @@
+import path from 'path';
+import { promises as fs } from 'fs';
+
+export function normalizeFolderPath(folderPath: string): string {
+  let normalized = folderPath.replace(/^\//, '');
+  normalized = normalized.replace(/\/+/g, '/');
+  normalized = normalized
+    .split('/')
+    .map(segment => sanitizePathSegment(segment))
+    .join('/');
+  normalized = normalized.replace(/\/$/, '');
+  return normalized;
+}
+
+function sanitizePathSegment(segment: string): string {
+  return segment
+    .replace(/[^a-zA-Z0-9-_]/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-+/g, '-');
+}
+
+export function calculateOutputPath(
+  baseDir: string,
+  folderPath: string,
+  filename?: string
+): string {
+  const normalized = normalizeFolderPath(folderPath);
+  const fullPath = path.join(baseDir, normalized);
+  return filename ? path.join(fullPath, filename) : fullPath;
+}
+
+export function calculateAgentOutputPath(
+  baseDir: string,
+  folderPath: string,
+  agentName: string,
+  filename?: string
+): string {
+  const normalizedFolder = normalizeFolderPath(folderPath);
+  const normalizedAgent = sanitizePathSegment(agentName);
+  const fullPath = path.join(baseDir, normalizedFolder, normalizedAgent);
+  return filename ? path.join(fullPath, filename) : fullPath;
+}
+
+export async function ensureDirectory(filePath: string): Promise<void> {
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true });
+}

package/tests/unit/config-manager.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { ConfigManager } from '../../src/core/config/config-manager.js';
+
+describe('ConfigManager', () => {
+  let tempDir: string;
+  let configManager: ConfigManager;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'porchestra-test-'));
+    process.env.PORCHESTRA_CONFIG_DIR = tempDir;
+    configManager = new ConfigManager();
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+    delete process.env.PORCHESTRA_CONFIG_DIR;
+  });
+
+  it('should create default config when none exists', async () => {
+    const config = await configManager.load();
+    expect(config.version).toBe('1.0.0');
+    expect(config.trackedProjects).toEqual([]);
+    expect(config.api?.baseUrl).toBe('https://api.porchestra.io/v1');
+  });
+
+  it('should save and load config', async () => {
+    const config = await configManager.load();
+    config.auth = {
+      token: 'test-token',
+      tokenId: '550e8400-e29b-41d4-a716-446655440000',
+      expiresAt: '2025-12-31T23:59:59Z',
+      deviceName: 'Test Device'
+    };
+    
+    await configManager.save(config);
+    
+    // Create new manager to test loading from disk
+    const newManager = new ConfigManager();
+    const loaded = await newManager.load();
+    
+    expect(loaded.auth?.token).toBe('test-token');
+    expect(loaded.auth?.deviceName).toBe('Test Device');
+  });
+
+  it('should update config with updater function', async () => {
+    await configManager.load();
+    
+    await configManager.update((cfg) => ({
+      ...cfg,
+      api: {
+        ...cfg.api,
+        baseUrl: 'https://custom.api.com/v1'
+      }
+    }));
+    
+    const config = await configManager.get();
+    expect(config.api?.baseUrl).toBe('https://custom.api.com/v1');
+  });
+
+  it('should clear config', async () => {
+    const config = await configManager.load();
+    config.auth = { token: 'test' };
+    await configManager.save(config);
+    
+    await configManager.clear();
+    
+    // After clear, should return default config
+    const newConfig = await configManager.load();
+    expect(newConfig.auth).toBeUndefined();
+  });
+});

package/tests/unit/config-schema.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { CliConfigSchema, TrackedProjectSchema } from '../../src/core/config/config-schema.js';
+
+describe('config-schema', () => {
+  it('should validate a valid config', () => {
+    const validConfig = {
+      version: '1.0.0',
+      auth: {
+        token: 'test-token',
+        tokenId: '550e8400-e29b-41d4-a716-446655440000',
+        expiresAt: '2025-12-31T23:59:59Z',
+        deviceName: 'Test Device'
+      },
+      api: {
+        baseUrl: 'https://api.porchestra.io/v1',
+        skipTlsVerify: false
+      },
+      trackedProjects: [],
+      output: {
+        baseDir: './src/agents',
+        createIndexFiles: true
+      }
+    };
+
+    const result = CliConfigSchema.safeParse(validConfig);
+    expect(result.success).toBe(true);
+  });
+
+  it('should apply defaults for missing fields', () => {
+    const minimalConfig = {
+      version: '1.0.0'
+    };
+
+    const result = CliConfigSchema.parse(minimalConfig);
+    expect(result.api?.baseUrl).toBe('https://api.porchestra.io/v1');
+    expect(result.output?.baseDir).toBe('./src/agents');
+    expect(result.trackedProjects).toEqual([]);
+  });
+
+  it('should reject invalid version', () => {
+    const invalidConfig = {
+      version: '2.0.0'
+    };
+
+    const result = CliConfigSchema.safeParse(invalidConfig);
+    expect(result.success).toBe(false);
+  });
+
+  it('should validate tracked project schema', () => {
+    const validProject = {
+      projectId: '550e8400-e29b-41d4-a716-446655440000',
+      projectName: 'Test Project',
+      projectSlug: 'test-project',
+      selectedAt: '2025-01-30T12:00:00Z',
+      agents: []
+    };
+
+    const result = TrackedProjectSchema.safeParse(validProject);
+    expect(result.success).toBe(true);
+  });
+});

package/tests/unit/path-utils.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import {
+  normalizeFolderPath,
+  calculateOutputPath,
+} from '../../src/utils/path-utils.js';
+
+describe('path-utils', () => {
+  describe('normalizeFolderPath', () => {
+    it('should remove leading slash', () => {
+      expect(normalizeFolderPath('/main/x-agent/')).toBe('main/x-agent');
+    });
+
+    it('should handle paths without leading slash', () => {
+      expect(normalizeFolderPath('y-agent')).toBe('y-agent');
+    });
+
+    it('should replace multiple slashes', () => {
+      expect(normalizeFolderPath('//legacy//agents//')).toBe('/legacy/agents');
+    });
+
+    it('should sanitize special characters', () => {
+      expect(normalizeFolderPath('My Agent (v2)')).toBe('My-Agent-v2');
+    });
+
+    it('should handle empty path', () => {
+      expect(normalizeFolderPath('/')).toBe('');
+    });
+
+    it('should prevent directory traversal', () => {
+      expect(normalizeFolderPath('../malicious')).toBe('/malicious');
+    });
+  });
+
+  describe('calculateOutputPath', () => {
+    it('should calculate correct output path', () => {
+      const result = calculateOutputPath(
+        './src/agents',
+        'main/x-agent',
+        'tool-schemas.ts'
+      );
+      expect(result).toMatch(/src[\\/]agents[\\/]main[\\/]x-agent[\\/]tool-schemas\.ts/);
+    });
+
+    it('should handle empty folder path', () => {
+      const result = calculateOutputPath(
+        './src/agents',
+        '/',
+        'tool-schemas.ts'
+      );
+      expect(result).toMatch(/src[\\/]agents[\\/]tool-schemas\.ts$/);
+    });
+  });
+});

package/tests/unit/schema-generator.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { jsonSchemaToZod } from '../../src/core/generators/schema-generator.js';
+import { z } from 'zod';
+
+describe('schema-generator', () => {
+  it('should convert string schema', () => {
+    const schema = { type: 'string' };
+    const result = jsonSchemaToZod(schema);
+    expect(() => result.parse('hello')).not.toThrow();
+    expect(() => result.parse(123)).toThrow();
+  });
+
+  it('should convert number schema', () => {
+    const schema = { type: 'number' };
+    const result = jsonSchemaToZod(schema);
+    expect(() => result.parse(42)).not.toThrow();
+    expect(() => result.parse('hello')).toThrow();
+  });
+
+  it('should convert boolean schema', () => {
+    const schema = { type: 'boolean' };
+    const result = jsonSchemaToZod(schema);
+    expect(() => result.parse(true)).not.toThrow();
+    expect(() => result.parse('true')).toThrow();
+  });
+
+  it('should convert array schema', () => {
+    const schema = {
+      type: 'array',
+      items: { type: 'string' }
+    };
+    const result = jsonSchemaToZod(schema);
+    expect(() => result.parse(['a', 'b'])).not.toThrow();
+    expect(() => result.parse([1, 2])).toThrow();
+  });
+
+  it('should convert object schema', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' }
+      },
+      required: ['name']
+    };
+    const result = jsonSchemaToZod(schema);
+    expect(() => result.parse({ name: 'John' })).not.toThrow();
+    expect(() => result.parse({ age: 30 })).toThrow();
+  });
+
+  it('should handle enum strings', () => {
+    const schema = {
+      type: 'string',
+      enum: ['red', 'green', 'blue']
+    };
+    const result = jsonSchemaToZod(schema);
+    expect(() => result.parse('red')).not.toThrow();
+    expect(() => result.parse('yellow')).toThrow();
+  });
+
+  it('should handle nullable types', () => {
+    const schema = {
+      type: 'string',
+      nullable: true
+    };
+    const result = jsonSchemaToZod(schema);
+    expect(() => result.parse('hello')).not.toThrow();
+    expect(() => result.parse(null)).not.toThrow();
+  });
+
+  it('should handle min/max constraints', () => {
+    const schema = {
+      type: 'string',
+      minLength: 2,
+      maxLength: 10
+    };
+    const result = jsonSchemaToZod(schema);
+    expect(() => result.parse('hi')).not.toThrow();
+    expect(() => result.parse('a')).toThrow();
+    expect(() => result.parse('a'.repeat(20))).toThrow();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "paths": {
+      "@porchestra/core": ["../core/src/index.ts"],
+      "@porchestra/core/*": ["../core/src/*"]
+    },
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests", "../**/*"]
+}

package/tsup.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  target: 'node22',
+  platform: 'node',
+  bundle: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  minify: false,
+  outDir: 'dist',
+  // No banner - shebang is in bin/porchestra.js instead
+  external: [],
+  loader: {
+    '.hbs': 'text'
+  }
+});

package/vitest.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.{test,spec}.{js,ts}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        '**/*.d.ts',
+        '**/*.config.{js,ts}'
+      ]
+    }
+  }
+});