@installagent/sdk 0.9.1 → 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.
@@ -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(/&amp;/g, "&")
45
+ .replace(/&lt;/g, "<")
46
+ .replace(/&gt;/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
+ }
@@ -32,6 +32,44 @@ import { type GcpManifestKey } from "./client-manifest.js";
32
32
  * anywhere.
33
33
  */
34
34
  export declare const TEMPLATE_SYNCED_FILES: string[];
35
+ /**
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.
39
+ *
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.
44
+ */
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
+ };
35
73
  export interface TemplateSyncOptions {
36
74
  /** The installagent/ workspace root (the dir that contains clients/). */
37
75
  workspaceDir: string;
@@ -40,7 +78,8 @@ export interface TemplateSyncOptions {
40
78
  /** Copy the template's version over any drifted/missing file. Default false — report only. */
41
79
  apply?: boolean;
42
80
  }
43
- export type TemplateSyncFileStatus = "in-sync" | "drifted" | "missing" | "fixed";
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";
44
83
  export interface TemplateSyncFileResult {
45
84
  file: string;
46
85
  status: TemplateSyncFileStatus;
@@ -50,6 +89,8 @@ export interface TemplateSyncRepoResult {
50
89
  dir: string;
51
90
  files: TemplateSyncFileResult[];
52
91
  inSync: boolean;
92
+ /** Set (with the reason) for an ad hoc repo (see adhocReason): nothing was compared or written. */
93
+ excluded?: string;
53
94
  /**
54
95
  * CLIENT.md's Google Cloud keys (gcp_project / gcp_account) that are absent
55
96
  * or still the placeholder. Report only: CLIENT.md is per-client, so even
@@ -1,5 +1,5 @@
1
- import { existsSync } from "node:fs";
2
- import { copyFile, mkdir, readdir, readFile } from "node:fs/promises";
1
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
2
+ import { copyFile, mkdir, readdir, readFile, rm } from "node:fs/promises";
3
3
  import { dirname, join, resolve } from "node:path";
4
4
  import { readGcpManifestFromRepo } from "./client-manifest.js";
5
5
  /**
@@ -41,14 +41,23 @@ export const TEMPLATE_SYNCED_FILES = [
41
41
  // repo-lint imports log-progress (rule 9), so the two always travel together.
42
42
  "ci/log-progress.mjs",
43
43
  "ci/log-progress.test.mjs",
44
- // repo-lint also imports roadmap (rule 10): the Roadmap tab + client roadmap
45
- // are generated from docs/06-roadmap.md.
46
- "ci/roadmap.mjs",
47
- "ci/roadmap.test.mjs",
48
44
  // repo-lint also imports builds-manifest (rule 11): the `## Builds` block
49
45
  // of CLIENT.md, the source of `ia portal sync-builds`.
50
46
  "ci/builds-manifest.mjs",
51
47
  "ci/builds-manifest.test.mjs",
48
+ // repo-lint also imports onboarding (rule 18): the generated status, news
49
+ // and Builds-card blocks of onboarding.html (client drift program, step 3).
50
+ "ci/onboarding.mjs",
51
+ "ci/onboarding.test.mjs",
52
+ // repo-lint also imports access (rule 21, 2026-11-08): docs/04 §1 is the one
53
+ // source of access status; the client's block in docs/03 is generated.
54
+ "ci/access.mjs",
55
+ "ci/access.test.mjs",
56
+ // The one write command for every generated view (progress list,
57
+ // onboarding blocks, the access block): rules 9, 18 and 21 name it,
58
+ // CADENCE.md points at it.
59
+ "ci/sync.mjs",
60
+ "ci/sync.test.mjs",
52
61
  "lefthook.yml",
53
62
  ".github/workflows/repo-lint.yml",
54
63
  ".github/workflows/pr-to-slack.yml",
@@ -57,6 +66,76 @@ export const TEMPLATE_SYNCED_FILES = [
57
66
  // in that repo's onboarding.html.
58
67
  "docs/kickoff-presentation.html",
59
68
  ];
69
+ /**
70
+ * Files the template used to sync and has since retired. A client repo that
71
+ * still has one is not in sync: the dry run lists it as `retired`, and
72
+ * `--apply` deletes it (`deleted`). Nothing else is ever deleted.
73
+ *
74
+ * ci/roadmap.mjs + its test (2026-11-08): docs/06-roadmap.md is retired —
75
+ * Linear owns the order of work and the portal reads Now / Next / Later from
76
+ * it. The per-client docs/06-roadmap.md itself is history: `ia roadmap-retire`
77
+ * moves it to docs/archive/, never this operation.
78
+ */
79
+ export const TEMPLATE_RETIRED_FILES = ["ci/roadmap.mjs", "ci/roadmap.test.mjs"];
80
+ const AD_HOC = "ad hoc repo: CLIENT.md says `linear_project: none`, so it is not an official Install Agent project — no template-sync, no Linear-based rule; it keeps its own docs/06-roadmap.md and rules";
81
+ const AD_HOC_BACKLOG = "ad hoc repo: CLIENT.md has `backlog:` in place of a Linear project — its CADENCE.md, lefthook.yml and CI are its own; copy a shared ci/ change by hand";
82
+ /**
83
+ * Why a client repo is ad hoc (not an official Install Agent project), or null.
84
+ * The repo says so itself, in its CLIENT.md: `linear_project: none`, or a
85
+ * `backlog:` key in place of a Linear project. A new repo still holds the
86
+ * template placeholder and is official. The names are read at run time and
87
+ * never listed in this package: @installagent/sdk is public on npm.
88
+ *
89
+ * Ad hoc repos are listed (so a report shows they were seen) but never compared
90
+ * and never written by `template-sync` (not even `--apply`), and `client-drift
91
+ * --all`, `roadmap-migrate --all` and `roadmap-retire --all` skip them and say
92
+ * so. A shared rule change reaches them only by a hand copy, recorded in that
93
+ * repo's own commit. The portal falls back to their hand today / next.
94
+ */
95
+ export function adhocReason(repoDir) {
96
+ const path = join(repoDir, "CLIENT.md");
97
+ if (!existsSync(path))
98
+ return null;
99
+ const text = readFileSync(path, "utf8");
100
+ if (/^backlog\s*:/m.test(text))
101
+ return AD_HOC_BACKLOG;
102
+ const linear = /^linear_project\s*:\s*(\S*)/m.exec(text)?.[1] ?? "";
103
+ return linear.toLowerCase() === "none" ? AD_HOC : null;
104
+ }
105
+ const CLIENT_SLUG = /^[a-z0-9][a-z0-9-]*$/;
106
+ /**
107
+ * The client slugs an operation runs on: one named slug (its checkout must
108
+ * exist; an ad hoc repo is kept, so the caller can say why it skips it), or
109
+ * every clients/client-*\/ checkout except client-template with `all`, where
110
+ * the ad hoc repos are left out and returned in `adhoc` so the report can say so.
111
+ */
112
+ export function selectClientSlugs(workspaceDir, options, op) {
113
+ if (Boolean(options.slug) === Boolean(options.all)) {
114
+ throw new Error(`${op} needs a slug or --all (one of them, not both)`);
115
+ }
116
+ const clientsDir = join(workspaceDir, "clients");
117
+ if (options.all) {
118
+ const all = existsSync(clientsDir)
119
+ ? readdirSync(clientsDir, { withFileTypes: true })
120
+ .filter((e) => e.isDirectory() && e.name.startsWith("client-") && e.name !== "client-template")
121
+ .map((e) => e.name.slice("client-".length))
122
+ .sort()
123
+ : [];
124
+ const isAdhoc = (slug) => adhocReason(join(clientsDir, `client-${slug}`)) !== null;
125
+ return {
126
+ slugs: all.filter((slug) => !isAdhoc(slug)),
127
+ adhoc: all.filter(isAdhoc),
128
+ };
129
+ }
130
+ const slug = String(options.slug).replace(/^client-/, "");
131
+ if (!CLIENT_SLUG.test(slug)) {
132
+ throw new Error(`"${options.slug}" is not a client slug (kebab-case, e.g. acme-hvac)`);
133
+ }
134
+ if (!existsSync(join(clientsDir, `client-${slug}`))) {
135
+ throw new Error(`no checkout at clients/client-${slug} under ${workspaceDir}`);
136
+ }
137
+ return { slugs: [slug], adhoc: [] };
138
+ }
60
139
  /**
61
140
  * Compare (and optionally fix) the shared infra files every client-<slug>
62
141
  * build repo copies verbatim from client-template at creation time. Never
@@ -80,6 +159,11 @@ export async function templateSync(options) {
80
159
  const repos = [];
81
160
  for (const slug of slugs) {
82
161
  const dir = join(clientsDir, `client-${slug}`);
162
+ const excluded = adhocReason(dir);
163
+ if (excluded) {
164
+ repos.push({ slug, dir, files: [], inSync: true, excluded, manifestGaps: [] });
165
+ continue;
166
+ }
83
167
  const fileResults = [];
84
168
  for (const rel of files) {
85
169
  const templateFile = join(templateDir, rel);
@@ -101,12 +185,22 @@ export async function templateSync(options) {
101
185
  }
102
186
  fileResults.push({ file: rel, status });
103
187
  }
188
+ if (!options.files) {
189
+ for (const rel of TEMPLATE_RETIRED_FILES) {
190
+ const repoFile = join(dir, rel);
191
+ if (!existsSync(repoFile))
192
+ continue;
193
+ if (apply)
194
+ await rm(repoFile);
195
+ fileResults.push({ file: rel, status: apply ? "deleted" : "retired" });
196
+ }
197
+ }
104
198
  const manifest = readGcpManifestFromRepo(dir);
105
199
  repos.push({
106
200
  slug,
107
201
  dir,
108
202
  files: fileResults,
109
- inSync: fileResults.every((f) => f.status === "in-sync" || f.status === "fixed"),
203
+ inSync: fileResults.every((f) => ["in-sync", "fixed", "deleted"].includes(f.status)),
110
204
  manifestGaps: manifest
111
205
  ? [...manifest.missing, ...manifest.unfilled, ...manifest.invalid]
112
206
  : [],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@installagent/sdk",
3
- "version": "0.9.1",
3
+ "version": "0.11.0",
4
4
  "description": "Install Agent's shared SDK for internal team operations (client repos, n8n workflows, docs search, and more).",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -29,7 +29,7 @@ skills/
29
29
  ├── backtest-acceptance-gates/ # prove an automation works before the client trusts it (ground truth, evidence, gates)
30
30
  ├── installagent-brand-kit/ # our brand for print/PDF/Excalidraw/decks (logo + brand red #d11a1a)
31
31
  ├── design-system/ # the Install Agent Design System (screens/UI)
32
- ├── house-voice/ # house voice for client-facing writing + the ~150-word client message budget
32
+ ├── house-voice/ # house voice for client-facing writing; client messages are short by default (150 words = a flag, not a cap)
33
33
  ├── contract-tech-agnostic/ # contracts/SOWs by FUNCTION and OUTCOME, never tech (+ SOW template in references/)
34
34
  ├── linear/ # Linear issue workflow for client build work (status discipline, sub-issue trees, PR linking)
35
35
  ├── ia-cli/ # route internal ops through the `ia` CLI (team-tools) — decision map + guardrails