@porchestra/cli 1.0.0

package/src/core/generators/code-generator.ts

@@ -0,0 +1,329 @@
+import fs from 'fs/promises';
+import path from 'path';
+import Handlebars from 'handlebars';
+import { calculateAgentOutputPath } from '../../utils/path-utils.js';
+import { AgentToolsResponse } from '../../types/index.js';
+import { logger } from '../../utils/logger.js';
+
+interface GenerateOptions {
+  agent: AgentToolsResponse['agent'];
+  tools: AgentToolsResponse['tools'];
+  components: AgentToolsResponse['components'];
+  outputDir: string;
+  forceOverwrite: boolean;
+}
+
+interface ToolData {
+  name: string;
+  description: string;
+  parameters: object;
+  returns: object | null;
+  isBuiltin?: boolean;
+  builtinType?: string;
+}
+
+interface TemplateData {
+  agentName: string;
+  version: string;
+  generatedAt: string;
+  tools: ToolData[];
+  variableSchema: object | null;
+  inputSchema: object | null;
+  responseSchema: object | null;
+  responseJsonSchema: object;
+}
+
+// Register Handlebars helpers
+Handlebars.registerHelper('pascalCase', function(str: string) {
+  return str
+    .replace(/[-_\s](.)/g, (_, char) => char.toUpperCase())
+    .replace(/^(.)/, (_, char) => char.toUpperCase());
+});
+
+Handlebars.registerHelper('camelCase', function(str: string) {
+  return str
+    .replace(/[-_\s](.)/g, (_, char) => char.toUpperCase())
+    .replace(/^(.)/, (_, char) => char.toLowerCase());
+});
+
+Handlebars.registerHelper('zodType', function(schema: any) {
+  return jsonSchemaToZodType(schema);
+});
+
+Handlebars.registerHelper('json', function(value: any) {
+  return JSON.stringify(value ?? {}, null, 2);
+});
+
+function jsonSchemaToZodType(schema: any): string {
+  if (!schema) return 'z.any()';
+
+  switch (schema.type) {
+    case 'string': {
+      let zod = 'z.string()';
+      if (schema.minLength) zod += `.min(${schema.minLength})`;
+      if (schema.maxLength) zod += `.max(${schema.maxLength})`;
+      if (schema.pattern) zod += `.regex(/${schema.pattern}/)`;
+      if (schema.enum) zod = `z.enum([${schema.enum.map((e: string) => `'${e}'`).join(', ')}])`;
+      if (schema.nullable) zod += '.nullable()';
+      return zod;
+    }
+    case 'number':
+    case 'integer': {
+      let zod = schema.type === 'integer' ? 'z.number().int()' : 'z.number()';
+      if (schema.minimum !== undefined) zod += `.min(${schema.minimum})`;
+      if (schema.maximum !== undefined) zod += `.max(${schema.maximum})`;
+      if (schema.nullable) zod += '.nullable()';
+      return zod;
+    }
+    case 'boolean': {
+      let zod = 'z.boolean()';
+      if (schema.nullable) zod += '.nullable()';
+      return zod;
+    }
+    case 'array': {
+      const itemType = jsonSchemaToZodType(schema.items);
+      let zod = `z.array(${itemType})`;
+      if (schema.minItems) zod += `.min(${schema.minItems})`;
+      if (schema.maxItems) zod += `.max(${schema.maxItems})`;
+      if (schema.nullable) zod += '.nullable()';
+      return zod;
+    }
+    case 'object': {
+      if (!schema.properties) return 'z.record(z.any())';
+      
+      const required = new Set(schema.required || []);
+      const props = Object.entries(schema.properties).map(([key, prop]: [string, any]) => {
+        const propType = jsonSchemaToZodType(prop);
+        const isRequired = required.has(key);
+        const formattedKey = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+        return `  ${formattedKey}: ${isRequired ? propType : `${propType}.optional()`}`;
+      });
+      
+      let zod = `z.object({\n${props.join(',\n')}\n})`;
+      if (schema.additionalProperties === false) zod += '.strict()';
+      if (schema.nullable) zod += '.nullable()';
+      return zod;
+    }
+    default:
+      return 'z.any()';
+  }
+}
+
+export class CodeGenerator {
+  private schemasTemplate: Handlebars.TemplateDelegate;
+  private toolsTemplate: Handlebars.TemplateDelegate;
+  private indexTemplate: Handlebars.TemplateDelegate;
+
+  constructor() {
+    this.schemasTemplate = Handlebars.compile(schemasTemplateSource);
+    this.toolsTemplate = Handlebars.compile(toolsTemplateSource);
+    this.indexTemplate = Handlebars.compile(indexTemplateSource);
+  }
+
+  async generate(options: GenerateOptions): Promise<void> {
+    const { agent, tools, components, outputDir } = options;
+
+    await fs.mkdir(outputDir, { recursive: true });
+
+    const responseJsonSchema = (components?.responseSchema?.content as object) || {};
+
+    const templateData: TemplateData = {
+      agentName: agent?.name || 'Unknown Agent',
+      version: agent?.version || 'unknown',
+      generatedAt: new Date().toISOString(),
+      tools: (tools || [])
+        .filter(t => t && !t.isBuiltin && typeof t.name === 'string' && t.name.length > 0)
+        .map(t => ({
+          name: t.name,
+          description: t.description || '',
+          parameters: t.parameters || {},
+          returns: t.returns ?? null,
+          isBuiltin: t.isBuiltin,
+          builtinType: t.builtinType,
+        })),
+      variableSchema: (components?.variableSchema?.content as object) || null,
+      inputSchema: (components?.inputSchema?.content as object) || null,
+      responseSchema: (components?.responseSchema?.content as object) || null,
+      responseJsonSchema,
+    };
+
+    // Generate ast.json (always overwrite)
+    const astPath = path.join(outputDir, 'ast.json');
+    const astContent = JSON.stringify(components?.ast?.content ?? {}, null, 2);
+    await fs.writeFile(astPath, astContent, 'utf-8');
+
+    // Generate config.ts (always overwrite)
+    const configPath = path.join(outputDir, 'config.ts');
+    const configContent = `/**
+ * Auto-generated model config for ${templateData.agentName}
+ * Generated: ${templateData.generatedAt}
+ * Version: ${templateData.version}
+ * DO NOT MODIFY - This file is auto-generated by Porchestra CLI
+ */
+
+export const ModelConfig = ${JSON.stringify(components?.modelConfig?.content ?? {}, null, 2)} as const;
+`;
+    await fs.writeFile(configPath, configContent, 'utf-8');
+
+    // Generate schemas.ts (always overwrite)
+    const schemasPath = path.join(outputDir, 'schemas.ts');
+    const schemasContent = this.schemasTemplate(templateData);
+    await fs.writeFile(schemasPath, schemasContent, 'utf-8');
+
+    // Generate tools.ts (always overwrite)
+    const toolsPath = path.join(outputDir, 'tools.ts');
+    const toolsContent = this.toolsTemplate(templateData);
+    await fs.writeFile(toolsPath, toolsContent, 'utf-8');
+
+    // Generate index.ts (always overwrite)
+    const indexPath = path.join(outputDir, 'index.ts');
+    const indexContent = this.indexTemplate(templateData);
+    await fs.writeFile(indexPath, indexContent, 'utf-8');
+  }
+
+  calculateOutputPath(baseDir: string, folderPath: string, agentName: string): string {
+    return calculateAgentOutputPath(baseDir, folderPath, agentName);
+  }
+}
+
+// Template sources
+const schemasTemplateSource = `/**
+ * Auto-generated Zod schemas for {{agentName}}
+ * Generated: {{generatedAt}}
+ * Version: {{version}}
+ * DO NOT MODIFY - This file is auto-generated by Porchestra CLI
+ */
+
+import { z } from 'zod';
+
+// 1. System Prompt Variables
+export const VariableSchema = {{{zodType variableSchema}}};
+export type AgentVariables = z.infer<typeof VariableSchema>;
+
+// 2. User Input
+export const InputSchema = {{{zodType inputSchema}}};
+export type AgentInput = z.infer<typeof InputSchema>;
+
+// 3. Model Response
+export const ResponseSchema = {{{zodType responseSchema}}};
+export type AgentResponse = z.infer<typeof ResponseSchema>;
+
+// 4. Raw JSON Schema (for LLM Provider 'response_format')
+export const ResponseJsonSchema = {{{json responseJsonSchema}}} as const;
+`;
+
+const toolsTemplateSource = `/**
+ * Auto-generated tools for {{agentName}}
+ * Generated: {{generatedAt}}
+ * Version: {{version}}
+ * DO NOT MODIFY - This file is auto-generated by Porchestra CLI
+ */
+
+import { z } from 'zod';
+
+{{#each tools}}
+// Schema for {{name}}
+export const {{pascalCase name}}Params = {{{zodType parameters}}};
+export type {{pascalCase name}}ParamsType = z.infer<typeof {{pascalCase name}}Params>;
+
+{{/each}}
+// The Interface the user MUST implement
+export interface ToolImplementation {
+{{#each tools}}
+  {{camelCase name}}: (args: {{pascalCase name}}ParamsType) => Promise<unknown>;
+{{/each}}
+}
+
+// Raw Tool Definitions for provider SDKs
+export const ToolDefinitions = [
+{{#each tools}}
+  {
+    name: '{{name}}',
+    description: {{{json description}}},
+    parameters: {{{json parameters}}},
+  },
+{{/each}}
+] as const;
+
+// Dispatcher with validation
+export async function dispatch(
+  name: string,
+  args: unknown,
+  impl: ToolImplementation
+): Promise<unknown> {
+  switch (name) {
+    {{#each tools}}
+    case '{{name}}':
+      return await impl.{{camelCase name}}({{pascalCase name}}Params.parse(args));
+    {{/each}}
+    default:
+      throw new Error(\`Unknown tool: \${name}\`);
+  }
+}
+`;
+
+const indexTemplateSource = `/**
+ * Auto-generated Agent class for {{agentName}}
+ * Generated: {{generatedAt}}
+ * Version: {{version}}
+ * DO NOT MODIFY - This file is auto-generated by Porchestra CLI
+ */
+
+import { PorchestraRuntime } from '@porchestra/core';
+import rawAst from './ast.json';
+import { ModelConfig } from './config.js';
+import * as Schemas from './schemas.js';
+import * as Tools from './tools.js';
+
+export class {{pascalCase agentName}}Agent {
+  /**
+   * @param tools - The implementation of the tool logic. Required if the agent uses tools.
+   */
+  constructor(private readonly tools?: Tools.ToolImplementation) {}
+
+  /**
+   * Renders the System Prompt.
+   * Throws ZodError if variables are invalid.
+   */
+  public renderPrompt(variables: Schemas.AgentVariables): string {
+    const safeVars = Schemas.VariableSchema.parse(variables);
+    return PorchestraRuntime.render(rawAst as any, safeVars);
+  }
+
+  /**
+   * Routes an LLM Tool Call to your implementation.
+   * Validates arguments automatically.
+   */
+  public async handleTool(name: string, args: unknown): Promise<unknown> {
+    if (!this.tools) {
+      throw new Error('No tool implementation provided to Agent constructor.');
+    }
+    return Tools.dispatch(name, args, this.tools);
+  }
+
+  /** Validates User Input (e.g. from API Request) */
+  public static validateInput(data: unknown): Schemas.AgentInput {
+    return Schemas.InputSchema.parse(data);
+  }
+
+  /** Validates LLM Output (Post-generation check) */
+  public static validateResponse(data: unknown): Schemas.AgentResponse {
+    return Schemas.ResponseSchema.parse(data);
+  }
+
+  /** Get Provider Configuration */
+  public static get config() {
+    return ModelConfig;
+  }
+
+  /** Get Tool Definitions for the LLM Provider */
+  public static get toolDefinitions() {
+    return Tools.ToolDefinitions;
+  }
+
+  /** Get JSON Schema for Structured Outputs */
+  public static get responseFormat() {
+    return Schemas.ResponseJsonSchema;
+  }
+}
+`;

package/src/core/generators/schema-generator.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+
+export function jsonSchemaToZod(schema: any): z.ZodTypeAny {
+  switch (schema.type) {
+    case 'string': {
+      let stringSchema = z.string();
+      if (schema.minLength) stringSchema = stringSchema.min(schema.minLength);
+      if (schema.maxLength) stringSchema = stringSchema.max(schema.maxLength);
+      if (schema.pattern) stringSchema = stringSchema.regex(new RegExp(schema.pattern));
+      if (schema.enum) return z.enum(schema.enum);
+      return schema.nullable ? stringSchema.nullable() : stringSchema;
+    }
+
+    case 'number':
+    case 'integer': {
+      let numberSchema = schema.type === 'integer' ? z.number().int() : z.number();
+      if (schema.minimum !== undefined) numberSchema = numberSchema.min(schema.minimum);
+      if (schema.maximum !== undefined) numberSchema = numberSchema.max(schema.maximum);
+      return schema.nullable ? numberSchema.nullable() : numberSchema;
+    }
+
+    case 'boolean': {
+      const boolSchema = z.boolean();
+      return schema.nullable ? boolSchema.nullable() : boolSchema;
+    }
+
+    case 'array': {
+      const itemSchema = jsonSchemaToZod(schema.items);
+      let arraySchema = z.array(itemSchema);
+      if (schema.minItems) arraySchema = arraySchema.min(schema.minItems);
+      if (schema.maxItems) arraySchema = arraySchema.max(schema.maxItems);
+      return schema.nullable ? arraySchema.nullable() : arraySchema;
+    }
+
+    case 'object': {
+      const shape: Record<string, z.ZodTypeAny> = {};
+      const required = new Set(schema.required || []);
+      
+      for (const [key, propSchema] of Object.entries(schema.properties || {})) {
+        let fieldSchema = jsonSchemaToZod(propSchema as any);
+        if (!required.has(key)) {
+          fieldSchema = fieldSchema.optional();
+        }
+        shape[key] = fieldSchema;
+      }
+      
+      let objectSchema = z.object(shape);
+      // Note: strict() is not applied to keep the schema flexible
+      return schema.nullable ? objectSchema.nullable() : objectSchema;
+    }
+
+    default:
+      if (schema.anyOf || schema.oneOf) {
+        const schemas = (schema.anyOf || schema.oneOf).map(jsonSchemaToZod);
+        return z.union([schemas[0], schemas[1], ...schemas.slice(2)]);
+      }
+      return z.any();
+  }
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { ConfigManager } from './core/config/config-manager.js';
+import { AuthService } from './core/auth/auth-service.js';
+import { TokenManager } from './core/auth/token-manager.js';
+import { ApiClient } from './core/api/client.js';
+import { CodeGenerator } from './core/generators/code-generator.js';
+import { createLoginCommand } from './commands/login.js';
+import { createLogoutCommand } from './commands/logout.js';
+import { createWhoamiCommand } from './commands/whoami.js';
+import { createExploreCommand } from './commands/explore.js';
+import { createPullCommand } from './commands/pull.js';
+import { createConfigCommand } from './commands/config.js';
+import { createStatusCommand } from './commands/status.js';
+import { createAgentsCommand } from './commands/agents.js';
+import { PorchestraError } from './utils/errors.js';
+
+const packageJson = { version: '1.0.0' };
+
+// Global error handlers
+process.on('unhandledRejection', (error) => {
+  console.error(pc.red('\n✗ Unexpected error:'));
+  console.error(error);
+  process.exit(1);
+});
+
+process.on('uncaughtException', (error) => {
+  console.error(pc.red('\n✗ Fatal error:'));
+  console.error(error);
+  process.exit(1);
+});
+
+async function main() {
+  // Initialize core services
+  const configManager = new ConfigManager();
+  const authService = new AuthService(configManager);
+  // TokenManager is available for future token operations
+  new TokenManager(configManager);
+  const apiClient = new ApiClient(configManager);
+  const codeGenerator = new CodeGenerator();
+
+  // Check token expiration and refresh if needed
+  await authService.checkAndRefreshTokenIfNeeded();
+
+  // Create CLI program
+  const program = new Command()
+    .name('porchestra')
+    .description('CLI for Porchestra - Generate LLM tool handlers')
+    .version(packageJson.version)
+    .configureOutput({
+      writeErr: (str) => process.stderr.write(str),
+      outputError: (str, write) => write(pc.red(str))
+    });
+
+  // Add global options
+  program
+    .option('--api-url <url>', 'Override API URL')
+    .option('--config-dir <dir>', 'Override config directory');
+
+  // Register commands
+  program.addCommand(createLoginCommand(configManager, authService));
+  program.addCommand(createLogoutCommand(configManager, authService));
+  program.addCommand(createWhoamiCommand(configManager, authService));
+  program.addCommand(createExploreCommand(configManager, apiClient));
+  program.addCommand(createPullCommand(configManager, apiClient, codeGenerator));
+  program.addCommand(createConfigCommand(configManager));
+  program.addCommand(createStatusCommand(configManager));
+  program.addCommand(createAgentsCommand(configManager));
+
+  // Parse arguments
+  await program.parseAsync(process.argv);
+}
+
+main().catch((error) => {
+  if (error instanceof PorchestraError) {
+    console.error(pc.red(`\n✗ ${error.message}`));
+    if (process.env.DEBUG) {
+      console.error(pc.gray(error.stack));
+    }
+  } else {
+    console.error(pc.red(`\n✗ Unexpected error: ${(error as Error).message}`));
+  }
+  process.exit(1);
+});

package/src/types/index.ts

@@ -0,0 +1,214 @@
+// Authentication Types
+export interface ApiResponse<T> {
+  statusCode: number;
+  message: string;
+  data: T;
+  timestamp: string;
+  path: string;
+}
+
+export interface CliTokenRequest {
+  deviceName?: string;
+  deviceInfo?: {
+    os: string;
+    version: string;
+    cliVersion: string;
+  };
+}
+
+export interface CliTokenResponse {
+  token: string;
+  tokenId: string;
+  expiresAt: string;
+  issuedAt: string;
+  deviceName: string;
+}
+
+export interface CliTokenRefreshRequest {
+  tokenId: string;
+  currentToken: string;
+}
+
+export interface CliTokenRefreshResponse {
+  token: string;
+  tokenId: string;
+  expiresAt: string;
+  refreshedAt: string;
+}
+
+export interface CliTokenRevokeRequest {
+  revokeAll?: boolean;
+}
+
+export interface CliTokenRevokeResponse {
+  revoked: boolean;
+  revokedCount?: number;
+  revokedAt: string;
+}
+
+export interface CliTokensListResponse {
+  tokens: Array<{
+    tokenId: string;
+    deviceName: string;
+    deviceInfo: {
+      os: string;
+      version: string;
+      cliVersion: string;
+    };
+    issuedAt: string;
+    expiresAt: string;
+    lastUsedAt: string | null;
+    lastUsedIp: string | null;
+    isCurrent: boolean;
+  }>;
+  total: number;
+  maxAllowed: number;
+}
+
+// Project Types
+export interface ProjectsBriefResponse {
+  projects: Array<{
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    agentCount: number;
+    environments: Array<{
+      name: 'PRODUCTION' | 'STAGING' | 'DEVELOPMENT';
+      hasPublishedVersion: boolean;
+    }>;
+    lastModifiedAt: string;
+  }>;
+  total: number;
+}
+
+export interface AgentsListQuery {
+  environment?: 'PRODUCTION' | 'STAGING' | 'DEVELOPMENT';
+}
+
+export interface AgentsListResponse {
+  project: {
+    id: string;
+    name: string;
+    slug: string;
+  };
+  environment: 'PRODUCTION' | 'STAGING' | 'DEVELOPMENT';
+  agents: Array<{
+    id: string;
+    name: string;
+    slug: string;
+    folderPath: string;
+    description: string | null;
+    version: string;
+    toolCount: number;
+    lastUpdatedAt: string;
+    isPublished: boolean;
+  }>;
+  versionResolution: {
+    source: 'PRODUCTION' | 'STAGING' | 'DEVELOPMENT';
+    note: string;
+  };
+}
+
+export interface AgentDetailQuery {
+  environment?: 'PRODUCTION' | 'STAGING' | 'DEVELOPMENT';
+}
+
+export interface AgentDetailResponse {
+  agent: {
+    id: string;
+    name: string;
+    slug: string;
+    folderPath: string;
+    description: string | null;
+    instructions: string | null;
+    model: string;
+    temperature: number;
+    version: string;
+    versionId: string;
+    environment: 'PRODUCTION' | 'STAGING' | 'DEVELOPMENT';
+    createdAt: string;
+    updatedAt: string;
+    publishedAt: string | null;
+  };
+  versionResolution: {
+    source: 'PRODUCTION' | 'STAGING' | 'DEVELOPMENT';
+    note: string;
+  };
+}
+
+// Tools Types
+export interface AgentToolsQuery {
+  environment?: 'PRODUCTION' | 'STAGING' | 'DEVELOPMENT';
+}
+
+export interface AgentToolsResponse {
+  agent: {
+    id: string;
+    name: string;
+    folderPath: string;
+    version: string;
+  };
+  tools?: Array<{
+    id: string;
+    name: string;
+    description: string;
+    parameters: object;
+    returns: object | null;
+    isBuiltin: boolean;
+    builtinType?: string;
+  }>;
+  // Legacy/alternate API shape where tools are provided under `toolset`
+  toolset?: Array<{
+    name: string;
+    description?: string;
+    parameters?: object;
+    returns?: object | null;
+    isBuiltin?: boolean;
+    builtinType?: string;
+    id?: string;
+  }>;
+  components: {
+    ast: { id: string; content: unknown } | null;
+    modelConfig: { id: string; content: unknown } | null;
+    inputSchema: { id: string; content: unknown } | null;
+    variableSchema: { id: string; content: unknown } | null;
+    responseSchema: { id: string; content: unknown } | null;
+    toolConfig: { id: string; content: unknown } | null;
+  };
+  total: number;
+}
+
+// User Types
+export interface UserInfo {
+  email: string;
+  name: string;
+  organization: string;
+}
+
+// CLI Config Types
+export interface CliConfigResponse {
+  api: {
+    version: string;
+    minCliVersion: string;
+    recommendedCliVersion: string;
+    deprecatedCliVersions: string[];
+  };
+  features: {
+    codeGeneration: boolean;
+    multiAgent: boolean;
+    onPremise: boolean;
+    customPaths: boolean;
+  };
+  limits: {
+    maxTokensPerUser: number;
+    tokenExpiryDays: number;
+    exportCacheHours: number;
+    maxToolsPerAgent: number;
+  };
+  endpoints: {
+    webApp: string;
+    documentation: string;
+    support: string;
+  };
+}

package/src/utils/date.ts

@@ -0,0 +1,23 @@
+export function formatDistanceToNow(date: Date): string {
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffSecs = Math.floor(diffMs / 1000);
+  const diffMins = Math.floor(diffSecs / 60);
+  const diffHours = Math.floor(diffMins / 60);
+  const diffDays = Math.floor(diffHours / 24);
+
+  if (diffSecs < 60) return 'just now';
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 30) return `${diffDays}d ago`;
+  return date.toISOString().split('T')[0];
+}
+
+export function formatDate(dateStr: string): string {
+  const date = new Date(dateStr);
+  return date.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  });
+}