newo 3.6.2 → 3.7.0

package/dist/sync/conversations.js

@@ -1,218 +1,265 @@
 /**
  * Conversations synchronization module
+ *
+ * Incremental/resumable conversation pull:
+ *  - Writes per-persona JSON files to newo_customers/<idn>/conversations/<persona_id>.json as they arrive
+ *  - Updates conversations.yaml aggregate after each persona finishes
+ *  - Skips personas already fully fetched (resume support) unless --force passed via env NEWO_CONV_FORCE=1
+ *  - Graceful on partial failure: individual persona errors do not abort the batch, state is preserved
  */
 import { listUserPersonas, getChatHistory } from '../api.js';
 import { writeFileSafe } from '../fsutil.js';
+import fs from 'fs-extra';
+import path from 'path';
 import yaml from 'js-yaml';
 import pLimit from 'p-limit';
-// Concurrency limit for API calls
 const concurrencyLimit = pLimit(5);
-/**
- * Pull conversations for a customer and save to YAML
- */
-export async function pullConversations(client, customer, options = {}, verbose = false) {
-    if (verbose)
-        console.log(`💬 Fetching conversations for customer ${customer.idn}...`);
+function personaFilePath(customerIdn, personaId) {
+    return path.join('newo_customers', customerIdn, 'conversations', `${personaId}.json`);
+}
+function aggregateYamlPath(customerIdn) {
+    return path.join('newo_customers', customerIdn, 'conversations.yaml');
+}
+async function readPersonaState(customerIdn, personaId) {
+    const p = personaFilePath(customerIdn, personaId);
+    if (!(await fs.pathExists(p)))
+        return null;
     try {
-        // Get all user personas with pagination
-        const allPersonas = [];
-        let page = 1;
-        const perPage = 50;
-        let hasMore = true;
-        while (hasMore) {
-            const response = await listUserPersonas(client, page, perPage);
-            allPersonas.push(...response.items);
-            if (verbose)
-                console.log(`📋 Page ${page}: Found ${response.items.length} personas (${allPersonas.length}/${response.metadata.total} total)`);
-            hasMore = response.items.length === perPage && allPersonas.length < response.metadata.total;
-            page++;
+        return JSON.parse(await fs.readFile(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function writePersonaState(customerIdn, state) {
+    await writeFileSafe(personaFilePath(customerIdn, state.id), JSON.stringify(state, null, 2));
+}
+async function writeAggregateYaml(customerIdn) {
+    const dir = path.join('newo_customers', customerIdn, 'conversations');
+    const files = (await fs.pathExists(dir)) ? await fs.readdir(dir) : [];
+    const personas = [];
+    for (const f of files) {
+        if (!f.endsWith('.json'))
+            continue;
+        try {
+            const state = JSON.parse(await fs.readFile(path.join(dir, f), 'utf8'));
+            personas.push({
+                id: state.id,
+                name: state.name,
+                phone: state.phone,
+                act_count: state.act_count,
+                acts: state.acts
+            });
         }
-        if (options.maxPersonas && allPersonas.length > options.maxPersonas) {
-            allPersonas.splice(options.maxPersonas);
-            if (verbose)
-                console.log(`⚠️  Limited to ${options.maxPersonas} personas as requested`);
+        catch {
+            // skip corrupted file
         }
+    }
+    personas.sort((a, b) => {
+        const aLatestTime = a.acts.length > 0 ? a.acts[a.acts.length - 1].datetime : '1970-01-01T00:00:00.000Z';
+        const bLatestTime = b.acts.length > 0 ? b.acts[b.acts.length - 1].datetime : '1970-01-01T00:00:00.000Z';
+        return new Date(bLatestTime).getTime() - new Date(aLatestTime).getTime();
+    });
+    const totalActs = personas.reduce((sum, p) => sum + p.acts.length, 0);
+    const data = {
+        personas,
+        total_personas: personas.length,
+        total_acts: totalActs,
+        generated_at: new Date().toISOString()
+    };
+    const yamlContent = yaml.dump(data, {
+        indent: 2,
+        quotingType: '"',
+        forceQuotes: false,
+        lineWidth: 120,
+        noRefs: true,
+        sortKeys: false,
+        flowLevel: -1
+    });
+    await writeFileSafe(aggregateYamlPath(customerIdn), yamlContent);
+    return { personas: personas.length, acts: totalActs };
+}
+function buildProcessedActs(raw) {
+    const sorted = [...raw].sort((a, b) => new Date(a.datetime).getTime() - new Date(b.datetime).getTime());
+    return sorted.map(act => {
+        const processedAct = {
+            datetime: act.datetime,
+            type: act.reference_idn,
+            message: act.source_text
+        };
+        if (act.contact_information)
+            processedAct.contact_information = act.contact_information;
+        if (act.flow_idn && act.flow_idn !== 'unknown')
+            processedAct.flow_idn = act.flow_idn;
+        if (act.skill_idn && act.skill_idn !== 'unknown')
+            processedAct.skill_idn = act.skill_idn;
+        if (act.session_id && act.session_id !== 'unknown')
+            processedAct.session_id = act.session_id;
+        return processedAct;
+    });
+}
+/**
+ * Pull conversations for a customer and save incrementally.
+ */
+export async function pullConversations(client, customer, options = {}, verbose = false) {
+    const force = process.env.NEWO_CONV_FORCE === '1';
+    console.log(`💬 Fetching conversations for ${customer.idn}${force ? ' (force re-fetch)' : ' (resume mode)'}...`);
+    // Ensure output dirs exist
+    await fs.ensureDir(path.join('newo_customers', customer.idn, 'conversations'));
+    // 1. Enumerate all personas
+    const allPersonas = [];
+    let page = 1;
+    const perPage = 50;
+    let hasMore = true;
+    while (hasMore) {
+        const response = await listUserPersonas(client, page, perPage);
+        allPersonas.push(...response.items);
         if (verbose)
-            console.log(`👥 Processing ${allPersonas.length} personas...`);
-        // Process personas concurrently with limited concurrency
-        const processedPersonas = [];
-        await Promise.all(allPersonas.map(persona => concurrencyLimit(async () => {
-            try {
-                // Extract phone number from actors
-                const phoneActor = persona.actors.find(actor => actor.integration_idn === 'newo_voice' &&
-                    actor.connector_idn === 'newo_voice_connector' &&
-                    actor.contact_information?.startsWith('+'));
-                const phone = phoneActor?.contact_information || null;
-                // Get acts for this persona
-                const allActs = [];
-                let actPage = 1;
-                const actsPerPage = 100; // Higher limit for acts
-                let hasMoreActs = true;
-                // Get user actor IDs from persona actors first
-                const userActors = persona.actors.filter(actor => actor.integration_idn === 'newo_voice' &&
-                    actor.connector_idn === 'newo_voice_connector');
-                if (userActors.length === 0) {
-                    if (verbose)
-                        console.log(`  👤 ${persona.name}: No voice actors found, skipping`);
-                    // No voice actors, can't get chat history - add persona with empty acts
-                    processedPersonas.push({
-                        id: persona.id,
-                        name: persona.name,
-                        phone,
-                        act_count: persona.act_count,
-                        acts: []
+            console.log(`📋 Page ${page}: ${response.items.length} personas (${allPersonas.length}/${response.metadata.total})`);
+        hasMore = response.items.length === perPage && allPersonas.length < response.metadata.total;
+        page++;
+    }
+    if (options.maxPersonas && allPersonas.length > options.maxPersonas) {
+        allPersonas.splice(options.maxPersonas);
+    }
+    const total = allPersonas.length;
+    console.log(`👥 Found ${total} personas. Processing with concurrency=5...`);
+    let done = 0;
+    let skipped = 0;
+    let failed = 0;
+    await Promise.all(allPersonas.map(persona => concurrencyLimit(async () => {
+        try {
+            // Resume: skip if already complete
+            const existing = await readPersonaState(customer.idn, persona.id);
+            if (!force && existing && existing.complete) {
+                skipped++;
+                done++;
+                if (verbose)
+                    console.log(`⏭️  [${done}/${total}] ${persona.name}: already complete (${existing.acts.length} acts)`);
+                return;
+            }
+            const phoneActor = persona.actors.find(actor => actor.integration_idn === 'newo_voice' &&
+                actor.connector_idn === 'newo_voice_connector' &&
+                actor.contact_information?.startsWith('+'));
+            const phone = phoneActor?.contact_information || null;
+            const userActors = persona.actors.filter(actor => actor.integration_idn === 'newo_voice' &&
+                actor.connector_idn === 'newo_voice_connector');
+            if (userActors.length === 0) {
+                const state = {
+                    id: persona.id,
+                    name: persona.name,
+                    phone,
+                    act_count: persona.act_count,
+                    acts: [],
+                    fetched_at: new Date().toISOString(),
+                    complete: true
+                };
+                await writePersonaState(customer.idn, state);
+                done++;
+                if (verbose)
+                    console.log(`✓ [${done}/${total}] ${persona.name}: no voice actors`);
+                return;
+            }
+            // Fetch acts paginated
+            const allActs = [];
+            let actPage = 1;
+            const actsPerPage = 100;
+            let hasMoreActs = true;
+            const maxPages = 50;
+            let lastError;
+            while (hasMoreActs && actPage <= maxPages) {
+                try {
+                    const chatResponse = await getChatHistory(client, {
+                        user_actor_id: userActors[0].id,
+                        page: actPage,
+                        per: actsPerPage
                     });
-                    if (verbose)
-                        console.log(`  ✓ Processed ${persona.name}: 0 acts (no voice actors)`);
-                    return; // Return from the concurrency function
-                }
-                // Safety mechanism to prevent infinite loops
-                const maxPages = 50; // Limit to 50 pages (5000 acts max per persona)
-                while (hasMoreActs && actPage <= maxPages) {
-                    try {
-                        const chatHistoryParams = {
+                    if (chatResponse.items && chatResponse.items.length > 0) {
+                        const convertedActs = chatResponse.items.map((item) => ({
+                            id: item.id || `chat_${Math.random()}`,
+                            command_act_id: null,
+                            external_event_id: item.external_event_id || 'chat_history',
+                            arguments: [],
+                            reference_idn: (item.is_agent === true) ? 'agent_message' : 'user_message',
+                            runtime_context_id: item.runtime_context_id || 'chat_history',
+                            source_text: item.payload?.text || item.message || item.content || item.text || '',
+                            original_text: item.payload?.text || item.message || item.content || item.text || '',
+                            datetime: item.datetime || item.created_at || item.timestamp || new Date().toISOString(),
                             user_actor_id: userActors[0].id,
-                            page: actPage,
-                            per: actsPerPage
+                            agent_actor_id: null,
+                            user_persona_id: persona.id,
+                            user_persona_name: persona.name,
+                            agent_persona_id: item.agent_persona_id || 'unknown',
+                            external_id: item.external_id || null,
+                            integration_idn: 'newo_voice',
+                            connector_idn: 'newo_voice_connector',
+                            to_integration_idn: null,
+                            to_connector_idn: null,
+                            is_agent: Boolean(item.is_agent === true),
+                            project_idn: null,
+                            flow_idn: item.flow_idn || 'unknown',
+                            skill_idn: item.skill_idn || 'unknown',
+                            session_id: item.session_id || 'unknown',
+                            recordings: item.recordings || [],
+                            contact_information: item.contact_information || null
+                        }));
+                        allActs.push(...convertedActs);
+                        // Save partial progress every page
+                        const partialState = {
+                            id: persona.id,
+                            name: persona.name,
+                            phone,
+                            act_count: persona.act_count,
+                            acts: buildProcessedActs(allActs),
+                            fetched_at: new Date().toISOString(),
+                            complete: false
                         };
-                        if (verbose)
-                            console.log(`    📄 ${persona.name}: Fetching page ${actPage}...`);
-                        const chatResponse = await getChatHistory(client, chatHistoryParams);
-                        if (chatResponse.items && chatResponse.items.length > 0) {
-                            // Convert chat history format to acts format - create minimal ConversationAct objects
-                            const convertedActs = chatResponse.items.map((item) => ({
-                                id: item.id || `chat_${Math.random()}`,
-                                command_act_id: null,
-                                external_event_id: item.external_event_id || 'chat_history',
-                                arguments: [],
-                                reference_idn: (item.is_agent === true) ? 'agent_message' : 'user_message',
-                                runtime_context_id: item.runtime_context_id || 'chat_history',
-                                source_text: item.payload?.text || item.message || item.content || item.text || '',
-                                original_text: item.payload?.text || item.message || item.content || item.text || '',
-                                datetime: item.datetime || item.created_at || item.timestamp || new Date().toISOString(),
-                                user_actor_id: userActors[0].id,
-                                agent_actor_id: null,
-                                user_persona_id: persona.id,
-                                user_persona_name: persona.name,
-                                agent_persona_id: item.agent_persona_id || 'unknown',
-                                external_id: item.external_id || null,
-                                integration_idn: 'newo_voice',
-                                connector_idn: 'newo_voice_connector',
-                                to_integration_idn: null,
-                                to_connector_idn: null,
-                                is_agent: Boolean(item.is_agent === true),
-                                project_idn: null,
-                                flow_idn: item.flow_idn || 'unknown',
-                                skill_idn: item.skill_idn || 'unknown',
-                                session_id: item.session_id || 'unknown',
-                                recordings: item.recordings || [],
-                                contact_information: item.contact_information || null
-                            }));
-                            allActs.push(...convertedActs);
-                            if (verbose && convertedActs.length > 0) {
-                                console.log(`  👤 ${persona.name}: Chat History - ${convertedActs.length} messages (${allActs.length} total)`);
-                            }
-                            // Check if we should continue paginating
-                            const hasMetadata = chatResponse.metadata?.total !== undefined;
-                            const currentTotal = chatResponse.metadata?.total || 0;
-                            hasMoreActs = chatResponse.items.length === actsPerPage &&
-                                hasMetadata &&
-                                allActs.length < currentTotal;
-                            actPage++;
-                            if (verbose)
-                                console.log(`    📊 ${persona.name}: Page ${actPage - 1} done, ${allActs.length}/${currentTotal} total acts`);
-                        }
-                        else {
-                            // No more items
-                            hasMoreActs = false;
-                            if (verbose)
-                                console.log(`    📊 ${persona.name}: No more chat history items`);
-                        }
+                        await writePersonaState(customer.idn, partialState);
+                        const currentTotal = chatResponse.metadata?.total || 0;
+                        hasMoreActs = chatResponse.items.length === actsPerPage && allActs.length < currentTotal;
+                        actPage++;
                     }
-                    catch (chatError) {
-                        if (verbose)
-                            console.log(`  ⚠️  Chat history failed for ${persona.name}: ${chatError instanceof Error ? chatError.message : String(chatError)}`);
+                    else {
                         hasMoreActs = false;
                     }
                 }
-                if (actPage > maxPages) {
+                catch (chatError) {
+                    lastError = chatError instanceof Error ? chatError.message : String(chatError);
                     if (verbose)
-                        console.log(`  ⚠️  ${persona.name}: Reached max pages limit (${maxPages}), stopping pagination`);
+                        console.log(`⚠️  ${persona.name} page ${actPage}: ${lastError}`);
+                    hasMoreActs = false;
                 }
-                // Sort acts by datetime ascending (chronological order)
-                allActs.sort((a, b) => new Date(a.datetime).getTime() - new Date(b.datetime).getTime());
-                // Process acts into simplified format - exclude redundant fields
-                const processedActs = allActs.map(act => {
-                    const processedAct = {
-                        datetime: act.datetime,
-                        type: act.reference_idn,
-                        message: act.source_text
-                    };
-                    // Only include non-redundant fields
-                    if (act.contact_information) {
-                        processedAct.contact_information = act.contact_information;
-                    }
-                    if (act.flow_idn && act.flow_idn !== 'unknown') {
-                        processedAct.flow_idn = act.flow_idn;
-                    }
-                    if (act.skill_idn && act.skill_idn !== 'unknown') {
-                        processedAct.skill_idn = act.skill_idn;
-                    }
-                    if (act.session_id && act.session_id !== 'unknown') {
-                        processedAct.session_id = act.session_id;
-                    }
-                    return processedAct;
-                });
-                processedPersonas.push({
-                    id: persona.id,
-                    name: persona.name,
-                    phone,
-                    act_count: persona.act_count,
-                    acts: processedActs
-                });
-                if (verbose)
-                    console.log(`  ✓ Processed ${persona.name}: ${processedActs.length} acts`);
             }
-            catch (error) {
-                console.error(`❌ Failed to process persona ${persona.name}:`, error);
-                // Continue with other personas
-            }
-        })));
-        // Sort personas by most recent act time (descending) - use latest act from acts array
-        processedPersonas.sort((a, b) => {
-            const aLatestTime = a.acts.length > 0 ? a.acts[a.acts.length - 1].datetime : '1970-01-01T00:00:00.000Z';
-            const bLatestTime = b.acts.length > 0 ? b.acts[b.acts.length - 1].datetime : '1970-01-01T00:00:00.000Z';
-            return new Date(bLatestTime).getTime() - new Date(aLatestTime).getTime();
-        });
-        // Calculate totals
-        const totalActs = processedPersonas.reduce((sum, persona) => sum + persona.acts.length, 0);
-        // Create final conversations data
-        const conversationsData = {
-            personas: processedPersonas,
-            total_personas: processedPersonas.length,
-            total_acts: totalActs,
-            generated_at: new Date().toISOString()
-        };
-        // Save to YAML file
-        const conversationsPath = `newo_customers/${customer.idn}/conversations.yaml`;
-        const yamlContent = yaml.dump(conversationsData, {
-            indent: 2,
-            quotingType: '"',
-            forceQuotes: false,
-            lineWidth: 120,
-            noRefs: true,
-            sortKeys: false,
-            flowLevel: -1
-        });
-        await writeFileSafe(conversationsPath, yamlContent);
-        if (verbose) {
-            console.log(`✓ Saved conversations to ${conversationsPath}`);
-            console.log(`📊 Summary: ${processedPersonas.length} personas, ${totalActs} total acts`);
+            const finalState = {
+                id: persona.id,
+                name: persona.name,
+                phone,
+                act_count: persona.act_count,
+                acts: buildProcessedActs(allActs),
+                fetched_at: new Date().toISOString(),
+                complete: !lastError
+            };
+            if (lastError)
+                finalState.last_error = lastError;
+            await writePersonaState(customer.idn, finalState);
+            // Incremental YAML aggregate every persona
+            const agg = await writeAggregateYaml(customer.idn);
+            done++;
+            if (lastError)
+                failed++;
+            console.log(`${lastError ? '⚠️ ' : '✓'} [${done}/${total}] ${persona.name}: ${finalState.acts.length} acts${lastError ? ` (partial: ${lastError})` : ''} | total so far: ${agg.personas} personas / ${agg.acts} acts`);
         }
-    }
-    catch (error) {
-        console.error(`❌ Failed to pull conversations for ${customer.idn}:`, error);
-        throw error;
-    }
+        catch (error) {
+            failed++;
+            done++;
+            const msg = error instanceof Error ? error.message : String(error);
+            console.error(`❌ [${done}/${total}] ${persona.name}: ${msg}`);
+        }
+    })));
+    // Final aggregate write
+    const final = await writeAggregateYaml(customer.idn);
+    console.log(`\n✅ Done. ${final.personas} personas, ${final.acts} acts. Skipped ${skipped} (already cached), ${failed} had errors.`);
+    console.log(`   Aggregate: ${aggregateYamlPath(customer.idn)}`);
+    console.log(`   Per-persona: newo_customers/${customer.idn}/conversations/<id>.json`);
 }
 //# sourceMappingURL=conversations.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newo",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "NEWO CLI: Professional command-line tool with modular architecture for NEWO AI Agent development. Features account migration, integration management, webhook automation, AKB knowledge base, project attributes, sandbox testing, IDN-based file management, real-time progress tracking, intelligent sync operations, and comprehensive multi-customer support.",
   "type": "module",
   "bin": {
@@ -60,6 +60,8 @@
     "node": ">=18"
   },
   "dependencies": {
+    "newo-dsl-analyzer": "^1.0.0",
+    "newo-dsl-core": "^1.0.0",
     "axios": "^1.7.7",
     "chokidar": "^5.0.0",
     "dotenv": "^16.4.5",

package/src/cli/commands/check.ts

@@ -0,0 +1,21 @@
+/**
+ * `newo check` - umbrella command equivalent to running lint + format --check.
+ *
+ * A failing check exits non-zero if any of the sub-checks fail, so CI
+ * pipelines can gate merges on a single invocation.
+ */
+import { handleLintCommand } from './lint.js';
+import { handleFormatCommand } from './format.js';
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+
+export async function handleCheckCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean,
+): Promise<void> {
+  const lintArgs = { ...args };
+  await handleLintCommand(customerConfig, lintArgs as CliArgs, verbose);
+
+  const formatCheckArgs = { ...args, check: true } as CliArgs;
+  await handleFormatCommand(customerConfig, formatCheckArgs, verbose);
+}

package/src/cli/commands/format.ts

@@ -0,0 +1,131 @@
+/**
+ * `newo format` - apply canonical formatting to DSL files.
+ *
+ * Invokes newo-dsl-analyzer's Formatter. In v1 the formatter is an
+ * identity transform (just ensures a final newline). Concrete rules
+ * land in subsequent versions; the command surface is stable now so
+ * CI pipelines and pre-commit hooks can wire `newo format --check`
+ * immediately.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { createFormatter } from 'newo-dsl-analyzer';
+
+import { selectSingleCustomer } from '../customer-selection.js';
+import { handleCliError } from '../errors.js';
+import { resolveFormat } from '../../format/detect.js';
+import { discoverCustomerFiles, discoverFromPath, defaultRoot } from '../../lint/discovery.js';
+import type { MultiCustomerConfig, CliArgs, CustomerConfig } from '../../types.js';
+import type { FormatVersion } from '../../format/types.js';
+
+interface FormatArgs {
+  positional: string[];
+  formatVersion: string | undefined;
+  check: boolean;
+  customer: string | undefined;
+}
+
+export async function handleFormatCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean,
+): Promise<void> {
+  try {
+    const fmtArgs = parseArgs(args);
+    const formatter = createFormatter();
+
+    const hasCustomerContext =
+      fmtArgs.customer !== undefined ||
+      Object.keys(customerConfig.customers ?? {}).length > 0;
+
+    const { selectedCustomer, allCustomers, isMultiCustomer } = hasCustomerContext
+      ? selectSingleCustomer(customerConfig, fmtArgs.customer)
+      : { selectedCustomer: null, allCustomers: [] as CustomerConfig[], isMultiCustomer: false };
+
+    const targetCustomer = selectedCustomer ?? (isMultiCustomer ? null : allCustomers[0] ?? null);
+    void targetCustomer;
+
+    const files = await resolveFiles(targetCustomer, allCustomers, fmtArgs, isMultiCustomer);
+    if (files.length === 0) {
+      console.log('No files matched.');
+      return;
+    }
+
+    let touched = 0;
+    let needsFormat = 0;
+    for (const file of files) {
+      const source = await fs.readFile(file.absPath, 'utf8');
+      const result = formatter.format(source, file.absPath);
+      if (!result.changed) continue;
+      needsFormat++;
+      if (fmtArgs.check) {
+        console.log(`would rewrite ${path.relative(process.cwd(), file.absPath)}`);
+      } else {
+        await fs.writeFile(file.absPath, result.formatted, 'utf8');
+        touched++;
+        if (verbose) console.log(`formatted ${path.relative(process.cwd(), file.absPath)}`);
+      }
+    }
+
+    if (fmtArgs.check) {
+      if (needsFormat === 0) {
+        console.log('All files are properly formatted.');
+        return;
+      }
+      console.log(`${needsFormat} file(s) would be reformatted.`);
+      process.exit(1);
+    } else {
+      console.log(`Formatted ${touched} file(s).`);
+    }
+  } catch (err) {
+    handleCliError(err, 'format');
+  }
+}
+
+function parseArgs(args: CliArgs): FormatArgs {
+  const positional = args._.slice(1).filter((p): p is string => typeof p === 'string');
+  return {
+    positional,
+    formatVersion: args.format as string | undefined,
+    check: Boolean(args.check),
+    customer: args.customer as string | undefined,
+  };
+}
+
+async function resolveFiles(
+  selected: CustomerConfig | null,
+  all: CustomerConfig[],
+  args: FormatArgs,
+  isMultiCustomer: boolean,
+) {
+  if (args.positional.length > 0) {
+    const files = [];
+    for (const p of args.positional) {
+      files.push(
+        ...(await discoverFromPath(p, {
+          ...(args.formatVersion ? { format: toFormatVersion(args.formatVersion) } : {}),
+        })),
+      );
+    }
+    return files;
+  }
+  if (selected) {
+    const formatVersion = resolveFormat(selected.idn, args.formatVersion).version;
+    return discoverCustomerFiles(selected, { format: formatVersion });
+  }
+  if (isMultiCustomer) {
+    const files = [];
+    for (const customer of all) {
+      const formatVersion = resolveFormat(customer.idn, args.formatVersion).version;
+      files.push(...(await discoverCustomerFiles(customer, { format: formatVersion })));
+    }
+    return files;
+  }
+  return discoverFromPath(defaultRoot(), {
+    ...(args.formatVersion ? { format: toFormatVersion(args.formatVersion) } : {}),
+  });
+}
+
+function toFormatVersion(v: string): FormatVersion {
+  return v === 'newo_v2' ? 'newo_v2' : 'cli_v1';
+}

package/src/cli/commands/help.ts

@@ -22,6 +22,19 @@ Core Commands:
   newo meta [--customer <idn>]                  # get project metadata (debug)
   newo import-akb <file> <persona_id> [--customer <idn>]  # import AKB articles
 
+Linting & Formatting (NEW):
+  newo lint [paths...] [--format <fmt>] [--reporter <text|json|sarif>]       # static-analysis on DSL files
+  newo lint --changed                                                        # lint only files modified since last push
+  newo lint --live                                                           # refresh action catalog from NEWO API
+  newo lint --rule <code> --no-rule <code>                                   # selectively enable/disable rules
+  newo lint --max-warnings <n>                                               # fail when warnings exceed threshold
+  newo format [paths...] [--check]                                           # apply canonical formatting (in-place or --check)
+  newo check [paths...]                                                      # umbrella: lint + format --check (CI gate)
+
+  Powered by newo-dsl-analyzer. Exit codes: 0 clean, 1 lint errors, 2 runtime error.
+  Discover rules via the Diagnostic code column (E100, W101, ...); configure
+  them in .neworc.yaml at your repo root. Plugin authors: depend on newo-dsl-core.
+
 Project Management:
   newo create-project <idn> [--title <title>] [--description <desc>] [--version <version>] [--auto-update]  # create empty project on platform
   newo list-registries [--customer <idn>]                                   # list available project registries (production, staging, etc.)