newo 3.4.1 → 3.6.0

package/src/env.ts

@@ -12,6 +12,7 @@ export interface ValidatedEnv {
   readonly NEWO_REFRESH_TOKEN: string | undefined;
   readonly NEWO_REFRESH_URL: string | undefined;
   readonly NEWO_DEFAULT_CUSTOMER: string | undefined;
+  readonly NEWO_FORMAT: string | undefined;
   // Dynamic customer entries will be detected at runtime
   readonly [key: string]: string | undefined;
 }
@@ -81,6 +82,7 @@ export function validateEnvironment(): ValidatedEnv {
     NEWO_REFRESH_TOKEN: refreshToken,
     NEWO_REFRESH_URL: refreshUrl,
     NEWO_DEFAULT_CUSTOMER: env.NEWO_DEFAULT_CUSTOMER?.trim(),
+    NEWO_FORMAT: env.NEWO_FORMAT?.trim(),
   };
 }
 

package/src/format/detect.ts

@@ -0,0 +1,123 @@
+/**
+ * Format detection and resolution
+ *
+ * Resolution chain per customer (highest to lowest priority):
+ * 1. Explicit --format flag (per-command override)
+ * 2. Filesystem auto-detect (for EXISTING customers):
+ *    - import_version.txt present -> newo_v2
+ *    - projects/ directory present -> cli_v1
+ * 3. NEWO_FORMAT env var (only for NEW customers where nothing exists locally)
+ * 4. Default: cli_v1
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { NEWO_CUSTOMERS_DIR } from '../fsutil.js';
+import { type FormatVersion, type FormatConfig, VALID_FORMATS } from './types.js';
+
+/**
+ * Detect format from existing filesystem structure for a customer
+ * Returns null if the customer directory doesn't exist or is empty
+ */
+export function detectFormatFromFilesystem(customerIdn: string): FormatVersion | null {
+  const customerDir = path.join(NEWO_CUSTOMERS_DIR, customerIdn);
+
+  if (!fs.existsSync(customerDir)) {
+    return null;
+  }
+
+  // Check for V2 marker: import_version.txt
+  const importVersionFile = path.join(customerDir, 'import_version.txt');
+  if (fs.existsSync(importVersionFile)) {
+    return 'newo_v2';
+  }
+
+  // Check for V1 marker: projects/ directory
+  const projectsDir = path.join(customerDir, 'projects');
+  if (fs.existsSync(projectsDir)) {
+    return 'cli_v1';
+  }
+
+  // Check one level down for import_version.txt (V2 exports sometimes have a wrapper dir)
+  try {
+    const entries = fs.readdirSync(customerDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const nestedImportVersion = path.join(customerDir, entry.name, 'import_version.txt');
+        if (fs.existsSync(nestedImportVersion)) {
+          return 'newo_v2';
+        }
+      }
+    }
+  } catch {
+    // Ignore read errors
+  }
+
+  // Directory exists but no format markers found - could be empty or only has attributes
+  return null;
+}
+
+/**
+ * Get format from NEWO_FORMAT environment variable
+ */
+function getEnvFormat(): FormatVersion | null {
+  const envFormat = process.env['NEWO_FORMAT']?.trim().toLowerCase();
+  if (!envFormat) return null;
+
+  if ((VALID_FORMATS as readonly string[]).includes(envFormat)) {
+    return envFormat as FormatVersion;
+  }
+
+  console.warn(
+    `Warning: Invalid NEWO_FORMAT="${envFormat}". Valid values: ${VALID_FORMATS.join(', ')}. Using default.`
+  );
+  return null;
+}
+
+/**
+ * Validate an explicit format string from --format flag
+ */
+function validateExplicitFormat(format: string): FormatVersion | null {
+  const normalized = format.trim().toLowerCase();
+  if ((VALID_FORMATS as readonly string[]).includes(normalized)) {
+    return normalized as FormatVersion;
+  }
+  return null;
+}
+
+/**
+ * Resolve the format version for a customer using the full resolution chain
+ *
+ * @param customerIdn - Customer identifier
+ * @param explicitFormat - Optional --format flag value
+ */
+export function resolveFormat(
+  customerIdn: string,
+  explicitFormat?: string
+): FormatConfig {
+  // 1. Explicit --format flag takes highest priority
+  if (explicitFormat) {
+    const validated = validateExplicitFormat(explicitFormat);
+    if (validated) {
+      return { version: validated, source: 'explicit-flag' };
+    }
+    console.error(
+      `Invalid format "${explicitFormat}". Valid values: ${VALID_FORMATS.join(', ')}`
+    );
+    process.exit(1);
+  }
+
+  // 2. Filesystem auto-detect for existing customers
+  const detected = detectFormatFromFilesystem(customerIdn);
+  if (detected) {
+    return { version: detected, source: 'auto-detected' };
+  }
+
+  // 3. NEWO_FORMAT env var (for new customers only)
+  const envFormat = getEnvFormat();
+  if (envFormat) {
+    return { version: envFormat, source: 'env-var' };
+  }
+
+  // 4. Default: cli_v1
+  return { version: 'cli_v1', source: 'default' };
+}

package/src/format/extensions.ts

@@ -0,0 +1,61 @@
+/**
+ * Format-aware file extension mapping
+ *
+ * Handles the extension differences between cli_v1 and newo_v2:
+ *   cli_v1:  guidance -> .guidance,  nsl -> .jinja
+ *   newo_v2: guidance -> .nslg,      nsl -> .nsl
+ */
+import type { RunnerType } from '../types.js';
+import {
+  type FormatVersion,
+  CLI_V1_EXTENSIONS,
+  NEWO_V2_EXTENSIONS,
+  ALL_SCRIPT_EXTENSIONS,
+} from './types.js';
+
+/**
+ * Get file extension for a runner type in a specific format
+ */
+export function getExtensionForFormat(runnerType: RunnerType, format: FormatVersion): string {
+  const map = format === 'newo_v2' ? NEWO_V2_EXTENSIONS : CLI_V1_EXTENSIONS;
+  const ext = map[runnerType];
+  return ext ?? CLI_V1_EXTENSIONS.guidance;
+}
+
+/**
+ * Get runner type from file extension (works for all 4 extensions)
+ */
+export function getRunnerTypeFromExtension(ext: string): RunnerType {
+  const normalized = ext.startsWith('.') ? ext : `.${ext}`;
+  switch (normalized) {
+    case '.guidance':
+    case '.nslg':
+      return 'guidance';
+    case '.jinja':
+    case '.nsl':
+      return 'nsl';
+    default:
+      return 'guidance';
+  }
+}
+
+/**
+ * Check if a filename is a recognized script file (any format)
+ */
+export function isScriptFile(filename: string): boolean {
+  const ext = filename.lastIndexOf('.') >= 0
+    ? filename.slice(filename.lastIndexOf('.'))
+    : '';
+  return (ALL_SCRIPT_EXTENSIONS as readonly string[]).includes(ext.toLowerCase());
+}
+
+/**
+ * Infer format version from a file extension
+ */
+export function getFormatFromExtension(ext: string): FormatVersion {
+  const normalized = ext.startsWith('.') ? ext : `.${ext}`;
+  if (normalized === '.nsl' || normalized === '.nslg') {
+    return 'newo_v2';
+  }
+  return 'cli_v1';
+}

package/src/format/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Format module - handles cli_v1 and newo_v2 format differences
+ */
+export {
+  type FormatVersion,
+  type FormatConfig,
+  CLI_V1_EXTENSIONS,
+  NEWO_V2_EXTENSIONS,
+  ALL_SCRIPT_EXTENSIONS,
+  V2_IMPORT_VERSION,
+  VALID_FORMATS,
+} from './types.js';
+
+export {
+  getExtensionForFormat,
+  getRunnerTypeFromExtension,
+  isScriptFile,
+  getFormatFromExtension,
+} from './extensions.js';
+
+export {
+  detectFormatFromFilesystem,
+  resolveFormat,
+} from './detect.js';
+
+export {
+  v2CustomerDir,
+  v2ProjectDir,
+  v2AgentDir,
+  v2FlowDir,
+  v2SkillsDir,
+  v2SkillScriptPath,
+  v2FlowYamlPath,
+  v2ProjectYamlPath,
+  v2AgentYamlPath,
+  v2ImportVersionPath,
+  v2AkbDir,
+  v2AkbPath,
+  v2CustomerAttributesPath,
+  v2ProjectAttributesPath,
+  v2LibraryDir,
+  v2LibraryYamlPath,
+  v2LibrarySkillsDir,
+  v2LibrarySkillScriptPath,
+} from './paths-v2.js';
+
+export { patchYamlToPyyaml } from './yaml-patch.js';
+export { v2LibrarySkillRelativePath } from './paths-v2.js';
+
+export {
+  type V2FlowDefinition,
+  type V2InlineSkill,
+  type V2FlowEvent,
+  type V2StateField,
+  type V2ProjectMeta,
+  type V2AgentMeta,
+  type V2LibraryDefinition,
+  parseV2FlowYaml,
+  generateV2FlowYaml,
+  parseV2ProjectYaml,
+  generateV2ProjectYaml,
+  parseV2AgentYaml,
+  generateV2AgentYaml,
+  parseV2LibraryYaml,
+  generateV2LibraryYaml,
+} from './v2-yaml.js';

package/src/format/paths-v2.ts

@@ -0,0 +1,207 @@
+/**
+ * V2 (newo_v2) path utilities
+ *
+ * Generates paths for the NEWO platform export format:
+ *   newo_customers/{cust}/
+ *     import_version.txt
+ *     attributes.yaml
+ *     akb/{AgentIdn}.yaml
+ *     {ProjectIdn}/
+ *       {project_idn}.yaml
+ *       attributes.yaml
+ *       agents/{AgentIdn}/
+ *         agent.yaml
+ *         flows/{FlowIdn}/
+ *           {FlowIdn}.yaml
+ *           skills/{SkillIdn}.nsl|.nslg
+ *       libraries/{LibIdn}/
+ *         {lib_idn}.yaml
+ *         skills/{SkillIdn}.nsl|.nslg
+ */
+import path from 'path';
+import { NEWO_CUSTOMERS_DIR } from '../fsutil.js';
+import type { RunnerType } from '../types.js';
+import { getExtensionForFormat } from './extensions.js';
+
+// ── Customer level ──
+
+export function v2CustomerDir(customerIdn: string): string {
+  return path.posix.join(NEWO_CUSTOMERS_DIR, customerIdn);
+}
+
+export function v2ImportVersionPath(customerIdn: string): string {
+  return path.posix.join(v2CustomerDir(customerIdn), 'import_version.txt');
+}
+
+export function v2CustomerAttributesPath(customerIdn: string): string {
+  return path.posix.join(v2CustomerDir(customerIdn), 'attributes.yaml');
+}
+
+// ── AKB level ──
+
+export function v2AkbDir(customerIdn: string): string {
+  return path.posix.join(v2CustomerDir(customerIdn), 'akb');
+}
+
+export function v2AkbPath(customerIdn: string, agentIdn: string): string {
+  return path.posix.join(v2AkbDir(customerIdn), `${agentIdn}.yaml`);
+}
+
+// ── Project level ──
+
+export function v2ProjectDir(customerIdn: string, projectIdn: string): string {
+  return path.posix.join(v2CustomerDir(customerIdn), projectIdn);
+}
+
+export function v2ProjectYamlPath(customerIdn: string, projectIdn: string): string {
+  return path.posix.join(v2ProjectDir(customerIdn, projectIdn), `${projectIdn}.yaml`);
+}
+
+export function v2ProjectAttributesPath(customerIdn: string, projectIdn: string): string {
+  return path.posix.join(v2ProjectDir(customerIdn, projectIdn), 'attributes.yaml');
+}
+
+// ── Agent level ──
+
+export function v2AgentDir(
+  customerIdn: string,
+  projectIdn: string,
+  agentIdn: string
+): string {
+  return path.posix.join(v2ProjectDir(customerIdn, projectIdn), 'agents', agentIdn);
+}
+
+export function v2AgentYamlPath(
+  customerIdn: string,
+  projectIdn: string,
+  agentIdn: string
+): string {
+  return path.posix.join(v2AgentDir(customerIdn, projectIdn, agentIdn), 'agent.yaml');
+}
+
+// ── Flow level ──
+
+export function v2FlowDir(
+  customerIdn: string,
+  projectIdn: string,
+  agentIdn: string,
+  flowIdn: string
+): string {
+  return path.posix.join(
+    v2AgentDir(customerIdn, projectIdn, agentIdn),
+    'flows',
+    flowIdn
+  );
+}
+
+export function v2FlowYamlPath(
+  customerIdn: string,
+  projectIdn: string,
+  agentIdn: string,
+  flowIdn: string
+): string {
+  return path.posix.join(
+    v2FlowDir(customerIdn, projectIdn, agentIdn, flowIdn),
+    `${flowIdn}.yaml`
+  );
+}
+
+// ── Skill level ──
+
+export function v2SkillsDir(
+  customerIdn: string,
+  projectIdn: string,
+  agentIdn: string,
+  flowIdn: string
+): string {
+  return path.posix.join(
+    v2FlowDir(customerIdn, projectIdn, agentIdn, flowIdn),
+    'skills'
+  );
+}
+
+export function v2SkillScriptPath(
+  customerIdn: string,
+  projectIdn: string,
+  agentIdn: string,
+  flowIdn: string,
+  skillIdn: string,
+  runnerType: RunnerType
+): string {
+  const ext = getExtensionForFormat(runnerType, 'newo_v2');
+  return path.posix.join(
+    v2SkillsDir(customerIdn, projectIdn, agentIdn, flowIdn),
+    `${skillIdn}${ext}`
+  );
+}
+
+/**
+ * Build the relative prompt_script path as it appears in V2 flow YAML
+ * e.g., "flows/MainFlow/skills/GreetingSkill.nsl"
+ */
+export function v2SkillRelativePath(
+  flowIdn: string,
+  skillIdn: string,
+  runnerType: RunnerType
+): string {
+  const ext = getExtensionForFormat(runnerType, 'newo_v2');
+  return `flows/${flowIdn}/skills/${skillIdn}${ext}`;
+}
+
+// ── Library level ──
+
+export function v2LibraryDir(
+  customerIdn: string,
+  projectIdn: string,
+  libraryIdn: string
+): string {
+  return path.posix.join(v2ProjectDir(customerIdn, projectIdn), 'libraries', libraryIdn);
+}
+
+export function v2LibraryYamlPath(
+  customerIdn: string,
+  projectIdn: string,
+  libraryIdn: string
+): string {
+  return path.posix.join(
+    v2LibraryDir(customerIdn, projectIdn, libraryIdn),
+    `${libraryIdn}.yaml`
+  );
+}
+
+export function v2LibrarySkillsDir(
+  customerIdn: string,
+  projectIdn: string,
+  libraryIdn: string
+): string {
+  return path.posix.join(v2LibraryDir(customerIdn, projectIdn, libraryIdn), 'skills');
+}
+
+export function v2LibrarySkillScriptPath(
+  customerIdn: string,
+  projectIdn: string,
+  libraryIdn: string,
+  skillIdn: string,
+  runnerType: RunnerType
+): string {
+  const ext = getExtensionForFormat(runnerType, 'newo_v2');
+  return path.posix.join(
+    v2LibrarySkillsDir(customerIdn, projectIdn, libraryIdn),
+    `${skillIdn}${ext}`
+  );
+}
+
+/**
+ * Build relative prompt_script path for library skill in V2 YAML
+ * The V2 export includes the project prefix:
+ *   e.g., "naf/libraries/testLib/skills/utilSkill.nsl"
+ */
+export function v2LibrarySkillRelativePath(
+  projectIdn: string,
+  libraryIdn: string,
+  skillIdn: string,
+  runnerType: RunnerType
+): string {
+  const ext = getExtensionForFormat(runnerType, 'newo_v2');
+  return `${projectIdn}/libraries/${libraryIdn}/skills/${skillIdn}${ext}`;
+}

package/src/format/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Format version types and constants
+ *
+ * Defines the two supported project formats:
+ * - cli_v1: Native CLI format (full feature support, per-entity metadata)
+ * - newo_v2: NEWO platform export format (compatible with platform UI exports)
+ */
+import type { RunnerType } from '../types.js';
+
+export type FormatVersion = 'cli_v1' | 'newo_v2';
+
+export interface FormatConfig {
+  version: FormatVersion;
+  source: 'explicit-flag' | 'env-var' | 'auto-detected' | 'default';
+}
+
+/**
+ * Extension mapping per format
+ *
+ * cli_v1: guidance -> .guidance, nsl -> .jinja
+ * newo_v2: guidance -> .nslg, nsl -> .nsl
+ */
+export const CLI_V1_EXTENSIONS: Record<RunnerType, string> = {
+  guidance: '.guidance',
+  nsl: '.jinja',
+} as const;
+
+export const NEWO_V2_EXTENSIONS: Record<RunnerType, string> = {
+  guidance: '.nslg',
+  nsl: '.nsl',
+} as const;
+
+/** All recognized script file extensions across both formats */
+export const ALL_SCRIPT_EXTENSIONS = ['.guidance', '.jinja', '.nsl', '.nslg'] as const;
+
+/** V2 import version marker content */
+export const V2_IMPORT_VERSION = 'v2.0.0';
+
+/** Valid format values for CLI flag and env var validation */
+export const VALID_FORMATS: readonly FormatVersion[] = ['cli_v1', 'newo_v2'] as const;