@installagent/sdk 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-mirror.d.ts +69 -0
- package/dist/agent-mirror.js +275 -0
- package/dist/claude-hours.d.ts +118 -0
- package/dist/claude-hours.js +523 -0
- package/dist/client-drive.d.ts +3 -0
- package/dist/client-drive.js +2 -2
- package/dist/env-fill.js +21 -4
- package/dist/env-registry.d.ts +4 -0
- package/dist/env-registry.js +54 -2
- package/dist/git.d.ts +31 -0
- package/dist/git.js +59 -0
- package/dist/google-service-account.d.ts +20 -0
- package/dist/google-service-account.js +49 -0
- package/dist/hours-estimate.d.ts +43 -0
- package/dist/hours-estimate.js +159 -0
- package/dist/hours-export-schedule.d.ts +35 -0
- package/dist/hours-export-schedule.js +188 -0
- package/dist/hours-ledger.d.ts +129 -0
- package/dist/hours-ledger.js +882 -0
- package/dist/index.d.ts +13 -2
- package/dist/index.js +13 -2
- package/dist/portal-admin.d.ts +68 -0
- package/dist/portal-admin.js +64 -1
- package/dist/sync-repos.d.ts +7 -0
- package/dist/sync-repos.js +10 -1
- package/dist/template-sync.d.ts +10 -9
- package/dist/template-sync.js +14 -9
- package/dist/triage-backfill.d.ts +37 -0
- package/dist/triage-backfill.js +211 -0
- package/dist/triage-enable.d.ts +90 -0
- package/dist/triage-enable.js +428 -0
- package/dist/triage-gates.d.ts +252 -0
- package/dist/triage-gates.js +951 -0
- package/dist/workspace-push.d.ts +39 -0
- package/dist/workspace-push.js +78 -0
- package/dist/workspace-status.d.ts +37 -0
- package/dist/workspace-status.js +114 -0
- package/package.json +1 -1
- package/templates/env.example +6 -2
- package/templates/workspace-root/.claude/settings.json +12 -1
- package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +53 -28
- package/templates/workspace-root/skills/CLAUDE.md +6 -1
- package/templates/workspace-root/skills/README.md +17 -2
- package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
- package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
- package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
- package/templates/workspace-root/skills/client-latest/SKILL.md +124 -82
- package/templates/workspace-root/skills/client-latest/catchup.command.md +5 -4
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +90 -13
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
- package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
- package/templates/workspace-root/skills/ia-cli/SKILL.md +30 -1
- package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { type ExecFileFn } from "./exec.js";
|
|
2
|
+
export type MirrorState =
|
|
3
|
+
/** Export and live workflow are joined, and the export is at least as new. */
|
|
4
|
+
"tracked"
|
|
5
|
+
/** Joined, but the instance changed after this file was last committed. Diff them. */
|
|
6
|
+
| "needs-diff"
|
|
7
|
+
/** Live on the instance, in no client repo. */
|
|
8
|
+
| "not-exported"
|
|
9
|
+
/** In a client repo, no live workflow matched. Archived or deleted — the API cannot say which. */
|
|
10
|
+
| "no-live-match";
|
|
11
|
+
export interface MirrorRow {
|
|
12
|
+
/** Client slug, when the row came from (or matched) a client repo. */
|
|
13
|
+
client: string | null;
|
|
14
|
+
/** Path relative to the workspace root, when there is an export. */
|
|
15
|
+
file: string | null;
|
|
16
|
+
/** Live n8n id, when known — from the export's own record or the live list. */
|
|
17
|
+
workflowId: string | null;
|
|
18
|
+
workflowName: string;
|
|
19
|
+
state: MirrorState;
|
|
20
|
+
/** How the export was joined to the live workflow. `null` when unjoined. */
|
|
21
|
+
matchedBy: "id" | "name" | null;
|
|
22
|
+
liveUpdatedAt: string | null;
|
|
23
|
+
liveActive: boolean | null;
|
|
24
|
+
/** True when the live workflow is archived in n8n. Archived is not deleted. */
|
|
25
|
+
liveArchived: boolean | null;
|
|
26
|
+
/** The export's last commit time (ISO), or null outside a git checkout. */
|
|
27
|
+
exportedAt: string | null;
|
|
28
|
+
hint: string;
|
|
29
|
+
}
|
|
30
|
+
export interface MirrorSummary {
|
|
31
|
+
liveWorkflows: number;
|
|
32
|
+
exports: number;
|
|
33
|
+
tracked: number;
|
|
34
|
+
needsDiff: number;
|
|
35
|
+
notExported: number;
|
|
36
|
+
noLiveMatch: number;
|
|
37
|
+
/** Exports joined by name because they record no id — the fragile joins. */
|
|
38
|
+
nameMatched: number;
|
|
39
|
+
}
|
|
40
|
+
export interface AgentMirrorResult {
|
|
41
|
+
workspaceDir: string;
|
|
42
|
+
summary: MirrorSummary;
|
|
43
|
+
rows: MirrorRow[];
|
|
44
|
+
/**
|
|
45
|
+
* False when `git log` produced no commit time for any export — outside a
|
|
46
|
+
* checkout, or with no git. `needs-diff` cannot be evaluated without it, so
|
|
47
|
+
* every joined row reads `tracked` and that is NOT evidence of being current.
|
|
48
|
+
*/
|
|
49
|
+
commitTimesAvailable: boolean;
|
|
50
|
+
notes: string[];
|
|
51
|
+
}
|
|
52
|
+
export interface AgentMirrorOptions {
|
|
53
|
+
/** The installagent/ workspace root (the dir that contains clients/). */
|
|
54
|
+
workspaceDir?: string;
|
|
55
|
+
/** Limit the check to one client slug (without the `client-` prefix). */
|
|
56
|
+
client?: string;
|
|
57
|
+
baseUrl?: string;
|
|
58
|
+
apiKey?: string;
|
|
59
|
+
env?: NodeJS.ProcessEnv;
|
|
60
|
+
fetchImpl?: typeof fetch;
|
|
61
|
+
/** Injectable for tests; defaults to real git via execFile. */
|
|
62
|
+
execFileImpl?: ExecFileFn;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Compare every n8n workflow against every client repo's exports. Read-only:
|
|
66
|
+
* it fetches the workflow list, reads files, and shells out to `git log`.
|
|
67
|
+
* It never writes, never touches the instance, and never exports anything.
|
|
68
|
+
*/
|
|
69
|
+
export declare function checkAgentMirror(opts?: AgentMirrorOptions): Promise<AgentMirrorResult>;
|
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
// Every n8n workflow a client build depends on is supposed to have a reviewed
|
|
2
|
+
// copy in that client's repo under workflows/*.json. Nothing enforced it, so
|
|
3
|
+
// the two drifted: a 2026-09-15 audit found one live workflow in no repo at
|
|
4
|
+
// all, and a probe that had been renamed on the instance while its export kept
|
|
5
|
+
// the old name. This module is the read-only check that finds both.
|
|
6
|
+
//
|
|
7
|
+
// Two lessons from that audit are load-bearing here, and both cost a wrong
|
|
8
|
+
// answer before they were learned:
|
|
9
|
+
//
|
|
10
|
+
// 1. A NEWER updatedAt IS NOT DRIFT. Deactivating a workflow bumps it
|
|
11
|
+
// without touching the definition. Two of the three exports flagged that
|
|
12
|
+
// day turned out to be byte-faithful. So this module never reports
|
|
13
|
+
// "stale" — it reports `needs-diff`, which means "open these two and
|
|
14
|
+
// compare", not "this file is wrong".
|
|
15
|
+
// 2. MATCH ON ID, NOT ON NAME. The renamed probe was reported as a deletion
|
|
16
|
+
// by a name-matched pass. Exports that record their live id get an exact
|
|
17
|
+
// join; the rest fall back to name and are labelled `matchedBy: "name"`
|
|
18
|
+
// so a reader knows the join is a guess.
|
|
19
|
+
//
|
|
20
|
+
// One more trap, and this one was got WRONG first and caught by this very
|
|
21
|
+
// module on its first real run. The n8n REST workflow list INCLUDES archived
|
|
22
|
+
// workflows (they come back with isArchived: true) — it is the n8n MCP
|
|
23
|
+
// search tool that hides them, returning 61 of 101. An audit built on that
|
|
24
|
+
// tool reported three live-but-archived exports as deleted. So: read
|
|
25
|
+
// isArchived from the list, say "archived" when it is set, and only then is
|
|
26
|
+
// an unmatched export genuinely absent.
|
|
27
|
+
import { readdir, readFile } from "node:fs/promises";
|
|
28
|
+
import { basename, join } from "node:path";
|
|
29
|
+
import { N8N_API_KEY_ENV, N8N_API_URL_ENV, N8nAuthError } from "./agent-templates.js";
|
|
30
|
+
import { execFileAsync } from "./exec.js";
|
|
31
|
+
/** n8n workflow ids are 16 chars of base62 — tight enough to find in prose. */
|
|
32
|
+
const N8N_ID = /\b[A-Za-z0-9]{16}\b/g;
|
|
33
|
+
/** Pull every n8n-shaped id out of a blob of text. */
|
|
34
|
+
function idsIn(text) {
|
|
35
|
+
return text.match(N8N_ID) ?? [];
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Did the instance change after the file was last committed?
|
|
39
|
+
*
|
|
40
|
+
* Compared as instants, never as strings. `git log --format=%cI` emits a local
|
|
41
|
+
* offset ("2026-09-11T13:52:11-04:00") while n8n emits UTC
|
|
42
|
+
* ("2026-09-11T17:50:32.202Z"). Lexically the first looks older; as instants it
|
|
43
|
+
* is 100 seconds NEWER. Comparing the strings made every single export on a
|
|
44
|
+
* real workspace report `needs-diff` — the exact cry-wolf this check exists to
|
|
45
|
+
* avoid. Unparseable on either side means "cannot tell", which is not drift.
|
|
46
|
+
*/
|
|
47
|
+
function instanceMovedAfterExport(liveUpdatedAt, exportedAt) {
|
|
48
|
+
if (liveUpdatedAt === null || exportedAt === null)
|
|
49
|
+
return false;
|
|
50
|
+
const live = Date.parse(liveUpdatedAt);
|
|
51
|
+
const exported = Date.parse(exportedAt);
|
|
52
|
+
if (Number.isNaN(live) || Number.isNaN(exported))
|
|
53
|
+
return false;
|
|
54
|
+
return live > exported;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* The live id an export claims, if any. Checked in order of how deliberate the
|
|
58
|
+
* record is: a real `id` field, then the prose fields repos use to note the
|
|
59
|
+
* live instance, then the `.md` sidecar sitting next to it.
|
|
60
|
+
*/
|
|
61
|
+
async function recordedIdFor(absPath, parsed, knownIds) {
|
|
62
|
+
const direct = typeof parsed.id === "string" ? parsed.id : null;
|
|
63
|
+
if (direct && knownIds.has(direct))
|
|
64
|
+
return direct;
|
|
65
|
+
const prose = [parsed._export_note, parsed.description]
|
|
66
|
+
.filter((v) => typeof v === "string")
|
|
67
|
+
.join(" ");
|
|
68
|
+
for (const candidate of idsIn(prose))
|
|
69
|
+
if (knownIds.has(candidate))
|
|
70
|
+
return candidate;
|
|
71
|
+
try {
|
|
72
|
+
const sidecar = await readFile(absPath.replace(/\.json$/, ".md"), "utf8");
|
|
73
|
+
for (const candidate of idsIn(sidecar))
|
|
74
|
+
if (knownIds.has(candidate))
|
|
75
|
+
return candidate;
|
|
76
|
+
}
|
|
77
|
+
catch {
|
|
78
|
+
// No sidecar is normal.
|
|
79
|
+
}
|
|
80
|
+
return null;
|
|
81
|
+
}
|
|
82
|
+
async function listExports(workspaceDir, only) {
|
|
83
|
+
const clientsDir = join(workspaceDir, "clients");
|
|
84
|
+
let entries = [];
|
|
85
|
+
try {
|
|
86
|
+
entries = await readdir(clientsDir);
|
|
87
|
+
}
|
|
88
|
+
catch {
|
|
89
|
+
return [];
|
|
90
|
+
}
|
|
91
|
+
const out = [];
|
|
92
|
+
for (const entry of entries.sort()) {
|
|
93
|
+
if (!entry.startsWith("client-") || entry === "client-template")
|
|
94
|
+
continue;
|
|
95
|
+
const slug = entry.slice("client-".length);
|
|
96
|
+
if (only && slug !== only)
|
|
97
|
+
continue;
|
|
98
|
+
const wfDir = join(clientsDir, entry, "workflows");
|
|
99
|
+
let files = [];
|
|
100
|
+
try {
|
|
101
|
+
files = await readdir(wfDir);
|
|
102
|
+
}
|
|
103
|
+
catch {
|
|
104
|
+
continue;
|
|
105
|
+
}
|
|
106
|
+
for (const file of files.sort()) {
|
|
107
|
+
if (!file.endsWith(".json"))
|
|
108
|
+
continue;
|
|
109
|
+
const absPath = join(wfDir, file);
|
|
110
|
+
let parsed;
|
|
111
|
+
try {
|
|
112
|
+
parsed = JSON.parse(await readFile(absPath, "utf8"));
|
|
113
|
+
}
|
|
114
|
+
catch {
|
|
115
|
+
continue; // An unparseable export is repo-lint's problem, not this check's.
|
|
116
|
+
}
|
|
117
|
+
out.push({
|
|
118
|
+
client: slug,
|
|
119
|
+
file: `clients/${entry}/workflows/${file}`,
|
|
120
|
+
absPath,
|
|
121
|
+
name: typeof parsed.name === "string" ? parsed.name : basename(file, ".json"),
|
|
122
|
+
parsed,
|
|
123
|
+
recordedId: null, // filled once the live ids are known
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
return out;
|
|
128
|
+
}
|
|
129
|
+
/** Last commit time of one file, ISO, or null outside a checkout. */
|
|
130
|
+
async function lastCommitIso(repoDir, relPath, execFileImpl) {
|
|
131
|
+
try {
|
|
132
|
+
const { stdout } = await execFileImpl("git", [
|
|
133
|
+
"-C",
|
|
134
|
+
repoDir,
|
|
135
|
+
"log",
|
|
136
|
+
"-1",
|
|
137
|
+
"--format=%cI",
|
|
138
|
+
"--",
|
|
139
|
+
relPath,
|
|
140
|
+
]);
|
|
141
|
+
const value = stdout.trim();
|
|
142
|
+
return value || null;
|
|
143
|
+
}
|
|
144
|
+
catch {
|
|
145
|
+
return null;
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Compare every n8n workflow against every client repo's exports. Read-only:
|
|
150
|
+
* it fetches the workflow list, reads files, and shells out to `git log`.
|
|
151
|
+
* It never writes, never touches the instance, and never exports anything.
|
|
152
|
+
*/
|
|
153
|
+
export async function checkAgentMirror(opts = {}) {
|
|
154
|
+
const workspaceDir = opts.workspaceDir ?? ".";
|
|
155
|
+
const env = opts.env ?? process.env;
|
|
156
|
+
const baseUrl = (opts.baseUrl ?? env[N8N_API_URL_ENV])?.replace(/\/+$/, "");
|
|
157
|
+
const apiKey = opts.apiKey ?? env[N8N_API_KEY_ENV];
|
|
158
|
+
if (!baseUrl || !apiKey) {
|
|
159
|
+
throw new N8nAuthError(`n8n API not configured — set $${N8N_API_URL_ENV} (incl. /api/v1) and $${N8N_API_KEY_ENV} (1Password).`);
|
|
160
|
+
}
|
|
161
|
+
const fetchImpl = opts.fetchImpl ?? fetch;
|
|
162
|
+
const execFileImpl = opts.execFileImpl ?? execFileAsync;
|
|
163
|
+
const response = await fetchImpl(`${baseUrl}/workflows?limit=250`, {
|
|
164
|
+
headers: { "X-N8N-API-KEY": apiKey, accept: "application/json" },
|
|
165
|
+
});
|
|
166
|
+
if (!response.ok)
|
|
167
|
+
throw new Error(`n8n API ${response.status} listing workflows`);
|
|
168
|
+
const payload = (await response.json());
|
|
169
|
+
const live = (payload.data ?? []).map((w) => ({
|
|
170
|
+
id: String(w.id ?? ""),
|
|
171
|
+
name: String(w.name ?? ""),
|
|
172
|
+
active: Boolean(w.active),
|
|
173
|
+
archived: Boolean(w.isArchived),
|
|
174
|
+
updatedAt: typeof w.updatedAt === "string" ? w.updatedAt : null,
|
|
175
|
+
}));
|
|
176
|
+
const knownIds = new Set(live.map((w) => w.id));
|
|
177
|
+
const exports = await listExports(workspaceDir, opts.client);
|
|
178
|
+
for (const exp of exports) {
|
|
179
|
+
exp.recordedId = await recordedIdFor(exp.absPath, exp.parsed, knownIds);
|
|
180
|
+
}
|
|
181
|
+
const byId = new Map(live.map((w) => [w.id, w]));
|
|
182
|
+
const byName = new Map();
|
|
183
|
+
for (const w of live)
|
|
184
|
+
if (!byName.has(w.name))
|
|
185
|
+
byName.set(w.name, w);
|
|
186
|
+
const rows = [];
|
|
187
|
+
const claimed = new Set();
|
|
188
|
+
for (const exp of exports) {
|
|
189
|
+
const viaId = exp.recordedId ? byId.get(exp.recordedId) : undefined;
|
|
190
|
+
const match = viaId ?? byName.get(exp.name);
|
|
191
|
+
const matchedBy = viaId ? "id" : match ? "name" : null;
|
|
192
|
+
if (match)
|
|
193
|
+
claimed.add(match.id);
|
|
194
|
+
const exportedAt = await lastCommitIso(join(workspaceDir, "clients", `client-${exp.client}`), exp.file.replace(`clients/client-${exp.client}/`, ""), execFileImpl);
|
|
195
|
+
if (!match) {
|
|
196
|
+
rows.push({
|
|
197
|
+
client: exp.client,
|
|
198
|
+
file: exp.file,
|
|
199
|
+
workflowId: exp.recordedId,
|
|
200
|
+
workflowName: exp.name,
|
|
201
|
+
state: "no-live-match",
|
|
202
|
+
matchedBy: null,
|
|
203
|
+
liveUpdatedAt: null,
|
|
204
|
+
liveActive: null,
|
|
205
|
+
liveArchived: null,
|
|
206
|
+
exportedAt,
|
|
207
|
+
hint: "No live workflow matched — not even an archived one, since the REST list includes those. Either it was deleted on the instance, or this export records a name/id that never existed. Confirm in the UI before removing the file; an export is cheap history.",
|
|
208
|
+
});
|
|
209
|
+
continue;
|
|
210
|
+
}
|
|
211
|
+
const moved = instanceMovedAfterExport(match.updatedAt, exportedAt);
|
|
212
|
+
rows.push({
|
|
213
|
+
client: exp.client,
|
|
214
|
+
file: exp.file,
|
|
215
|
+
workflowId: match.id,
|
|
216
|
+
workflowName: match.name,
|
|
217
|
+
state: moved ? "needs-diff" : "tracked",
|
|
218
|
+
matchedBy,
|
|
219
|
+
liveUpdatedAt: match.updatedAt,
|
|
220
|
+
liveActive: match.active,
|
|
221
|
+
liveArchived: match.archived,
|
|
222
|
+
exportedAt,
|
|
223
|
+
hint: moved
|
|
224
|
+
? "The instance changed after this file was last committed. That is a prompt to DIFF, not a verdict — deactivating a workflow bumps updatedAt without touching the definition."
|
|
225
|
+
: matchedBy === "name"
|
|
226
|
+
? "Joined by name only — this export records no live id, so a rename on the instance would read as a deletion. Record the id in the export or its .md sidecar."
|
|
227
|
+
: "Export is at least as new as the instance.",
|
|
228
|
+
});
|
|
229
|
+
}
|
|
230
|
+
// With --client we cannot attribute an unexported live workflow to anyone:
|
|
231
|
+
// nothing on a workflow says which client it belongs to. Listing them all
|
|
232
|
+
// under a single-client run would be noise, so they are left out.
|
|
233
|
+
for (const w of live) {
|
|
234
|
+
if (claimed.has(w.id) || opts.client)
|
|
235
|
+
continue;
|
|
236
|
+
rows.push({
|
|
237
|
+
client: null,
|
|
238
|
+
file: null,
|
|
239
|
+
workflowId: w.id,
|
|
240
|
+
workflowName: w.name,
|
|
241
|
+
state: "not-exported",
|
|
242
|
+
matchedBy: null,
|
|
243
|
+
liveUpdatedAt: w.updatedAt,
|
|
244
|
+
liveActive: w.active,
|
|
245
|
+
liveArchived: w.archived,
|
|
246
|
+
exportedAt: null,
|
|
247
|
+
hint: "Live on the instance, in no client repo. Team-level and one-off workflows are expected here; a client build workflow is not.",
|
|
248
|
+
});
|
|
249
|
+
}
|
|
250
|
+
const summary = {
|
|
251
|
+
liveWorkflows: live.length,
|
|
252
|
+
exports: exports.length,
|
|
253
|
+
tracked: rows.filter((r) => r.state === "tracked").length,
|
|
254
|
+
needsDiff: rows.filter((r) => r.state === "needs-diff").length,
|
|
255
|
+
notExported: rows.filter((r) => r.state === "not-exported").length,
|
|
256
|
+
noLiveMatch: rows.filter((r) => r.state === "no-live-match").length,
|
|
257
|
+
nameMatched: rows.filter((r) => r.matchedBy === "name").length,
|
|
258
|
+
};
|
|
259
|
+
const commitTimesAvailable = rows.some((r) => r.exportedAt !== null);
|
|
260
|
+
const notes = [
|
|
261
|
+
"Read-only: nothing on the n8n instance was read beyond the workflow list, and nothing was written anywhere.",
|
|
262
|
+
"`needs-diff` means open both and compare. It is never on its own a reason to re-export.",
|
|
263
|
+
"`no-live-match` means no live workflow at all, archived ones included — the REST list returns archived workflows with isArchived set, unlike the n8n MCP search tool, which hides them.",
|
|
264
|
+
];
|
|
265
|
+
if (exports.length > 0 && !commitTimesAvailable) {
|
|
266
|
+
notes.unshift("WARNING: no commit time could be read for any export (not a git checkout, or git is unavailable), so `needs-diff` was NOT evaluated. Every joined row reads `tracked` — that is the absence of a check, not a clean result.");
|
|
267
|
+
}
|
|
268
|
+
if (opts.client) {
|
|
269
|
+
notes.push(`Scoped to client "${opts.client}": live workflows with no export are NOT listed, because nothing on a workflow records which client it belongs to. Run without --client to see them.`);
|
|
270
|
+
}
|
|
271
|
+
if (summary.nameMatched > 0) {
|
|
272
|
+
notes.push(`${summary.nameMatched} export(s) joined by NAME because they record no live id. A rename on the instance would read as a deletion — record the id in the export or its .md sidecar.`);
|
|
273
|
+
}
|
|
274
|
+
return { workspaceDir, summary, rows, commitTimesAvailable, notes };
|
|
275
|
+
}
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
export declare const HOURS_EXPORT_SCHEMA = "ia-hours-export/2";
|
|
2
|
+
/** Claude Code's own config-dir override; scanned in addition to the defaults. */
|
|
3
|
+
export declare const CLAUDE_CONFIG_DIR_ENV = "CLAUDE_CONFIG_DIR";
|
|
4
|
+
/** The pseudo-slug for Install Agent work that named no client. */
|
|
5
|
+
export declare const UNATTRIBUTED_SLUG = "unattributed";
|
|
6
|
+
/** The only tool_use input fields read — where a working path or a command lives. */
|
|
7
|
+
export declare const TOOL_INPUT_PATH_KEYS: readonly ["file_path", "path", "notebook_path", "command", "pattern", "glob"];
|
|
8
|
+
export interface ClaudeHoursSummaryRow {
|
|
9
|
+
slug: string;
|
|
10
|
+
/** False when this machine has no clients/client-<slug> repo — the ledger files it as other-lead. */
|
|
11
|
+
known: boolean;
|
|
12
|
+
activeMinutes: number;
|
|
13
|
+
hoursByMonth: Record<string, number>;
|
|
14
|
+
hoursTotal: number;
|
|
15
|
+
}
|
|
16
|
+
export interface ClaudeHoursExportResult {
|
|
17
|
+
schema: typeof HOURS_EXPORT_SCHEMA;
|
|
18
|
+
person: string;
|
|
19
|
+
/** When this export was produced (ISO timestamp). */
|
|
20
|
+
generatedAt: string;
|
|
21
|
+
windowSince: string | null;
|
|
22
|
+
windowUntil: string | null;
|
|
23
|
+
/** Config dirs actually scanned, for the person merging this in to sanity-check. */
|
|
24
|
+
configDirsUsed: string[];
|
|
25
|
+
workspaceRoot: string | null;
|
|
26
|
+
/** User/assistant lines in the window (the ledger's source-range table). */
|
|
27
|
+
events: {
|
|
28
|
+
first: string | null;
|
|
29
|
+
last: string | null;
|
|
30
|
+
lines: number;
|
|
31
|
+
};
|
|
32
|
+
/** slug → sorted minutes with activity, each "YYYY-MM-DDTHH:MMZ". The ledger's raw input. */
|
|
33
|
+
minutes: Record<string, string[]>;
|
|
34
|
+
/** Claude Code on its own, by the ledger's rules — the human summary, most hours first. */
|
|
35
|
+
summary: ClaudeHoursSummaryRow[];
|
|
36
|
+
/** Sessions that named no client and ran outside the workspace — other work, left out. */
|
|
37
|
+
skippedSessions: number;
|
|
38
|
+
/** Session files that could not be read (permissions, mid-write) — reported, never thrown. */
|
|
39
|
+
unreadableSessions: string[];
|
|
40
|
+
}
|
|
41
|
+
export interface ClaudeHoursExportOptions {
|
|
42
|
+
/** Ledger name for this person, e.g. "Ian". Required. */
|
|
43
|
+
person: string;
|
|
44
|
+
/** Injectable for tests; defaults to the real home directory. */
|
|
45
|
+
homeDir?: string;
|
|
46
|
+
env?: NodeJS.ProcessEnv;
|
|
47
|
+
/** Overrides config-dir discovery entirely — for tests, or a non-standard install. */
|
|
48
|
+
configDirs?: string[];
|
|
49
|
+
/** Install Agent workspace root; default: found by walking up from the cwd. */
|
|
50
|
+
workspaceRoot?: string | null;
|
|
51
|
+
/** YYYY-MM-DD (UTC day), inclusive lower bound. Default: everything Claude Code kept. */
|
|
52
|
+
since?: string;
|
|
53
|
+
/** YYYY-MM-DD (UTC day), inclusive upper bound. Default: now. */
|
|
54
|
+
until?: string;
|
|
55
|
+
now?: () => Date;
|
|
56
|
+
}
|
|
57
|
+
/** Reject anything but a real YYYY-MM-DD calendar date. */
|
|
58
|
+
export declare function parseLedgerDate(value: string, flag: string): number;
|
|
59
|
+
/** Parse a "YYYY-MM-DDTHH:MMZ" minute from an export back to epoch ms. */
|
|
60
|
+
export declare function parseMinuteIso(value: string): number;
|
|
61
|
+
/** Where exports are kept on the technician's machine (and where the weekly job writes). */
|
|
62
|
+
export declare const HOURS_EXPORT_DIR: string;
|
|
63
|
+
export interface SaveClaudeHoursExportOptions {
|
|
64
|
+
/** Default: ~/.config/installagent/hours-export/ia-hours-export-<person>-<date>.json. A relative path resolves against `cwd`. */
|
|
65
|
+
out?: string;
|
|
66
|
+
/** Overwrite an existing `out` file. */
|
|
67
|
+
force?: boolean;
|
|
68
|
+
cwd?: string;
|
|
69
|
+
homeDir?: string;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Write an export to disk. The default location is this command's own folder
|
|
73
|
+
* and keeps one file per person per (Eastern) day: a rerun the same day
|
|
74
|
+
* replaces it, since the newer export covers everything the older one did. An
|
|
75
|
+
* explicit `out` path is the caller's file and is never overwritten without
|
|
76
|
+
* `force`. Returns the path written.
|
|
77
|
+
*/
|
|
78
|
+
export declare function saveClaudeHoursExport(result: ClaudeHoursExportResult, options?: SaveClaudeHoursExportOptions): string;
|
|
79
|
+
/** The ledger keeper's n8n intake: it DMs the file to them on Slack. Not a secret. */
|
|
80
|
+
export declare const HOURS_EXPORT_WEBHOOK_URL = "https://n8n.installagent.com/webhook/hours-export";
|
|
81
|
+
/** Shared secret the intake webhook checks, sent as HOURS_EXPORT_SECRET_HEADER. */
|
|
82
|
+
export declare const HOURS_EXPORT_SECRET_ENV = "HOURS_EXPORT_SECRET";
|
|
83
|
+
export declare const HOURS_EXPORT_SECRET_HEADER = "x-hours-export-secret";
|
|
84
|
+
export interface SendClaudeHoursExportOptions {
|
|
85
|
+
/** Default: HOURS_EXPORT_WEBHOOK_URL. */
|
|
86
|
+
webhookUrl?: string;
|
|
87
|
+
env?: NodeJS.ProcessEnv;
|
|
88
|
+
fetchImpl?: typeof fetch;
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Send an export to the ledger keeper through the n8n intake webhook, which
|
|
92
|
+
* DMs them the file on Slack. Throws with a plain reason on any failure — the
|
|
93
|
+
* caller keeps the file on disk either way.
|
|
94
|
+
*/
|
|
95
|
+
export declare function sendClaudeHoursExport(result: ClaudeHoursExportResult, options?: SendClaudeHoursExportOptions): Promise<void>;
|
|
96
|
+
export interface DeliverClaudeHoursExportOptions extends SaveClaudeHoursExportOptions, SendClaudeHoursExportOptions {
|
|
97
|
+
/** Send to the ledger keeper after saving (default true). */
|
|
98
|
+
send?: boolean;
|
|
99
|
+
}
|
|
100
|
+
export interface DeliverClaudeHoursExportResult {
|
|
101
|
+
outPath: string;
|
|
102
|
+
sent: boolean;
|
|
103
|
+
/** Why sending failed; the file is saved regardless. */
|
|
104
|
+
sendError: string | null;
|
|
105
|
+
}
|
|
106
|
+
/** Save the export, then send it unless `send` is false. A failed send never loses the file. */
|
|
107
|
+
export declare function deliverClaudeHoursExport(result: ClaudeHoursExportResult, options?: DeliverClaudeHoursExportOptions): Promise<DeliverClaudeHoursExportResult>;
|
|
108
|
+
/** The export minus its per-minute lists (replaced by counts) — for showing to a person or an agent. */
|
|
109
|
+
export declare function compactClaudeHoursExport(result: ClaudeHoursExportResult): Omit<ClaudeHoursExportResult, "minutes"> & {
|
|
110
|
+
minuteCounts: Record<string, number>;
|
|
111
|
+
};
|
|
112
|
+
/**
|
|
113
|
+
* Read this machine's Claude Code session logs and return one person's
|
|
114
|
+
* per-client activity minutes (plus a Claude-only hours summary), for
|
|
115
|
+
* handing to whoever maintains the ledger. Read-only: never writes
|
|
116
|
+
* anywhere, never transmits anything itself.
|
|
117
|
+
*/
|
|
118
|
+
export declare function exportClaudeHours(options: ClaudeHoursExportOptions): Promise<ClaudeHoursExportResult>;
|