@installagent/sdk 0.10.0 → 0.11.0
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/dist/agent-templates.js +1 -1
- package/dist/client-drift.d.ts +6 -0
- package/dist/client-drift.js +30 -28
- package/dist/index.d.ts +4 -2
- package/dist/index.js +4 -2
- package/dist/roadmap-migrate.d.ts +75 -0
- package/dist/roadmap-migrate.js +328 -0
- package/dist/roadmap-retire.d.ts +61 -0
- package/dist/roadmap-retire.js +416 -0
- package/dist/template-sync.d.ts +38 -11
- package/dist/template-sync.js +88 -21
- package/package.json +1 -1
- package/templates/workspace-root/skills/client-latest/SKILL.md +1 -1
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +47 -21
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +40 -17
- package/templates/workspace-root/skills/ia-cli/SKILL.md +1 -0
- package/templates/workspace-root/skills/linear/SKILL.md +32 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +7 -3
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { type ExecFileFn } from "./exec.js";
|
|
2
|
+
export declare const ROADMAP_FILE = "docs/06-roadmap.md";
|
|
3
|
+
export declare const ROADMAP_ARCHIVE = "docs/archive/06-roadmap.md";
|
|
4
|
+
export interface OnboardingChange {
|
|
5
|
+
label: string;
|
|
6
|
+
/** 1-based lines of the original page. */
|
|
7
|
+
startLine: number;
|
|
8
|
+
endLine: number;
|
|
9
|
+
removed: string[];
|
|
10
|
+
added: string[];
|
|
11
|
+
}
|
|
12
|
+
export interface OnboardingRetirePlan {
|
|
13
|
+
html: string;
|
|
14
|
+
changes: OnboardingChange[];
|
|
15
|
+
/** Lines of the original page with another link to #roadmap (hand content: listed, not edited). */
|
|
16
|
+
otherLinks: number[];
|
|
17
|
+
/**
|
|
18
|
+
* h2/h3 headings in the Roadmap section that the template never had: hand
|
|
19
|
+
* content (history, "read before you touch X" notes). `roadmapRetire --apply`
|
|
20
|
+
* refuses the repo until the owner moves what is still true.
|
|
21
|
+
*/
|
|
22
|
+
handHeadings: string[];
|
|
23
|
+
}
|
|
24
|
+
/** What retiring the roadmap removes from one onboarding.html. Pure: reads nothing, writes nothing. */
|
|
25
|
+
export declare function planOnboardingRetire(html: string): OnboardingRetirePlan;
|
|
26
|
+
export interface RoadmapRetireClient {
|
|
27
|
+
slug: string;
|
|
28
|
+
dir: string;
|
|
29
|
+
/** The planned `git mv`, or null when the repo has no docs/06-roadmap.md. */
|
|
30
|
+
move: {
|
|
31
|
+
from: string;
|
|
32
|
+
to: string;
|
|
33
|
+
} | null;
|
|
34
|
+
changes: OnboardingChange[];
|
|
35
|
+
/** Hand-kept lines that still point at the roadmap, for the owner to fix. */
|
|
36
|
+
handFix: string[];
|
|
37
|
+
/** Set when nothing was planned for this repo, with the reason. */
|
|
38
|
+
skipped: string | null;
|
|
39
|
+
/** apply only: why this repo was not changed. */
|
|
40
|
+
refused: string | null;
|
|
41
|
+
applied: boolean;
|
|
42
|
+
}
|
|
43
|
+
export interface RoadmapRetireResult {
|
|
44
|
+
workspaceDir: string;
|
|
45
|
+
clients: RoadmapRetireClient[];
|
|
46
|
+
/** --all only: the ad hoc repos left out (they keep their roadmap). */
|
|
47
|
+
adhocSkipped: string[];
|
|
48
|
+
applied: boolean;
|
|
49
|
+
notes: string[];
|
|
50
|
+
}
|
|
51
|
+
export interface RoadmapRetireOptions {
|
|
52
|
+
workspaceDir?: string;
|
|
53
|
+
slug?: string;
|
|
54
|
+
all?: boolean;
|
|
55
|
+
/** git mv + write onboarding.html. Default false: report only. */
|
|
56
|
+
apply?: boolean;
|
|
57
|
+
/** git status / git mv. Injectable for tests. */
|
|
58
|
+
execFileImpl?: ExecFileFn;
|
|
59
|
+
}
|
|
60
|
+
/** Plan (and, with `apply`, do) the one-time roadmap cleanup in one client repo or every one. */
|
|
61
|
+
export declare function roadmapRetire(options: RoadmapRetireOptions): Promise<RoadmapRetireResult>;
|
|
@@ -0,0 +1,416 @@
|
|
|
1
|
+
// `ia roadmap-retire` — the one-time cleanup of docs/06-roadmap.md in a client repo.
|
|
2
|
+
//
|
|
3
|
+
// The roadmap file is retired (2026-11-08): Linear owns the order of work.
|
|
4
|
+
// Run `ia roadmap-migrate --apply` first, so Linear holds what the file held.
|
|
5
|
+
// Then this operation, per client repo:
|
|
6
|
+
//
|
|
7
|
+
// - `git mv docs/06-roadmap.md docs/archive/06-roadmap.md` (history kept);
|
|
8
|
+
// - removes from onboarding.html: the Roadmap sidebar link, the
|
|
9
|
+
// `<section id="roadmap">` (with its banner comment), the client roadmap in
|
|
10
|
+
// Public (the wrapper section when it holds only the heading and the
|
|
11
|
+
// generated ROADMAP_CLIENT block, else the block alone), "roadmap" from
|
|
12
|
+
// the page script's SECTIONS list (a section id that is gone breaks the
|
|
13
|
+
// page's navigation), the ROADMAP entry of the header comment (and one
|
|
14
|
+
// from its section count), and the roadmap CSS (`.rm-asof` stays, under the
|
|
15
|
+
// template's comment; the CSS stays while a page class still uses it).
|
|
16
|
+
//
|
|
17
|
+
// A repo retired by an older `ia` (the roadmap already archived) gets only
|
|
18
|
+
// these page leftovers removed.
|
|
19
|
+
//
|
|
20
|
+
// Hand-kept content is never edited: other links to #roadmap and pointers to
|
|
21
|
+
// docs/06-roadmap.md in CLAUDE.md / AGENT.md / README.md are listed for the
|
|
22
|
+
// owner to fix in their own slice. The dry run (the default) writes nothing.
|
|
23
|
+
// `apply` refuses a repo whose onboarding.html or roadmap has uncommitted
|
|
24
|
+
// changes (another session may be working there) and never overwrites an
|
|
25
|
+
// archived roadmap. It never commits.
|
|
26
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
27
|
+
import { mkdir, writeFile } from "node:fs/promises";
|
|
28
|
+
import { join, resolve } from "node:path";
|
|
29
|
+
import { execFileAsync } from "./exec.js";
|
|
30
|
+
import { adhocReason, selectClientSlugs } from "./template-sync.js";
|
|
31
|
+
export const ROADMAP_FILE = "docs/06-roadmap.md";
|
|
32
|
+
export const ROADMAP_ARCHIVE = "docs/archive/06-roadmap.md";
|
|
33
|
+
const POINTER_FILES = ["CLAUDE.md", "AGENT.md", "README.md"];
|
|
34
|
+
const SECTION_TAG = /<section\b[^>]*>|<\/section>/g;
|
|
35
|
+
// The headings client-template's Roadmap section carried; anything else is hand content.
|
|
36
|
+
const TEMPLATE_HEADINGS = new Set([
|
|
37
|
+
"The order of work, and why",
|
|
38
|
+
"Ranked list",
|
|
39
|
+
"Keeping it true",
|
|
40
|
+
"The fine line",
|
|
41
|
+
]);
|
|
42
|
+
const headingText = (raw) => raw
|
|
43
|
+
.replace(/<[^>]+>/g, "")
|
|
44
|
+
.replace(/&/g, "&")
|
|
45
|
+
.replace(/</g, "<")
|
|
46
|
+
.replace(/>/g, ">")
|
|
47
|
+
.replace(/\s+/g, " ")
|
|
48
|
+
.trim();
|
|
49
|
+
const ROADMAP_LINK = /<a\b[^>]*\bhref=["']#roadmap["'][^>]*>[\s\S]*?<\/a>/;
|
|
50
|
+
/** End offset of the `<section>` that opens at `start` (balanced), or null. */
|
|
51
|
+
function sectionEnd(html, start) {
|
|
52
|
+
const tags = new RegExp(SECTION_TAG.source, "g");
|
|
53
|
+
tags.lastIndex = start;
|
|
54
|
+
let depth = 0;
|
|
55
|
+
for (let m = tags.exec(html); m; m = tags.exec(html)) {
|
|
56
|
+
depth += m[0].startsWith("</") ? -1 : 1;
|
|
57
|
+
if (depth === 0)
|
|
58
|
+
return m.index + m[0].length;
|
|
59
|
+
}
|
|
60
|
+
return null;
|
|
61
|
+
}
|
|
62
|
+
const lineStart = (html, at) => html.lastIndexOf("\n", at - 1) + 1;
|
|
63
|
+
/** Widen [start, end) to whole lines when only whitespace sits beside it, and eat one blank line after. */
|
|
64
|
+
function wholeLines(html, start, end) {
|
|
65
|
+
const from = lineStart(html, start);
|
|
66
|
+
const s = html.slice(from, start).trim() === "" ? from : start;
|
|
67
|
+
const lineEnd = html.indexOf("\n", end);
|
|
68
|
+
const stop = lineEnd === -1 ? html.length : lineEnd;
|
|
69
|
+
if (html.slice(end, stop).trim() !== "")
|
|
70
|
+
return [s, end];
|
|
71
|
+
let e = lineEnd === -1 ? html.length : lineEnd + 1;
|
|
72
|
+
if (s === from && html[e] === "\n" && (s === 0 || html[s - 1] === "\n") && html[s - 2] === "\n")
|
|
73
|
+
e += 1;
|
|
74
|
+
return [s, e];
|
|
75
|
+
}
|
|
76
|
+
/** The innermost `<section>` that holds [from, to), or null. */
|
|
77
|
+
function enclosingSection(html, from, to) {
|
|
78
|
+
let best = null;
|
|
79
|
+
for (const m of html.slice(0, from).matchAll(/<section\b[^>]*>/g)) {
|
|
80
|
+
const end = sectionEnd(html, m.index ?? 0);
|
|
81
|
+
if (end !== null && end >= to)
|
|
82
|
+
best = { start: m.index ?? 0, end, open: m[0] };
|
|
83
|
+
}
|
|
84
|
+
return best;
|
|
85
|
+
}
|
|
86
|
+
/** True when a section holds nothing but its sec-head, comments and the given block. */
|
|
87
|
+
function onlyHeadAndBlock(section, open, block) {
|
|
88
|
+
let inner = section.slice(open.length, -"</section>".length).replace(block, "");
|
|
89
|
+
inner = inner.replace(/<!--[\s\S]*?-->/g, "");
|
|
90
|
+
const head = /<div class="sec-head">/.exec(inner);
|
|
91
|
+
if (head) {
|
|
92
|
+
let depth = 0;
|
|
93
|
+
const tags = /<div\b[^>]*>|<\/div>/g;
|
|
94
|
+
tags.lastIndex = head.index;
|
|
95
|
+
for (let m = tags.exec(inner); m; m = tags.exec(inner)) {
|
|
96
|
+
depth += m[0].startsWith("</") ? -1 : 1;
|
|
97
|
+
if (depth === 0) {
|
|
98
|
+
inner = inner.slice(0, head.index) + inner.slice(m.index + m[0].length);
|
|
99
|
+
break;
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
return inner.trim() === "";
|
|
104
|
+
}
|
|
105
|
+
const COUNT_WORDS = [
|
|
106
|
+
"zero",
|
|
107
|
+
"one",
|
|
108
|
+
"two",
|
|
109
|
+
"three",
|
|
110
|
+
"four",
|
|
111
|
+
"five",
|
|
112
|
+
"six",
|
|
113
|
+
"seven",
|
|
114
|
+
"eight",
|
|
115
|
+
"nine",
|
|
116
|
+
"ten",
|
|
117
|
+
"eleven",
|
|
118
|
+
"twelve",
|
|
119
|
+
];
|
|
120
|
+
/**
|
|
121
|
+
* The page's header comment lists its sidebar sections; its ROADMAP entry (the
|
|
122
|
+
* label line and its deeper-indented lines) names the retired file. The entry
|
|
123
|
+
* goes, and "nine sections" in the same comment becomes "eight sections".
|
|
124
|
+
*/
|
|
125
|
+
function headerEntryCuts(html) {
|
|
126
|
+
for (const comment of html.matchAll(/<!--[\s\S]*?-->/g)) {
|
|
127
|
+
const text = comment[0];
|
|
128
|
+
const entry = /^( +)ROADMAP {2,}\S.*$/m.exec(text);
|
|
129
|
+
if (!entry)
|
|
130
|
+
continue;
|
|
131
|
+
const base = comment.index ?? 0;
|
|
132
|
+
const start = base + entry.index;
|
|
133
|
+
let end = start + entry[0].length + 1;
|
|
134
|
+
while (end < base + text.length) {
|
|
135
|
+
const stop = html.indexOf("\n", end);
|
|
136
|
+
const line = html.slice(end, stop === -1 ? html.length : stop);
|
|
137
|
+
if (!line.startsWith(`${entry[1]} `) || line.trim() === "" || line.trim() === "-->")
|
|
138
|
+
break;
|
|
139
|
+
end = stop === -1 ? html.length : stop + 1;
|
|
140
|
+
}
|
|
141
|
+
const cuts = [{ label: "header comment: ROADMAP entry", start, end, replacement: "" }];
|
|
142
|
+
const count = new RegExp(`\\b(${COUNT_WORDS.join("|")}) sections\\b`).exec(text.slice(0, entry.index));
|
|
143
|
+
const n = count ? COUNT_WORDS.indexOf(count[1]) : 0;
|
|
144
|
+
if (count && n > 1) {
|
|
145
|
+
const at = base + count.index;
|
|
146
|
+
cuts.push({
|
|
147
|
+
label: "header comment: section count",
|
|
148
|
+
start: at,
|
|
149
|
+
end: at + count[1].length,
|
|
150
|
+
replacement: COUNT_WORDS[n - 1],
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
return cuts;
|
|
154
|
+
}
|
|
155
|
+
return [];
|
|
156
|
+
}
|
|
157
|
+
// The roadmap view's CSS. `.rm-asof` stays: ci/onboarding.mjs writes it in the
|
|
158
|
+
// Status snapshot, and the template keeps it under its own comment.
|
|
159
|
+
const ROADMAP_CSS_COMMENT = /^[ \t]*\/\*[^*]*Roadmap: the ranked list[\s\S]*?\*\/[ \t]*\n/m;
|
|
160
|
+
const ROADMAP_CSS_RULE = /^[ \t]*(?:ol\.roadmap\b|\.rm-(?:row|rank|body|head|why|tag|status|phase|empty)\b)/;
|
|
161
|
+
const AS_OF_RULE = /^[ \t]*\.rm-asof\b/;
|
|
162
|
+
const ROADMAP_CLASS = /\bclass=["'][^"']*\b(?:roadmap|rm-(?:row|rank|body|head|why|tag|status|phase|empty))\b/;
|
|
163
|
+
const AS_OF_COMMENT = "/* ── The AS OF line of the generated Status snapshot (ci/onboarding.mjs) ── */";
|
|
164
|
+
/** The roadmap CSS block, unless `rest` (the page after the other cuts) still uses a roadmap class. */
|
|
165
|
+
function roadmapCssCut(html, rest) {
|
|
166
|
+
const comment = ROADMAP_CSS_COMMENT.exec(html);
|
|
167
|
+
if (!comment || ROADMAP_CLASS.test(rest))
|
|
168
|
+
return null;
|
|
169
|
+
const indent = /^[ \t]*/.exec(comment[0])?.[0] ?? "";
|
|
170
|
+
const start = comment.index;
|
|
171
|
+
let end = start + comment[0].length;
|
|
172
|
+
const kept = [];
|
|
173
|
+
while (end < html.length) {
|
|
174
|
+
const stop = html.indexOf("\n", end);
|
|
175
|
+
const line = html.slice(end, stop === -1 ? html.length : stop);
|
|
176
|
+
if (AS_OF_RULE.test(line))
|
|
177
|
+
kept.push(line);
|
|
178
|
+
else if (!ROADMAP_CSS_RULE.test(line))
|
|
179
|
+
break;
|
|
180
|
+
end = stop === -1 ? html.length : stop + 1;
|
|
181
|
+
}
|
|
182
|
+
const replacement = kept.length ? `${indent}${AS_OF_COMMENT}\n${kept.join("\n")}\n` : "";
|
|
183
|
+
// Nothing kept: also eat the blank line after, so no double blank line is left.
|
|
184
|
+
if (!replacement && html[end] === "\n" && html[start - 1] === "\n" && html[start - 2] === "\n")
|
|
185
|
+
end += 1;
|
|
186
|
+
if (html.slice(start, end) === replacement)
|
|
187
|
+
return null;
|
|
188
|
+
return { label: "roadmap CSS (the template's AS OF rule stays)", start, end, replacement };
|
|
189
|
+
}
|
|
190
|
+
function markerBlock(html, name) {
|
|
191
|
+
const start = html.indexOf(`<!-- ${name}:START -->`);
|
|
192
|
+
if (start === -1)
|
|
193
|
+
return null;
|
|
194
|
+
const endMarker = `<!-- ${name}:END -->`;
|
|
195
|
+
const end = html.indexOf(endMarker, start);
|
|
196
|
+
return end === -1 ? null : { start, end: end + endMarker.length };
|
|
197
|
+
}
|
|
198
|
+
/** What retiring the roadmap removes from one onboarding.html. Pure: reads nothing, writes nothing. */
|
|
199
|
+
export function planOnboardingRetire(html) {
|
|
200
|
+
const cuts = [];
|
|
201
|
+
const nav = /<nav\b[\s\S]*?<\/nav>/.exec(html);
|
|
202
|
+
const link = nav ? ROADMAP_LINK.exec(nav[0]) : null;
|
|
203
|
+
if (nav && link) {
|
|
204
|
+
const at = nav.index + link.index;
|
|
205
|
+
const [start, end] = wholeLines(html, at, at + link[0].length);
|
|
206
|
+
cuts.push({ label: "sidebar link", start, end, replacement: "" });
|
|
207
|
+
}
|
|
208
|
+
const section = /<section\b[^>]*\bid=["']roadmap["'][^>]*>/.exec(html);
|
|
209
|
+
const sectionStop = section ? sectionEnd(html, section.index) : null;
|
|
210
|
+
if (section && sectionStop !== null) {
|
|
211
|
+
let start = section.index;
|
|
212
|
+
const banner = /<!--[^\n]*ROADMAP[^\n]*-->\s*$/.exec(html.slice(0, start));
|
|
213
|
+
if (banner)
|
|
214
|
+
start = banner.index;
|
|
215
|
+
const [s, e] = wholeLines(html, start, sectionStop);
|
|
216
|
+
cuts.push({ label: "Roadmap section", start: s, end: e, replacement: "" });
|
|
217
|
+
}
|
|
218
|
+
const handHeadings = section && sectionStop !== null
|
|
219
|
+
? [...html.slice(section.index, sectionStop).matchAll(/<h[23]\b[^>]*>([\s\S]*?)<\/h[23]>/g)]
|
|
220
|
+
.map((m) => headingText(m[1]))
|
|
221
|
+
.filter((text) => text && !TEMPLATE_HEADINGS.has(text))
|
|
222
|
+
: [];
|
|
223
|
+
const insideRoadmap = (at) => section !== null && sectionStop !== null && at >= section.index && at < sectionStop;
|
|
224
|
+
const client = markerBlock(html, "ROADMAP_CLIENT");
|
|
225
|
+
if (client && !insideRoadmap(client.start)) {
|
|
226
|
+
const wrapper = enclosingSection(html, client.start, client.end);
|
|
227
|
+
const block = html.slice(client.start, client.end);
|
|
228
|
+
const anonymous = wrapper && !/\bid=/.test(wrapper.open);
|
|
229
|
+
if (wrapper &&
|
|
230
|
+
anonymous &&
|
|
231
|
+
onlyHeadAndBlock(html.slice(wrapper.start, wrapper.end), wrapper.open, block)) {
|
|
232
|
+
const [s, e] = wholeLines(html, wrapper.start, wrapper.end);
|
|
233
|
+
cuts.push({ label: "client roadmap section (Public)", start: s, end: e, replacement: "" });
|
|
234
|
+
}
|
|
235
|
+
else {
|
|
236
|
+
let start = client.start;
|
|
237
|
+
// The generator's note names the retired file: it goes too, next to the block or not.
|
|
238
|
+
const from = wrapper ? wrapper.start : 0;
|
|
239
|
+
const notes = [
|
|
240
|
+
...html
|
|
241
|
+
.slice(from, start)
|
|
242
|
+
.matchAll(/<!--\s*GENERATED from docs\/06-roadmap\.md[\s\S]*?-->/g),
|
|
243
|
+
];
|
|
244
|
+
const note = notes.at(-1);
|
|
245
|
+
if (note) {
|
|
246
|
+
const noteStart = from + (note.index ?? 0);
|
|
247
|
+
const noteEnd = noteStart + note[0].length;
|
|
248
|
+
if (html.slice(noteEnd, start).trim() === "")
|
|
249
|
+
start = noteStart;
|
|
250
|
+
else {
|
|
251
|
+
const [s, e] = wholeLines(html, noteStart, noteEnd);
|
|
252
|
+
cuts.push({ label: "client roadmap note (Public)", start: s, end: e, replacement: "" });
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
const [s, e] = wholeLines(html, start, client.end);
|
|
256
|
+
cuts.push({
|
|
257
|
+
label: "client roadmap block (Public; the section keeps hand content)",
|
|
258
|
+
start: s,
|
|
259
|
+
end: e,
|
|
260
|
+
replacement: "",
|
|
261
|
+
});
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
const list = markerBlock(html, "ROADMAP_LIST");
|
|
265
|
+
if (list && !insideRoadmap(list.start)) {
|
|
266
|
+
const [s, e] = wholeLines(html, list.start, list.end);
|
|
267
|
+
cuts.push({ label: "roadmap list block", start: s, end: e, replacement: "" });
|
|
268
|
+
}
|
|
269
|
+
const sections = /const SECTIONS\s*=\s*\[[^\]]*\]/.exec(html);
|
|
270
|
+
// Pages write the list with "double" or 'single' quotes ('roadmap', is valid too).
|
|
271
|
+
if (sections && /(["'])roadmap\1/.test(sections[0])) {
|
|
272
|
+
const start = lineStart(html, sections.index);
|
|
273
|
+
const stop = html.indexOf("\n", sections.index);
|
|
274
|
+
const end = stop === -1 ? html.length : stop;
|
|
275
|
+
const line = html.slice(start, end);
|
|
276
|
+
const fixed = line.replace(/,\s*(["'])roadmap\1(?=\s*[,\]])|(["'])roadmap\2\s*,\s*/, "");
|
|
277
|
+
cuts.push({ label: "SECTIONS entry (page script)", start, end, replacement: fixed });
|
|
278
|
+
}
|
|
279
|
+
cuts.push(...headerEntryCuts(html));
|
|
280
|
+
let rest = html;
|
|
281
|
+
for (const cut of [...cuts].sort((a, b) => b.start - a.start))
|
|
282
|
+
rest = rest.slice(0, cut.start) + cut.replacement + rest.slice(cut.end);
|
|
283
|
+
const css = roadmapCssCut(html, rest);
|
|
284
|
+
if (css)
|
|
285
|
+
cuts.push(css);
|
|
286
|
+
cuts.sort((a, b) => a.start - b.start);
|
|
287
|
+
const kept = cuts.filter((cut, i) => i === 0 || cut.start >= cuts[i - 1].end);
|
|
288
|
+
const lineOf = (at) => html.slice(0, at).split("\n").length;
|
|
289
|
+
const changes = kept.map((cut) => ({
|
|
290
|
+
label: cut.label,
|
|
291
|
+
startLine: lineOf(cut.start),
|
|
292
|
+
endLine: lineOf(Math.max(cut.start, cut.end - 1)),
|
|
293
|
+
removed: html.slice(cut.start, cut.end).replace(/\n$/, "").split("\n"),
|
|
294
|
+
added: cut.replacement ? cut.replacement.split("\n") : [],
|
|
295
|
+
}));
|
|
296
|
+
let next = html;
|
|
297
|
+
for (const cut of [...kept].reverse())
|
|
298
|
+
next = next.slice(0, cut.start) + cut.replacement + next.slice(cut.end);
|
|
299
|
+
const otherLinks = [];
|
|
300
|
+
for (const m of html.matchAll(new RegExp(ROADMAP_LINK.source, "g"))) {
|
|
301
|
+
const at = m.index ?? 0;
|
|
302
|
+
if (!kept.some((cut) => at >= cut.start && at < cut.end))
|
|
303
|
+
otherLinks.push(lineOf(at));
|
|
304
|
+
}
|
|
305
|
+
return { html: next, changes, otherLinks, handHeadings };
|
|
306
|
+
}
|
|
307
|
+
function handFixes(dir, otherLinks) {
|
|
308
|
+
const fixes = otherLinks.map((line) => `onboarding.html:${line} links to #roadmap`);
|
|
309
|
+
for (const file of POINTER_FILES) {
|
|
310
|
+
const path = join(dir, file);
|
|
311
|
+
if (!existsSync(path))
|
|
312
|
+
continue;
|
|
313
|
+
readFileSync(path, "utf8")
|
|
314
|
+
.split("\n")
|
|
315
|
+
.forEach((text, i) => {
|
|
316
|
+
if (text.includes("06-roadmap.md"))
|
|
317
|
+
fixes.push(`${file}:${i + 1} names ${ROADMAP_FILE}`);
|
|
318
|
+
});
|
|
319
|
+
}
|
|
320
|
+
return fixes;
|
|
321
|
+
}
|
|
322
|
+
/** Plan (and, with `apply`, do) the one-time roadmap cleanup in one client repo or every one. */
|
|
323
|
+
export async function roadmapRetire(options) {
|
|
324
|
+
const workspaceDir = resolve(options.workspaceDir ?? ".");
|
|
325
|
+
const { slugs, adhoc } = selectClientSlugs(workspaceDir, options, "roadmap-retire");
|
|
326
|
+
const exec = options.execFileImpl ?? execFileAsync;
|
|
327
|
+
const apply = options.apply ?? false;
|
|
328
|
+
const clients = [];
|
|
329
|
+
for (const slug of slugs) {
|
|
330
|
+
const dir = join(workspaceDir, "clients", `client-${slug}`);
|
|
331
|
+
const client = {
|
|
332
|
+
slug,
|
|
333
|
+
dir,
|
|
334
|
+
move: null,
|
|
335
|
+
changes: [],
|
|
336
|
+
handFix: [],
|
|
337
|
+
skipped: null,
|
|
338
|
+
refused: null,
|
|
339
|
+
applied: false,
|
|
340
|
+
};
|
|
341
|
+
clients.push(client);
|
|
342
|
+
const adhoc = adhocReason(dir);
|
|
343
|
+
if (adhoc) {
|
|
344
|
+
client.skipped = adhoc;
|
|
345
|
+
continue;
|
|
346
|
+
}
|
|
347
|
+
const pagePath = join(dir, "onboarding.html");
|
|
348
|
+
const page = existsSync(pagePath) ? readFileSync(pagePath, "utf8") : null;
|
|
349
|
+
const plan = page === null ? null : planOnboardingRetire(page);
|
|
350
|
+
if (existsSync(join(dir, ROADMAP_FILE)))
|
|
351
|
+
client.move = { from: ROADMAP_FILE, to: ROADMAP_ARCHIVE };
|
|
352
|
+
client.changes = plan?.changes ?? [];
|
|
353
|
+
client.handFix = handFixes(dir, plan?.otherLinks ?? []);
|
|
354
|
+
const hand = plan?.handHeadings ?? [];
|
|
355
|
+
if (hand.length > 0) {
|
|
356
|
+
const shown = hand
|
|
357
|
+
.slice(0, 3)
|
|
358
|
+
.map((h) => `"${h}"`)
|
|
359
|
+
.join(", ");
|
|
360
|
+
client.handFix.unshift(`onboarding.html: the Roadmap section holds hand content (${hand.length} heading(s): ${shown}${hand.length > 3 ? ", …" : ""}) — move what is still true to docs/ or Linear, then run again`);
|
|
361
|
+
}
|
|
362
|
+
if (!client.move && client.changes.length === 0) {
|
|
363
|
+
client.skipped =
|
|
364
|
+
"nothing to retire (no docs/06-roadmap.md, no roadmap markup in onboarding.html)";
|
|
365
|
+
continue;
|
|
366
|
+
}
|
|
367
|
+
if (!apply)
|
|
368
|
+
continue;
|
|
369
|
+
if (hand.length > 0) {
|
|
370
|
+
client.refused =
|
|
371
|
+
"the Roadmap section holds hand content — move it first (see the hand fixes); nothing was changed";
|
|
372
|
+
continue;
|
|
373
|
+
}
|
|
374
|
+
if (!existsSync(join(dir, ".git"))) {
|
|
375
|
+
client.refused = "not a git checkout — the move must keep the file's history";
|
|
376
|
+
continue;
|
|
377
|
+
}
|
|
378
|
+
if (client.move && existsSync(join(dir, ROADMAP_ARCHIVE))) {
|
|
379
|
+
client.refused = `${ROADMAP_ARCHIVE} already exists — compare the two by hand; nothing was changed`;
|
|
380
|
+
continue;
|
|
381
|
+
}
|
|
382
|
+
const { stdout } = await exec("git", [
|
|
383
|
+
"-C",
|
|
384
|
+
dir,
|
|
385
|
+
"status",
|
|
386
|
+
"--porcelain",
|
|
387
|
+
"--",
|
|
388
|
+
"onboarding.html",
|
|
389
|
+
ROADMAP_FILE,
|
|
390
|
+
]);
|
|
391
|
+
if (stdout.trim()) {
|
|
392
|
+
client.refused =
|
|
393
|
+
"onboarding.html or docs/06-roadmap.md has uncommitted changes (another session may be working there) — commit or stash them, then run again";
|
|
394
|
+
continue;
|
|
395
|
+
}
|
|
396
|
+
if (client.move) {
|
|
397
|
+
await mkdir(join(dir, "docs", "archive"), { recursive: true });
|
|
398
|
+
await exec("git", ["-C", dir, "mv", ROADMAP_FILE, ROADMAP_ARCHIVE]);
|
|
399
|
+
}
|
|
400
|
+
if (plan && client.changes.length > 0)
|
|
401
|
+
await writeFile(pagePath, plan.html);
|
|
402
|
+
client.applied = true;
|
|
403
|
+
}
|
|
404
|
+
return {
|
|
405
|
+
workspaceDir,
|
|
406
|
+
clients,
|
|
407
|
+
adhocSkipped: adhoc,
|
|
408
|
+
applied: apply,
|
|
409
|
+
notes: [
|
|
410
|
+
apply
|
|
411
|
+
? "Applied: git mv + onboarding.html only. Nothing was committed. Run `node ci/sync.mjs --write` in each repo (after `ia template-sync --apply`), then commit each repo as one slice."
|
|
412
|
+
: "Dry run: nothing was written. Run `ia roadmap-migrate --all --apply` before `--apply` here.",
|
|
413
|
+
"Hand fixes are listed, never edited: other #roadmap links and pointers to docs/06-roadmap.md.",
|
|
414
|
+
],
|
|
415
|
+
};
|
|
416
|
+
}
|
package/dist/template-sync.d.ts
CHANGED
|
@@ -33,17 +33,43 @@ import { type GcpManifestKey } from "./client-manifest.js";
|
|
|
33
33
|
*/
|
|
34
34
|
export declare const TEMPLATE_SYNCED_FILES: string[];
|
|
35
35
|
/**
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
* hand copy, recorded in that repo's own commit.
|
|
36
|
+
* Files the template used to sync and has since retired. A client repo that
|
|
37
|
+
* still has one is not in sync: the dry run lists it as `retired`, and
|
|
38
|
+
* `--apply` deletes it (`deleted`). Nothing else is ever deleted.
|
|
40
39
|
*
|
|
41
|
-
*
|
|
42
|
-
* and
|
|
43
|
-
*
|
|
44
|
-
*
|
|
40
|
+
* ci/roadmap.mjs + its test (2026-11-08): docs/06-roadmap.md is retired —
|
|
41
|
+
* Linear owns the order of work and the portal reads Now / Next / Later from
|
|
42
|
+
* it. The per-client docs/06-roadmap.md itself is history: `ia roadmap-retire`
|
|
43
|
+
* moves it to docs/archive/, never this operation.
|
|
45
44
|
*/
|
|
46
|
-
export declare const
|
|
45
|
+
export declare const TEMPLATE_RETIRED_FILES: string[];
|
|
46
|
+
/**
|
|
47
|
+
* Why a client repo is ad hoc (not an official Install Agent project), or null.
|
|
48
|
+
* The repo says so itself, in its CLIENT.md: `linear_project: none`, or a
|
|
49
|
+
* `backlog:` key in place of a Linear project. A new repo still holds the
|
|
50
|
+
* template placeholder and is official. The names are read at run time and
|
|
51
|
+
* never listed in this package: @installagent/sdk is public on npm.
|
|
52
|
+
*
|
|
53
|
+
* Ad hoc repos are listed (so a report shows they were seen) but never compared
|
|
54
|
+
* and never written by `template-sync` (not even `--apply`), and `client-drift
|
|
55
|
+
* --all`, `roadmap-migrate --all` and `roadmap-retire --all` skip them and say
|
|
56
|
+
* so. A shared rule change reaches them only by a hand copy, recorded in that
|
|
57
|
+
* repo's own commit. The portal falls back to their hand today / next.
|
|
58
|
+
*/
|
|
59
|
+
export declare function adhocReason(repoDir: string): string | null;
|
|
60
|
+
/**
|
|
61
|
+
* The client slugs an operation runs on: one named slug (its checkout must
|
|
62
|
+
* exist; an ad hoc repo is kept, so the caller can say why it skips it), or
|
|
63
|
+
* every clients/client-*\/ checkout except client-template with `all`, where
|
|
64
|
+
* the ad hoc repos are left out and returned in `adhoc` so the report can say so.
|
|
65
|
+
*/
|
|
66
|
+
export declare function selectClientSlugs(workspaceDir: string, options: {
|
|
67
|
+
slug?: string;
|
|
68
|
+
all?: boolean;
|
|
69
|
+
}, op: string): {
|
|
70
|
+
slugs: string[];
|
|
71
|
+
adhoc: string[];
|
|
72
|
+
};
|
|
47
73
|
export interface TemplateSyncOptions {
|
|
48
74
|
/** The installagent/ workspace root (the dir that contains clients/). */
|
|
49
75
|
workspaceDir: string;
|
|
@@ -52,7 +78,8 @@ export interface TemplateSyncOptions {
|
|
|
52
78
|
/** Copy the template's version over any drifted/missing file. Default false — report only. */
|
|
53
79
|
apply?: boolean;
|
|
54
80
|
}
|
|
55
|
-
|
|
81
|
+
/** `retired`: a TEMPLATE_RETIRED_FILES file the repo still has; `deleted`: `--apply` removed it. */
|
|
82
|
+
export type TemplateSyncFileStatus = "in-sync" | "drifted" | "missing" | "fixed" | "retired" | "deleted";
|
|
56
83
|
export interface TemplateSyncFileResult {
|
|
57
84
|
file: string;
|
|
58
85
|
status: TemplateSyncFileStatus;
|
|
@@ -62,7 +89,7 @@ export interface TemplateSyncRepoResult {
|
|
|
62
89
|
dir: string;
|
|
63
90
|
files: TemplateSyncFileResult[];
|
|
64
91
|
inSync: boolean;
|
|
65
|
-
/** Set (with the reason) for
|
|
92
|
+
/** Set (with the reason) for an ad hoc repo (see adhocReason): nothing was compared or written. */
|
|
66
93
|
excluded?: string;
|
|
67
94
|
/**
|
|
68
95
|
* CLIENT.md's Google Cloud keys (gcp_project / gcp_account) that are absent
|