@adamchanadam/agent-handoff-kit 0.3.40 → 0.3.42
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.
- package/README.md +34 -34
- package/bin/agent-handoff-kit.mjs +4663 -2366
- package/bin/installed-file-contract.mjs +74 -0
- package/bin/migration-baselines/official-origin-catalog.json +10039 -0
- package/bin/official-origin-catalog.mjs +248 -0
- package/bin/semantic-candidate.mjs +594 -0
- package/bin/upgrade-inventory.mjs +587 -0
- package/bin/user-rules-router.mjs +461 -0
- package/package.json +1 -1
- package/packs/closeout.md +15 -13
- package/packs/communication.md +8 -6
- package/packs/onboarding.md +1 -1
- package/runtime-core/AGENTS.core.md +8 -5
- package/runtime-core/PROJECT_INDEX.md +73 -73
- package/runtime-core/SESSION_HANDOFF.md +12 -6
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
- package/runtime-core/USER_RULES.md +30 -0
- package/runtime-core/USER_RULES_ENTRY.md +7 -0
- package/bin/migration-baselines/v0.3.38/integrations.md +0 -235
- package/bin/migration-baselines/v0.3.38/onboarding.md +0 -201
- package/bin/migration-baselines/v0.3.38/safety.md +0 -46
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { readFile } from "node:fs/promises";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
|
|
6
|
+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
7
|
+
const defaultCatalogPath = path.join(__dirname, "migration-baselines", "official-origin-catalog.json");
|
|
8
|
+
|
|
9
|
+
export const OFFICIAL_ORIGIN_CATALOG_SCHEMA = 1;
|
|
10
|
+
|
|
11
|
+
export async function loadOfficialOriginCatalog(catalogPath = defaultCatalogPath) {
|
|
12
|
+
const catalog = JSON.parse(await readFile(catalogPath, "utf8"));
|
|
13
|
+
validateOfficialOriginCatalog(catalog);
|
|
14
|
+
return catalog;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export function validateOfficialOriginCatalog(catalog) {
|
|
18
|
+
assertCatalogShape(catalog);
|
|
19
|
+
const digestCopy = { ...catalog };
|
|
20
|
+
delete digestCopy.catalogDigestSha256;
|
|
21
|
+
const expectedDigest = sha256(`${JSON.stringify(digestCopy)}\n`);
|
|
22
|
+
if (catalog.catalogDigestSha256 !== expectedDigest) throw new Error("official origin catalog integrity digest mismatch");
|
|
23
|
+
|
|
24
|
+
const targets = catalog.installedTargets.map((item) => item.targetRel);
|
|
25
|
+
const referenced = new Set();
|
|
26
|
+
for (const [version, release] of Object.entries(catalog.releases)) {
|
|
27
|
+
if (JSON.stringify(Object.keys(release.manifest)) !== JSON.stringify(targets)) {
|
|
28
|
+
throw new Error(`official origin catalog manifest coverage mismatch: ${version}`);
|
|
29
|
+
}
|
|
30
|
+
for (const [targetRel, entry] of Object.entries(release.manifest)) {
|
|
31
|
+
if (entry.state === "absent") continue;
|
|
32
|
+
if (entry.state !== "present" || !/^[0-9a-f]{64}$/.test(entry.rawSha256) || !/^[0-9a-f]{64}$/.test(entry.normalizedSha256)) {
|
|
33
|
+
throw new Error(`official origin catalog manifest entry invalid: ${version} ${targetRel}`);
|
|
34
|
+
}
|
|
35
|
+
const content = catalog.contents[entry.contentId];
|
|
36
|
+
if (!content || content.targetRel !== targetRel) {
|
|
37
|
+
throw new Error(`official origin catalog content target mismatch: ${version} ${targetRel}`);
|
|
38
|
+
}
|
|
39
|
+
if (entry.canonicalSha256 !== content.canonicalSha256) {
|
|
40
|
+
throw new Error(`official origin catalog canonical hash mismatch: ${version} ${targetRel}`);
|
|
41
|
+
}
|
|
42
|
+
referenced.add(entry.contentId);
|
|
43
|
+
}
|
|
44
|
+
for (const targetRel of Object.keys(release.managedSegments ?? {})) {
|
|
45
|
+
getArtifactBoundManagedSegment({ version, targetRel, catalog });
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
for (const [contentId, content] of Object.entries(catalog.contents)) {
|
|
50
|
+
if (contentId !== sha256(`${content.targetRel}\0${content.text}`)) {
|
|
51
|
+
throw new Error(`official origin catalog content ID mismatch: ${contentId}`);
|
|
52
|
+
}
|
|
53
|
+
if (content.canonicalSha256 !== sha256(canonicalizeOfficialText(content.targetRel, content.text))) {
|
|
54
|
+
throw new Error(`official origin catalog content hash mismatch: ${contentId}`);
|
|
55
|
+
}
|
|
56
|
+
if (!referenced.has(contentId)) throw new Error(`official origin catalog has orphan content: ${contentId}`);
|
|
57
|
+
}
|
|
58
|
+
return true;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export function identifyOfficialOrigin({ targetRel, text, bytes = null, catalog }) {
|
|
62
|
+
assertCatalogShape(catalog);
|
|
63
|
+
const sourceText = String(text);
|
|
64
|
+
const rawBytes = bytes == null ? Buffer.from(sourceText, "utf8") : Buffer.from(bytes);
|
|
65
|
+
const rawSha256 = createHash("sha256").update(rawBytes).digest("hex");
|
|
66
|
+
const normalizedSha256 = sha256(normalizeNewlines(sourceText));
|
|
67
|
+
const canonicalSha256 = sha256(canonicalizeOfficialText(targetRel, sourceText));
|
|
68
|
+
const rawExactVersions = [];
|
|
69
|
+
const exactVersions = [];
|
|
70
|
+
const canonicalVersions = [];
|
|
71
|
+
|
|
72
|
+
for (const [version, release] of Object.entries(catalog.releases)) {
|
|
73
|
+
const entry = release.manifest[targetRel];
|
|
74
|
+
if (!entry || entry.state !== "present") continue;
|
|
75
|
+
if (entry.rawSha256 === rawSha256) rawExactVersions.push(version);
|
|
76
|
+
if (entry.normalizedSha256 === normalizedSha256) exactVersions.push(version);
|
|
77
|
+
else if (entry.canonicalSha256 === canonicalSha256) canonicalVersions.push(version);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
return {
|
|
81
|
+
targetRel,
|
|
82
|
+
rawSha256,
|
|
83
|
+
rawExact: rawExactVersions.length > 0,
|
|
84
|
+
rawExactVersions,
|
|
85
|
+
normalizedSha256,
|
|
86
|
+
canonicalSha256,
|
|
87
|
+
exact: exactVersions.length > 0,
|
|
88
|
+
exactVersions,
|
|
89
|
+
canonicalVersions
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export function getOfficialBaseline({ version, targetRel, catalog, root = null }) {
|
|
94
|
+
assertCatalogShape(catalog);
|
|
95
|
+
const release = catalog.releases[stripVersionPrefix(version)];
|
|
96
|
+
if (!release) return null;
|
|
97
|
+
const entry = release.manifest[targetRel];
|
|
98
|
+
if (!entry) return null;
|
|
99
|
+
if (entry.state === "absent") return { state: "absent", version: stripVersionPrefix(version), targetRel };
|
|
100
|
+
const content = catalog.contents[entry.contentId];
|
|
101
|
+
if (!content || content.targetRel !== targetRel) {
|
|
102
|
+
throw new Error(`official origin catalog content mismatch: ${version} ${targetRel}`);
|
|
103
|
+
}
|
|
104
|
+
return {
|
|
105
|
+
state: "present",
|
|
106
|
+
version: stripVersionPrefix(version),
|
|
107
|
+
targetRel,
|
|
108
|
+
text: materializeOfficialText(targetRel, content.text, { version: stripVersionPrefix(version), root }),
|
|
109
|
+
normalizedSha256: entry.normalizedSha256,
|
|
110
|
+
canonicalSha256: entry.canonicalSha256
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// A managed segment is deliberately narrower than a whole-file catalog
|
|
115
|
+
// identity. It exists only when the release is tied to an npm artifact and
|
|
116
|
+
// its raw source plus transformed core bytes are recorded in this catalog.
|
|
117
|
+
// Markers, filenames, headings, and language never grant this authority.
|
|
118
|
+
export function getArtifactBoundManagedSegment({ version, targetRel, catalog }) {
|
|
119
|
+
assertCatalogShape(catalog);
|
|
120
|
+
const normalizedVersion = stripVersionPrefix(version);
|
|
121
|
+
const release = catalog.releases[normalizedVersion];
|
|
122
|
+
const segment = release?.managedSegments?.[targetRel];
|
|
123
|
+
if (!segment) return null;
|
|
124
|
+
const npm = release.source?.npm;
|
|
125
|
+
if (!npm || typeof npm.spec !== "string" || !/^[a-f0-9]{40}$/.test(npm.shasum)
|
|
126
|
+
|| typeof npm.integrity !== "string" || !npm.integrity.startsWith("sha512-")) {
|
|
127
|
+
throw new Error(`official origin catalog managed segment has no artifact identity: ${normalizedVersion} ${targetRel}`);
|
|
128
|
+
}
|
|
129
|
+
if (!segment || typeof segment !== "object" || Array.isArray(segment)
|
|
130
|
+
|| segment.sourceRel !== "runtime-core/AGENTS.core.md"
|
|
131
|
+
|| segment.transform?.kind !== "utf8-trim-wrapped-managed-core"
|
|
132
|
+
|| typeof segment.transform.beginMarker !== "string" || !segment.transform.beginMarker
|
|
133
|
+
|| typeof segment.transform.endMarker !== "string" || !segment.transform.endMarker
|
|
134
|
+
|| !validSegmentByteIdentity(segment.artifactSource)
|
|
135
|
+
|| !validSegmentByteIdentity(segment.transform.core)) {
|
|
136
|
+
throw new Error(`official origin catalog managed segment is invalid: ${normalizedVersion} ${targetRel}`);
|
|
137
|
+
}
|
|
138
|
+
return Object.freeze({
|
|
139
|
+
version: normalizedVersion,
|
|
140
|
+
targetRel,
|
|
141
|
+
sourceRel: segment.sourceRel,
|
|
142
|
+
artifact: Object.freeze({ spec: npm.spec, shasum: npm.shasum, integrity: npm.integrity }),
|
|
143
|
+
artifactSource: Object.freeze({ ...segment.artifactSource }),
|
|
144
|
+
transform: Object.freeze({
|
|
145
|
+
kind: segment.transform.kind,
|
|
146
|
+
beginMarker: segment.transform.beginMarker,
|
|
147
|
+
endMarker: segment.transform.endMarker,
|
|
148
|
+
core: Object.freeze({ ...segment.transform.core })
|
|
149
|
+
})
|
|
150
|
+
});
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
export function normalizeNewlines(text) {
|
|
154
|
+
return String(text).replace(/\r\n?/g, "\n");
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
export function canonicalizeOfficialText(targetRel, text) {
|
|
158
|
+
let normalized = normalizeNewlines(text);
|
|
159
|
+
if (targetRel === "dev/PROJECT_INDEX.md") {
|
|
160
|
+
normalized = normalized.replace(
|
|
161
|
+
/^(\|\s*Agent Handoff Kit template version\s*\|)\s*[^|\n]+?(\s*\|.*)$/m,
|
|
162
|
+
"$1 <VERSION>$2"
|
|
163
|
+
);
|
|
164
|
+
}
|
|
165
|
+
if (targetRel === "START_NEXT_SESSION_PROMPT.txt") {
|
|
166
|
+
normalized = canonicalizeOpeningRootLine(normalized);
|
|
167
|
+
}
|
|
168
|
+
if (targetRel === "dev/SESSION_HANDOFF.md") {
|
|
169
|
+
normalized = canonicalizeHandoffOpeningRoot(normalized);
|
|
170
|
+
}
|
|
171
|
+
return normalized;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
export function materializeOfficialText(targetRel, text, { version = null, root = null } = {}) {
|
|
175
|
+
let materialized = normalizeNewlines(text);
|
|
176
|
+
if (targetRel === "dev/PROJECT_INDEX.md" && version) {
|
|
177
|
+
materialized = materialized.replace(
|
|
178
|
+
/^(\|\s*Agent Handoff Kit template version\s*\|)\s*<VERSION>(\s*\|.*)$/m,
|
|
179
|
+
`$1 ${stripVersionPrefix(version)}$2`
|
|
180
|
+
);
|
|
181
|
+
}
|
|
182
|
+
if (root && targetRel === "START_NEXT_SESSION_PROMPT.txt") {
|
|
183
|
+
materialized = materializeOpeningRootLine(materialized, root);
|
|
184
|
+
}
|
|
185
|
+
if (root && targetRel === "dev/SESSION_HANDOFF.md") {
|
|
186
|
+
materialized = materializeHandoffOpeningRoot(materialized, root);
|
|
187
|
+
}
|
|
188
|
+
return materialized;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
export function sha256(text) {
|
|
192
|
+
return createHash("sha256").update(text, "utf8").digest("hex");
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
function canonicalizeOpeningRootLine(text) {
|
|
196
|
+
return text.replace(/^(Work in )[^\n]+?(\.(?: Read AGENTS\.md, then dev\/SESSION_HANDOFF\.md\.)?)$/m, "$1<ROOT>$2");
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
function canonicalizeHandoffOpeningRoot(text) {
|
|
200
|
+
const marker = "<!-- ack:section:next-session-opening-message -->";
|
|
201
|
+
const markerIndex = text.indexOf(marker);
|
|
202
|
+
if (markerIndex < 0) return text;
|
|
203
|
+
const fenceStart = text.indexOf("```text\n", markerIndex);
|
|
204
|
+
if (fenceStart < 0) return text;
|
|
205
|
+
const contentStart = fenceStart + "```text\n".length;
|
|
206
|
+
const fenceEnd = text.indexOf("\n```", contentStart);
|
|
207
|
+
if (fenceEnd < 0) return text;
|
|
208
|
+
const before = text.slice(0, contentStart);
|
|
209
|
+
const opening = canonicalizeOpeningRootLine(text.slice(contentStart, fenceEnd));
|
|
210
|
+
return `${before}${opening}${text.slice(fenceEnd)}`;
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
function materializeOpeningRootLine(text, root) {
|
|
214
|
+
return text.replace(/^(Work in )<ROOT>(\.(?: Read AGENTS\.md, then dev\/SESSION_HANDOFF\.md\.)?)$/m, `$1${root}$2`);
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
function materializeHandoffOpeningRoot(text, root) {
|
|
218
|
+
const marker = "<!-- ack:section:next-session-opening-message -->";
|
|
219
|
+
const markerIndex = text.indexOf(marker);
|
|
220
|
+
if (markerIndex < 0) return text;
|
|
221
|
+
const fenceStart = text.indexOf("```text\n", markerIndex);
|
|
222
|
+
if (fenceStart < 0) return text;
|
|
223
|
+
const contentStart = fenceStart + "```text\n".length;
|
|
224
|
+
const fenceEnd = text.indexOf("\n```", contentStart);
|
|
225
|
+
if (fenceEnd < 0) return text;
|
|
226
|
+
const before = text.slice(0, contentStart);
|
|
227
|
+
const opening = materializeOpeningRootLine(text.slice(contentStart, fenceEnd), root);
|
|
228
|
+
return `${before}${opening}${text.slice(fenceEnd)}`;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
function stripVersionPrefix(version) {
|
|
232
|
+
return String(version ?? "").replace(/^v/, "");
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
function validSegmentByteIdentity(value) {
|
|
236
|
+
return Boolean(value && typeof value === "object" && !Array.isArray(value)
|
|
237
|
+
&& /^[a-f0-9]{64}$/.test(value.sha256)
|
|
238
|
+
&& Number.isInteger(value.bytes) && value.bytes >= 0);
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
function assertCatalogShape(catalog) {
|
|
242
|
+
if (!catalog || catalog.schemaVersion !== OFFICIAL_ORIGIN_CATALOG_SCHEMA) {
|
|
243
|
+
throw new Error(`unsupported official origin catalog schema: ${catalog?.schemaVersion ?? "missing"}`);
|
|
244
|
+
}
|
|
245
|
+
if (!catalog.releases || !catalog.contents || !Array.isArray(catalog.installedTargets)) {
|
|
246
|
+
throw new Error("official origin catalog is incomplete");
|
|
247
|
+
}
|
|
248
|
+
}
|