principles-disciple 1.71.0 → 1.73.0

package/tests/plugin-config-resolution-cutover.test.ts

@@ -0,0 +1,359 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+import { WorkspaceContext } from '../src/core/workspace-context.js';
+import {
+  resolveWorkspaceDirForRuntimeV2,
+  WorkspaceResolutionError,
+} from '../src/utils/workspace-resolver.js';
+import { validateWorkspaceDir } from '../src/core/workspace-dir-validation.js';
+
+const noopLogger = {
+  info: (..._args: unknown[]) => {},
+  warn: (..._args: unknown[]) => {},
+  error: (..._args: unknown[]) => {},
+  debug: (..._args: unknown[]) => {},
+};
+
+describe('PRI-228: Plugin config resolution cutover', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-pri228-'));
+    WorkspaceContext.clearCache();
+    delete process.env.PD_WORKSPACE_DIR;
+    delete process.env.OPENCLAW_WORKSPACE;
+  });
+
+  afterEach(() => {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* already removed */ }
+    WorkspaceContext.clearCache();
+  });
+
+  describe('fromHookContextExplicit: fail-loud on missing workspaceDir', () => {
+    it('throws when workspaceDir is undefined', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ logger: noopLogger })
+      ).toThrow(/workspace_dir_missing/);
+    });
+
+    it('throws when workspaceDir is empty string', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ workspaceDir: '', logger: noopLogger })
+      ).toThrow(/workspace_dir_missing/);
+    });
+
+    it('throws when workspaceDir is whitespace-only', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ workspaceDir: '   ', logger: noopLogger })
+      ).toThrow(/workspace_dir_missing/);
+    });
+
+    it('throws error with structured reason and nextAction', () => {
+      try {
+        WorkspaceContext.fromHookContextExplicit({ logger: noopLogger });
+        expect.unreachable('Should have thrown');
+      } catch (err) {
+        const msg = (err as Error).message;
+        expect(msg).toContain('workspace_dir_missing');
+        expect(msg).toContain('Runtime V2');
+        expect(msg).toContain('workspaceDir');
+      }
+    });
+  });
+
+  describe('fromHookContextExplicit: reject dangerous paths', () => {
+    it('throws when workspaceDir is home directory', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ workspaceDir: os.homedir(), logger: noopLogger })
+      ).toThrow(/workspace_dir_invalid/);
+    });
+
+    it('throws when workspaceDir is root "/"', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ workspaceDir: '/', logger: noopLogger })
+      ).toThrow(/workspace_dir_invalid/);
+    });
+
+    it('throws when workspaceDir is Windows drive root', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ workspaceDir: 'C:\\', logger: noopLogger })
+      ).toThrow(/workspace_dir_invalid/);
+    });
+
+    it('throws when workspaceDir is home with trailing slash', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ workspaceDir: os.homedir() + '/', logger: noopLogger })
+      ).toThrow(/workspace_dir_invalid/);
+    });
+
+    it('rejects /tmp/.. which normalizes to root "/"', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ workspaceDir: '/tmp/..', logger: noopLogger })
+      ).toThrow(/workspace_dir_invalid/);
+    });
+
+    it('rejects /tmp/../.. which normalizes to root "/"', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ workspaceDir: '/tmp/../..', logger: noopLogger })
+      ).toThrow(/workspace_dir_invalid/);
+    });
+
+    it('rejects home subpath traversal that normalizes to home', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ workspaceDir: os.homedir() + '/subdir/..', logger: noopLogger })
+      ).toThrow(/workspace_dir_invalid/);
+    });
+
+    it('rejects path with repeated separators that normalizes to root', () => {
+      expect(() =>
+        WorkspaceContext.fromHookContextExplicit({ workspaceDir: '/foo/../bar/../..', logger: noopLogger })
+      ).toThrow(/workspace_dir_invalid/);
+    });
+  });
+
+  describe('fromHookContextExplicit: succeed with valid workspaceDir', () => {
+    it('creates context with explicit valid workspaceDir', () => {
+      const wctx = WorkspaceContext.fromHookContextExplicit({
+        workspaceDir: tmpDir,
+        logger: noopLogger,
+      });
+      expect(wctx.workspaceDir).toBe(tmpDir);
+      expect(wctx.stateDir).toBeDefined();
+    });
+
+    it('returns cached instance for same workspaceDir', () => {
+      const wctx1 = WorkspaceContext.fromHookContextExplicit({
+        workspaceDir: tmpDir,
+        logger: noopLogger,
+      });
+      const wctx2 = WorkspaceContext.fromHookContextExplicit({
+        workspaceDir: tmpDir,
+        logger: noopLogger,
+      });
+      expect(wctx1).toBe(wctx2);
+    });
+  });
+
+  describe('fromHookContext (legacy): safe degradation for host enhancement hooks', () => {
+    it('falls back to PathResolver when workspaceDir is missing', () => {
+      process.env.PD_WORKSPACE_DIR = tmpDir;
+      try {
+        const wctx = WorkspaceContext.fromHookContext({ logger: noopLogger });
+        expect(wctx.workspaceDir).toBeTruthy();
+      } finally {
+        delete process.env.PD_WORKSPACE_DIR;
+      }
+    });
+
+    it('only warns (does not throw) on dangerous paths', () => {
+      const warnings: string[] = [];
+      const capturingLogger = {
+        info: (..._args: unknown[]) => {},
+        warn: (...args: unknown[]) => { warnings.push(String(args[0])); },
+        error: (..._args: unknown[]) => {},
+        debug: (..._args: unknown[]) => {},
+      };
+      const wctx = WorkspaceContext.fromHookContext({ workspaceDir: os.homedir(), logger: capturingLogger });
+      expect(wctx).toBeDefined();
+      expect(warnings.some(w => w.includes('LEGACY_PATH_RESOLVER_FALLBACK'))).toBe(true);
+    });
+  });
+
+  describe('resolveWorkspaceDirForRuntimeV2: explicit-only resolution', () => {
+    it('throws WorkspaceResolutionError when workspaceDir is missing', () => {
+      expect(() =>
+        resolveWorkspaceDirForRuntimeV2({}, undefined, 'test-source')
+      ).toThrow(WorkspaceResolutionError);
+
+      try {
+        resolveWorkspaceDirForRuntimeV2({}, undefined, 'test-source');
+        expect.unreachable('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(WorkspaceResolutionError);
+        const wsErr = err as WorkspaceResolutionError;
+        expect(wsErr.reason).toBe('workspace_dir_missing');
+        expect(wsErr.nextAction).toContain('workspaceDir');
+      }
+    });
+
+    it('throws WorkspaceResolutionError when workspaceDir is invalid', () => {
+      expect(() =>
+        resolveWorkspaceDirForRuntimeV2({ workspaceDir: os.homedir() }, undefined, 'test-source')
+      ).toThrow(WorkspaceResolutionError);
+
+      try {
+        resolveWorkspaceDirForRuntimeV2({ workspaceDir: os.homedir() }, undefined, 'test-source');
+        expect.unreachable('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(WorkspaceResolutionError);
+        expect((err as WorkspaceResolutionError).reason).toBe('workspace_dir_invalid');
+      }
+    });
+
+    it('returns normalized workspaceDir when explicit and valid', () => {
+      const result = resolveWorkspaceDirForRuntimeV2(
+        { workspaceDir: tmpDir },
+        undefined,
+        'test-source',
+      );
+      expect(path.resolve(tmpDir)).toBe(result);
+    });
+
+    it('rejects /tmp/.. which normalizes to root', () => {
+      expect(() =>
+        resolveWorkspaceDirForRuntimeV2({ workspaceDir: '/tmp/..' }, undefined, 'test-source')
+      ).toThrow(WorkspaceResolutionError);
+    });
+
+    it('rejects home subpath traversal that normalizes to home', () => {
+      expect(() =>
+        resolveWorkspaceDirForRuntimeV2({ workspaceDir: os.homedir() + '/subdir/..' }, undefined, 'test-source')
+      ).toThrow(WorkspaceResolutionError);
+    });
+
+    it('does NOT fall back to resolveWorkspaceDirFromApi', () => {
+      const mockApi = {
+        logger: noopLogger,
+        runtime: {
+          agent: { resolveAgentWorkspaceDir: () => tmpDir },
+        },
+        config: {},
+      };
+      expect(() =>
+        resolveWorkspaceDirForRuntimeV2({}, mockApi, 'test-source')
+      ).toThrow(WorkspaceResolutionError);
+    });
+  });
+
+  describe('WorkspaceResolutionError: structured output', () => {
+    it('toJSON returns ok:false with reason, message, nextAction', () => {
+      const err = new WorkspaceResolutionError('test msg', 'test_reason', 'do something');
+      const json = err.toJSON();
+      expect(json.ok).toBe(false);
+      expect(json.reason).toBe('test_reason');
+      expect(json.message).toBe('test msg');
+      expect(json.nextAction).toBe('do something');
+    });
+
+    it('is instanceof Error', () => {
+      const err = new WorkspaceResolutionError('test', 'r', 'a');
+      expect(err).toBeInstanceOf(Error);
+      expect(err.name).toBe('WorkspaceResolutionError');
+    });
+  });
+
+  describe('validateWorkspaceDir: dangerous path detection', () => {
+    it('rejects undefined', () => {
+      expect(validateWorkspaceDir(undefined)).toContain('undefined');
+    });
+
+    it('rejects home directory', () => {
+      expect(validateWorkspaceDir(os.homedir())).toContain('home directory');
+    });
+
+    it('rejects root "/"', () => {
+      expect(validateWorkspaceDir('/')).toContain('root');
+    });
+
+    it('rejects empty string', () => {
+      expect(validateWorkspaceDir('')).toBeTruthy();
+    });
+
+    it('rejects Windows drive root', () => {
+      expect(validateWorkspaceDir('C:\\')).toContain('drive root');
+      expect(validateWorkspaceDir('D:\\')).toContain('drive root');
+    });
+
+    it('accepts valid workspace paths', () => {
+      expect(validateWorkspaceDir(tmpDir)).toBeNull();
+      expect(validateWorkspaceDir('/home/user/projects/my-workspace')).toBeNull();
+    });
+  });
+
+  describe('Hook classification: only pain.ts is Runtime V2', () => {
+    it('pain.ts uses fromHookContextExplicit (Runtime V2 entrypoint)', () => {
+      const filePath = path.resolve(__dirname, '..', 'src', 'hooks', 'pain.ts');
+      const content = fs.readFileSync(filePath, 'utf-8');
+      expect(content).toContain('fromHookContextExplicit');
+      expect(content).toContain('resolveWorkspaceDirForRuntimeV2');
+    });
+
+    const hostEnhancementHooks = [
+      'prompt.ts',
+      'lifecycle.ts',
+      'gate.ts',
+      'subagent.ts',
+      'llm.ts',
+    ];
+
+    for (const hookFile of hostEnhancementHooks) {
+      it(hookFile + ' uses fromHookContext (host enhancement — safe degradation)', () => {
+        const filePath = path.resolve(__dirname, '..', 'src', 'hooks', hookFile);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const explicitCalls = content.match(/fromHookContextExplicit/g) ?? [];
+        expect(
+          explicitCalls.length,
+          hookFile + ' should NOT use fromHookContextExplicit — it is a host enhancement hook'
+        ).toBe(0);
+      });
+    }
+  });
+
+  describe('resolveWorkspaceDirForRuntimeV2 has production caller', () => {
+    it('pain.ts calls resolveWorkspaceDirForRuntimeV2', () => {
+      const filePath = path.resolve(__dirname, '..', 'src', 'hooks', 'pain.ts');
+      const content = fs.readFileSync(filePath, 'utf-8');
+      expect(content).toContain('resolveWorkspaceDirForRuntimeV2');
+      const callMatch = content.match(/resolveWorkspaceDirForRuntimeV2\(/g) ?? [];
+      expect(callMatch.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('Prompt hook safe degradation', () => {
+    it('prompt.ts returns early when workspaceDir is missing (does not throw)', () => {
+      const filePath = path.resolve(__dirname, '..', 'src', 'hooks', 'prompt.ts');
+      const content = fs.readFileSync(filePath, 'utf-8');
+      expect(content).toContain("if (!workspaceDir)");
+      expect(content).toContain("skipping PD context injection");
+      expect(content).toContain("return;");
+    });
+
+    it('prompt.ts uses fromHookContext (not fromHookContextExplicit)', () => {
+      const filePath = path.resolve(__dirname, '..', 'src', 'hooks', 'prompt.ts');
+      const content = fs.readFileSync(filePath, 'utf-8');
+      expect(content).toContain('fromHookContext(ctx)');
+      const explicitCalls = content.match(/fromHookContextExplicit/g) ?? [];
+      expect(explicitCalls.length).toBe(0);
+    });
+  });
+
+  describe('Cache isolation between workspaces', () => {
+    it('invalidate clears service caches without removing the instance', () => {
+      const wctx = WorkspaceContext.fromHookContextExplicit({
+        workspaceDir: tmpDir,
+        logger: noopLogger,
+      });
+      const config = wctx.config;
+      wctx.invalidate();
+      const configAfter = wctx.config;
+      expect(config).toBeDefined();
+      expect(configAfter).toBeDefined();
+    });
+
+    it('dispose removes the instance from cache entirely', () => {
+      const wctx1 = WorkspaceContext.fromHookContextExplicit({
+        workspaceDir: tmpDir,
+        logger: noopLogger,
+      });
+      WorkspaceContext.dispose(tmpDir);
+      const wctx2 = WorkspaceContext.fromHookContextExplicit({
+        workspaceDir: tmpDir,
+        logger: noopLogger,
+      });
+      expect(wctx1).not.toBe(wctx2);
+    });
+  });
+});

package/tests/runtime-v2-discovery-guard.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const PLUGIN_SRC = path.resolve(__dirname, '..', 'src');
+
+const DISALLOWED_RUNTIME_V2_IMPORTS = [
+  'nocturnal-config',
+  'nocturnal-runtime',
+  'sleep-cycle',
+  'checkWorkspaceIdle',
+  'loadNocturnalConfigMerged',
+  'idle-trigger',
+];
+
+describe('PRI-228: Runtime V2 discovery guard', () => {
+  const guardedFiles = [
+    { name: 'workspace-resolver.ts', path: path.join(PLUGIN_SRC, 'utils', 'workspace-resolver.ts') },
+    { name: 'workspace-context.ts', path: path.join(PLUGIN_SRC, 'core', 'workspace-context.ts') },
+    { name: 'workspace-dir-service.ts', path: path.join(PLUGIN_SRC, 'core', 'workspace-dir-service.ts') },
+    { name: 'path-resolver.ts', path: path.join(PLUGIN_SRC, 'core', 'path-resolver.ts') },
+  ];
+
+  for (const file of guardedFiles) {
+    describe(file.name + ' isolation', () => {
+      it('does not import nocturnal or idle modules', () => {
+        if (!fs.existsSync(file.path)) return;
+        const content = fs.readFileSync(file.path, 'utf-8');
+        for (const disallowed of DISALLOWED_RUNTIME_V2_IMPORTS) {
+          expect(
+            content.includes(disallowed),
+            file.name + ' must not import legacy discovery path: ' + disallowed,
+          ).toBe(false);
+        }
+      });
+    });
+  }
+
+  describe('resolveWorkspaceDirForRuntimeV2 does not use legacy fallback chain', () => {
+    it('does not call resolveWorkspaceDirFromApi', () => {
+      const filePath = path.join(PLUGIN_SRC, 'utils', 'workspace-resolver.ts');
+      if (!fs.existsSync(filePath)) return;
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const fnMatch = content.match(/function resolveWorkspaceDirForRuntimeV2[\s\S]*?^}/m);
+      if (!fnMatch) {
+        expect.unreachable('resolveWorkspaceDirForRuntimeV2 function not found');
+        return;
+      }
+      const fnBody = fnMatch[0];
+      expect(
+        fnBody.includes('resolveWorkspaceDirFromApi'),
+        'resolveWorkspaceDirForRuntimeV2 must NOT call resolveWorkspaceDirFromApi (legacy fallback)',
+      ).toBe(false);
+      expect(
+        fnBody.includes('PathResolver'),
+        'resolveWorkspaceDirForRuntimeV2 must NOT reference PathResolver (legacy fallback)',
+      ).toBe(false);
+    });
+
+    it('only accepts explicit ctx.workspaceDir', () => {
+      const filePath = path.join(PLUGIN_SRC, 'utils', 'workspace-resolver.ts');
+      if (!fs.existsSync(filePath)) return;
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const fnMatch = content.match(/function resolveWorkspaceDirForRuntimeV2[\s\S]*?^}/m);
+      if (!fnMatch) return;
+      const fnBody = fnMatch[0];
+      expect(fnBody.includes('ctx.workspaceDir')).toBe(true);
+      expect(fnBody.includes('validateWorkspaceDir')).toBe(true);
+    });
+  });
+
+  describe('fromHookContextExplicit validates before delegating', () => {
+    it('validates workspaceDir BEFORE calling fromHookContext', () => {
+      const filePath = path.join(PLUGIN_SRC, 'core', 'workspace-context.ts');
+      if (!fs.existsSync(filePath)) return;
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const fnMatch = content.match(/static fromHookContextExplicit[\s\S]*?^\s{4}\}/m);
+      if (!fnMatch) {
+        expect.unreachable('fromHookContextExplicit method not found');
+        return;
+      }
+      const fnBody = fnMatch[0];
+      const validatePos = fnBody.indexOf('validateWorkspaceDir');
+      const delegatePos = fnBody.indexOf('this.fromHookContext(');
+      expect(validatePos).toBeGreaterThan(-1);
+      expect(delegatePos).toBeGreaterThan(-1);
+      expect(
+        validatePos,
+        'validateWorkspaceDir must be called BEFORE delegating to fromHookContext',
+      ).toBeLessThan(delegatePos);
+    });
+
+    it('throws on missing workspaceDir (does not just warn)', () => {
+      const filePath = path.join(PLUGIN_SRC, 'core', 'workspace-context.ts');
+      if (!fs.existsSync(filePath)) return;
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const fnMatch = content.match(/static fromHookContextExplicit[\s\S]*?^\s{4}\}/m);
+      if (!fnMatch) return;
+      const fnBody = fnMatch[0];
+      expect(fnBody).toContain('throw');
+      expect(fnBody).toContain('workspace_dir_missing');
+    });
+
+    it('throws on invalid workspaceDir (does not just warn)', () => {
+      const filePath = path.join(PLUGIN_SRC, 'core', 'workspace-context.ts');
+      if (!fs.existsSync(filePath)) return;
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const fnMatch = content.match(/static fromHookContextExplicit[\s\S]*?^\s{4}\}/m);
+      if (!fnMatch) return;
+      const fnBody = fnMatch[0];
+      expect(fnBody).toContain('workspace_dir_invalid');
+    });
+  });
+
+  describe('LEGACY_PATH_RESOLVER_FALLBACK marker in fromHookContext', () => {
+    it('fromHookContext logs LEGACY_PATH_RESOLVER_FALLBACK on dangerous paths', () => {
+      const filePath = path.join(PLUGIN_SRC, 'core', 'workspace-context.ts');
+      if (!fs.existsSync(filePath)) return;
+      const content = fs.readFileSync(filePath, 'utf-8');
+      expect(content).toContain('LEGACY_PATH_RESOLVER_FALLBACK');
+    });
+  });
+
+  describe('Hook classification: Runtime V2 vs host enhancement', () => {
+    it('pain.ts is the only Runtime V2 hook — uses fromHookContextExplicit + resolveWorkspaceDirForRuntimeV2', () => {
+      const filePath = path.join(PLUGIN_SRC, 'hooks', 'pain.ts');
+      if (!fs.existsSync(filePath)) return;
+      const content = fs.readFileSync(filePath, 'utf-8');
+      expect(content).toContain('fromHookContextExplicit');
+      expect(content).toContain('resolveWorkspaceDirForRuntimeV2');
+    });
+
+    const hostEnhancementHooks = ['prompt.ts', 'lifecycle.ts', 'gate.ts', 'subagent.ts', 'llm.ts'];
+    for (const hookFile of hostEnhancementHooks) {
+      it(hookFile + ' is a host enhancement hook — uses fromHookContext with early-return guard', () => {
+        const filePath = path.join(PLUGIN_SRC, 'hooks', hookFile);
+        if (!fs.existsSync(filePath)) return;
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const explicitCalls = content.match(/fromHookContextExplicit/g) ?? [];
+        expect(explicitCalls.length, hookFile + ' should NOT use fromHookContextExplicit').toBe(0);
+      });
+    }
+  });
+
+  describe('resolveWorkspaceDirForRuntimeV2 has production caller', () => {
+    it('pain.ts imports and calls resolveWorkspaceDirForRuntimeV2', () => {
+      const filePath = path.join(PLUGIN_SRC, 'hooks', 'pain.ts');
+      if (!fs.existsSync(filePath)) return;
+      const content = fs.readFileSync(filePath, 'utf-8');
+      expect(content).toContain("from '../utils/workspace-resolver.js'");
+      expect(content).toContain('resolveWorkspaceDirForRuntimeV2(');
+    });
+  });
+});