@ornexus/neocortex 4.0.1

package/packages/client/dist/resilience/recovery-detector.js

@@ -0,0 +1,74 @@
+/**
+ * @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.
+ */
+// ── RecoveryDetector ─────────────────────────────────────────────────────
+export class RecoveryDetector {
+    actions;
+    constructor(actions) {
+        this.actions = actions;
+    }
+    /**
+     * Execute full recovery sequence.
+     * Each step is independent - failures are captured but don't block others.
+     */
+    async onRecovery() {
+        const result = {
+            circuitClosed: false,
+            jwtRefreshed: false,
+            cacheSynced: false,
+            telemetryFlushed: { sent: 0, failed: 0 },
+            notification: '[ONLINE] Server connection restored',
+        };
+        // Step 1: Close circuit breaker
+        try {
+            await this.actions.circuitBreaker.recordSuccess();
+            result.circuitClosed = true;
+        }
+        catch {
+            // Non-critical: breaker will close on next successful call
+        }
+        // Step 2: Re-validate JWT
+        try {
+            const token = await this.actions.licenseClient.getToken();
+            result.jwtRefreshed = token !== null;
+        }
+        catch {
+            // Non-critical: will be retried on next server call
+        }
+        // Step 3: Sync cache (background - just attempt, don't block)
+        try {
+            // We don't actually sync here - the next resolver call will
+            // update the cache automatically via fetchWithCacheFallback.
+            // We just mark as synced since the circuit is now closed.
+            result.cacheSynced = true;
+        }
+        catch {
+            // Non-critical
+        }
+        // Step 4: Flush telemetry queue
+        try {
+            const flushResult = await this.actions.telemetryQueue.flush(async (events) => {
+                const response = await fetch(`${this.actions.serverUrl}/api/v1/telemetry/batch`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ events }),
+                });
+                return response.ok;
+            });
+            result.telemetryFlushed = flushResult;
+        }
+        catch {
+            // Non-critical: queue will be flushed on next recovery
+        }
+        return result;
+    }
+}

package/packages/client/dist/resolvers/asset-resolver.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @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 - AssetResolver Interface
+ *
+ * Strategy pattern interface for resolving pipeline assets.
+ * Implementations: LocalResolver (filesystem) and RemoteResolver (HTTP API).
+ */
+import type { AssembledPrompt, PipelineContext, ResolverMode, SkillContent, StandardContent, StepContent, StepRegistry } from '../types/index.js';
+/**
+ * AssetResolver - Core interface for the thin client abstraction layer.
+ *
+ * Enables the CLI to resolve pipeline assets (steps, skills, standards)
+ * from either local filesystem or remote server, transparently.
+ */
+export interface AssetResolver {
+    /** The mode this resolver operates in */
+    readonly mode: ResolverMode;
+    /**
+     * Resolve a pipeline step by its ID.
+     *
+     * @param stepId - Step identifier (e.g., "step-c-01-setup-branch")
+     * @param context - Current pipeline context for variable substitution
+     * @returns Resolved step content with parsed frontmatter
+     */
+    resolveStep(stepId: string, context: PipelineContext): Promise<StepContent>;
+    /**
+     * Resolve a skill by its ID.
+     *
+     * @param skillId - Skill identifier (e.g., "tdd-guardian")
+     * @param context - Current pipeline context
+     * @returns Resolved skill content with metadata
+     */
+    resolveSkill(skillId: string, context: PipelineContext): Promise<SkillContent>;
+    /**
+     * Resolve a standard by its ID.
+     *
+     * @param standardId - Standard identifier (e.g., "testing/tdd-practices")
+     * @returns Resolved standard content
+     */
+    resolveStandard(standardId: string): Promise<StandardContent>;
+    /**
+     * Resolve the step registry (step-registry.json).
+     *
+     * @returns Parsed step registry with all step definitions
+     */
+    resolveRegistry(): Promise<StepRegistry>;
+    /**
+     * Assemble a complete prompt for a step.
+     *
+     * Combines step content, required skills, and standards with
+     * variable substitution from the pipeline context.
+     *
+     * @param stepId - Step to assemble prompt for
+     * @param context - Current pipeline context
+     * @returns Fully assembled prompt ready for execution
+     */
+    assemblePrompt(stepId: string, context: PipelineContext): Promise<AssembledPrompt>;
+    /**
+     * Check if this resolver is available and properly configured.
+     *
+     * @returns true if resolver can serve requests
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Release any resources held by this resolver.
+     */
+    dispose(): Promise<void>;
+}

package/packages/client/dist/resolvers/asset-resolver.js

@@ -0,0 +1,13 @@
+/**
+ * @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 {};

package/packages/client/dist/resolvers/local-resolver.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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 './asset-resolver.js';
+import { ResolverMode, type AssembledPrompt, type LocalResolverOptions, type PipelineContext, type SkillContent, type StandardContent, type StepContent, type StepRegistry } from '../types/index.js';
+export declare class LocalResolver implements AssetResolver {
+    readonly mode = ResolverMode.LOCAL;
+    private readonly projectRoot;
+    constructor(options: LocalResolverOptions);
+    resolveStep(stepId: string, _context: PipelineContext): Promise<StepContent>;
+    resolveSkill(skillId: string, _context: PipelineContext): Promise<SkillContent>;
+    resolveStandard(standardId: string): Promise<StandardContent>;
+    resolveRegistry(): Promise<StepRegistry>;
+    assemblePrompt(stepId: string, context: PipelineContext): Promise<AssembledPrompt>;
+    isAvailable(): Promise<boolean>;
+    dispose(): Promise<void>;
+}

package/packages/client/dist/resolvers/local-resolver.js

@@ -0,0 +1,218 @@
+/**
+ * @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 - LocalResolver
+ *
+ * Resolves pipeline assets from the local filesystem.
+ * Used in development mode when core/ directory is available locally.
+ * Replicates the current CLI behavior of reading .md files directly.
+ */
+import { readFile, access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { ResolverMode, } from '../types/index.js';
+// ── Frontmatter Parser ───────────────────────────────────────────────────
+const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---/;
+/**
+ * Parse YAML-like frontmatter from markdown content.
+ * Simple key-value parser sufficient for step/skill frontmatter.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match) {
+        return { frontmatter: {}, body: content };
+    }
+    const frontmatter = {};
+    const lines = match[1].split('\n');
+    for (const line of lines) {
+        const colonIndex = line.indexOf(':');
+        if (colonIndex === -1)
+            continue;
+        const key = line.slice(0, colonIndex).trim().replace(/^['"]|['"]$/g, '');
+        let value = line.slice(colonIndex + 1).trim();
+        // Remove surrounding quotes
+        if (typeof value === 'string') {
+            value = value.replace(/^['"]|['"]$/g, '');
+        }
+        // Parse booleans
+        if (value === 'true')
+            value = true;
+        else if (value === 'false')
+            value = false;
+        frontmatter[key] = value;
+    }
+    const body = content.slice(match[0].length).trimStart();
+    return { frontmatter, body };
+}
+// ── Step ID to File Path Mapping ─────────────────────────────────────────
+/**
+ * Map step ID to file path within core/steps/.
+ *
+ * Step IDs follow the pattern: step-{category}-{order}-{name}
+ * File paths: core/steps/steps-{category}/{id}.md
+ */
+function stepIdToPath(stepId) {
+    // Extract category from step ID: step-c-01-setup-branch -> c
+    // step-r-fix-blocked -> r, step-u-init -> u, step-p-01-idea-diagnose -> p, step-e-01-epic-init -> e
+    const parts = stepId.split('-');
+    if (parts.length < 3) {
+        throw new Error(`Invalid step ID format: ${stepId}`);
+    }
+    const category = parts[1]; // c, r, u, p, e
+    const categoryMap = {
+        c: 'steps-c',
+        r: 'steps-r',
+        u: 'steps-u',
+        p: 'steps-p',
+        e: 'steps-e',
+    };
+    const dir = categoryMap[category];
+    if (!dir) {
+        throw new Error(`Unknown step category '${category}' in step ID: ${stepId}`);
+    }
+    return `core/steps/${dir}/${stepId}.md`;
+}
+// ── LocalResolver Implementation ─────────────────────────────────────────
+export class LocalResolver {
+    mode = ResolverMode.LOCAL;
+    projectRoot;
+    constructor(options) {
+        this.projectRoot = resolve(options.projectRoot);
+    }
+    async resolveStep(stepId, _context) {
+        const relativePath = stepIdToPath(stepId);
+        const fullPath = join(this.projectRoot, relativePath);
+        const raw = await readFile(fullPath, 'utf-8');
+        const { frontmatter, body } = parseFrontmatter(raw);
+        return {
+            id: stepId,
+            content: body,
+            frontmatter,
+        };
+    }
+    async resolveSkill(skillId, _context) {
+        // Skills are organized in: core/skills/{category}/{skillId}.md
+        // or: core/skills/step-skills/{step}/{skillId}.md
+        // Try multiple paths to find the skill
+        const searchPaths = [
+            `core/skills/${skillId}.md`,
+            `core/skills/step-skills/${skillId}.md`,
+        ];
+        // Also try with nested path: "diagnose/prompt-enricher" -> core/skills/step-skills/diagnose/prompt-enricher.md
+        if (skillId.includes('/')) {
+            searchPaths.unshift(`core/skills/step-skills/${skillId}.md`);
+            searchPaths.unshift(`core/skills/${skillId}.md`);
+        }
+        let raw = null;
+        let resolvedPath = '';
+        for (const searchPath of searchPaths) {
+            const fullPath = join(this.projectRoot, searchPath);
+            try {
+                raw = await readFile(fullPath, 'utf-8');
+                resolvedPath = searchPath;
+                break;
+            }
+            catch {
+                // Try next path
+            }
+        }
+        if (raw === null) {
+            throw new Error(`Skill '${skillId}' not found. Searched: ${searchPaths.join(', ')}`);
+        }
+        const { frontmatter, body } = parseFrontmatter(raw);
+        return {
+            id: skillId,
+            content: body,
+            metadata: { ...frontmatter, resolvedPath },
+        };
+    }
+    async resolveStandard(standardId) {
+        const fullPath = join(this.projectRoot, 'core', 'standards', standardId);
+        let content;
+        try {
+            content = await readFile(fullPath, 'utf-8');
+        }
+        catch {
+            // Try with .md extension if not present
+            if (!standardId.endsWith('.md')) {
+                content = await readFile(`${fullPath}.md`, 'utf-8');
+            }
+            else {
+                throw new Error(`Standard '${standardId}' not found at ${fullPath}`);
+            }
+        }
+        return {
+            id: standardId,
+            content,
+        };
+    }
+    async resolveRegistry() {
+        const fullPath = join(this.projectRoot, 'core', 'data', 'step-registry.json');
+        const raw = await readFile(fullPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    async assemblePrompt(stepId, context) {
+        // Resolve the step content
+        const step = await this.resolveStep(stepId, context);
+        // Build variables map from context
+        const variables = {
+            '{story_id}': context.storyId,
+            '{story_title}': context.storyTitle,
+            '{step_id}': stepId,
+            '{step_name}': step.frontmatter['name'] || stepId,
+            '{current_status}': context.currentStatus,
+            '{epic_id}': context.epicId,
+            '{branch_name}': context.branchName,
+            '{platform_target}': context.platformTarget,
+        };
+        // Substitute variables in step content
+        let prompt = step.content;
+        for (const [key, value] of Object.entries(variables)) {
+            prompt = prompt.replaceAll(key, value);
+        }
+        // Resolve skills referenced in step frontmatter
+        const includedSkills = [];
+        const skillsRef = step.frontmatter['skills'];
+        if (skillsRef && typeof skillsRef === 'string') {
+            const skillIds = skillsRef.split(',').map((s) => s.trim());
+            for (const sid of skillIds) {
+                try {
+                    const skill = await this.resolveSkill(sid, context);
+                    prompt += `\n\n---\n\n# Skill: ${sid}\n\n${skill.content}`;
+                    includedSkills.push(sid);
+                }
+                catch {
+                    // Skill not found - skip
+                }
+            }
+        }
+        return {
+            prompt,
+            variables,
+            includedSkills,
+            includedStandards: [],
+        };
+    }
+    async isAvailable() {
+        try {
+            const corePath = join(this.projectRoot, 'core');
+            await access(corePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async dispose() {
+        // LocalResolver holds no resources to release
+    }
+}

package/packages/client/dist/resolvers/remote-resolver.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @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 - RemoteResolver
+ *
+ * Resolves pipeline assets from the IP Protection Server via HTTP API.
+ * Used in production mode when core/ directory is not available locally.
+ * Supports retry with exponential backoff, timeouts, and cache fallback.
+ */
+import type { AssetResolver } from './asset-resolver.js';
+import { ResolverMode, type AssembledPrompt, type PipelineContext, type RemoteResolverOptions, type SkillContent, type StandardContent, type StepContent, type StepRegistry } from '../types/index.js';
+export declare class RemoteResolverError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly endpoint?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, endpoint?: string | undefined);
+}
+export declare class RemoteResolver implements AssetResolver {
+    readonly mode = ResolverMode.REMOTE;
+    private readonly serverUrl;
+    private readonly licenseKey;
+    private readonly timeout;
+    private readonly retryCount;
+    /**
+     * Persistent cache -- used for registry only.
+     * P70.06: NEVER used for step/skill/standard content (those live in
+     * `assetCache` and only in process memory).
+     */
+    private readonly cache;
+    /**
+     * In-memory LRU cache for asset content (Epic P70.06).
+     * Volatile: discarded on process exit. Never persisted to disk.
+     */
+    private readonly assetCache;
+    private readonly licenseClient;
+    constructor(options: RemoteResolverOptions);
+    resolveStep(stepId: string, _context: PipelineContext): Promise<StepContent>;
+    resolveSkill(skillId: string, _context: PipelineContext): Promise<SkillContent>;
+    resolveStandard(standardId: string): Promise<StandardContent>;
+    resolveRegistry(): Promise<StepRegistry>;
+    assemblePrompt(stepId: string, context: PipelineContext): Promise<AssembledPrompt>;
+    isAvailable(): Promise<boolean>;
+    dispose(): Promise<void>;
+    /**
+     * Build authorization headers for API requests.
+     * When a LicenseClient is available, uses JWT token from it.
+     * Story 31.04: NEVER sends raw license key as Bearer token.
+     * If JWT is unavailable, omits Authorization header entirely.
+     * Server will return 401, which fetchWithRetry handles via forceRefresh.
+     */
+    private buildHeaders;
+    /**
+     * Execute HTTP request with retry and exponential backoff.
+     * Handles 401 specially: if a licenseClient is available, attempts
+     * forceRefresh() and retries once with the new token.
+     */
+    private fetchWithRetry;
+    /**
+     * Fetch with persistent cache fallback: try HTTP first, fall back to cache
+     * on failure. On successful HTTP response, update the cache.
+     *
+     * P70.06: ONLY the registry uses this path. Asset content (step/skill/
+     * standard) uses {@link fetchWithInMemoryCache} so it never touches disk.
+     */
+    private fetchWithCacheFallback;
+    /**
+     * P70.06: fetch with VOLATILE in-memory cache fallback.
+     *
+     * Identical structure to {@link fetchWithCacheFallback} but the backing
+     * store is {@link InMemoryAssetCache} -- entries live only in the running
+     * process memory, never written to disk.
+     *
+     * When the server is unreachable and the in-memory cache is empty (e.g.
+     * first invocation of a fresh CLI process), the original error is
+     * re-thrown instead of silently degrading to a stale disk cache.
+     */
+    private fetchWithInMemoryCache;
+    /**
+     * Sleep for the specified duration.
+     */
+    private sleep;
+}