@installagent/sdk 0.1.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.
Files changed (114) hide show
  1. package/dist/agent-mirror.d.ts +69 -0
  2. package/dist/agent-mirror.js +275 -0
  3. package/dist/agent-templates.d.ts +36 -2
  4. package/dist/agent-templates.js +173 -3
  5. package/dist/claude-hours.d.ts +118 -0
  6. package/dist/claude-hours.js +523 -0
  7. package/dist/client-drive.d.ts +3 -0
  8. package/dist/client-drive.js +2 -2
  9. package/dist/client-linear-create.d.ts +26 -0
  10. package/dist/client-linear-create.js +46 -0
  11. package/dist/client-linear.d.ts +28 -9
  12. package/dist/client-linear.js +36 -14
  13. package/dist/docs-search.d.ts +19 -6
  14. package/dist/docs-search.js +32 -11
  15. package/dist/doctor.d.ts +9 -0
  16. package/dist/doctor.js +126 -23
  17. package/dist/env-fill.d.ts +13 -0
  18. package/dist/env-fill.js +55 -13
  19. package/dist/env-push.d.ts +3 -0
  20. package/dist/env-push.js +11 -6
  21. package/dist/env-registry.d.ts +29 -0
  22. package/dist/env-registry.js +123 -9
  23. package/dist/exec.js +15 -2
  24. package/dist/git.d.ts +31 -0
  25. package/dist/git.js +59 -0
  26. package/dist/google-service-account.d.ts +20 -0
  27. package/dist/google-service-account.js +49 -0
  28. package/dist/hours-estimate.d.ts +43 -0
  29. package/dist/hours-estimate.js +159 -0
  30. package/dist/hours-export-schedule.d.ts +35 -0
  31. package/dist/hours-export-schedule.js +188 -0
  32. package/dist/hours-ledger.d.ts +129 -0
  33. package/dist/hours-ledger.js +882 -0
  34. package/dist/index.d.ts +25 -6
  35. package/dist/index.js +25 -6
  36. package/dist/linear-project.d.ts +2 -2
  37. package/dist/linear-project.js +2 -2
  38. package/dist/log.d.ts +28 -0
  39. package/dist/log.js +73 -0
  40. package/dist/n8n-executions.d.ts +85 -0
  41. package/dist/n8n-executions.js +259 -0
  42. package/dist/op-cli.d.ts +29 -0
  43. package/dist/op-cli.js +52 -0
  44. package/dist/platform.d.ts +35 -0
  45. package/dist/platform.js +39 -0
  46. package/dist/portal-admin.d.ts +108 -0
  47. package/dist/portal-admin.js +94 -1
  48. package/dist/standup.d.ts +88 -0
  49. package/dist/standup.js +235 -0
  50. package/dist/sync-repos.d.ts +54 -0
  51. package/dist/sync-repos.js +89 -0
  52. package/dist/template-sync.d.ts +11 -0
  53. package/dist/template-sync.js +16 -0
  54. package/dist/triage-backfill.d.ts +37 -0
  55. package/dist/triage-backfill.js +211 -0
  56. package/dist/triage-enable.d.ts +90 -0
  57. package/dist/triage-enable.js +428 -0
  58. package/dist/triage-gates.d.ts +252 -0
  59. package/dist/triage-gates.js +951 -0
  60. package/dist/wizard.d.ts +15 -0
  61. package/dist/wizard.js +35 -56
  62. package/dist/workspace-docs.d.ts +44 -0
  63. package/dist/workspace-docs.js +73 -0
  64. package/dist/workspace-push.d.ts +39 -0
  65. package/dist/workspace-push.js +78 -0
  66. package/dist/workspace-status.d.ts +37 -0
  67. package/dist/workspace-status.js +114 -0
  68. package/package.json +2 -2
  69. package/templates/env.example +37 -23
  70. package/templates/workspace-root/.claude/settings.json +12 -1
  71. package/templates/workspace-root/AGENT.md +7 -5
  72. package/templates/workspace-root/ONBOARDING.md +65 -8
  73. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +127 -0
  74. package/templates/workspace-root/skills/CLAUDE.md +29 -6
  75. package/templates/workspace-root/skills/README.md +171 -0
  76. package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
  77. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
  78. package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
  79. package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
  80. package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
  81. package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
  82. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
  83. package/templates/workspace-root/skills/client-latest/SKILL.md +343 -0
  84. package/templates/workspace-root/skills/client-latest/catchup.command.md +18 -0
  85. package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
  86. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +258 -0
  87. package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
  88. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
  89. package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
  90. package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
  91. package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
  92. package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
  93. package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
  94. package/templates/workspace-root/skills/ia-cli/SKILL.md +49 -7
  95. package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
  96. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
  97. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
  98. package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
  99. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
  100. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
  101. package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
  102. package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
  103. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
  104. package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
  105. package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
  106. package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
  107. package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
  108. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
  109. package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
  110. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
  111. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
  112. package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
  113. package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
  114. package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
@@ -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. */
package/dist/doctor.js CHANGED
@@ -2,12 +2,14 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
2
2
  import { join, resolve } from "node:path";
3
3
  import { N8N_API_KEY_ENV, N8N_API_URL_ENV } from "./agent-templates.js";
4
4
  import { AIRTABLE_API_TOKEN_ENV, GOOGLE_SERVICE_ACCOUNT_KEY_ENV } from "./client-drive.js";
5
- import { DOCS_SESSION_ENV, TEAM_DOCS_BASE_URL } from "./docs-search.js";
5
+ import { DOCS_SEARCH_TOKEN_ENV, DOCS_SESSION_ENV, TEAM_DOCS_BASE_URL } from "./docs-search.js";
6
6
  import { parseEnvFile } from "./env-file.js";
7
- import { DEFAULT_TECH_VAULT, ENV_VARS, opSecretReference, } from "./env-registry.js";
7
+ import { DEFAULT_TECH_VAULT, opSecretReference, TECH_ENV_VARS, } from "./env-registry.js";
8
8
  import { execFailureDetail, execFileAsync } from "./exec.js";
9
9
  import { GITHUB_API_TOKEN_ENV, GITHUB_TOKEN_FIX } from "./github-token.js";
10
10
  import { LINEAR_API_TOKEN_ENV } from "./linear-project.js";
11
+ import { opInstallFix, opIntegrationFix } from "./op-cli.js";
12
+ import { detectPlatformInfo } from "./platform.js";
11
13
  const WORKSPACE_CHECKS = [
12
14
  {
13
15
  name: "team-clients",
@@ -72,6 +74,7 @@ export async function doctor(options = {}) {
72
74
  const execFileImpl = options.execFileImpl ?? execFileAsync;
73
75
  const fetchImpl = options.fetchImpl ?? fetch;
74
76
  const offline = options.offline ?? false;
77
+ const platform = options.platform ?? detectPlatformInfo();
75
78
  const checks = [];
76
79
  for (const spec of WORKSPACE_CHECKS) {
77
80
  const present = existsSync(join(workspaceDir, spec.relPath));
@@ -90,22 +93,26 @@ export async function doctor(options = {}) {
90
93
  const envFreshness = envFreshnessCheck(workspaceDir);
91
94
  if (envFreshness)
92
95
  checks.push(envFreshness);
93
- checks.push(await ghCheck(execFileImpl, env));
94
- checks.push(await opCheck(execFileImpl));
96
+ checks.push(await ghCheck(execFileImpl, env, platform));
97
+ checks.push(await opCheck(execFileImpl, platform));
95
98
  checks.push(await gcloudCheck(execFileImpl));
96
- for (const spec of ENV_VARS) {
99
+ // Technician vars only. Admin vars are all doctor:false today, so this
100
+ // changes nothing now — it is here so that adding a doctor:true infra var
101
+ // later cannot start naming it in every technician's checkup.
102
+ for (const spec of TECH_ENV_VARS) {
97
103
  if (!spec.doctor)
98
104
  continue;
99
105
  const value = env[spec.name];
100
106
  const present = typeof value === "string" && value.length > 0;
101
107
  if (!present) {
108
+ const covered = spec.coveredBy && env[spec.coveredBy];
102
109
  checks.push({
103
110
  id: `env/${spec.name}`,
104
111
  group: "env",
105
- status: spec.tier === "required" ? "missing" : "warn",
112
+ status: covered ? "ok" : spec.tier === "required" ? "missing" : "warn",
106
113
  label: `$${spec.name}`,
107
- detail: "not set",
108
- fixIt: envFixIt(spec),
114
+ detail: covered ? `not set — $${spec.coveredBy} covers ${spec.neededBy}` : "not set",
115
+ ...(covered ? {} : { fixIt: envFixIt(spec) }),
109
116
  });
110
117
  continue;
111
118
  }
@@ -163,7 +170,9 @@ function lefthookCheck(workspaceDir) {
163
170
  ...base,
164
171
  status: "warn",
165
172
  detail: `${unhooked.length} of ${gitRepos.length} client repo(s) missing the lefthook pre-commit hook: ${unhooked.join(", ")}`,
166
- fixIt: "hooks are per-clone — run `lefthook install` inside each listed repo (repo-lint never runs without it)",
173
+ fixIt: "hooks are per-clone — run `npx lefthook install` inside each listed repo (client repos carry no " +
174
+ "package.json, so there is no local lefthook to call; npx fetches it. `npx` ships with Node, so the " +
175
+ "same command works in PowerShell, cmd and any POSIX shell). repo-lint never runs without it",
167
176
  };
168
177
  }
169
178
  /**
@@ -177,7 +186,11 @@ function envFreshnessCheck(workspaceDir) {
177
186
  if (!existsSync(envPath))
178
187
  return null; // the root-env workspace check already covers absence
179
188
  const presentNames = new Set(Object.keys(parseEnvFile(readFileSync(envPath, "utf8"))));
180
- const missing = ENV_VARS.map((spec) => spec.name).filter((name) => !presentNames.has(name));
189
+ // Technician vars only. The admin block ships commented out in
190
+ // env.example, so parseEnvFile never sees it — comparing against the whole
191
+ // registry would report 21 permanent "missing" lines and name every
192
+ // payments and database secret while doing it.
193
+ const missing = TECH_ENV_VARS.map((spec) => spec.name).filter((name) => !presentNames.has(name));
181
194
  const base = {
182
195
  id: "workspace/env-freshness",
183
196
  group: "workspace",
@@ -190,7 +203,7 @@ function envFreshnessCheck(workspaceDir) {
190
203
  ...base,
191
204
  status: "warn",
192
205
  detail: `missing ${missing.length} var line(s) added since it was created: ${missing.join(", ")}`,
193
- fixIt: "add the missing lines from .env.example (`ia wizard --update` refreshes it), then `ia env fill`",
206
+ fixIt: "add the missing lines from .env.example (`ia sync --docs` refreshes it), then `ia env fill`",
194
207
  };
195
208
  }
196
209
  const LIVE_CHECK_TIMEOUT_MS = 5000;
@@ -225,6 +238,20 @@ const LIVE_VALIDATORS = {
225
238
  return { outcome: "invalid", detail: `Airtable rejected it (HTTP ${res.status})` };
226
239
  return { outcome: "valid", detail: "Airtable accepts it" };
227
240
  },
241
+ [DOCS_SEARCH_TOKEN_ENV]: async (value, _env, fetchImpl) => {
242
+ const res = await fetchImpl(`${TEAM_DOCS_BASE_URL}/api/search?query=doctor`, {
243
+ headers: { authorization: `Bearer ${value}` },
244
+ redirect: "manual",
245
+ signal: AbortSignal.timeout(LIVE_CHECK_TIMEOUT_MS),
246
+ });
247
+ if (!res.ok) {
248
+ return {
249
+ outcome: "invalid",
250
+ detail: `the docs search API rejected it (HTTP ${res.status})`,
251
+ };
252
+ }
253
+ return { outcome: "valid", detail: "the docs search API accepts it" };
254
+ },
228
255
  [DOCS_SESSION_ENV]: async (value, _env, fetchImpl) => {
229
256
  const res = await fetchImpl(`${TEAM_DOCS_BASE_URL}/docs`, {
230
257
  headers: { cookie: `__Secure-authjs.session-token=${value}` },
@@ -313,13 +340,21 @@ function isServiceAccountKey(value) {
313
340
  }
314
341
  }
315
342
  const GH_NEEDED_BY = "ia client-build, client-linear, client-intake";
343
+ /** The package-manager one-liner that puts `gh` on PATH for this platform. */
344
+ function ghInstallCommand(platform) {
345
+ if (platform.platform === "win32")
346
+ return "`winget install GitHub.cli` from PowerShell";
347
+ if (platform.platform === "linux")
348
+ return "see cli.github.com";
349
+ return "`brew install gh`";
350
+ }
316
351
  /**
317
352
  * GitHub auth: `gh auth status` is the day-one path (OAuth, no PAT, no
318
353
  * org-approval wait); a set $GITHUB_API_TOKEN passes too, as an override.
319
354
  * This check carries the required-ness — there is no env check for the
320
355
  * override var.
321
356
  */
322
- async function ghCheck(execFileImpl, env) {
357
+ async function ghCheck(execFileImpl, env, platform) {
323
358
  const base = { id: "tools/gh", group: "tools", label: "GitHub auth (gh CLI)" };
324
359
  const override = env[GITHUB_API_TOKEN_ENV];
325
360
  try {
@@ -341,7 +376,7 @@ async function ghCheck(execFileImpl, env) {
341
376
  ...base,
342
377
  status: "missing",
343
378
  detail: ghState,
344
- fixIt: `needed by ${GH_NEEDED_BY} — install the GitHub CLI (\`brew install gh\`), then ${GITHUB_TOKEN_FIX}`,
379
+ fixIt: `needed by ${GH_NEEDED_BY} — install the GitHub CLI (${ghInstallCommand(platform)}), then ${GITHUB_TOKEN_FIX}`,
345
380
  };
346
381
  }
347
382
  return {
@@ -356,7 +391,7 @@ async function ghCheck(execFileImpl, env) {
356
391
  * 1Password CLI: powers `ia env fill` (shared secrets come from the team
357
392
  * vaults). Warn-only — a technician can still fill .env by hand.
358
393
  */
359
- async function opCheck(execFileImpl) {
394
+ async function opCheck(execFileImpl, platform) {
360
395
  const base = { id: "tools/op", group: "tools", label: "1Password CLI (op)" };
361
396
  try {
362
397
  const { stdout } = await execFileImpl("op", ["whoami"]);
@@ -374,28 +409,56 @@ async function opCheck(execFileImpl) {
374
409
  ...base,
375
410
  status: "warn",
376
411
  detail: "op CLI not found on PATH",
377
- fixIt: "needed by `ia env fill` — install it (`brew install 1password-cli`), run `op signin`, then `ia env fill`",
412
+ fixIt: `needed by \`ia env fill\` — ${opInstallFix(platform)}`,
378
413
  };
379
414
  }
380
415
  return {
381
416
  ...base,
382
417
  status: "warn",
383
- detail: "op is installed but not signed in",
384
- fixIt: `run \`op signin\` (the shared ia secrets live in the ${DEFAULT_TECH_VAULT} vault), then \`ia env fill\``,
418
+ detail: "op is installed but not authenticated",
419
+ fixIt: `needed by \`ia env fill\` (it reads the ${DEFAULT_TECH_VAULT} vault) — ${opIntegrationFix(platform)}`,
385
420
  };
386
421
  }
387
422
  }
423
+ /**
424
+ * gcloud is needed by `ia secrets mint gcp-service-account-key` and nothing
425
+ * else, so it is `verboseOnly` — it warned in every technician's daily
426
+ * checkup and told them to install a 400 MB SDK for a command most of them
427
+ * will never run. `ia doctor --all` still shows it, and the mint command
428
+ * fails with its own message if gcloud really is absent.
429
+ *
430
+ * Also flags the multi-tenant risk the `gcloud-cli-setup` skill exists for:
431
+ * once more than one account is credentialed on the machine (two clients'
432
+ * GCP projects), running off the unnamed `default` configuration means a
433
+ * stray command can land on the wrong client's project with no warning.
434
+ * `gcloud config configurations list` is a second, best-effort call — its
435
+ * failure (e.g. an ancient gcloud without the `configurations` group)
436
+ * degrades to the plain authenticated-account result, never to a false
437
+ * failure of this check.
438
+ */
388
439
  async function gcloudCheck(execFileImpl) {
389
- const base = { id: "tools/gcloud", group: "tools", label: "gcloud CLI" };
440
+ const base = {
441
+ id: "tools/gcloud",
442
+ group: "tools",
443
+ label: "gcloud CLI",
444
+ verboseOnly: true,
445
+ };
390
446
  try {
391
447
  const { stdout } = await execFileImpl("gcloud", [
392
448
  "auth",
393
449
  "list",
394
- "--filter=status:ACTIVE",
395
- "--format=value(account)",
450
+ "--format=value(account,status)",
396
451
  ]);
397
- const account = stdout.trim().split("\n")[0] ?? "";
398
- if (account.length === 0) {
452
+ const accounts = stdout
453
+ .trim()
454
+ .split("\n")
455
+ .filter((line) => line.length > 0)
456
+ .map((line) => {
457
+ const [account = "", status = ""] = line.split("\t");
458
+ return { account, active: status.trim().toUpperCase() === "ACTIVE" };
459
+ });
460
+ const active = accounts.find((a) => a.active);
461
+ if (!active) {
399
462
  return {
400
463
  ...base,
401
464
  status: "warn",
@@ -403,7 +466,47 @@ async function gcloudCheck(execFileImpl) {
403
466
  fixIt: "only needed for `ia secrets mint gcp-*` — run `gcloud auth login`",
404
467
  };
405
468
  }
406
- return { ...base, status: "ok", detail: `authenticated as ${account}` };
469
+ let activeConfigName;
470
+ try {
471
+ const { stdout: configStdout } = await execFileImpl("gcloud", [
472
+ "config",
473
+ "configurations",
474
+ "list",
475
+ "--format=value(name,is_active)",
476
+ ]);
477
+ const configs = configStdout
478
+ .trim()
479
+ .split("\n")
480
+ .filter((line) => line.length > 0)
481
+ .map((line) => {
482
+ const [name = "", isActive = ""] = line.split("\t");
483
+ return { name, active: isActive.trim().toLowerCase() === "true" };
484
+ });
485
+ activeConfigName = configs.find((c) => c.active)?.name;
486
+ }
487
+ catch {
488
+ // Best-effort — an older gcloud without `configurations` still gets a
489
+ // plain "authenticated as" result below, not a failure.
490
+ }
491
+ if (accounts.length > 1 && (activeConfigName ?? "default") === "default") {
492
+ return {
493
+ ...base,
494
+ status: "warn",
495
+ detail: `authenticated as ${active.account}, but running off the unnamed "default" gcloud ` +
496
+ `configuration with ${accounts.length} accounts on this machine — a stray command can ` +
497
+ "hit the wrong client's project",
498
+ fixIt: "one named gcloud configuration per client (see the gcloud-cli-setup skill): " +
499
+ "`gcloud config configurations create <name> && gcloud config configurations activate <name> " +
500
+ "&& gcloud config set account <email>`",
501
+ };
502
+ }
503
+ return {
504
+ ...base,
505
+ status: "ok",
506
+ detail: activeConfigName
507
+ ? `authenticated as ${active.account} (configuration "${activeConfigName}")`
508
+ : `authenticated as ${active.account}`,
509
+ };
407
510
  }
408
511
  catch (error) {
409
512
  const { code, detail } = execFailureDetail(error);