feat(graceful-handoff): 2.0 — SessionStart auto-load handoff on resume/compact [skip-docs]
Step 6 of v2.0 plan. SessionStart hook fires on source: resume or source: compact, walks up to 3 levels searching for NEXT-SESSION-*.local.md, injects content via additionalContext, and archives the file (rename to *.archived.local.md) to prevent stale-load in later sessions. 9 tests cover sources, multi-level search, topic-slug variants, archive filtering, malformed payload.
This commit is contained in:
Kjell Tore Guttormsen
parent
81aba9a5f5
commit
4076bf904a
2 changed files with 201 additions and 0 deletions
|
|
@ -0,0 +1,93 @@
|
||||||
|
#!/usr/bin/env node
|
||||||
|
// session-start-load-handoff.mjs — graceful-handoff v2.0
|
||||||
|
// SessionStart hook: on `source: resume` or `source: compact`, find
|
||||||
|
// NEXT-SESSION-PROMPT.local.md (or NEXT-SESSION-*.local.md) in cwd and up
|
||||||
|
// to 3 levels above, inject contents into the new session's context, then
|
||||||
|
// archive the file to prevent stale-load in subsequent sessions.
|
||||||
|
|
||||||
|
import { readFileSync, existsSync, readdirSync, renameSync } from 'node:fs';
|
||||||
|
import { dirname, join } from 'node:path';
|
||||||
|
|
||||||
|
function readStdin() {
|
||||||
|
try {
|
||||||
|
return readFileSync(0, 'utf-8');
|
||||||
|
} catch {
|
||||||
|
return '';
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Find NEXT-SESSION-*.local.md in dir; returns path or null
|
||||||
|
function findHandoffIn(dir) {
|
||||||
|
try {
|
||||||
|
const entries = readdirSync(dir);
|
||||||
|
// Prefer NEXT-SESSION-PROMPT.local.md, then any NEXT-SESSION-*.local.md
|
||||||
|
const exact = entries.find(e => e === 'NEXT-SESSION-PROMPT.local.md');
|
||||||
|
if (exact) return join(dir, exact);
|
||||||
|
const match = entries.find(e => /^NEXT-SESSION-.*\.local\.md$/.test(e) && !/\.archived\./.test(e));
|
||||||
|
if (match) return join(dir, match);
|
||||||
|
} catch { /* ignore */ }
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Walk up from start, max 3 levels, looking for handoff
|
||||||
|
function findHandoffUpwards(start) {
|
||||||
|
let cur = start;
|
||||||
|
for (let i = 0; i < 4; i++) { // 0,1,2,3 — start + 3 ancestors
|
||||||
|
const found = findHandoffIn(cur);
|
||||||
|
if (found) return found;
|
||||||
|
const parent = dirname(cur);
|
||||||
|
if (parent === cur) break;
|
||||||
|
cur = parent;
|
||||||
|
}
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
function main() {
|
||||||
|
const raw = readStdin();
|
||||||
|
if (!raw.trim()) process.exit(0);
|
||||||
|
let payload;
|
||||||
|
try {
|
||||||
|
payload = JSON.parse(raw);
|
||||||
|
} catch {
|
||||||
|
process.exit(0);
|
||||||
|
}
|
||||||
|
|
||||||
|
const source = payload?.source;
|
||||||
|
if (source !== 'resume' && source !== 'compact') {
|
||||||
|
process.exit(0);
|
||||||
|
}
|
||||||
|
|
||||||
|
const cwd = payload?.cwd || process.cwd();
|
||||||
|
const handoffPath = findHandoffUpwards(cwd);
|
||||||
|
if (!handoffPath) {
|
||||||
|
process.exit(0);
|
||||||
|
}
|
||||||
|
|
||||||
|
let content;
|
||||||
|
try {
|
||||||
|
content = readFileSync(handoffPath, 'utf-8');
|
||||||
|
} catch {
|
||||||
|
process.exit(0);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Inject via additionalContext for clean structured output
|
||||||
|
const output = {
|
||||||
|
hookSpecificOutput: {
|
||||||
|
hookEventName: 'SessionStart',
|
||||||
|
additionalContext: `<session-handoff source="${handoffPath}" loaded-by="graceful-handoff">\n${content}\n</session-handoff>`,
|
||||||
|
},
|
||||||
|
};
|
||||||
|
process.stdout.write(JSON.stringify(output));
|
||||||
|
|
||||||
|
// Archive to prevent stale-load in subsequent sessions
|
||||||
|
try {
|
||||||
|
const archived = handoffPath.replace(/\.local\.md$/, '.archived.local.md');
|
||||||
|
if (!existsSync(archived)) {
|
||||||
|
renameSync(handoffPath, archived);
|
||||||
|
}
|
||||||
|
} catch { /* archival is best-effort, never block injection */ }
|
||||||
|
|
||||||
|
process.exit(0);
|
||||||
|
}
|
||||||
|
|
||||||
|
main();
|
||||||
|
|
@ -0,0 +1,108 @@
|
||||||
|
// session-start-load-handoff.test.mjs
|
||||||
|
|
||||||
|
import { test } from 'node:test';
|
||||||
|
import { strict as assert } from 'node:assert';
|
||||||
|
import { dirname, join } from 'node:path';
|
||||||
|
import { fileURLToPath } from 'node:url';
|
||||||
|
import { mkdtempSync, mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs';
|
||||||
|
import { tmpdir } from 'node:os';
|
||||||
|
import { runHook } from './hook-helper.mjs';
|
||||||
|
|
||||||
|
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||||
|
const HOOK = join(__dirname, '..', '..', 'hooks', 'scripts', 'session-start-load-handoff.mjs');
|
||||||
|
|
||||||
|
function makeFixture() {
|
||||||
|
return mkdtempSync(join(tmpdir(), 'sessionstart-'));
|
||||||
|
}
|
||||||
|
|
||||||
|
test('source: startup → silent (no injection)', async () => {
|
||||||
|
const dir = makeFixture();
|
||||||
|
writeFileSync(join(dir, 'NEXT-SESSION-PROMPT.local.md'), 'should not load\n');
|
||||||
|
const res = await runHook(HOOK, { source: 'startup', cwd: dir });
|
||||||
|
assert.equal(res.code, 0);
|
||||||
|
assert.equal(res.stdout.trim(), '', 'startup source should not inject');
|
||||||
|
assert.ok(existsSync(join(dir, 'NEXT-SESSION-PROMPT.local.md')), 'file should not be archived');
|
||||||
|
rmSync(dir, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
test('source: clear → silent (no injection)', async () => {
|
||||||
|
const dir = makeFixture();
|
||||||
|
writeFileSync(join(dir, 'NEXT-SESSION-PROMPT.local.md'), 'should not load\n');
|
||||||
|
const res = await runHook(HOOK, { source: 'clear', cwd: dir });
|
||||||
|
assert.equal(res.code, 0);
|
||||||
|
assert.equal(res.stdout.trim(), '');
|
||||||
|
rmSync(dir, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
test('source: resume + handoff in cwd → injected and archived', async () => {
|
||||||
|
const dir = makeFixture();
|
||||||
|
writeFileSync(join(dir, 'NEXT-SESSION-PROMPT.local.md'), '# my handoff\n\nimportant content\n');
|
||||||
|
const res = await runHook(HOOK, { source: 'resume', cwd: dir });
|
||||||
|
assert.equal(res.code, 0);
|
||||||
|
// Stdout should be JSON with additionalContext containing the file
|
||||||
|
const json = JSON.parse(res.stdout);
|
||||||
|
assert.equal(json.hookSpecificOutput.hookEventName, 'SessionStart');
|
||||||
|
assert.match(json.hookSpecificOutput.additionalContext, /important content/);
|
||||||
|
assert.match(json.hookSpecificOutput.additionalContext, /<session-handoff/);
|
||||||
|
// File should be archived
|
||||||
|
assert.ok(!existsSync(join(dir, 'NEXT-SESSION-PROMPT.local.md')), 'original should be renamed');
|
||||||
|
assert.ok(existsSync(join(dir, 'NEXT-SESSION-PROMPT.archived.local.md')), 'archive should exist');
|
||||||
|
rmSync(dir, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
test('source: compact + handoff in cwd → injected and archived', async () => {
|
||||||
|
const dir = makeFixture();
|
||||||
|
writeFileSync(join(dir, 'NEXT-SESSION-PROMPT.local.md'), '# compact handoff\n');
|
||||||
|
const res = await runHook(HOOK, { source: 'compact', cwd: dir });
|
||||||
|
assert.equal(res.code, 0);
|
||||||
|
const json = JSON.parse(res.stdout);
|
||||||
|
assert.match(json.hookSpecificOutput.additionalContext, /compact handoff/);
|
||||||
|
rmSync(dir, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
test('source: resume + handoff 2 levels above cwd → found and injected', async () => {
|
||||||
|
const root = makeFixture();
|
||||||
|
const sub = join(root, 'a', 'b');
|
||||||
|
mkdirSync(sub, { recursive: true });
|
||||||
|
writeFileSync(join(root, 'NEXT-SESSION-PROMPT.local.md'), '# parent handoff\n');
|
||||||
|
const res = await runHook(HOOK, { source: 'resume', cwd: sub });
|
||||||
|
assert.equal(res.code, 0);
|
||||||
|
const json = JSON.parse(res.stdout);
|
||||||
|
assert.match(json.hookSpecificOutput.additionalContext, /parent handoff/);
|
||||||
|
// Archived in the original parent location
|
||||||
|
assert.ok(existsSync(join(root, 'NEXT-SESSION-PROMPT.archived.local.md')));
|
||||||
|
rmSync(root, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
test('source: resume + no handoff anywhere → silent', async () => {
|
||||||
|
const dir = makeFixture();
|
||||||
|
const res = await runHook(HOOK, { source: 'resume', cwd: dir });
|
||||||
|
assert.equal(res.code, 0);
|
||||||
|
assert.equal(res.stdout.trim(), '');
|
||||||
|
rmSync(dir, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
test('source: resume + topic-slug variant NEXT-SESSION-foo.local.md → found', async () => {
|
||||||
|
const dir = makeFixture();
|
||||||
|
writeFileSync(join(dir, 'NEXT-SESSION-feature-x.local.md'), '# topic handoff\n');
|
||||||
|
const res = await runHook(HOOK, { source: 'resume', cwd: dir });
|
||||||
|
assert.equal(res.code, 0);
|
||||||
|
const json = JSON.parse(res.stdout);
|
||||||
|
assert.match(json.hookSpecificOutput.additionalContext, /topic handoff/);
|
||||||
|
rmSync(dir, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
test('archived files are not re-loaded on subsequent runs', async () => {
|
||||||
|
const dir = makeFixture();
|
||||||
|
writeFileSync(join(dir, 'NEXT-SESSION-PROMPT.archived.local.md'), 'stale - should not load\n');
|
||||||
|
const res = await runHook(HOOK, { source: 'resume', cwd: dir });
|
||||||
|
assert.equal(res.code, 0);
|
||||||
|
assert.equal(res.stdout.trim(), '', 'archived files must be ignored');
|
||||||
|
rmSync(dir, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
test('malformed JSON payload: silent exit 0', async () => {
|
||||||
|
const res = await runHook(HOOK, '{not valid');
|
||||||
|
assert.equal(res.code, 0);
|
||||||
|
assert.equal(res.stdout.trim(), '');
|
||||||
|
});
|
||||||
Loading…
Add table
Add a link
Reference in a new issue