@ornexus/neocortex 4.60.73 → 4.60.75

package/packages/client/dist/yoloop/discovery-hook.js

@@ -1,300 +1,2 @@
-/**
- * @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.
- */
-/**
- * Epic P120.04 -- Client-side discovery hook (extends P101.07 pattern).
- *
- * Pre-request hook that, when `YOLOOP_AUTO_DISCOVERY=on` and trigger is
- * `*yoloop` resolving to a directory, calls `discoverEpicsFromDir()` (P120.01)
- * + `mergeDiscoveredIntoState()` (P120.02) on the client BEFORE sending the
- * invoke request. Server (P120.05) sees the enriched state in
- * `body.stateSnapshot.epics`, relaxing `EPIC_NOT_FOUND` for filesystem epics.
- *
- * Hook follows P101.07 pattern (lazy dynamic import for tree-shaking via
- * the wrapper in `invoke-hooks.ts`, fail-soft try/catch, mutate stateSnapshot
- * in place).
- *
- * Activation conditions (ALL must hold):
- *   1. `featureFlag === true` -- operator opt-in via `YOLOOP_AUTO_DISCOVERY=on`
- *   2. Args resolve to a yoloop trigger (regex per P101.07)
- *   3. Args target via `@<path>` resolves to a directory
- *
- * Fail-open contract: ANY error in discovery / merge / fs-resolution is
- * caught + logged (warn) + returns `{ applied: false, reason }`. The
- * caller (invoke.ts wrapper) ALSO catches outermost. Hook NEVER blocks
- * the invoke request. Worst case: state is unenriched + server falls back
- * to existing canonical resolver (pre-P120 behavior).
- *
- * Pattern references:
- *  - P101.07 (yoloop pre-request hook) -- exact pattern reused
- *  - P120.01 (discoverEpicsFromDir) -- consumed via local SSoT-Shadow inline
- *  - P120.02 (mergeDiscoveredIntoState) -- consumed via local SSoT-Shadow inline
- *  - P120.03 (feature flag) -- gating variable
- *  - P107.02 (architecture-policy hook) -- secondary reference for
- *    fail-soft + dynamic import + state mutation
- *
- * Pre-request hook order (client-side, before invoke POST):
- *   1. P121.05: maybeAutoResolveYoloopArgs (invoke-hooks.ts)  -- rewrite empty args
- *   2. P101.07: yoloop client state collection                -- read ~/.neocortex/yoloop-state.json
- *   3. P120.04: maybeRunDiscoveryHook (this hook)             -- scan args dir for epics
- *   4. P107.02: architecture-policy reader                    -- attach state.architecture_policy
- *   5. POST /invoke
- *
- * P121.05 runs FIRST so that subsequent hooks (P101.07, this hook) see the
- * rewritten args. The discovery hook itself sees `*yoloop @docs/epics/`
- * after P121.05 fires and proceeds normally.
- */
-import { existsSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
-import { basename, dirname, resolve, isAbsolute } from 'node:path';
-// P120.04: import from local SSoT-Shadow inline mirror (P117.01 pattern).
-// See `./shared-discover-epics.ts` for sync rules and drift test enforcement
-// in `client/__tests__/discover-shared-sync.test.ts`.
-import { discoverEpicsFromDir, mergeDiscoveredIntoState, buildDefaultDiscoveryFs, } from './shared-discover-epics.js';
-import { extractYoloopTargetPath, isYoloopInvocation, } from './target-normalization.js';
-// =====================================================================
-// Internal helpers
-// =====================================================================
-/**
- * Resolve a `@<path>` token to an absolute path, given a project root.
- * Pure function: zero I/O.
- */
-function resolveAtPath(token, projectRoot) {
-    if (isAbsolute(token))
-        return token;
-    return resolve(projectRoot, token);
-}
-/**
- * Keep on-disk `.neocortex/state.json` aligned with the enriched snapshot.
- *
- * The server receives `stateSnapshot`, so snapshot mutation is sufficient for
- * the current invoke. Persisting discovered epics removes the next-iteration
- * EPIC_NOT_FOUND failure and matches the operator expectation that filesystem
- * epics are registered once discovered. This writer reads state.json fresh so
- * transient request-only fields (for example `stateSnapshot.yoloop`) are not
- * accidentally stored in the project state.
- */
-function persistDiscoveredStateJson(projectRoot, discovered, logger) {
-    if (discovered.epics.length === 0)
-        return;
-    const statePath = resolve(projectRoot, '.neocortex', 'state.json');
-    if (!existsSync(statePath))
-        return;
-    try {
-        const raw = readFileSync(statePath, 'utf8');
-        const diskState = JSON.parse(raw);
-        const merge = mergeDiscoveredIntoState(diskState, discovered);
-        if (merge.added.length === 0 && merge.storiesAdded === 0)
-            return;
-        diskState.last_updated = new Date().toISOString();
-        const tmpPath = `${statePath}.tmp.${process.pid}.${Date.now()}`;
-        writeFileSync(tmpPath, `${JSON.stringify(diskState, null, 2)}\n`, 'utf8');
-        renameSync(tmpPath, statePath);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        logger?.warn?.(`[neocortex] discovery hook: failed to persist .neocortex/state.json: ${msg}. Proceeding with request snapshot only.`);
-    }
-}
-function filterDiscoveryToFile(result, absPath) {
-    const targetBase = basename(absPath);
-    const epics = result.epics.filter((epic) => {
-        return epic.path === absPath || epic.filename === targetBase;
-    });
-    const epicIds = new Set(epics.map((epic) => epic.id));
-    return {
-        epics: Object.freeze(epics),
-        warnings: Object.freeze([
-            ...result.warnings,
-            ...(epics.length === 0
-                ? [`single-file discovery found no matching epic descriptor for ${targetBase}`]
-                : []),
-        ]),
-        skipped: Object.freeze([
-            ...result.skipped,
-            ...result.epics
-                .filter((epic) => !epicIds.has(epic.id))
-                .map((epic) => `${epic.filename}: skipped (not requested file)`),
-        ]),
-    };
-}
-// =====================================================================
-// Public API
-// =====================================================================
-/**
- * Run discovery + merge if hook conditions are met.
- *
- * Async because `buildDefaultDiscoveryFs()` lazy-imports `node:fs` /
- * `node:path` (tree-shake friendly per P120.01 design). Returns
- * synchronously-resolvable promise in the no-op cases (flag off, non-yoloop
- * trigger, file not dir, missing dir) -- discovery work only happens on
- * the happy path.
- *
- * **Never throws**. ANY error is caught, logged via `logger.warn`, and
- * returned as `{ applied: false, reason }`. Caller continues normal
- * invoke flow without enrichment.
- *
- * @param ctx hook context (args + projectRoot + stateSnapshot + flag + logger)
- * @returns DiscoveryHookResult with telemetry counters
- */
-export async function runDiscoveryHook(ctx) {
-    // -------------------------------------------------------------------
-    // Activation conditions (ordered cheap-to-expensive)
-    // -------------------------------------------------------------------
-    // 1. Feature flag check (zero I/O, fastest)
-    if (!ctx.featureFlag) {
-        return {
-            applied: false,
-            added: Object.freeze([]),
-            skipped: Object.freeze([]),
-            storiesAdded: 0,
-            reason: 'flag off',
-        };
-    }
-    // 2. Yoloop trigger detection (regex over args)
-    if (!isYoloopInvocation(ctx.args)) {
-        return {
-            applied: false,
-            added: Object.freeze([]),
-            skipped: Object.freeze([]),
-            storiesAdded: 0,
-            reason: 'not a yoloop trigger',
-        };
-    }
-    // 3. Extract target path arg
-    const pathToken = extractYoloopTargetPath(ctx.args, ctx.projectRoot);
-    if (!pathToken) {
-        return {
-            applied: false,
-            added: Object.freeze([]),
-            skipped: Object.freeze([]),
-            storiesAdded: 0,
-            reason: 'no path arg',
-        };
-    }
-    // 4. Resolve to absolute path
-    let absPath;
-    try {
-        absPath = resolveAtPath(pathToken, ctx.projectRoot);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        ctx.logger?.warn?.(`[neocortex] discovery hook: path resolution failed: ${msg}. Proceeding without enrichment.`);
-        return {
-            applied: false,
-            added: Object.freeze([]),
-            skipped: Object.freeze([]),
-            storiesAdded: 0,
-            reason: 'path resolution failed',
-        };
-    }
-    // 5. Verify path exists and determine scan mode.
-    let isDir = false;
-    let isFile = false;
-    try {
-        if (existsSync(absPath)) {
-            const stat = statSync(absPath);
-            isDir = stat.isDirectory();
-            isFile = stat.isFile();
-        }
-    }
-    catch {
-        // statSync error -> treat as missing (fail-open)
-        isDir = false;
-        isFile = false;
-    }
-    if (!isDir && !isFile) {
-        return {
-            applied: false,
-            added: Object.freeze([]),
-            skipped: Object.freeze([]),
-            storiesAdded: 0,
-            reason: 'path not found',
-        };
-    }
-    // -------------------------------------------------------------------
-    // Activation: run discovery + merge
-    // -------------------------------------------------------------------
-    try {
-        const fs = await buildDefaultDiscoveryFs();
-        const scanDir = isDir ? absPath : dirname(absPath);
-        const rawResult = discoverEpicsFromDir(scanDir, fs);
-        const result = isFile ? filterDiscoveryToFile(rawResult, absPath) : rawResult;
-        // Even if zero epics discovered, we still count this as "applied" for
-        // observability (caller knows hook ran). State stays untouched.
-        const merge = mergeDiscoveredIntoState(ctx.stateSnapshot, result);
-        persistDiscoveredStateJson(ctx.projectRoot, result, ctx.logger);
-        // Telemetry: emit info if anything was added
-        if (merge.added.length > 0 || merge.storiesAdded > 0) {
-            ctx.logger?.info?.(`[neocortex] discovered ${merge.added.length} epic(s), ${merge.storiesAdded} story-ies from ${isDir ? absPath : basename(absPath)}`);
-        }
-        // Surface non-fatal warnings (e.g., orphan stories, ID collisions)
-        for (const w of result.warnings) {
-            ctx.logger?.warn?.(`[neocortex] discovery: ${w}`);
-        }
-        return {
-            applied: true,
-            added: merge.added,
-            skipped: merge.skipped,
-            storiesAdded: merge.storiesAdded,
-        };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        ctx.logger?.warn?.(`[neocortex] discovery hook failed: ${msg}. Proceeding without enrichment.`);
-        return {
-            applied: false,
-            added: Object.freeze([]),
-            skipped: Object.freeze([]),
-            storiesAdded: 0,
-            reason: `error: ${msg}`,
-        };
-    }
-}
-/**
- * Async wrapper with lazy-load semantics + outermost defensive try/catch.
- *
- * Designed to be invoked from `invoke-hooks.ts`. Performs the same
- * `featureFlag` short-circuit as `runDiscoveryHook` to keep the async
- * import truly tree-shakeable when the flag is off. Wraps the inner call
- * in an additional try/catch as defense-in-depth (the hook itself is
- * already fail-open, but module-load errors are caught here).
- */
-export async function maybeRunDiscoveryHook(ctx) {
-    // Defense-in-depth: short-circuit BEFORE doing any work if flag is off.
-    // Note: in practice, callers (invoke-hooks.ts) also check the flag
-    // before importing this module to maximize tree-shaking. This is a
-    // belt-and-suspenders guard.
-    if (!ctx.featureFlag) {
-        return {
-            applied: false,
-            added: Object.freeze([]),
-            skipped: Object.freeze([]),
-            storiesAdded: 0,
-            reason: 'flag off',
-        };
-    }
-    try {
-        return await runDiscoveryHook(ctx);
-    }
-    catch (err) {
-        // runDiscoveryHook is itself fail-open; this is defense-in-depth.
-        const msg = err instanceof Error ? err.message : String(err);
-        ctx.logger?.warn?.(`[neocortex] discovery hook (outer) failed: ${msg}. Proceeding without enrichment.`);
-        return {
-            applied: false,
-            added: Object.freeze([]),
-            skipped: Object.freeze([]),
-            storiesAdded: 0,
-            reason: `outer error: ${msg}`,
-        };
-    }
-}
+import{existsSync as f,readFileSync as h,renameSync as m,statSync as y,writeFileSync as j}from"node:fs";import{basename as p,dirname as b,resolve as l,isAbsolute as O}from"node:path";import{discoverEpicsFromDir as w,mergeDiscoveredIntoState as g,buildDefaultDiscoveryFs as k}from"./shared-discover-epics.js";import{extractYoloopTargetPath as z,isYoloopInvocation as S}from"./target-normalization.js";function v(e,o){return O(e)?e:l(o,e)}function $(e,o,t){if(o.epics.length===0)return;const s=l(e,".neocortex","state.json");if(f(s))try{const i=h(s,"utf8"),r=JSON.parse(i),n=g(r,o);if(n.added.length===0&&n.storiesAdded===0)return;r.last_updated=new Date().toISOString();const a=`${s}.tmp.${process.pid}.${Date.now()}`;j(a,`${JSON.stringify(r,null,2)}
+`,"utf8"),m(a,s)}catch(i){const r=i instanceof Error?i.message:String(i);t?.warn?.(`[neocortex] discovery hook: failed to persist .neocortex/state.json: ${r}. Proceeding with request snapshot only.`)}}function A(e,o){const t=p(o),s=e.epics.filter(r=>r.path===o||r.filename===t),i=new Set(s.map(r=>r.id));return{epics:Object.freeze(s),warnings:Object.freeze([...e.warnings,...s.length===0?[`single-file discovery found no matching epic descriptor for ${t}`]:[]]),skipped:Object.freeze([...e.skipped,...e.epics.filter(r=>!i.has(r.id)).map(r=>`${r.filename}: skipped (not requested file)`)])}}async function D(e){if(!e.featureFlag)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"flag off"};if(!S(e.args))return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"not a yoloop trigger"};const o=z(e.args,e.projectRoot);if(!o)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"no path arg"};let t;try{t=v(o,e.projectRoot)}catch(r){const n=r instanceof Error?r.message:String(r);return e.logger?.warn?.(`[neocortex] discovery hook: path resolution failed: ${n}. Proceeding without enrichment.`),{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"path resolution failed"}}let s=!1,i=!1;try{if(f(t)){const r=y(t);s=r.isDirectory(),i=r.isFile()}}catch{s=!1,i=!1}if(!s&&!i)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"path not found"};try{const r=await k(),n=s?t:b(t),a=w(n,r),c=i?A(a,t):a,d=g(e.stateSnapshot,c);$(e.projectRoot,c,e.logger),(d.added.length>0||d.storiesAdded>0)&&e.logger?.info?.(`[neocortex] discovered ${d.added.length} epic(s), ${d.storiesAdded} story-ies from ${s?t:p(t)}`);for(const u of c.warnings)e.logger?.warn?.(`[neocortex] discovery: ${u}`);return{applied:!0,added:d.added,skipped:d.skipped,storiesAdded:d.storiesAdded}}catch(r){const n=r instanceof Error?r.message:String(r);return e.logger?.warn?.(`[neocortex] discovery hook failed: ${n}. Proceeding without enrichment.`),{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:`error: ${n}`}}}async function I(e){if(!e.featureFlag)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"flag off"};try{return await D(e)}catch(o){const t=o instanceof Error?o.message:String(o);return e.logger?.warn?.(`[neocortex] discovery hook (outer) failed: ${t}. Proceeding without enrichment.`),{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:`outer error: ${t}`}}}export{I as maybeRunDiscoveryHook,D as runDiscoveryHook};

package/packages/client/dist/yoloop/index.js

@@ -1,8 +1 @@
-/**
- * Epic P101.06 -- Client-side yoloop state persistence.
- *
- * Re-exports the YoloopClientStateStore class and wire-format types for
- * consumption by invoke.ts (P101.07 pre/post-request hooks).
- */
-export { YoloopClientStateStore, createDefaultCounters, createDefaultState, } from './yoloop-client-state-store.js';
-export { isYoloopTrigger, readYoloopForRequest, persistYoloopFromResponse, maybeRunDiscoveryHook, } from './invoke-hooks.js';
+import{YoloopClientStateStore as r,createDefaultCounters as t,createDefaultState as a}from"./yoloop-client-state-store.js";import{isYoloopTrigger as s,readYoloopForRequest as l,persistYoloopFromResponse as i,maybeRunDiscoveryHook as u}from"./invoke-hooks.js";export{r as YoloopClientStateStore,t as createDefaultCounters,a as createDefaultState,s as isYoloopTrigger,u as maybeRunDiscoveryHook,i as persistYoloopFromResponse,l as readYoloopForRequest};