@installagent/sdk 0.1.0 → 0.2.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 (80) hide show
  1. package/dist/agent-templates.d.ts +36 -2
  2. package/dist/agent-templates.js +173 -3
  3. package/dist/client-linear-create.d.ts +26 -0
  4. package/dist/client-linear-create.js +46 -0
  5. package/dist/client-linear.d.ts +28 -9
  6. package/dist/client-linear.js +36 -14
  7. package/dist/docs-search.d.ts +19 -6
  8. package/dist/docs-search.js +32 -11
  9. package/dist/doctor.d.ts +9 -0
  10. package/dist/doctor.js +126 -23
  11. package/dist/env-fill.d.ts +13 -0
  12. package/dist/env-fill.js +34 -9
  13. package/dist/env-push.d.ts +3 -0
  14. package/dist/env-push.js +11 -6
  15. package/dist/env-registry.d.ts +25 -0
  16. package/dist/env-registry.js +69 -7
  17. package/dist/exec.js +15 -2
  18. package/dist/index.d.ts +14 -6
  19. package/dist/index.js +14 -6
  20. package/dist/linear-project.d.ts +2 -2
  21. package/dist/linear-project.js +2 -2
  22. package/dist/log.d.ts +28 -0
  23. package/dist/log.js +73 -0
  24. package/dist/n8n-executions.d.ts +85 -0
  25. package/dist/n8n-executions.js +259 -0
  26. package/dist/op-cli.d.ts +29 -0
  27. package/dist/op-cli.js +52 -0
  28. package/dist/platform.d.ts +35 -0
  29. package/dist/platform.js +39 -0
  30. package/dist/portal-admin.d.ts +40 -0
  31. package/dist/portal-admin.js +30 -0
  32. package/dist/standup.d.ts +88 -0
  33. package/dist/standup.js +235 -0
  34. package/dist/sync-repos.d.ts +47 -0
  35. package/dist/sync-repos.js +80 -0
  36. package/dist/template-sync.d.ts +10 -0
  37. package/dist/template-sync.js +11 -0
  38. package/dist/wizard.d.ts +15 -0
  39. package/dist/wizard.js +35 -56
  40. package/dist/workspace-docs.d.ts +44 -0
  41. package/dist/workspace-docs.js +73 -0
  42. package/package.json +2 -2
  43. package/templates/env.example +33 -23
  44. package/templates/workspace-root/AGENT.md +7 -5
  45. package/templates/workspace-root/ONBOARDING.md +65 -8
  46. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +102 -0
  47. package/templates/workspace-root/skills/CLAUDE.md +24 -6
  48. package/templates/workspace-root/skills/README.md +156 -0
  49. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
  50. package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
  51. package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
  52. package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
  53. package/templates/workspace-root/skills/client-latest/SKILL.md +301 -0
  54. package/templates/workspace-root/skills/client-latest/catchup.command.md +17 -0
  55. package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
  56. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +181 -0
  57. package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
  58. package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
  59. package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
  60. package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
  61. package/templates/workspace-root/skills/ia-cli/SKILL.md +19 -6
  62. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
  63. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
  64. package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
  65. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
  66. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
  67. package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
  68. package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
  69. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
  70. package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
  71. package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
  72. package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
  73. package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
  74. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
  75. package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
  76. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
  77. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
  78. package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
  79. package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
  80. package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
@@ -50,19 +50,33 @@ export interface SaveAgentTemplateResult {
50
50
  nodeCount: number;
51
51
  strippedCredentials: StrippedCredential[];
52
52
  manifestCreated: boolean;
53
+ /** True when this save scaffolded sop.md (an existing one is never touched). */
54
+ sopCreated: boolean;
53
55
  nextSteps: string[];
54
56
  }
55
57
  /**
56
58
  * Bank a live n8n workflow: fetch by id, sanitize, write
57
- * agents/<template>/workflow.json (+ template.md scaffold on first save; an
58
- * existing manifest is never overwritten).
59
+ * agents/<template>/workflow.json (+ template.md and sop.md scaffolds on first
60
+ * save; existing files are never overwritten).
59
61
  */
60
62
  export declare function saveAgentTemplate(input: SaveAgentTemplateInput, opts?: SaveAgentTemplateOptions): Promise<SaveAgentTemplateResult>;
63
+ /** sop.md status: absent, still the unfilled save-time scaffold, or written. */
64
+ export type SopState = "missing" | "scaffold" | "filled";
61
65
  export interface AgentTemplateInfo {
62
66
  slug: string;
63
67
  workflowName: string;
64
68
  description: string | null;
65
69
  hasManifest: boolean;
70
+ /**
71
+ * Whether the template ships a FILLED delivery SOP (sopState === "filled").
72
+ * False means the template is not deliverable yet — the SOP is missing or
73
+ * still the scaffold `save` wrote, so a technician has the machine but not
74
+ * the method (agents/AGENT.md § "The delivery SOP contract"), and callers
75
+ * surface it.
76
+ */
77
+ hasSop: boolean;
78
+ /** Distinguishes a missing sop.md from a scaffold-only one (see hasSop). */
79
+ sopState: SopState;
66
80
  }
67
81
  export interface ListAgentTemplatesResult {
68
82
  agentsDir: string;
@@ -70,6 +84,26 @@ export interface ListAgentTemplatesResult {
70
84
  }
71
85
  /** Catalog the bank: every agents/<slug>/ dir that holds a workflow.json. */
72
86
  export declare function listAgentTemplates(opts?: AgentBankOptions): Promise<ListAgentTemplatesResult>;
87
+ export interface AgentTemplateMatch extends AgentTemplateInfo {
88
+ /** Term-centered slice of template.md; empty when the template has no manifest. */
89
+ snippet: string;
90
+ }
91
+ export interface SearchAgentTemplatesResult {
92
+ agentsDir: string;
93
+ query: string;
94
+ matches: AgentTemplateMatch[];
95
+ }
96
+ export interface SearchAgentTemplatesOptions extends AgentBankOptions {
97
+ /** Max matches returned (default 5). */
98
+ limit?: number;
99
+ }
100
+ /**
101
+ * "Do we already have a workflow for X?" — rank banked templates against
102
+ * search terms, weighting slug + workflow-name hits over manifest-body hits
103
+ * (same scoring shape as docsSearch/clientBuild). Templates without a
104
+ * manifest still match on slug/name so `save` gaps stay findable.
105
+ */
106
+ export declare function searchAgentTemplates(query: string, opts?: SearchAgentTemplatesOptions): Promise<SearchAgentTemplatesResult>;
73
107
  export interface CreateFromTemplateInput {
74
108
  template: string;
75
109
  /** Where the JSON lands; defaults to the current working directory. */
@@ -66,10 +66,68 @@ ${credLines}
66
66
  (\`ia portal create-agent\`).
67
67
  `;
68
68
  }
69
+ /**
70
+ * Scaffold for the delivery SOP. Deliberately mostly questions: the SOP has to
71
+ * be written from the engagement the technician is actually in, and a
72
+ * confidently-worded template invites someone to leave the defaults in place.
73
+ * Contract: agents/AGENT.md § "The delivery SOP (`sop.md`) contract".
74
+ */
75
+ function sopScaffold(template, workflowName) {
76
+ return `# ${template} — delivery SOP
77
+
78
+ > Banked from n8n workflow “${workflowName}”. **This is a scaffold, not an
79
+ > SOP.** Fill it from the engagement you are in — a rollout method written
80
+ > from memory is the thing this file exists to prevent. Contract:
81
+ > \`agents/AGENT.md\` § *The delivery SOP contract*. Worked example:
82
+ > \`agents/email-gmail-triage/sop.md\`.
83
+
84
+ One paragraph: how many stages, roughly how long, and what the client has at
85
+ the end.
86
+
87
+ ## Preconditions
88
+
89
+ Credentials, access, client agreements, anything that must be pre-created.
90
+ A checklist. Anything missing here blocks stage 1.
91
+
92
+ - [ ] …
93
+
94
+ ## Stages
95
+
96
+ Does this automation write to a system the client depends on? Then it needs at
97
+ least an observe-only first stage and a full stage. "Deploy it and watch" is
98
+ not a stage. Selection is **one config value**, never a disabled node.
99
+
100
+ | Stage | Config value | What runs | Deliberately off | Exit gate |
101
+ |---|---|---|---|---|
102
+ | 1. | | | | |
103
+
104
+ ## Gate proof
105
+
106
+ Per promotion: the sample, the thresholds, the zero-tolerance list, and the
107
+ \`evidence/\` filename. **A gate with no number is not a gate.** Name the
108
+ errors that are never acceptable at any percentage.
109
+
110
+ ## Client comms
111
+
112
+ What we tell the client at each promotion, and over which channel. Use the
113
+ \`house-voice\` skill. A silent promotion is how a client finds out by
114
+ noticing something changed.
115
+
116
+ ## Steady state
117
+
118
+ After the last stage: who watches what, how often, and the one signal that
119
+ says it is still healthy.
120
+
121
+ ## Rollback
122
+
123
+ How to undo each stage, and the pause switch. Every action that looks
124
+ irreversible should be recoverable by one search or one config value.
125
+ `;
126
+ }
69
127
  /**
70
128
  * Bank a live n8n workflow: fetch by id, sanitize, write
71
- * agents/<template>/workflow.json (+ template.md scaffold on first save; an
72
- * existing manifest is never overwritten).
129
+ * agents/<template>/workflow.json (+ template.md and sop.md scaffolds on first
130
+ * save; existing files are never overwritten).
73
131
  */
74
132
  export async function saveAgentTemplate(input, opts = {}) {
75
133
  if (!SLUG_PATTERN.test(input.template)) {
@@ -105,6 +163,15 @@ export async function saveAgentTemplate(input, opts = {}) {
105
163
  await writeFile(manifestPath, manifestScaffold(input.template, workflow.name, strippedCredentials));
106
164
  manifestCreated = true;
107
165
  }
166
+ const sopPath = join(dir, "sop.md");
167
+ let sopCreated = false;
168
+ try {
169
+ await readFile(sopPath, "utf8");
170
+ }
171
+ catch {
172
+ await writeFile(sopPath, sopScaffold(input.template, workflow.name));
173
+ sopCreated = true;
174
+ }
108
175
  return {
109
176
  template: input.template,
110
177
  dir,
@@ -112,11 +179,15 @@ export async function saveAgentTemplate(input, opts = {}) {
112
179
  nodeCount: workflow.nodes.length,
113
180
  strippedCredentials,
114
181
  manifestCreated,
182
+ sopCreated,
115
183
  nextSteps: [
116
184
  "Review workflow.json for client-specific parameter values (replace with REPLACE_ME_*).",
117
185
  manifestCreated
118
186
  ? "Fill in the description paragraph in template.md."
119
187
  : "template.md already existed — confirm it still matches the export.",
188
+ sopCreated
189
+ ? "Fill in sop.md — stages, numbered gates, client comms, rollback. A template with an unfilled SOP is not deliverable (agents/AGENT.md)."
190
+ : "sop.md already existed — confirm its stages still match the export.",
120
191
  "Commit the template in the agents/ repo.",
121
192
  ],
122
193
  };
@@ -134,6 +205,17 @@ function manifestDescription(markdown) {
134
205
  }
135
206
  return null;
136
207
  }
208
+ // sopScaffold() hard-wraps this sentence inside a blockquote, so detection
209
+ // strips markdown quote/emphasis markup and collapses whitespace first.
210
+ const SOP_SCAFFOLD_MARKER = "This is a scaffold, not an SOP";
211
+ // Fallback for a scaffold whose intro was trimmed: the stage table still
212
+ // holds the empty placeholder row sopScaffold() wrote.
213
+ const SOP_EMPTY_STAGE_ROW = /^\|\s*1\.\s*\|\s*\|\s*\|\s*\|\s*\|\s*$/m;
214
+ /** True when sop.md is still the unfilled scaffold from sopScaffold(). */
215
+ function isSopScaffold(markdown) {
216
+ const normalized = markdown.replace(/[>*_`]/g, "").replace(/\s+/g, " ");
217
+ return normalized.includes(SOP_SCAFFOLD_MARKER) || SOP_EMPTY_STAGE_ROW.test(markdown);
218
+ }
137
219
  /** Catalog the bank: every agents/<slug>/ dir that holds a workflow.json. */
138
220
  export async function listAgentTemplates(opts = {}) {
139
221
  const dir = agentsDir(opts);
@@ -165,11 +247,99 @@ export async function listAgentTemplates(opts = {}) {
165
247
  catch {
166
248
  // manifest missing — listed anyway so `save` gaps are visible
167
249
  }
168
- templates.push({ slug: entry.name, workflowName, description, hasManifest });
250
+ let sopState = "missing";
251
+ try {
252
+ const sop = await readFile(join(dir, entry.name, "sop.md"), "utf8");
253
+ sopState = isSopScaffold(sop) ? "scaffold" : "filled";
254
+ }
255
+ catch {
256
+ // SOP missing — listed anyway; callers flag it as not-yet-deliverable
257
+ }
258
+ templates.push({
259
+ slug: entry.name,
260
+ workflowName,
261
+ description,
262
+ hasManifest,
263
+ hasSop: sopState === "filled",
264
+ sopState,
265
+ });
169
266
  }
170
267
  templates.sort((a, b) => a.slug.localeCompare(b.slug));
171
268
  return { agentsDir: dir, templates };
172
269
  }
270
+ const DEFAULT_SEARCH_LIMIT = 5;
271
+ const SNIPPET_RADIUS = 120;
272
+ function countOccurrences(text, term) {
273
+ return term ? text.split(term).length - 1 : 0;
274
+ }
275
+ function termSnippet(markdown, terms) {
276
+ const haystack = markdown.toLowerCase();
277
+ let index = -1;
278
+ for (const term of terms) {
279
+ index = haystack.indexOf(term);
280
+ if (index !== -1)
281
+ break;
282
+ }
283
+ if (index === -1)
284
+ return "";
285
+ const start = Math.max(0, index - SNIPPET_RADIUS);
286
+ const end = Math.min(markdown.length, index + SNIPPET_RADIUS);
287
+ const slice = markdown.slice(start, end).replace(/\s+/g, " ").trim();
288
+ return `${start > 0 ? "…" : ""}${slice}${end < markdown.length ? "…" : ""}`;
289
+ }
290
+ /**
291
+ * "Do we already have a workflow for X?" — rank banked templates against
292
+ * search terms, weighting slug + workflow-name hits over manifest-body hits
293
+ * (same scoring shape as docsSearch/clientBuild). Templates without a
294
+ * manifest still match on slug/name so `save` gaps stay findable.
295
+ */
296
+ export async function searchAgentTemplates(query, opts = {}) {
297
+ const trimmed = query.trim();
298
+ if (!trimmed) {
299
+ throw new Error("searchAgentTemplates needs a non-empty query — use listAgentTemplates for the full catalog.");
300
+ }
301
+ const { agentsDir: dir, templates } = await listAgentTemplates(opts);
302
+ const terms = trimmed.toLowerCase().split(/\s+/).filter(Boolean);
303
+ const limit = opts.limit ?? DEFAULT_SEARCH_LIMIT;
304
+ const scored = await Promise.all(templates.map(async (template) => {
305
+ let manifest = "";
306
+ if (template.hasManifest) {
307
+ try {
308
+ manifest = await readFile(join(dir, template.slug, "template.md"), "utf8");
309
+ }
310
+ catch {
311
+ // listed with hasManifest just above; a race here only costs the snippet
312
+ }
313
+ }
314
+ // A filled SOP is searched too, so rollout questions ("staged rollout",
315
+ // "soak week", "promotion gate") find the template that answers them.
316
+ // Scaffold-only SOPs are skipped — the boilerplate mentions stages,
317
+ // gates and rollback, so it would false-match every rollout query.
318
+ // The snippet still comes from the manifest — that's the front door.
319
+ let sop = "";
320
+ if (template.sopState === "filled") {
321
+ try {
322
+ sop = await readFile(join(dir, template.slug, "sop.md"), "utf8");
323
+ }
324
+ catch {
325
+ // same race as above; costs only this template's SOP-body score
326
+ }
327
+ }
328
+ const title = `${template.slug} ${template.workflowName}`.toLowerCase();
329
+ const body = `${manifest}\n${sop}`.toLowerCase();
330
+ let score = 0;
331
+ for (const term of terms) {
332
+ score += countOccurrences(title, term) * 5 + countOccurrences(body, term);
333
+ }
334
+ return { template, manifest, score };
335
+ }));
336
+ const matches = scored
337
+ .filter((entry) => entry.score > 0)
338
+ .sort((a, b) => b.score - a.score)
339
+ .slice(0, limit)
340
+ .map(({ template, manifest }) => ({ ...template, snippet: termSnippet(manifest, terms) }));
341
+ return { agentsDir: dir, query: trimmed, matches };
342
+ }
173
343
  /**
174
344
  * Start a client build from a banked template: copy its workflow.json to
175
345
  * <destDir>/<template>.json, ready to import into the client's n8n. Never
@@ -0,0 +1,26 @@
1
+ import { type ClientLinearProjectOptions } from "./client-linear.js";
2
+ import { type ProjectNode } from "./linear-project.js";
3
+ export interface ClientLinearCreateIssueInput {
4
+ /** Issue title; required, non-empty. */
5
+ title: string;
6
+ /** Optional markdown body. */
7
+ description?: string;
8
+ }
9
+ export interface ClientLinearCreateIssueResult {
10
+ project: ProjectNode;
11
+ issue: {
12
+ identifier: string;
13
+ title: string;
14
+ url: string;
15
+ };
16
+ }
17
+ /**
18
+ * Create one issue in a client's Linear project. The project is resolved
19
+ * exactly like `clientLinearProject` reads it — from the client's own
20
+ * CLIENT.md `linear_project` URL, never a typed or guessed name — so the
21
+ * issue can only land on that engagement's board. The team is taken from the
22
+ * resolved project itself (its first team), not from configuration, for the
23
+ * same reason. Issues land in the team's default state (triage/backlog);
24
+ * status moves stay a human act in Linear.
25
+ */
26
+ export declare function clientLinearCreateIssue(slug: string, input: ClientLinearCreateIssueInput, options?: ClientLinearProjectOptions): Promise<ClientLinearCreateIssueResult>;
@@ -0,0 +1,46 @@
1
+ import { resolveClientLinearProject } from "./client-linear.js";
2
+ import { linearRequest } from "./linear-project.js";
3
+ const PROJECT_TEAMS_QUERY = `
4
+ query ProjectTeams($id: String!) {
5
+ project(id: $id) {
6
+ teams(first: 1) { nodes { id } }
7
+ }
8
+ }
9
+ `;
10
+ const CREATE_ISSUE_MUTATION = `
11
+ mutation CreateIssue($input: IssueCreateInput!) {
12
+ issueCreate(input: $input) {
13
+ success
14
+ issue { identifier title url }
15
+ }
16
+ }
17
+ `;
18
+ /**
19
+ * Create one issue in a client's Linear project. The project is resolved
20
+ * exactly like `clientLinearProject` reads it — from the client's own
21
+ * CLIENT.md `linear_project` URL, never a typed or guessed name — so the
22
+ * issue can only land on that engagement's board. The team is taken from the
23
+ * resolved project itself (its first team), not from configuration, for the
24
+ * same reason. Issues land in the team's default state (triage/backlog);
25
+ * status moves stay a human act in Linear.
26
+ */
27
+ export async function clientLinearCreateIssue(slug, input, options = {}) {
28
+ const title = input.title.trim();
29
+ if (!title) {
30
+ throw new Error("clientLinearCreateIssue needs a non-empty issue title");
31
+ }
32
+ const description = input.description?.trim() || undefined;
33
+ const { project, linearToken, fetchImpl } = await resolveClientLinearProject(slug, options);
34
+ const teams = await linearRequest(fetchImpl, linearToken, PROJECT_TEAMS_QUERY, { id: project.id });
35
+ const teamId = teams.project?.teams.nodes[0]?.id;
36
+ if (!teamId) {
37
+ throw new Error(`Linear project "${project.name}" has no team — can't create an issue without one.`);
38
+ }
39
+ const created = await linearRequest(fetchImpl, linearToken, CREATE_ISSUE_MUTATION, {
40
+ input: { teamId, projectId: project.id, title, ...(description ? { description } : {}) },
41
+ });
42
+ if (!created.issueCreate.success || !created.issueCreate.issue) {
43
+ throw new Error(`Linear did not create the issue in "${project.name}" (success=false).`);
44
+ }
45
+ return { project, issue: created.issueCreate.issue };
46
+ }
@@ -1,5 +1,5 @@
1
1
  import type { ExecFileFn } from "./exec.js";
2
- import { type LinearProjectOptions, type LinearProjectResult } from "./linear-project.js";
2
+ import { type LinearProjectOptions, type LinearProjectResult, type ProjectNode } from "./linear-project.js";
3
3
  /** Thrown when the GitHub token is missing or rejected while fetching CLIENT.md. */
4
4
  export declare class ClientLinearAuthError extends Error {
5
5
  }
@@ -13,16 +13,35 @@ export interface ClientLinearProjectOptions extends LinearProjectOptions {
13
13
  /** Defaults to "client-". */
14
14
  repoPrefix?: string;
15
15
  }
16
+ /**
17
+ * The slug id is the segment right after /project/ — a copied URL often
18
+ * carries a view tail (".../project/<slugId>/overview" or "/issues"), which
19
+ * a naive last-segment parse mistakes for the id (found live 2026-08-22).
20
+ */
21
+ export declare function parseLinearProjectSlugId(url: string): string | undefined;
22
+ export interface ResolvedClientLinearProject {
23
+ project: ProjectNode;
24
+ /** The Linear API key that resolved the project — reuse it for follow-up calls. */
25
+ linearToken: string;
26
+ fetchImpl: typeof fetch;
27
+ }
28
+ /**
29
+ * Resolve a client engagement's Linear project from its own `CLIENT.md`
30
+ * `linear_project` field (a `linear.app/.../project/<slugId>` URL, read via
31
+ * the GitHub contents API — same source of truth `clientBuild` reads from,
32
+ * never cloned) rather than guessing from the client's name: Linear project
33
+ * display names don't reliably match a client slug (spacing, capitalization,
34
+ * rebrands), and a guessed name could silently resolve to the wrong project.
35
+ * Shared by `clientLinearProject` (reads) and `clientLinearCreateIssue`
36
+ * (the one write) so both hit the identical project, resolved the identical
37
+ * way.
38
+ */
39
+ export declare function resolveClientLinearProject(slug: string, options?: ClientLinearProjectOptions): Promise<ResolvedClientLinearProject>;
16
40
  /**
17
41
  * Open (not completed/canceled/duplicate) issues in a client's Linear
18
- * project — "what's left to do" for that engagement. The project is
19
- * resolved from the client's own `CLIENT.md` `linear_project` field (a
20
- * `linear.app/.../project/<slugId>` URL, read via the GitHub contents API —
21
- * same source of truth `clientBuild` reads from, never cloned) rather than
22
- * guessed from the client's name: Linear project display names don't
23
- * reliably match a client slug (spacing, capitalization, rebrands), and a
24
- * guessed name could silently resolve to the wrong project. Once resolved,
25
- * behaves exactly like `linearProject` — see `linearProjectIssues`.
42
+ * project — "what's left to do" for that engagement. Resolution is
43
+ * `resolveClientLinearProject` above; once resolved, behaves exactly like
44
+ * `linearProject` — see `linearProjectIssues`.
26
45
  *
27
46
  * Strictly read-only: never touches CLIENT.md or Linear beyond GraphQL
28
47
  * queries.
@@ -9,33 +9,42 @@ const LINEAR_PROJECT_FIELD_PATTERN = /^linear_project:\s*(\S+)\s*$/m;
9
9
  /** Thrown when the GitHub token is missing or rejected while fetching CLIENT.md. */
10
10
  export class ClientLinearAuthError extends Error {
11
11
  }
12
+ /**
13
+ * The slug id is the segment right after /project/ — a copied URL often
14
+ * carries a view tail (".../project/<slugId>/overview" or "/issues"), which
15
+ * a naive last-segment parse mistakes for the id (found live 2026-08-22).
16
+ */
17
+ export function parseLinearProjectSlugId(url) {
18
+ const segments = url.split("/").filter(Boolean);
19
+ const projectIndex = segments.lastIndexOf("project");
20
+ if (projectIndex !== -1 && segments[projectIndex + 1])
21
+ return segments[projectIndex + 1];
22
+ return segments.pop();
23
+ }
12
24
  function parseSlugId(clientMd, slug) {
13
25
  const match = clientMd.match(LINEAR_PROJECT_FIELD_PATTERN);
14
26
  if (!match) {
15
27
  throw new Error(`"${slug}"'s CLIENT.md has no linear_project field — can't resolve its Linear project.`);
16
28
  }
17
29
  const url = match[1];
18
- const slugId = url.split("/").filter(Boolean).pop();
30
+ const slugId = parseLinearProjectSlugId(url);
19
31
  if (!slugId) {
20
32
  throw new Error(`Could not parse a Linear project slug id out of "${url}" (from "${slug}"'s CLIENT.md).`);
21
33
  }
22
34
  return slugId;
23
35
  }
24
36
  /**
25
- * Open (not completed/canceled/duplicate) issues in a client's Linear
26
- * project — "what's left to do" for that engagement. The project is
27
- * resolved from the client's own `CLIENT.md` `linear_project` field (a
28
- * `linear.app/.../project/<slugId>` URL, read via the GitHub contents API —
29
- * same source of truth `clientBuild` reads from, never cloned) rather than
30
- * guessed from the client's name: Linear project display names don't
31
- * reliably match a client slug (spacing, capitalization, rebrands), and a
32
- * guessed name could silently resolve to the wrong project. Once resolved,
33
- * behaves exactly like `linearProject` — see `linearProjectIssues`.
34
- *
35
- * Strictly read-only: never touches CLIENT.md or Linear beyond GraphQL
36
- * queries.
37
+ * Resolve a client engagement's Linear project from its own `CLIENT.md`
38
+ * `linear_project` field (a `linear.app/.../project/<slugId>` URL, read via
39
+ * the GitHub contents API — same source of truth `clientBuild` reads from,
40
+ * never cloned) rather than guessing from the client's name: Linear project
41
+ * display names don't reliably match a client slug (spacing, capitalization,
42
+ * rebrands), and a guessed name could silently resolve to the wrong project.
43
+ * Shared by `clientLinearProject` (reads) and `clientLinearCreateIssue`
44
+ * (the one write) so both hit the identical project, resolved the identical
45
+ * way.
37
46
  */
38
- export async function clientLinearProject(slug, options = {}) {
47
+ export async function resolveClientLinearProject(slug, options = {}) {
39
48
  if (slug.startsWith("client-")) {
40
49
  throw new Error(`pass the bare slug ("${slug.slice("client-".length)}"), not "${slug}" — the repo prefix is added for you`);
41
50
  }
@@ -81,5 +90,18 @@ export async function clientLinearProject(slug, options = {}) {
81
90
  throw new LinearAuthError(`Linear API key required — set ${LINEAR_API_TOKEN_ENV} (a personal API key with read access) or pass token`);
82
91
  }
83
92
  const project = await findProjectBySlugId(fetchImpl, linearToken, slugId);
93
+ return { project, linearToken, fetchImpl };
94
+ }
95
+ /**
96
+ * Open (not completed/canceled/duplicate) issues in a client's Linear
97
+ * project — "what's left to do" for that engagement. Resolution is
98
+ * `resolveClientLinearProject` above; once resolved, behaves exactly like
99
+ * `linearProject` — see `linearProjectIssues`.
100
+ *
101
+ * Strictly read-only: never touches CLIENT.md or Linear beyond GraphQL
102
+ * queries.
103
+ */
104
+ export async function clientLinearProject(slug, options = {}) {
105
+ const { project, linearToken, fetchImpl } = await resolveClientLinearProject(slug, options);
84
106
  return linearProjectIssues(fetchImpl, linearToken, project, options);
85
107
  }
@@ -1,5 +1,12 @@
1
1
  export declare const TEAM_DOCS_BASE_URL = "https://team.installagent.com";
2
2
  export declare const DOCS_SESSION_ENV = "IA_DOCS_SESSION";
3
+ /**
4
+ * Shared bearer token for the /api/search endpoint — the same value as the
5
+ * docs app's IA_DOCS_SEARCH_TOKEN deployment env (see team-web
6
+ * apps/docs/lib/access.ts). Unlike the session cookie it never expires, so
7
+ * it's the right credential for headless callers (the Slack agent, CI).
8
+ */
9
+ export declare const DOCS_SEARCH_TOKEN_ENV = "IA_DOCS_SEARCH_TOKEN";
3
10
  export interface DocsSearchResult {
4
11
  title: string;
5
12
  url: string;
@@ -19,7 +26,13 @@ export interface DocsSearchOptions {
19
26
  baseUrl?: string;
20
27
  limit?: number;
21
28
  /**
22
- * Session for the crawl fallback: either the raw value of the
29
+ * Bearer token for the /api/search endpoint. Preferred over the session
30
+ * cookie when both are set. Defaults to the IA_DOCS_SEARCH_TOKEN env var.
31
+ */
32
+ token?: string;
33
+ /**
34
+ * Browser session, used as the /api/search credential when no token is set
35
+ * and for the crawl fallback: either the raw value of the
23
36
  * __Secure-authjs.session-token cookie or a full Cookie header string.
24
37
  * Defaults to the IA_DOCS_SESSION env var.
25
38
  */
@@ -35,10 +48,10 @@ export declare class DocsSessionError extends Error {
35
48
  * results can't drift from what's deployed and don't require a team-web
36
49
  * checkout.
37
50
  *
38
- * Tries the standard Fumadocs search endpoint (/api/search) first so we
39
- * automatically upgrade the moment team-web deploys one. Today that route
40
- * does not exist (the docs app registers only /api/auth/*), so we fall back
41
- * to crawling the SSO-gated /docs pages with the technician's own session
42
- * cookie and ranking them client-side.
51
+ * Tries the Fumadocs search endpoint (/api/search) first — the docs app
52
+ * gates it on a NextAuth session OR the shared IA_DOCS_SEARCH_TOKEN bearer,
53
+ * so either credential gets real full-text search. When the endpoint says no
54
+ * (or is unreachable), we fall back to crawling the SSO-gated /docs pages
55
+ * with the session cookie and ranking them client-side.
43
56
  */
44
57
  export declare function docsSearch(query: string, options?: DocsSearchOptions): Promise<DocsSearchResponse>;
@@ -2,6 +2,13 @@ export const TEAM_DOCS_BASE_URL = "https://team.installagent.com";
2
2
  /** NextAuth v5 production session cookie on team.installagent.com. */
3
3
  const SESSION_COOKIE = "__Secure-authjs.session-token";
4
4
  export const DOCS_SESSION_ENV = "IA_DOCS_SESSION";
5
+ /**
6
+ * Shared bearer token for the /api/search endpoint — the same value as the
7
+ * docs app's IA_DOCS_SEARCH_TOKEN deployment env (see team-web
8
+ * apps/docs/lib/access.ts). Unlike the session cookie it never expires, so
9
+ * it's the right credential for headless callers (the Slack agent, CI).
10
+ */
11
+ export const DOCS_SEARCH_TOKEN_ENV = "IA_DOCS_SEARCH_TOKEN";
5
12
  const CONCURRENCY = 8;
6
13
  /** Thrown when the crawl fallback has no usable Google SSO session. */
7
14
  export class DocsSessionError extends Error {
@@ -11,11 +18,11 @@ export class DocsSessionError extends Error {
11
18
  * results can't drift from what's deployed and don't require a team-web
12
19
  * checkout.
13
20
  *
14
- * Tries the standard Fumadocs search endpoint (/api/search) first so we
15
- * automatically upgrade the moment team-web deploys one. Today that route
16
- * does not exist (the docs app registers only /api/auth/*), so we fall back
17
- * to crawling the SSO-gated /docs pages with the technician's own session
18
- * cookie and ranking them client-side.
21
+ * Tries the Fumadocs search endpoint (/api/search) first — the docs app
22
+ * gates it on a NextAuth session OR the shared IA_DOCS_SEARCH_TOKEN bearer,
23
+ * so either credential gets real full-text search. When the endpoint says no
24
+ * (or is unreachable), we fall back to crawling the SSO-gated /docs pages
25
+ * with the session cookie and ranking them client-side.
19
26
  */
20
27
  export async function docsSearch(query, options = {}) {
21
28
  const q = query.trim();
@@ -25,14 +32,26 @@ export async function docsSearch(query, options = {}) {
25
32
  const base = (options.baseUrl ?? TEAM_DOCS_BASE_URL).replace(/\/+$/, "");
26
33
  const limit = options.limit ?? 8;
27
34
  const fetchImpl = options.fetchImpl ?? fetch;
28
- const apiResults = await tryApiSearch(fetchImpl, base, q);
35
+ const token = options.token ?? process.env[DOCS_SEARCH_TOKEN_ENV];
36
+ const session = options.session ?? process.env[DOCS_SESSION_ENV];
37
+ const apiResults = await tryApiSearch(fetchImpl, base, q, searchAuthHeaders(token, session));
29
38
  if (apiResults) {
30
39
  return { query: q, source: "api", results: apiResults.slice(0, limit) };
31
40
  }
32
- const session = options.session ?? process.env[DOCS_SESSION_ENV];
33
41
  const results = await crawlSearch(fetchImpl, base, q, limit, session);
34
42
  return { query: q, source: "crawl", results };
35
43
  }
44
+ /** The bearer token wins when both are set: it never expires, the cookie does. */
45
+ function searchAuthHeaders(token, session) {
46
+ if (token)
47
+ return { authorization: `Bearer ${token}` };
48
+ if (session)
49
+ return { cookie: sessionCookieHeader(session) };
50
+ return {};
51
+ }
52
+ function sessionCookieHeader(session) {
53
+ return session.includes("=") ? session : `${SESSION_COOKIE}=${session}`;
54
+ }
36
55
  function isFumadocsEntry(value) {
37
56
  if (typeof value !== "object" || value === null)
38
57
  return false;
@@ -41,10 +60,11 @@ function isFumadocsEntry(value) {
41
60
  typeof entry.type === "string" &&
42
61
  typeof entry.content === "string");
43
62
  }
44
- async function tryApiSearch(fetchImpl, base, query) {
63
+ async function tryApiSearch(fetchImpl, base, query, headers) {
45
64
  let data;
46
65
  try {
47
66
  const res = await fetchImpl(`${base}/api/search?query=${encodeURIComponent(query)}`, {
67
+ headers,
48
68
  redirect: "manual",
49
69
  });
50
70
  if (!res.ok)
@@ -85,14 +105,15 @@ async function tryApiSearch(fetchImpl, base, query) {
85
105
  async function crawlSearch(fetchImpl, base, query, limit, session) {
86
106
  if (!session) {
87
107
  throw new DocsSessionError([
88
- `The team docs (${base}) are gated by Google SSO and expose no public search endpoint, so searching needs your browser session.`,
108
+ `The team docs (${base}) are gated, so searching needs a credential.`,
109
+ `Preferred: set ${DOCS_SEARCH_TOKEN_ENV} to the shared docs-search bearer token — \`ia env fill\` reads it from 1Password, and it never expires.`,
110
+ `Or use your own browser session (expires periodically):`,
89
111
  `1. Open ${base} in your browser and sign in with your @installagent.com account.`,
90
112
  `2. DevTools → Application → Cookies → copy the value of ${SESSION_COOKIE}.`,
91
113
  `3. export ${DOCS_SESSION_ENV}="<that value>" (or pass --session).`,
92
114
  ].join("\n"));
93
115
  }
94
- const cookie = session.includes("=") ? session : `${SESSION_COOKIE}=${session}`;
95
- const headers = { cookie };
116
+ const headers = { cookie: sessionCookieHeader(session) };
96
117
  const rootRes = await fetchImpl(`${base}/docs`, { headers, redirect: "manual" });
97
118
  if (rootRes.status >= 300 && rootRes.status < 400) {
98
119
  throw new DocsSessionError(`Your docs session was rejected (redirected to login). Grab a fresh ${SESSION_COOKIE} cookie from ${base} and update ${DOCS_SESSION_ENV}.`);
package/dist/doctor.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { type ExecFileFn } from "./exec.js";
2
+ import { type PlatformInfo } from "./platform.js";
2
3
  export interface DoctorOptions {
3
4
  /** installagent/ workspace root to inspect. Defaults to the current dir. */
4
5
  workspaceDir?: string;
@@ -10,6 +11,8 @@ export interface DoctorOptions {
10
11
  offline?: boolean;
11
12
  /** Injectable for tests; defaults to global fetch. */
12
13
  fetchImpl?: typeof fetch;
14
+ /** Injectable for tests; defaults to the running machine. Picks fix-it text. */
15
+ platform?: PlatformInfo;
13
16
  }
14
17
  export type DoctorStatus = "ok" | "missing" | "warn";
15
18
  export interface DoctorCheck {
@@ -21,6 +24,12 @@ export interface DoctorCheck {
21
24
  detail: string;
22
25
  /** Concrete next step when the check isn't ok. */
23
26
  fixIt?: string;
27
+ /**
28
+ * Background detail, not part of the daily checkup — printed only by
29
+ * `ia doctor --all`. The check still travels in the result so MCP callers
30
+ * and the wizard see everything; only the default human view hides it.
31
+ */
32
+ verboseOnly?: boolean;
24
33
  }
25
34
  export interface DoctorResult {
26
35
  /** True when nothing is `missing` — warnings don't fail the checkup. */