@installagent/sdk 0.2.0 → 0.4.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.
Files changed (56) hide show
  1. package/dist/agent-mirror.d.ts +69 -0
  2. package/dist/agent-mirror.js +275 -0
  3. package/dist/claude-hours.d.ts +134 -0
  4. package/dist/claude-hours.js +638 -0
  5. package/dist/client-drive.d.ts +3 -0
  6. package/dist/client-drive.js +2 -2
  7. package/dist/client-linear-create.d.ts +10 -0
  8. package/dist/client-linear-create.js +30 -3
  9. package/dist/env-fill.js +21 -4
  10. package/dist/env-registry.d.ts +4 -0
  11. package/dist/env-registry.js +54 -2
  12. package/dist/git.d.ts +31 -0
  13. package/dist/git.js +59 -0
  14. package/dist/google-service-account.d.ts +20 -0
  15. package/dist/google-service-account.js +49 -0
  16. package/dist/hours-estimate.d.ts +43 -0
  17. package/dist/hours-estimate.js +159 -0
  18. package/dist/hours-export-schedule.d.ts +35 -0
  19. package/dist/hours-export-schedule.js +188 -0
  20. package/dist/hours-ledger.d.ts +137 -0
  21. package/dist/hours-ledger.js +926 -0
  22. package/dist/index.d.ts +14 -3
  23. package/dist/index.js +14 -3
  24. package/dist/portal-admin.d.ts +68 -0
  25. package/dist/portal-admin.js +64 -1
  26. package/dist/sync-repos.d.ts +7 -0
  27. package/dist/sync-repos.js +10 -1
  28. package/dist/template-sync.d.ts +10 -9
  29. package/dist/template-sync.js +14 -9
  30. package/dist/triage-backfill.d.ts +37 -0
  31. package/dist/triage-backfill.js +211 -0
  32. package/dist/triage-enable.d.ts +90 -0
  33. package/dist/triage-enable.js +428 -0
  34. package/dist/triage-gates.d.ts +252 -0
  35. package/dist/triage-gates.js +951 -0
  36. package/dist/workspace-push.d.ts +39 -0
  37. package/dist/workspace-push.js +78 -0
  38. package/dist/workspace-status.d.ts +37 -0
  39. package/dist/workspace-status.js +114 -0
  40. package/package.json +1 -1
  41. package/templates/env.example +6 -2
  42. package/templates/workspace-root/.claude/settings.json +12 -1
  43. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +53 -28
  44. package/templates/workspace-root/skills/CLAUDE.md +6 -1
  45. package/templates/workspace-root/skills/README.md +17 -2
  46. package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
  47. package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
  48. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
  49. package/templates/workspace-root/skills/client-latest/SKILL.md +124 -82
  50. package/templates/workspace-root/skills/client-latest/catchup.command.md +5 -4
  51. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +90 -13
  52. package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
  53. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
  54. package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
  55. package/templates/workspace-root/skills/ia-cli/SKILL.md +30 -1
  56. package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
@@ -0,0 +1,926 @@
1
+ import { execFile } from "node:child_process";
2
+ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
3
+ import { homedir } from "node:os";
4
+ import { basename, join, resolve } from "node:path";
5
+ import { promisify } from "node:util";
6
+ import { CLAUDE_CONFIG_DIR_ENV, exportClaudeHours, HOURS_EXPORT_SCHEMA, PROMPT_WINDOW_MINUTES, parseLedgerDate, parseMinuteIso, UNATTRIBUTED_SLUG, } from "./claude-hours.js";
7
+ import { AIRTABLE_API_TOKEN_ENV, DEFAULT_AIRTABLE_BASE_ID, DEFAULT_AIRTABLE_TABLE_ID, } from "./client-drive.js";
8
+ import { parseLinearProjectSlugId } from "./client-linear.js";
9
+ import { findWorkspaceRoot } from "./env-file.js";
10
+ import { estimateHours, HOURS_SOURCES, LEAD_HEAVY_MINUTES, LEAD_LIGHT_MINUTES, LEDGER_TIME_ZONE, ledgerDay, minuteOf, round2, roundMonths, SESSION_GAP_MINUTES, } from "./hours-estimate.js";
11
+ import { findProjectBySlugId, LINEAR_API_TOKEN_ENV, linearRequest } from "./linear-project.js";
12
+ import { createLogger } from "./log.js";
13
+ // `ia hours-ledger` — rebuild the internal hours ledger's data from the
14
+ // traces work leaves behind, with the same rules every time (hours-estimate.ts).
15
+ //
16
+ // Sources, per person and client:
17
+ // - git — every commit in each clients/client-<slug> repo (after a
18
+ // `git fetch`, so technicians' pushed work is included), every
19
+ // team-clients commit that touched clients/<slug>/, and any
20
+ // extra repo the config maps to a client.
21
+ // - linear — issue created (creator), started and completed (assignee),
22
+ // and each comment (author), in each client's Linear project
23
+ // (the `linear_project` URL in its CLIENT.md).
24
+ // - claude — the per-minute activity each person's `ia hours-export`
25
+ // produces, kept in a cumulative store under the ledger dir,
26
+ // because Claude Code deletes its own logs after ~30 days.
27
+ // - call / slack (or anything else) — frozen CSV files in `frozen/`,
28
+ // loaded as-is; nothing refreshes them automatically.
29
+ // - the CRM — status, technician and tech start date from
30
+ // Airtable "Clients - Master" / "Team - Master".
31
+ //
32
+ // Output is hours and dates only. It never requests a package, contract
33
+ // value, MRR or pay field from Airtable (CLIENT_FIELDS / TEAM_FIELDS are the
34
+ // whole list) and never writes a dollar figure: pay math lives only in the
35
+ // private ledger page. Everything it writes stays in the ledger dir on this
36
+ // machine.
37
+ const log = createLogger("sdk.hours-ledger");
38
+ export const HOURS_LEDGER_SCHEMA = "ia-hours-ledger/1";
39
+ const CLAUDE_STORE_SCHEMA = "ia-hours-ledger-claude/1";
40
+ /** Where the ledger keeps its config, inbox, frozen sources, Claude store and output. */
41
+ export const DEFAULT_HOURS_LEDGER_DIR = join(".config", "installagent", "hours-ledger");
42
+ /** The ledger's window starts here unless --since says otherwise. */
43
+ export const LEDGER_WINDOW_START = "2026-06-01";
44
+ /** Activity on a slug that is neither an engagement in the CRM nor a build repo. */
45
+ export const OTHER_LEAD_SLUG = "other-lead";
46
+ /** "Team - Master" in the Clients - Master base. */
47
+ const TEAM_MASTER_TABLE_ID = "tbl3rr8K3dkuUABjl";
48
+ const AIRTABLE_API_BASE_URL = "https://api.airtable.com/v0";
49
+ /**
50
+ * The only Clients - Master fields ever requested. No package, contract value or MRR — on
51
+ * purpose — and no Name either: for some records it holds a contact person, not the business.
52
+ * The display name comes from the registry profile's `dba` / `legal_name` (`registryName`).
53
+ */
54
+ export const CLIENT_FIELDS = ["Slug", "Status", "Technician", "Tech Start Date"];
55
+ /** The only Team - Master fields ever requested. No pay — on purpose. */
56
+ export const TEAM_FIELDS = ["Name", "Email"];
57
+ const FETCH_CONCURRENCY = 6;
58
+ const GIT_MAX_BUFFER = 64 * 1024 * 1024;
59
+ const GIT_FETCH_TIMEOUT_MS = 90_000;
60
+ const STALE_CLAUDE_DAYS = 21;
61
+ const DAY_MS = 86_400_000;
62
+ const LINEAR_PROJECT_FIELD_PATTERN = /^linear_project:\s*(\S+)\s*$/m;
63
+ const CONFIG_TEMPLATE = {
64
+ people: {
65
+ Firstname: { emails: ["firstname@installagent.com", "personal-git-local-part@", "githubuser"] },
66
+ },
67
+ extraRepos: [],
68
+ };
69
+ const defaultGitExec = async (file, args) => {
70
+ const { stdout, stderr } = await promisify(execFile)(file, [...args], {
71
+ maxBuffer: GIT_MAX_BUFFER,
72
+ timeout: GIT_FETCH_TIMEOUT_MS,
73
+ });
74
+ return { stdout: String(stdout), stderr: String(stderr) };
75
+ };
76
+ function expandHome(path, home) {
77
+ return resolve(path.replace(/^~(?=$|[\\/])/, home));
78
+ }
79
+ function readJson(path) {
80
+ return JSON.parse(readFileSync(path, "utf8"));
81
+ }
82
+ function loadConfig(ledgerDir) {
83
+ const path = join(ledgerDir, "config.json");
84
+ if (!existsSync(path)) {
85
+ writeFileSync(path, `${JSON.stringify(CONFIG_TEMPLATE, null, 2)}\n`);
86
+ throw new Error(`No ledger config yet — wrote a template to ${path}. Fill in one entry per person: the ledger ` +
87
+ "name, then how git and Linear identify them — an exact address, a local part ending in " +
88
+ '"@" (any domain, GitHub noreply too), or a piece of the local part. Add any client repo ' +
89
+ "outside clients/ under extraRepos, and run this again.");
90
+ }
91
+ const config = readJson(path);
92
+ const people = Object.entries(config.people ?? {});
93
+ if (people.length === 0 || people.some(([name]) => name === "Firstname")) {
94
+ throw new Error(`${path} still has the template's people — fill it in first.`);
95
+ }
96
+ for (const [name, entry] of people) {
97
+ if (!Array.isArray(entry?.emails) || entry.emails.some((email) => typeof email !== "string")) {
98
+ throw new Error(`${path}: people.${name}.emails must be a list of strings`);
99
+ }
100
+ }
101
+ return config;
102
+ }
103
+ /** Map an email to a ledger person by the config's address fragments. */
104
+ /**
105
+ * One config identity against one email, case-insensitive:
106
+ * - "ian@installagent.com" — that exact address (never "brian@installagent.com");
107
+ * - "jdoe-dev@" — that local part at any domain, also as a GitHub
108
+ * noreply "<id>+jdoe-dev@users.noreply.github.com";
109
+ * - "jdoehacks" — any local part containing it.
110
+ */
111
+ export function identityMatches(identity, email) {
112
+ const want = identity.trim().toLowerCase();
113
+ const have = email.trim().toLowerCase();
114
+ if (!want || !have.includes("@"))
115
+ return false;
116
+ const [local = "", domain = ""] = have.split("@");
117
+ if (want.endsWith("@")) {
118
+ const wantLocal = want.slice(0, -1);
119
+ return local === wantLocal || local.endsWith(`+${wantLocal}`);
120
+ }
121
+ if (want.includes("@"))
122
+ return want === `${local}@${domain}`;
123
+ return local.includes(want);
124
+ }
125
+ function personMatcher(config) {
126
+ const entries = Object.entries(config.people);
127
+ return (email) => {
128
+ if (!email)
129
+ return null;
130
+ for (const [name, entry] of entries) {
131
+ if (entry.emails.some((identity) => identityMatches(identity, email)))
132
+ return name;
133
+ }
134
+ return null;
135
+ };
136
+ }
137
+ function normalizePerson(config, raw) {
138
+ const wanted = raw.trim().toLowerCase();
139
+ return Object.keys(config.people).find((name) => name.toLowerCase() === wanted) ?? null;
140
+ }
141
+ async function mapLimit(items, limit, fn) {
142
+ const results = new Array(items.length);
143
+ let next = 0;
144
+ const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
145
+ while (next < items.length) {
146
+ const index = next++;
147
+ results[index] = await fn(items[index]);
148
+ }
149
+ });
150
+ await Promise.all(workers);
151
+ return results;
152
+ }
153
+ // ---------- CRM (Airtable) ----------
154
+ /**
155
+ * A client's business name from its registry profile's Identity section —
156
+ * `dba`, else `legal_name`. Only those two keys are read; never the contact section.
157
+ */
158
+ function registryName(workspaceRoot, slug) {
159
+ const path = join(workspaceRoot, "team-clients", "clients", slug, "PROFILE.md");
160
+ if (!existsSync(path))
161
+ return null;
162
+ const text = readFileSync(path, "utf8");
163
+ for (const key of ["dba", "legal_name"]) {
164
+ const raw = new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(text)?.[1] ?? "";
165
+ const value = raw
166
+ .replace(/\s+#.*$/, "")
167
+ .trim()
168
+ .replace(/^["']|["']$/g, "")
169
+ .trim();
170
+ if (value && value !== "null")
171
+ return value;
172
+ }
173
+ return null;
174
+ }
175
+ async function airtableList(fetchImpl, token, tableId, fields, formula) {
176
+ const records = [];
177
+ let offset;
178
+ do {
179
+ const url = new URL(`${AIRTABLE_API_BASE_URL}/${DEFAULT_AIRTABLE_BASE_ID}/${tableId}`);
180
+ for (const field of fields)
181
+ url.searchParams.append("fields[]", field);
182
+ if (formula)
183
+ url.searchParams.set("filterByFormula", formula);
184
+ url.searchParams.set("pageSize", "100");
185
+ if (offset)
186
+ url.searchParams.set("offset", offset);
187
+ const res = await fetchImpl(url, { headers: { Authorization: `Bearer ${token}` } });
188
+ if (res.status === 401 || res.status === 403) {
189
+ throw new Error(`Airtable rejected ${AIRTABLE_API_TOKEN_ENV} (HTTP ${res.status}) — it needs data.records:read on the Clients - Master base.`);
190
+ }
191
+ if (!res.ok)
192
+ throw new Error(`Airtable read of ${tableId} failed: HTTP ${res.status}`);
193
+ const body = (await res.json());
194
+ for (const record of body.records ?? [])
195
+ records.push({ id: record.id, fields: record.fields ?? {} });
196
+ offset = body.offset;
197
+ } while (offset);
198
+ return records;
199
+ }
200
+ async function loadCrm(fetchImpl, token, matchPerson) {
201
+ const [team, clients] = await Promise.all([
202
+ airtableList(fetchImpl, token, TEAM_MASTER_TABLE_ID, TEAM_FIELDS),
203
+ airtableList(fetchImpl, token, DEFAULT_AIRTABLE_TABLE_ID, CLIENT_FIELDS, "NOT({Slug} = '')"),
204
+ ]);
205
+ const teamById = new Map();
206
+ for (const member of team) {
207
+ const email = typeof member.fields.Email === "string" ? member.fields.Email : null;
208
+ const name = typeof member.fields.Name === "string" ? member.fields.Name : member.id;
209
+ teamById.set(member.id, matchPerson(email) ?? name);
210
+ }
211
+ const bySlug = new Map();
212
+ for (const record of clients) {
213
+ const slug = typeof record.fields.Slug === "string" ? record.fields.Slug.trim() : "";
214
+ if (!slug)
215
+ continue;
216
+ const techIds = Array.isArray(record.fields.Technician) ? record.fields.Technician : [];
217
+ const tech = techIds.map((id) => teamById.get(String(id))).find((value) => value !== undefined) ?? null;
218
+ const techStart = typeof record.fields["Tech Start Date"] === "string"
219
+ ? record.fields["Tech Start Date"]
220
+ : null;
221
+ const client = {
222
+ slug,
223
+ status: typeof record.fields.Status === "string" ? record.fields.Status : null,
224
+ tech,
225
+ techStart,
226
+ engaged: tech !== null || techStart !== null,
227
+ };
228
+ const existing = bySlug.get(slug);
229
+ // Two records on one slug (a lead and the engagement): keep the engagement.
230
+ if (!existing || (!existing.engaged && client.engaged))
231
+ bySlug.set(slug, client);
232
+ }
233
+ return bySlug;
234
+ }
235
+ async function gitEvents(exec, repos, registryPath, buildSlugs, window, doFetch, matchPerson) {
236
+ // Filtered by author date here, never with `git log --since`: --since walks by
237
+ // committer date and stops at the first old commit, so one rebased or
238
+ // back-dated commit at a branch tip hides everything behind it.
239
+ const inWindow = (ts) => !Number.isNaN(ts) && ts >= window.sinceMs && ts <= window.untilMs;
240
+ const fetchFailures = [];
241
+ const allRepoPaths = [
242
+ ...new Set([...repos.map((r) => r.path), ...(registryPath ? [registryPath] : [])]),
243
+ ];
244
+ if (doFetch) {
245
+ await mapLimit(allRepoPaths, FETCH_CONCURRENCY, async (path) => {
246
+ try {
247
+ await exec("git", ["-C", path, "fetch", "--all", "--quiet"]);
248
+ }
249
+ catch (error) {
250
+ const detail = error instanceof Error ? error.message.split("\n")[0] : String(error);
251
+ fetchFailures.push(`${basename(path)}: ${detail}`);
252
+ }
253
+ });
254
+ }
255
+ const events = [];
256
+ const unmappedByDomain = {};
257
+ const seen = new Set();
258
+ const format = "--format=@@%H|%ae|%aI";
259
+ const noteUnmapped = (email) => {
260
+ const domain = email.split("@")[1] ?? "unknown";
261
+ unmappedByDomain[domain] = (unmappedByDomain[domain] ?? 0) + 1;
262
+ };
263
+ await mapLimit(repos, FETCH_CONCURRENCY, async ({ slug, path }) => {
264
+ let stdout;
265
+ try {
266
+ ({ stdout } = await exec("git", ["-C", path, "log", "--all", format]));
267
+ }
268
+ catch (error) {
269
+ fetchFailures.push(`${basename(path)}: git log failed (${error instanceof Error ? error.message.split("\n")[0] : error})`);
270
+ return;
271
+ }
272
+ for (const line of stdout.split("\n")) {
273
+ if (!line.startsWith("@@"))
274
+ continue;
275
+ const [sha, email = "", iso = ""] = line.slice(2).split("|");
276
+ const ts = Date.parse(iso);
277
+ if (!inWindow(ts))
278
+ continue;
279
+ const person = matchPerson(email);
280
+ if (!person) {
281
+ noteUnmapped(email);
282
+ continue;
283
+ }
284
+ const key = `${sha}|${slug}`;
285
+ if (seen.has(key))
286
+ continue; // the same commit reachable from two clones
287
+ seen.add(key);
288
+ events.push({ source: "git", person, slug, ts, durationMin: null });
289
+ }
290
+ });
291
+ if (registryPath) {
292
+ try {
293
+ const { stdout } = await exec("git", [
294
+ "-C",
295
+ registryPath,
296
+ "log",
297
+ "--all",
298
+ "--name-only",
299
+ format,
300
+ ]);
301
+ let current = null;
302
+ for (const line of stdout.split("\n")) {
303
+ if (line.startsWith("@@")) {
304
+ const [, email = "", iso = ""] = line.slice(2).split("|");
305
+ const ts = Date.parse(iso);
306
+ if (!inWindow(ts)) {
307
+ current = null;
308
+ continue;
309
+ }
310
+ const person = matchPerson(email);
311
+ if (!person)
312
+ noteUnmapped(email);
313
+ current = { person, ts, slugs: new Set() };
314
+ continue;
315
+ }
316
+ const match = /^clients\/([^/]+)\//.exec(line);
317
+ const slug = match?.[1];
318
+ if (!current?.person || !slug || !buildSlugs.has(slug) || current.slugs.has(slug))
319
+ continue;
320
+ current.slugs.add(slug);
321
+ events.push({
322
+ source: "git",
323
+ person: current.person,
324
+ slug,
325
+ ts: current.ts,
326
+ durationMin: null,
327
+ });
328
+ }
329
+ }
330
+ catch (error) {
331
+ fetchFailures.push(`team-clients: git log failed (${error instanceof Error ? error.message.split("\n")[0] : error})`);
332
+ }
333
+ }
334
+ return { events, unmappedByDomain, fetchFailures };
335
+ }
336
+ // ---------- Linear ----------
337
+ const LEDGER_ISSUES_QUERY = `
338
+ query LedgerIssues($projectId: ID!, $after: String) {
339
+ issues(filter: { project: { id: { eq: $projectId } } }, first: 50, after: $after) {
340
+ pageInfo { hasNextPage endCursor }
341
+ nodes {
342
+ id
343
+ createdAt
344
+ startedAt
345
+ completedAt
346
+ creator { email }
347
+ assignee { email }
348
+ comments(first: 50) {
349
+ pageInfo { hasNextPage endCursor }
350
+ nodes { createdAt user { email } }
351
+ }
352
+ }
353
+ }
354
+ }
355
+ `;
356
+ const LEDGER_COMMENTS_QUERY = `
357
+ query LedgerComments($issueId: String!, $after: String) {
358
+ issue(id: $issueId) {
359
+ comments(first: 100, after: $after) {
360
+ pageInfo { hasNextPage endCursor }
361
+ nodes { createdAt user { email } }
362
+ }
363
+ }
364
+ }
365
+ `;
366
+ async function linearEvents(fetchImpl, token, workspaceRoot, buildSlugs, window, matchPerson) {
367
+ const events = [];
368
+ const noProject = [];
369
+ const failures = [];
370
+ const unmappedByDomain = {};
371
+ const push = (slug, email, iso) => {
372
+ if (!iso)
373
+ return;
374
+ const ts = Date.parse(iso);
375
+ if (Number.isNaN(ts) || ts < window.sinceMs || ts > window.untilMs)
376
+ return;
377
+ const person = matchPerson(email);
378
+ if (!person) {
379
+ const domain = email?.split("@")[1] ?? "no email";
380
+ unmappedByDomain[domain] = (unmappedByDomain[domain] ?? 0) + 1;
381
+ return;
382
+ }
383
+ events.push({ source: "linear", person, slug, ts, durationMin: null });
384
+ };
385
+ await mapLimit(buildSlugs, 3, async (slug) => {
386
+ const clientMdPath = join(workspaceRoot, "clients", `client-${slug}`, "CLIENT.md");
387
+ const url = existsSync(clientMdPath)
388
+ ? LINEAR_PROJECT_FIELD_PATTERN.exec(readFileSync(clientMdPath, "utf8"))?.[1]
389
+ : undefined;
390
+ const slugId = url?.startsWith("http") ? parseLinearProjectSlugId(url) : undefined;
391
+ if (!slugId) {
392
+ noProject.push(slug);
393
+ return;
394
+ }
395
+ try {
396
+ const project = await findProjectBySlugId(fetchImpl, token, slugId);
397
+ let after = null;
398
+ do {
399
+ const page = await linearRequest(fetchImpl, token, LEDGER_ISSUES_QUERY, {
400
+ projectId: project.id,
401
+ after,
402
+ });
403
+ for (const issue of page.issues.nodes) {
404
+ push(slug, issue.creator?.email, issue.createdAt);
405
+ push(slug, issue.assignee?.email, issue.startedAt);
406
+ push(slug, issue.assignee?.email, issue.completedAt);
407
+ for (const comment of issue.comments.nodes)
408
+ push(slug, comment.user?.email, comment.createdAt);
409
+ let commentCursor = issue.comments.pageInfo.hasNextPage
410
+ ? issue.comments.pageInfo.endCursor
411
+ : null;
412
+ while (commentCursor) {
413
+ const more = await linearRequest(fetchImpl, token, LEDGER_COMMENTS_QUERY, {
414
+ issueId: issue.id,
415
+ after: commentCursor,
416
+ });
417
+ for (const comment of more.issue.comments.nodes) {
418
+ push(slug, comment.user?.email, comment.createdAt);
419
+ }
420
+ commentCursor = more.issue.comments.pageInfo.hasNextPage
421
+ ? more.issue.comments.pageInfo.endCursor
422
+ : null;
423
+ }
424
+ }
425
+ after = page.issues.pageInfo.hasNextPage ? page.issues.pageInfo.endCursor : null;
426
+ } while (after);
427
+ }
428
+ catch (error) {
429
+ const message = error instanceof Error ? error.message : String(error);
430
+ if (/rejected/.test(message))
431
+ throw error; // a bad key is fatal, not per-project
432
+ failures.push(`${slug}: ${message}`);
433
+ }
434
+ });
435
+ return { events, unmappedByDomain, noProject: noProject.sort(), failures };
436
+ }
437
+ function storePath(ledgerDir, person) {
438
+ return join(ledgerDir, "claude", `${person.toLowerCase()}.json`);
439
+ }
440
+ function loadStore(ledgerDir, person) {
441
+ const path = storePath(ledgerDir, person);
442
+ if (!existsSync(path))
443
+ return { schema: CLAUDE_STORE_SCHEMA, person, minutes: {}, coverage: [] };
444
+ return readJson(path);
445
+ }
446
+ /**
447
+ * Replace the store's minutes inside the export's range with the export's
448
+ * minutes, and keep every minute outside it — so older history survives
449
+ * Claude Code's own log cleanup, and a re-export with a fixed method replaces
450
+ * what it covers instead of piling up next to it.
451
+ */
452
+ function mergeExport(store, exported, file, nowIso) {
453
+ if (!exported.events.first)
454
+ return null;
455
+ const fromMinute = minuteOf(Date.parse(exported.events.first));
456
+ const toMs = exported.windowUntil
457
+ ? parseLedgerDate(exported.windowUntil, "windowUntil") + DAY_MS - 1
458
+ : Date.parse(exported.generatedAt);
459
+ const toMinute = minuteOf(toMs);
460
+ const merged = {};
461
+ const slugs = new Set([...Object.keys(store.minutes), ...Object.keys(exported.minutes)]);
462
+ let added = 0;
463
+ for (const slug of slugs) {
464
+ const kept = (store.minutes[slug] ?? []).filter((minute) => {
465
+ const m = minuteOf(parseMinuteIso(minute));
466
+ return m < fromMinute || m > toMinute;
467
+ });
468
+ const fresh = exported.minutes[slug] ?? [];
469
+ added += fresh.length;
470
+ const all = [...new Set([...kept, ...fresh])].sort();
471
+ if (all.length > 0)
472
+ merged[slug] = all;
473
+ }
474
+ store.minutes = merged;
475
+ const from = new Date(fromMinute * 60_000).toISOString();
476
+ const to = new Date(toMs).toISOString();
477
+ store.coverage.push({ from, to, file, ingestedAt: nowIso, schema: exported.schema });
478
+ return { person: store.person, file, from, to, minutes: added };
479
+ }
480
+ /**
481
+ * Stored minutes no current-schema export has covered: they came from an
482
+ * older export that also counted Claude running on its own (loops, wake-ups,
483
+ * background tasks), and the logs that could correct them are gone. Kept and
484
+ * counted, but named so nobody mistakes them for checked time.
485
+ */
486
+ function notCorrected(store, window) {
487
+ const checked = store.coverage
488
+ .filter((range) => range.schema === HOURS_EXPORT_SCHEMA)
489
+ .map((range) => ({ from: Date.parse(range.from), to: Date.parse(range.to) }));
490
+ let first = null;
491
+ let last = null;
492
+ let count = 0;
493
+ for (const list of Object.values(store.minutes)) {
494
+ for (const minute of list) {
495
+ const ms = parseMinuteIso(minute);
496
+ if (ms < window.sinceMs || ms > window.untilMs)
497
+ continue;
498
+ if (checked.some((range) => ms >= range.from && ms <= range.to))
499
+ continue;
500
+ count += 1;
501
+ if (first === null || ms < first)
502
+ first = ms;
503
+ if (last === null || ms > last)
504
+ last = ms;
505
+ }
506
+ }
507
+ if (first === null || last === null)
508
+ return null;
509
+ return [ledgerDay(first), ledgerDay(last), count];
510
+ }
511
+ // ---------- frozen CSV sources ----------
512
+ /** Minimal RFC 4180 reader — the frozen files come from Python's csv writer. */
513
+ function parseCsv(text) {
514
+ const rows = [];
515
+ let row = [];
516
+ let field = "";
517
+ let quoted = false;
518
+ for (let i = 0; i < text.length; i += 1) {
519
+ const ch = text[i];
520
+ if (quoted) {
521
+ if (ch === '"' && text[i + 1] === '"') {
522
+ field += '"';
523
+ i += 1;
524
+ }
525
+ else if (ch === '"') {
526
+ quoted = false;
527
+ }
528
+ else {
529
+ field += ch;
530
+ }
531
+ }
532
+ else if (ch === '"') {
533
+ quoted = true;
534
+ }
535
+ else if (ch === ",") {
536
+ row.push(field);
537
+ field = "";
538
+ }
539
+ else if (ch === "\n" || ch === "\r") {
540
+ if (ch === "\r" && text[i + 1] === "\n")
541
+ i += 1;
542
+ row.push(field);
543
+ if (row.some((value) => value !== ""))
544
+ rows.push(row);
545
+ row = [];
546
+ field = "";
547
+ }
548
+ else {
549
+ field += ch;
550
+ }
551
+ }
552
+ row.push(field);
553
+ if (row.some((value) => value !== ""))
554
+ rows.push(row);
555
+ return rows;
556
+ }
557
+ function frozenEvents(ledgerDir, config, nowMs, warnings) {
558
+ const dir = join(ledgerDir, "frozen");
559
+ if (!existsSync(dir))
560
+ return [];
561
+ const events = [];
562
+ for (const file of readdirSync(dir)
563
+ .filter((name) => name.endsWith(".csv"))
564
+ .sort()) {
565
+ const [header, ...rows] = parseCsv(readFileSync(join(dir, file), "utf8"));
566
+ const col = (name) => header?.indexOf(name) ?? -1;
567
+ const [iSource, iPerson, iSlug, iTs, iDur] = [
568
+ col("source"),
569
+ col("person"),
570
+ col("client_slug"),
571
+ col("ts_utc"),
572
+ col("duration_min"),
573
+ ];
574
+ if ([iSource, iPerson, iSlug, iTs].some((index) => index < 0)) {
575
+ warnings.push(`frozen/${file}: not a ledger CSV (needs source,person,client_slug,ts_utc) — skipped`);
576
+ continue;
577
+ }
578
+ for (const row of rows) {
579
+ const source = row[iSource];
580
+ const person = normalizePerson(config, row[iPerson] ?? "");
581
+ const ts = Date.parse(row[iTs] ?? "");
582
+ if (!HOURS_SOURCES.includes(source) || !person || Number.isNaN(ts))
583
+ continue;
584
+ if (source === "call" && ts > nowMs)
585
+ continue; // a scheduled call that has not happened
586
+ const dur = iDur >= 0 && row[iDur] ? Number.parseFloat(row[iDur] ?? "") : Number.NaN;
587
+ events.push({
588
+ source,
589
+ person,
590
+ slug: (row[iSlug] ?? "").trim().toLowerCase(),
591
+ ts,
592
+ durationMin: Number.isNaN(dur) ? null : Math.trunc(dur),
593
+ });
594
+ }
595
+ }
596
+ return events;
597
+ }
598
+ // ---------- build ----------
599
+ /**
600
+ * Rebuild the hours ledger's data: every source, the ledger's rules, hours
601
+ * and dates only. Reads git, Linear and Airtable; writes only inside the
602
+ * ledger dir (the Claude store and the output file).
603
+ */
604
+ export async function buildHoursLedger(options = {}) {
605
+ const env = options.env ?? process.env;
606
+ const home = options.homeDir ?? homedir();
607
+ const now = (options.now ?? (() => new Date()))();
608
+ const nowMs = now.getTime();
609
+ const fetchImpl = options.fetchImpl ?? fetch;
610
+ const exec = options.execFileImpl ?? defaultGitExec;
611
+ const warnings = [];
612
+ const ledgerDir = expandHome(options.ledgerDir ?? join(home, DEFAULT_HOURS_LEDGER_DIR), home);
613
+ // Owner-only: the store holds everyone's activity minutes.
614
+ for (const sub of ["", "inbox", "frozen", "claude", "out"]) {
615
+ mkdirSync(join(ledgerDir, sub), { recursive: true, mode: 0o700 });
616
+ }
617
+ const config = loadConfig(ledgerDir);
618
+ const people = Object.keys(config.people);
619
+ const matchPerson = personMatcher(config);
620
+ const workspaceRoot = options.workspaceRoot ?? findWorkspaceRoot();
621
+ if (!workspaceRoot) {
622
+ throw new Error("Run this inside the installagent workspace, or pass --workspace <path>.");
623
+ }
624
+ const since = options.since ?? LEDGER_WINDOW_START;
625
+ const sinceMs = parseLedgerDate(since, "--since");
626
+ const untilMs = options.until ? parseLedgerDate(options.until, "--until") + DAY_MS - 1 : nowMs;
627
+ if (sinceMs > untilMs)
628
+ throw new Error(`--since (${since}) is after --until (${options.until})`);
629
+ const linearToken = env[LINEAR_API_TOKEN_ENV];
630
+ const airtableToken = env[AIRTABLE_API_TOKEN_ENV];
631
+ const missing = [
632
+ ...(linearToken ? [] : [LINEAR_API_TOKEN_ENV]),
633
+ ...(airtableToken ? [] : [AIRTABLE_API_TOKEN_ENV]),
634
+ ];
635
+ if (missing.length > 0) {
636
+ throw new Error(`${missing.join(" and ")} must be set (the workspace .env, via \`ia env fill\`).`);
637
+ }
638
+ const generated = ledgerDay(nowMs);
639
+ const outPath = options.out
640
+ ? expandHome(options.out, home)
641
+ : join(ledgerDir, "out", `ledger-data-${generated}.json`);
642
+ if (existsSync(outPath) && !options.force) {
643
+ throw new Error(`${outPath} already exists — pass --force to overwrite, or --out <path>`);
644
+ }
645
+ const clientsDir = join(workspaceRoot, "clients");
646
+ const buildSlugs = readdirSync(clientsDir, { withFileTypes: true })
647
+ .filter((entry) => entry.isDirectory() && entry.name.startsWith("client-"))
648
+ .map((entry) => entry.name.slice("client-".length))
649
+ .filter((slug) => slug !== "template")
650
+ .sort();
651
+ const buildSlugSet = new Set(buildSlugs);
652
+ const repos = [
653
+ ...buildSlugs.map((slug) => ({ slug, path: join(clientsDir, `client-${slug}`) })),
654
+ ...(config.extraRepos ?? [])
655
+ .map((repo) => ({ slug: repo.slug, path: expandHome(repo.path, home) }))
656
+ .filter((repo) => {
657
+ if (existsSync(repo.path))
658
+ return true;
659
+ warnings.push(`extra repo for ${repo.slug} not found: ${repo.path}`);
660
+ return false;
661
+ }),
662
+ ];
663
+ const registryPath = existsSync(join(workspaceRoot, "team-clients", ".git"))
664
+ ? join(workspaceRoot, "team-clients")
665
+ : null;
666
+ if (!registryPath)
667
+ warnings.push("team-clients is not cloned here — registry commits are missing");
668
+ // Claude Code: ingest new exports into the cumulative store, then read the store.
669
+ const ingested = [];
670
+ const stores = new Map();
671
+ const storeFor = (person) => {
672
+ let store = stores.get(person);
673
+ if (!store) {
674
+ store = loadStore(ledgerDir, person);
675
+ stores.set(person, store);
676
+ }
677
+ return store;
678
+ };
679
+ const ingest = (exported, file) => {
680
+ if (exported.schema !== HOURS_EXPORT_SCHEMA) {
681
+ warnings.push(`${basename(file)} was made by an older \`ia hours-export\` (${exported.schema ?? "no schema"}, ` +
682
+ `which counts Claude running on its own as work) — skipped; ask ` +
683
+ `${exported.person ?? "its sender"} to update team-tools and run it again`);
684
+ return;
685
+ }
686
+ const person = normalizePerson(config, exported.person);
687
+ if (!person) {
688
+ warnings.push(`${basename(file)}: "${exported.person}" is not a person in the ledger config — skipped`);
689
+ return;
690
+ }
691
+ const merged = mergeExport(storeFor(person), exported, file, now.toISOString());
692
+ if (merged)
693
+ ingested.push(merged);
694
+ };
695
+ if (options.self) {
696
+ const person = normalizePerson(config, options.self);
697
+ if (!person)
698
+ throw new Error(`--self "${options.self}" is not a person in the ledger config`);
699
+ const exported = await (options.exportClaude ?? exportClaudeHours)({
700
+ person,
701
+ workspaceRoot,
702
+ env,
703
+ homeDir: home,
704
+ now: () => now,
705
+ });
706
+ ingest(exported, `this machine (${exported.configDirsUsed.length} config dir(s))`);
707
+ if (exported.configDirsUsed.length === 0) {
708
+ warnings.push(`no Claude Code data found on this machine (checked $${CLAUDE_CONFIG_DIR_ENV}, ~/.claude-installagent, ~/.claude)`);
709
+ }
710
+ }
711
+ const inboxDir = join(ledgerDir, "inbox");
712
+ const exportFiles = [
713
+ ...readdirSync(inboxDir)
714
+ .filter((name) => name.endsWith(".json"))
715
+ .sort()
716
+ .map((name) => join(inboxDir, name)),
717
+ ...(options.claudeExports ?? []).map((file) => expandHome(file, home)),
718
+ ];
719
+ for (const file of exportFiles) {
720
+ try {
721
+ ingest(readJson(file), file);
722
+ }
723
+ catch (error) {
724
+ warnings.push(`${basename(file)}: not readable as an export (${error instanceof Error ? error.message : error})`);
725
+ }
726
+ }
727
+ for (const store of stores.values()) {
728
+ writeFileSync(storePath(ledgerDir, store.person), `${JSON.stringify(store)}\n`);
729
+ }
730
+ const claudeEvents = [];
731
+ for (const person of people) {
732
+ const store = storeFor(person);
733
+ for (const [slug, minutes] of Object.entries(store.minutes)) {
734
+ for (const minute of minutes) {
735
+ claudeEvents.push({
736
+ source: "claude",
737
+ person,
738
+ slug,
739
+ ts: parseMinuteIso(minute),
740
+ durationMin: null,
741
+ });
742
+ }
743
+ }
744
+ }
745
+ const claudeNotCorrected = {};
746
+ for (const person of people) {
747
+ const range = notCorrected(storeFor(person), { sinceMs, untilMs });
748
+ if (range)
749
+ claudeNotCorrected[person] = range;
750
+ }
751
+ log.debug("sources-start", { repos: repos.length, buildSlugs: buildSlugs.length });
752
+ const [crm, git, linear] = await Promise.all([
753
+ loadCrm(fetchImpl, airtableToken, matchPerson),
754
+ gitEvents(exec, repos, registryPath, buildSlugSet, { sinceMs, untilMs }, options.fetch !== false, (email) => matchPerson(email)),
755
+ linearEvents(fetchImpl, linearToken, workspaceRoot, buildSlugs, { sinceMs, untilMs }, matchPerson),
756
+ ]);
757
+ const frozen = frozenEvents(ledgerDir, config, nowMs, warnings);
758
+ // Keep a slug when it is an engagement in the CRM or has a build repo; else it's a lead.
759
+ const keepSlug = (slug) => slug === UNATTRIBUTED_SLUG || buildSlugSet.has(slug) || crm.get(slug)?.engaged
760
+ ? slug
761
+ : OTHER_LEAD_SLUG;
762
+ const events = [...git.events, ...linear.events, ...claudeEvents, ...frozen]
763
+ .filter((event) => !Number.isNaN(event.ts) && event.ts >= sinceMs && event.ts <= untilMs)
764
+ .map((event) => ({ ...event, slug: keepSlug(event.slug) }));
765
+ const techStart = (slug) => {
766
+ const client = crm.get(slug);
767
+ return client?.engaged ? client.techStart : null;
768
+ };
769
+ const combined = estimateHours(events, { techStart });
770
+ const presentSources = HOURS_SOURCES.filter((source) => events.some((e) => e.source === source));
771
+ const bySource = new Map(presentSources.map((source) => [
772
+ source,
773
+ estimateHours(events, { sources: new Set([source]) }).hours,
774
+ ]));
775
+ const counts = {};
776
+ for (const event of events) {
777
+ const personCounts = counts[event.person] ?? {};
778
+ const slugCounts = personCounts[event.slug] ?? {};
779
+ slugCounts[event.source] = (slugCounts[event.source] ?? 0) + 1;
780
+ personCounts[event.slug] = slugCounts;
781
+ counts[event.person] = personCounts;
782
+ }
783
+ const rows = [];
784
+ for (const person of people) {
785
+ const own = [...crm.values()]
786
+ .filter((client) => client.engaged && client.tech === person && client.techStart)
787
+ .map((client) => client.slug);
788
+ const slugs = new Set([
789
+ ...Object.keys(combined.hours[person] ?? {}),
790
+ ...Object.keys(counts[person] ?? {}),
791
+ ...own,
792
+ ]);
793
+ for (const slug of [...slugs].sort()) {
794
+ const { byMonth, total } = roundMonths(combined.hours[person]?.[slug]);
795
+ const client = crm.get(slug);
796
+ const engaged = client?.engaged ? client : null;
797
+ const hoursBySource = {};
798
+ for (const source of presentSources) {
799
+ const months = bySource.get(source)?.[person]?.[slug] ?? {};
800
+ hoursBySource[source] = round2(Object.values(months).reduce((sum, v) => sum + v, 0));
801
+ }
802
+ rows.push({
803
+ person,
804
+ slug,
805
+ client: registryName(workspaceRoot, slug) ?? slug,
806
+ crm_tech: engaged?.tech ?? null,
807
+ is_technician: engaged?.tech === person,
808
+ status: client?.status ?? null,
809
+ tech_start: engaged?.techStart ?? null,
810
+ hours_by_month: byMonth,
811
+ hours_total: total,
812
+ hours_before_start: round2(combined.beforeStart[person]?.[slug] ?? 0),
813
+ hours_by_source: hoursBySource,
814
+ event_counts: counts[person]?.[slug] ?? {},
815
+ });
816
+ }
817
+ }
818
+ const sourceRanges = {};
819
+ const spans = new Map();
820
+ let firstTs = null;
821
+ for (const event of events) {
822
+ const key = `${event.source}|${event.person}`;
823
+ const span = spans.get(key) ?? { first: event.ts, last: event.ts, count: 0 };
824
+ span.first = Math.min(span.first, event.ts);
825
+ span.last = Math.max(span.last, event.ts);
826
+ span.count += 1;
827
+ spans.set(key, span);
828
+ if (firstTs === null || event.ts < firstTs)
829
+ firstTs = event.ts;
830
+ }
831
+ for (const source of presentSources) {
832
+ for (const person of people) {
833
+ const span = spans.get(`${source}|${person}`);
834
+ if (!span)
835
+ continue;
836
+ const range = sourceRanges[source] ?? {};
837
+ range[person] = [ledgerDay(span.first), ledgerDay(span.last), span.count];
838
+ sourceRanges[source] = range;
839
+ }
840
+ }
841
+ const claudeThrough = {};
842
+ for (const [person, range] of Object.entries(sourceRanges.claude ?? {}))
843
+ claudeThrough[person] = range[1];
844
+ // A source that only ever comes from frozen files — the page says how old it is.
845
+ const liveSources = new Set(["git", "linear", "claude"]);
846
+ const frozenSources = {};
847
+ for (const event of frozen) {
848
+ if (liveSources.has(event.source))
849
+ continue;
850
+ const day = ledgerDay(event.ts);
851
+ if (!frozenSources[event.source] || day > (frozenSources[event.source] ?? "")) {
852
+ frozenSources[event.source] = day;
853
+ }
854
+ }
855
+ const data = {
856
+ schema: HOURS_LEDGER_SCHEMA,
857
+ generated,
858
+ window_start: since,
859
+ window_end: options.until ?? generated,
860
+ people,
861
+ claude_missing: people.filter((person) => !claudeThrough[person]),
862
+ claude_through: claudeThrough,
863
+ claude_not_corrected: claudeNotCorrected,
864
+ frozen_sources: frozenSources,
865
+ first_event: firstTs === null ? null : ledgerDay(firstTs),
866
+ rules: {
867
+ gap_min: SESSION_GAP_MINUTES,
868
+ lead_heavy_min: LEAD_HEAVY_MINUTES,
869
+ lead_light_min: LEAD_LIGHT_MINUTES,
870
+ prompt_window_min: PROMPT_WINDOW_MINUTES,
871
+ time_zone: LEDGER_TIME_ZONE,
872
+ },
873
+ source_ranges: sourceRanges,
874
+ rows,
875
+ };
876
+ writeFileSync(outPath, `${JSON.stringify(data, null, 1)}\n`);
877
+ // Warnings a person should act on before trusting the numbers.
878
+ if (git.fetchFailures.length)
879
+ warnings.push(`git: ${git.fetchFailures.join("; ")}`);
880
+ const byDomain = (counts) => Object.entries(counts)
881
+ .sort((a, b) => b[1] - a[1])
882
+ .map(([domain, n]) => `${domain} ×${n}`)
883
+ .join(", ");
884
+ if (Object.keys(git.unmappedByDomain).length) {
885
+ warnings.push(`git: skipped commits by authors outside the config (${byDomain(git.unmappedByDomain)}) — ` +
886
+ "bots and client developers are expected here; a teammate is not");
887
+ }
888
+ if (linear.noProject.length) {
889
+ warnings.push(`linear: no linear_project in CLIENT.md for ${linear.noProject.join(", ")}`);
890
+ }
891
+ if (linear.failures.length)
892
+ warnings.push(`linear: ${linear.failures.join("; ")}`);
893
+ if (Object.keys(linear.unmappedByDomain).length) {
894
+ warnings.push(`linear: skipped events by people outside the config (${byDomain(linear.unmappedByDomain)})`);
895
+ }
896
+ if (data.claude_missing.length) {
897
+ warnings.push(`claude: no Claude Code data yet for ${data.claude_missing.join(", ")} — they run ` +
898
+ `\`ia hours-export --person <Name>\` and send the file; drop it in ${inboxDir}`);
899
+ }
900
+ for (const [person, [from, to, minutes]] of Object.entries(claudeNotCorrected)) {
901
+ warnings.push(`claude: ${person}'s ${minutes} minute(s) from ${from} to ${to} come from an older export ` +
902
+ "that also counted Claude running on its own — kept, not corrected (those logs are gone)");
903
+ }
904
+ for (const [person, day] of Object.entries(claudeThrough)) {
905
+ if (Date.parse(`${generated}T12:00:00Z`) - Date.parse(`${day}T12:00:00Z`) >
906
+ STALE_CLAUDE_DAYS * DAY_MS) {
907
+ warnings.push(`claude: ${person}'s data ends ${day} — ask for a fresh export (Claude Code deletes logs after ~30 days)`);
908
+ }
909
+ }
910
+ const totals = people.map((person) => {
911
+ const personRows = rows.filter((row) => row.person === person);
912
+ const sum = (list) => round2(list.reduce((acc, row) => acc + row.hours_total, 0));
913
+ const perSource = {};
914
+ for (const source of presentSources) {
915
+ perSource[source] = round2(personRows.reduce((acc, row) => acc + (row.hours_by_source[source] ?? 0), 0));
916
+ }
917
+ return {
918
+ person,
919
+ ownClients: sum(personRows.filter((row) => row.is_technician)),
920
+ helping: sum(personRows.filter((row) => !row.is_technician && row.slug !== UNATTRIBUTED_SLUG)),
921
+ unattributed: sum(personRows.filter((row) => row.slug === UNATTRIBUTED_SLUG)),
922
+ bySource: perSource,
923
+ };
924
+ });
925
+ return { outPath, ledgerDir, data, ingested, totals, warnings };
926
+ }