@installagent/sdk 0.14.0 → 0.16.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/env-registry.js +19 -3
- package/dist/index.d.ts +6 -1
- package/dist/index.js +6 -1
- package/dist/portal-admin.d.ts +24 -0
- package/dist/portal-admin.js +12 -0
- package/dist/tech-call-agenda.d.ts +57 -0
- package/dist/tech-call-agenda.js +94 -0
- package/dist/tech-call-note-landed.d.ts +43 -0
- package/dist/tech-call-note-landed.js +93 -0
- package/dist/tech-call-prep.d.ts +94 -0
- package/dist/tech-call-prep.js +460 -0
- package/dist/tech-call-update-pass.d.ts +142 -0
- package/dist/tech-call-update-pass.js +707 -0
- package/dist/tech-call-verify.d.ts +191 -0
- package/dist/tech-call-verify.js +673 -0
- package/package.json +1 -1
- package/templates/env.example +3 -0
- package/templates/workspace-root/AGENT.md +2 -1
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +27 -0
- package/templates/workspace-root/skills/ia-cli/SKILL.md +5 -0
- package/templates/workspace-root/skills/linear/SKILL.md +13 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +48 -19
|
@@ -0,0 +1,707 @@
|
|
|
1
|
+
// `ia tech-call update-pass <slug>` — the post-call update pass. After the
|
|
2
|
+
// tech discovery call the engagement docs must change: open questions get
|
|
3
|
+
// answers, a priority moves, a stack fact firms up. A person used to do this
|
|
4
|
+
// with the engagement-spec skill, or it did not happen (it happened: nothing was
|
|
5
|
+
// committed after the call). This command does the pass and hands a person a
|
|
6
|
+
// branch to read and merge.
|
|
7
|
+
//
|
|
8
|
+
// What it does, in order:
|
|
9
|
+
// 1. Finds the tech-discovery note in the registry and its transcript.
|
|
10
|
+
// 2. Clones the client repo into a scratch folder (never a person's working
|
|
11
|
+
// tree) and makes the branch `bot/tech-call-update-<date>` from `base`.
|
|
12
|
+
// 3. Maps which lines a PERSON last wrote (`git blame`). Those stay, unless
|
|
13
|
+
// the call contradicts them.
|
|
14
|
+
// 4. Runs the engagement-spec skill's update pass with Claude Code, headless,
|
|
15
|
+
// with read and edit tools only, inside the clone.
|
|
16
|
+
// 5. Runs `node ci/sync.mjs --write`, then the transcript check
|
|
17
|
+
// (`techCallVerify --write`) on the result.
|
|
18
|
+
// 6. Gates: the diff touches only the docs, the page, the log and evidence;
|
|
19
|
+
// no secret; no new email or phone; no new template token; a changed
|
|
20
|
+
// hand-written line needs a real quote from the call.
|
|
21
|
+
// 7. Writes `evidence/<date>-tech-call-update.md`: the changes with quotes,
|
|
22
|
+
// the conflicts, the promises with no scope, and a DRAFT list of Linear
|
|
23
|
+
// issues. It never calls Linear.
|
|
24
|
+
// 8. Commits in the clone. With `push`: pushes the branch. With `notify`:
|
|
25
|
+
// one Slack DM to the technician. A person merges.
|
|
26
|
+
//
|
|
27
|
+
// Default = dry run: steps 1-8 in the scratch clone, no push, no DM.
|
|
28
|
+
// It changes a client repo (a branch) and sends a DM, so it is SDK + CLI only.
|
|
29
|
+
import { execFile } from "node:child_process";
|
|
30
|
+
import { existsSync } from "node:fs";
|
|
31
|
+
import { mkdir, mkdtemp, readdir, readFile, writeFile } from "node:fs/promises";
|
|
32
|
+
import { tmpdir } from "node:os";
|
|
33
|
+
import { join, resolve } from "node:path";
|
|
34
|
+
import { promisify } from "node:util";
|
|
35
|
+
import { redactContactDetails, removeMoney } from "./build-estimate.js";
|
|
36
|
+
import { execFailureDetail, execFileAsync } from "./exec.js";
|
|
37
|
+
import { SLUG_PATTERN } from "./new-client.js";
|
|
38
|
+
import { parseNoteFrontmatter } from "./tech-call-note-landed.js";
|
|
39
|
+
import { realProbes } from "./tech-call-prep.js";
|
|
40
|
+
import { findQuote, loadTranscripts, SLACK_BOT_TOKEN_ENV, techCallVerify, VERIFY_DOCS, } from "./tech-call-verify.js";
|
|
41
|
+
import { workspaceRootTemplateDir as workspaceTemplatesDir } from "./templates.js";
|
|
42
|
+
export const UPDATE_PASS_MODEL = "claude-opus-5-5";
|
|
43
|
+
export const FALLBACK_SLACK_USER_ENV = "IA_TECH_CALL_FALLBACK_SLACK_USER";
|
|
44
|
+
export const BOT_AUTHOR_NAME = "installagent-bot";
|
|
45
|
+
export const BOT_AUTHOR_EMAIL = "bot@installagent.com";
|
|
46
|
+
/** The only paths the pass may change. */
|
|
47
|
+
export const UPDATE_PASS_ALLOWED = [
|
|
48
|
+
/^docs\/0[1-4]-[a-z0-9-]+\.md$/,
|
|
49
|
+
/^docs\/00-delivery-log\.md$/,
|
|
50
|
+
/^onboarding\.html$/,
|
|
51
|
+
/^evidence\/[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+\.md$/,
|
|
52
|
+
];
|
|
53
|
+
const SECRET = /(xox[abp]-[A-Za-z0-9-]{10,}|sk-[A-Za-z0-9_-]{20,}|whsec_[A-Za-z0-9]{10,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY|ghp_[A-Za-z0-9]{20,})/;
|
|
54
|
+
const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
|
|
55
|
+
const PHONE = /(?:\+?1[\s.-]?)?\(?\d{3}\)?[\s.-]\d{3}[\s.-]\d{4}\b/g;
|
|
56
|
+
const PAY_WORDS = /\b(pay|paid|payroll|payout|invoice|commission|bonus|rate)\b/i;
|
|
57
|
+
// ---------------------------------------------------------------------------
|
|
58
|
+
// Pure
|
|
59
|
+
/** `git blame --line-porcelain` output → the lines whose author is not the bot. */
|
|
60
|
+
export function handEditedLines(blamePorcelain) {
|
|
61
|
+
const out = [];
|
|
62
|
+
let line = 0;
|
|
63
|
+
let author = "";
|
|
64
|
+
for (const row of blamePorcelain.split("\n")) {
|
|
65
|
+
const head = /^[0-9a-f]{40} \d+ (\d+)/.exec(row);
|
|
66
|
+
if (head)
|
|
67
|
+
line = Number(head[1]);
|
|
68
|
+
else if (row.startsWith("author "))
|
|
69
|
+
author = row.slice(7).trim();
|
|
70
|
+
else if (row.startsWith("\t") && line > 0) {
|
|
71
|
+
if (!/bot\b|\[bot\]/i.test(author))
|
|
72
|
+
out.push(line);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
return out;
|
|
76
|
+
}
|
|
77
|
+
/** `[3,4,5,9]` → `3-5, 9` — for the prompt. */
|
|
78
|
+
export function lineRanges(lines) {
|
|
79
|
+
const sorted = [...new Set(lines)].sort((a, b) => a - b);
|
|
80
|
+
const parts = [];
|
|
81
|
+
for (let i = 0; i < sorted.length; i++) {
|
|
82
|
+
const start = sorted[i];
|
|
83
|
+
let end = start;
|
|
84
|
+
while (sorted[i + 1] === end + 1)
|
|
85
|
+
end = sorted[++i];
|
|
86
|
+
parts.push(start === end ? `${start}` : `${start}-${end}`);
|
|
87
|
+
}
|
|
88
|
+
return parts.join(", ");
|
|
89
|
+
}
|
|
90
|
+
/** `git diff -U0 <base>` → per file: the BASE line numbers a hunk removed or replaced. */
|
|
91
|
+
export function changedBaseLines(diff) {
|
|
92
|
+
const out = {};
|
|
93
|
+
let file = "";
|
|
94
|
+
for (const row of diff.split("\n")) {
|
|
95
|
+
const name = /^--- a\/(.+)$/.exec(row);
|
|
96
|
+
if (name)
|
|
97
|
+
file = name[1];
|
|
98
|
+
const hunk = /^@@ -(\d+)(?:,(\d+))? \+/.exec(row);
|
|
99
|
+
if (hunk && file) {
|
|
100
|
+
const start = Number(hunk[1]);
|
|
101
|
+
const count = hunk[2] === undefined ? 1 : Number(hunk[2]);
|
|
102
|
+
const lines = out[file] ?? [];
|
|
103
|
+
for (let i = 0; i < count; i++)
|
|
104
|
+
lines.push(start + i);
|
|
105
|
+
out[file] = lines;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
return out;
|
|
109
|
+
}
|
|
110
|
+
/** The lines a diff ADDS, per file. */
|
|
111
|
+
export function addedLines(diff) {
|
|
112
|
+
const out = {};
|
|
113
|
+
let file = "";
|
|
114
|
+
for (const row of diff.split("\n")) {
|
|
115
|
+
const name = /^\+\+\+ b\/(.+)$/.exec(row);
|
|
116
|
+
if (name)
|
|
117
|
+
file = name[1];
|
|
118
|
+
else if (row.startsWith("+") && !row.startsWith("+++") && file) {
|
|
119
|
+
const lines = out[file] ?? [];
|
|
120
|
+
lines.push(row.slice(1));
|
|
121
|
+
out[file] = lines;
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
return out;
|
|
125
|
+
}
|
|
126
|
+
const count = (text, pattern) => (text.match(pattern) ?? []).length;
|
|
127
|
+
/**
|
|
128
|
+
* The gates. Empty = the branch may be pushed. Every failure says what and
|
|
129
|
+
* where, so the log alone tells a person what to fix.
|
|
130
|
+
*/
|
|
131
|
+
export function checkGates(input) {
|
|
132
|
+
const failures = [];
|
|
133
|
+
const outside = input.changedFiles.filter((file) => !UPDATE_PASS_ALLOWED.some((ok) => ok.test(file)));
|
|
134
|
+
if (outside.length > 0) {
|
|
135
|
+
failures.push({
|
|
136
|
+
gate: "paths",
|
|
137
|
+
detail: `the pass changed files it may not touch: ${outside.join(", ")}`,
|
|
138
|
+
});
|
|
139
|
+
}
|
|
140
|
+
const added = addedLines(input.diff);
|
|
141
|
+
for (const [file, lines] of Object.entries(added)) {
|
|
142
|
+
if (lines.some((line) => SECRET.test(line))) {
|
|
143
|
+
failures.push({ gate: "secret", detail: `${file}: an added line looks like a credential` });
|
|
144
|
+
}
|
|
145
|
+
// The evidence files quote the call; their text is redacted where it is written.
|
|
146
|
+
if (file.startsWith("evidence/"))
|
|
147
|
+
continue;
|
|
148
|
+
const fresh = new Set();
|
|
149
|
+
for (const line of lines) {
|
|
150
|
+
for (const match of [...(line.match(EMAIL) ?? []), ...(line.match(PHONE) ?? [])]) {
|
|
151
|
+
if (!input.baseText.includes(match))
|
|
152
|
+
fresh.add(file);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
if (fresh.size > 0) {
|
|
156
|
+
failures.push({
|
|
157
|
+
gate: "contact",
|
|
158
|
+
detail: `${file}: an added line holds an email address or a phone number that the repo did not have — point at the registry instead`,
|
|
159
|
+
});
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
const before = count(input.baseText, /REPLACE_WITH_[A-Z_]+/g);
|
|
163
|
+
const after = count(input.afterText, /REPLACE_WITH_[A-Z_]+/g);
|
|
164
|
+
if (after > before) {
|
|
165
|
+
failures.push({ gate: "tokens", detail: `template tokens went from ${before} to ${after}` });
|
|
166
|
+
}
|
|
167
|
+
const touched = changedBaseLines(input.diff);
|
|
168
|
+
for (const [file, lines] of Object.entries(touched)) {
|
|
169
|
+
const human = new Set(input.handEdited[file] ?? []);
|
|
170
|
+
const hit = lines.filter((line) => human.has(line));
|
|
171
|
+
if (hit.length === 0)
|
|
172
|
+
continue;
|
|
173
|
+
const backed = input.changes.some((change) => change.file === file && change.kind !== "fill" && change.at !== "");
|
|
174
|
+
if (!backed) {
|
|
175
|
+
failures.push({
|
|
176
|
+
gate: "hand-edited",
|
|
177
|
+
detail: `${file}: ${hit.length} hand-written line(s) changed (${lineRanges(hit)}) with no change entry that quotes the call`,
|
|
178
|
+
});
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
return failures;
|
|
182
|
+
}
|
|
183
|
+
/** The agent's `changes.json` → changes with the quote checked against the transcripts. */
|
|
184
|
+
export function checkChanges(raw, transcripts) {
|
|
185
|
+
const rows = Array.isArray(raw) ? raw : [];
|
|
186
|
+
const kinds = new Set(["fill", "update", "conflict", "status"]);
|
|
187
|
+
return rows
|
|
188
|
+
.map((row) => (row && typeof row === "object" ? row : {}))
|
|
189
|
+
.map((row) => {
|
|
190
|
+
const quote = String(row.quote ?? "").trim();
|
|
191
|
+
const found = quote ? findQuote(quote, { transcripts, slack: null }) : null;
|
|
192
|
+
return {
|
|
193
|
+
file: String(row.file ?? "").trim(),
|
|
194
|
+
kind: (kinds.has(String(row.kind)) ? row.kind : "update"),
|
|
195
|
+
summary: String(row.summary ?? "").trim(),
|
|
196
|
+
quote,
|
|
197
|
+
at: found?.at ?? "",
|
|
198
|
+
};
|
|
199
|
+
})
|
|
200
|
+
.filter((change) => change.file && change.summary);
|
|
201
|
+
}
|
|
202
|
+
export function checkLinearDrafts(raw) {
|
|
203
|
+
return (Array.isArray(raw) ? raw : [])
|
|
204
|
+
.map((row) => (row && typeof row === "object" ? row : {}))
|
|
205
|
+
.map((row) => ({
|
|
206
|
+
// Linear is shared by all staff: never a dollar amount, never a contact detail.
|
|
207
|
+
title: removeMoney(redactContactDetails(String(row.title ?? "").trim())).slice(0, 120),
|
|
208
|
+
line: removeMoney(redactContactDetails(String(row.line ?? "").trim())).slice(0, 240),
|
|
209
|
+
}))
|
|
210
|
+
.filter((draft) => draft.title);
|
|
211
|
+
}
|
|
212
|
+
/** The one-line DM. No pay text, ever. */
|
|
213
|
+
export function updatePassNotice(input) {
|
|
214
|
+
const line = `${input.slug}: tech-call update ready - ${input.compareUrl} - review and merge.`;
|
|
215
|
+
const text = input.noTechnician ? `${line} (No technician is linked on the CRM record.)` : line;
|
|
216
|
+
if (PAY_WORDS.test(text.replace(input.compareUrl, ""))) {
|
|
217
|
+
throw new Error("the notice must not mention pay");
|
|
218
|
+
}
|
|
219
|
+
return text;
|
|
220
|
+
}
|
|
221
|
+
export function buildUpdatePrompt(input) {
|
|
222
|
+
const human = Object.entries(input.handEdited)
|
|
223
|
+
.filter(([, lines]) => lines.length > 0)
|
|
224
|
+
.map(([file, lines]) => `- ${file}: lines ${lineRanges(lines)}`)
|
|
225
|
+
.join("\n");
|
|
226
|
+
return `You run the UPDATE PASS of the engagement-spec skill for the client "${input.slug}", after its
|
|
227
|
+
tech discovery call of ${input.callDate}. You are in the client's build repo (a scratch clone).
|
|
228
|
+
|
|
229
|
+
Read these first, in this order:
|
|
230
|
+
1. ${input.contextDir}/SKILL.md - the engagement-spec skill. Follow its "Two passes" section: this is
|
|
231
|
+
pass 2, an UPDATE, not a rewrite.
|
|
232
|
+
2. ${input.contextDir}/call-note.md - the call note (Fathom's summary and action items).
|
|
233
|
+
3. ${input.contextDir}/transcript.md - the full transcript, one line per turn: [HH:MM:SS] Speaker: text.
|
|
234
|
+
4. docs/01-overview.md, docs/02-tech-spec.md, docs/03-client-onboarding.md,
|
|
235
|
+
docs/04-access-checklist.md, onboarding.html, docs/00-delivery-log.md.
|
|
236
|
+
|
|
237
|
+
Rules, stricter than the skill where they differ:
|
|
238
|
+
- Change ONLY these files: docs/01-overview.md, docs/02-tech-spec.md, docs/03-client-onboarding.md,
|
|
239
|
+
docs/04-access-checklist.md, onboarding.html, docs/00-delivery-log.md. Create no file in the repo.
|
|
240
|
+
- Fill what is still a literal REPLACE_WITH_ token or an open question, when the call answers it.
|
|
241
|
+
- Lines a PERSON wrote stay as they are, unless the call says otherwise. These lines were last
|
|
242
|
+
written by a person:
|
|
243
|
+
${human || "- (none: every line is from the first pass)"}
|
|
244
|
+
When the call CONTRADICTS such a line, change the line and record the change with the exact
|
|
245
|
+
words from the transcript. When the call only adds detail, add it; do not rephrase what is there.
|
|
246
|
+
- Do not regenerate text that is still accurate. A smaller diff is a better diff.
|
|
247
|
+
- docs/04 section 1: a status is HAVE only when the call says the access was RECEIVED. "They will
|
|
248
|
+
send it" is REQUESTED. Never edit the block between the ACCESS_STATUS_TABLE markers in docs/03:
|
|
249
|
+
a script builds it.
|
|
250
|
+
- The tech spec's open questions are Linear issues. You cannot create or close issues. For an
|
|
251
|
+
open question the call answered: write the answer into the spec and KEEP its INS id in the
|
|
252
|
+
list with "(answered on the call; close after merge)". For a NEW open question: do not invent
|
|
253
|
+
an INS id; put it in linear-draft.json instead.
|
|
254
|
+
- docs/01, docs/03 and the Public section of onboarding.html are read by the client: plain
|
|
255
|
+
words, no tool jargon. No dollar amount anywhere. No email address or phone number that the
|
|
256
|
+
repo does not already hold.
|
|
257
|
+
- Add ONE entry to docs/00-delivery-log.md, in the format of the entries there: the docs were
|
|
258
|
+
updated from the ${input.callDate} tech discovery call. Name these two files in the entry as
|
|
259
|
+
its evidence (the command writes them after you): evidence/${input.date}-tech-call-update.md
|
|
260
|
+
and evidence/${input.date}-transcript-check.md.
|
|
261
|
+
- Do not run commands. Do not touch git.
|
|
262
|
+
|
|
263
|
+
When the files are done, write TWO files in ${input.contextDir} (not in the repo):
|
|
264
|
+
- changes.json: a JSON array, one object per change you made:
|
|
265
|
+
{"file": "<path>", "kind": "fill" | "update" | "conflict" | "status",
|
|
266
|
+
"summary": "<what changed, one sentence>",
|
|
267
|
+
"quote": "<the EXACT words from ONE turn of the transcript that the change rests on, 4 to 40 words>"}
|
|
268
|
+
"conflict" = the call contradicts a line a person wrote, or two things said on the calls
|
|
269
|
+
disagree. A quote that is not literally in the transcript is thrown away, and a change to a
|
|
270
|
+
hand-written line with no real quote stops the whole pass.
|
|
271
|
+
- linear-draft.json: a JSON array of {"title": "<issue title>", "line": "<one line of context>"}
|
|
272
|
+
for each NEW open question or follow-up the call raised. No dollar amounts.
|
|
273
|
+
Then answer with one line: the number of changes.`;
|
|
274
|
+
}
|
|
275
|
+
const cell = (text) => removeMoney(redactContactDetails(text))
|
|
276
|
+
.replace(/\s*\n\s*/g, " ")
|
|
277
|
+
.replace(/\|/g, "\\|");
|
|
278
|
+
export function renderUpdateEvidence(input) {
|
|
279
|
+
const table = (rows) => rows.length
|
|
280
|
+
? [
|
|
281
|
+
"| File | What changed | Words from the call |",
|
|
282
|
+
"|---|---|---|",
|
|
283
|
+
...rows.map((change) => `| \`${change.file}\` | ${cell(change.summary)} | ${change.at
|
|
284
|
+
? `${change.at} "${cell(change.quote.slice(0, 180))}"`
|
|
285
|
+
: "**no quote found in the transcript — check this one by hand**"} |`),
|
|
286
|
+
].join("\n")
|
|
287
|
+
: "None.";
|
|
288
|
+
const noScope = (input.verify?.promises ?? []).filter((promise) => !promise.scope);
|
|
289
|
+
return [
|
|
290
|
+
`# Tech-call update pass — ${input.slug} — call of ${input.callDate}`,
|
|
291
|
+
"",
|
|
292
|
+
`> \`ia tech-call update-pass ${input.slug}\`, ${input.date}, model ${input.model}. Branch \`${input.branch}\` from \`${input.base}\`.`,
|
|
293
|
+
"> A person reads this file and the diff, then merges. Nothing here was merged by the bot.",
|
|
294
|
+
"",
|
|
295
|
+
"## Conflicts — the call disagrees with what was written",
|
|
296
|
+
"",
|
|
297
|
+
table(input.changes.filter((change) => change.kind === "conflict")),
|
|
298
|
+
"",
|
|
299
|
+
"## Changes",
|
|
300
|
+
"",
|
|
301
|
+
table(input.changes.filter((change) => change.kind !== "conflict")),
|
|
302
|
+
"",
|
|
303
|
+
"## Promises made on a call that no scope item holds",
|
|
304
|
+
"",
|
|
305
|
+
noScope.length
|
|
306
|
+
? noScope.map((promise) => `- ${promise.at} — ${cell(promise.text)}`).join("\n")
|
|
307
|
+
: input.verify
|
|
308
|
+
? "None."
|
|
309
|
+
: "Not checked (the transcript check did not run).",
|
|
310
|
+
"",
|
|
311
|
+
"## Transcript check on this branch",
|
|
312
|
+
"",
|
|
313
|
+
input.verify
|
|
314
|
+
? `${input.verify.counts.supported} supported, ${input.verify.counts.unverified} unverified, ${input.verify.counts.contradicted} contradicted. The list is in \`evidence/${input.date}-transcript-check.md\`.`
|
|
315
|
+
: "Did not run.",
|
|
316
|
+
"",
|
|
317
|
+
"## Other branches that change the same docs",
|
|
318
|
+
"",
|
|
319
|
+
input.otherBranches.length
|
|
320
|
+
? `${input.otherBranches.map((name) => `- \`${name}\``).join("\n")}\n\nMerge by hand: this branch does not hold their changes.`
|
|
321
|
+
: "None.",
|
|
322
|
+
"",
|
|
323
|
+
"## DRAFT Linear issues — not created",
|
|
324
|
+
"",
|
|
325
|
+
input.drafts.length
|
|
326
|
+
? `${input.drafts.map((draft) => `- **${cell(draft.title)}** — ${cell(draft.line)}`).join("\n")}\n\nLinear is shared: ask before you create or close an issue.`
|
|
327
|
+
: "None.",
|
|
328
|
+
"",
|
|
329
|
+
...(input.gates.length
|
|
330
|
+
? [
|
|
331
|
+
"## GATES FAILED — this branch was not pushed",
|
|
332
|
+
"",
|
|
333
|
+
...input.gates.map((g) => `- ${g.gate}: ${g.detail}`),
|
|
334
|
+
"",
|
|
335
|
+
]
|
|
336
|
+
: []),
|
|
337
|
+
].join("\n");
|
|
338
|
+
}
|
|
339
|
+
/** `git@github.com:Org/repo.git` or an https URL → `https://github.com/Org/repo`, tokens dropped. */
|
|
340
|
+
export function repoWebUrl(remote) {
|
|
341
|
+
const match = /github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(remote.trim());
|
|
342
|
+
return match ? `https://github.com/${match[1]}/${match[2]}` : null;
|
|
343
|
+
}
|
|
344
|
+
/** A subprocess in a given folder. Not the shared ExecFileFn: that one has no `cwd`. */
|
|
345
|
+
async function execIn(cwd, file, args) {
|
|
346
|
+
await promisify(execFile)(file, args, {
|
|
347
|
+
cwd,
|
|
348
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
349
|
+
timeout: 30 * 60 * 1000,
|
|
350
|
+
});
|
|
351
|
+
}
|
|
352
|
+
async function defaultRunAgent(input) {
|
|
353
|
+
await execIn(input.cwd, "claude", [
|
|
354
|
+
"-p",
|
|
355
|
+
input.prompt,
|
|
356
|
+
"--model",
|
|
357
|
+
input.model,
|
|
358
|
+
"--permission-mode",
|
|
359
|
+
"acceptEdits",
|
|
360
|
+
"--allowedTools",
|
|
361
|
+
"Read",
|
|
362
|
+
"Edit",
|
|
363
|
+
"Write",
|
|
364
|
+
"Glob",
|
|
365
|
+
"Grep",
|
|
366
|
+
"--disallowedTools",
|
|
367
|
+
"Bash",
|
|
368
|
+
"WebFetch",
|
|
369
|
+
"WebSearch",
|
|
370
|
+
"--add-dir",
|
|
371
|
+
input.contextDir,
|
|
372
|
+
"--strict-mcp-config",
|
|
373
|
+
"--no-session-persistence",
|
|
374
|
+
]);
|
|
375
|
+
}
|
|
376
|
+
async function slackCall(method, body, token, fetchImpl) {
|
|
377
|
+
const res = await fetchImpl(`https://slack.com/api/${method}`, {
|
|
378
|
+
method: "POST",
|
|
379
|
+
headers: {
|
|
380
|
+
Authorization: `Bearer ${token}`,
|
|
381
|
+
"Content-Type": "application/x-www-form-urlencoded",
|
|
382
|
+
},
|
|
383
|
+
body: new URLSearchParams(body),
|
|
384
|
+
});
|
|
385
|
+
return (await res.json().catch(() => ({ ok: false, error: "bad response" })));
|
|
386
|
+
}
|
|
387
|
+
/** A clone URL can carry a token; a git error message repeats the URL. Never let it out. */
|
|
388
|
+
export function scrubCredentials(text) {
|
|
389
|
+
return text.replace(/(https?:\/\/)[^/@\s:]+:[^/@\s]+@/g, "$1***@");
|
|
390
|
+
}
|
|
391
|
+
export async function techCallUpdatePass(slug, options) {
|
|
392
|
+
try {
|
|
393
|
+
const result = await runUpdatePass(slug, options);
|
|
394
|
+
return { ...result, notes: result.notes.map(scrubCredentials) };
|
|
395
|
+
}
|
|
396
|
+
catch (error) {
|
|
397
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
398
|
+
throw new Error(scrubCredentials(message));
|
|
399
|
+
}
|
|
400
|
+
}
|
|
401
|
+
async function runUpdatePass(slug, options) {
|
|
402
|
+
if (!SLUG_PATTERN.test(slug)) {
|
|
403
|
+
throw new Error(`invalid slug "${slug}" — use lowercase letters, digits, and hyphens`);
|
|
404
|
+
}
|
|
405
|
+
if (options.notify && !options.push)
|
|
406
|
+
throw new Error("--notify needs --push: the DM links the branch");
|
|
407
|
+
const exec = options.execFileImpl ?? execFileAsync;
|
|
408
|
+
const fetchImpl = options.fetchImpl ?? fetch;
|
|
409
|
+
const env = options.env ?? process.env;
|
|
410
|
+
const workspace = resolve(options.workspaceDir);
|
|
411
|
+
const now = options.now ?? new Date();
|
|
412
|
+
const date = now.toISOString().slice(0, 10);
|
|
413
|
+
const base = options.base ?? "main";
|
|
414
|
+
const notes = [];
|
|
415
|
+
const git = async (cwd, ...args) => (await exec("git", ["-C", cwd, ...args])).stdout;
|
|
416
|
+
// 1. The tech-discovery note.
|
|
417
|
+
const registry = join(workspace, "team-clients");
|
|
418
|
+
const callsDir = join(registry, "clients", slug, "calls");
|
|
419
|
+
const noteNames = options.registryRef
|
|
420
|
+
? (await git(registry, "ls-tree", "--name-only", `${options.registryRef}:clients/${slug}/calls`).catch(() => ""))
|
|
421
|
+
.split("\n")
|
|
422
|
+
.filter(Boolean)
|
|
423
|
+
: existsSync(callsDir)
|
|
424
|
+
? await readdir(callsDir)
|
|
425
|
+
: [];
|
|
426
|
+
const readNote = (name) => options.registryRef
|
|
427
|
+
? git(registry, "show", `${options.registryRef}:clients/${slug}/calls/${name}`).catch(() => "")
|
|
428
|
+
: readFile(join(callsDir, name), "utf8").catch(() => "");
|
|
429
|
+
let callDate = options.call ?? "";
|
|
430
|
+
let noteText = "";
|
|
431
|
+
for (const name of noteNames
|
|
432
|
+
.filter((n) => /^\d{4}-\d{2}-\d{2}\.md$/.test(n))
|
|
433
|
+
.sort()
|
|
434
|
+
.reverse()) {
|
|
435
|
+
const text = await readNote(name);
|
|
436
|
+
const isTech = parseNoteFrontmatter(text).type?.toLowerCase() === "tech-discovery";
|
|
437
|
+
if (callDate ? name.startsWith(callDate) : isTech) {
|
|
438
|
+
callDate = name.slice(0, 10);
|
|
439
|
+
noteText = text;
|
|
440
|
+
if (!isTech)
|
|
441
|
+
notes.push(`The ${callDate} note is typed "${parseNoteFrontmatter(text).type ?? "?"}", not tech-discovery: used because --call names it.`);
|
|
442
|
+
break;
|
|
443
|
+
}
|
|
444
|
+
}
|
|
445
|
+
if (!noteText) {
|
|
446
|
+
throw new Error(callDate
|
|
447
|
+
? `no call note for ${callDate} in team-clients/clients/${slug}/calls/`
|
|
448
|
+
: `"${slug}" has no call note with \`type: tech-discovery\` — pass --call <date> to name the tech call`);
|
|
449
|
+
}
|
|
450
|
+
const fathomId = parseNoteFrontmatter(noteText).fathom_id ?? null;
|
|
451
|
+
const branch = `bot/tech-call-update-${callDate}`;
|
|
452
|
+
// 2. The clone.
|
|
453
|
+
const localRepo = join(workspace, "clients", `client-${slug}`);
|
|
454
|
+
const source = options.cloneUrl ?? localRepo;
|
|
455
|
+
if (!options.cloneUrl && !existsSync(localRepo)) {
|
|
456
|
+
throw new Error(`${localRepo} not found — clone the client repo first (\`ia sync\`), or pass --clone-url`);
|
|
457
|
+
}
|
|
458
|
+
const remote = options.cloneUrl ??
|
|
459
|
+
(await git(localRepo, "remote", "get-url", "origin").catch(() => "")).trim();
|
|
460
|
+
// A remote that is not a GitHub URL (a test, a mirror): the repo's standard address.
|
|
461
|
+
const webUrl = repoWebUrl(remote) ?? `https://github.com/InstallAgent/client-${slug}`;
|
|
462
|
+
if (options.push && !options.force && remote) {
|
|
463
|
+
const heads = await exec("git", ["ls-remote", "--heads", remote, branch]).catch(() => ({
|
|
464
|
+
stdout: "",
|
|
465
|
+
}));
|
|
466
|
+
if (heads.stdout.trim()) {
|
|
467
|
+
return {
|
|
468
|
+
slug,
|
|
469
|
+
status: "exists",
|
|
470
|
+
callDate,
|
|
471
|
+
fathomId,
|
|
472
|
+
branch,
|
|
473
|
+
base,
|
|
474
|
+
cloneDir: "",
|
|
475
|
+
changedFiles: [],
|
|
476
|
+
changes: [],
|
|
477
|
+
drafts: [],
|
|
478
|
+
gates: [],
|
|
479
|
+
otherBranches: [],
|
|
480
|
+
verify: null,
|
|
481
|
+
compareUrl: webUrl ? `${webUrl}/compare/main...${branch}` : null,
|
|
482
|
+
notified: null,
|
|
483
|
+
notes: [
|
|
484
|
+
`The branch ${branch} is already on the remote: nothing was run. Pass --force to run again.`,
|
|
485
|
+
],
|
|
486
|
+
};
|
|
487
|
+
}
|
|
488
|
+
}
|
|
489
|
+
const scratch = options.scratchDir ?? (await mkdtemp(join(tmpdir(), `ia-update-pass-${slug}-`)));
|
|
490
|
+
const cloneDir = join(scratch, `client-${slug}`);
|
|
491
|
+
const contextDir = join(scratch, "context");
|
|
492
|
+
await mkdir(contextDir, { recursive: true });
|
|
493
|
+
await exec("git", ["clone", "--quiet", "--no-hardlinks", source, cloneDir]);
|
|
494
|
+
await git(cloneDir, "checkout", "--quiet", "-b", branch, base);
|
|
495
|
+
const baseSha = (await git(cloneDir, "rev-parse", "HEAD")).trim();
|
|
496
|
+
// Other branches with their own edits to the same docs (a technician's branch, most often).
|
|
497
|
+
const otherBranches = [];
|
|
498
|
+
if (!options.cloneUrl) {
|
|
499
|
+
const refs = (await git(localRepo, "for-each-ref", "--format=%(refname:short)", "refs/remotes/origin", "refs/heads").catch(() => ""))
|
|
500
|
+
.split("\n")
|
|
501
|
+
.map((ref) => ref.trim())
|
|
502
|
+
.filter((ref) => ref && !/(^|\/)(main|HEAD)$/.test(ref) && !ref.includes("bot/tech-call-update"));
|
|
503
|
+
for (const ref of refs) {
|
|
504
|
+
const log = await git(localRepo, "log", "--oneline", `${baseSha}..${ref}`, "--", ...VERIFY_DOCS).catch(() => "");
|
|
505
|
+
if (log.trim())
|
|
506
|
+
otherBranches.push(ref);
|
|
507
|
+
}
|
|
508
|
+
}
|
|
509
|
+
// 3. Who wrote what.
|
|
510
|
+
const handEdited = {};
|
|
511
|
+
for (const file of VERIFY_DOCS) {
|
|
512
|
+
const blame = await git(cloneDir, "blame", "--line-porcelain", "HEAD", "--", file).catch(() => "");
|
|
513
|
+
handEdited[file] = handEditedLines(blame);
|
|
514
|
+
}
|
|
515
|
+
// 4. The agent.
|
|
516
|
+
const transcripts = options.transcripts ??
|
|
517
|
+
(await loadTranscripts(slug, { workspaceDir: workspace, registryRef: options.registryRef, call: callDate }, fetchImpl));
|
|
518
|
+
const callTranscript = transcripts.filter((t) => t.call.startsWith(callDate));
|
|
519
|
+
if (callTranscript.length === 0) {
|
|
520
|
+
throw new Error(`no transcript for the ${callDate} call — the update pass needs what was said, not only the summary`);
|
|
521
|
+
}
|
|
522
|
+
// The workspace copy first (it is the one people edit); a runner with no
|
|
523
|
+
// workspace skills gets the copy bundled with the SDK.
|
|
524
|
+
const skillFile = join("skills", "engagement-spec", "SKILL.md");
|
|
525
|
+
const skillText = options.skillText ??
|
|
526
|
+
((await readFile(join(workspace, skillFile), "utf8").catch(() => "")) ||
|
|
527
|
+
(await readFile(join(workspaceTemplatesDir(), skillFile), "utf8").catch(() => "")));
|
|
528
|
+
if (!skillText)
|
|
529
|
+
throw new Error(`${skillFile} not found in the workspace or in the SDK bundle`);
|
|
530
|
+
await writeFile(join(contextDir, "SKILL.md"), skillText);
|
|
531
|
+
await writeFile(join(contextDir, "call-note.md"), noteText);
|
|
532
|
+
await writeFile(join(contextDir, "transcript.md"), callTranscript.map((t) => t.text).join("\n\n"));
|
|
533
|
+
const model = options.model ?? UPDATE_PASS_MODEL;
|
|
534
|
+
const prompt = buildUpdatePrompt({ slug, callDate, contextDir, handEdited, date });
|
|
535
|
+
if (options.runAgent)
|
|
536
|
+
await options.runAgent({ prompt, cwd: cloneDir, contextDir, model });
|
|
537
|
+
else
|
|
538
|
+
await defaultRunAgent({ prompt, cwd: cloneDir, contextDir, model });
|
|
539
|
+
const readJson = async (name) => {
|
|
540
|
+
try {
|
|
541
|
+
return JSON.parse(await readFile(join(contextDir, name), "utf8"));
|
|
542
|
+
}
|
|
543
|
+
catch {
|
|
544
|
+
notes.push(`The agent wrote no valid ${name}.`);
|
|
545
|
+
return [];
|
|
546
|
+
}
|
|
547
|
+
};
|
|
548
|
+
const changes = checkChanges(await readJson("changes.json"), transcripts);
|
|
549
|
+
const drafts = checkLinearDrafts(await readJson("linear-draft.json"));
|
|
550
|
+
// 5. sync, then the transcript check on the result.
|
|
551
|
+
if (existsSync(join(cloneDir, "ci", "sync.mjs"))) {
|
|
552
|
+
await execIn(cloneDir, "node", ["ci/sync.mjs", "--write"]).catch((error) => {
|
|
553
|
+
notes.push(`node ci/sync.mjs --write failed: ${execFailureDetail(error).detail.slice(0, 160)}`);
|
|
554
|
+
});
|
|
555
|
+
}
|
|
556
|
+
// Gates look at the agent's own diff, before the check adds its marks.
|
|
557
|
+
const agentDiff = await git(cloneDir, "diff", "-U0", "HEAD");
|
|
558
|
+
const agentFiles = (await git(cloneDir, "status", "--porcelain"))
|
|
559
|
+
.split("\n")
|
|
560
|
+
.filter(Boolean)
|
|
561
|
+
.map((row) => row.slice(3).trim());
|
|
562
|
+
const readAll = async (ref) => {
|
|
563
|
+
const parts = [];
|
|
564
|
+
for (const file of [...VERIFY_DOCS, "onboarding.html", "docs/00-delivery-log.md"]) {
|
|
565
|
+
parts.push(ref
|
|
566
|
+
? await git(cloneDir, "show", `${ref}:${file}`).catch(() => "")
|
|
567
|
+
: await readFile(join(cloneDir, file), "utf8").catch(() => ""));
|
|
568
|
+
}
|
|
569
|
+
return parts.join("\n");
|
|
570
|
+
};
|
|
571
|
+
const gates = checkGates({
|
|
572
|
+
changedFiles: agentFiles,
|
|
573
|
+
diff: agentDiff,
|
|
574
|
+
baseText: await readAll("HEAD"),
|
|
575
|
+
afterText: await readAll(null),
|
|
576
|
+
handEdited,
|
|
577
|
+
changes,
|
|
578
|
+
});
|
|
579
|
+
let verify = null;
|
|
580
|
+
try {
|
|
581
|
+
verify = await (options.verify ?? techCallVerify)(slug, {
|
|
582
|
+
workspaceDir: workspace,
|
|
583
|
+
repoDir: cloneDir,
|
|
584
|
+
registryRef: options.registryRef,
|
|
585
|
+
call: callDate,
|
|
586
|
+
write: true,
|
|
587
|
+
transcripts,
|
|
588
|
+
fetchImpl,
|
|
589
|
+
now,
|
|
590
|
+
});
|
|
591
|
+
}
|
|
592
|
+
catch (error) {
|
|
593
|
+
notes.push(`The transcript check did not run: ${error instanceof Error ? error.message.slice(0, 200) : "error"}`);
|
|
594
|
+
}
|
|
595
|
+
// 7. The evidence file.
|
|
596
|
+
await mkdir(join(cloneDir, "evidence"), { recursive: true });
|
|
597
|
+
const evidencePath = `evidence/${date}-tech-call-update.md`;
|
|
598
|
+
await writeFile(join(cloneDir, evidencePath), renderUpdateEvidence({
|
|
599
|
+
slug,
|
|
600
|
+
callDate,
|
|
601
|
+
date,
|
|
602
|
+
branch,
|
|
603
|
+
base,
|
|
604
|
+
model,
|
|
605
|
+
changes,
|
|
606
|
+
drafts,
|
|
607
|
+
verify,
|
|
608
|
+
otherBranches,
|
|
609
|
+
gates,
|
|
610
|
+
}));
|
|
611
|
+
// The repo's own lint, as a note: it says what a person must still fix before the merge.
|
|
612
|
+
if (existsSync(join(cloneDir, "ci", "repo-lint.mjs"))) {
|
|
613
|
+
await execIn(cloneDir, "node", ["ci/repo-lint.mjs"]).catch((error) => {
|
|
614
|
+
notes.push(`node ci/repo-lint.mjs fails on the branch: ${execFailureDetail(error).detail.slice(0, 300)}`);
|
|
615
|
+
});
|
|
616
|
+
}
|
|
617
|
+
// 8. Commit; then push and notify, only with clean gates.
|
|
618
|
+
await git(cloneDir, "add", "-A");
|
|
619
|
+
const changedFiles = (await git(cloneDir, "diff", "--cached", "--name-only"))
|
|
620
|
+
.split("\n")
|
|
621
|
+
.filter(Boolean);
|
|
622
|
+
await exec("git", [
|
|
623
|
+
"-C",
|
|
624
|
+
cloneDir,
|
|
625
|
+
"-c",
|
|
626
|
+
`user.name=${BOT_AUTHOR_NAME}`,
|
|
627
|
+
"-c",
|
|
628
|
+
`user.email=${BOT_AUTHOR_EMAIL}`,
|
|
629
|
+
"commit",
|
|
630
|
+
"--quiet",
|
|
631
|
+
"--no-verify",
|
|
632
|
+
"-m",
|
|
633
|
+
`Update the engagement docs from the ${callDate} tech discovery call`,
|
|
634
|
+
"-m",
|
|
635
|
+
`Bot branch: a person reviews and merges. See ${evidencePath}.`,
|
|
636
|
+
"-m",
|
|
637
|
+
`Tech-Call-Note: ${fathomId ?? callDate}`,
|
|
638
|
+
]);
|
|
639
|
+
const compareUrl = webUrl ? `${webUrl}/compare/main...${branch}` : null;
|
|
640
|
+
const result = {
|
|
641
|
+
slug,
|
|
642
|
+
status: "dry-run",
|
|
643
|
+
callDate,
|
|
644
|
+
fathomId,
|
|
645
|
+
branch,
|
|
646
|
+
base,
|
|
647
|
+
cloneDir,
|
|
648
|
+
changedFiles,
|
|
649
|
+
changes,
|
|
650
|
+
drafts,
|
|
651
|
+
gates,
|
|
652
|
+
otherBranches,
|
|
653
|
+
verify: verify?.counts ?? null,
|
|
654
|
+
compareUrl,
|
|
655
|
+
notified: null,
|
|
656
|
+
notes,
|
|
657
|
+
};
|
|
658
|
+
if (gates.length > 0) {
|
|
659
|
+
result.status = "gates-failed";
|
|
660
|
+
return result;
|
|
661
|
+
}
|
|
662
|
+
if (!options.push)
|
|
663
|
+
return result;
|
|
664
|
+
if (options.cloneUrl)
|
|
665
|
+
await git(cloneDir, "remote", "set-url", "origin", options.cloneUrl);
|
|
666
|
+
else if (remote)
|
|
667
|
+
await git(cloneDir, "remote", "set-url", "origin", remote);
|
|
668
|
+
// --force replaces a bot branch that is already on the remote — but only
|
|
669
|
+
// while the bot is still its last author. A person's commit on the branch
|
|
670
|
+
// (a fix before the merge) is never overwritten.
|
|
671
|
+
const lease = [];
|
|
672
|
+
if (options.force) {
|
|
673
|
+
const tip = (await git(cloneDir, "ls-remote", "--heads", "origin", branch)).split(/\s/)[0] ?? "";
|
|
674
|
+
if (tip) {
|
|
675
|
+
await git(cloneDir, "fetch", "--quiet", "origin", branch);
|
|
676
|
+
const author = (await git(cloneDir, "log", "-1", "--format=%an", "FETCH_HEAD")).trim();
|
|
677
|
+
if (author !== BOT_AUTHOR_NAME) {
|
|
678
|
+
throw new Error(`${branch} on the remote has a commit by a person (${author}) — not overwritten. Merge or delete that branch first.`);
|
|
679
|
+
}
|
|
680
|
+
lease.push(`--force-with-lease=${branch}:${tip}`);
|
|
681
|
+
}
|
|
682
|
+
}
|
|
683
|
+
await git(cloneDir, "push", "--quiet", ...lease, "origin", branch);
|
|
684
|
+
result.status = "pushed";
|
|
685
|
+
if (options.notify) {
|
|
686
|
+
const token = env[SLACK_BOT_TOKEN_ENV];
|
|
687
|
+
if (!token || !compareUrl)
|
|
688
|
+
throw new Error(`the branch is pushed (${branch}) but the DM was not sent: ${token ? "no repo URL" : `${SLACK_BOT_TOKEN_ENV} is not set`}`);
|
|
689
|
+
const team = await (options.team ?? realProbes({ workspaceDir: workspace, fetchImpl, env }).team)(slug);
|
|
690
|
+
let userId = "";
|
|
691
|
+
if (typeof team !== "string" && team.technicians[0]) {
|
|
692
|
+
const found = await slackCall("users.lookupByEmail", { email: team.technicians[0].email }, token, fetchImpl);
|
|
693
|
+
userId = String(found.user?.id ?? "");
|
|
694
|
+
}
|
|
695
|
+
const noTechnician = !userId;
|
|
696
|
+
if (noTechnician)
|
|
697
|
+
userId = env[FALLBACK_SLACK_USER_ENV] ?? "";
|
|
698
|
+
if (!userId) {
|
|
699
|
+
throw new Error(`the branch is pushed (${branch}) but the DM was not sent: no technician is linked on the CRM record and ${FALLBACK_SLACK_USER_ENV} is not set`);
|
|
700
|
+
}
|
|
701
|
+
const sent = await slackCall("chat.postMessage", { channel: userId, text: updatePassNotice({ slug, compareUrl, noTechnician }) }, token, fetchImpl);
|
|
702
|
+
if (!sent.ok)
|
|
703
|
+
throw new Error(`the branch is pushed (${branch}) but Slack refused the DM: ${String(sent.error ?? "error")}`);
|
|
704
|
+
result.notified = noTechnician ? "fallback" : "technician";
|
|
705
|
+
}
|
|
706
|
+
return result;
|
|
707
|
+
}
|