@dzhechkov/p-replicator 1.10.4 → 1.13.1

package/tests/unit/hooks-project-anchored.test.js

@@ -65,14 +65,15 @@ function project() {
 }
 
 /** Run one hook FROM THE SUBDIRECTORY — the only place this defect is visible. */
-function runFromSub(p, hook, { withEnv = true, args = [] } = {}) {
+function runFromSub(p, hook, { withEnv = true, args = [], input, envOverrides = {} } = {}) {
   const env = { ...process.env };
   if (withEnv) env.CLAUDE_PROJECT_DIR = p.root;
   else delete env.CLAUDE_PROJECT_DIR;
+  Object.assign(env, envOverrides);
   try {
     const stdout = execFileSync(process.execPath,
       [path.join(p.root, '.claude', 'hooks', hook + '.cjs'), ...args],
-      { cwd: p.sub, env, encoding: 'utf8', stdio: 'pipe' });
+      { cwd: p.sub, env, encoding: 'utf8', stdio: 'pipe', input });
     return { code: 0, stdout: stdout || '' };
   } catch (err) {
     return { code: err.status ?? 1, stdout: err.stdout?.toString() ?? '' };
@@ -138,13 +139,76 @@ describe('hooks resolve against the project, not the drifting cwd (PR-013)', ()
       fs.mkdirSync(path.join(p.root, '.claude', 'insights'), { recursive: true });
       fs.writeFileSync(path.join(p.root, '.claude', 'insights', 'index.md'),
         '## Insight one\n\nbody one\n');
-      const r = runFromSub(p, 'session-insights', { withEnv: false });
+      const r = runFromSub(p, 'session-insights', {
+        withEnv: false,
+        envOverrides: { PATH: '' },
+        input: JSON.stringify({ hook_event_name: 'UserPromptSubmit', prompt: 'anchor' }),
+      });
       assert.equal(r.code, 0, 'the hook must stay non-blocking');
       assert.match(r.stdout, /Insight one/,
         'with no env var and cwd in a subdirectory, the hook must still read the ROOT index');
     } finally { fs.rmSync(p.root, { recursive: true, force: true }); }
   });
 
+  test('P8 - missing store triggers exactly one no-insights hint without creating the carrier', () => {
+    const p = project();
+    const hint = 'инсайтов пока нет; /myinsights создаст первую запись\n';
+    const index = path.join(p.root, '.claude', 'insights', 'index.md');
+    try {
+      const missing = runFromSub(p, 'session-insights');
+      assert.equal(missing.code, 0, 'the missing state stays advisory');
+      assert.equal(missing.stdout, hint, 'the genuine missing branch prints exactly one line');
+      assert.equal(fs.existsSync(path.dirname(index)), false,
+        'the reader must not blur missing into empty by creating the carrier');
+
+      fs.mkdirSync(path.dirname(index), { recursive: true });
+      fs.writeFileSync(index, '');
+      const empty = runFromSub(p, 'session-insights');
+      assert.equal(empty.code, 0);
+      assert.equal(empty.stdout, '', 'an existing empty carrier is not the missing branch');
+
+      fs.writeFileSync(index, '## 2026-08-30 — existing\n\nBody.\n');
+      const populated = runFromSub(p, 'session-insights');
+      assert.equal(populated.code, 0);
+      assert.equal(populated.stdout, '',
+        'SessionStart must not inject populated insights before a prompt exists');
+      assert.doesNotMatch(populated.stdout, /инсайтов пока нет/);
+
+      fs.rmSync(index);
+      fs.mkdirSync(index);
+      const unreadable = runFromSub(p, 'session-insights');
+      assert.equal(unreadable.code, 0, 'read errors remain never-blocking');
+      assert.equal(unreadable.stdout, '',
+        'an unrelated read failure must not be laundered into the ordinary missing state');
+    } finally { fs.rmSync(p.root, { recursive: true, force: true }); }
+  });
+
+  test('P9 - SessionStart preserves only missing-carrier visibility', () => {
+    const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-start-state-')));
+    const hook = path.join(TPL, 'hooks', 'session-insights.cjs');
+    delete require.cache[require.resolve(hook)];
+    const { emitInsights } = require(hook);
+    const run = () => {
+      const output = [];
+      emitInsights(root, { write: (chunk) => output.push(chunk) }, {
+        rawEvent: JSON.stringify({ hook_event_name: 'SessionStart' }),
+      });
+      return output;
+    };
+    try {
+      assert.deepEqual(run(), ['инсайтов пока нет; /myinsights создаст первую запись\n']);
+      assert.equal(fs.existsSync(path.join(root, '.claude', 'insights')), false,
+        'the callable production branch must remain read-only on an absent root');
+
+      const index = path.join(root, '.claude', 'insights', 'index.md');
+      fs.mkdirSync(path.dirname(index), { recursive: true });
+      fs.writeFileSync(index, '');
+      assert.deepEqual(run(), [], 'an empty carrier is not a missing-carrier warning');
+      fs.writeFileSync(index, '## 2026-08-30 — populated\n\nBody.\n');
+      assert.deepEqual(run(), [], 'populated delivery waits for UserPromptSubmit');
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
   test('P5 — EFFECT from a subdirectory: the roadmap is actually committed', () => {
     // The property the whole feature exists for. An exit-code check passes on the broken hook;
     // this does not. Fails if EITHER half of the fix is missing.

package/tests/unit/insights-docs-tell-the-truth.test.js

@@ -1,26 +1,19 @@
 'use strict';
 
-// Two shipped documents promised something the hook does not do — and, as written, CANNOT do.
-//
-// `myinsights.md` said insights are injected "when their tags match the current task". The hook
-// runs on SessionStart, BEFORE the user has said anything, so there is no current task to match
-// tags against. MEASURED: `session-insights.cjs:33` is `sections.slice(-3)` — the last three by
-// file order, and no tag matching exists anywhere in the package.
-//
-// The hook's own printed heading, "Recent project insights", was already honest. Only the documents
-// around it were not.
-//
-// This test exists because a promise removed from prose comes back. It pins the CODE and the DOC to
-// each other: if selection ever becomes relevance-based, this test is where the doc must change too.
-
 const { test, describe } = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 
 const TPL = path.join(__dirname, '..', '..', 'templates', '.claude');
+const PKG = path.join(__dirname, '..', '..');
 const CMD = path.join(TPL, 'commands', 'myinsights.md');
 const HOOK = path.join(TPL, 'hooks', 'session-insights.cjs');
+const RULE = path.join(TPL, 'rules', 'insights-capture.md');
+const HARVEST = path.join(TPL, 'commands', 'harvest.md');
+const README = path.join(PKG, 'README.md');
+const API_EN = path.join(PKG, 'README', 'eng', '04_api_reference.md');
+const API_RU = path.join(PKG, 'README', 'ru', '04_api_reference.md');
 
 const read = (f) => fs.readFileSync(f, 'utf-8');
 /** Prose with code fences and comments removed — a MENTION of a claim is not the claim. */
@@ -40,12 +33,13 @@ describe('the insights documents describe the hook that exists', () => {
 
   test('P2 - the document states what the hook actually selects', () => {
     const doc = read(CMD);
-    assert.match(doc, /three most recent/i, 'the real selection must be named');
-    assert.match(doc, /by their\s*\n?order in the file/i, 'and how it is ordered');
-    assert.match(doc, /There is no tag matching, and it is not an omission/,
-      'and WHY there is none, or a future reader files it as a bug');
-    assert.match(doc, /BEFORE you have said anything/,
-      'the reason must be the timing, which is the load-bearing fact');
+    assert.match(doc, /UserPromptSubmit/, 'selection must occur after the real prompt exists');
+    assert.match(doc, /successful,? non-empty.*dz recall/is,
+      'the value-armed recall condition must be named');
+    assert.match(doc, /falls back.*three most recent/is,
+      'the local last-three fallback must remain visible');
+    assert.match(doc, /only.*suppresses.*local/is,
+      'binary presence alone must not read as readiness');
   });
 
   test('P3 - the code and the doc agree, asserted against the CODE', () => {
@@ -60,25 +54,52 @@ describe('the insights documents describe the hook that exists', () => {
   });
 
   test('P4 - the consequence of last-three is stated, not left to be discovered', () => {
-    // The file is append-only and the hook takes the last three, so a long-lived project stops
-    // seeing its earlier entries. insights-capture.md plans for 50+.
     const doc = read(CMD);
     assert.match(doc, /append-only/, 'the growth behaviour must be named');
-    assert.match(doc, /earlier ones stop being injected/,
+    assert.match(doc, /fallback.*earlier ones stop being injected/is,
       'and its consequence, in plain words');
-    const rule = read(path.join(TPL, 'rules', 'insights-capture.md'));
+    const rule = read(RULE);
     assert.match(rule, /50 entries|> 50/,
       'the rule really does plan for a size the hook cannot show — that is the point');
   });
 
-  test('P5 - the /harvest link is described as an intention, not a wired path', () => {
-    // MEASURED: `grep -ci insight` over harvest.md returns 0. The command promised harvest
-    // "extracts reusable patterns from insights", which nothing does.
+  test('P5 - /harvest and /myinsights name their executable shared-carrier contract', () => {
     const doc = read(CMD);
-    assert.match(doc, /does\s*\n?\s*NOT read `\.claude\/insights\/index\.md` today/,
-      'the unwired link must be admitted where it is claimed');
-    const harvest = read(path.join(TPL, 'commands', 'harvest.md'));
-    assert.equal((harvest.match(/insight/gi) || []).length, 0,
-      'if harvest ever DOES read insights, this admission must be removed — that is the trigger');
+    const harvest = read(HARVEST);
+    assert.doesNotMatch(doc, /does\s*\n?\s*NOT read `\.claude\/insights\/index\.md` today/,
+      'the old unwired admission became false once harvest acquired a writer');
+    assert.match(doc, /share the same Markdown carrier/i,
+      'manual and harvest capture must be described as one carrier, not two stores');
+    assert.match(harvest, /REQUIRED INSIGHT PERSISTENCE GATE/,
+      'the relationship must be executable wiring, not a prose aspiration');
+    assert.match(harvest, /\.claude\/hooks\/write-insight\.cjs/,
+      'the shipped writer boundary must be named exactly');
+    assert.match(harvest, /\.claude\/insights\/index\.md/,
+      'the command and /myinsights must converge on the same Markdown source of truth');
+    assert.match(harvest, /Only `created`, `appended`, or `duplicate`/,
+      'normal completion must be bound to the three canonical writer receipts');
+    assert.match(harvest, /writer exits non-zero.*MUST NOT\s+report.*completed/is,
+      'an unestablished write must remain a blocking harvest outcome');
+  });
+
+  test('P6 - docs describe prompt-time armed recall and Markdown authority', () => {
+    const hook = read(HOOK);
+    assert.match(hook, /recall\.kind === 'ok'/,
+      'the docs cannot claim armed recall without the production predicate');
+    assert.doesNotMatch(hook, /command\s+-v\s+dz/,
+      'binary discovery must not become the suppression condition');
+
+    const docs = [read(CMD), read(RULE), read(HARVEST), read(README), read(API_EN), read(API_RU)];
+    for (const [index, doc] of docs.entries()) {
+      assert.match(doc, /Markdown/i, `behavior document ${index + 1} omits Markdown authority`);
+      assert.match(doc, /best-effort/i, `behavior document ${index + 1} omits optional teach`);
+    }
+    for (const doc of [docs[0], docs[1], docs[3], docs[4], docs[5]]) {
+      assert.match(doc, /UserPromptSubmit/, 'prompt-time delivery must be named');
+      assert.match(doc, /(?:non-empty|непуст(?:ой|ого)).*(?:recall|вывод)/is,
+        'successful non-empty output must be the documented arming condition');
+      assert.match(doc, /(?:local|локальн).*(?:fallback|фолб[эе]к)/is,
+        'absent/failing/empty recall must retain local delivery');
+    }
   });
 });

package/tests/unit/insights-dz-delegation.test.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PKG = path.resolve(__dirname, '..', '..');
+const HOOK = path.join(PKG, 'templates', '.claude', 'hooks', 'session-insights.cjs');
+const LOCAL = 'LOCAL_ONLY';
+const DZ = 'DZ_ONLY';
+
+function loadHook() {
+  delete require.cache[require.resolve(HOOK)];
+  return require(HOOK);
+}
+
+function project(prefix = 'p-rep-dz-contract-') {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+  const index = path.join(root, '.claude', 'insights', 'index.md');
+  fs.mkdirSync(path.dirname(index), { recursive: true });
+  fs.writeFileSync(index, `## 2026-08-30 — ${LOCAL}\n\nlocal body\n`);
+  return root;
+}
+
+function userPrompt(prompt = 'choose an optional dependency fallback') {
+  return JSON.stringify({ hook_event_name: 'UserPromptSubmit', prompt });
+}
+
+function runHook(root, result, rawEvent = userPrompt()) {
+  const chunks = [];
+  const runner = (_file, _args, _options) => result;
+  loadHook().emitInsights(root, { write: (chunk) => chunks.push(chunk) }, { rawEvent, runner });
+  return chunks.join('');
+}
+
+function envelope(stdout) {
+  const lines = stdout.trimEnd().split('\n');
+  assert.equal(lines.length, 1, `expected one hook envelope, got ${lines.length}: ${stdout}`);
+  const parsed = JSON.parse(lines[0]);
+  assert.equal(parsed.hookSpecificOutput.hookEventName, 'UserPromptSubmit');
+  return parsed.hookSpecificOutput.additionalContext;
+}
+
+function recalled(pattern = DZ) {
+  return {
+    status: 0,
+    stdout: JSON.stringify([{ pattern, domain: 'p-replicator-insights' }]),
+    stderr: '',
+  };
+}
+
+function absent() {
+  return { status: null, stdout: '', stderr: '', error: { code: 'ENOENT' } };
+}
+
+describe('PR-022 optional dz delivery contract', () => {
+  test('P10 - absent dz emits local only without dz error text', () => {
+    const root = project();
+    try {
+      const context = envelope(runHook(root, absent()));
+      assert.match(context, new RegExp(LOCAL));
+      assert.doesNotMatch(context, new RegExp(DZ));
+      assert.doesNotMatch(context, /dz recall (unavailable|failed)/i);
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P11 - armed non-empty recall emits dz only', () => {
+    const root = project();
+    try {
+      const context = envelope(runHook(root, recalled()));
+      assert.match(context, new RegExp(DZ));
+      assert.doesNotMatch(context, new RegExp(LOCAL));
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P12 - failing or timed-out recall names degradation and emits local only', () => {
+    const root = project();
+    const failures = [
+      { status: 23, stdout: '', stderr: 'SECRET child stderr' },
+      { status: null, stdout: '', stderr: '', error: { code: 'ETIMEDOUT' }, signal: 'SIGTERM' },
+    ];
+    try {
+      for (const result of failures) {
+        const context = envelope(runHook(root, result));
+        assert.match(context, /dz recall unavailable: (exit 23|timeout); using local recent insights/i);
+        assert.match(context, new RegExp(LOCAL));
+        assert.doesNotMatch(context, new RegExp(DZ));
+        assert.doesNotMatch(context, /SECRET child stderr/);
+      }
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P13 - empty successful recall emits local only', () => {
+    const root = project();
+    const emptyResults = [
+      { status: 0, stdout: '[]', stderr: '' },
+      { status: 0, stdout: JSON.stringify([
+        { pattern: DZ, domain: 'another-domain' },
+        { pattern: '   ', domain: 'p-replicator-insights' },
+      ]), stderr: '' },
+    ];
+    try {
+      for (const result of emptyResults) {
+        const context = envelope(runHook(root, result));
+        assert.match(context, new RegExp(LOCAL));
+        assert.doesNotMatch(context, new RegExp(DZ));
+        assert.doesNotMatch(context, /dz recall unavailable/i);
+      }
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P14 - local suppression requires armed recall and never double-injects across absent/ok/failing/empty', () => {
+    const root = project();
+    const states = {
+      absent: absent(),
+      ok: recalled(),
+      failing: { status: 2, stdout: '', stderr: '' },
+      empty: { status: 0, stdout: '[]', stderr: '' },
+    };
+    try {
+      for (const [state, result] of Object.entries(states)) {
+        const context = envelope(runHook(root, result));
+        const hasLocal = context.includes(LOCAL);
+        const hasDz = context.includes(DZ);
+        assert.notEqual(hasLocal, hasDz, `${state} must select exactly one insight source`);
+        assert.equal(hasDz, state === 'ok', `${state} armedness selected the wrong source`);
+      }
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P15 - malformed successful stdout cannot arm recall', () => {
+    const root = project();
+    try {
+      for (const stdout of ['not-json', '{}']) {
+        const context = envelope(runHook(root, { status: 0, stdout, stderr: '' }));
+        assert.match(context, /dz recall unavailable: invalid (JSON|result)/i);
+        assert.match(context, new RegExp(LOCAL));
+        assert.doesNotMatch(context, new RegExp(DZ));
+      }
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P15a - prompt parsing root pin argv and output bounds survive hostile input', () => {
+    const api = loadHook();
+    for (const key of ['prompt', 'user_prompt', 'userPrompt']) {
+      assert.deepEqual(
+        api.parseHookEvent(JSON.stringify({ hook_event_name: 'UserPromptSubmit', [key]: ' task ' })),
+        { kind: 'user-prompt', prompt: 'task' },
+      );
+    }
+
+    const root = project('p rep dz contract ');
+    const calls = [];
+    try {
+      const result = api.recallFromDz('literal $(touch never) `echo never`', root, {
+        runner(file, args, options) {
+          calls.push({ file, args, options });
+          return recalled('X'.repeat(20 * 1024));
+        },
+      });
+      assert.equal(result.kind, 'ok');
+      assert.ok(Buffer.byteLength(result.context, 'utf8') <= 16 * 1024,
+        `rendered context exceeded 16 KiB: ${Buffer.byteLength(result.context, 'utf8')}`);
+      assert.equal(calls.length, 1);
+      assert.equal(calls[0].file, 'dz');
+      // The ADR's Decision pins this argv exactly, --domain included: it is a rank BOOST, and
+      // without it a shared multi-domain store buries insight records below the top-12 cut, so
+      // the armed state never fires. This assertion previously omitted the flag and therefore
+      // cemented the very gap cross-family QE found.
+      assert.deepEqual(calls[0].args, [
+        'recall', 'literal $(touch never) `echo never`', '--limit', '12',
+        '--domain', 'p-replicator-insights',
+        '--project', root, '--json',
+      ]);
+      assert.equal(calls[0].options.cwd, root);
+      assert.equal(calls[0].options.shell, false);
+      assert.equal(calls[0].options.timeout, 1500);
+      assert.equal(calls[0].options.maxBuffer, 1024 * 1024);
+
+      const oversized = api.recallFromDz('task', root, {
+        runner: () => ({ status: null, stdout: '', stderr: '', error: { code: 'ENOBUFS' } }),
+      });
+      assert.deepEqual(oversized, { kind: 'failing', reason: 'spawn ENOBUFS' });
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P19 - production comments contain no decision-history narration', () => {
+    for (const file of ['session-insights.cjs', 'write-insight.cjs']) {
+      const source = fs.readFileSync(path.join(PKG, 'templates', '.claude', 'hooks', file), 'utf8');
+      const comments = source.split('\n').filter((line) => /^\s*(\/\/|\/\*|\*)/.test(line)).join('\n');
+      assert.doesNotMatch(comments, /supersed|a0ea8b|cross-model|FIX-\d|AM-\d|third answer/i,
+        `${file} contains decision history that belongs in the ADR`);
+    }
+  });
+});