@ornexus/neocortex 4.0.1

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

@@ -0,0 +1,390 @@
+/**
+ * @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 - Activate Command
+ *
+ * Manages license activation for the Neocortex CLI.
+ * Validates license key with the IP Protection Server,
+ * caches JWT token, and creates user config file.
+ *
+ * Story 43.3 - AC1, AC3, AC4, AC5
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { LicenseClient } from '../license/license-client.js';
+import { EncryptedCache } from '../cache/encrypted-cache.js';
+import { getMachineFingerprint } from '../machine/fingerprint.js';
+import { updateAgentDescription } from '../agent/update-description.js';
+import { refreshStubs } from '../agent/refresh-stubs.js';
+import { updateAgentYaml } from '../agent/update-agent-yaml.js';
+import { saveSecureConfig, setSecureDirPermissions } from '../config/secure-config.js';
+import { DEFAULT_SERVER_URL } from '../constants.js';
+// ── Version Resolution ────────────────────────────────────────────────────
+function getInstalledVersion() {
+    try {
+        const thisFile = fileURLToPath(import.meta.url);
+        let dir = dirname(thisFile);
+        for (let i = 0; i < 5; i++) {
+            try {
+                const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'));
+                if (pkg.name === '@ornexus/neocortex' || pkg.name === '@neocortex/client') {
+                    return pkg.version ?? '0.0.0';
+                }
+            }
+            catch { /* no package.json at this level */ }
+            dir = dirname(dir);
+        }
+    }
+    catch { /* fallback */ }
+    return '0.0.0';
+}
+// ── Constants ─────────────────────────────────────────────────────────────
+const CONFIG_DIR = join(homedir(), '.neocortex');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+// License key format: NX-{F|P|E}-{24 hex}-{4 hex checksum}
+const LICENSE_KEY_PATTERN = /^NX-(F|P|E)-[a-f0-9]+-[a-f0-9]+$/i;
+// API key format: nxk_{24hex}_{4check} (new, P32) or nxk_{tier}_{24hex}_{4check} (legacy)
+const API_KEY_PATTERN = /^nxk_(?:[a-z]+_)?[a-f0-9]+_[a-f0-9]+$/;
+// ── Validation ────────────────────────────────────────────────────────────
+/**
+ * Validate license key format.
+ * Format: NX-{TIER}-{random}-{random}
+ * Tiers: FREE, PRO, ENT
+ */
+export function validateLicenseKeyFormat(key) {
+    if (!key || key.trim().length === 0) {
+        return { valid: false, error: 'License key cannot be empty' };
+    }
+    const trimmed = key.trim().toUpperCase();
+    if (!trimmed.startsWith('NX-')) {
+        return { valid: false, error: 'License key must start with "NX-"' };
+    }
+    if (!LICENSE_KEY_PATTERN.test(trimmed)) {
+        return {
+            valid: false,
+            error: 'Invalid license key format. Expected: NX-{TIER}-{ID} (e.g., NX-PRO-ABC-123)',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate API key format.
+ * Format: nxk_{tier}_{random}_{check}
+ */
+export function validateApiKeyFormat(key) {
+    if (!key || key.trim().length === 0) {
+        return { valid: false, error: 'API key cannot be empty' };
+    }
+    const trimmed = key.trim();
+    if (!trimmed.startsWith('nxk_')) {
+        return { valid: false, error: 'API key must start with "nxk_"' };
+    }
+    if (trimmed.length < 20) {
+        return { valid: false, error: 'API key is too short' };
+    }
+    if (!API_KEY_PATTERN.test(trimmed)) {
+        return {
+            valid: false,
+            error: 'Invalid API key format. Expected: nxk_{id}_{check} (e.g., nxk_abc123def456...)',
+        };
+    }
+    return { valid: true };
+}
+// ── Config Management ─────────────────────────────────────────────────────
+/**
+ * Load existing user config, if any.
+ */
+function loadExistingConfig() {
+    try {
+        if (existsSync(CONFIG_FILE)) {
+            const raw = readFileSync(CONFIG_FILE, 'utf-8');
+            return JSON.parse(raw);
+        }
+    }
+    catch {
+        // Corrupted config - will be overwritten
+    }
+    return null;
+}
+/**
+ * Save user config after successful activation.
+ * License key is encrypted using machine fingerprint (Story 61.2).
+ * File permissions set to 600 (Story 61.4).
+ */
+function saveConfig(config) {
+    // Ensure directories exist with secure permissions
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    setSecureDirPermissions(CONFIG_DIR);
+    const cacheDir = join(CONFIG_DIR, 'cache');
+    mkdirSync(cacheDir, { recursive: true });
+    setSecureDirPermissions(cacheDir);
+    if (config.licenseKey || config.apiKey) {
+        // Use secure config writer which encrypts the key
+        saveSecureConfig({
+            serverUrl: config.serverUrl,
+            mode: config.mode,
+            machineId: config.machineId,
+            activatedAt: config.activatedAt,
+            tier: config.tier,
+            licenseKey: (config.licenseKey ?? config.apiKey),
+        });
+    }
+    else {
+        // Fallback: write without key (should not happen in normal flow)
+        const fallbackConfig = { configVersion: 1, ...config };
+        writeFileSync(CONFIG_FILE, JSON.stringify(fallbackConfig, null, 2) + '\n', 'utf-8');
+    }
+}
+// ── Activate Command ──────────────────────────────────────────────────────
+/**
+ * Activate a Neocortex license.
+ *
+ * Flow:
+ * 1. Validate license key format
+ * 2. Call IP Protection Server to activate
+ * 3. Cache JWT token via LicenseClient
+ * 4. Create/update ~/.neocortex/config.json
+ * 5. Return result with feedback
+ */
+export async function activate(options) {
+    const { licenseKey, serverUrl = DEFAULT_SERVER_URL } = options;
+    // 1. Check if key is provided
+    if (!licenseKey) {
+        return {
+            success: false,
+            message: [
+                'No key provided.',
+                '',
+                'Get your license key at https://neocortex.ornexus.com/login',
+                '',
+                'Usage:',
+                '  neocortex activate YOUR-LICENSE-KEY',
+                '  neocortex activate YOUR-API-KEY',
+            ].join('\n'),
+        };
+    }
+    const trimmedKey = licenseKey.trim();
+    // 2. Detect key type: API key (nxk_) or license key (NX-)
+    const isApiKey = trimmedKey.startsWith('nxk_');
+    if (isApiKey) {
+        // ── API Key Activation Flow (Story 22.04) ──────────────────────────
+        const apiValidation = validateApiKeyFormat(trimmedKey);
+        if (!apiValidation.valid) {
+            return {
+                success: false,
+                message: `Invalid API key: ${apiValidation.error}`,
+            };
+        }
+        // Extract tier from API key -- new format has no tier prefix, server returns tier in response
+        const tierMatch = trimmedKey.match(/^nxk_(free|pro|ent)_/);
+        const apiTierMap = { free: 'free', pro: 'pro', ent: 'enterprise' };
+        const tier = tierMatch?.[1] ? (apiTierMap[tierMatch[1]] ?? 'unknown') : 'unknown'; // will be overridden by server response
+        const machineId = getMachineFingerprint();
+        const cliVersion = getInstalledVersion();
+        // Call /api/v1/license/activate-key
+        let response;
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/license/activate-key`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    api_key: trimmedKey,
+                    machine_id: machineId,
+                    client_version: cliVersion,
+                }),
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => ({}));
+                const errorBody = body;
+                return {
+                    success: false,
+                    message: `API key activation failed: ${errorBody.message ?? `HTTP ${res.status}`}`,
+                };
+            }
+            response = await res.json();
+        }
+        catch {
+            return {
+                success: false,
+                message: [
+                    'Failed to connect to IP Protection Server.',
+                    '',
+                    'Possible causes:',
+                    `  - Server at ${serverUrl} is unreachable`,
+                    '  - Network connectivity issue',
+                    '',
+                    'Workaround: Use --local flag to run in local mode',
+                ].join('\n'),
+            };
+        }
+        const activatedTier = response.tier ?? tier;
+        // Cache JWT token via EncryptedCache
+        const cacheDir = join(CONFIG_DIR, 'cache');
+        try {
+            const encryptedCache = new EncryptedCache({
+                cacheDir,
+                passphrase: trimmedKey,
+            });
+            await encryptedCache.set('neocortex:jwt:token', response.token, response.expires_in * 1000);
+        }
+        catch {
+            // Cache is non-critical (fail-open)
+        }
+        // Save config with API key
+        const config = {
+            serverUrl,
+            mode: 'remote',
+            machineId,
+            activatedAt: new Date().toISOString(),
+            tier: activatedTier,
+            apiKey: trimmedKey,
+        };
+        try {
+            saveConfig(config);
+        }
+        catch (err) {
+            return {
+                success: false,
+                message: `Failed to save configuration: ${err instanceof Error ? err.message : 'unknown error'}`,
+            };
+        }
+        // Refresh stubs and agent description
+        const stubsRefreshed = refreshStubs(cliVersion, { forceCreate: true, targetFilter: 'claude-code' });
+        refreshStubs(cliVersion);
+        updateAgentDescription(cliVersion, activatedTier);
+        updateAgentYaml(cliVersion, activatedTier);
+        return {
+            success: true,
+            message: [
+                'API key activated successfully!',
+                '',
+                `  Tier:    ${activatedTier}`,
+                `  Server:  ${serverUrl}`,
+                `  Expires: ${Math.floor(response.expires_in / 3600)}h`,
+                ...(stubsRefreshed > 0 ? ['  Agents:  updated'] : []),
+                '',
+                'You can now use Neocortex. Run *menu to get started.',
+            ].join('\n'),
+            tier: activatedTier,
+            serverUrl,
+            configPath: CONFIG_FILE,
+        };
+    }
+    // ── License Key Activation Flow (existing) ──────────────────────────────
+    const validation = validateLicenseKeyFormat(trimmedKey);
+    if (!validation.valid) {
+        return {
+            success: false,
+            message: `Invalid license key: ${validation.error}`,
+        };
+    }
+    const normalizedKey = trimmedKey;
+    // Extract tier from key
+    const tierMatch = normalizedKey.match(/^NX-(F|P|E)-/i);
+    const tierMap = { F: 'free', P: 'pro', E: 'enterprise' };
+    const tier = tierMatch?.[1] ? (tierMap[tierMatch[1].toUpperCase()] ?? 'unknown') : 'unknown';
+    // Attempt activation via LicenseClient with EncryptedCache
+    const cacheDir = join(CONFIG_DIR, 'cache');
+    const encryptedCache = new EncryptedCache({
+        cacheDir,
+        passphrase: normalizedKey,
+    });
+    const client = new LicenseClient({
+        serverUrl,
+        licenseKey: normalizedKey,
+        cacheProvider: encryptedCache,
+    });
+    let activationResult;
+    try {
+        activationResult = await client.activate();
+    }
+    catch {
+        return {
+            success: false,
+            message: [
+                'Failed to connect to IP Protection Server.',
+                '',
+                'Possible causes:',
+                `  - Server at ${serverUrl} is unreachable`,
+                '  - Network connectivity issue',
+                '  - Server is still being deployed',
+                '',
+                'Workaround: Use --local flag to run in local mode',
+            ].join('\n'),
+        };
+    }
+    if (!activationResult) {
+        return {
+            success: false,
+            message: [
+                'License activation failed.',
+                '',
+                'Possible causes:',
+                '  - Invalid or expired license key',
+                '  - License already activated on another machine',
+                '  - Server rejected the activation request',
+                '',
+                'Check your license key and try again.',
+                'Contact support if the problem persists.',
+            ].join('\n'),
+        };
+    }
+    // Save config with license key for invoke re-authentication
+    const config = {
+        serverUrl,
+        mode: 'remote',
+        machineId: getMachineFingerprint(),
+        activatedAt: new Date().toISOString(),
+        tier,
+        licenseKey: normalizedKey,
+    };
+    try {
+        saveConfig(config);
+    }
+    catch (err) {
+        return {
+            success: false,
+            message: `Failed to save config to ${CONFIG_FILE}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // Refresh stubs if version mismatch detected (Story 55.1)
+    const cliVersion = getInstalledVersion();
+    const stubsRefreshed = refreshStubs(cliVersion, {
+        forceCreate: true,
+        targetFilter: 'claude-code',
+    });
+    // Also refresh other existing targets (without forceCreate)
+    refreshStubs(cliVersion);
+    // Update agent description with activated tier and version
+    updateAgentDescription(cliVersion, tier);
+    // Update agent YAML with version and tier (Story 55.2)
+    updateAgentYaml(cliVersion, tier);
+    return {
+        success: true,
+        message: [
+            `License activated successfully!`,
+            '',
+            `  Tier:    ${tier}`,
+            `  Server:  ${serverUrl}`,
+            `  Expires: ${Math.floor(activationResult.expiresIn / 3600)}h`,
+            ...(stubsRefreshed > 0 ? ['  Agents:  updated'] : []),
+            '',
+            'You can now use Neocortex. Run *menu to get started.',
+        ].join('\n'),
+        tier,
+        serverUrl,
+        configPath: CONFIG_FILE,
+    };
+}

package/packages/client/dist/commands/cache-status.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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 { ClientCircuitBreaker, CircuitState } from '../resilience/circuit-breaker.js';
+import type { OfflineTelemetryQueue } from '../telemetry/offline-queue.js';
+export interface CacheStatusInfo {
+    totalEntries: number;
+    totalSizeBytes: number;
+    totalSizeFormatted: string;
+    oldestEntry: Date | null;
+    newestEntry: Date | null;
+    staleEntries: number;
+    circuitState: CircuitState;
+    lastSync: Date | null;
+    telemetryQueueSize: number;
+}
+export interface CacheStatusOptions {
+    cacheDir: string;
+    circuitBreaker: ClientCircuitBreaker;
+    telemetryQueue: OfflineTelemetryQueue;
+    staleThresholdMs?: number;
+}
+/**
+ * Gather comprehensive cache status information.
+ */
+export declare function getCacheStatus(options: CacheStatusOptions): Promise<CacheStatusInfo>;
+/**
+ * Format cache status as a human-readable string for terminal output.
+ */
+export declare function formatCacheStatus(info: CacheStatusInfo): string;

package/packages/client/dist/commands/cache-status.js

@@ -0,0 +1,112 @@
+/**
+ * @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 - Cache Status Command
+ *
+ * Displays comprehensive cache and circuit breaker status information.
+ * Shows entry count, total size, age range, stale entries, circuit state,
+ * and telemetry queue stats.
+ *
+ * Story 42.9 - AC7
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+// ── Implementation ──────────────────────────────────────────────────────
+/**
+ * Gather comprehensive cache status information.
+ */
+export async function getCacheStatus(options) {
+    const staleThreshold = options.staleThresholdMs ?? 86_400_000; // 24h default
+    let totalEntries = 0;
+    let totalSizeBytes = 0;
+    let staleEntries = 0;
+    let oldestEntry = null;
+    let newestEntry = null;
+    try {
+        const entries = await readdir(options.cacheDir);
+        const encFiles = entries.filter((e) => e.endsWith('.enc'));
+        totalEntries = encFiles.length;
+        const now = Date.now();
+        for (const file of encFiles) {
+            try {
+                const filePath = join(options.cacheDir, file);
+                const fileStat = await stat(filePath);
+                totalSizeBytes += fileStat.size;
+                const mtime = fileStat.mtime;
+                if (!oldestEntry || mtime < oldestEntry)
+                    oldestEntry = mtime;
+                if (!newestEntry || mtime > newestEntry)
+                    newestEntry = mtime;
+                if (now - mtime.getTime() > staleThreshold) {
+                    staleEntries++;
+                }
+            }
+            catch {
+                // Skip files that can't be stat'd
+            }
+        }
+    }
+    catch {
+        // Cache directory doesn't exist or can't be read
+    }
+    const circuitState = options.circuitBreaker.getState().state;
+    let telemetryQueueSize = 0;
+    try {
+        const queueStats = await options.telemetryQueue.getStats();
+        telemetryQueueSize = queueStats.count;
+    }
+    catch {
+        // Queue unavailable
+    }
+    return {
+        totalEntries,
+        totalSizeBytes,
+        totalSizeFormatted: formatBytes(totalSizeBytes),
+        oldestEntry,
+        newestEntry,
+        staleEntries,
+        circuitState,
+        lastSync: newestEntry, // Most recent cache write approximates last sync
+        telemetryQueueSize,
+    };
+}
+/**
+ * Format cache status as a human-readable string for terminal output.
+ */
+export function formatCacheStatus(info) {
+    const lines = [
+        '+-------------------------------------------------+',
+        '|  NEOCORTEX CACHE STATUS                         |',
+        '+-------------------------------------------------+',
+        `|  Total entries:    ${String(info.totalEntries).padEnd(29)}|`,
+        `|  Total size:       ${info.totalSizeFormatted.padEnd(29)}|`,
+        `|  Oldest entry:     ${(info.oldestEntry?.toISOString() ?? 'N/A').padEnd(29)}|`,
+        `|  Newest entry:     ${(info.newestEntry?.toISOString() ?? 'N/A').padEnd(29)}|`,
+        `|  Stale entries:    ${String(info.staleEntries).padEnd(29)}|`,
+        '|-------------------------------------------------|',
+        `|  Circuit breaker:  ${info.circuitState.padEnd(29)}|`,
+        `|  Last sync:        ${(info.lastSync?.toISOString() ?? 'N/A').padEnd(29)}|`,
+        `|  Telemetry queue:  ${(info.telemetryQueueSize + ' events').padEnd(29)}|`,
+        '+-------------------------------------------------+',
+    ];
+    return lines.join('\n');
+}
+// ── Helpers ─────────────────────────────────────────────────────────────
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    const value = bytes / Math.pow(1024, i);
+    return `${value.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}

package/packages/client/dist/commands/invoke.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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.
+ */
+export interface InvokeOptions {
+    /** Raw args from the user (e.g., "*yolo @docs/stories/1.1.story.md") */
+    readonly args: string;
+    /** Project root directory (default: cwd) */
+    readonly projectRoot?: string;
+    /** Output format: 'json' for full response, 'plain' for instructions only */
+    readonly format?: 'json' | 'plain';
+    /** Server URL override */
+    readonly serverUrl?: string;
+    /** Platform target (default: 'claude-code') */
+    readonly platformTarget?: string;
+}
+export interface InvokeResult {
+    readonly success: boolean;
+    readonly instructions?: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly error?: string;
+    readonly exitCode: number;
+}
+interface StateSnapshot {
+    readonly config: {
+        readonly project_name: string;
+        readonly default_branch: string;
+        readonly language: string;
+        readonly yolo_mode?: boolean;
+        readonly user_name?: string;
+        readonly worktree_base?: string;
+        readonly max_parallel_stories?: number;
+    };
+    readonly stories: Record<string, Record<string, unknown>>;
+    readonly epics: Record<string, Record<string, unknown>>;
+}
+/**
+ * Read state.json and construct a sanitized snapshot for the server.
+ * Relative paths only - no absolute paths sent to server.
+ */
+export declare function collectStateSnapshot(projectRoot: string): StateSnapshot;
+/**
+ * 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 declare function invoke(options: InvokeOptions): Promise<InvokeResult>;
+/**
+ * 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 declare function invokeCliHandler(argv: string[]): Promise<number>;
+export {};