claude-code-session-manager 0.86.0 → 0.87.0

package/src/main/__tests__/prdCreateDisposition.test.cjs

@@ -0,0 +1,201 @@
+/**
+ * prdCreateDisposition.test.cjs — scheduler wave-disposition PRD:
+ * createPrd()'s authoring-time disposition gate. A PRD landing as a wave
+ * ROOT (no dependsOn of its own) in an Epic that already has incomplete
+ * PRDs must record an explicit 'append'/'new-head' choice — required for an
+ * interactive caller, defaulted (and logged) for a non-interactive one.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdCreateDisposition.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const config = require('../config.cjs');
+const prdParser = require('../scheduler/prdParser.cjs');
+const { parsePrdFile } = require('../lib/prdFrontmatter.cjs');
+const { createPrd } = require('../lib/prdCreate.cjs');
+
+async function mkTmpPrdsDir() {
+  const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-disposition-create-prd-'));
+  config.addAllowedRoot(root);
+  const prdsDir = path.join(root, '.claude', 'prds');
+  await fsp.mkdir(prdsDir, { recursive: true });
+  return prdsDir;
+}
+
+/** Minimal fake `remote` — same shape as prdCreate.test.cjs's
+ *  makeFakeRemoteWithPrdsDir, but listPrds also reports sourcePromptId/
+ *  dependsOn (read back from each seeded file's real frontmatter) and
+ *  status (from the test-supplied statusBySlug map) — the fields
+ *  createPrd()'s disposition gate actually reads. */
+function makeFakeRemote(prdsDir, statusBySlug = {}) {
+  return {
+    async allocateParallelGroup() {
+      return prdParser.allocateParallelGroup(prdsDir);
+    },
+    async readPrd(slug) {
+      try {
+        const text = await fsp.readFile(path.join(prdsDir, `${slug}.md`), 'utf8');
+        return { ok: true, text };
+      } catch (e) {
+        return { ok: false, error: e?.message };
+      }
+    },
+    async writePrd(slug, body) {
+      try {
+        const filePath = path.join(prdsDir, `${slug}.md`);
+        await config.writeTextAtomic(filePath, body, { writer: 'scheduler' });
+        return { ok: true };
+      } catch (e) {
+        return { ok: false, error: e?.message };
+      }
+    },
+    async listPrds() {
+      const entries = await fsp.readdir(prdsDir);
+      const prds = [];
+      for (const f of entries) {
+        if (!f.endsWith('.md')) continue;
+        const slug = f.slice(0, -3);
+        const raw = await fsp.readFile(path.join(prdsDir, f), 'utf8');
+        const { frontmatter } = parsePrdFile(raw);
+        prds.push({
+          slug,
+          sourcePromptId: frontmatter.sourcePromptId ?? null,
+          dependsOn: frontmatter.dependsOn ?? null,
+          status: statusBySlug[slug] ?? null,
+        });
+      }
+      return { prds, total: prds.length, limit: prds.length, offset: 0, hasMore: false };
+    },
+  };
+}
+
+/** Seeds a fixture PRD file directly (bypassing createPrd) at an explicit,
+ *  already-NN-prefixed slug, so tests can assert dependsOn against a known
+ *  name instead of a freshly-allocated one. */
+async function seedPrd(prdsDir, slug, { sourcePromptId, dependsOn } = {}) {
+  const lines = ['---', 'title: seed', `sourcePromptId: ${sourcePromptId}`];
+  if (dependsOn && dependsOn.length) lines.push(`dependsOn: [${dependsOn.join(', ')}]`);
+  lines.push('---', '# Goal', '', 'seed body', '');
+  await fsp.writeFile(path.join(prdsDir, `${slug}.md`), lines.join('\n'));
+}
+
+function validBody(overrides = {}) {
+  return {
+    title: 'Wave 2 root',
+    cwd: os.homedir(),
+    estimateMinutes: 10,
+    goal: 'Do the follow-on work.',
+    acceptanceCriteria: ['a'],
+    implementationNotes: 'n',
+    ...overrides,
+  };
+}
+
+// This suite's own process may itself be running as a scheduled job (this
+// file's disposition gate keys directly off SM_SCHEDULER_JOB_SLUG — see
+// createPrd()) — never assume it's unset going in; each test controls it
+// explicitly.
+const originalJobSlug = process.env.SM_SCHEDULER_JOB_SLUG;
+beforeEach(() => {
+  delete process.env.SM_SCHEDULER_JOB_SLUG;
+});
+afterEach(() => {
+  if (originalJobSlug === undefined) delete process.env.SM_SCHEDULER_JOB_SLUG;
+  else process.env.SM_SCHEDULER_JOB_SLUG = originalJobSlug;
+});
+
+test('refuses to write, without a disposition, a new root joining an Epic that already has an incomplete PRD', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-1' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'pending' });
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-1' }), remote);
+
+  expect(result.ok).toBe(false);
+  expect(result.status).toBe(400);
+  expect(result.error).toMatch(/disposition/i);
+});
+
+test('disposition: append attaches the new root behind the Epic\'s current terminal PRD', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-1' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'pending' });
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-1', disposition: 'append' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).toMatch(/^dependsOn: \[1-wave1-tail\]$/m);
+  expect(written).toMatch(/^disposition: append$/m);
+});
+
+test('disposition: new-head leaves the new root independent (no dependsOn)', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-1' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'pending' });
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-1', disposition: 'new-head' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).not.toContain('dependsOn');
+  expect(written).toMatch(/^disposition: new-head$/m);
+});
+
+test('a non-interactive caller (SM_SCHEDULER_JOB_SLUG set) with no disposition defaults to append, logged as a default', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-1' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'pending' });
+  process.env.SM_SCHEDULER_JOB_SLUG = 'some-running-job';
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-1' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).toMatch(/^dependsOn: \[1-wave1-tail\]$/m);
+  expect(written).toMatch(/^disposition: append$/m);
+});
+
+test('no disposition required for the first PRD in a brand-new Epic', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemote(prdsDir);
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-empty' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).not.toContain('disposition');
+});
+
+test('no disposition required when every existing PRD in the Epic is already completed', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-done' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'completed' });
+
+  const result = await createPrd(validBody({ sourcePromptId: 'epic-done' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).not.toContain('disposition');
+});
+
+test('an explicit dependsOn bypasses the disposition gate entirely', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  await seedPrd(prdsDir, '1-wave1-tail', { sourcePromptId: 'epic-1' });
+  const remote = makeFakeRemote(prdsDir, { '1-wave1-tail': 'pending' });
+
+  const result = await createPrd(
+    validBody({ sourcePromptId: 'epic-1', dependsOn: ['1-wave1-tail'] }),
+    remote,
+  );
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).toMatch(/^dependsOn: \[1-wave1-tail\]$/m);
+  expect(written).not.toContain('disposition');
+});

package/src/main/__tests__/prdFrontmatterDisposition.test.cjs

@@ -0,0 +1,125 @@
+/**
+ * prdFrontmatterDisposition.test.cjs — scheduler wave-disposition PRD:
+ * `disposition` ('append' | 'new-head') is a recognized, patchable PRD
+ * frontmatter key, same pattern as `dependsOn` in
+ * prdFrontmatterDependsOn.test.cjs. It records the authoring-time decision
+ * for a wave's root PRD: does it extend the Epic's existing dependsOn chain
+ * (append) or start an independent, parallel-eligible chain (new-head)?
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdFrontmatterDisposition.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+
+const { parsePrdFile, serializePrdFile, RECOGNIZED_KEYS } = require('../lib/prdFrontmatter.cjs');
+
+test('disposition is a recognized key', () => {
+  expect(RECOGNIZED_KEYS.has('disposition')).toBe(true);
+});
+
+test('parsePrdFile parses disposition: append and round-trips it byte-identically when unedited', () => {
+  const raw = [
+    '---',
+    'title: A second wave',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 20',
+    'dependsOn: [widget-base]',
+    'disposition: append',
+    '---',
+    '# Goal',
+    '',
+    'Extend the chain.',
+    '',
+  ].join('\n');
+
+  const { frontmatter, body } = parsePrdFile(raw);
+  expect(frontmatter.disposition).toBe('append');
+  expect(serializePrdFile(frontmatter, body)).toBe(raw);
+});
+
+test('parsePrdFile parses disposition: new-head', () => {
+  const raw = [
+    '---',
+    'title: A parallel wave',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 20',
+    'disposition: new-head',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+
+  const { frontmatter } = parsePrdFile(raw);
+  expect(frontmatter.disposition).toBe('new-head');
+});
+
+test('parsePrdFile leaves disposition unset for an unrecognized value rather than throwing', () => {
+  const raw = [
+    '---',
+    'title: A hand-edited PRD',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 20',
+    'disposition: sideways',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+
+  const { frontmatter } = parsePrdFile(raw);
+  expect(frontmatter.disposition).toBeUndefined();
+});
+
+test('parsePrdFile leaves disposition undefined when omitted — a PRD authored before this field existed round-trips unaffected', () => {
+  const raw = [
+    '---',
+    'title: An older PRD',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 10',
+    '---',
+    '# Goal',
+    '',
+    'Do the thing.',
+    '',
+  ].join('\n');
+
+  const { frontmatter, body } = parsePrdFile(raw);
+  expect(frontmatter.disposition).toBeUndefined();
+  expect(serializePrdFile(frontmatter, body)).toBe(raw);
+});
+
+test('serializePrdFile emits a newly-set disposition onto a frontmatter object that lacked one', () => {
+  const raw = [
+    '---',
+    'title: Legacy PRD',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 5',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+
+  const { frontmatter, body } = parsePrdFile(raw);
+  const updated = serializePrdFile({ ...frontmatter, disposition: 'new-head' }, body);
+  expect(updated).toContain('disposition: new-head');
+});
+
+test('serializePrdFile patches an existing disposition (promoting append to new-head)', () => {
+  const raw = [
+    '---',
+    'title: A second wave',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 20',
+    'dependsOn: [widget-base]',
+    'disposition: append',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+
+  const { frontmatter, body } = parsePrdFile(raw);
+  const updated = serializePrdFile({ ...frontmatter, dependsOn: [], disposition: 'new-head' }, body);
+  expect(updated).toContain('disposition: new-head');
+  expect(updated).not.toContain('dependsOn');
+});

package/src/main/__tests__/prdLocations.test.cjs

@@ -7,12 +7,17 @@
 
 'use strict';
 
-import { test, expect, afterEach } from 'vitest';
+import { test, expect, afterEach, vi } from 'vitest';
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
-const { resolvePrdWriteDir, resolvePrdsDirs } = require('../lib/prdLocations.cjs');
+const {
+  resolvePrdWriteDir,
+  resolvePrdsDirs,
+  resolveEpicPrdWriteDir,
+  listEpicPrdDirs,
+} = require('../lib/prdLocations.cjs');
 
 const tmpDirs = [];
 afterEach(async () => {
@@ -95,3 +100,96 @@ test('resolvePrdsDirs returns [] when no project has a recent transcript', () =>
   const dirs = resolvePrdsDirs(90, { projectsDir: '/nonexistent-projects-dir' });
   expect(dirs).toEqual([]);
 });
+
+test('listEpicPrdDirs memoizes on the Epics-root mtime: no readdir on a repeat call, but a freshly minted Epic prds dir is picked up on the very next call', async () => {
+  const cwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-memo-cwd-'));
+  tmpDirs.push(cwd);
+  fs.mkdirSync(resolveEpicPrdWriteDir(cwd, 'epic-1'), { recursive: true });
+
+  const first = listEpicPrdDirs(cwd);
+  expect(first).toEqual([resolveEpicPrdWriteDir(cwd, 'epic-1')]);
+
+  const readdirSpy = vi.spyOn(fs, 'readdirSync');
+  try {
+    // Nothing under the Epics root changed — the cached result comes back
+    // without a fresh readdir of the Epics root.
+    const second = listEpicPrdDirs(cwd);
+    expect(second).toEqual(first);
+    expect(readdirSpy).not.toHaveBeenCalled();
+  } finally {
+    readdirSpy.mockRestore();
+  }
+
+  // A brand-new Epic's prds/ dir is a NEW entry under the Epics root, which
+  // bumps the root's own mtime — no TTL wait required to see it.
+  fs.mkdirSync(resolveEpicPrdWriteDir(cwd, 'epic-2'), { recursive: true });
+  const third = listEpicPrdDirs(cwd);
+  expect(third).toEqual(
+    expect.arrayContaining([resolveEpicPrdWriteDir(cwd, 'epic-1'), resolveEpicPrdWriteDir(cwd, 'epic-2')]),
+  );
+});
+
+test('listEpicPrdDirs: an unreadable Epics root does not write a poisoned entry that survives the dir becoming readable', async () => {
+  const cwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-unreadable-cwd-'));
+  tmpDirs.push(cwd);
+
+  // No Epics root at all yet.
+  expect(listEpicPrdDirs(cwd)).toEqual([]);
+
+  // The root now exists, with a real Epic prds dir inside it.
+  fs.mkdirSync(resolveEpicPrdWriteDir(cwd, 'epic-1'), { recursive: true });
+  expect(listEpicPrdDirs(cwd)).toEqual([resolveEpicPrdWriteDir(cwd, 'epic-1')]);
+});
+
+test('resolvePrdsDirs EDGE (non-negotiable): a new epics/<id>/prds dir created after a prior call is visible on the VERY NEXT call, no TTL wait', async () => {
+  const projectsDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-freshness-projects-'));
+  tmpDirs.push(projectsDir);
+  const projectCwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-freshness-cwd-'));
+  tmpDirs.push(projectCwd);
+
+  const projDir = path.join(projectsDir, 'freshness-project');
+  fs.mkdirSync(projDir, { recursive: true });
+  fs.writeFileSync(path.join(projDir, 'session1.jsonl'), `${JSON.stringify({ cwd: projectCwd })}\n`);
+
+  const before = resolvePrdsDirs(90, { projectsDir });
+  const newEpicPrdDir = resolveEpicPrdWriteDir(projectCwd, 'freshly-minted-epic');
+  expect(before).not.toContain(newEpicPrdDir);
+
+  fs.mkdirSync(newEpicPrdDir, { recursive: true });
+
+  const after = resolvePrdsDirs(90, { projectsDir });
+  expect(after).toContain(newEpicPrdDir);
+});
+
+test('resolvePrdsDirs: calls with an explicit { projectsDir } opts are keyed separately per projectsDir and never share a stale cache entry', async () => {
+  const projectsDirA = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-a-'));
+  tmpDirs.push(projectsDirA);
+  const projectsDirB = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-b-'));
+  tmpDirs.push(projectsDirB);
+  const cwdA = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-cwd-a-'));
+  tmpDirs.push(cwdA);
+  const cwdB = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-cwd-b-'));
+  tmpDirs.push(cwdB);
+
+  const projDirA = path.join(projectsDirA, 'proj-a');
+  fs.mkdirSync(projDirA, { recursive: true });
+  fs.writeFileSync(path.join(projDirA, 'session1.jsonl'), `${JSON.stringify({ cwd: cwdA })}\n`);
+  fs.mkdirSync(resolvePrdWriteDir(cwdA), { recursive: true });
+
+  const projDirB = path.join(projectsDirB, 'proj-b');
+  fs.mkdirSync(projDirB, { recursive: true });
+  fs.writeFileSync(path.join(projDirB, 'session1.jsonl'), `${JSON.stringify({ cwd: cwdB })}\n`);
+  fs.mkdirSync(resolvePrdWriteDir(cwdB), { recursive: true });
+
+  const dirsA = resolvePrdsDirs(90, { projectsDir: projectsDirA });
+  const dirsB = resolvePrdsDirs(90, { projectsDir: projectsDirB });
+
+  expect(dirsA).toContain(resolvePrdWriteDir(cwdA));
+  expect(dirsA).not.toContain(resolvePrdWriteDir(cwdB));
+  expect(dirsB).toContain(resolvePrdWriteDir(cwdB));
+  expect(dirsB).not.toContain(resolvePrdWriteDir(cwdA));
+
+  // Re-querying A after B was resolved must still reflect A's own state, not
+  // B's — proof the two opts objects never shared one cache key.
+  expect(resolvePrdsDirs(90, { projectsDir: projectsDirA })).toEqual(dirsA);
+});

package/src/main/__tests__/prdLocationsArchived.test.cjs

@@ -21,7 +21,7 @@
 
 'use strict';
 
-import { test, expect, afterEach } from 'vitest';
+import { test, expect, afterEach, vi } from 'vitest';
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const os = require('node:os');
@@ -150,3 +150,45 @@ test('scheduler.cjs exports candidateArchivedPrdsDirs alongside candidatePrdsDir
   expect(Array.isArray(candidatePrdsDirs())).toBe(true);
   expect(Array.isArray(candidateArchivedPrdsDirs())).toBe(true);
 });
+
+test('resolveArchivedPrdsDirs: a prds-archived/ dir created inside an ALREADY-EXISTING Epic (the archiveCompletedPrd shape — does not bump the Epics root mtime) is bounded-stale, not stale forever', async () => {
+  // archiveCompletedPrd (scheduler.cjs) creates `epics/<id>/prds-archived/`
+  // as a new entry INSIDE an already-existing `epics/<id>/` dir — unlike a
+  // brand-new Epic's `prds/` (created in the same mkdirSync call as
+  // `epics/<id>/` itself), this does NOT bump the Epics root's own mtime,
+  // so the mtime-keyed freshness key alone would never invalidate. The
+  // short TTL backstop (same idiom as activeSessions.cjs's cwdScanCache)
+  // bounds that blind spot instead of leaving it stale indefinitely.
+  vi.useFakeTimers();
+  try {
+    const projectsDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-blindspot-projects-'));
+    tmpDirs.push(projectsDir);
+    const projectCwd = await mkEpicProject();
+    tmpDirs.push(projectCwd);
+
+    const epicId = `blindspot-epic-${process.pid}`;
+    const epicPrdsDir = resolveEpicPrdWriteDir(projectCwd, epicId);
+    fs.mkdirSync(epicPrdsDir, { recursive: true }); // Epic already exists, well before archiving.
+
+    const projDir = path.join(projectsDir, 'blindspot-project');
+    fs.mkdirSync(projDir, { recursive: true });
+    fs.writeFileSync(path.join(projDir, 'session1.jsonl'), `${JSON.stringify({ cwd: projectCwd })}\n`);
+
+    // Prime the cache — no prds-archived/ dir exists yet.
+    const before = resolveArchivedPrdsDirs(90, { projectsDir });
+    const epicArchiveDir = path.join(epicPrdsDir, '..', 'prds-archived');
+    expect(before).not.toContain(path.resolve(epicArchiveDir));
+
+    // The archiveCompletedPrd shape: a NEW prds-archived/ dir appears inside
+    // the ALREADY-EXISTING epic dir. This does not change the Epics root's
+    // own mtime.
+    fs.mkdirSync(epicArchiveDir, { recursive: true });
+
+    // Bounded staleness is acceptable — but it must actually be bounded.
+    vi.advanceTimersByTime(31_000);
+    const after = resolveArchivedPrdsDirs(90, { projectsDir });
+    expect(after.map((d) => path.resolve(d))).toContain(path.resolve(epicArchiveDir));
+  } finally {
+    vi.useRealTimers();
+  }
+});