@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,188 @@
|
|
|
1
|
+
import { execFile } from "node:child_process";
|
|
2
|
+
import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
|
|
3
|
+
import { homedir, tmpdir, userInfo } from "node:os";
|
|
4
|
+
import { join } from "node:path";
|
|
5
|
+
import { promisify } from "node:util";
|
|
6
|
+
import { HOURS_EXPORT_DIR } from "./claude-hours.js";
|
|
7
|
+
import { detectPlatform } from "./platform.js";
|
|
8
|
+
// `ia hours-export --install-schedule` — run the export once a week on a
|
|
9
|
+
// technician's own machine, so nobody has to remember it and no Claude Code
|
|
10
|
+
// history is lost to its ~30-day log cleanup. One small runner script (cd into
|
|
11
|
+
// the workspace so the root .env loads, then run the export) plus the
|
|
12
|
+
// platform's own scheduler: launchd on macOS, Task Scheduler on Windows, the
|
|
13
|
+
// user crontab on Linux. Everything lives in the user's account; nothing needs
|
|
14
|
+
// admin rights.
|
|
15
|
+
const LAUNCHD_LABEL = "com.installagent.hours-export";
|
|
16
|
+
const WINDOWS_TASK = "InstallAgent hours export";
|
|
17
|
+
const CRON_MARKER = "# ia-hours-export";
|
|
18
|
+
/** Monday, 10:00 local time. */
|
|
19
|
+
const WEEKDAY = 1;
|
|
20
|
+
const HOUR = 10;
|
|
21
|
+
const defaultExec = async (file, args) => {
|
|
22
|
+
const { stdout, stderr } = await promisify(execFile)(file, [...args]);
|
|
23
|
+
return { stdout: String(stdout), stderr: String(stderr) };
|
|
24
|
+
};
|
|
25
|
+
/** Reject anything that could break out of the quoted runner script. */
|
|
26
|
+
function checkSafe(label, value) {
|
|
27
|
+
if (!value || /["\r\n`$%]/.test(value)) {
|
|
28
|
+
throw new Error(`${label} contains characters the scheduled job can't quote safely: ${value}`);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
function paths(homeDir, platform) {
|
|
32
|
+
const dir = join(homeDir, HOURS_EXPORT_DIR);
|
|
33
|
+
return {
|
|
34
|
+
dir,
|
|
35
|
+
runner: join(dir, platform === "win32" ? "run-weekly.cmd" : "run-weekly.sh"),
|
|
36
|
+
logPath: join(dir, "weekly.log"),
|
|
37
|
+
plist: join(homeDir, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`),
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
function runnerScript(platform, options, logPath) {
|
|
41
|
+
const { workspaceRoot, nodePath, iaScript, person } = options;
|
|
42
|
+
if (platform === "win32") {
|
|
43
|
+
return [
|
|
44
|
+
"@echo off",
|
|
45
|
+
"rem Written by `ia hours-export --install-schedule` — weekly Claude Code export for the hours ledger.",
|
|
46
|
+
`cd /d "${workspaceRoot}" || exit /b 1`,
|
|
47
|
+
`"${nodePath}" "${iaScript}" hours-export --person "${person}" --force >> "${logPath}" 2>&1`,
|
|
48
|
+
"",
|
|
49
|
+
].join("\r\n");
|
|
50
|
+
}
|
|
51
|
+
return [
|
|
52
|
+
"#!/bin/sh",
|
|
53
|
+
"# Written by `ia hours-export --install-schedule` — weekly Claude Code export for the hours ledger.",
|
|
54
|
+
`cd "${workspaceRoot}" || exit 1`,
|
|
55
|
+
`exec "${nodePath}" "${iaScript}" hours-export --person "${person}" --force`,
|
|
56
|
+
"",
|
|
57
|
+
].join("\n");
|
|
58
|
+
}
|
|
59
|
+
function launchdPlist(runner, logPath) {
|
|
60
|
+
return `<?xml version="1.0" encoding="UTF-8"?>
|
|
61
|
+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
62
|
+
<plist version="1.0">
|
|
63
|
+
<dict>
|
|
64
|
+
<key>Label</key><string>${LAUNCHD_LABEL}</string>
|
|
65
|
+
<key>ProgramArguments</key>
|
|
66
|
+
<array><string>/bin/sh</string><string>${runner}</string></array>
|
|
67
|
+
<key>StartCalendarInterval</key>
|
|
68
|
+
<dict><key>Weekday</key><integer>${WEEKDAY}</integer><key>Hour</key><integer>${HOUR}</integer><key>Minute</key><integer>0</integer></dict>
|
|
69
|
+
<key>StandardOutPath</key><string>${logPath}</string>
|
|
70
|
+
<key>StandardErrorPath</key><string>${logPath}</string>
|
|
71
|
+
</dict>
|
|
72
|
+
</plist>
|
|
73
|
+
`;
|
|
74
|
+
}
|
|
75
|
+
async function readCrontab(exec) {
|
|
76
|
+
try {
|
|
77
|
+
return (await exec("crontab", ["-l"])).stdout;
|
|
78
|
+
}
|
|
79
|
+
catch {
|
|
80
|
+
return ""; // no crontab yet
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
async function writeCrontab(exec, content) {
|
|
84
|
+
const file = join(tmpdir(), `ia-crontab-${process.pid}`);
|
|
85
|
+
writeFileSync(file, content);
|
|
86
|
+
try {
|
|
87
|
+
await exec("crontab", [file]);
|
|
88
|
+
}
|
|
89
|
+
finally {
|
|
90
|
+
rmSync(file, { force: true });
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
/** Install (or replace) the weekly export job for this user. */
|
|
94
|
+
export async function installHoursExportSchedule(options) {
|
|
95
|
+
const platform = options.platform ?? detectPlatform();
|
|
96
|
+
const exec = options.exec ?? defaultExec;
|
|
97
|
+
for (const [label, value] of [
|
|
98
|
+
["--person", options.person],
|
|
99
|
+
["workspace path", options.workspaceRoot],
|
|
100
|
+
["node path", options.nodePath],
|
|
101
|
+
["ia path", options.iaScript],
|
|
102
|
+
]) {
|
|
103
|
+
checkSafe(label, value);
|
|
104
|
+
}
|
|
105
|
+
const p = paths(options.homeDir ?? homedir(), platform);
|
|
106
|
+
mkdirSync(p.dir, { recursive: true, mode: 0o700 });
|
|
107
|
+
writeFileSync(p.runner, runnerScript(platform, options, p.logPath), { mode: 0o700 });
|
|
108
|
+
const when = "every Monday at 10:00 (runs at next wake if the computer was off)";
|
|
109
|
+
if (platform === "darwin") {
|
|
110
|
+
const uid = options.uid ?? userInfo().uid;
|
|
111
|
+
mkdirSync(join(p.plist, ".."), { recursive: true });
|
|
112
|
+
writeFileSync(p.plist, launchdPlist(p.runner, p.logPath));
|
|
113
|
+
await exec("launchctl", ["bootout", `gui/${uid}/${LAUNCHD_LABEL}`]).catch(() => undefined);
|
|
114
|
+
await exec("launchctl", ["bootstrap", `gui/${uid}`, p.plist]);
|
|
115
|
+
return { platform, runner: p.runner, scheduler: p.plist, when, logPath: p.logPath };
|
|
116
|
+
}
|
|
117
|
+
if (platform === "win32") {
|
|
118
|
+
await exec("schtasks", [
|
|
119
|
+
"/Create",
|
|
120
|
+
"/F",
|
|
121
|
+
"/SC",
|
|
122
|
+
"WEEKLY",
|
|
123
|
+
"/D",
|
|
124
|
+
"MON",
|
|
125
|
+
"/ST",
|
|
126
|
+
`${String(HOUR).padStart(2, "0")}:00`,
|
|
127
|
+
"/TN",
|
|
128
|
+
WINDOWS_TASK,
|
|
129
|
+
"/TR",
|
|
130
|
+
`"${p.runner}"`,
|
|
131
|
+
]);
|
|
132
|
+
return {
|
|
133
|
+
platform,
|
|
134
|
+
runner: p.runner,
|
|
135
|
+
scheduler: `Task Scheduler: ${WINDOWS_TASK}`,
|
|
136
|
+
when: "every Monday at 10:00",
|
|
137
|
+
logPath: p.logPath,
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
const current = await readCrontab(exec);
|
|
141
|
+
const kept = current.split("\n").filter((line) => line.trim() && !line.includes(CRON_MARKER));
|
|
142
|
+
kept.push(`0 ${HOUR} * * ${WEEKDAY} /bin/sh "${p.runner}" >> "${p.logPath}" 2>&1 ${CRON_MARKER}`);
|
|
143
|
+
await writeCrontab(exec, `${kept.join("\n")}\n`);
|
|
144
|
+
return {
|
|
145
|
+
platform,
|
|
146
|
+
runner: p.runner,
|
|
147
|
+
scheduler: "user crontab",
|
|
148
|
+
when: "every Monday at 10:00 (skipped if the computer is off)",
|
|
149
|
+
logPath: p.logPath,
|
|
150
|
+
};
|
|
151
|
+
}
|
|
152
|
+
/** Remove the weekly export job. Exports already written stay where they are. */
|
|
153
|
+
export async function uninstallHoursExportSchedule(options = {}) {
|
|
154
|
+
const platform = options.platform ?? detectPlatform();
|
|
155
|
+
const exec = options.exec ?? defaultExec;
|
|
156
|
+
const p = paths(options.homeDir ?? homedir(), platform);
|
|
157
|
+
const removed = [];
|
|
158
|
+
if (platform === "darwin") {
|
|
159
|
+
const uid = options.uid ?? userInfo().uid;
|
|
160
|
+
await exec("launchctl", ["bootout", `gui/${uid}/${LAUNCHD_LABEL}`]).catch(() => undefined);
|
|
161
|
+
if (existsSync(p.plist)) {
|
|
162
|
+
rmSync(p.plist);
|
|
163
|
+
removed.push(p.plist);
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
else if (platform === "win32") {
|
|
167
|
+
try {
|
|
168
|
+
await exec("schtasks", ["/Delete", "/F", "/TN", WINDOWS_TASK]);
|
|
169
|
+
removed.push(`Task Scheduler: ${WINDOWS_TASK}`);
|
|
170
|
+
}
|
|
171
|
+
catch {
|
|
172
|
+
// no such task
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
else {
|
|
176
|
+
const current = await readCrontab(exec);
|
|
177
|
+
if (current.includes(CRON_MARKER)) {
|
|
178
|
+
const kept = current.split("\n").filter((line) => line.trim() && !line.includes(CRON_MARKER));
|
|
179
|
+
await writeCrontab(exec, kept.length ? `${kept.join("\n")}\n` : "");
|
|
180
|
+
removed.push("user crontab line");
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
if (existsSync(p.runner)) {
|
|
184
|
+
rmSync(p.runner);
|
|
185
|
+
removed.push(p.runner);
|
|
186
|
+
}
|
|
187
|
+
return { removed };
|
|
188
|
+
}
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
import { type ClaudeHoursExportOptions, type ClaudeHoursExportResult } from "./claude-hours.js";
|
|
2
|
+
import type { ExecFileFn } from "./exec.js";
|
|
3
|
+
import { type HoursSource } from "./hours-estimate.js";
|
|
4
|
+
export declare const HOURS_LEDGER_SCHEMA = "ia-hours-ledger/1";
|
|
5
|
+
/** Where the ledger keeps its config, inbox, frozen sources, Claude store and output. */
|
|
6
|
+
export declare const DEFAULT_HOURS_LEDGER_DIR: string;
|
|
7
|
+
/** The ledger's window starts here unless --since says otherwise. */
|
|
8
|
+
export declare const LEDGER_WINDOW_START = "2026-06-01";
|
|
9
|
+
/** Activity on a slug that is neither an engagement in the CRM nor a build repo. */
|
|
10
|
+
export declare const OTHER_LEAD_SLUG = "other-lead";
|
|
11
|
+
/**
|
|
12
|
+
* The only Clients - Master fields ever requested. No package, contract value or MRR — on
|
|
13
|
+
* purpose — and no Name either: for some records it holds a contact person, not the business.
|
|
14
|
+
* The display name comes from the registry profile's `dba` / `legal_name` (`registryName`).
|
|
15
|
+
*/
|
|
16
|
+
export declare const CLIENT_FIELDS: readonly ["Slug", "Status", "Technician", "Tech Start Date"];
|
|
17
|
+
/** The only Team - Master fields ever requested. No pay — on purpose. */
|
|
18
|
+
export declare const TEAM_FIELDS: readonly ["Name", "Email"];
|
|
19
|
+
export interface HoursLedgerConfig {
|
|
20
|
+
/** Ledger name → identities in git and Linear (see `identityMatches`). Order = page order. */
|
|
21
|
+
people: Record<string, {
|
|
22
|
+
emails: string[];
|
|
23
|
+
}>;
|
|
24
|
+
/** Client code outside clients/client-<slug>, e.g. a deploy clone. `~` is expanded. */
|
|
25
|
+
extraRepos?: Array<{
|
|
26
|
+
slug: string;
|
|
27
|
+
path: string;
|
|
28
|
+
}>;
|
|
29
|
+
}
|
|
30
|
+
export interface HoursLedgerRow {
|
|
31
|
+
person: string;
|
|
32
|
+
slug: string;
|
|
33
|
+
client: string;
|
|
34
|
+
crm_tech: string | null;
|
|
35
|
+
is_technician: boolean;
|
|
36
|
+
status: string | null;
|
|
37
|
+
tech_start: string | null;
|
|
38
|
+
hours_by_month: Record<string, number>;
|
|
39
|
+
hours_total: number;
|
|
40
|
+
hours_before_start: number;
|
|
41
|
+
hours_by_source: Partial<Record<HoursSource, number>>;
|
|
42
|
+
event_counts: Partial<Record<HoursSource, number>>;
|
|
43
|
+
}
|
|
44
|
+
export interface HoursLedgerData {
|
|
45
|
+
schema: typeof HOURS_LEDGER_SCHEMA;
|
|
46
|
+
generated: string;
|
|
47
|
+
window_start: string;
|
|
48
|
+
window_end: string;
|
|
49
|
+
people: string[];
|
|
50
|
+
/** People with no Claude Code data at all yet. */
|
|
51
|
+
claude_missing: string[];
|
|
52
|
+
/** person → last day their Claude Code data reaches. */
|
|
53
|
+
claude_through: Record<string, string>;
|
|
54
|
+
/** source → last day of a source that only comes from frozen files. */
|
|
55
|
+
frozen_sources: Record<string, string>;
|
|
56
|
+
first_event: string | null;
|
|
57
|
+
rules: {
|
|
58
|
+
gap_min: number;
|
|
59
|
+
lead_heavy_min: number;
|
|
60
|
+
lead_light_min: number;
|
|
61
|
+
time_zone: string;
|
|
62
|
+
};
|
|
63
|
+
/** source → person → [first day, last day, event count]. */
|
|
64
|
+
source_ranges: Partial<Record<HoursSource, Record<string, [string, string, number]>>>;
|
|
65
|
+
rows: HoursLedgerRow[];
|
|
66
|
+
}
|
|
67
|
+
export interface HoursLedgerIngest {
|
|
68
|
+
person: string;
|
|
69
|
+
file: string;
|
|
70
|
+
from: string;
|
|
71
|
+
to: string;
|
|
72
|
+
minutes: number;
|
|
73
|
+
}
|
|
74
|
+
export interface HoursLedgerPersonTotal {
|
|
75
|
+
person: string;
|
|
76
|
+
ownClients: number;
|
|
77
|
+
helping: number;
|
|
78
|
+
unattributed: number;
|
|
79
|
+
bySource: Partial<Record<HoursSource, number>>;
|
|
80
|
+
}
|
|
81
|
+
export interface HoursLedgerResult {
|
|
82
|
+
outPath: string;
|
|
83
|
+
ledgerDir: string;
|
|
84
|
+
data: HoursLedgerData;
|
|
85
|
+
ingested: HoursLedgerIngest[];
|
|
86
|
+
totals: HoursLedgerPersonTotal[];
|
|
87
|
+
warnings: string[];
|
|
88
|
+
}
|
|
89
|
+
export interface HoursLedgerOptions {
|
|
90
|
+
/** Default: ~/.config/installagent/hours-ledger. */
|
|
91
|
+
ledgerDir?: string;
|
|
92
|
+
/** Default: found by walking up from the cwd. */
|
|
93
|
+
workspaceRoot?: string;
|
|
94
|
+
/** YYYY-MM-DD, inclusive. Default: LEDGER_WINDOW_START. */
|
|
95
|
+
since?: string;
|
|
96
|
+
/** YYYY-MM-DD, inclusive. Default: now. */
|
|
97
|
+
until?: string;
|
|
98
|
+
/** Also read THIS machine's Claude Code logs, as this ledger person. */
|
|
99
|
+
self?: string;
|
|
100
|
+
/** Extra `ia hours-export` files, besides everything in <ledgerDir>/inbox/. */
|
|
101
|
+
claudeExports?: string[];
|
|
102
|
+
/** `git fetch --all` each repo first (default true) — without it, others' pushed commits are missing. */
|
|
103
|
+
fetch?: boolean;
|
|
104
|
+
/** Output path. Default: <ledgerDir>/out/ledger-data-<generated>.json. */
|
|
105
|
+
out?: string;
|
|
106
|
+
/** Overwrite the output file if it exists. */
|
|
107
|
+
force?: boolean;
|
|
108
|
+
now?: () => Date;
|
|
109
|
+
env?: NodeJS.ProcessEnv;
|
|
110
|
+
homeDir?: string;
|
|
111
|
+
fetchImpl?: typeof fetch;
|
|
112
|
+
execFileImpl?: ExecFileFn;
|
|
113
|
+
exportClaude?: (options: ClaudeHoursExportOptions) => Promise<ClaudeHoursExportResult>;
|
|
114
|
+
}
|
|
115
|
+
/** Map an email to a ledger person by the config's address fragments. */
|
|
116
|
+
/**
|
|
117
|
+
* One config identity against one email, case-insensitive:
|
|
118
|
+
* - "ian@installagent.com" — that exact address (never "brian@installagent.com");
|
|
119
|
+
* - "jdoe-dev@" — that local part at any domain, also as a GitHub
|
|
120
|
+
* noreply "<id>+jdoe-dev@users.noreply.github.com";
|
|
121
|
+
* - "jdoehacks" — any local part containing it.
|
|
122
|
+
*/
|
|
123
|
+
export declare function identityMatches(identity: string, email: string): boolean;
|
|
124
|
+
/**
|
|
125
|
+
* Rebuild the hours ledger's data: every source, the ledger's rules, hours
|
|
126
|
+
* and dates only. Reads git, Linear and Airtable; writes only inside the
|
|
127
|
+
* ledger dir (the Claude store and the output file).
|
|
128
|
+
*/
|
|
129
|
+
export declare function buildHoursLedger(options?: HoursLedgerOptions): Promise<HoursLedgerResult>;
|