@ornexus/neocortex 4.0.1

package/packages/client/dist/commands/invoke.js

@@ -0,0 +1,490 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Invoke Command
+ *
+ * Primary entry point for server-side orchestration.
+ * Sends raw user args to POST /api/v1/invoke and returns
+ * complete orchestration instructions from the server.
+ *
+ * Story 45.2 - AC1-AC6
+ */
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { LicenseClient } from '../license/license-client.js';
+import { EncryptedCache } from '../cache/encrypted-cache.js';
+import { NoOpCache } from '../types/index.js';
+import { TierAwareClient } from '../tier/tier-aware-client.js';
+import { loadSecureConfig } from '../config/secure-config.js';
+import { DEFAULT_SERVER_URL } from '../constants.js';
+// ── Constants ─────────────────────────────────────────────────────────────
+const CONFIG_DIR = join(homedir(), '.neocortex');
+const CACHE_DIR = join(CONFIG_DIR, 'cache');
+const MENU_CACHE_FILE = join(CACHE_DIR, 'menu-cache.json');
+const MENU_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_TIMEOUT_MS = 30_000;
+const CLIENT_VERSION = '3.9.62';
+// ── State Snapshot Collection ──────────────────────────────────────────────
+/**
+ * Read state.json and construct a sanitized snapshot for the server.
+ * Relative paths only - no absolute paths sent to server.
+ */
+export function collectStateSnapshot(projectRoot) {
+    const stateJsonPath = join(projectRoot, '.neocortex', 'state.json');
+    if (!existsSync(stateJsonPath)) {
+        // Return minimal snapshot if state.json doesn't exist
+        return {
+            config: {
+                project_name: 'unknown',
+                default_branch: 'main',
+                language: 'pt-BR',
+            },
+            stories: {},
+            epics: {},
+        };
+    }
+    let stateData;
+    try {
+        const raw = readFileSync(stateJsonPath, 'utf-8');
+        stateData = JSON.parse(raw);
+    }
+    catch {
+        return {
+            config: {
+                project_name: 'unknown',
+                default_branch: 'main',
+                language: 'pt-BR',
+            },
+            stories: {},
+            epics: {},
+        };
+    }
+    // Extract config - check both locations for compatibility
+    const config = (stateData.config ?? stateData.project ?? {});
+    // Extract stories - sanitize sensitive fields
+    const rawStories = (stateData.stories ?? {});
+    const stories = {};
+    for (const [id, story] of Object.entries(rawStories)) {
+        stories[id] = {
+            id: story.id ?? id,
+            title: story.title,
+            epic_id: story.epic_id,
+            status: story.status ?? 'backlog',
+            steps_completed: story.steps_completed ?? [],
+            last_step: story.last_step ?? null,
+            branch_name: story.branch_name ?? null,
+            pr_number: story.pr_number,
+            workflow_issue: story.workflow_issue,
+        };
+    }
+    // Extract epics
+    const rawEpics = (stateData.epics ?? {});
+    const epics = {};
+    for (const [id, epic] of Object.entries(rawEpics)) {
+        epics[id] = {
+            id: epic.id ?? id,
+            title: epic.title,
+            status: epic.status,
+            stories: epic.stories,
+            total_stories: epic.total_stories,
+            completed_stories: epic.completed_stories,
+        };
+    }
+    return {
+        config: {
+            project_name: (config.project_name ?? config.name ?? 'unknown'),
+            default_branch: (config.default_branch ?? 'main'),
+            language: (config.language ?? 'pt-BR'),
+            yolo_mode: config.yolo_mode,
+            user_name: config.user_name,
+            worktree_base: config.worktree_base,
+            max_parallel_stories: config.max_parallel_stories,
+        },
+        stories,
+        epics,
+    };
+}
+// ── Menu Cache (Encrypted - Story 61.1) ──────────────────────────────────
+const MENU_CACHE_KEY = 'neocortex:menu:cache';
+/**
+ * Read menu cache from EncryptedCache.
+ * Falls back gracefully: if decryption fails or data is stale, returns null.
+ * Also cleans up legacy plaintext menu-cache.json if it exists.
+ */
+async function getMenuCache(encryptedCache) {
+    try {
+        const raw = await encryptedCache.get(MENU_CACHE_KEY);
+        if (!raw)
+            return null;
+        const cache = JSON.parse(raw);
+        // Invalidate on version mismatch (stale cache from previous install)
+        if (cache.version !== CLIENT_VERSION) {
+            return null;
+        }
+        // Check TTL (EncryptedCache also has TTL, but we double-check for version-based invalidation)
+        if (Date.now() - cache.cachedAt > MENU_CACHE_TTL_MS) {
+            return null; // Expired
+        }
+        return cache;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write menu cache to EncryptedCache.
+ * Deletes legacy plaintext menu-cache.json on first encrypted write.
+ */
+async function setMenuCache(encryptedCache, instructions, metadata) {
+    try {
+        const cache = {
+            instructions,
+            metadata,
+            cachedAt: Date.now(),
+            version: CLIENT_VERSION,
+        };
+        await encryptedCache.set(MENU_CACHE_KEY, JSON.stringify(cache), MENU_CACHE_TTL_MS);
+        // Delete legacy plaintext menu-cache.json if it exists (F1 remediation)
+        deleteLegacyMenuCache();
+    }
+    catch {
+        // Cache write failure is non-critical
+    }
+}
+/**
+ * Remove legacy plaintext menu-cache.json file.
+ * Called after successful encrypted write to prevent IP leakage.
+ */
+function deleteLegacyMenuCache() {
+    try {
+        if (existsSync(MENU_CACHE_FILE)) {
+            unlinkSync(MENU_CACHE_FILE);
+        }
+    }
+    catch {
+        // Non-critical: best-effort cleanup
+    }
+}
+// ── Config Loading (Story 61.2 - Secure) ─────────────────────────────────
+/**
+ * Load config with automatic decryption of license key.
+ * Handles migration from plaintext licenseKey to encryptedLicenseKey.
+ */
+function loadConfig() {
+    return loadSecureConfig();
+}
+async function getAuthTokenAndClient(serverUrl, licenseKey) {
+    try {
+        let cacheProvider;
+        if (licenseKey) {
+            const cacheDir = join(CONFIG_DIR, 'cache');
+            cacheProvider = new EncryptedCache({ cacheDir, passphrase: licenseKey });
+        }
+        else {
+            // Legacy config without licenseKey - use NoOpCache with warning
+            process.stderr.write('[neocortex] Warning: No license key in config. Run "neocortex activate" to re-authenticate.\n');
+            cacheProvider = new NoOpCache();
+        }
+        const client = new LicenseClient({
+            serverUrl,
+            licenseKey: licenseKey ?? '',
+            cacheProvider,
+        });
+        const token = await client.getToken();
+        if (!token)
+            return null;
+        const tierClient = new TierAwareClient({
+            cacheProvider,
+            licenseClient: client,
+        });
+        return { token, client, tierClient };
+    }
+    catch {
+        return null;
+    }
+}
+// ── HTTP Request ──────────────────────────────────────────────────────────
+/** P50.05: One-time warning flag per process */
+let versionWarningShown = false;
+async function sendInvokeRequest(serverUrl, body, authToken) {
+    const url = `${serverUrl}/api/v1/invoke`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${authToken}`,
+                'X-Client-Version': CLIENT_VERSION,
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            let errorJson;
+            try {
+                errorJson = JSON.parse(errorText);
+            }
+            catch {
+                // Not JSON
+            }
+            return {
+                ok: false,
+                status: response.status,
+                error: errorJson
+                    ? `${errorJson.error_code ?? 'ERROR'}: ${errorJson.message ?? errorText}`
+                    : `HTTP ${response.status}: ${errorText}`,
+                errorBody: errorJson,
+            };
+        }
+        const data = (await response.json());
+        // P50.05: Detect version warning header (non-blocking, once per process)
+        const versionWarning = response.headers.get('X-Client-Version-Warning');
+        if (versionWarning && !versionWarningShown) {
+            versionWarningShown = true;
+            process.stderr.write(`\n[Neocortex] ${versionWarning}\n\n`);
+        }
+        return { ok: true, status: response.status, data };
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            status: 0,
+            error: message.includes('abort')
+                ? `Request timeout after ${DEFAULT_TIMEOUT_MS / 1000}s`
+                : `Network error: ${message}`,
+        };
+    }
+}
+// ── Main Invoke Function ──────────────────────────────────────────────────
+/**
+ * Execute the invoke command.
+ *
+ * Flow:
+ * 1. Load config to get server URL
+ * 2. Collect state snapshot from project root
+ * 3. Check menu cache for empty invocations
+ * 4. Send POST /api/v1/invoke
+ * 5. Format and return result
+ */
+export async function invoke(options) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const platformTarget = options.platformTarget ?? 'claude-code';
+    // 1. Determine server URL
+    const config = loadConfig();
+    const serverUrl = (options.serverUrl ?? config?.serverUrl ?? DEFAULT_SERVER_URL).replace(/\/+$/, '');
+    // 2. Collect state snapshot
+    const stateSnapshot = collectStateSnapshot(projectRoot);
+    // 2a. Create encrypted cache for menu (uses licenseKey as passphrase)
+    const menuCache = config?.licenseKey
+        ? new EncryptedCache({ cacheDir: CACHE_DIR, passphrase: config.licenseKey })
+        : null;
+    // 3. Check menu cache for empty invocations (AC6)
+    const trimmedArgs = options.args.trim();
+    if (!trimmedArgs && menuCache) {
+        const cachedMenu = await getMenuCache(menuCache);
+        if (cachedMenu) {
+            return {
+                success: true,
+                instructions: cachedMenu.instructions,
+                metadata: cachedMenu.metadata,
+                exitCode: 0,
+            };
+        }
+    }
+    // 4. Get auth token and license client from config
+    const auth = await getAuthTokenAndClient(serverUrl, config?.licenseKey);
+    if (!auth) {
+        // Story P26.04: Include fingerprint change as possible cause
+        const hint = config && !config.licenseKey
+            ? ' This may be caused by a machine fingerprint change (e.g., hardware or hostname change).'
+            : '';
+        return {
+            success: false,
+            error: `Not authenticated.${hint} Visit https://neocortex.ornexus.com/login to get your license key, then run: neocortex activate YOUR-LICENSE-KEY`,
+            exitCode: 2, // Not configured
+        };
+    }
+    // 4a. Pre-flight tier check (optimistic -- if it fails, still proceed)
+    const trigger = extractTrigger(trimmedArgs);
+    if (trigger) {
+        try {
+            const preFlightResult = await auth.tierClient.preFlightCheck(trigger);
+            if (!preFlightResult.allowed) {
+                process.stderr.write(`[neocortex] ${preFlightResult.message}\n`);
+                return {
+                    success: false,
+                    error: preFlightResult.message ?? 'Trigger not available on your plan',
+                    exitCode: 1,
+                };
+            }
+        }
+        catch {
+            // Fail-open: pre-flight errors should not block invocation
+        }
+    }
+    const requestBody = {
+        args: trimmedArgs,
+        projectRoot: projectRoot.replace(homedir(), '~'), // Sanitize absolute path
+        stateSnapshot,
+        platformTarget,
+    };
+    // 5. Send request
+    let result = await sendInvokeRequest(serverUrl, requestBody, auth.token);
+    // 5a. 401 retry: inspect fallback_action and retry once after forceRefresh
+    if (!result.ok && result.status === 401) {
+        const fallbackAction = result.errorBody?.fallback_action;
+        if (fallbackAction === 'refresh_token' || fallbackAction === 're_authenticate') {
+            const newToken = await auth.client.forceRefresh();
+            if (newToken) {
+                result = await sendInvokeRequest(serverUrl, requestBody, newToken);
+            }
+        }
+    }
+    // P50.04: 426 UPGRADE_REQUIRED -- forced update with clear instructions
+    if (!result.ok && result.status === 426) {
+        const body = result.errorBody;
+        const upgradeCmd = body?.upgrade_command ?? 'npm install -g @ornexus/neocortex@latest';
+        const minVersion = body?.min_version ?? 'unknown';
+        process.stderr.write('\n');
+        process.stderr.write('==================================================\n');
+        process.stderr.write('  UPGRADE REQUIRED\n');
+        process.stderr.write('==================================================\n');
+        process.stderr.write(`\n  Your Neocortex version (${CLIENT_VERSION}) is no longer supported.\n`);
+        process.stderr.write(`  Minimum required: ${minVersion}\n\n`);
+        process.stderr.write('  Run this command to update:\n\n');
+        process.stderr.write(`    ${upgradeCmd}\n\n`);
+        process.stderr.write('  After updating, re-run your command.\n');
+        process.stderr.write('==================================================\n\n');
+        return {
+            success: false,
+            error: `UPGRADE_REQUIRED: Client version ${CLIENT_VERSION} is below minimum ${minVersion}. Run: ${upgradeCmd}`,
+            exitCode: 3,
+        };
+    }
+    if (!result.ok || !result.data) {
+        // AC5: Error exit code
+        const exitCode = result.status === 401 ? 2 :
+            result.status === 429 ? 1 :
+                result.status >= 500 ? 1 : 1;
+        return {
+            success: false,
+            error: result.error ?? 'Unknown error from server',
+            exitCode,
+        };
+    }
+    // 6. Cache menu responses (AC6) - encrypted (Story 61.1)
+    if (!trimmedArgs && result.data.metadata?.mode === 'menu' && menuCache) {
+        setMenuCache(menuCache, result.data.instructions, result.data.metadata).catch(() => { });
+    }
+    // 6a. Update cached quota from server response metadata (Epic 60)
+    if (result.data.metadata) {
+        auth.tierClient.updateQuotaFromResponse(result.data.metadata).catch(() => { });
+    }
+    // 6b. Story 18.7 + 18.8: Detect tier change and auto-refresh
+    if (result.data.metadata?.tier_changed) {
+        const newTier = result.data.metadata.current_tier;
+        try {
+            const newToken = await auth.client.forceRefresh();
+            if (newToken) {
+                await auth.tierClient.invalidateTierCache();
+                process.stderr.write(`[Neocortex] Token atualizado automaticamente para tier ${newTier}\n`);
+            }
+            else {
+                process.stderr.write(`[Neocortex] Seu tier foi atualizado para ${newTier}! Execute "neocortex activate" para obter um token atualizado.\n`);
+            }
+        }
+        catch {
+            // Fail-open: tier change notification is best-effort
+            process.stderr.write(`[Neocortex] Seu tier foi atualizado para ${newTier}! Execute "neocortex activate" para obter um token atualizado.\n`);
+        }
+    }
+    return {
+        success: true,
+        instructions: result.data.instructions,
+        metadata: result.data.metadata,
+        exitCode: 0,
+    };
+}
+// ── Trigger Extraction ──────────────────────────────────────────────────
+/**
+ * Extract trigger name from args string.
+ * Triggers start with '*' (e.g., "*yolo", "*implement", "*status").
+ * Returns the trigger name without the '*' prefix, or null if no trigger.
+ */
+function extractTrigger(args) {
+    const match = args.match(/^\*([a-zA-Z][\w-]*)/);
+    return match ? match[1] : null;
+}
+// ── CLI Entry Point ───────────────────────────────────────────────────────
+/**
+ * CLI handler for the invoke command.
+ * Parses CLI args and delegates to invoke().
+ *
+ * Usage:
+ *   neocortex-client invoke --args "*yolo @story.md" --project-root /path
+ *   neocortex-client invoke --args "*status" --format json
+ */
+export async function invokeCliHandler(argv) {
+    let args = '';
+    let projectRoot = process.cwd();
+    let format = 'plain';
+    let serverUrl;
+    // Parse CLI arguments
+    for (let i = 0; i < argv.length; i++) {
+        switch (argv[i]) {
+            case '--args':
+                args = argv[++i] ?? '';
+                break;
+            case '--project-root':
+                projectRoot = argv[++i] ?? process.cwd();
+                break;
+            case '--format':
+                format = (argv[++i] ?? 'plain');
+                break;
+            case '--server-url':
+                serverUrl = argv[++i];
+                break;
+        }
+    }
+    const result = await invoke({ args, projectRoot, format, serverUrl });
+    if (!result.success) {
+        // AC5: Error to stderr as JSON
+        process.stderr.write(JSON.stringify({
+            error_code: result.exitCode === 2 ? 'NOT_CONFIGURED' : 'INVOKE_ERROR',
+            message: result.error,
+        }) + '\n');
+        return result.exitCode;
+    }
+    if (format === 'json') {
+        // AC3: Full JSON to stdout
+        process.stdout.write(JSON.stringify({
+            instructions: result.instructions,
+            metadata: result.metadata,
+        }) + '\n');
+    }
+    else {
+        // AC4: Instructions to stdout, metadata to stderr
+        process.stdout.write((result.instructions ?? '') + '\n');
+        if (result.metadata) {
+            process.stderr.write(JSON.stringify(result.metadata) + '\n');
+        }
+    }
+    return 0;
+}

package/packages/client/dist/config/resolver-selection.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+import type { AssetResolver } from '../resolvers/asset-resolver.js';
+import type { CreateResolverOptions } from '../types/index.js';
+/** Result of resolver selection including the reason for the choice */
+export interface ResolverSelectionResult {
+    readonly resolver: AssetResolver;
+    readonly reason: string;
+    readonly mode: 'local' | 'remote';
+}
+/**
+ * Create the appropriate AssetResolver based on configuration.
+ *
+ * Selection follows a strict priority chain:
+ * 1. forceLocal option -> LocalResolver
+ * 2. NEOCORTEX_MODE=local -> LocalResolver
+ * 3. NEOCORTEX_MODE=remote -> RemoteResolver
+ * 4. core/ exists locally -> LocalResolver
+ * 5. License key + no core/ -> RemoteResolver
+ * 6. Default -> LocalResolver
+ *
+ * @param options - Optional configuration overrides
+ * @returns Configured AssetResolver ready for use
+ */
+export declare function createResolver(options?: CreateResolverOptions): Promise<AssetResolver>;
+/**
+ * Select resolver with full result including reason.
+ * Useful for logging/debugging why a specific resolver was chosen.
+ */
+export declare function selectResolver(options?: CreateResolverOptions): Promise<ResolverSelectionResult>;