@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.
- package/LICENSE +21 -21
- package/README.en.md +1 -1
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +7107 -7047
- package/bin/commands.mjs +134 -134
- package/bin/handoff-read.mjs +88 -88
- package/bin/installed-file-contract.mjs +154 -90
- package/bin/migration-baselines/official-origin-catalog.json +280 -1
- package/bin/official-origin-catalog.mjs +294 -294
- package/bin/progress/ICON-LICENSE.txt +21 -21
- package/bin/progress/assets.mjs +6 -6
- package/bin/progress/dashboard.mjs +134 -134
- package/bin/progress/icons.svg +36 -36
- package/bin/progress/index.html +31 -31
- package/bin/progress/launch.mjs +40 -40
- package/bin/progress/open.mjs +43 -43
- package/bin/progress/project-version.mjs +121 -121
- package/bin/progress/projection.mjs +144 -144
- package/bin/progress/renderer.js +152 -152
- package/bin/progress/server.mjs +78 -78
- package/bin/progress/styles.css +31 -31
- package/bin/prompt-mirror-core.mjs +84 -84
- package/bin/upgrade-inventory.mjs +243 -243
- package/bin/user-rules-router.mjs +4 -4
- package/docs/commands.md +2 -2
- package/docs/progress.md +73 -73
- package/package.json +22 -22
- package/packs/agent-governance.md +120 -120
- package/packs/closeout.md +91 -91
- package/packs/coding.md +28 -28
- package/packs/integrations.md +19 -19
- package/packs/knowledge.md +3 -3
- package/packs/onboarding.md +45 -45
- package/packs/research.md +30 -30
- package/packs/safety.md +2 -2
- package/runtime-core/AGENTS.core.md +161 -161
- package/runtime-core/CLAUDE.md +13 -13
- package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
- package/runtime-core/GEMINI.md +17 -17
- package/runtime-core/PROJECT_DECISIONS.md +43 -43
- package/runtime-core/PROJECT_INDEX.md +16 -16
- package/runtime-core/RULE_PACKS.md +1 -1
- package/runtime-core/SESSION_HANDOFF.md +180 -180
- package/runtime-core/SESSION_LOG.md +37 -37
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
- package/runtime-core/USER_RULES_ENTRY.md +5 -5
|
@@ -1,294 +1,294 @@
|
|
|
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
|
-
const requiredArtifactBoundManagedSegments = Object.freeze([
|
|
9
|
-
Object.freeze({ version: "0.3.38", targetRel: "AGENTS.md" }),
|
|
10
|
-
Object.freeze({ version: "0.3.41", targetRel: "AGENTS.md" })
|
|
11
|
-
]);
|
|
12
|
-
|
|
13
|
-
export const OFFICIAL_ORIGIN_CATALOG_SCHEMA = 1;
|
|
14
|
-
export const RECENT_PUBLISHED_UPGRADE_VERSION_LIMIT = 30;
|
|
15
|
-
|
|
16
|
-
export async function loadOfficialOriginCatalog(catalogPath = defaultCatalogPath) {
|
|
17
|
-
const catalog = JSON.parse(await readFile(catalogPath, "utf8"));
|
|
18
|
-
validateOfficialOriginCatalog(catalog);
|
|
19
|
-
return catalog;
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
// This selection limits WORK upgrade acceptance exercises. It does not alter
|
|
23
|
-
// catalog validation or runtime recognition of any older official release.
|
|
24
|
-
export function selectRecentPublishedStableVersions(catalog, limit = RECENT_PUBLISHED_UPGRADE_VERSION_LIMIT) {
|
|
25
|
-
if (!Number.isInteger(limit) || limit < 1) throw new Error("recent published upgrade limit must be a positive integer");
|
|
26
|
-
return Object.entries(catalog?.releases ?? {})
|
|
27
|
-
.filter(([version, release]) => (
|
|
28
|
-
/^\d+\.\d+\.\d+$/.test(version)
|
|
29
|
-
&& typeof release?.source?.npm?.spec === "string"
|
|
30
|
-
&& typeof release?.source?.githubRelease?.publishedAt === "string"
|
|
31
|
-
&& Number.isFinite(Date.parse(release.source.githubRelease.publishedAt))
|
|
32
|
-
))
|
|
33
|
-
.sort(([leftVersion, left], [rightVersion, right]) => (
|
|
34
|
-
Date.parse(left.source.githubRelease.publishedAt) - Date.parse(right.source.githubRelease.publishedAt)
|
|
35
|
-
|| compareStableVersions(leftVersion, rightVersion)
|
|
36
|
-
))
|
|
37
|
-
.slice(-limit)
|
|
38
|
-
.map(([version]) => version);
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
export function validateOfficialOriginCatalog(catalog) {
|
|
42
|
-
assertCatalogShape(catalog);
|
|
43
|
-
const digestCopy = { ...catalog };
|
|
44
|
-
delete digestCopy.catalogDigestSha256;
|
|
45
|
-
const expectedDigest = sha256(`${JSON.stringify(digestCopy)}\n`);
|
|
46
|
-
if (catalog.catalogDigestSha256 !== expectedDigest) throw new Error("official origin catalog integrity digest mismatch");
|
|
47
|
-
|
|
48
|
-
const targets = catalog.installedTargets.map((item) => item.targetRel);
|
|
49
|
-
const referenced = new Set();
|
|
50
|
-
for (const [version, release] of Object.entries(catalog.releases)) {
|
|
51
|
-
if (JSON.stringify(Object.keys(release.manifest)) !== JSON.stringify(targets)) {
|
|
52
|
-
throw new Error(`official origin catalog manifest coverage mismatch: ${version}`);
|
|
53
|
-
}
|
|
54
|
-
for (const [targetRel, entry] of Object.entries(release.manifest)) {
|
|
55
|
-
if (entry.state === "absent") continue;
|
|
56
|
-
if (entry.state !== "present" || !/^[0-9a-f]{64}$/.test(entry.rawSha256) || !/^[0-9a-f]{64}$/.test(entry.normalizedSha256)) {
|
|
57
|
-
throw new Error(`official origin catalog manifest entry invalid: ${version} ${targetRel}`);
|
|
58
|
-
}
|
|
59
|
-
const content = catalog.contents[entry.contentId];
|
|
60
|
-
if (!content || content.targetRel !== targetRel) {
|
|
61
|
-
throw new Error(`official origin catalog content target mismatch: ${version} ${targetRel}`);
|
|
62
|
-
}
|
|
63
|
-
if (entry.canonicalSha256 !== content.canonicalSha256) {
|
|
64
|
-
throw new Error(`official origin catalog canonical hash mismatch: ${version} ${targetRel}`);
|
|
65
|
-
}
|
|
66
|
-
referenced.add(entry.contentId);
|
|
67
|
-
}
|
|
68
|
-
for (const targetRel of Object.keys(release.managedSegments ?? {})) {
|
|
69
|
-
getArtifactBoundManagedSegment({ version, targetRel, catalog });
|
|
70
|
-
}
|
|
71
|
-
}
|
|
72
|
-
for (const required of requiredArtifactBoundManagedSegments) {
|
|
73
|
-
if (!getArtifactBoundManagedSegment({ ...required, catalog })) {
|
|
74
|
-
throw new Error(`official origin catalog missing required managed segment: ${required.version} ${required.targetRel}`);
|
|
75
|
-
}
|
|
76
|
-
}
|
|
77
|
-
|
|
78
|
-
for (const [contentId, content] of Object.entries(catalog.contents)) {
|
|
79
|
-
if (contentId !== sha256(`${content.targetRel}\0${content.text}`)) {
|
|
80
|
-
throw new Error(`official origin catalog content ID mismatch: ${contentId}`);
|
|
81
|
-
}
|
|
82
|
-
if (content.canonicalSha256 !== sha256(canonicalizeOfficialText(content.targetRel, content.text))) {
|
|
83
|
-
throw new Error(`official origin catalog content hash mismatch: ${contentId}`);
|
|
84
|
-
}
|
|
85
|
-
if (!referenced.has(contentId)) throw new Error(`official origin catalog has orphan content: ${contentId}`);
|
|
86
|
-
}
|
|
87
|
-
for (const [version, entry] of Object.entries(catalog.generatedShortcuts ?? {})) {
|
|
88
|
-
if (!/^\d+\.\d+\.\d+$/.test(version) || entry.npm?.spec !== catalog.packageName + '@' + version
|
|
89
|
-
|| !/^[a-f0-9]{40}$/.test(entry.npm?.shasum) || !entry.npm?.integrity?.startsWith('sha512-')
|
|
90
|
-
|| !/^[a-f0-9]{64}$/.test(entry.npm?.tarballSha256) || !/^[a-f0-9]{64}$/.test(entry.generatorSha256)
|
|
91
|
-
|| !entry.files || !Object.keys(entry.files).length) throw Error('invalid official shortcut artifact: ' + version);
|
|
92
|
-
for (const [file, digest] of Object.entries(entry.files)) {
|
|
93
|
-
if (!/^(?:dev\/handoff-kit\/(?:launch|open|server|projection|dashboard|project-version|assets)\.mjs|\.(?:agents|claude)\/skills\/handoff-kit-[a-z]+\/(?:SKILL\.md|agents\/openai\.yaml)|\.gemini\/commands\/handoff-kit-[a-z]+\.toml)$/.test(file)
|
|
94
|
-
|| !/^[a-f0-9]{64}$/.test(digest)) throw Error('invalid official shortcut path/hash: ' + version);
|
|
95
|
-
}
|
|
96
|
-
}
|
|
97
|
-
return true;
|
|
98
|
-
}
|
|
99
|
-
|
|
100
|
-
export function identifyOfficialOrigin({ targetRel, text, bytes = null, catalog }) {
|
|
101
|
-
assertCatalogShape(catalog);
|
|
102
|
-
const sourceText = String(text);
|
|
103
|
-
const rawBytes = bytes == null ? Buffer.from(sourceText, "utf8") : Buffer.from(bytes);
|
|
104
|
-
const rawSha256 = createHash("sha256").update(rawBytes).digest("hex");
|
|
105
|
-
const normalizedSha256 = sha256(normalizeNewlines(sourceText));
|
|
106
|
-
const canonicalSha256 = sha256(canonicalizeOfficialText(targetRel, sourceText));
|
|
107
|
-
const rawExactVersions = [];
|
|
108
|
-
const exactVersions = [];
|
|
109
|
-
const canonicalVersions = [];
|
|
110
|
-
|
|
111
|
-
for (const [version, release] of Object.entries(catalog.releases)) {
|
|
112
|
-
const entry = release.manifest[targetRel];
|
|
113
|
-
if (!entry || entry.state !== "present") continue;
|
|
114
|
-
if (entry.rawSha256 === rawSha256) rawExactVersions.push(version);
|
|
115
|
-
if (entry.normalizedSha256 === normalizedSha256) exactVersions.push(version);
|
|
116
|
-
else if (entry.canonicalSha256 === canonicalSha256) canonicalVersions.push(version);
|
|
117
|
-
}
|
|
118
|
-
|
|
119
|
-
return {
|
|
120
|
-
targetRel,
|
|
121
|
-
rawSha256,
|
|
122
|
-
rawExact: rawExactVersions.length > 0,
|
|
123
|
-
rawExactVersions,
|
|
124
|
-
normalizedSha256,
|
|
125
|
-
canonicalSha256,
|
|
126
|
-
exact: exactVersions.length > 0,
|
|
127
|
-
exactVersions,
|
|
128
|
-
canonicalVersions
|
|
129
|
-
};
|
|
130
|
-
}
|
|
131
|
-
|
|
132
|
-
export function getOfficialBaseline({ version, targetRel, catalog, root = null }) {
|
|
133
|
-
assertCatalogShape(catalog);
|
|
134
|
-
const release = catalog.releases[stripVersionPrefix(version)];
|
|
135
|
-
if (!release) return null;
|
|
136
|
-
const entry = release.manifest[targetRel];
|
|
137
|
-
if (!entry) return null;
|
|
138
|
-
if (entry.state === "absent") return { state: "absent", version: stripVersionPrefix(version), targetRel };
|
|
139
|
-
const content = catalog.contents[entry.contentId];
|
|
140
|
-
if (!content || content.targetRel !== targetRel) {
|
|
141
|
-
throw new Error(`official origin catalog content mismatch: ${version} ${targetRel}`);
|
|
142
|
-
}
|
|
143
|
-
return {
|
|
144
|
-
state: "present",
|
|
145
|
-
version: stripVersionPrefix(version),
|
|
146
|
-
targetRel,
|
|
147
|
-
text: materializeOfficialText(targetRel, content.text, { version: stripVersionPrefix(version), root }),
|
|
148
|
-
normalizedSha256: entry.normalizedSha256,
|
|
149
|
-
canonicalSha256: entry.canonicalSha256
|
|
150
|
-
};
|
|
151
|
-
}
|
|
152
|
-
|
|
153
|
-
// A managed segment is deliberately narrower than a whole-file catalog
|
|
154
|
-
// identity. It exists only when the release is tied to an npm artifact and
|
|
155
|
-
// its raw source plus transformed core bytes are recorded in this catalog.
|
|
156
|
-
// Markers, filenames, headings, and language never grant this authority.
|
|
157
|
-
export function getArtifactBoundManagedSegment({ version, targetRel, catalog }) {
|
|
158
|
-
assertCatalogShape(catalog);
|
|
159
|
-
const normalizedVersion = stripVersionPrefix(version);
|
|
160
|
-
const release = catalog.releases[normalizedVersion];
|
|
161
|
-
const segment = release?.managedSegments?.[targetRel];
|
|
162
|
-
if (!segment) return null;
|
|
163
|
-
const npm = release.source?.npm;
|
|
164
|
-
if (!npm || typeof npm.spec !== "string" || !/^[a-f0-9]{40}$/.test(npm.shasum)
|
|
165
|
-
|| typeof npm.integrity !== "string" || !npm.integrity.startsWith("sha512-")) {
|
|
166
|
-
throw new Error(`official origin catalog managed segment has no artifact identity: ${normalizedVersion} ${targetRel}`);
|
|
167
|
-
}
|
|
168
|
-
if (!segment || typeof segment !== "object" || Array.isArray(segment)
|
|
169
|
-
|| segment.sourceRel !== "runtime-core/AGENTS.core.md"
|
|
170
|
-
|| segment.transform?.kind !== "utf8-trim-wrapped-managed-core"
|
|
171
|
-
|| typeof segment.transform.beginMarker !== "string" || !segment.transform.beginMarker
|
|
172
|
-
|| typeof segment.transform.endMarker !== "string" || !segment.transform.endMarker
|
|
173
|
-
|| !validSegmentByteIdentity(segment.artifactSource)
|
|
174
|
-
|| !validSegmentByteIdentity(segment.transform.core)) {
|
|
175
|
-
throw new Error(`official origin catalog managed segment is invalid: ${normalizedVersion} ${targetRel}`);
|
|
176
|
-
}
|
|
177
|
-
return Object.freeze({
|
|
178
|
-
version: normalizedVersion,
|
|
179
|
-
targetRel,
|
|
180
|
-
sourceRel: segment.sourceRel,
|
|
181
|
-
artifact: Object.freeze({ spec: npm.spec, shasum: npm.shasum, integrity: npm.integrity }),
|
|
182
|
-
artifactSource: Object.freeze({ ...segment.artifactSource }),
|
|
183
|
-
transform: Object.freeze({
|
|
184
|
-
kind: segment.transform.kind,
|
|
185
|
-
beginMarker: segment.transform.beginMarker,
|
|
186
|
-
endMarker: segment.transform.endMarker,
|
|
187
|
-
core: Object.freeze({ ...segment.transform.core })
|
|
188
|
-
})
|
|
189
|
-
});
|
|
190
|
-
}
|
|
191
|
-
|
|
192
|
-
export function normalizeNewlines(text) {
|
|
193
|
-
return String(text).replace(/\r\n?/g, "\n");
|
|
194
|
-
}
|
|
195
|
-
|
|
196
|
-
export function canonicalizeOfficialText(targetRel, text) {
|
|
197
|
-
let normalized = normalizeNewlines(text);
|
|
198
|
-
if (targetRel === "dev/PROJECT_INDEX.md") {
|
|
199
|
-
normalized = normalized.replace(
|
|
200
|
-
/^(\|\s*Agent Handoff Kit template version\s*\|)\s*[^|\n]+?(\s*\|.*)$/m,
|
|
201
|
-
"$1 <VERSION>$2"
|
|
202
|
-
);
|
|
203
|
-
}
|
|
204
|
-
if (targetRel === "START_NEXT_SESSION_PROMPT.txt") {
|
|
205
|
-
normalized = canonicalizeOpeningRootLine(normalized);
|
|
206
|
-
}
|
|
207
|
-
if (targetRel === "dev/SESSION_HANDOFF.md") {
|
|
208
|
-
normalized = canonicalizeHandoffOpeningRoot(normalized);
|
|
209
|
-
}
|
|
210
|
-
return normalized;
|
|
211
|
-
}
|
|
212
|
-
|
|
213
|
-
export function materializeOfficialText(targetRel, text, { version = null, root = null } = {}) {
|
|
214
|
-
let materialized = normalizeNewlines(text);
|
|
215
|
-
if (targetRel === "dev/PROJECT_INDEX.md" && version) {
|
|
216
|
-
materialized = materialized.replace(
|
|
217
|
-
/^(\|\s*Agent Handoff Kit template version\s*\|)\s*<VERSION>(\s*\|.*)$/m,
|
|
218
|
-
`$1 ${stripVersionPrefix(version)}$2`
|
|
219
|
-
);
|
|
220
|
-
}
|
|
221
|
-
if (root && targetRel === "START_NEXT_SESSION_PROMPT.txt") {
|
|
222
|
-
materialized = materializeOpeningRootLine(materialized, root);
|
|
223
|
-
}
|
|
224
|
-
if (root && targetRel === "dev/SESSION_HANDOFF.md") {
|
|
225
|
-
materialized = materializeHandoffOpeningRoot(materialized, root);
|
|
226
|
-
}
|
|
227
|
-
return materialized;
|
|
228
|
-
}
|
|
229
|
-
|
|
230
|
-
export function sha256(text) {
|
|
231
|
-
return createHash("sha256").update(text, "utf8").digest("hex");
|
|
232
|
-
}
|
|
233
|
-
|
|
234
|
-
function canonicalizeOpeningRootLine(text) {
|
|
235
|
-
return text.replace(/^(Work in )[^\n]+?(\.(?: Read AGENTS\.md, then dev\/SESSION_HANDOFF\.md\.)?)$/m, "$1<ROOT>$2");
|
|
236
|
-
}
|
|
237
|
-
|
|
238
|
-
function canonicalizeHandoffOpeningRoot(text) {
|
|
239
|
-
const marker = "<!-- ack:section:next-session-opening-message -->";
|
|
240
|
-
const markerIndex = text.indexOf(marker);
|
|
241
|
-
if (markerIndex < 0) return text;
|
|
242
|
-
const fenceStart = text.indexOf("```text\n", markerIndex);
|
|
243
|
-
if (fenceStart < 0) return text;
|
|
244
|
-
const contentStart = fenceStart + "```text\n".length;
|
|
245
|
-
const fenceEnd = text.indexOf("\n```", contentStart);
|
|
246
|
-
if (fenceEnd < 0) return text;
|
|
247
|
-
const before = text.slice(0, contentStart);
|
|
248
|
-
const opening = canonicalizeOpeningRootLine(text.slice(contentStart, fenceEnd));
|
|
249
|
-
return `${before}${opening}${text.slice(fenceEnd)}`;
|
|
250
|
-
}
|
|
251
|
-
|
|
252
|
-
function materializeOpeningRootLine(text, root) {
|
|
253
|
-
return text.replace(/^(Work in )<ROOT>(\.(?: Read AGENTS\.md, then dev\/SESSION_HANDOFF\.md\.)?)$/m, `$1${root}$2`);
|
|
254
|
-
}
|
|
255
|
-
|
|
256
|
-
function materializeHandoffOpeningRoot(text, root) {
|
|
257
|
-
const marker = "<!-- ack:section:next-session-opening-message -->";
|
|
258
|
-
const markerIndex = text.indexOf(marker);
|
|
259
|
-
if (markerIndex < 0) return text;
|
|
260
|
-
const fenceStart = text.indexOf("```text\n", markerIndex);
|
|
261
|
-
if (fenceStart < 0) return text;
|
|
262
|
-
const contentStart = fenceStart + "```text\n".length;
|
|
263
|
-
const fenceEnd = text.indexOf("\n```", contentStart);
|
|
264
|
-
if (fenceEnd < 0) return text;
|
|
265
|
-
const before = text.slice(0, contentStart);
|
|
266
|
-
const opening = materializeOpeningRootLine(text.slice(contentStart, fenceEnd), root);
|
|
267
|
-
return `${before}${opening}${text.slice(fenceEnd)}`;
|
|
268
|
-
}
|
|
269
|
-
|
|
270
|
-
function stripVersionPrefix(version) {
|
|
271
|
-
return String(version ?? "").replace(/^v/, "");
|
|
272
|
-
}
|
|
273
|
-
|
|
274
|
-
function compareStableVersions(left, right) {
|
|
275
|
-
const a = left.split(".").map(Number);
|
|
276
|
-
const b = right.split(".").map(Number);
|
|
277
|
-
for (let index = 0; index < 3; index += 1) if (a[index] !== b[index]) return a[index] - b[index];
|
|
278
|
-
return 0;
|
|
279
|
-
}
|
|
280
|
-
|
|
281
|
-
function validSegmentByteIdentity(value) {
|
|
282
|
-
return Boolean(value && typeof value === "object" && !Array.isArray(value)
|
|
283
|
-
&& /^[a-f0-9]{64}$/.test(value.sha256)
|
|
284
|
-
&& Number.isInteger(value.bytes) && value.bytes >= 0);
|
|
285
|
-
}
|
|
286
|
-
|
|
287
|
-
function assertCatalogShape(catalog) {
|
|
288
|
-
if (!catalog || catalog.schemaVersion !== OFFICIAL_ORIGIN_CATALOG_SCHEMA) {
|
|
289
|
-
throw new Error(`unsupported official origin catalog schema: ${catalog?.schemaVersion ?? "missing"}`);
|
|
290
|
-
}
|
|
291
|
-
if (!catalog.releases || !catalog.contents || !Array.isArray(catalog.installedTargets)) {
|
|
292
|
-
throw new Error("official origin catalog is incomplete");
|
|
293
|
-
}
|
|
294
|
-
}
|
|
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
|
+
const requiredArtifactBoundManagedSegments = Object.freeze([
|
|
9
|
+
Object.freeze({ version: "0.3.38", targetRel: "AGENTS.md" }),
|
|
10
|
+
Object.freeze({ version: "0.3.41", targetRel: "AGENTS.md" })
|
|
11
|
+
]);
|
|
12
|
+
|
|
13
|
+
export const OFFICIAL_ORIGIN_CATALOG_SCHEMA = 1;
|
|
14
|
+
export const RECENT_PUBLISHED_UPGRADE_VERSION_LIMIT = 30;
|
|
15
|
+
|
|
16
|
+
export async function loadOfficialOriginCatalog(catalogPath = defaultCatalogPath) {
|
|
17
|
+
const catalog = JSON.parse(await readFile(catalogPath, "utf8"));
|
|
18
|
+
validateOfficialOriginCatalog(catalog);
|
|
19
|
+
return catalog;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
// This selection limits WORK upgrade acceptance exercises. It does not alter
|
|
23
|
+
// catalog validation or runtime recognition of any older official release.
|
|
24
|
+
export function selectRecentPublishedStableVersions(catalog, limit = RECENT_PUBLISHED_UPGRADE_VERSION_LIMIT) {
|
|
25
|
+
if (!Number.isInteger(limit) || limit < 1) throw new Error("recent published upgrade limit must be a positive integer");
|
|
26
|
+
return Object.entries(catalog?.releases ?? {})
|
|
27
|
+
.filter(([version, release]) => (
|
|
28
|
+
/^\d+\.\d+\.\d+$/.test(version)
|
|
29
|
+
&& typeof release?.source?.npm?.spec === "string"
|
|
30
|
+
&& typeof release?.source?.githubRelease?.publishedAt === "string"
|
|
31
|
+
&& Number.isFinite(Date.parse(release.source.githubRelease.publishedAt))
|
|
32
|
+
))
|
|
33
|
+
.sort(([leftVersion, left], [rightVersion, right]) => (
|
|
34
|
+
Date.parse(left.source.githubRelease.publishedAt) - Date.parse(right.source.githubRelease.publishedAt)
|
|
35
|
+
|| compareStableVersions(leftVersion, rightVersion)
|
|
36
|
+
))
|
|
37
|
+
.slice(-limit)
|
|
38
|
+
.map(([version]) => version);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export function validateOfficialOriginCatalog(catalog) {
|
|
42
|
+
assertCatalogShape(catalog);
|
|
43
|
+
const digestCopy = { ...catalog };
|
|
44
|
+
delete digestCopy.catalogDigestSha256;
|
|
45
|
+
const expectedDigest = sha256(`${JSON.stringify(digestCopy)}\n`);
|
|
46
|
+
if (catalog.catalogDigestSha256 !== expectedDigest) throw new Error("official origin catalog integrity digest mismatch");
|
|
47
|
+
|
|
48
|
+
const targets = catalog.installedTargets.map((item) => item.targetRel);
|
|
49
|
+
const referenced = new Set();
|
|
50
|
+
for (const [version, release] of Object.entries(catalog.releases)) {
|
|
51
|
+
if (JSON.stringify(Object.keys(release.manifest)) !== JSON.stringify(targets)) {
|
|
52
|
+
throw new Error(`official origin catalog manifest coverage mismatch: ${version}`);
|
|
53
|
+
}
|
|
54
|
+
for (const [targetRel, entry] of Object.entries(release.manifest)) {
|
|
55
|
+
if (entry.state === "absent") continue;
|
|
56
|
+
if (entry.state !== "present" || !/^[0-9a-f]{64}$/.test(entry.rawSha256) || !/^[0-9a-f]{64}$/.test(entry.normalizedSha256)) {
|
|
57
|
+
throw new Error(`official origin catalog manifest entry invalid: ${version} ${targetRel}`);
|
|
58
|
+
}
|
|
59
|
+
const content = catalog.contents[entry.contentId];
|
|
60
|
+
if (!content || content.targetRel !== targetRel) {
|
|
61
|
+
throw new Error(`official origin catalog content target mismatch: ${version} ${targetRel}`);
|
|
62
|
+
}
|
|
63
|
+
if (entry.canonicalSha256 !== content.canonicalSha256) {
|
|
64
|
+
throw new Error(`official origin catalog canonical hash mismatch: ${version} ${targetRel}`);
|
|
65
|
+
}
|
|
66
|
+
referenced.add(entry.contentId);
|
|
67
|
+
}
|
|
68
|
+
for (const targetRel of Object.keys(release.managedSegments ?? {})) {
|
|
69
|
+
getArtifactBoundManagedSegment({ version, targetRel, catalog });
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
for (const required of requiredArtifactBoundManagedSegments) {
|
|
73
|
+
if (!getArtifactBoundManagedSegment({ ...required, catalog })) {
|
|
74
|
+
throw new Error(`official origin catalog missing required managed segment: ${required.version} ${required.targetRel}`);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
for (const [contentId, content] of Object.entries(catalog.contents)) {
|
|
79
|
+
if (contentId !== sha256(`${content.targetRel}\0${content.text}`)) {
|
|
80
|
+
throw new Error(`official origin catalog content ID mismatch: ${contentId}`);
|
|
81
|
+
}
|
|
82
|
+
if (content.canonicalSha256 !== sha256(canonicalizeOfficialText(content.targetRel, content.text))) {
|
|
83
|
+
throw new Error(`official origin catalog content hash mismatch: ${contentId}`);
|
|
84
|
+
}
|
|
85
|
+
if (!referenced.has(contentId)) throw new Error(`official origin catalog has orphan content: ${contentId}`);
|
|
86
|
+
}
|
|
87
|
+
for (const [version, entry] of Object.entries(catalog.generatedShortcuts ?? {})) {
|
|
88
|
+
if (!/^\d+\.\d+\.\d+$/.test(version) || entry.npm?.spec !== catalog.packageName + '@' + version
|
|
89
|
+
|| !/^[a-f0-9]{40}$/.test(entry.npm?.shasum) || !entry.npm?.integrity?.startsWith('sha512-')
|
|
90
|
+
|| !/^[a-f0-9]{64}$/.test(entry.npm?.tarballSha256) || !/^[a-f0-9]{64}$/.test(entry.generatorSha256)
|
|
91
|
+
|| !entry.files || !Object.keys(entry.files).length) throw Error('invalid official shortcut artifact: ' + version);
|
|
92
|
+
for (const [file, digest] of Object.entries(entry.files)) {
|
|
93
|
+
if (!/^(?:dev\/handoff-kit\/(?:launch|open|server|projection|dashboard|project-version|assets)\.mjs|\.(?:agents|claude)\/skills\/handoff-kit-[a-z]+\/(?:SKILL\.md|agents\/openai\.yaml)|\.gemini\/commands\/handoff-kit-[a-z]+\.toml)$/.test(file)
|
|
94
|
+
|| !/^[a-f0-9]{64}$/.test(digest)) throw Error('invalid official shortcut path/hash: ' + version);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
return true;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export function identifyOfficialOrigin({ targetRel, text, bytes = null, catalog }) {
|
|
101
|
+
assertCatalogShape(catalog);
|
|
102
|
+
const sourceText = String(text);
|
|
103
|
+
const rawBytes = bytes == null ? Buffer.from(sourceText, "utf8") : Buffer.from(bytes);
|
|
104
|
+
const rawSha256 = createHash("sha256").update(rawBytes).digest("hex");
|
|
105
|
+
const normalizedSha256 = sha256(normalizeNewlines(sourceText));
|
|
106
|
+
const canonicalSha256 = sha256(canonicalizeOfficialText(targetRel, sourceText));
|
|
107
|
+
const rawExactVersions = [];
|
|
108
|
+
const exactVersions = [];
|
|
109
|
+
const canonicalVersions = [];
|
|
110
|
+
|
|
111
|
+
for (const [version, release] of Object.entries(catalog.releases)) {
|
|
112
|
+
const entry = release.manifest[targetRel];
|
|
113
|
+
if (!entry || entry.state !== "present") continue;
|
|
114
|
+
if (entry.rawSha256 === rawSha256) rawExactVersions.push(version);
|
|
115
|
+
if (entry.normalizedSha256 === normalizedSha256) exactVersions.push(version);
|
|
116
|
+
else if (entry.canonicalSha256 === canonicalSha256) canonicalVersions.push(version);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
return {
|
|
120
|
+
targetRel,
|
|
121
|
+
rawSha256,
|
|
122
|
+
rawExact: rawExactVersions.length > 0,
|
|
123
|
+
rawExactVersions,
|
|
124
|
+
normalizedSha256,
|
|
125
|
+
canonicalSha256,
|
|
126
|
+
exact: exactVersions.length > 0,
|
|
127
|
+
exactVersions,
|
|
128
|
+
canonicalVersions
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
export function getOfficialBaseline({ version, targetRel, catalog, root = null }) {
|
|
133
|
+
assertCatalogShape(catalog);
|
|
134
|
+
const release = catalog.releases[stripVersionPrefix(version)];
|
|
135
|
+
if (!release) return null;
|
|
136
|
+
const entry = release.manifest[targetRel];
|
|
137
|
+
if (!entry) return null;
|
|
138
|
+
if (entry.state === "absent") return { state: "absent", version: stripVersionPrefix(version), targetRel };
|
|
139
|
+
const content = catalog.contents[entry.contentId];
|
|
140
|
+
if (!content || content.targetRel !== targetRel) {
|
|
141
|
+
throw new Error(`official origin catalog content mismatch: ${version} ${targetRel}`);
|
|
142
|
+
}
|
|
143
|
+
return {
|
|
144
|
+
state: "present",
|
|
145
|
+
version: stripVersionPrefix(version),
|
|
146
|
+
targetRel,
|
|
147
|
+
text: materializeOfficialText(targetRel, content.text, { version: stripVersionPrefix(version), root }),
|
|
148
|
+
normalizedSha256: entry.normalizedSha256,
|
|
149
|
+
canonicalSha256: entry.canonicalSha256
|
|
150
|
+
};
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
// A managed segment is deliberately narrower than a whole-file catalog
|
|
154
|
+
// identity. It exists only when the release is tied to an npm artifact and
|
|
155
|
+
// its raw source plus transformed core bytes are recorded in this catalog.
|
|
156
|
+
// Markers, filenames, headings, and language never grant this authority.
|
|
157
|
+
export function getArtifactBoundManagedSegment({ version, targetRel, catalog }) {
|
|
158
|
+
assertCatalogShape(catalog);
|
|
159
|
+
const normalizedVersion = stripVersionPrefix(version);
|
|
160
|
+
const release = catalog.releases[normalizedVersion];
|
|
161
|
+
const segment = release?.managedSegments?.[targetRel];
|
|
162
|
+
if (!segment) return null;
|
|
163
|
+
const npm = release.source?.npm;
|
|
164
|
+
if (!npm || typeof npm.spec !== "string" || !/^[a-f0-9]{40}$/.test(npm.shasum)
|
|
165
|
+
|| typeof npm.integrity !== "string" || !npm.integrity.startsWith("sha512-")) {
|
|
166
|
+
throw new Error(`official origin catalog managed segment has no artifact identity: ${normalizedVersion} ${targetRel}`);
|
|
167
|
+
}
|
|
168
|
+
if (!segment || typeof segment !== "object" || Array.isArray(segment)
|
|
169
|
+
|| segment.sourceRel !== "runtime-core/AGENTS.core.md"
|
|
170
|
+
|| segment.transform?.kind !== "utf8-trim-wrapped-managed-core"
|
|
171
|
+
|| typeof segment.transform.beginMarker !== "string" || !segment.transform.beginMarker
|
|
172
|
+
|| typeof segment.transform.endMarker !== "string" || !segment.transform.endMarker
|
|
173
|
+
|| !validSegmentByteIdentity(segment.artifactSource)
|
|
174
|
+
|| !validSegmentByteIdentity(segment.transform.core)) {
|
|
175
|
+
throw new Error(`official origin catalog managed segment is invalid: ${normalizedVersion} ${targetRel}`);
|
|
176
|
+
}
|
|
177
|
+
return Object.freeze({
|
|
178
|
+
version: normalizedVersion,
|
|
179
|
+
targetRel,
|
|
180
|
+
sourceRel: segment.sourceRel,
|
|
181
|
+
artifact: Object.freeze({ spec: npm.spec, shasum: npm.shasum, integrity: npm.integrity }),
|
|
182
|
+
artifactSource: Object.freeze({ ...segment.artifactSource }),
|
|
183
|
+
transform: Object.freeze({
|
|
184
|
+
kind: segment.transform.kind,
|
|
185
|
+
beginMarker: segment.transform.beginMarker,
|
|
186
|
+
endMarker: segment.transform.endMarker,
|
|
187
|
+
core: Object.freeze({ ...segment.transform.core })
|
|
188
|
+
})
|
|
189
|
+
});
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
export function normalizeNewlines(text) {
|
|
193
|
+
return String(text).replace(/\r\n?/g, "\n");
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
export function canonicalizeOfficialText(targetRel, text) {
|
|
197
|
+
let normalized = normalizeNewlines(text);
|
|
198
|
+
if (targetRel === "dev/PROJECT_INDEX.md") {
|
|
199
|
+
normalized = normalized.replace(
|
|
200
|
+
/^(\|\s*Agent Handoff Kit template version\s*\|)\s*[^|\n]+?(\s*\|.*)$/m,
|
|
201
|
+
"$1 <VERSION>$2"
|
|
202
|
+
);
|
|
203
|
+
}
|
|
204
|
+
if (targetRel === "START_NEXT_SESSION_PROMPT.txt") {
|
|
205
|
+
normalized = canonicalizeOpeningRootLine(normalized);
|
|
206
|
+
}
|
|
207
|
+
if (targetRel === "dev/SESSION_HANDOFF.md") {
|
|
208
|
+
normalized = canonicalizeHandoffOpeningRoot(normalized);
|
|
209
|
+
}
|
|
210
|
+
return normalized;
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
export function materializeOfficialText(targetRel, text, { version = null, root = null } = {}) {
|
|
214
|
+
let materialized = normalizeNewlines(text);
|
|
215
|
+
if (targetRel === "dev/PROJECT_INDEX.md" && version) {
|
|
216
|
+
materialized = materialized.replace(
|
|
217
|
+
/^(\|\s*Agent Handoff Kit template version\s*\|)\s*<VERSION>(\s*\|.*)$/m,
|
|
218
|
+
`$1 ${stripVersionPrefix(version)}$2`
|
|
219
|
+
);
|
|
220
|
+
}
|
|
221
|
+
if (root && targetRel === "START_NEXT_SESSION_PROMPT.txt") {
|
|
222
|
+
materialized = materializeOpeningRootLine(materialized, root);
|
|
223
|
+
}
|
|
224
|
+
if (root && targetRel === "dev/SESSION_HANDOFF.md") {
|
|
225
|
+
materialized = materializeHandoffOpeningRoot(materialized, root);
|
|
226
|
+
}
|
|
227
|
+
return materialized;
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
export function sha256(text) {
|
|
231
|
+
return createHash("sha256").update(text, "utf8").digest("hex");
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
function canonicalizeOpeningRootLine(text) {
|
|
235
|
+
return text.replace(/^(Work in )[^\n]+?(\.(?: Read AGENTS\.md, then dev\/SESSION_HANDOFF\.md\.)?)$/m, "$1<ROOT>$2");
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
function canonicalizeHandoffOpeningRoot(text) {
|
|
239
|
+
const marker = "<!-- ack:section:next-session-opening-message -->";
|
|
240
|
+
const markerIndex = text.indexOf(marker);
|
|
241
|
+
if (markerIndex < 0) return text;
|
|
242
|
+
const fenceStart = text.indexOf("```text\n", markerIndex);
|
|
243
|
+
if (fenceStart < 0) return text;
|
|
244
|
+
const contentStart = fenceStart + "```text\n".length;
|
|
245
|
+
const fenceEnd = text.indexOf("\n```", contentStart);
|
|
246
|
+
if (fenceEnd < 0) return text;
|
|
247
|
+
const before = text.slice(0, contentStart);
|
|
248
|
+
const opening = canonicalizeOpeningRootLine(text.slice(contentStart, fenceEnd));
|
|
249
|
+
return `${before}${opening}${text.slice(fenceEnd)}`;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
function materializeOpeningRootLine(text, root) {
|
|
253
|
+
return text.replace(/^(Work in )<ROOT>(\.(?: Read AGENTS\.md, then dev\/SESSION_HANDOFF\.md\.)?)$/m, `$1${root}$2`);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
function materializeHandoffOpeningRoot(text, root) {
|
|
257
|
+
const marker = "<!-- ack:section:next-session-opening-message -->";
|
|
258
|
+
const markerIndex = text.indexOf(marker);
|
|
259
|
+
if (markerIndex < 0) return text;
|
|
260
|
+
const fenceStart = text.indexOf("```text\n", markerIndex);
|
|
261
|
+
if (fenceStart < 0) return text;
|
|
262
|
+
const contentStart = fenceStart + "```text\n".length;
|
|
263
|
+
const fenceEnd = text.indexOf("\n```", contentStart);
|
|
264
|
+
if (fenceEnd < 0) return text;
|
|
265
|
+
const before = text.slice(0, contentStart);
|
|
266
|
+
const opening = materializeOpeningRootLine(text.slice(contentStart, fenceEnd), root);
|
|
267
|
+
return `${before}${opening}${text.slice(fenceEnd)}`;
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
function stripVersionPrefix(version) {
|
|
271
|
+
return String(version ?? "").replace(/^v/, "");
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
function compareStableVersions(left, right) {
|
|
275
|
+
const a = left.split(".").map(Number);
|
|
276
|
+
const b = right.split(".").map(Number);
|
|
277
|
+
for (let index = 0; index < 3; index += 1) if (a[index] !== b[index]) return a[index] - b[index];
|
|
278
|
+
return 0;
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
function validSegmentByteIdentity(value) {
|
|
282
|
+
return Boolean(value && typeof value === "object" && !Array.isArray(value)
|
|
283
|
+
&& /^[a-f0-9]{64}$/.test(value.sha256)
|
|
284
|
+
&& Number.isInteger(value.bytes) && value.bytes >= 0);
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
function assertCatalogShape(catalog) {
|
|
288
|
+
if (!catalog || catalog.schemaVersion !== OFFICIAL_ORIGIN_CATALOG_SCHEMA) {
|
|
289
|
+
throw new Error(`unsupported official origin catalog schema: ${catalog?.schemaVersion ?? "missing"}`);
|
|
290
|
+
}
|
|
291
|
+
if (!catalog.releases || !catalog.contents || !Array.isArray(catalog.installedTargets)) {
|
|
292
|
+
throw new Error("official origin catalog is incomplete");
|
|
293
|
+
}
|
|
294
|
+
}
|
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) Tailwind Labs, Inc.
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) Tailwind Labs, Inc.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/bin/progress/assets.mjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
// Source assets; the normal installer materializes these same bytes locally.
|
|
2
|
-
import {readFileSync} from 'node:fs';
|
|
3
|
-
export const assetNames=Object.freeze(['index.html','styles.css','renderer.js','agent-handoff-kit-logo2-256.png','dashboard-hero.png','icons.svg','ICON-LICENSE.txt']);
|
|
4
|
-
export const installed=false;
|
|
5
|
-
export const runtimeVersion=JSON.parse(readFileSync(new URL('../../package.json',import.meta.url),'utf8')).version;
|
|
6
|
-
export function assetBytes(name){if(!assetNames.includes(name))throw Error('Unknown progress asset');return readFileSync(new URL(name,import.meta.url));}
|
|
1
|
+
// Source assets; the normal installer materializes these same bytes locally.
|
|
2
|
+
import {readFileSync} from 'node:fs';
|
|
3
|
+
export const assetNames=Object.freeze(['index.html','styles.css','renderer.js','agent-handoff-kit-logo2-256.png','dashboard-hero.png','icons.svg','ICON-LICENSE.txt']);
|
|
4
|
+
export const installed=false;
|
|
5
|
+
export const runtimeVersion=JSON.parse(readFileSync(new URL('../../package.json',import.meta.url),'utf8')).version;
|
|
6
|
+
export function assetBytes(name){if(!assetNames.includes(name))throw Error('Unknown progress asset');return readFileSync(new URL(name,import.meta.url));}
|