@adamchanadam/agent-handoff-kit 0.4.0 → 0.4.1
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.en.md +77 -246
- package/README.md +77 -252
- package/bin/agent-handoff-kit.mjs +66 -26
- package/bin/commands.mjs +54 -6
- package/bin/installed-file-contract.mjs +79 -63
- package/bin/migration-baselines/official-origin-catalog.json +238 -1
- package/bin/official-origin-catalog.mjs +267 -257
- package/bin/progress/assets.mjs +6 -0
- package/bin/progress/dashboard.mjs +1 -1
- package/bin/progress/index.html +4 -1
- package/bin/progress/launch.mjs +40 -0
- package/bin/progress/open.mjs +4 -3
- package/bin/progress/project-version.mjs +121 -0
- package/bin/progress/renderer.js +1 -0
- package/bin/progress/server.mjs +5 -3
- package/bin/progress/styles.css +1 -1
- package/bin/upgrade-inventory.mjs +153 -273
- package/docs/commands.md +61 -59
- package/docs/progress.md +45 -39
- package/package.json +1 -1
|
@@ -1,98 +1,100 @@
|
|
|
1
|
-
import {
|
|
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";
|
|
2
4
|
import { lstat, readdir, readFile, realpath } from "node:fs/promises";
|
|
3
5
|
import path from "node:path";
|
|
4
6
|
import { installedFileContracts } from "./installed-file-contract.mjs";
|
|
5
7
|
import { FORMAL_USER_RULES_ENTRY_ANCHOR, readFormalUserRules } from "./user-rules-router.mjs";
|
|
6
|
-
|
|
8
|
+
|
|
7
9
|
export const UPGRADE_INVENTORY_SCHEMA = 1;
|
|
8
|
-
|
|
9
|
-
const formalEntryTargets = Object.freeze([
|
|
10
|
-
"AGENTS.md",
|
|
11
|
-
"CLAUDE.md",
|
|
12
|
-
"GEMINI.md",
|
|
13
|
-
"START_NEXT_SESSION_PROMPT.txt"
|
|
14
|
-
]);
|
|
15
|
-
|
|
10
|
+
|
|
11
|
+
const formalEntryTargets = Object.freeze([
|
|
12
|
+
"AGENTS.md",
|
|
13
|
+
"CLAUDE.md",
|
|
14
|
+
"GEMINI.md",
|
|
15
|
+
"START_NEXT_SESSION_PROMPT.txt"
|
|
16
|
+
]);
|
|
17
|
+
|
|
16
18
|
const archiveDirectories = Object.freeze([
|
|
17
19
|
{ relative: "dev/SESSION_LOG_archive", classification: "session-log-archive" },
|
|
18
20
|
{ relative: "dev/session_log_archive", classification: "legacy-session-log-archive" }
|
|
19
21
|
]);
|
|
20
|
-
|
|
22
|
+
|
|
21
23
|
/**
|
|
22
24
|
* Builds a read-only, hash-bound description of the Kit data that an upgrade
|
|
23
25
|
* can reach now. Ordinary workspace files, generic Markdown references, and
|
|
24
26
|
* committed historical transaction receipts are not current upgrade authority.
|
|
25
27
|
*/
|
|
26
|
-
export async function buildUpgradeInventory({ root, contracts = installedFileContracts } = {}) {
|
|
27
|
-
if (!root) throw new Error("upgrade inventory requires a project root");
|
|
28
|
-
const rootPath = path.resolve(root);
|
|
29
|
-
const rootStats = await lstat(rootPath).catch((error) => {
|
|
30
|
-
if (error?.code === "ENOENT") return null;
|
|
31
|
-
throw error;
|
|
32
|
-
});
|
|
33
|
-
if (!rootStats?.isDirectory() || rootStats.isSymbolicLink()) {
|
|
34
|
-
throw new Error("upgrade inventory root must be a real directory");
|
|
35
|
-
}
|
|
36
|
-
const realRoot = await realpath(rootPath);
|
|
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);
|
|
37
39
|
const entries = new Map();
|
|
38
40
|
const blockers = [];
|
|
39
|
-
|
|
40
|
-
const addBlocker = (relative, reason) => {
|
|
41
|
-
const key = `${relative}\0${reason}`;
|
|
42
|
-
if (!blockers.some((item) => `${item.path}\0${item.reason}` === key)) blockers.push({ path: relative, reason });
|
|
43
|
-
};
|
|
44
|
-
|
|
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
|
+
|
|
45
47
|
async function addFile(relative, classification, reachability = null) {
|
|
46
|
-
const normalized = normalizeProjectRelative(relative);
|
|
47
|
-
if (!normalized) {
|
|
48
|
-
addBlocker(String(relative), "reference escapes the selected project root");
|
|
49
|
-
return null;
|
|
50
|
-
}
|
|
51
|
-
const absolute = path.resolve(rootPath, normalized);
|
|
52
|
-
if (!isInside(rootPath, absolute)) {
|
|
53
|
-
addBlocker(normalized, "reference escapes the selected project root");
|
|
54
|
-
return null;
|
|
55
|
-
}
|
|
56
|
-
const stats = await lstat(absolute).catch((error) => {
|
|
57
|
-
if (error?.code === "ENOENT") return null;
|
|
58
|
-
throw error;
|
|
59
|
-
});
|
|
60
|
-
if (!stats) return null;
|
|
61
|
-
if (stats.isSymbolicLink()) {
|
|
62
|
-
addBlocker(normalized, "symbolic links and junctions are not accepted as inventory sources");
|
|
63
|
-
return null;
|
|
64
|
-
}
|
|
65
|
-
if (!stats.isFile()) {
|
|
66
|
-
addBlocker(normalized, "inventory source is not a regular file");
|
|
67
|
-
return null;
|
|
68
|
-
}
|
|
69
|
-
const resolved = await realpath(absolute);
|
|
70
|
-
if (!isInside(realRoot, resolved)) {
|
|
71
|
-
addBlocker(normalized, "resolved inventory source is outside the selected project root");
|
|
72
|
-
return null;
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
const buffer = await readFile(absolute);
|
|
76
|
-
let entry = entries.get(normalized);
|
|
77
|
-
if (!entry) {
|
|
78
|
-
entry = {
|
|
79
|
-
path: normalized,
|
|
80
|
-
sha256: sha256(buffer),
|
|
81
|
-
bytes: buffer.length,
|
|
82
|
-
classifications: new Set(),
|
|
83
|
-
reachability: new Map(),
|
|
84
|
-
text: decodeUtf8(buffer)
|
|
85
|
-
};
|
|
86
|
-
entries.set(normalized, entry);
|
|
87
|
-
}
|
|
88
|
-
entry.classifications.add(classification);
|
|
89
|
-
if (reachability) entry.reachability.set(`${reachability.from}\0${reachability.via}`, reachability);
|
|
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);
|
|
90
92
|
return entry;
|
|
91
93
|
}
|
|
92
|
-
|
|
93
|
-
for (const contract of contracts) {
|
|
94
|
-
const isFormalEntry = formalEntryTargets.includes(contract.targetRel);
|
|
95
|
-
await addFile(
|
|
94
|
+
|
|
95
|
+
for (const contract of contracts) {
|
|
96
|
+
const isFormalEntry = formalEntryTargets.includes(contract.targetRel);
|
|
97
|
+
await addFile(
|
|
96
98
|
contract.targetRel,
|
|
97
99
|
"managed-contract",
|
|
98
100
|
isFormalEntry ? { from: "formal-entry", via: contract.targetRel } : { from: "managed-contract", via: contract.targetRel }
|
|
@@ -115,54 +117,54 @@ export async function buildUpgradeInventory({ root, contracts = installedFileCon
|
|
|
115
117
|
addBlocker("dev/USER_RULES.md", `formal user-rules state is unsafe: ${String(error?.message ?? error)}`);
|
|
116
118
|
}
|
|
117
119
|
}
|
|
118
|
-
|
|
119
|
-
const frozenEntries = [...entries.values()]
|
|
120
|
-
.map((entry) => ({
|
|
121
|
-
path: entry.path,
|
|
122
|
-
sha256: entry.sha256,
|
|
123
|
-
bytes: entry.bytes,
|
|
124
|
-
classifications: [...entry.classifications].sort(),
|
|
125
|
-
reachability: [...entry.reachability.values()]
|
|
126
|
-
.sort((left, right) => `${left.from}\0${left.via}`.localeCompare(`${right.from}\0${right.via}`))
|
|
127
|
-
}))
|
|
128
|
-
.sort((left, right) => left.path.localeCompare(right.path));
|
|
129
|
-
const sortedBlockers = blockers.sort((left, right) => `${left.path}\0${left.reason}`.localeCompare(`${right.path}\0${right.reason}`));
|
|
130
|
-
const digestInput = {
|
|
131
|
-
schemaVersion: UPGRADE_INVENTORY_SCHEMA,
|
|
132
|
-
entries: frozenEntries,
|
|
133
|
-
blockers: sortedBlockers
|
|
134
|
-
};
|
|
135
|
-
|
|
136
|
-
return Object.freeze({
|
|
137
|
-
schemaVersion: UPGRADE_INVENTORY_SCHEMA,
|
|
138
|
-
status: sortedBlockers.length === 0 ? "ready" : "blocked",
|
|
139
|
-
entries: frozenEntries,
|
|
140
|
-
blockers: sortedBlockers,
|
|
141
|
-
inventorySha256: sha256(Buffer.from(`${JSON.stringify(digestInput)}\n`, "utf8")),
|
|
142
|
-
formalEntryTargets: formalEntryTargets.filter((target) => entries.has(target))
|
|
143
|
-
});
|
|
144
|
-
|
|
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
|
+
|
|
145
147
|
async function addTree(relativeDirectory, classification) {
|
|
146
|
-
const normalized = normalizeProjectRelative(relativeDirectory);
|
|
147
|
-
if (!normalized) {
|
|
148
|
+
const normalized = normalizeProjectRelative(relativeDirectory);
|
|
149
|
+
if (!normalized) {
|
|
148
150
|
addBlocker(String(relativeDirectory), "dynamic directory escapes the selected project root");
|
|
149
151
|
return;
|
|
150
152
|
}
|
|
151
153
|
const absolute = path.resolve(rootPath, normalized);
|
|
152
154
|
const stats = await lstat(absolute).catch((error) => {
|
|
153
155
|
if (error?.code === "ENOENT") return null;
|
|
154
|
-
throw error;
|
|
155
|
-
});
|
|
156
|
-
if (!stats) return;
|
|
157
|
-
if (!stats.isDirectory() || stats.isSymbolicLink()) {
|
|
158
|
-
addBlocker(normalized, "dynamic inventory directory is not a safe real directory");
|
|
159
|
-
return;
|
|
160
|
-
}
|
|
161
|
-
const resolved = await realpath(absolute);
|
|
162
|
-
if (!isInside(realRoot, resolved)) {
|
|
163
|
-
addBlocker(normalized, "dynamic inventory directory resolves outside the selected project root");
|
|
164
|
-
return;
|
|
165
|
-
}
|
|
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
|
+
}
|
|
166
168
|
for (const item of await readdir(absolute, { withFileTypes: true })) {
|
|
167
169
|
const child = `${normalized}/${item.name}`;
|
|
168
170
|
const childAbsolute = path.join(absolute, item.name);
|
|
@@ -193,171 +195,49 @@ export async function readProjectIndexTemplateVersion(root) {
|
|
|
193
195
|
return parseProjectIndexTemplateVersion(bytes.toString("utf8"));
|
|
194
196
|
}
|
|
195
197
|
|
|
196
|
-
export function
|
|
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}`));
|
|
198
212
|
}
|
|
199
213
|
|
|
200
|
-
|
|
201
|
-
|
|
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);
|
|
202
220
|
}
|
|
203
221
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
return String(text).slice(0, evidence.rowStart)
|
|
209
|
-
+ evidence.row.replace(`| ${evidence.version} |`, `| ${version} |`)
|
|
210
|
-
+ String(text).slice(evidence.rowEnd);
|
|
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;
|
|
211
226
|
}
|
|
212
227
|
|
|
213
|
-
function
|
|
214
|
-
const
|
|
215
|
-
|
|
216
|
-
const visibleLines = markdownVisibleLinesOutsideHiddenBlocks(value);
|
|
217
|
-
const headings = [];
|
|
218
|
-
for (const item of visibleLines) if (/^## [^\r\n]+$/u.test(item.text)) headings.push({ title: item.text.trim(), line: item.line, offset: item.normalizedStart });
|
|
219
|
-
const stackHeadings = headings.filter((heading) => heading.title === "## Stack");
|
|
220
|
-
if (stackHeadings.length !== 1) return null;
|
|
221
|
-
const stack = stackHeadings[0];
|
|
222
|
-
const nextHeading = headings.find((heading) => heading.line > stack.line);
|
|
223
|
-
const stackStart = stack.offset + visibleLines.find((line) => line.line === stack.line)?.text.length + 1;
|
|
224
|
-
const stackEnd = nextHeading ? nextHeading.offset : normalized.length;
|
|
225
|
-
const stackLines = visibleLines.filter((line) => line.normalizedStart >= stackStart && line.normalizedStart < stackEnd);
|
|
226
|
-
const candidateRows = [];
|
|
227
|
-
const rowPattern = /^\| Agent Handoff Kit template version \| ([^|\n]+) \| [^|\n]+ \|$/u;
|
|
228
|
-
for (const line of stackLines) {
|
|
229
|
-
const match = rowPattern.exec(line.text);
|
|
230
|
-
if (!match) continue;
|
|
231
|
-
const version = match[1].trim();
|
|
232
|
-
if (!isStableSemver(version)) return null;
|
|
233
|
-
candidateRows.push({
|
|
234
|
-
version,
|
|
235
|
-
row: line.text,
|
|
236
|
-
rowStart: line.start,
|
|
237
|
-
rowEnd: line.end
|
|
238
|
-
});
|
|
239
|
-
}
|
|
240
|
-
const versionLabelRows = stackLines.filter((line) => line.text.startsWith("| Agent Handoff Kit template version |"));
|
|
241
|
-
if (versionLabelRows.length !== candidateRows.length || candidateRows.length !== 1) return null;
|
|
242
|
-
const [row] = candidateRows;
|
|
243
|
-
return { version: row.version, row: row.row, rowStart: row.rowStart, rowEnd: row.rowEnd };
|
|
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);
|
|
244
231
|
}
|
|
245
232
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
let offset = 0;
|
|
252
|
-
let fence = null;
|
|
253
|
-
let inComment = false;
|
|
254
|
-
for (let index = 0; index < lines.length; index += 1) {
|
|
255
|
-
const line = lines[index];
|
|
256
|
-
if (inComment) {
|
|
257
|
-
if (line.includes("-->")) inComment = false;
|
|
258
|
-
offset += line.length + 1;
|
|
259
|
-
continue;
|
|
260
|
-
}
|
|
261
|
-
const fenceMatch = /^\s{0,3}(`{3,}|~{3,})(?![`~])(.*)$/u.exec(line);
|
|
262
|
-
const fenceRun = fenceMatch?.[1] ?? null;
|
|
263
|
-
if (fence) {
|
|
264
|
-
if (
|
|
265
|
-
fenceRun
|
|
266
|
-
&& fenceRun[0] === fence.char
|
|
267
|
-
&& fenceRun.length >= fence.length
|
|
268
|
-
&& /^\s*$/u.test(fenceMatch?.[2] ?? "")
|
|
269
|
-
) {
|
|
270
|
-
fence = null;
|
|
271
|
-
}
|
|
272
|
-
offset += line.length + 1;
|
|
273
|
-
continue;
|
|
274
|
-
}
|
|
275
|
-
if (fenceRun) {
|
|
276
|
-
fence = { char: fenceRun[0], length: fenceRun.length };
|
|
277
|
-
offset += line.length + 1;
|
|
278
|
-
continue;
|
|
279
|
-
}
|
|
280
|
-
const commentStart = line.indexOf("<!--");
|
|
281
|
-
if (commentStart >= 0) {
|
|
282
|
-
if (line.indexOf("-->", commentStart + 4) < 0) inComment = true;
|
|
283
|
-
offset += line.length + 1;
|
|
284
|
-
continue;
|
|
285
|
-
}
|
|
286
|
-
result.push({
|
|
287
|
-
text: line,
|
|
288
|
-
line: index,
|
|
289
|
-
normalizedStart: offset,
|
|
290
|
-
normalizedEnd: offset + line.length,
|
|
291
|
-
start: originalOffsetForNormalizedOffset(value, offset),
|
|
292
|
-
end: originalOffsetForNormalizedOffset(value, offset + line.length)
|
|
293
|
-
});
|
|
294
|
-
offset += line.length + 1;
|
|
233
|
+
function decodeUtf8(buffer) {
|
|
234
|
+
try {
|
|
235
|
+
return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
|
|
236
|
+
} catch {
|
|
237
|
+
return null;
|
|
295
238
|
}
|
|
296
|
-
return result;
|
|
297
239
|
}
|
|
298
240
|
|
|
299
|
-
function
|
|
300
|
-
|
|
301
|
-
let normalized = 0;
|
|
302
|
-
while (original < text.length && normalized < normalizedOffset) {
|
|
303
|
-
if (text[original] === "\r" && text[original + 1] === "\n") {
|
|
304
|
-
original += 2;
|
|
305
|
-
normalized += 1;
|
|
306
|
-
} else {
|
|
307
|
-
original += 1;
|
|
308
|
-
normalized += 1;
|
|
309
|
-
}
|
|
310
|
-
}
|
|
311
|
-
return original;
|
|
312
|
-
}
|
|
313
|
-
|
|
314
|
-
function isStableSemver(value) {
|
|
315
|
-
return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.test(String(value));
|
|
241
|
+
function sha256(value) {
|
|
242
|
+
return createHash("sha256").update(value).digest("hex");
|
|
316
243
|
}
|
|
317
|
-
|
|
318
|
-
export function extractExplicitLocalReferences(text) {
|
|
319
|
-
const matches = new Map();
|
|
320
|
-
const add = (raw, via) => {
|
|
321
|
-
const normalized = normalizeReference(raw);
|
|
322
|
-
if (normalized) matches.set(`${normalized}\0${via}`, { path: normalized, via });
|
|
323
|
-
};
|
|
324
|
-
for (const match of String(text).matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+[^)]*)?\)/g)) add(match[1], "markdown-link");
|
|
325
|
-
for (const match of String(text).matchAll(/`([^`\r\n]+)`/g)) add(match[1], "inline-code-path");
|
|
326
|
-
for (const match of String(text).matchAll(/^\s*@([^\s]+)\s*$/gm)) add(match[1], "bridge-import");
|
|
327
|
-
// Do not treat the dot before a filename extension as sentence punctuation.
|
|
328
|
-
// On Windows, the truncated `dev/USER_RULES` then aliases the real
|
|
329
|
-
// `dev/user_rules/` directory, making a valid formal router look unsafe.
|
|
330
|
-
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");
|
|
331
|
-
return [...matches.values()].sort((left, right) => `${left.path}\0${left.via}`.localeCompare(`${right.path}\0${right.via}`));
|
|
332
|
-
}
|
|
333
|
-
|
|
334
|
-
function normalizeReference(raw) {
|
|
335
|
-
const value = String(raw).trim().replace(/^<|>$/g, "");
|
|
336
|
-
if (!value || value.includes("://") || value.startsWith("~") || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith("/")) return null;
|
|
337
|
-
const withoutFragment = value.split(/[?#]/, 1)[0].replaceAll("\\", "/");
|
|
338
|
-
if (!withoutFragment || withoutFragment.endsWith("/") || (!withoutFragment.includes("/") && !/\.[\p{L}\p{N}]+$/u.test(withoutFragment))) return null;
|
|
339
|
-
return normalizeProjectRelative(withoutFragment);
|
|
340
|
-
}
|
|
341
|
-
|
|
342
|
-
function normalizeProjectRelative(relative) {
|
|
343
|
-
const normalized = path.posix.normalize(String(relative).replaceAll("\\", "/").replace(/^\.\//, ""));
|
|
344
|
-
if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) return null;
|
|
345
|
-
return normalized;
|
|
346
|
-
}
|
|
347
|
-
|
|
348
|
-
function isInside(root, target) {
|
|
349
|
-
const relative = path.relative(path.resolve(root), path.resolve(target));
|
|
350
|
-
return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
|
|
351
|
-
}
|
|
352
|
-
|
|
353
|
-
function decodeUtf8(buffer) {
|
|
354
|
-
try {
|
|
355
|
-
return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
|
|
356
|
-
} catch {
|
|
357
|
-
return null;
|
|
358
|
-
}
|
|
359
|
-
}
|
|
360
|
-
|
|
361
|
-
function sha256(value) {
|
|
362
|
-
return createHash("sha256").update(value).digest("hex");
|
|
363
|
-
}
|
package/docs/commands.md
CHANGED
|
@@ -1,59 +1,61 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
|
10
|
-
|
|
11
|
-
|
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
1
|
+
# Agent Handoff Kit 常用指令
|
|
2
|
+
|
|
3
|
+
[English](#shortcuts)
|
|
4
|
+
|
|
5
|
+
這份說明包含尚未發布的更新;正式下載可用的功能,以已發布版本為準。
|
|
6
|
+
|
|
7
|
+
在專案的 AI 對話輸入指令,不是在終端機。Claude Code、Gemini CLI、Antigravity CLI 用 /;Codex 用 $,也可從 /skills 選取。 例如 Codex 用 `$handoff-kit-start`。
|
|
8
|
+
|
|
9
|
+
| 想做甚麼 | 指令 |
|
|
10
|
+
|---|---|
|
|
11
|
+
| 接回上次工作 | [`/handoff-kit-start`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#start) |
|
|
12
|
+
| 看專案全貌 | [`/handoff-kit-progress`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#progress) |
|
|
13
|
+
| 準備結束這次對話 | [`/handoff-kit-close`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#close) |
|
|
14
|
+
| 第一次用,想有人帶路 | [`/handoff-kit-onboard`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#onboard) |
|
|
15
|
+
| 忘了用哪個指令 | [`/handoff-kit-help`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#help) |
|
|
16
|
+
| 讓下次 AI 找得到重要文件 | [`/handoff-kit-align`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#align) |
|
|
17
|
+
| 希望以後都照這樣做 | [`/handoff-kit-remember`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#remember) |
|
|
18
|
+
| 交接功能出了問題 | [`/handoff-kit-check`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#check) |
|
|
19
|
+
| 想用最新正式版 | [`/handoff-kit-update`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#update) |
|
|
20
|
+
|
|
21
|
+
日常用開工、進度頁、收工;其他按需要用。每個指令的例子與注意事項都在[使用指南](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html),不用另外讀一套教學。
|
|
22
|
+
|
|
23
|
+
### 安裝與選單
|
|
24
|
+
|
|
25
|
+
安裝或升級時,指令入口會一併放好,只供目前專案使用,不安裝到電腦的共用設定。不用額外啟用。舊對話未顯示時,重新開啟專案對話;Gemini CLI 可用 `/commands reload`。Codex 選單有簡短中英文說明,例如「開工 / Start」。
|
|
26
|
+
|
|
27
|
+
如果入口缺漏,把[安裝頁](../agent-handoff-kit-ai-install.html)的句子交給 AI。同版本也可補齊缺項;你的自訂內容遇到衝突會保留並停止,不會強行覆寫。檔案齊備只證明安裝結果,實際選單和呼叫仍須在所用工具確認。
|
|
28
|
+
|
|
29
|
+
### 使用成本
|
|
30
|
+
|
|
31
|
+
叫 AI 執行指令及平常保存紀錄會使用一些 token。進度頁開啟後,查看、篩選和自動更新由本機程式處理,不再叫 AI 寫報告。[進度頁說明](progress.md)包含重開、斷線和資料不完整時的處理。
|
|
32
|
+
|
|
33
|
+
## Shortcuts
|
|
34
|
+
|
|
35
|
+
This guide includes updates that have not been released yet. Features available to download depend on the published version.
|
|
36
|
+
|
|
37
|
+
Enter shortcuts in your project’s AI conversation, not in the terminal. Claude Code, Gemini CLI and Antigravity CLI use /; Codex uses $, or selection through /skills. For example, Codex uses `$handoff-kit-start`.
|
|
38
|
+
|
|
39
|
+
| What you want to do | Shortcut |
|
|
40
|
+
|---|---|
|
|
41
|
+
| Pick up where you left off | [`/handoff-kit-start`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#start) |
|
|
42
|
+
| See the whole project | [`/handoff-kit-progress`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#progress) |
|
|
43
|
+
| Finish this conversation | [`/handoff-kit-close`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#close) |
|
|
44
|
+
| Get help getting started | [`/handoff-kit-onboard`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#onboard) |
|
|
45
|
+
| Find the right shortcut | [`/handoff-kit-help`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#help) |
|
|
46
|
+
| Help the next AI find an important file | [`/handoff-kit-align`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#align) |
|
|
47
|
+
| Keep a working preference for next time | [`/handoff-kit-remember`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#remember) |
|
|
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
|
+
| Get the latest released version | [`/handoff-kit-update`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#update) |
|
|
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.
|
|
52
|
+
|
|
53
|
+
### Installation and menus
|
|
54
|
+
|
|
55
|
+
Installation and upgrades include the shortcuts for this project only, not shared computer-wide settings. No separate activation is needed. If an older conversation does not show them, reopen the project conversation; Gemini CLI can use `/commands reload`. Codex has short bilingual labels such as “開工 / Start”.
|
|
56
|
+
|
|
57
|
+
For missing entries, give the AI the sentence on the [setup page](../agent-handoff-kit-ai-install.en.html). Reapplying the same version can fill missing files. Conflicting custom content is kept and the operation stops, without forced overwrites. Complete files prove installation only; check menus and invocation in the tool you use.
|
|
58
|
+
|
|
59
|
+
### Usage cost
|
|
60
|
+
|
|
61
|
+
Asking the AI to run a shortcut and saving normal records use some tokens. Once the dashboard is open, viewing, filtering and automatic updates run locally without asking the AI to write another report. [Dashboard help](progress.md) covers reopening, disconnections and incomplete data.
|