newo 1.4.0 → 1.5.1

package/src/types.ts

@@ -0,0 +1,276 @@
+/**
+ * Comprehensive type definitions for NEWO CLI
+ */
+
+export interface NewoEnvironment {
+  NEWO_BASE_URL?: string;
+  NEWO_PROJECT_ID?: string;
+  NEWO_API_KEY?: string;
+  NEWO_API_KEYS?: string; // JSON string containing array of keys or key objects
+  NEWO_ACCESS_TOKEN?: string;
+  NEWO_REFRESH_TOKEN?: string;
+  NEWO_REFRESH_URL?: string;
+  NEWO_DEFAULT_CUSTOMER?: string;
+  // Dynamic customer entries will be detected at runtime
+  [key: string]: string | undefined;
+}
+
+export interface ApiKeyConfig {
+  key: string;
+  project_id?: string;
+}
+
+export interface CustomerConfig {
+  idn: string;
+  apiKey: string;
+  projectId?: string | undefined;
+}
+
+export interface CustomerProfile {
+  id: string;
+  idn: string;
+  organization_name: string;
+  email: string;
+  [key: string]: any;
+}
+
+export interface MultiCustomerConfig {
+  customers: Record<string, CustomerConfig>;
+  defaultCustomer?: string | undefined;
+}
+
+// Authentication Types
+export interface TokenResponse {
+  access_token?: string;
+  token?: string;
+  accessToken?: string;
+  refresh_token?: string;
+  refreshToken?: string;
+  expires_in?: number;
+  expiresIn?: number;
+}
+
+export interface StoredTokens {
+  access_token: string;
+  refresh_token: string;
+  expires_at: number;
+}
+
+// API Response Types
+export interface ProjectMeta {
+  readonly id: string;
+  readonly idn: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly created_at?: string;
+  readonly updated_at?: string;
+}
+
+export interface Agent {
+  readonly id: string;
+  readonly idn: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly flows?: readonly Flow[];
+}
+
+export interface Flow {
+  readonly id: string;
+  readonly idn: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly default_runner_type: RunnerType;
+  readonly default_model: ModelConfig;
+}
+
+export interface ModelConfig {
+  readonly model_idn: string;
+  readonly provider_idn: string;
+}
+
+export interface SkillParameter {
+  readonly name: string;
+  readonly default_value?: string;
+}
+
+export interface Skill {
+  readonly id: string;
+  readonly idn: string;
+  readonly title: string;
+  prompt_script?: string; // Mutable for updates
+  readonly runner_type: RunnerType;
+  readonly model: ModelConfig;
+  readonly parameters: readonly SkillParameter[];
+  readonly path?: string | undefined;
+}
+
+export interface FlowEvent {
+  readonly id: string;
+  readonly idn: string;
+  readonly description: string;
+  readonly skill_selector: SkillSelector;
+  readonly skill_idn?: string;
+  readonly state_idn?: string;
+  readonly integration_idn?: string;
+  readonly connector_idn?: string;
+  readonly interrupt_mode: InterruptMode;
+}
+
+export interface FlowState {
+  readonly id: string;
+  readonly idn: string;
+  readonly title: string;
+  readonly default_value?: string;
+  readonly scope: StateFieldScope;
+}
+
+// Enum Types
+export type RunnerType = 'guidance' | 'nsl';
+export type SkillSelector = 'first' | 'last' | 'random' | 'all';
+export type InterruptMode = 'allow' | 'deny' | 'queue';
+export type StateFieldScope = 'flow' | 'agent' | 'project' | 'global';
+
+// File System Types
+export interface SkillMetadata {
+  id: string;
+  title: string;
+  idn: string;
+  runner_type: RunnerType;
+  model: ModelConfig;
+  parameters: SkillParameter[];
+  path?: string | undefined;
+}
+
+export interface FlowData {
+  id: string;
+  skills: Record<string, SkillMetadata>;
+}
+
+export interface AgentData {
+  id: string;
+  flows: Record<string, FlowData>;
+}
+
+export interface ProjectData {
+  projectId: string;
+  projectIdn: string;
+  agents: Record<string, AgentData>;
+}
+
+export interface ProjectMap {
+  projects: Record<string, ProjectData>;
+}
+
+// Legacy single-project format support
+export interface LegacyProjectMap extends ProjectData {
+  projects?: Record<string, ProjectData>;
+}
+
+export interface HashStore {
+  [filePath: string]: string;
+}
+
+// AKB Types
+export interface ParsedArticle {
+  readonly topic_name: string;
+  readonly persona_id: string | null;
+  readonly topic_summary: string;
+  readonly topic_facts: readonly string[];
+  readonly confidence: number;
+  readonly source: string;
+  readonly labels: readonly string[];
+}
+
+export interface AkbImportArticle extends Omit<ParsedArticle, 'persona_id'> {
+  persona_id: string;
+}
+
+// CLI Types
+export interface CliArgs {
+  readonly _: readonly string[];
+  readonly verbose?: boolean;
+  readonly v?: boolean;
+  readonly [key: string]: unknown;
+}
+
+// flows.yaml Generation Types
+export interface FlowsYamlSkill {
+  idn: string;
+  title: string;
+  prompt_script: string;
+  runner_type: string;
+  model: ModelConfig;
+  parameters: Array<{
+    name: string;
+    default_value: string;
+  }>;
+}
+
+export interface FlowsYamlEvent {
+  title: string;
+  idn: string;
+  skill_selector: string;
+  skill_idn?: string | undefined;
+  state_idn?: string | undefined;
+  integration_idn?: string | undefined;
+  connector_idn?: string | undefined;
+  interrupt_mode: string;
+}
+
+export interface FlowsYamlState {
+  title: string;
+  idn: string;
+  default_value?: string | undefined;
+  scope: string;
+}
+
+export interface FlowsYamlFlow {
+  idn: string;
+  title: string;
+  description: string | null;
+  default_runner_type: string;
+  default_provider_idn: string;
+  default_model_idn: string;
+  skills: FlowsYamlSkill[];
+  events: FlowsYamlEvent[];
+  state_fields: FlowsYamlState[];
+}
+
+export interface FlowsYamlAgent {
+  agent_idn: string;
+  agent_description?: string | undefined;
+  agent_flows: FlowsYamlFlow[];
+}
+
+export interface FlowsYamlData {
+  flows: FlowsYamlAgent[];
+}
+
+// HTTP Client Types
+export interface AxiosClientConfig {
+  baseURL?: string;
+  headers?: Record<string, string>;
+}
+
+// Error Types
+export interface NewoApiError extends Error {
+  response?: {
+    status: number;
+    data: unknown;
+  };
+  config?: {
+    method?: string;
+    url?: string;
+    headers?: Record<string, string>;
+  };
+}
+
+// Status Types
+export type FileStatus = 'M' | 'D' | 'clean';
+
+export interface StatusResult {
+  filePath: string;
+  status: FileStatus;
+  oldHash?: string;
+  newHash?: string;
+}

package/src/api.js

@@ -1,103 +0,0 @@
-import axios from 'axios';
-import dotenv from 'dotenv';
-import { getValidAccessToken, forceReauth } from './auth.js';
-dotenv.config();
-
-const { NEWO_BASE_URL } = process.env;
-
-export async function makeClient(verbose = false) {
-  let accessToken = await getValidAccessToken();
-  if (verbose) console.log('✓ Access token obtained');
-
-  const client = axios.create({
-    baseURL: NEWO_BASE_URL,
-    headers: { accept: 'application/json' }
-  });
-
-  client.interceptors.request.use(async (config) => {
-    config.headers = config.headers || {};
-    config.headers.Authorization = `Bearer ${accessToken}`;
-    if (verbose) {
-      console.log(`→ ${config.method?.toUpperCase()} ${config.url}`);
-      if (config.data) console.log('  Data:', JSON.stringify(config.data, null, 2));
-      if (config.params) console.log('  Params:', config.params);
-    }
-    return config;
-  });
-
-  let retried = false;
-  client.interceptors.response.use(
-    r => {
-      if (verbose) {
-        console.log(`← ${r.status} ${r.config.method?.toUpperCase()} ${r.config.url}`);
-        if (r.data && Object.keys(r.data).length < 20) {
-          console.log('  Response:', JSON.stringify(r.data, null, 2));
-        } else if (r.data) {
-          console.log(`  Response: [${typeof r.data}] ${Array.isArray(r.data) ? r.data.length + ' items' : 'large object'}`);
-        }
-      }
-      return r;
-    },
-    async (error) => {
-      const status = error?.response?.status;
-      if (verbose) {
-        console.log(`← ${status} ${error.config?.method?.toUpperCase()} ${error.config?.url} - ${error.message}`);
-        if (error.response?.data) console.log('  Error data:', error.response.data);
-      }
-      if (status === 401 && !retried) {
-        retried = true;
-        if (verbose) console.log('🔄 Retrying with fresh token...');
-        accessToken = await forceReauth();
-        error.config.headers.Authorization = `Bearer ${accessToken}`;
-        return client.request(error.config);
-      }
-      throw error;
-    }
-  );
-
-  return client;
-}
-
-export async function listProjects(client) {
-  const r = await client.get(`/api/v1/designer/projects`);
-  return r.data;
-}
-
-export async function listAgents(client, projectId) {
-  const r = await client.get(`/api/v1/bff/agents/list`, { params: { project_id: projectId } });
-  return r.data;
-}
-
-export async function getProjectMeta(client, projectId) {
-  const r = await client.get(`/api/v1/designer/projects/by-id/${projectId}`);
-  return r.data;
-}
-
-export async function listFlowSkills(client, flowId) {
-  const r = await client.get(`/api/v1/designer/flows/${flowId}/skills`);
-  return r.data;
-}
-
-export async function getSkill(client, skillId) {
-  const r = await client.get(`/api/v1/designer/skills/${skillId}`);
-  return r.data;
-}
-
-export async function updateSkill(client, skillObject) {
-  await client.put(`/api/v1/designer/flows/skills/${skillObject.id}`, skillObject);
-}
-
-export async function listFlowEvents(client, flowId) {
-  const r = await client.get(`/api/v1/designer/flows/${flowId}/events`);
-  return r.data;
-}
-
-export async function listFlowStates(client, flowId) {
-  const r = await client.get(`/api/v1/designer/flows/${flowId}/states`);
-  return r.data;
-}
-
-export async function importAkbArticle(client, articleData) {
-  const r = await client.post('/api/v1/akb/append-manual', articleData);
-  return r.data;
-}

package/src/auth.js

@@ -1,92 +0,0 @@
-import fs from 'fs-extra';
-import path from 'path';
-import axios from 'axios';
-import dotenv from 'dotenv';
-dotenv.config();
-
-const {
-  NEWO_BASE_URL,
-  NEWO_API_KEY,
-  NEWO_ACCESS_TOKEN,
-  NEWO_REFRESH_TOKEN,
-  NEWO_REFRESH_URL
-} = process.env;
-
-const STATE_DIR = path.join(process.cwd(), '.newo');
-const TOKENS_PATH = path.join(STATE_DIR, 'tokens.json');
-
-async function saveTokens(tokens) {
-  await fs.ensureDir(STATE_DIR);
-  await fs.writeJson(TOKENS_PATH, tokens, { spaces: 2 });
-}
-
-async function loadTokens() {
-  if (await fs.pathExists(TOKENS_PATH)) {
-    return fs.readJson(TOKENS_PATH);
-  }
-  if (NEWO_ACCESS_TOKEN || NEWO_REFRESH_TOKEN) {
-    const t = {
-      access_token: NEWO_ACCESS_TOKEN || '',
-      refresh_token: NEWO_REFRESH_TOKEN || '',
-      expires_at: Date.now() + 10 * 60 * 1000
-    };
-    await saveTokens(t);
-    return t;
-  }
-  return null;
-}
-
-function isExpired(tokens) {
-  if (!tokens?.expires_at) return false;
-  return Date.now() >= tokens.expires_at - 10_000;
-}
-
-export async function exchangeApiKeyForToken() {
-  if (!NEWO_API_KEY) throw new Error('NEWO_API_KEY not set. Provide an API key in .env');
-  const url = `${NEWO_BASE_URL}/api/v1/auth/api-key/token`;
-  const res = await axios.post(url, {}, { headers: { 'x-api-key': NEWO_API_KEY, 'accept': 'application/json' } });
-  const data = res.data || {};
-  const access = data.access_token || data.token || data.accessToken;
-  const refresh = data.refresh_token || data.refreshToken || '';
-  const expiresInSec = data.expires_in || data.expiresIn || 3600;
-  const tokens = { access_token: access, refresh_token: refresh, expires_at: Date.now() + expiresInSec * 1000 };
-  await saveTokens(tokens);
-  return tokens;
-}
-
-export async function refreshWithEndpoint(refreshToken) {
-  if (!NEWO_REFRESH_URL) throw new Error('NEWO_REFRESH_URL not set');
-  const res = await axios.post(NEWO_REFRESH_URL, { refresh_token: refreshToken }, { headers: { 'accept': 'application/json' } });
-  const data = res.data || {};
-  const access = data.access_token || data.token || data.accessToken;
-  const refresh = data.refresh_token ?? refreshToken;
-  const expiresInSec = data.expires_in || 3600;
-  const tokens = { access_token: access, refresh_token: refresh, expires_at: Date.now() + expiresInSec * 1000 };
-  await saveTokens(tokens);
-  return tokens;
-}
-
-export async function getValidAccessToken() {
-  let tokens = await loadTokens();
-  if (!tokens || !tokens.access_token) {
-    tokens = await exchangeApiKeyForToken();
-    return tokens.access_token;
-  }
-  if (!isExpired(tokens)) return tokens.access_token;
-
-  if (NEWO_REFRESH_URL && tokens.refresh_token) {
-    try {
-      tokens = await refreshWithEndpoint(tokens.refresh_token);
-      return tokens.access_token;
-    } catch (e) {
-      console.warn('Refresh failed, falling back to API key exchange…');
-    }
-  }
-  tokens = await exchangeApiKeyForToken();
-  return tokens.access_token;
-}
-
-export async function forceReauth() {
-  const tokens = await exchangeApiKeyForToken();
-  return tokens.access_token;
-}

package/src/cli.js

@@ -1,108 +0,0 @@
-#!/usr/bin/env node
-import minimist from 'minimist';
-import dotenv from 'dotenv';
-import { makeClient, getProjectMeta, importAkbArticle } from './api.js';
-import { pullAll, pushChanged, status } from './sync.js';
-import { parseAkbFile, prepareArticlesForImport } from './akb.js';
-import path from 'path';
-
-dotenv.config();
-const { NEWO_PROJECT_ID } = process.env;
-
-async function main() {
-  const args = minimist(process.argv.slice(2));
-  const cmd = args._[0];
-  const verbose = args.verbose || args.v;
-
-  if (!cmd || ['help', '-h', '--help'].includes(cmd)) {
-    console.log(`NEWO CLI
-Usage:
-  newo pull                    # download all projects -> ./projects/ OR specific project if NEWO_PROJECT_ID set
-  newo push                    # upload modified *.guidance/*.jinja back to NEWO
-  newo status                  # show modified files
-  newo meta                    # get project metadata (debug, requires NEWO_PROJECT_ID)
-  newo import-akb <file> <persona_id>  # import AKB articles from file
-  
-Flags:
-  --verbose, -v                # enable detailed logging
-  
-Env:
-  NEWO_BASE_URL, NEWO_PROJECT_ID (optional), NEWO_API_KEY, NEWO_REFRESH_URL (optional)
-  
-Notes:
-  - multi-project support: pull downloads all accessible projects or single project based on NEWO_PROJECT_ID
-  - If NEWO_PROJECT_ID is set, pull downloads only that project
-  - If NEWO_PROJECT_ID is not set, pull downloads all projects accessible with your API key
-  - Projects are stored in ./projects/{project-idn}/ folders
-  - Each project folder contains metadata.json and flows.yaml
-`);
-    return;
-  }
-
-  const client = await makeClient(verbose);
-
-  if (cmd === 'pull') {
-    // If PROJECT_ID is set, pull single project; otherwise pull all projects
-    await pullAll(client, NEWO_PROJECT_ID || null, verbose);
-  } else if (cmd === 'push') {
-    await pushChanged(client, verbose);
-  } else if (cmd === 'status') {
-    await status(verbose);
-  } else if (cmd === 'meta') {
-    if (!NEWO_PROJECT_ID) throw new Error('NEWO_PROJECT_ID is not set in env');
-    const meta = await getProjectMeta(client, NEWO_PROJECT_ID);
-    console.log(JSON.stringify(meta, null, 2));
-  } else if (cmd === 'import-akb') {
-    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);
-    
-    try {
-      if (verbose) console.log(`📖 Parsing AKB file: ${filePath}`);
-      const articles = parseAkbFile(filePath);
-      console.log(`✓ Parsed ${articles.length} articles from ${akbFile}`);
-      
-      if (verbose) console.log(`🔧 Preparing articles for persona: ${personaId}`);
-      const preparedArticles = prepareArticlesForImport(articles, personaId);
-      
-      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) {
-          errorCount++;
-          console.error(`\n❌ Failed to import ${article.topic_name}:`, error?.response?.data || error.message);
-        }
-      }
-      
-      if (!verbose) console.log(''); // new line after dots
-      console.log(`✅ Import complete: ${successCount} successful, ${errorCount} failed`);
-      
-    } catch (error) {
-      console.error('❌ AKB import failed:', error.message);
-      process.exit(1);
-    }
-  } else {
-    console.error('Unknown command:', cmd);
-    process.exit(1);
-  }
-}
-
-main().catch((e) => {
-  console.error(e?.response?.data || e);
-  process.exit(1);
-});

package/src/fsutil.js

@@ -1,34 +0,0 @@
-import fs from 'fs-extra';
-import path from 'path';
-
-export const ROOT_DIR = path.join(process.cwd(), 'projects');
-export const STATE_DIR = path.join(process.cwd(), '.newo');
-export const MAP_PATH = path.join(STATE_DIR, 'map.json');
-export const HASHES_PATH = path.join(STATE_DIR, 'hashes.json');
-
-export async function ensureState() {
-  await fs.ensureDir(STATE_DIR);
-  await fs.ensureDir(ROOT_DIR);
-}
-
-export function projectDir(projectIdn) {
-  return path.join(ROOT_DIR, projectIdn);
-}
-
-export function skillPath(projectIdn, agentIdn, flowIdn, skillIdn, runnerType = 'guidance') {
-  const extension = runnerType === 'nsl' ? '.jinja' : '.guidance';
-  return path.join(ROOT_DIR, projectIdn, agentIdn, flowIdn, `${skillIdn}${extension}`);
-}
-
-export function metadataPath(projectIdn) {
-  return path.join(ROOT_DIR, projectIdn, 'metadata.json');
-}
-
-export async function writeFileAtomic(filepath, content) {
-  await fs.ensureDir(path.dirname(filepath));
-  await fs.writeFile(filepath, content, 'utf8');
-}
-
-export async function readIfExists(filepath) {
-  return (await fs.pathExists(filepath)) ? fs.readFile(filepath, 'utf8') : null;
-}

package/src/hash.js

@@ -1,17 +0,0 @@
-import crypto from 'crypto';
-import fs from 'fs-extra';
-import { ensureState, HASHES_PATH } from './fsutil.js';
-
-export function sha256(str) {
-  return crypto.createHash('sha256').update(str, 'utf8').digest('hex');
-}
-
-export async function loadHashes() {
-  await ensureState();
-  if (await fs.pathExists(HASHES_PATH)) return fs.readJson(HASHES_PATH);
-  return {};
-}
-
-export async function saveHashes(h) {
-  await fs.writeJson(HASHES_PATH, h, { spaces: 2 });
-}