@adamchanadam/agent-handoff-kit 0.4.2 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/LICENSE +21 -21
  2. package/README.en.md +1 -1
  3. package/README.md +1 -1
  4. package/bin/agent-handoff-kit.mjs +7107 -7047
  5. package/bin/commands.mjs +134 -134
  6. package/bin/handoff-read.mjs +88 -88
  7. package/bin/installed-file-contract.mjs +154 -90
  8. package/bin/migration-baselines/official-origin-catalog.json +280 -1
  9. package/bin/official-origin-catalog.mjs +294 -294
  10. package/bin/progress/ICON-LICENSE.txt +21 -21
  11. package/bin/progress/assets.mjs +6 -6
  12. package/bin/progress/dashboard.mjs +134 -134
  13. package/bin/progress/icons.svg +36 -36
  14. package/bin/progress/index.html +31 -31
  15. package/bin/progress/launch.mjs +40 -40
  16. package/bin/progress/open.mjs +43 -43
  17. package/bin/progress/project-version.mjs +121 -121
  18. package/bin/progress/projection.mjs +144 -144
  19. package/bin/progress/renderer.js +152 -152
  20. package/bin/progress/server.mjs +78 -78
  21. package/bin/progress/styles.css +31 -31
  22. package/bin/prompt-mirror-core.mjs +84 -84
  23. package/bin/upgrade-inventory.mjs +243 -243
  24. package/bin/user-rules-router.mjs +4 -4
  25. package/docs/commands.md +2 -2
  26. package/docs/progress.md +73 -73
  27. package/package.json +22 -22
  28. package/packs/agent-governance.md +120 -120
  29. package/packs/closeout.md +91 -91
  30. package/packs/coding.md +28 -28
  31. package/packs/integrations.md +19 -19
  32. package/packs/knowledge.md +3 -3
  33. package/packs/onboarding.md +45 -45
  34. package/packs/research.md +30 -30
  35. package/packs/safety.md +2 -2
  36. package/runtime-core/AGENTS.core.md +161 -161
  37. package/runtime-core/CLAUDE.md +13 -13
  38. package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
  39. package/runtime-core/GEMINI.md +17 -17
  40. package/runtime-core/PROJECT_DECISIONS.md +43 -43
  41. package/runtime-core/PROJECT_INDEX.md +16 -16
  42. package/runtime-core/RULE_PACKS.md +1 -1
  43. package/runtime-core/SESSION_HANDOFF.md +180 -180
  44. package/runtime-core/SESSION_LOG.md +37 -37
  45. package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
  46. package/runtime-core/USER_RULES_ENTRY.md +5 -5
@@ -1,43 +1,43 @@
1
- import http from 'node:http';
2
- import path from 'node:path';
3
- import {fileURLToPath} from 'node:url';
4
- import {spawn} from 'node:child_process';
5
- import {progressIdentity,openProgressBrowser} from './server.mjs';
6
- import {createSource} from './projection.mjs';
7
- const cli=fileURLToPath(new URL('./launch.mjs',import.meta.url));
8
- const sleep=ms=>new Promise(r=>setTimeout(r,ms));
9
- export function probeProgress(port,{reopen=false}={}){
10
- return new Promise(resolve=>{
11
- let done=false,request,response,deadline;
12
- const end=value=>{if(done)return;done=true;clearTimeout(deadline);response?.destroy();request?.destroy();resolve(value);};
13
- // Inactivity timeouts alone can be kept alive by a foreign slow-trickle server.
14
- deadline=setTimeout(()=>end(null),350);
15
- request=http.get({hostname:'127.0.0.1',port,path:'/api/identity'+(reopen?'?reopen=1':'')},res=>{
16
- response=res;let text='';if(res.statusCode!==200){end(null);return;}
17
- res.on('data',chunk=>{text+=chunk;if(text.length>2048)end(null);});
18
- res.on('end',()=>{try{end(JSON.parse(text));}catch{end(null);}});
19
- res.on('error',()=>end(null));res.on('aborted',()=>end(null));
20
- });
21
- request.on('error',()=>end(null));
22
- });
23
- }
24
- export async function openProgress({root,version,port=0,openBrowser=true}){
25
- if(!Number.isInteger(port)||port<0||port>65535)throw Error('progress --port must be an integer from 0 to 65535');
26
- root=path.resolve(root);const identity=progressIdentity(root,version);
27
- const source=createSource(root);source.refresh({immediate:true});
28
- if(source.state.errors.lock)throw Error('Upgrade lock exists; recover the Kit upgrade before opening progress.');
29
- if(source.state.errors.handoff==='missing')throw Error('No dev/SESSION_HANDOFF.md found. Select an installed Kit project with --root.');
30
- // Spread deterministic choices across ranges: Windows can reserve adjacent port blocks.
31
- const ports=port?[port]:Array.from({length:12},(_,i)=>42000+((parseInt(identity.rootId.slice(0,8),16)+i*997)%18000));
32
- const same=other=>other&&Object.keys(identity).every(key=>other[key]===identity[key]);
33
- for(const candidate of ports){const existing=await probeProgress(candidate);if(same(existing)&&same(await probeProgress(candidate,{reopen:true}))){const url=`http://127.0.0.1:${candidate}`;if(openBrowser)openProgressBrowser(url);return{url,reused:true};}}
34
- for(const candidate of ports){let error=null,ended=false;const child=spawn(process.execPath,[cli,'--serve','--root',root,'--port',String(candidate),'--version',version,'--no-open'],{detached:true,windowsHide:true,stdio:'ignore'});
35
- child.once('error',e=>{error=e;ended=true;});child.once('exit',()=>{ended=true;});
36
- const deadline=Date.now()+6000;
37
- while(Date.now()<deadline&&!ended){if(same(await probeProgress(candidate))){child.unref();const url=`http://127.0.0.1:${candidate}`;if(openBrowser)openProgressBrowser(url);return{url,reused:false,pid:child.pid};}await sleep(80);}
38
- if(!ended)child.kill();if(error)throw Error('Could not start the local progress process.');
39
- // Another invocation may have won the same port while our child exited.
40
- if(same(await probeProgress(candidate))&&same(await probeProgress(candidate,{reopen:true}))){const url=`http://127.0.0.1:${candidate}`;if(openBrowser)openProgressBrowser(url);return{url,reused:true};}
41
- }
42
- throw Error('Could not open project progress. Check the project files and available loopback ports.');
43
- }
1
+ import http from 'node:http';
2
+ import path from 'node:path';
3
+ import {fileURLToPath} from 'node:url';
4
+ import {spawn} from 'node:child_process';
5
+ import {progressIdentity,openProgressBrowser} from './server.mjs';
6
+ import {createSource} from './projection.mjs';
7
+ const cli=fileURLToPath(new URL('./launch.mjs',import.meta.url));
8
+ const sleep=ms=>new Promise(r=>setTimeout(r,ms));
9
+ export function probeProgress(port,{reopen=false}={}){
10
+ return new Promise(resolve=>{
11
+ let done=false,request,response,deadline;
12
+ const end=value=>{if(done)return;done=true;clearTimeout(deadline);response?.destroy();request?.destroy();resolve(value);};
13
+ // Inactivity timeouts alone can be kept alive by a foreign slow-trickle server.
14
+ deadline=setTimeout(()=>end(null),350);
15
+ request=http.get({hostname:'127.0.0.1',port,path:'/api/identity'+(reopen?'?reopen=1':'')},res=>{
16
+ response=res;let text='';if(res.statusCode!==200){end(null);return;}
17
+ res.on('data',chunk=>{text+=chunk;if(text.length>2048)end(null);});
18
+ res.on('end',()=>{try{end(JSON.parse(text));}catch{end(null);}});
19
+ res.on('error',()=>end(null));res.on('aborted',()=>end(null));
20
+ });
21
+ request.on('error',()=>end(null));
22
+ });
23
+ }
24
+ export async function openProgress({root,version,port=0,openBrowser=true}){
25
+ if(!Number.isInteger(port)||port<0||port>65535)throw Error('progress --port must be an integer from 0 to 65535');
26
+ root=path.resolve(root);const identity=progressIdentity(root,version);
27
+ const source=createSource(root);source.refresh({immediate:true});
28
+ if(source.state.errors.lock)throw Error('Upgrade lock exists; recover the Kit upgrade before opening progress.');
29
+ if(source.state.errors.handoff==='missing')throw Error('No dev/SESSION_HANDOFF.md found. Select an installed Kit project with --root.');
30
+ // Spread deterministic choices across ranges: Windows can reserve adjacent port blocks.
31
+ const ports=port?[port]:Array.from({length:12},(_,i)=>42000+((parseInt(identity.rootId.slice(0,8),16)+i*997)%18000));
32
+ const same=other=>other&&Object.keys(identity).every(key=>other[key]===identity[key]);
33
+ for(const candidate of ports){const existing=await probeProgress(candidate);if(same(existing)&&same(await probeProgress(candidate,{reopen:true}))){const url=`http://127.0.0.1:${candidate}`;if(openBrowser)openProgressBrowser(url);return{url,reused:true};}}
34
+ for(const candidate of ports){let error=null,ended=false;const child=spawn(process.execPath,[cli,'--serve','--root',root,'--port',String(candidate),'--version',version,'--no-open'],{detached:true,windowsHide:true,stdio:'ignore'});
35
+ child.once('error',e=>{error=e;ended=true;});child.once('exit',()=>{ended=true;});
36
+ const deadline=Date.now()+6000;
37
+ while(Date.now()<deadline&&!ended){if(same(await probeProgress(candidate))){child.unref();const url=`http://127.0.0.1:${candidate}`;if(openBrowser)openProgressBrowser(url);return{url,reused:false,pid:child.pid};}await sleep(80);}
38
+ if(!ended)child.kill();if(error)throw Error('Could not start the local progress process.');
39
+ // Another invocation may have won the same port while our child exited.
40
+ if(same(await probeProgress(candidate))&&same(await probeProgress(candidate,{reopen:true}))){const url=`http://127.0.0.1:${candidate}`;if(openBrowser)openProgressBrowser(url);return{url,reused:true};}
41
+ }
42
+ throw Error('Could not open project progress. Check the project files and available loopback ports.');
43
+ }
@@ -1,121 +1,121 @@
1
- export function parseProjectIndexTemplateVersion(text) {
2
- return projectIndexTemplateVersionEvidence(text)?.version ?? null;
3
- }
4
-
5
- export function projectIndexTemplateVersionRow(text) {
6
- return projectIndexTemplateVersionEvidence(text)?.row ?? null;
7
- }
8
-
9
- export function materializeProjectIndexTemplateVersion(text, version) {
10
- if (!isStableSemver(version)) return text;
11
- const evidence = projectIndexTemplateVersionEvidence(text);
12
- if (!evidence) return text;
13
- return String(text).slice(0, evidence.rowStart)
14
- + evidence.row.replace(`| ${evidence.version} |`, `| ${version} |`)
15
- + String(text).slice(evidence.rowEnd);
16
- }
17
-
18
- function projectIndexTemplateVersionEvidence(text) {
19
- const value = String(text);
20
- const normalized = value.replace(/\r\n/g, "\n");
21
- const visibleLines = markdownVisibleLinesOutsideHiddenBlocks(value);
22
- const headings = [];
23
- for (const item of visibleLines) if (/^## [^\r\n]+$/u.test(item.text)) headings.push({ title: item.text.trim(), line: item.line, offset: item.normalizedStart });
24
- const stackHeadings = headings.filter((heading) => heading.title === "## Stack");
25
- if (stackHeadings.length !== 1) return null;
26
- const stack = stackHeadings[0];
27
- const nextHeading = headings.find((heading) => heading.line > stack.line);
28
- const stackStart = stack.offset + visibleLines.find((line) => line.line === stack.line)?.text.length + 1;
29
- const stackEnd = nextHeading ? nextHeading.offset : normalized.length;
30
- const stackLines = visibleLines.filter((line) => line.normalizedStart >= stackStart && line.normalizedStart < stackEnd);
31
- const candidateRows = [];
32
- const rowPattern = /^\| Agent Handoff Kit template version \| ([^|\n]+) \| [^|\n]+ \|$/u;
33
- for (const line of stackLines) {
34
- const match = rowPattern.exec(line.text);
35
- if (!match) continue;
36
- const version = match[1].trim();
37
- if (!isStableSemver(version)) return null;
38
- candidateRows.push({
39
- version,
40
- row: line.text,
41
- rowStart: line.start,
42
- rowEnd: line.end
43
- });
44
- }
45
- const versionLabelRows = stackLines.filter((line) => line.text.startsWith("| Agent Handoff Kit template version |"));
46
- if (versionLabelRows.length !== candidateRows.length || candidateRows.length !== 1) return null;
47
- const [row] = candidateRows;
48
- return { version: row.version, row: row.row, rowStart: row.rowStart, rowEnd: row.rowEnd };
49
- }
50
-
51
- export function markdownVisibleLinesOutsideHiddenBlocks(text) {
52
- const value = String(text);
53
- const normalized = value.replace(/\r\n/g, "\n");
54
- const lines = normalized.split("\n");
55
- const result = [];
56
- let offset = 0;
57
- let fence = null;
58
- let inComment = false;
59
- for (let index = 0; index < lines.length; index += 1) {
60
- const line = lines[index];
61
- if (inComment) {
62
- if (line.includes("-->")) inComment = false;
63
- offset += line.length + 1;
64
- continue;
65
- }
66
- const fenceMatch = /^\s{0,3}(`{3,}|~{3,})(?![`~])(.*)$/u.exec(line);
67
- const fenceRun = fenceMatch?.[1] ?? null;
68
- if (fence) {
69
- if (
70
- fenceRun
71
- && fenceRun[0] === fence.char
72
- && fenceRun.length >= fence.length
73
- && /^\s*$/u.test(fenceMatch?.[2] ?? "")
74
- ) {
75
- fence = null;
76
- }
77
- offset += line.length + 1;
78
- continue;
79
- }
80
- if (fenceRun) {
81
- fence = { char: fenceRun[0], length: fenceRun.length };
82
- offset += line.length + 1;
83
- continue;
84
- }
85
- const commentStart = line.indexOf("<!--");
86
- if (commentStart >= 0) {
87
- if (line.indexOf("-->", commentStart + 4) < 0) inComment = true;
88
- offset += line.length + 1;
89
- continue;
90
- }
91
- result.push({
92
- text: line,
93
- line: index,
94
- normalizedStart: offset,
95
- normalizedEnd: offset + line.length,
96
- start: originalOffsetForNormalizedOffset(value, offset),
97
- end: originalOffsetForNormalizedOffset(value, offset + line.length)
98
- });
99
- offset += line.length + 1;
100
- }
101
- return result;
102
- }
103
-
104
- function originalOffsetForNormalizedOffset(text, normalizedOffset) {
105
- let original = 0;
106
- let normalized = 0;
107
- while (original < text.length && normalized < normalizedOffset) {
108
- if (text[original] === "\r" && text[original + 1] === "\n") {
109
- original += 2;
110
- normalized += 1;
111
- } else {
112
- original += 1;
113
- normalized += 1;
114
- }
115
- }
116
- return original;
117
- }
118
-
119
- function isStableSemver(value) {
120
- return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.test(String(value));
121
- }
1
+ export function parseProjectIndexTemplateVersion(text) {
2
+ return projectIndexTemplateVersionEvidence(text)?.version ?? null;
3
+ }
4
+
5
+ export function projectIndexTemplateVersionRow(text) {
6
+ return projectIndexTemplateVersionEvidence(text)?.row ?? null;
7
+ }
8
+
9
+ export function materializeProjectIndexTemplateVersion(text, version) {
10
+ if (!isStableSemver(version)) return text;
11
+ const evidence = projectIndexTemplateVersionEvidence(text);
12
+ if (!evidence) return text;
13
+ return String(text).slice(0, evidence.rowStart)
14
+ + evidence.row.replace(`| ${evidence.version} |`, `| ${version} |`)
15
+ + String(text).slice(evidence.rowEnd);
16
+ }
17
+
18
+ function projectIndexTemplateVersionEvidence(text) {
19
+ const value = String(text);
20
+ const normalized = value.replace(/\r\n/g, "\n");
21
+ const visibleLines = markdownVisibleLinesOutsideHiddenBlocks(value);
22
+ const headings = [];
23
+ for (const item of visibleLines) if (/^## [^\r\n]+$/u.test(item.text)) headings.push({ title: item.text.trim(), line: item.line, offset: item.normalizedStart });
24
+ const stackHeadings = headings.filter((heading) => heading.title === "## Stack");
25
+ if (stackHeadings.length !== 1) return null;
26
+ const stack = stackHeadings[0];
27
+ const nextHeading = headings.find((heading) => heading.line > stack.line);
28
+ const stackStart = stack.offset + visibleLines.find((line) => line.line === stack.line)?.text.length + 1;
29
+ const stackEnd = nextHeading ? nextHeading.offset : normalized.length;
30
+ const stackLines = visibleLines.filter((line) => line.normalizedStart >= stackStart && line.normalizedStart < stackEnd);
31
+ const candidateRows = [];
32
+ const rowPattern = /^\| Agent Handoff Kit template version \| ([^|\n]+) \| [^|\n]+ \|$/u;
33
+ for (const line of stackLines) {
34
+ const match = rowPattern.exec(line.text);
35
+ if (!match) continue;
36
+ const version = match[1].trim();
37
+ if (!isStableSemver(version)) return null;
38
+ candidateRows.push({
39
+ version,
40
+ row: line.text,
41
+ rowStart: line.start,
42
+ rowEnd: line.end
43
+ });
44
+ }
45
+ const versionLabelRows = stackLines.filter((line) => line.text.startsWith("| Agent Handoff Kit template version |"));
46
+ if (versionLabelRows.length !== candidateRows.length || candidateRows.length !== 1) return null;
47
+ const [row] = candidateRows;
48
+ return { version: row.version, row: row.row, rowStart: row.rowStart, rowEnd: row.rowEnd };
49
+ }
50
+
51
+ export function markdownVisibleLinesOutsideHiddenBlocks(text) {
52
+ const value = String(text);
53
+ const normalized = value.replace(/\r\n/g, "\n");
54
+ const lines = normalized.split("\n");
55
+ const result = [];
56
+ let offset = 0;
57
+ let fence = null;
58
+ let inComment = false;
59
+ for (let index = 0; index < lines.length; index += 1) {
60
+ const line = lines[index];
61
+ if (inComment) {
62
+ if (line.includes("-->")) inComment = false;
63
+ offset += line.length + 1;
64
+ continue;
65
+ }
66
+ const fenceMatch = /^\s{0,3}(`{3,}|~{3,})(?![`~])(.*)$/u.exec(line);
67
+ const fenceRun = fenceMatch?.[1] ?? null;
68
+ if (fence) {
69
+ if (
70
+ fenceRun
71
+ && fenceRun[0] === fence.char
72
+ && fenceRun.length >= fence.length
73
+ && /^\s*$/u.test(fenceMatch?.[2] ?? "")
74
+ ) {
75
+ fence = null;
76
+ }
77
+ offset += line.length + 1;
78
+ continue;
79
+ }
80
+ if (fenceRun) {
81
+ fence = { char: fenceRun[0], length: fenceRun.length };
82
+ offset += line.length + 1;
83
+ continue;
84
+ }
85
+ const commentStart = line.indexOf("<!--");
86
+ if (commentStart >= 0) {
87
+ if (line.indexOf("-->", commentStart + 4) < 0) inComment = true;
88
+ offset += line.length + 1;
89
+ continue;
90
+ }
91
+ result.push({
92
+ text: line,
93
+ line: index,
94
+ normalizedStart: offset,
95
+ normalizedEnd: offset + line.length,
96
+ start: originalOffsetForNormalizedOffset(value, offset),
97
+ end: originalOffsetForNormalizedOffset(value, offset + line.length)
98
+ });
99
+ offset += line.length + 1;
100
+ }
101
+ return result;
102
+ }
103
+
104
+ function originalOffsetForNormalizedOffset(text, normalizedOffset) {
105
+ let original = 0;
106
+ let normalized = 0;
107
+ while (original < text.length && normalized < normalizedOffset) {
108
+ if (text[original] === "\r" && text[original + 1] === "\n") {
109
+ original += 2;
110
+ normalized += 1;
111
+ } else {
112
+ original += 1;
113
+ normalized += 1;
114
+ }
115
+ }
116
+ return original;
117
+ }
118
+
119
+ function isStableSemver(value) {
120
+ return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.test(String(value));
121
+ }