newo 1.9.1 → 2.0.0

package/dist/types.d.ts

@@ -176,7 +176,6 @@ export interface CliArgs {
 export interface FlowsYamlSkill {
     idn: string;
     title: string;
-    prompt_script: string;
     runner_type: string;
     model: ModelConfig;
     parameters: Array<{

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "newo",
-  "version": "1.9.1",
-  "description": "NEWO CLI: comprehensive sync for AI Agent skills, customer attributes, conversations, and metadata between NEWO platform and local files. Multi-customer workspaces, conversation history extraction, complete change tracking, Git-first workflows.",
+  "version": "2.0.0",
+  "description": "NEWO CLI: Professional command-line tool with modular architecture for NEWO AI Agent development. Features IDN-based file management, real-time progress tracking, intelligent sync operations, and comprehensive multi-customer support.",
   "type": "module",
   "bin": {
     "newo": "dist/cli.js"

package/src/cli/commands/conversations.ts

@@ -0,0 +1,47 @@
+/**
+ * Conversations command handler
+ */
+import { makeClient } from '../../api.js';
+import { pullConversations } from '../../sync.js';
+import { getValidAccessToken } from '../../auth.js';
+import { selectSingleCustomer } from '../customer-selection.js';
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+
+export async function handleConversationsCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean
+): Promise<void> {
+  const { selectedCustomer, allCustomers, isMultiCustomer } = selectSingleCustomer(
+    customerConfig,
+    args.customer as string | undefined
+  );
+
+  // Parse conversation-specific options - load all data by default
+  const conversationOptions = {
+    includeAll: true, // Always include all data for conversations
+    maxPersonas: undefined, // No limit on personas
+    maxActsPerPersona: undefined // No limit on acts per persona
+  };
+
+  if (selectedCustomer) {
+    // Single customer conversations
+    const accessToken = await getValidAccessToken(selectedCustomer);
+    const client = await makeClient(verbose, accessToken);
+    console.log(`💬 Pulling conversations for customer: ${selectedCustomer.idn} (all data)`);
+    await pullConversations(client, selectedCustomer, conversationOptions, verbose);
+    console.log(`✅ Conversations saved to newo_customers/${selectedCustomer.idn}/conversations.yaml`);
+  } else if (isMultiCustomer) {
+    // Multi-customer conversations
+    if (verbose) console.log(`💬 No default customer specified, pulling conversations from all ${allCustomers.length} customers`);
+    console.log(`💬 Pulling conversations from ${allCustomers.length} customers (all data)...`);
+
+    for (const customer of allCustomers) {
+      console.log(`\n💬 Pulling conversations for customer: ${customer.idn}`);
+      const accessToken = await getValidAccessToken(customer);
+      const client = await makeClient(verbose, accessToken);
+      await pullConversations(client, customer, conversationOptions, verbose);
+    }
+    console.log(`\n✅ Conversations pull completed for all ${allCustomers.length} customers`);
+  }
+}

package/src/cli/commands/help.ts

@@ -0,0 +1,50 @@
+/**
+ * Help command handler
+ */
+
+export function handleHelpCommand(): void {
+  console.log(`NEWO CLI - Multi-Customer Support
+Usage:
+  newo pull [--customer <idn>]                  # download projects -> ./newo_customers/<idn>/projects/
+  newo push [--customer <idn>]                  # upload modified *.guidance/*.jinja back to NEWO
+  newo status [--customer <idn>]                # show modified files
+  newo conversations [--customer <idn>] [--all] # download user conversations -> ./newo_customers/<idn>/conversations.yaml
+  newo list-customers                           # list available customers
+  newo meta [--customer <idn>]                  # get project metadata (debug)
+  newo import-akb <file> <persona_id> [--customer <idn>]  # import AKB articles from file
+
+Flags:
+  --customer <idn>             # specify customer (if not set, uses default or interactive selection)
+  --all                        # include all available data (for conversations: all personas and acts)
+  --force, -f                  # force overwrite without prompting (for pull command)
+  --verbose, -v                # enable detailed logging
+
+Environment Variables:
+  NEWO_BASE_URL                                 # NEWO API base URL (default: https://app.newo.ai)
+  NEWO_CUSTOMER_<IDN>_API_KEY                   # API key for customer <IDN>
+  NEWO_CUSTOMER_<IDN>_PROJECT_ID               # Optional: specific project ID for customer
+  NEWO_DEFAULT_CUSTOMER                        # Optional: default customer to use
+
+Multi-Customer Examples:
+  # Configure customers in .env:
+  NEWO_CUSTOMER_acme_API_KEY=your_acme_api_key
+  NEWO_CUSTOMER_globex_API_KEY=your_globex_api_key
+  NEWO_DEFAULT_CUSTOMER=acme
+
+  # Commands:
+  newo pull                                    # Pull from all customers (if no default set)
+  newo pull --customer acme                    # Pull projects for Acme only
+  newo status                                  # Status for all customers (if no default set)
+  newo push                                    # Interactive selection for multiple customers
+  newo push --customer globex                  # Push changes for Globex only
+
+File Structure:
+  newo_customers/
+  ├── acme/
+  │   └── projects/
+  │       └── project1/
+  └── globex/
+      └── projects/
+          └── project2/
+`);
+}

package/src/cli/commands/import-akb.ts

@@ -0,0 +1,71 @@
+/**
+ * Import AKB command handler
+ */
+import path from 'path';
+import { makeClient, importAkbArticle } from '../../api.js';
+import { parseAkbFile, prepareArticlesForImport } from '../../akb.js';
+import { getValidAccessToken } from '../../auth.js';
+import { requireSingleCustomer } from '../customer-selection.js';
+import type { MultiCustomerConfig, CliArgs, NewoApiError } from '../../types.js';
+
+export async function handleImportAkbCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean
+): Promise<void> {
+  const selectedCustomer = requireSingleCustomer(customerConfig, args.customer as string | undefined);
+
+  const akbFile = args._[1];
+  const personaId = args._[2];
+
+  if (!akbFile || !personaId) {
+    console.error('Usage: newo import-akb <file> <persona_id>');
+    console.error('Example: newo import-akb akb.txt da4550db-2b95-4500-91ff-fb4b60fe7be9');
+    process.exit(1);
+  }
+
+  const filePath = path.resolve(akbFile as string);
+  const accessToken = await getValidAccessToken(selectedCustomer);
+  const client = await makeClient(verbose, accessToken);
+
+  try {
+    if (verbose) console.log(`📖 Parsing AKB file: ${filePath}`);
+    const articles = await parseAkbFile(filePath);
+    console.log(`✓ Parsed ${articles.length} articles from ${akbFile}`);
+
+    if (verbose) console.log(`🔧 Preparing articles for persona: ${personaId}`);
+    const preparedArticles = prepareArticlesForImport(articles, personaId as string);
+
+    let successCount = 0;
+    let errorCount = 0;
+
+    console.log(`📤 Importing ${preparedArticles.length} articles...`);
+
+    for (const [index, article] of preparedArticles.entries()) {
+      try {
+        if (verbose) {
+          console.log(`  [${index + 1}/${preparedArticles.length}] Importing ${article.topic_name}...`);
+        }
+        await importAkbArticle(client, article);
+        successCount++;
+        if (!verbose) process.stdout.write('.');
+      } catch (error: unknown) {
+        errorCount++;
+        const errorMessage = error instanceof Error && 'response' in error
+          ? (error as NewoApiError)?.response?.data
+          : error instanceof Error
+          ? error.message
+          : String(error);
+        console.error(`\n❌ Failed to import ${article.topic_name}:`, errorMessage);
+      }
+    }
+
+    if (!verbose) console.log(''); // new line after dots
+    console.log(`✅ Import complete: ${successCount} successful, ${errorCount} failed`);
+
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error('❌ AKB import failed:', message);
+    process.exit(1);
+  }
+}

package/src/cli/commands/list-customers.ts

@@ -0,0 +1,14 @@
+/**
+ * List customers command handler
+ */
+import { listCustomers } from '../../customerAsync.js';
+import type { MultiCustomerConfig } from '../../types.js';
+
+export function handleListCustomersCommand(customerConfig: MultiCustomerConfig): void {
+  const customers = listCustomers(customerConfig);
+  console.log('Available customers:');
+  for (const customerIdn of customers) {
+    const isDefault = customerConfig.defaultCustomer === customerIdn;
+    console.log(`  ${customerIdn}${isDefault ? ' (default)' : ''}`);
+  }
+}

package/src/cli/commands/meta.ts

@@ -0,0 +1,26 @@
+/**
+ * Meta command handler - get project metadata
+ */
+import { makeClient, getProjectMeta } from '../../api.js';
+import { getValidAccessToken } from '../../auth.js';
+import { requireSingleCustomer } from '../customer-selection.js';
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+
+export async function handleMetaCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean
+): Promise<void> {
+  const selectedCustomer = requireSingleCustomer(customerConfig, args.customer as string | undefined);
+
+  if (!selectedCustomer.projectId) {
+    console.error(`No project ID configured for customer ${selectedCustomer.idn}`);
+    console.error(`Set NEWO_CUSTOMER_${selectedCustomer.idn.toUpperCase()}_PROJECT_ID in your .env file`);
+    process.exit(1);
+  }
+
+  const accessToken = await getValidAccessToken(selectedCustomer);
+  const client = await makeClient(verbose, accessToken);
+  const meta = await getProjectMeta(client, selectedCustomer.projectId);
+  console.log(JSON.stringify(meta, null, 2));
+}

package/src/cli/commands/pull-attributes.ts

@@ -0,0 +1,23 @@
+/**
+ * Pull attributes command handler
+ */
+import { makeClient } from '../../api.js';
+import { saveCustomerAttributes } from '../../sync.js';
+import { getValidAccessToken } from '../../auth.js';
+import { requireSingleCustomer } from '../customer-selection.js';
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+
+export async function handlePullAttributesCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean
+): Promise<void> {
+  const selectedCustomer = requireSingleCustomer(customerConfig, args.customer as string | undefined);
+
+  const accessToken = await getValidAccessToken(selectedCustomer);
+  const client = await makeClient(verbose, accessToken);
+
+  console.log(`🔍 Fetching customer attributes for ${selectedCustomer.idn}...`);
+  await saveCustomerAttributes(client, selectedCustomer, verbose);
+  console.log(`✅ Customer attributes saved to newo_customers/${selectedCustomer.idn}/attributes.yaml`);
+}

package/src/cli/commands/pull.ts

@@ -0,0 +1,43 @@
+/**
+ * Pull command handler
+ */
+import { makeClient } from '../../api.js';
+import { pullAll } from '../../sync.js';
+import { getValidAccessToken } from '../../auth.js';
+import { selectSingleCustomer } from '../customer-selection.js';
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+
+export async function handlePullCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean
+): Promise<void> {
+  const { selectedCustomer, allCustomers, isMultiCustomer } = selectSingleCustomer(
+    customerConfig,
+    args.customer as string | undefined
+  );
+
+  // Check for force/silent overwrite flag
+  const silentOverwrite = Boolean(args.force || args.f);
+
+  if (selectedCustomer) {
+    // Single customer pull
+    const accessToken = await getValidAccessToken(selectedCustomer);
+    const client = await makeClient(verbose, accessToken);
+    const projectId = selectedCustomer.projectId || null;
+    await pullAll(client, selectedCustomer, projectId, verbose, silentOverwrite);
+  } else if (isMultiCustomer) {
+    // Multi-customer pull
+    if (verbose) console.log(`📥 No default customer specified, pulling from all ${allCustomers.length} customers`);
+    console.log(`🔄 Pulling from ${allCustomers.length} customers...`);
+
+    for (const customer of allCustomers) {
+      console.log(`\n📥 Pulling from customer: ${customer.idn}`);
+      const accessToken = await getValidAccessToken(customer);
+      const client = await makeClient(verbose, accessToken);
+      const projectId = customer.projectId || null;
+      await pullAll(client, customer, projectId, verbose, silentOverwrite);
+    }
+    console.log(`\n✅ Pull completed for all ${allCustomers.length} customers`);
+  }
+}

package/src/cli/commands/push.ts

@@ -0,0 +1,47 @@
+/**
+ * Push command handler
+ */
+import { makeClient } from '../../api.js';
+import { pushChanged } from '../../sync.js';
+import { getValidAccessToken } from '../../auth.js';
+import { selectSingleCustomer, interactiveCustomerSelection } from '../customer-selection.js';
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+
+export async function handlePushCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean
+): Promise<void> {
+  const { selectedCustomer, allCustomers, isMultiCustomer } = selectSingleCustomer(
+    customerConfig,
+    args.customer as string | undefined
+  );
+
+  if (selectedCustomer) {
+    // Single customer push
+    const accessToken = await getValidAccessToken(selectedCustomer);
+    const client = await makeClient(verbose, accessToken);
+    await pushChanged(client, selectedCustomer, verbose);
+  } else if (isMultiCustomer) {
+    // Multiple customers exist with no default, ask user
+    const customersToProcess = await interactiveCustomerSelection(allCustomers);
+
+    if (customersToProcess.length === 1) {
+      // Single customer selected
+      const customer = customersToProcess[0]!;
+      const accessToken = await getValidAccessToken(customer);
+      const client = await makeClient(verbose, accessToken);
+      await pushChanged(client, customer, verbose);
+    } else {
+      // Multi-customer push (user selected "All customers")
+      console.log(`🔄 Pushing to ${customersToProcess.length} customers...`);
+      for (const customer of customersToProcess) {
+        console.log(`\n📤 Pushing for customer: ${customer.idn}`);
+        const accessToken = await getValidAccessToken(customer);
+        const client = await makeClient(verbose, accessToken);
+        await pushChanged(client, customer, verbose);
+      }
+      console.log(`\n✅ Push completed for all ${customersToProcess.length} customers`);
+    }
+  }
+}

package/src/cli/commands/status.ts

@@ -0,0 +1,30 @@
+/**
+ * Status command handler
+ */
+import { status } from '../../sync.js';
+import { selectSingleCustomer } from '../customer-selection.js';
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+
+export async function handleStatusCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean
+): Promise<void> {
+  const { selectedCustomer, allCustomers, isMultiCustomer } = selectSingleCustomer(
+    customerConfig,
+    args.customer as string | undefined
+  );
+
+  if (selectedCustomer) {
+    // Single customer status
+    await status(selectedCustomer, verbose);
+  } else if (isMultiCustomer) {
+    // Multi-customer status
+    console.log(`🔄 Checking status for ${allCustomers.length} customers...`);
+    for (const customer of allCustomers) {
+      console.log(`\n📋 Status for customer: ${customer.idn}`);
+      await status(customer, verbose);
+    }
+    console.log(`\n✅ Status check completed for all ${allCustomers.length} customers`);
+  }
+}

package/src/cli/customer-selection.ts

@@ -0,0 +1,135 @@
+/**
+ * Customer selection and management utilities for CLI commands
+ */
+import {
+  parseCustomerConfigAsync,
+  listCustomers,
+  getCustomer,
+  getDefaultCustomer,
+  tryGetDefaultCustomer,
+  getAllCustomers,
+  validateCustomerConfig
+} from '../customerAsync.js';
+import { logCliError } from './errors.js';
+import type { CustomerConfig, MultiCustomerConfig } from '../types.js';
+
+export interface CustomerSelectionResult {
+  selectedCustomer: CustomerConfig | null;
+  allCustomers: CustomerConfig[];
+  isMultiCustomer: boolean;
+}
+
+/**
+ * Parse and validate customer configuration
+ */
+export async function parseAndValidateCustomerConfig(env: any, verbose: boolean): Promise<MultiCustomerConfig> {
+  try {
+    const customerConfig = await parseCustomerConfigAsync(env, verbose);
+    validateCustomerConfig(customerConfig);
+    return customerConfig;
+  } catch (error: unknown) {
+    logCliError('error', 'Failed to parse customer configuration');
+    if (error instanceof Error) {
+      logCliError('error', error.message);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle customer selection for commands that support single customer operations
+ */
+export function selectSingleCustomer(
+  customerConfig: MultiCustomerConfig,
+  customerArg?: string
+): CustomerSelectionResult {
+  let selectedCustomer: CustomerConfig | null = null;
+  let allCustomers: CustomerConfig[] = [];
+
+  if (customerArg) {
+    const customer = getCustomer(customerConfig, customerArg);
+    if (!customer) {
+      console.error(`Unknown customer: ${customerArg}`);
+      console.error(`Available customers: ${listCustomers(customerConfig).join(', ')}`);
+      process.exit(1);
+    }
+    selectedCustomer = customer;
+  } else {
+    // Try to get default, fall back to all customers
+    selectedCustomer = tryGetDefaultCustomer(customerConfig);
+    if (!selectedCustomer) {
+      allCustomers = getAllCustomers(customerConfig);
+    }
+  }
+
+  return {
+    selectedCustomer,
+    allCustomers,
+    isMultiCustomer: allCustomers.length > 0
+  };
+}
+
+/**
+ * Handle customer selection for commands that require exactly one customer
+ */
+export function requireSingleCustomer(
+  customerConfig: MultiCustomerConfig,
+  customerArg?: string
+): CustomerConfig {
+  if (customerArg) {
+    const customer = getCustomer(customerConfig, customerArg);
+    if (!customer) {
+      console.error(`Unknown customer: ${customerArg}`);
+      console.error(`Available customers: ${listCustomers(customerConfig).join(', ')}`);
+      process.exit(1);
+    }
+    return customer;
+  } else {
+    try {
+      return getDefaultCustomer(customerConfig);
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(message);
+      process.exit(1);
+    }
+  }
+}
+
+/**
+ * Interactive customer selection for commands like push
+ */
+export async function interactiveCustomerSelection(allCustomers: CustomerConfig[]): Promise<CustomerConfig[]> {
+  console.log(`\n📤 Multiple customers available for push:`);
+  allCustomers.forEach((customer, index) => {
+    console.log(`  ${index + 1}. ${customer.idn}`);
+  });
+  console.log(`  ${allCustomers.length + 1}. All customers`);
+
+  const readline = await import('readline');
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  const choice = await new Promise<string>((resolve) => {
+    rl.question(`\nSelect customer to push (1-${allCustomers.length + 1}): `, resolve);
+  });
+  rl.close();
+
+  const choiceNum = parseInt(choice.trim());
+  if (choiceNum === allCustomers.length + 1) {
+    // User selected "All customers"
+    console.log(`🔄 Pushing to all ${allCustomers.length} customers...`);
+    return allCustomers;
+  } else if (choiceNum >= 1 && choiceNum <= allCustomers.length) {
+    // User selected specific customer
+    const selectedCustomer = allCustomers[choiceNum - 1];
+    if (selectedCustomer) {
+      console.log(`🔄 Pushing to customer: ${selectedCustomer.idn}`);
+      return [selectedCustomer];
+    }
+  }
+
+  console.error('Invalid choice. Exiting.');
+  process.exit(1);
+}

package/src/cli/errors.ts

@@ -0,0 +1,111 @@
+/**
+ * Enhanced error handling utilities for NEWO CLI
+ */
+import { EnvValidationError } from '../env.js';
+
+/**
+ * Enhanced error logging for CLI
+ */
+export function logCliError(level: 'error' | 'warn' | 'info', message: string, meta?: Record<string, unknown>): void {
+  const timestamp = new Date().toISOString();
+  const logEntry = {
+    timestamp,
+    level,
+    module: 'cli',
+    message,
+    ...meta
+  };
+
+  // Only log JSON format in verbose mode, otherwise use clean user messages
+  const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');
+
+  if (verbose) {
+    if (level === 'error') {
+      console.error(JSON.stringify(logEntry));
+    } else if (level === 'warn') {
+      console.warn(JSON.stringify(logEntry));
+    } else {
+      console.log(JSON.stringify(logEntry));
+    }
+  } else {
+    // Clean user-facing messages
+    if (level === 'error') {
+      console.error(`❌ ${message}`);
+    } else if (level === 'warn') {
+      console.warn(`⚠️  ${message}`);
+    } else {
+      console.log(`ℹ️  ${message}`);
+    }
+  }
+}
+
+/**
+ * Enhanced error handling with user-friendly messages
+ */
+export function handleCliError(error: unknown, operation: string = 'operation'): never {
+  const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');
+
+  if (error instanceof Error) {
+    // Authentication errors
+    if (error.message.includes('API key') || error.message.includes('Authentication failed')) {
+      logCliError('error', 'Authentication failed. Please check your API key configuration.');
+      if (!verbose) {
+        console.error('\n💡 Troubleshooting tips:');
+        console.error('  • Verify your API key is correct in .env file');
+        console.error('  • For multi-customer setup, check NEWO_CUSTOMER_<IDN>_API_KEY');
+        console.error('  • Run with --verbose for detailed error information');
+      }
+    }
+    // Network errors
+    else if (error.message.includes('Network timeout') || error.message.includes('ENOTFOUND') || error.message.includes('ECONNREFUSED')) {
+      logCliError('error', 'Network connection failed. Please check your internet connection.');
+      if (!verbose) {
+        console.error('\n💡 Troubleshooting tips:');
+        console.error('  • Check your internet connection');
+        console.error('  • Verify NEWO_BASE_URL is correct');
+        console.error('  • Try again in a few moments');
+      }
+    }
+    // Environment configuration errors
+    else if (error instanceof EnvValidationError || error.message.includes('not set')) {
+      logCliError('error', 'Configuration error. Please check your environment setup.');
+      if (!verbose) {
+        console.error('\n💡 Setup help:');
+        console.error('  • Copy .env.example to .env and configure your settings');
+        console.error('  • Run "newo --help" to see configuration examples');
+        console.error('  • Check the README for detailed setup instructions');
+      }
+    }
+    // File system errors
+    else if (error.message.includes('ENOENT') || error.message.includes('EACCES')) {
+      logCliError('error', 'File system error. Please check file permissions and paths.');
+    }
+    // Rate limiting
+    else if (error.message.includes('Rate limit exceeded')) {
+      logCliError('error', 'Rate limit exceeded. Please wait before trying again.');
+    }
+    // General API errors
+    else if (error.message.includes('response') || error.message.includes('status')) {
+      logCliError('error', `API error during ${operation}. Please try again or contact support.`);
+    }
+    // Unknown errors
+    else {
+      logCliError('error', `Unexpected error during ${operation}: ${error.message}`);
+      if (!verbose) {
+        console.error('\n💡 For more details, run the command with --verbose flag');
+      }
+    }
+
+    if (verbose) {
+      logCliError('error', 'Full error details', {
+        operation,
+        errorType: error.constructor.name,
+        stack: error.stack?.split('\n').slice(0, 5).join('\n') // First 5 lines of stack
+      });
+    }
+  } else {
+    logCliError('error', `Unknown error during ${operation}: ${String(error)}`);
+  }
+
+  process.exit(1);
+}