@adamchanadam/agent-handoff-kit 0.4.1 → 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 -6887
- 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 +514 -1
- package/bin/official-origin-catalog.mjs +294 -267
- 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 +20 -20
- package/packs/knowledge.md +3 -3
- package/packs/onboarding.md +43 -39
- package/packs/research.md +30 -30
- package/packs/safety.md +2 -2
- package/runtime-core/AGENTS.core.md +161 -147
- 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 +2 -0
|
@@ -1,243 +1,243 @@
|
|
|
1
|
-
import { parseProjectIndexTemplateVersion, projectIndexTemplateVersionRow, materializeProjectIndexTemplateVersion, markdownVisibleLinesOutsideHiddenBlocks } from './progress/project-version.mjs';
|
|
2
|
-
export { parseProjectIndexTemplateVersion, projectIndexTemplateVersionRow, materializeProjectIndexTemplateVersion, markdownVisibleLinesOutsideHiddenBlocks } from './progress/project-version.mjs';
|
|
3
|
-
import { createHash } from "node:crypto";
|
|
4
|
-
import { lstat, readdir, readFile, realpath } from "node:fs/promises";
|
|
5
|
-
import path from "node:path";
|
|
6
|
-
import { installedFileContracts } from "./installed-file-contract.mjs";
|
|
7
|
-
import { FORMAL_USER_RULES_ENTRY_ANCHOR, readFormalUserRules } from "./user-rules-router.mjs";
|
|
8
|
-
|
|
9
|
-
export const UPGRADE_INVENTORY_SCHEMA = 1;
|
|
10
|
-
|
|
11
|
-
const formalEntryTargets = Object.freeze([
|
|
12
|
-
"AGENTS.md",
|
|
13
|
-
"CLAUDE.md",
|
|
14
|
-
"GEMINI.md",
|
|
15
|
-
"START_NEXT_SESSION_PROMPT.txt"
|
|
16
|
-
]);
|
|
17
|
-
|
|
18
|
-
const archiveDirectories = Object.freeze([
|
|
19
|
-
{ relative: "dev/SESSION_LOG_archive", classification: "session-log-archive" },
|
|
20
|
-
{ relative: "dev/session_log_archive", classification: "legacy-session-log-archive" }
|
|
21
|
-
]);
|
|
22
|
-
|
|
23
|
-
/**
|
|
24
|
-
* Builds a read-only, hash-bound description of the Kit data that an upgrade
|
|
25
|
-
* can reach now. Ordinary workspace files, generic Markdown references, and
|
|
26
|
-
* committed historical transaction receipts are not current upgrade authority.
|
|
27
|
-
*/
|
|
28
|
-
export async function buildUpgradeInventory({ root, contracts = installedFileContracts } = {}) {
|
|
29
|
-
if (!root) throw new Error("upgrade inventory requires a project root");
|
|
30
|
-
const rootPath = path.resolve(root);
|
|
31
|
-
const rootStats = await lstat(rootPath).catch((error) => {
|
|
32
|
-
if (error?.code === "ENOENT") return null;
|
|
33
|
-
throw error;
|
|
34
|
-
});
|
|
35
|
-
if (!rootStats?.isDirectory() || rootStats.isSymbolicLink()) {
|
|
36
|
-
throw new Error("upgrade inventory root must be a real directory");
|
|
37
|
-
}
|
|
38
|
-
const realRoot = await realpath(rootPath);
|
|
39
|
-
const entries = new Map();
|
|
40
|
-
const blockers = [];
|
|
41
|
-
|
|
42
|
-
const addBlocker = (relative, reason) => {
|
|
43
|
-
const key = `${relative}\0${reason}`;
|
|
44
|
-
if (!blockers.some((item) => `${item.path}\0${item.reason}` === key)) blockers.push({ path: relative, reason });
|
|
45
|
-
};
|
|
46
|
-
|
|
47
|
-
async function addFile(relative, classification, reachability = null) {
|
|
48
|
-
const normalized = normalizeProjectRelative(relative);
|
|
49
|
-
if (!normalized) {
|
|
50
|
-
addBlocker(String(relative), "reference escapes the selected project root");
|
|
51
|
-
return null;
|
|
52
|
-
}
|
|
53
|
-
const absolute = path.resolve(rootPath, normalized);
|
|
54
|
-
if (!isInside(rootPath, absolute)) {
|
|
55
|
-
addBlocker(normalized, "reference escapes the selected project root");
|
|
56
|
-
return null;
|
|
57
|
-
}
|
|
58
|
-
const stats = await lstat(absolute).catch((error) => {
|
|
59
|
-
if (error?.code === "ENOENT") return null;
|
|
60
|
-
throw error;
|
|
61
|
-
});
|
|
62
|
-
if (!stats) return null;
|
|
63
|
-
if (stats.isSymbolicLink()) {
|
|
64
|
-
addBlocker(normalized, "symbolic links and junctions are not accepted as inventory sources");
|
|
65
|
-
return null;
|
|
66
|
-
}
|
|
67
|
-
if (!stats.isFile()) {
|
|
68
|
-
addBlocker(normalized, "inventory source is not a regular file");
|
|
69
|
-
return null;
|
|
70
|
-
}
|
|
71
|
-
const resolved = await realpath(absolute);
|
|
72
|
-
if (!isInside(realRoot, resolved)) {
|
|
73
|
-
addBlocker(normalized, "resolved inventory source is outside the selected project root");
|
|
74
|
-
return null;
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
const buffer = await readFile(absolute);
|
|
78
|
-
let entry = entries.get(normalized);
|
|
79
|
-
if (!entry) {
|
|
80
|
-
entry = {
|
|
81
|
-
path: normalized,
|
|
82
|
-
sha256: sha256(buffer),
|
|
83
|
-
bytes: buffer.length,
|
|
84
|
-
classifications: new Set(),
|
|
85
|
-
reachability: new Map(),
|
|
86
|
-
text: decodeUtf8(buffer)
|
|
87
|
-
};
|
|
88
|
-
entries.set(normalized, entry);
|
|
89
|
-
}
|
|
90
|
-
entry.classifications.add(classification);
|
|
91
|
-
if (reachability) entry.reachability.set(`${reachability.from}\0${reachability.via}`, reachability);
|
|
92
|
-
return entry;
|
|
93
|
-
}
|
|
94
|
-
|
|
95
|
-
for (const contract of contracts) {
|
|
96
|
-
const isFormalEntry = formalEntryTargets.includes(contract.targetRel);
|
|
97
|
-
await addFile(
|
|
98
|
-
contract.targetRel,
|
|
99
|
-
"managed-contract",
|
|
100
|
-
isFormalEntry ? { from: "formal-entry", via: contract.targetRel } : { from: "managed-contract", via: contract.targetRel }
|
|
101
|
-
);
|
|
102
|
-
}
|
|
103
|
-
|
|
104
|
-
for (const directory of archiveDirectories) {
|
|
105
|
-
await addTree(directory.relative, directory.classification);
|
|
106
|
-
}
|
|
107
|
-
|
|
108
|
-
const agentsEntry = entries.get("AGENTS.md");
|
|
109
|
-
if (agentsEntry?.text?.includes(FORMAL_USER_RULES_ENTRY_ANCHOR)) {
|
|
110
|
-
try {
|
|
111
|
-
const formal = await readFormalUserRules({ root: rootPath, allowActiveTransaction: true });
|
|
112
|
-
await addFile(formal.routerPath, "formal-user-rules-router", { from: formal.entryPath, via: formal.routerPath });
|
|
113
|
-
for (const rule of formal.rules) {
|
|
114
|
-
await addFile(rule.path, "formal-user-rule-content", { from: formal.routerPath, via: rule.path });
|
|
115
|
-
}
|
|
116
|
-
} catch (error) {
|
|
117
|
-
addBlocker("dev/USER_RULES.md", `formal user-rules state is unsafe: ${String(error?.message ?? error)}`);
|
|
118
|
-
}
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
const frozenEntries = [...entries.values()]
|
|
122
|
-
.map((entry) => ({
|
|
123
|
-
path: entry.path,
|
|
124
|
-
sha256: entry.sha256,
|
|
125
|
-
bytes: entry.bytes,
|
|
126
|
-
classifications: [...entry.classifications].sort(),
|
|
127
|
-
reachability: [...entry.reachability.values()]
|
|
128
|
-
.sort((left, right) => `${left.from}\0${left.via}`.localeCompare(`${right.from}\0${right.via}`))
|
|
129
|
-
}))
|
|
130
|
-
.sort((left, right) => left.path.localeCompare(right.path));
|
|
131
|
-
const sortedBlockers = blockers.sort((left, right) => `${left.path}\0${left.reason}`.localeCompare(`${right.path}\0${right.reason}`));
|
|
132
|
-
const digestInput = {
|
|
133
|
-
schemaVersion: UPGRADE_INVENTORY_SCHEMA,
|
|
134
|
-
entries: frozenEntries,
|
|
135
|
-
blockers: sortedBlockers
|
|
136
|
-
};
|
|
137
|
-
|
|
138
|
-
return Object.freeze({
|
|
139
|
-
schemaVersion: UPGRADE_INVENTORY_SCHEMA,
|
|
140
|
-
status: sortedBlockers.length === 0 ? "ready" : "blocked",
|
|
141
|
-
entries: frozenEntries,
|
|
142
|
-
blockers: sortedBlockers,
|
|
143
|
-
inventorySha256: sha256(Buffer.from(`${JSON.stringify(digestInput)}\n`, "utf8")),
|
|
144
|
-
formalEntryTargets: formalEntryTargets.filter((target) => entries.has(target))
|
|
145
|
-
});
|
|
146
|
-
|
|
147
|
-
async function addTree(relativeDirectory, classification) {
|
|
148
|
-
const normalized = normalizeProjectRelative(relativeDirectory);
|
|
149
|
-
if (!normalized) {
|
|
150
|
-
addBlocker(String(relativeDirectory), "dynamic directory escapes the selected project root");
|
|
151
|
-
return;
|
|
152
|
-
}
|
|
153
|
-
const absolute = path.resolve(rootPath, normalized);
|
|
154
|
-
const stats = await lstat(absolute).catch((error) => {
|
|
155
|
-
if (error?.code === "ENOENT") return null;
|
|
156
|
-
throw error;
|
|
157
|
-
});
|
|
158
|
-
if (!stats) return;
|
|
159
|
-
if (!stats.isDirectory() || stats.isSymbolicLink()) {
|
|
160
|
-
addBlocker(normalized, "dynamic inventory directory is not a safe real directory");
|
|
161
|
-
return;
|
|
162
|
-
}
|
|
163
|
-
const resolved = await realpath(absolute);
|
|
164
|
-
if (!isInside(realRoot, resolved)) {
|
|
165
|
-
addBlocker(normalized, "dynamic inventory directory resolves outside the selected project root");
|
|
166
|
-
return;
|
|
167
|
-
}
|
|
168
|
-
for (const item of await readdir(absolute, { withFileTypes: true })) {
|
|
169
|
-
const child = `${normalized}/${item.name}`;
|
|
170
|
-
const childAbsolute = path.join(absolute, item.name);
|
|
171
|
-
const childStats = await lstat(childAbsolute).catch((error) => {
|
|
172
|
-
if (error?.code === "ENOENT") return null;
|
|
173
|
-
throw error;
|
|
174
|
-
});
|
|
175
|
-
if (!childStats) continue;
|
|
176
|
-
if (childStats.isSymbolicLink()) {
|
|
177
|
-
addBlocker(child, "dynamic inventory source is not a safe real file or directory");
|
|
178
|
-
} else if (childStats.isDirectory()) {
|
|
179
|
-
await addTree(child, classification);
|
|
180
|
-
} else if (childStats.isFile()) {
|
|
181
|
-
await addFile(child, classification, { from: "dynamic-state", via: normalized });
|
|
182
|
-
} else {
|
|
183
|
-
addBlocker(child, "dynamic inventory source is not a regular file or directory");
|
|
184
|
-
}
|
|
185
|
-
}
|
|
186
|
-
}
|
|
187
|
-
}
|
|
188
|
-
|
|
189
|
-
export async function readProjectIndexTemplateVersion(root) {
|
|
190
|
-
const bytes = await readFile(path.join(root, "dev", "PROJECT_INDEX.md")).catch((error) => {
|
|
191
|
-
if (error?.code === "ENOENT") return null;
|
|
192
|
-
throw error;
|
|
193
|
-
});
|
|
194
|
-
if (!bytes) return null;
|
|
195
|
-
return parseProjectIndexTemplateVersion(bytes.toString("utf8"));
|
|
196
|
-
}
|
|
197
|
-
|
|
198
|
-
export function extractExplicitLocalReferences(text) {
|
|
199
|
-
const matches = new Map();
|
|
200
|
-
const add = (raw, via) => {
|
|
201
|
-
const normalized = normalizeReference(raw);
|
|
202
|
-
if (normalized) matches.set(`${normalized}\0${via}`, { path: normalized, via });
|
|
203
|
-
};
|
|
204
|
-
for (const match of String(text).matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+[^)]*)?\)/g)) add(match[1], "markdown-link");
|
|
205
|
-
for (const match of String(text).matchAll(/`([^`\r\n]+)`/g)) add(match[1], "inline-code-path");
|
|
206
|
-
for (const match of String(text).matchAll(/^\s*@([^\s]+)\s*$/gm)) add(match[1], "bridge-import");
|
|
207
|
-
// Do not treat the dot before a filename extension as sentence punctuation.
|
|
208
|
-
// On Windows, the truncated `dev/USER_RULES` then aliases the real
|
|
209
|
-
// `dev/user_rules/` directory, making a valid formal router look unsafe.
|
|
210
|
-
for (const match of String(text).matchAll(/(?:^|[\s("'`])((?:[\p{L}\p{N}_-]+[\\/])+[\p{L}\p{N}_. -]*[\p{L}\p{N}_.-])(?=$|[\s,;:,。!?)\]}>"'])/gu)) add(match[1], "plain-local-path");
|
|
211
|
-
return [...matches.values()].sort((left, right) => `${left.path}\0${left.via}`.localeCompare(`${right.path}\0${right.via}`));
|
|
212
|
-
}
|
|
213
|
-
|
|
214
|
-
function normalizeReference(raw) {
|
|
215
|
-
const value = String(raw).trim().replace(/^<|>$/g, "");
|
|
216
|
-
if (!value || value.includes("://") || value.startsWith("~") || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith("/")) return null;
|
|
217
|
-
const withoutFragment = value.split(/[?#]/, 1)[0].replaceAll("\\", "/");
|
|
218
|
-
if (!withoutFragment || withoutFragment.endsWith("/") || (!withoutFragment.includes("/") && !/\.[\p{L}\p{N}]+$/u.test(withoutFragment))) return null;
|
|
219
|
-
return normalizeProjectRelative(withoutFragment);
|
|
220
|
-
}
|
|
221
|
-
|
|
222
|
-
function normalizeProjectRelative(relative) {
|
|
223
|
-
const normalized = path.posix.normalize(String(relative).replaceAll("\\", "/").replace(/^\.\//, ""));
|
|
224
|
-
if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) return null;
|
|
225
|
-
return normalized;
|
|
226
|
-
}
|
|
227
|
-
|
|
228
|
-
function isInside(root, target) {
|
|
229
|
-
const relative = path.relative(path.resolve(root), path.resolve(target));
|
|
230
|
-
return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
|
|
231
|
-
}
|
|
232
|
-
|
|
233
|
-
function decodeUtf8(buffer) {
|
|
234
|
-
try {
|
|
235
|
-
return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
|
|
236
|
-
} catch {
|
|
237
|
-
return null;
|
|
238
|
-
}
|
|
239
|
-
}
|
|
240
|
-
|
|
241
|
-
function sha256(value) {
|
|
242
|
-
return createHash("sha256").update(value).digest("hex");
|
|
243
|
-
}
|
|
1
|
+
import { parseProjectIndexTemplateVersion, projectIndexTemplateVersionRow, materializeProjectIndexTemplateVersion, markdownVisibleLinesOutsideHiddenBlocks } from './progress/project-version.mjs';
|
|
2
|
+
export { parseProjectIndexTemplateVersion, projectIndexTemplateVersionRow, materializeProjectIndexTemplateVersion, markdownVisibleLinesOutsideHiddenBlocks } from './progress/project-version.mjs';
|
|
3
|
+
import { createHash } from "node:crypto";
|
|
4
|
+
import { lstat, readdir, readFile, realpath } from "node:fs/promises";
|
|
5
|
+
import path from "node:path";
|
|
6
|
+
import { installedFileContracts } from "./installed-file-contract.mjs";
|
|
7
|
+
import { FORMAL_USER_RULES_ENTRY_ANCHOR, readFormalUserRules } from "./user-rules-router.mjs";
|
|
8
|
+
|
|
9
|
+
export const UPGRADE_INVENTORY_SCHEMA = 1;
|
|
10
|
+
|
|
11
|
+
const formalEntryTargets = Object.freeze([
|
|
12
|
+
"AGENTS.md",
|
|
13
|
+
"CLAUDE.md",
|
|
14
|
+
"GEMINI.md",
|
|
15
|
+
"START_NEXT_SESSION_PROMPT.txt"
|
|
16
|
+
]);
|
|
17
|
+
|
|
18
|
+
const archiveDirectories = Object.freeze([
|
|
19
|
+
{ relative: "dev/SESSION_LOG_archive", classification: "session-log-archive" },
|
|
20
|
+
{ relative: "dev/session_log_archive", classification: "legacy-session-log-archive" }
|
|
21
|
+
]);
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Builds a read-only, hash-bound description of the Kit data that an upgrade
|
|
25
|
+
* can reach now. Ordinary workspace files, generic Markdown references, and
|
|
26
|
+
* committed historical transaction receipts are not current upgrade authority.
|
|
27
|
+
*/
|
|
28
|
+
export async function buildUpgradeInventory({ root, contracts = installedFileContracts } = {}) {
|
|
29
|
+
if (!root) throw new Error("upgrade inventory requires a project root");
|
|
30
|
+
const rootPath = path.resolve(root);
|
|
31
|
+
const rootStats = await lstat(rootPath).catch((error) => {
|
|
32
|
+
if (error?.code === "ENOENT") return null;
|
|
33
|
+
throw error;
|
|
34
|
+
});
|
|
35
|
+
if (!rootStats?.isDirectory() || rootStats.isSymbolicLink()) {
|
|
36
|
+
throw new Error("upgrade inventory root must be a real directory");
|
|
37
|
+
}
|
|
38
|
+
const realRoot = await realpath(rootPath);
|
|
39
|
+
const entries = new Map();
|
|
40
|
+
const blockers = [];
|
|
41
|
+
|
|
42
|
+
const addBlocker = (relative, reason) => {
|
|
43
|
+
const key = `${relative}\0${reason}`;
|
|
44
|
+
if (!blockers.some((item) => `${item.path}\0${item.reason}` === key)) blockers.push({ path: relative, reason });
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
async function addFile(relative, classification, reachability = null) {
|
|
48
|
+
const normalized = normalizeProjectRelative(relative);
|
|
49
|
+
if (!normalized) {
|
|
50
|
+
addBlocker(String(relative), "reference escapes the selected project root");
|
|
51
|
+
return null;
|
|
52
|
+
}
|
|
53
|
+
const absolute = path.resolve(rootPath, normalized);
|
|
54
|
+
if (!isInside(rootPath, absolute)) {
|
|
55
|
+
addBlocker(normalized, "reference escapes the selected project root");
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
const stats = await lstat(absolute).catch((error) => {
|
|
59
|
+
if (error?.code === "ENOENT") return null;
|
|
60
|
+
throw error;
|
|
61
|
+
});
|
|
62
|
+
if (!stats) return null;
|
|
63
|
+
if (stats.isSymbolicLink()) {
|
|
64
|
+
addBlocker(normalized, "symbolic links and junctions are not accepted as inventory sources");
|
|
65
|
+
return null;
|
|
66
|
+
}
|
|
67
|
+
if (!stats.isFile()) {
|
|
68
|
+
addBlocker(normalized, "inventory source is not a regular file");
|
|
69
|
+
return null;
|
|
70
|
+
}
|
|
71
|
+
const resolved = await realpath(absolute);
|
|
72
|
+
if (!isInside(realRoot, resolved)) {
|
|
73
|
+
addBlocker(normalized, "resolved inventory source is outside the selected project root");
|
|
74
|
+
return null;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const buffer = await readFile(absolute);
|
|
78
|
+
let entry = entries.get(normalized);
|
|
79
|
+
if (!entry) {
|
|
80
|
+
entry = {
|
|
81
|
+
path: normalized,
|
|
82
|
+
sha256: sha256(buffer),
|
|
83
|
+
bytes: buffer.length,
|
|
84
|
+
classifications: new Set(),
|
|
85
|
+
reachability: new Map(),
|
|
86
|
+
text: decodeUtf8(buffer)
|
|
87
|
+
};
|
|
88
|
+
entries.set(normalized, entry);
|
|
89
|
+
}
|
|
90
|
+
entry.classifications.add(classification);
|
|
91
|
+
if (reachability) entry.reachability.set(`${reachability.from}\0${reachability.via}`, reachability);
|
|
92
|
+
return entry;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
for (const contract of contracts) {
|
|
96
|
+
const isFormalEntry = formalEntryTargets.includes(contract.targetRel);
|
|
97
|
+
await addFile(
|
|
98
|
+
contract.targetRel,
|
|
99
|
+
"managed-contract",
|
|
100
|
+
isFormalEntry ? { from: "formal-entry", via: contract.targetRel } : { from: "managed-contract", via: contract.targetRel }
|
|
101
|
+
);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
for (const directory of archiveDirectories) {
|
|
105
|
+
await addTree(directory.relative, directory.classification);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const agentsEntry = entries.get("AGENTS.md");
|
|
109
|
+
if (agentsEntry?.text?.includes(FORMAL_USER_RULES_ENTRY_ANCHOR)) {
|
|
110
|
+
try {
|
|
111
|
+
const formal = await readFormalUserRules({ root: rootPath, allowActiveTransaction: true });
|
|
112
|
+
await addFile(formal.routerPath, "formal-user-rules-router", { from: formal.entryPath, via: formal.routerPath });
|
|
113
|
+
for (const rule of formal.rules) {
|
|
114
|
+
await addFile(rule.path, "formal-user-rule-content", { from: formal.routerPath, via: rule.path });
|
|
115
|
+
}
|
|
116
|
+
} catch (error) {
|
|
117
|
+
addBlocker("dev/USER_RULES.md", `formal user-rules state is unsafe: ${String(error?.message ?? error)}`);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const frozenEntries = [...entries.values()]
|
|
122
|
+
.map((entry) => ({
|
|
123
|
+
path: entry.path,
|
|
124
|
+
sha256: entry.sha256,
|
|
125
|
+
bytes: entry.bytes,
|
|
126
|
+
classifications: [...entry.classifications].sort(),
|
|
127
|
+
reachability: [...entry.reachability.values()]
|
|
128
|
+
.sort((left, right) => `${left.from}\0${left.via}`.localeCompare(`${right.from}\0${right.via}`))
|
|
129
|
+
}))
|
|
130
|
+
.sort((left, right) => left.path.localeCompare(right.path));
|
|
131
|
+
const sortedBlockers = blockers.sort((left, right) => `${left.path}\0${left.reason}`.localeCompare(`${right.path}\0${right.reason}`));
|
|
132
|
+
const digestInput = {
|
|
133
|
+
schemaVersion: UPGRADE_INVENTORY_SCHEMA,
|
|
134
|
+
entries: frozenEntries,
|
|
135
|
+
blockers: sortedBlockers
|
|
136
|
+
};
|
|
137
|
+
|
|
138
|
+
return Object.freeze({
|
|
139
|
+
schemaVersion: UPGRADE_INVENTORY_SCHEMA,
|
|
140
|
+
status: sortedBlockers.length === 0 ? "ready" : "blocked",
|
|
141
|
+
entries: frozenEntries,
|
|
142
|
+
blockers: sortedBlockers,
|
|
143
|
+
inventorySha256: sha256(Buffer.from(`${JSON.stringify(digestInput)}\n`, "utf8")),
|
|
144
|
+
formalEntryTargets: formalEntryTargets.filter((target) => entries.has(target))
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
async function addTree(relativeDirectory, classification) {
|
|
148
|
+
const normalized = normalizeProjectRelative(relativeDirectory);
|
|
149
|
+
if (!normalized) {
|
|
150
|
+
addBlocker(String(relativeDirectory), "dynamic directory escapes the selected project root");
|
|
151
|
+
return;
|
|
152
|
+
}
|
|
153
|
+
const absolute = path.resolve(rootPath, normalized);
|
|
154
|
+
const stats = await lstat(absolute).catch((error) => {
|
|
155
|
+
if (error?.code === "ENOENT") return null;
|
|
156
|
+
throw error;
|
|
157
|
+
});
|
|
158
|
+
if (!stats) return;
|
|
159
|
+
if (!stats.isDirectory() || stats.isSymbolicLink()) {
|
|
160
|
+
addBlocker(normalized, "dynamic inventory directory is not a safe real directory");
|
|
161
|
+
return;
|
|
162
|
+
}
|
|
163
|
+
const resolved = await realpath(absolute);
|
|
164
|
+
if (!isInside(realRoot, resolved)) {
|
|
165
|
+
addBlocker(normalized, "dynamic inventory directory resolves outside the selected project root");
|
|
166
|
+
return;
|
|
167
|
+
}
|
|
168
|
+
for (const item of await readdir(absolute, { withFileTypes: true })) {
|
|
169
|
+
const child = `${normalized}/${item.name}`;
|
|
170
|
+
const childAbsolute = path.join(absolute, item.name);
|
|
171
|
+
const childStats = await lstat(childAbsolute).catch((error) => {
|
|
172
|
+
if (error?.code === "ENOENT") return null;
|
|
173
|
+
throw error;
|
|
174
|
+
});
|
|
175
|
+
if (!childStats) continue;
|
|
176
|
+
if (childStats.isSymbolicLink()) {
|
|
177
|
+
addBlocker(child, "dynamic inventory source is not a safe real file or directory");
|
|
178
|
+
} else if (childStats.isDirectory()) {
|
|
179
|
+
await addTree(child, classification);
|
|
180
|
+
} else if (childStats.isFile()) {
|
|
181
|
+
await addFile(child, classification, { from: "dynamic-state", via: normalized });
|
|
182
|
+
} else {
|
|
183
|
+
addBlocker(child, "dynamic inventory source is not a regular file or directory");
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
export async function readProjectIndexTemplateVersion(root) {
|
|
190
|
+
const bytes = await readFile(path.join(root, "dev", "PROJECT_INDEX.md")).catch((error) => {
|
|
191
|
+
if (error?.code === "ENOENT") return null;
|
|
192
|
+
throw error;
|
|
193
|
+
});
|
|
194
|
+
if (!bytes) return null;
|
|
195
|
+
return parseProjectIndexTemplateVersion(bytes.toString("utf8"));
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
export function extractExplicitLocalReferences(text) {
|
|
199
|
+
const matches = new Map();
|
|
200
|
+
const add = (raw, via) => {
|
|
201
|
+
const normalized = normalizeReference(raw);
|
|
202
|
+
if (normalized) matches.set(`${normalized}\0${via}`, { path: normalized, via });
|
|
203
|
+
};
|
|
204
|
+
for (const match of String(text).matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+[^)]*)?\)/g)) add(match[1], "markdown-link");
|
|
205
|
+
for (const match of String(text).matchAll(/`([^`\r\n]+)`/g)) add(match[1], "inline-code-path");
|
|
206
|
+
for (const match of String(text).matchAll(/^\s*@([^\s]+)\s*$/gm)) add(match[1], "bridge-import");
|
|
207
|
+
// Do not treat the dot before a filename extension as sentence punctuation.
|
|
208
|
+
// On Windows, the truncated `dev/USER_RULES` then aliases the real
|
|
209
|
+
// `dev/user_rules/` directory, making a valid formal router look unsafe.
|
|
210
|
+
for (const match of String(text).matchAll(/(?:^|[\s("'`])((?:[\p{L}\p{N}_-]+[\\/])+[\p{L}\p{N}_. -]*[\p{L}\p{N}_.-])(?=$|[\s,;:,。!?)\]}>"'])/gu)) add(match[1], "plain-local-path");
|
|
211
|
+
return [...matches.values()].sort((left, right) => `${left.path}\0${left.via}`.localeCompare(`${right.path}\0${right.via}`));
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
function normalizeReference(raw) {
|
|
215
|
+
const value = String(raw).trim().replace(/^<|>$/g, "");
|
|
216
|
+
if (!value || value.includes("://") || value.startsWith("~") || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith("/")) return null;
|
|
217
|
+
const withoutFragment = value.split(/[?#]/, 1)[0].replaceAll("\\", "/");
|
|
218
|
+
if (!withoutFragment || withoutFragment.endsWith("/") || (!withoutFragment.includes("/") && !/\.[\p{L}\p{N}]+$/u.test(withoutFragment))) return null;
|
|
219
|
+
return normalizeProjectRelative(withoutFragment);
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
function normalizeProjectRelative(relative) {
|
|
223
|
+
const normalized = path.posix.normalize(String(relative).replaceAll("\\", "/").replace(/^\.\//, ""));
|
|
224
|
+
if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) return null;
|
|
225
|
+
return normalized;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
function isInside(root, target) {
|
|
229
|
+
const relative = path.relative(path.resolve(root), path.resolve(target));
|
|
230
|
+
return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
function decodeUtf8(buffer) {
|
|
234
|
+
try {
|
|
235
|
+
return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
|
|
236
|
+
} catch {
|
|
237
|
+
return null;
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
function sha256(value) {
|
|
242
|
+
return createHash("sha256").update(value).digest("hex");
|
|
243
|
+
}
|
|
@@ -133,10 +133,10 @@ function ensureStateRegion(routerText) {
|
|
|
133
133
|
export function renderUserRulesAcceptanceDigest(agentsText, digest) {
|
|
134
134
|
if (typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest)) throw new Error("user-rules acceptance digest is invalid");
|
|
135
135
|
const source = String(agentsText);
|
|
136
|
-
parseFormalUserRulesEntry(source);
|
|
137
|
-
// Validation above proves there is one active digest. Replace only that
|
|
138
|
-
// token; splitting/rejoining the file would rewrite mixed-newline user data.
|
|
139
|
-
return source.replace(acceptanceAnchorPattern, `<!-- ack:user-rules-acceptance:sha256=${digest} -->`);
|
|
136
|
+
parseFormalUserRulesEntry(source);
|
|
137
|
+
// Validation above proves there is one active digest. Replace only that
|
|
138
|
+
// token; splitting/rejoining the file would rewrite mixed-newline user data.
|
|
139
|
+
return source.replace(acceptanceAnchorPattern, `<!-- ack:user-rules-acceptance:sha256=${digest} -->`);
|
|
140
140
|
}
|
|
141
141
|
|
|
142
142
|
/**
|
package/docs/commands.md
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
| 交接功能出了問題 | [`/handoff-kit-check`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#check) |
|
|
19
19
|
| 想用最新正式版 | [`/handoff-kit-update`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#update) |
|
|
20
20
|
|
|
21
|
-
日常用開工、進度頁、收工;其他按需要用。每個指令的例子與注意事項都在[使用指南](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html)
|
|
21
|
+
日常用開工、進度頁、收工;其他按需要用。每個指令的例子與注意事項都在[使用指南](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html),不用另外讀一套教學。候選版 `handoff-kit-update` 受控實測必須在同一條 `npx --registry <loopback> ...` 呼叫明確傳入一般 registry,讓 npx 啟動的 CLI 繼承設定作更新檢查;專案 `.npmrc` 的讀回只是準備紀錄,不能證明已繼承,直接以 Node 執行亦不足。
|
|
22
22
|
|
|
23
23
|
### 安裝與選單
|
|
24
24
|
|
|
@@ -48,7 +48,7 @@ Enter shortcuts in your project’s AI conversation, not in the terminal. Claude
|
|
|
48
48
|
| Check whether the tool is installed correctly | [`/handoff-kit-check`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#check) |
|
|
49
49
|
| Get the latest released version | [`/handoff-kit-update`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#update) |
|
|
50
50
|
|
|
51
|
-
Start, Progress and Wrap up are the everyday shortcuts; use the others as needed. Examples and limits for each are in the [guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html), so you do not need a second set of instructions.
|
|
51
|
+
Start, Progress and Wrap up are the everyday shortcuts; use the others as needed. Examples and limits for each are in the [guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html), so you do not need a second set of instructions. Controlled candidate `handoff-kit-update` testing must pass the general registry explicitly on the same `npx --registry <loopback> ...` invocation, so the CLI launched by npx inherits it for the update check. A project `.npmrc` readback is setup metadata only, not proof of inheritance, and a direct Node run is insufficient.
|
|
52
52
|
|
|
53
53
|
### Installation and menus
|
|
54
54
|
|