@installagent/sdk 0.15.0 → 0.16.1
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 +5 -0
- package/dist/index.js +5 -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 +459 -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/tech-call-prep/SKILL.md +48 -19
package/dist/env-registry.js
CHANGED
|
@@ -8,6 +8,7 @@ import { DOCS_SEARCH_TOKEN_ENV, DOCS_SESSION_ENV } from "./docs-search.js";
|
|
|
8
8
|
import { FATHOM_API_KEY_ENV } from "./fathom-webhook.js";
|
|
9
9
|
import { LINEAR_API_TOKEN_ENV } from "./linear-project.js";
|
|
10
10
|
import { PORTAL_ADMIN_SECRET_ENV } from "./portal-admin.js";
|
|
11
|
+
import { PREP_CALENDAR_ID_ENV } from "./tech-call-prep.js";
|
|
11
12
|
/** Day-one shared secrets — every technician gets read access. */
|
|
12
13
|
export const DEFAULT_TECH_VAULT = "team-techs";
|
|
13
14
|
/** Payments / DB / deploy secrets — granted case-by-case. */
|
|
@@ -132,18 +133,31 @@ export const ENV_VARS = [
|
|
|
132
133
|
source: "vault",
|
|
133
134
|
doctor: true,
|
|
134
135
|
vault: DEFAULT_TECH_VAULT,
|
|
135
|
-
neededBy: "ia client-drive, ia triage",
|
|
136
|
+
neededBy: "ia client-drive, ia triage, ia tech-call prep",
|
|
136
137
|
howToGet: `the Drive service-account key JSON — ${inTechVault}`,
|
|
137
138
|
section: SECTION_DRIVERS,
|
|
138
139
|
comment: "the Drive service-account key JSON, single line — filled by `ia env fill`",
|
|
139
140
|
},
|
|
141
|
+
{
|
|
142
|
+
// The calendar that holds the client calls. An id, not a secret: each
|
|
143
|
+
// person sets their own. The calendar must be shared read-only with the
|
|
144
|
+
// Drive service account, or the invite check reports "not checked".
|
|
145
|
+
name: PREP_CALENDAR_ID_ENV,
|
|
146
|
+
tier: "optional",
|
|
147
|
+
source: "personal",
|
|
148
|
+
doctor: false,
|
|
149
|
+
neededBy: "ia tech-call prep (the invite check)",
|
|
150
|
+
howToGet: "the calendar id (Google Calendar → Settings → Integrate calendar), after you share that calendar read-only with the Drive service account",
|
|
151
|
+
section: SECTION_DRIVERS,
|
|
152
|
+
comment: "optional — the calendar id for `ia tech-call prep`. Share the calendar read-only\nwith the Drive service account first; unset = the invite check is not run.",
|
|
153
|
+
},
|
|
140
154
|
{
|
|
141
155
|
name: FATHOM_API_KEY_ENV,
|
|
142
156
|
tier: "optional",
|
|
143
157
|
source: "vault",
|
|
144
158
|
doctor: true,
|
|
145
159
|
vault: DEFAULT_TECH_VAULT,
|
|
146
|
-
neededBy: "ia secrets mint fathom-webhook",
|
|
160
|
+
neededBy: "ia secrets mint fathom-webhook, ia tech-call verify / update-pass (transcript fallback)",
|
|
147
161
|
howToGet: `the Fathom account API key — ${inTechVault}`,
|
|
148
162
|
section: SECTION_DRIVERS,
|
|
149
163
|
comment: "Fathom dashboard → Settings → API Access — filled by `ia env fill`",
|
|
@@ -187,7 +201,7 @@ export const ENV_VARS = [
|
|
|
187
201
|
source: "vault",
|
|
188
202
|
doctor: false,
|
|
189
203
|
vault: DEFAULT_TECH_VAULT,
|
|
190
|
-
neededBy: "ia build-estimate, ia secrets mint gemini-api-key",
|
|
204
|
+
neededBy: "ia build-estimate, ia tech-call verify / update-pass, ia secrets mint gemini-api-key",
|
|
191
205
|
howToGet: inTechVault,
|
|
192
206
|
section: SECTION_DRIVERS,
|
|
193
207
|
},
|
|
@@ -268,6 +282,8 @@ const TECH_ROLE_VAR_NAMES = new Set([
|
|
|
268
282
|
N8N_API_URL_ENV,
|
|
269
283
|
N8N_API_KEY_ENV,
|
|
270
284
|
GEMINI_API_KEY_ENV,
|
|
285
|
+
// Personal, optional: the calendar id for `ia tech-call prep` (2026-11-19).
|
|
286
|
+
PREP_CALENDAR_ID_ENV,
|
|
271
287
|
// Every technician's `ia hours-export` sends with it (2026-09-24).
|
|
272
288
|
HOURS_EXPORT_SECRET_ENV,
|
|
273
289
|
// In team-techs by the account owner's choice (2026-09-24); no `ia` command reads them.
|
package/dist/index.d.ts
CHANGED
|
@@ -48,6 +48,11 @@ export { type OnboardingChange, type OnboardingRetirePlan, planOnboardingRetire,
|
|
|
48
48
|
export { type StandupCallPrep, type StandupCallPrepStatus, type StandupGitState, type StandupIssueRef, type StandupLinear, type StandupOptions, type StandupRepo, type StandupRepoLint, type StandupResult, type StandupStaleTodo, standup, } from "./standup.js";
|
|
49
49
|
export { type SyncRepoResult, type SyncRepoStatus, type SyncReposOptions, type SyncReposResult, syncRepos, workspaceRepoNames, } from "./sync-repos.js";
|
|
50
50
|
export { type SyncTemplatesFileResult, type SyncTemplatesFileStatus, type SyncTemplatesOptions, type SyncTemplatesResult, syncTemplates, TEMPLATE_CLAUDE_SETTINGS, TEMPLATE_ROOT_DOCS, } from "./sync-templates.js";
|
|
51
|
+
export { AGENDA_API_PATH, AGENDA_FILE, agendaFileContent, prepGapsBlock, type TechCallAgendaAnswer, type TechCallAgendaOptions, type TechCallAgendaResult, techCallAgenda, } from "./tech-call-agenda.js";
|
|
52
|
+
export { NOTE_LANDED_PATH, type NoteLandedAnswer, type NoteLandedEvent, parseNoteFrontmatter, type TechCallNoteLandedOptions, type TechCallNoteLandedResult, techCallNoteLanded, } from "./tech-call-note-landed.js";
|
|
53
|
+
export { checkAgendaDoc, checkAgendaFile, checkDocs, checkInvite, checkLinear, checkPortalOrg, checkScaffold, checkVault, MANUAL_PREP, PREP_CALENDAR_ID_ENV, type PrepCalendarEvent, type PrepCheck, type PrepProbes, type PrepRepoFiles, type PrepStatus, type PrepTeam, renderPrepBlock, type TechCallPrepOptions, type TechCallPrepResult, techCallPrep, withPrepBlock, } from "./tech-call-prep.js";
|
|
54
|
+
export { buildUpdatePrompt, type ChangeKind, checkChanges, checkGates, checkLinearDrafts, FALLBACK_SLACK_USER_ENV, type GateFailure, handEditedLines, type LinearDraft, renderUpdateEvidence, type TechCallUpdatePassOptions, type TechCallUpdatePassResult, techCallUpdatePass, UPDATE_PASS_ALLOWED, UPDATE_PASS_MODEL, type UpdateChange, type UpdatePassStatus, updatePassNotice, } from "./tech-call-update-pass.js";
|
|
55
|
+
export { applyMarks, buildVerifyPrompt, type CallTranscript, type ClaimKind, type ClaimVerdict, checkClaims, checkPromises, findQuote, NoTranscriptError, renderVerifyEvidence, stripMarks, type TechCallVerifyOptions, type TechCallVerifyResult, techCallVerify, VERIFY_DOCS, VERIFY_MODEL, type VerifyClaim, type VerifyPromise, type VerifySources, } from "./tech-call-verify.js";
|
|
51
56
|
export { adhocReason, selectClientSlugs, TEMPLATE_RETIRED_FILES, TEMPLATE_SYNCED_FILES, type TemplateSyncFileResult, type TemplateSyncFileStatus, type TemplateSyncOptions, type TemplateSyncRepoResult, type TemplateSyncResult, templateSync, } from "./template-sync.js";
|
|
52
57
|
export { TRIAGE_BACKFILL_CHUNK, type TriageBackfillOptions, type TriageBackfillResult, triageBackfill, } from "./triage-backfill.js";
|
|
53
58
|
export { checkTriageRecordWiring, detectWorkflowProvider, PORTAL_INGEST_CREDENTIAL_NAME, TRIAGE_RECORDS_PATH, type TriageEnableOptions, type TriageEnableResult, type TriageWiringCheck, type TriageWiringCheckId, type TriageWiringReport, triageEnable, } from "./triage-enable.js";
|
package/dist/index.js
CHANGED
|
@@ -51,6 +51,11 @@ export { planOnboardingRetire, ROADMAP_ARCHIVE, ROADMAP_FILE, roadmapRetire, } f
|
|
|
51
51
|
export { standup, } from "./standup.js";
|
|
52
52
|
export { syncRepos, workspaceRepoNames, } from "./sync-repos.js";
|
|
53
53
|
export { syncTemplates, TEMPLATE_CLAUDE_SETTINGS, TEMPLATE_ROOT_DOCS, } from "./sync-templates.js";
|
|
54
|
+
export { AGENDA_API_PATH, AGENDA_FILE, agendaFileContent, prepGapsBlock, techCallAgenda, } from "./tech-call-agenda.js";
|
|
55
|
+
export { NOTE_LANDED_PATH, parseNoteFrontmatter, techCallNoteLanded, } from "./tech-call-note-landed.js";
|
|
56
|
+
export { checkAgendaDoc, checkAgendaFile, checkDocs, checkInvite, checkLinear, checkPortalOrg, checkScaffold, checkVault, MANUAL_PREP, PREP_CALENDAR_ID_ENV, renderPrepBlock, techCallPrep, withPrepBlock, } from "./tech-call-prep.js";
|
|
57
|
+
export { buildUpdatePrompt, checkChanges, checkGates, checkLinearDrafts, FALLBACK_SLACK_USER_ENV, handEditedLines, renderUpdateEvidence, techCallUpdatePass, UPDATE_PASS_ALLOWED, UPDATE_PASS_MODEL, updatePassNotice, } from "./tech-call-update-pass.js";
|
|
58
|
+
export { applyMarks, buildVerifyPrompt, checkClaims, checkPromises, findQuote, NoTranscriptError, renderVerifyEvidence, stripMarks, techCallVerify, VERIFY_DOCS, VERIFY_MODEL, } from "./tech-call-verify.js";
|
|
54
59
|
export { adhocReason, selectClientSlugs, TEMPLATE_RETIRED_FILES, TEMPLATE_SYNCED_FILES, templateSync, } from "./template-sync.js";
|
|
55
60
|
export { TRIAGE_BACKFILL_CHUNK, triageBackfill, } from "./triage-backfill.js";
|
|
56
61
|
export { checkTriageRecordWiring, detectWorkflowProvider, PORTAL_INGEST_CREDENTIAL_NAME, TRIAGE_RECORDS_PATH, triageEnable, } from "./triage-enable.js";
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
export declare const AGENDA_API_PATH = "/api/admin/agenda";
|
|
2
|
+
export declare const AGENDA_FILE = "docs/05-call-agenda.md";
|
|
3
|
+
export declare const PREP_GAPS_START = "<!-- PREP_GAPS:START -->";
|
|
4
|
+
export declare const PREP_GAPS_END = "<!-- PREP_GAPS:END -->";
|
|
5
|
+
/** The portal's answer (portal `lib/agenda-service.ts` → `AgendaResult`). */
|
|
6
|
+
export interface TechCallAgendaAnswer {
|
|
7
|
+
slug: string;
|
|
8
|
+
markdown: string;
|
|
9
|
+
callDate: string;
|
|
10
|
+
callDateKnown: boolean;
|
|
11
|
+
playbook: string | null;
|
|
12
|
+
notes: "registry" | "fathom";
|
|
13
|
+
repoDocs: boolean;
|
|
14
|
+
scriptLoaded: boolean;
|
|
15
|
+
warnings: string[];
|
|
16
|
+
doc: {
|
|
17
|
+
action: "created" | "updated";
|
|
18
|
+
id: string;
|
|
19
|
+
name: string;
|
|
20
|
+
webViewLink: string | null;
|
|
21
|
+
previousName?: string;
|
|
22
|
+
} | null;
|
|
23
|
+
stale: string[];
|
|
24
|
+
}
|
|
25
|
+
export interface TechCallAgendaOptions {
|
|
26
|
+
/** installagent/ workspace root (holds clients/client-<slug>/). Needed for `write`. */
|
|
27
|
+
workspaceDir: string;
|
|
28
|
+
/** YYYY-MM-DD of the call. Omitted = the portal uses today and the agenda says so. */
|
|
29
|
+
callDate?: string;
|
|
30
|
+
/** Update (or create) the ONE agenda Doc in the client's Drive folder. */
|
|
31
|
+
publish?: boolean;
|
|
32
|
+
/** Write docs/05-call-agenda.md in the client checkout. */
|
|
33
|
+
write?: boolean;
|
|
34
|
+
secret?: string;
|
|
35
|
+
baseUrl?: string;
|
|
36
|
+
fetchImpl?: typeof fetch;
|
|
37
|
+
}
|
|
38
|
+
export interface TechCallAgendaResult {
|
|
39
|
+
answer: TechCallAgendaAnswer;
|
|
40
|
+
/** Absolute path of the file written, or null. */
|
|
41
|
+
written: string | null;
|
|
42
|
+
/** True when an existing prep-gaps block was carried into the new file. */
|
|
43
|
+
keptPrepGaps: boolean;
|
|
44
|
+
}
|
|
45
|
+
/** The text between the prep-gaps markers (markers excluded), or null. */
|
|
46
|
+
export declare function prepGapsBlock(markdown: string): string | null;
|
|
47
|
+
/**
|
|
48
|
+
* The portal's agenda → the repo file: the `Type: spec` line under the title
|
|
49
|
+
* (repo-lint rule 19; a repo convention, so the Drive Doc has none), and the
|
|
50
|
+
* prep-gaps block of the file on disk kept — `ia tech-call prep` wrote it, and
|
|
51
|
+
* a new draft must not throw its findings away.
|
|
52
|
+
*/
|
|
53
|
+
export declare function agendaFileContent(markdown: string, existing: string | null): {
|
|
54
|
+
content: string;
|
|
55
|
+
keptPrepGaps: boolean;
|
|
56
|
+
};
|
|
57
|
+
export declare function techCallAgenda(slug: string, options: TechCallAgendaOptions): Promise<TechCallAgendaResult>;
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
// `ia tech-call agenda <slug>` — the ONE tech-call agenda. The portal drafts
|
|
2
|
+
// it (POST /api/admin/agenda: call notes + transcript, the build repo's
|
|
3
|
+
// engagement docs, the industry playbook, the discovery-call script) — the
|
|
4
|
+
// same code the lead-close kickoff runs — and this command is how a technician
|
|
5
|
+
// regenerates it before the call.
|
|
6
|
+
//
|
|
7
|
+
// Default = draft only: the markdown comes back and nothing is written
|
|
8
|
+
// anywhere. `publish` puts it in the ONE agenda Doc of the call in the
|
|
9
|
+
// client's Drive folder (updated in place; other agenda Docs are reported as
|
|
10
|
+
// stale, never deleted). `write` puts the same text in the client checkout's
|
|
11
|
+
// docs/05-call-agenda.md (working tree only — never a commit).
|
|
12
|
+
//
|
|
13
|
+
// `publish` changes a client's Drive folder, so this ships as SDK + CLI only
|
|
14
|
+
// (golden rule 2). No agenda logic lives here: one implementation, in the portal.
|
|
15
|
+
import { existsSync } from "node:fs";
|
|
16
|
+
import { readFile, writeFile } from "node:fs/promises";
|
|
17
|
+
import { join, resolve } from "node:path";
|
|
18
|
+
import { SLUG_PATTERN } from "./new-client.js";
|
|
19
|
+
import { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_URL_ENV, PortalAdminAuthError, PortalRequestError, } from "./portal-admin.js";
|
|
20
|
+
export const AGENDA_API_PATH = "/api/admin/agenda";
|
|
21
|
+
export const AGENDA_FILE = "docs/05-call-agenda.md";
|
|
22
|
+
export const PREP_GAPS_START = "<!-- PREP_GAPS:START -->";
|
|
23
|
+
export const PREP_GAPS_END = "<!-- PREP_GAPS:END -->";
|
|
24
|
+
/** The text between the prep-gaps markers (markers excluded), or null. */
|
|
25
|
+
export function prepGapsBlock(markdown) {
|
|
26
|
+
const start = markdown.indexOf(PREP_GAPS_START);
|
|
27
|
+
const end = markdown.indexOf(PREP_GAPS_END);
|
|
28
|
+
if (start === -1 || end === -1 || end < start)
|
|
29
|
+
return null;
|
|
30
|
+
return markdown.slice(start + PREP_GAPS_START.length, end);
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* The portal's agenda → the repo file: the `Type: spec` line under the title
|
|
34
|
+
* (repo-lint rule 19; a repo convention, so the Drive Doc has none), and the
|
|
35
|
+
* prep-gaps block of the file on disk kept — `ia tech-call prep` wrote it, and
|
|
36
|
+
* a new draft must not throw its findings away.
|
|
37
|
+
*/
|
|
38
|
+
export function agendaFileContent(markdown, existing) {
|
|
39
|
+
const lines = markdown.replace(/\r\n/g, "\n").split("\n");
|
|
40
|
+
if (lines[0]?.startsWith("# ") && lines[1]?.trim() !== "Type: spec") {
|
|
41
|
+
lines.splice(1, 0, "Type: spec");
|
|
42
|
+
}
|
|
43
|
+
let content = lines.join("\n");
|
|
44
|
+
const kept = existing ? prepGapsBlock(existing) : null;
|
|
45
|
+
const fresh = prepGapsBlock(content);
|
|
46
|
+
let keptPrepGaps = false;
|
|
47
|
+
if (kept !== null && fresh !== null && kept.trim() && kept !== fresh) {
|
|
48
|
+
content = content.replace(`${PREP_GAPS_START}${fresh}${PREP_GAPS_END}`, `${PREP_GAPS_START}${kept}${PREP_GAPS_END}`);
|
|
49
|
+
keptPrepGaps = true;
|
|
50
|
+
}
|
|
51
|
+
return { content: content.endsWith("\n") ? content : `${content}\n`, keptPrepGaps };
|
|
52
|
+
}
|
|
53
|
+
export async function techCallAgenda(slug, options) {
|
|
54
|
+
if (!SLUG_PATTERN.test(slug)) {
|
|
55
|
+
throw new Error(`invalid slug "${slug}" — use lowercase letters, digits, and hyphens`);
|
|
56
|
+
}
|
|
57
|
+
if (options.callDate && !/^\d{4}-\d{2}-\d{2}$/.test(options.callDate)) {
|
|
58
|
+
throw new Error(`--call-date must be YYYY-MM-DD, not "${options.callDate}"`);
|
|
59
|
+
}
|
|
60
|
+
const repoDir = join(resolve(options.workspaceDir), "clients", `client-${slug}`);
|
|
61
|
+
// Checked BEFORE the model call: a draft nobody can write is a wasted run.
|
|
62
|
+
if (options.write && !existsSync(join(repoDir, "docs"))) {
|
|
63
|
+
throw new Error(`${join(repoDir, "docs")} not found — clone the client repo first (\`ia sync\`), or drop --write`);
|
|
64
|
+
}
|
|
65
|
+
const secret = options.secret ?? process.env[PORTAL_ADMIN_SECRET_ENV];
|
|
66
|
+
if (!secret) {
|
|
67
|
+
throw new PortalAdminAuthError(`portal admin secret required — set ${PORTAL_ADMIN_SECRET_ENV} (from 1Password; \`ia env fill\`)`);
|
|
68
|
+
}
|
|
69
|
+
const baseUrl = (options.baseUrl ?? process.env[PORTAL_URL_ENV] ?? DEFAULT_PORTAL_URL).replace(/\/$/, "");
|
|
70
|
+
const res = await (options.fetchImpl ?? fetch)(`${baseUrl}${AGENDA_API_PATH}`, {
|
|
71
|
+
method: "POST",
|
|
72
|
+
headers: { Authorization: `Bearer ${secret}`, "Content-Type": "application/json" },
|
|
73
|
+
body: JSON.stringify({
|
|
74
|
+
slug,
|
|
75
|
+
...(options.callDate ? { callDate: options.callDate } : {}),
|
|
76
|
+
publish: options.publish === true,
|
|
77
|
+
}),
|
|
78
|
+
});
|
|
79
|
+
if (res.status === 401) {
|
|
80
|
+
throw new PortalAdminAuthError(`the portal refused the secret (HTTP 401) — check ${PORTAL_ADMIN_SECRET_ENV}`);
|
|
81
|
+
}
|
|
82
|
+
const body = (await res.json().catch(() => null));
|
|
83
|
+
if (!res.ok || !body?.markdown) {
|
|
84
|
+
const serverError = body?.error ?? null;
|
|
85
|
+
throw new PortalRequestError(`agenda failed (HTTP ${res.status})${serverError ? `: ${serverError}` : ""}`, res.status, serverError);
|
|
86
|
+
}
|
|
87
|
+
if (!options.write)
|
|
88
|
+
return { answer: body, written: null, keptPrepGaps: false };
|
|
89
|
+
const target = join(repoDir, AGENDA_FILE);
|
|
90
|
+
const existing = existsSync(target) ? await readFile(target, "utf8") : null;
|
|
91
|
+
const file = agendaFileContent(body.markdown, existing);
|
|
92
|
+
await writeFile(target, file.content);
|
|
93
|
+
return { answer: body, written: target, keptPrepGaps: file.keptPrepGaps };
|
|
94
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
export declare const NOTE_LANDED_PATH = "/api/hooks/note-landed";
|
|
2
|
+
export interface NoteLandedEvent {
|
|
3
|
+
slug: string;
|
|
4
|
+
/** Filename inside `clients/<slug>/calls/`. */
|
|
5
|
+
file: string;
|
|
6
|
+
date: string;
|
|
7
|
+
/** The note's frontmatter `type`, lower-cased. */
|
|
8
|
+
type: string;
|
|
9
|
+
fathomId?: string;
|
|
10
|
+
}
|
|
11
|
+
/** The portal's answer (portal `lib/note-landed.ts` → `NoteLandedDecision`, plus the run mode). */
|
|
12
|
+
export interface NoteLandedAnswer {
|
|
13
|
+
mode: string;
|
|
14
|
+
kickoff: "found" | "none";
|
|
15
|
+
action: "docs-rerun" | "update-pass" | "none";
|
|
16
|
+
steps: string[];
|
|
17
|
+
ran: string[];
|
|
18
|
+
reason: string;
|
|
19
|
+
key: string;
|
|
20
|
+
}
|
|
21
|
+
export interface TechCallNoteLandedOptions {
|
|
22
|
+
/** installagent/ workspace root (holds team-clients/). */
|
|
23
|
+
workspaceDir: string;
|
|
24
|
+
/** Note filename inside calls/; default = the newest note. */
|
|
25
|
+
file?: string;
|
|
26
|
+
/** Build and return the event; send nothing. */
|
|
27
|
+
dryRun?: boolean;
|
|
28
|
+
/** Bearer secret; defaults to $IA_PORTAL_ADMIN_SECRET. */
|
|
29
|
+
secret?: string;
|
|
30
|
+
/** Portal base URL; defaults to $IA_PORTAL_URL, then the prod portal. */
|
|
31
|
+
baseUrl?: string;
|
|
32
|
+
/** Injectable for tests; defaults to global fetch. */
|
|
33
|
+
fetchImpl?: typeof fetch;
|
|
34
|
+
}
|
|
35
|
+
export interface TechCallNoteLandedResult {
|
|
36
|
+
event: NoteLandedEvent;
|
|
37
|
+
sent: boolean;
|
|
38
|
+
/** Absent on a dry run. */
|
|
39
|
+
answer?: NoteLandedAnswer;
|
|
40
|
+
}
|
|
41
|
+
/** Top-level `key: value` pairs of a note's YAML frontmatter, quotes stripped. */
|
|
42
|
+
export declare function parseNoteFrontmatter(content: string): Record<string, string>;
|
|
43
|
+
export declare function techCallNoteLanded(slug: string, options: TechCallNoteLandedOptions): Promise<TechCallNoteLandedResult>;
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
// `ia tech-call note-landed <slug>` — replay the "note landed" event for one
|
|
2
|
+
// call note in the local team-clients checkout. The normal sender is
|
|
3
|
+
// team-clients' call-note-landed GitHub Actions workflow (a note reaches
|
|
4
|
+
// main); this is the same event sent by hand, for a note the workflow missed
|
|
5
|
+
// or a portal answer worth seeing again.
|
|
6
|
+
//
|
|
7
|
+
// It POSTs to the portal's /api/hooks/note-landed with the admin secret the
|
|
8
|
+
// `ia portal` commands already use. It sends the slug, the file name and
|
|
9
|
+
// four frontmatter values — never note content. It reads the registry and
|
|
10
|
+
// never writes to it (golden rule 7). What the portal does with the event is
|
|
11
|
+
// the portal's decision; its answer comes back verbatim.
|
|
12
|
+
//
|
|
13
|
+
// The portal may re-run kickoff steps on this event (a client-facing
|
|
14
|
+
// mutation), so this ships as SDK + CLI only — no MCP twin (golden rule 2).
|
|
15
|
+
import { existsSync } from "node:fs";
|
|
16
|
+
import { readdir, readFile } from "node:fs/promises";
|
|
17
|
+
import { join, resolve } from "node:path";
|
|
18
|
+
import { SLUG_PATTERN } from "./new-client.js";
|
|
19
|
+
import { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_URL_ENV, PortalAdminAuthError, PortalRequestError, } from "./portal-admin.js";
|
|
20
|
+
export const NOTE_LANDED_PATH = "/api/hooks/note-landed";
|
|
21
|
+
/** `YYYY-MM-DD.md` or `YYYY-MM-DD-<hint>.md` — never README.md, never `*.transcript.md`. */
|
|
22
|
+
const NOTE_FILE = /^\d{4}-\d{2}-\d{2}(-[a-z0-9-]+)?\.md$/;
|
|
23
|
+
/** Top-level `key: value` pairs of a note's YAML frontmatter, quotes stripped. */
|
|
24
|
+
export function parseNoteFrontmatter(content) {
|
|
25
|
+
const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
|
|
26
|
+
const values = {};
|
|
27
|
+
if (!match?.[1])
|
|
28
|
+
return values;
|
|
29
|
+
for (const line of match[1].split(/\r?\n/)) {
|
|
30
|
+
const pair = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/.exec(line);
|
|
31
|
+
if (!pair?.[1])
|
|
32
|
+
continue;
|
|
33
|
+
values[pair[1]] = (pair[2] ?? "").trim().replace(/^["'](.*)["']$/, "$1");
|
|
34
|
+
}
|
|
35
|
+
return values;
|
|
36
|
+
}
|
|
37
|
+
export async function techCallNoteLanded(slug, options) {
|
|
38
|
+
if (!SLUG_PATTERN.test(slug)) {
|
|
39
|
+
throw new Error(`invalid slug "${slug}" — use lowercase letters, digits, and hyphens`);
|
|
40
|
+
}
|
|
41
|
+
const callsDir = join(resolve(options.workspaceDir), "team-clients", "clients", slug, "calls");
|
|
42
|
+
if (!existsSync(callsDir)) {
|
|
43
|
+
throw new Error(`${callsDir} not found — clone team-clients (\`ia init\`) and check the slug is a registry folder`);
|
|
44
|
+
}
|
|
45
|
+
const notes = (await readdir(callsDir)).filter((name) => NOTE_FILE.test(name)).sort();
|
|
46
|
+
let file = options.file?.trim();
|
|
47
|
+
if (file) {
|
|
48
|
+
if (!NOTE_FILE.test(file)) {
|
|
49
|
+
throw new Error(`--file must be a call note name like 2026-11-18.md, not "${file}"`);
|
|
50
|
+
}
|
|
51
|
+
if (!notes.includes(file)) {
|
|
52
|
+
throw new Error(`no ${file} in clients/${slug}/calls/. Notes there: ${notes.join(", ") || "none"}`);
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
else {
|
|
56
|
+
file = notes.at(-1);
|
|
57
|
+
if (!file)
|
|
58
|
+
throw new Error(`clients/${slug}/calls/ has no call note yet`);
|
|
59
|
+
}
|
|
60
|
+
const fm = parseNoteFrontmatter(await readFile(join(callsDir, file), "utf8"));
|
|
61
|
+
const type = (fm.type ?? "").toLowerCase();
|
|
62
|
+
if (!type) {
|
|
63
|
+
throw new Error(`clients/${slug}/calls/${file} has no \`type\` in its frontmatter — the portal cannot route it`);
|
|
64
|
+
}
|
|
65
|
+
const event = {
|
|
66
|
+
slug,
|
|
67
|
+
file,
|
|
68
|
+
date: /^\d{4}-\d{2}-\d{2}$/.test(fm.date ?? "") ? fm.date : file.slice(0, 10),
|
|
69
|
+
type,
|
|
70
|
+
...(fm.fathom_id ? { fathomId: fm.fathom_id } : {}),
|
|
71
|
+
};
|
|
72
|
+
if (options.dryRun)
|
|
73
|
+
return { event, sent: false };
|
|
74
|
+
const secret = options.secret ?? process.env[PORTAL_ADMIN_SECRET_ENV];
|
|
75
|
+
if (!secret) {
|
|
76
|
+
throw new PortalAdminAuthError(`portal admin secret required — set ${PORTAL_ADMIN_SECRET_ENV} (from 1Password; \`ia env fill\`)`);
|
|
77
|
+
}
|
|
78
|
+
const baseUrl = (options.baseUrl ?? process.env[PORTAL_URL_ENV] ?? DEFAULT_PORTAL_URL).replace(/\/$/, "");
|
|
79
|
+
const res = await (options.fetchImpl ?? fetch)(`${baseUrl}${NOTE_LANDED_PATH}`, {
|
|
80
|
+
method: "POST",
|
|
81
|
+
headers: { Authorization: `Bearer ${secret}`, "Content-Type": "application/json" },
|
|
82
|
+
body: JSON.stringify(event),
|
|
83
|
+
});
|
|
84
|
+
if (res.status === 401) {
|
|
85
|
+
throw new PortalAdminAuthError(`the portal refused the secret (HTTP 401) — check ${PORTAL_ADMIN_SECRET_ENV}`);
|
|
86
|
+
}
|
|
87
|
+
const body = (await res.json().catch(() => null));
|
|
88
|
+
if (!res.ok || !body) {
|
|
89
|
+
const serverError = body?.error ?? null;
|
|
90
|
+
throw new PortalRequestError(`note-landed failed (HTTP ${res.status})${serverError ? `: ${serverError}` : ""}`, res.status, serverError);
|
|
91
|
+
}
|
|
92
|
+
return { event, sent: true, answer: body };
|
|
93
|
+
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { type ExecFileFn } from "./exec.js";
|
|
2
|
+
export declare const PREP_CALENDAR_ID_ENV = "IA_PREP_CALENDAR_ID";
|
|
3
|
+
export declare const AGENDA_DOC_MARKER = "tech-discovery-agenda";
|
|
4
|
+
export declare const PORTAL_LOGIN_ITEM_TITLE = "Install Agent client portal";
|
|
5
|
+
export type PrepStatus = "pass" | "gap" | "skipped";
|
|
6
|
+
export interface PrepCheck {
|
|
7
|
+
id: string;
|
|
8
|
+
status: PrepStatus;
|
|
9
|
+
/** What was found, in one sentence. No email address, no secret. */
|
|
10
|
+
detail: string;
|
|
11
|
+
/** What to do about a gap or a skip. Empty on a pass. */
|
|
12
|
+
fix: string;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* The people who must be on the invite, from the CRM: the technician and a
|
|
16
|
+
* client contact. Sales is not required on a tech call (decided 2026-11-20).
|
|
17
|
+
* Names and emails stay in memory only.
|
|
18
|
+
*/
|
|
19
|
+
export interface PrepTeam {
|
|
20
|
+
technicians: Array<{
|
|
21
|
+
name: string;
|
|
22
|
+
email: string;
|
|
23
|
+
}>;
|
|
24
|
+
/** The client's company email domain, or "" for a free-mail contact. */
|
|
25
|
+
clientDomain: string;
|
|
26
|
+
}
|
|
27
|
+
export interface PrepCalendarEvent {
|
|
28
|
+
summary: string;
|
|
29
|
+
attendees: string[];
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* The outside lookups, one per system. Each returns its data, or a string =
|
|
33
|
+
* "could not run, and why" (the check is then `skipped`). Injectable for tests.
|
|
34
|
+
*/
|
|
35
|
+
export interface PrepProbes {
|
|
36
|
+
team(slug: string): Promise<PrepTeam | string>;
|
|
37
|
+
calendarEvents(date: string): Promise<PrepCalendarEvent[] | string>;
|
|
38
|
+
vaultItemTitles(vault: string): Promise<string[] | string>;
|
|
39
|
+
portalOrgExists(slug: string): Promise<boolean | string>;
|
|
40
|
+
openLinearIssues(slug: string): Promise<string[] | string>;
|
|
41
|
+
driveDocTitles(slug: string): Promise<string[] | string>;
|
|
42
|
+
}
|
|
43
|
+
export interface PrepRepoFiles {
|
|
44
|
+
/** Top-level names in the client checkout. */
|
|
45
|
+
entries: string[];
|
|
46
|
+
onboardingHtml: string;
|
|
47
|
+
/** docs/ file name → text, for 01-04 and 05. */
|
|
48
|
+
docs: Record<string, string>;
|
|
49
|
+
/** evidence/ file name → text, transcript checks only. */
|
|
50
|
+
evidence: Record<string, string>;
|
|
51
|
+
/** Call notes in the registry, newest last: `2026-11-16`, `2026-11-18`. */
|
|
52
|
+
registryCalls: string[];
|
|
53
|
+
}
|
|
54
|
+
export declare function checkScaffold(files: PrepRepoFiles): PrepCheck;
|
|
55
|
+
export declare function checkDocs(files: PrepRepoFiles): PrepCheck[];
|
|
56
|
+
export declare function checkAgendaFile(files: PrepRepoFiles, callDate: string): PrepCheck;
|
|
57
|
+
export declare function checkInvite(events: PrepCalendarEvent[] | string, team: PrepTeam | string, callDate: string): PrepCheck;
|
|
58
|
+
export declare function checkVault(titles: string[] | string, vault: string): PrepCheck[];
|
|
59
|
+
export declare function checkPortalOrg(exists: boolean | string, slug: string): PrepCheck;
|
|
60
|
+
/** INS ids under `## Open questions...` of the tech spec. */
|
|
61
|
+
export declare function openQuestionIds(techSpec: string): string[];
|
|
62
|
+
export declare function checkLinear(open: string[] | string, techSpec: string): PrepCheck;
|
|
63
|
+
export declare function checkAgendaDoc(titles: string[] | string, callDate: string): PrepCheck;
|
|
64
|
+
/** What only a person can do. Fixed text, on every agenda. */
|
|
65
|
+
export declare const MANUAL_PREP: string[];
|
|
66
|
+
export declare function renderPrepBlock(checks: PrepCheck[], checkedOn: string): string;
|
|
67
|
+
/** docs/05 with its prep-gaps block replaced. Throws when the file has no block. */
|
|
68
|
+
export declare function withPrepBlock(agenda: string, block: string): string;
|
|
69
|
+
export declare function realProbes(options: {
|
|
70
|
+
workspaceDir: string;
|
|
71
|
+
fetchImpl?: typeof fetch;
|
|
72
|
+
execFileImpl?: ExecFileFn;
|
|
73
|
+
env?: Record<string, string | undefined>;
|
|
74
|
+
}): PrepProbes;
|
|
75
|
+
export interface TechCallPrepOptions {
|
|
76
|
+
workspaceDir: string;
|
|
77
|
+
/** YYYY-MM-DD. Default: the date in the title of docs/05-call-agenda.md, else today. */
|
|
78
|
+
callDate?: string;
|
|
79
|
+
/** Replace the prep-gaps block of docs/05-call-agenda.md in the working tree. */
|
|
80
|
+
write?: boolean;
|
|
81
|
+
probes?: PrepProbes;
|
|
82
|
+
now?: Date;
|
|
83
|
+
}
|
|
84
|
+
export interface TechCallPrepResult {
|
|
85
|
+
slug: string;
|
|
86
|
+
callDate: string;
|
|
87
|
+
checks: PrepCheck[];
|
|
88
|
+
counts: Record<PrepStatus, number>;
|
|
89
|
+
/** The block text (between the markers). */
|
|
90
|
+
block: string;
|
|
91
|
+
/** Absolute path of docs/05-call-agenda.md when it was written, else null. */
|
|
92
|
+
written: string | null;
|
|
93
|
+
}
|
|
94
|
+
export declare function techCallPrep(slug: string, options: TechCallPrepOptions): Promise<TechCallPrepResult>;
|