@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
@@ -1,4 +1,5 @@
1
1
  import { type ExecFileFn } from "./exec.js";
2
+ import { type PlatformInfo } from "./platform.js";
2
3
  export interface EnvFillOptions {
3
4
  /** installagent/ workspace root holding the .env. Defaults to the current dir. */
4
5
  workspaceDir?: string;
@@ -6,6 +7,13 @@ export interface EnvFillOptions {
6
7
  dryRun?: boolean;
7
8
  /** Read every vault var from this vault instead of its registry vault. */
8
9
  vaultOverride?: string;
10
+ /**
11
+ * Also attempt the admin vars (infra, portal, payments). Default false:
12
+ * a technician's run never names a secret they hold no grant to.
13
+ */
14
+ includeAdmin?: boolean;
15
+ /** Injectable for tests; defaults to the running machine. Picks the op fix-it text. */
16
+ platform?: PlatformInfo;
9
17
  /** Injectable for tests; defaults to real `op` via execFile. */
10
18
  execFileImpl?: ExecFileFn;
11
19
  }
@@ -29,6 +37,11 @@ export interface EnvFillResult {
29
37
  name: string;
30
38
  howToGet: string;
31
39
  }>;
40
+ /**
41
+ * How many admin vars this run deliberately did not attempt. Reported as a
42
+ * single count, never as a list of names — see EnvVarRole.
43
+ */
44
+ adminSkipped: number;
32
45
  nextSteps: string[];
33
46
  }
34
47
  /**
package/dist/env-fill.js CHANGED
@@ -2,8 +2,10 @@ import { existsSync } from "node:fs";
2
2
  import { copyFile, readFile, writeFile } from "node:fs/promises";
3
3
  import { join, resolve } from "node:path";
4
4
  import { parseEnvFile } from "./env-file.js";
5
- import { DEFAULT_TECH_VAULT, ENV_VARS } from "./env-registry.js";
5
+ import { ADMIN_ENV_VARS, DEFAULT_TECH_VAULT, envVarsForRole, TECH_ENV_VARS, } from "./env-registry.js";
6
6
  import { execFailureDetail, execFileAsync } from "./exec.js";
7
+ import { opInstallFix, opIntegrationFix } from "./op-cli.js";
8
+ import { detectPlatformInfo } from "./platform.js";
7
9
  import { envExampleTemplatePath } from "./templates.js";
8
10
  /** Values op read fields are tried in when the registry doesn't pin one. */
9
11
  const OP_FIELD_FALLBACKS = ["value", "credential", "password"];
@@ -22,8 +24,11 @@ export async function envFill(options = {}) {
22
24
  const workspaceDir = resolve(options.workspaceDir ?? ".");
23
25
  const dryRun = options.dryRun ?? false;
24
26
  const execFileImpl = options.execFileImpl ?? execFileAsync;
27
+ const includeAdmin = options.includeAdmin ?? false;
28
+ const platform = options.platform ?? detectPlatformInfo();
25
29
  const envPath = join(workspaceDir, ".env");
26
- const opReady = await opPreflight(execFileImpl);
30
+ const adminSkipped = includeAdmin ? 0 : ADMIN_ENV_VARS.length;
31
+ const opReady = await opPreflight(execFileImpl, platform);
27
32
  if (opReady !== true) {
28
33
  return {
29
34
  ok: false,
@@ -32,6 +37,7 @@ export async function envFill(options = {}) {
32
37
  created: false,
33
38
  vars: [],
34
39
  personalRemaining: personalHomework({}),
40
+ adminSkipped,
35
41
  nextSteps: [opReady, "then re-run `ia env fill`"],
36
42
  };
37
43
  }
@@ -47,7 +53,7 @@ export async function envFill(options = {}) {
47
53
  const existing = parseEnvFile(original);
48
54
  const vars = [];
49
55
  const fills = new Map();
50
- for (const spec of ENV_VARS) {
56
+ for (const spec of envVarsForRole(includeAdmin)) {
51
57
  const current = existing[spec.name];
52
58
  if (typeof current === "string" && current.length > 0) {
53
59
  vars.push({ name: spec.name, status: "kept", detail: "already set — left untouched" });
@@ -98,21 +104,40 @@ export async function envFill(options = {}) {
98
104
  created,
99
105
  vars,
100
106
  personalRemaining,
107
+ adminSkipped,
101
108
  nextSteps,
102
109
  };
103
110
  }
104
- /** True when op is installed and signed in; otherwise the fix-it next step. */
105
- async function opPreflight(execFileImpl) {
111
+ /**
112
+ * True when op is installed and can reach the vaults; otherwise the fix-it step.
113
+ *
114
+ * `op whoami` is the obvious probe but NOT a sufficient one: with the desktop
115
+ * app integration on, op 2.35 answers "account is not signed in" to `whoami`
116
+ * while `op read` and `op vault list` both work — the CLI has no session of its
117
+ * own, and the app authorizes each call. Failing preflight there told a
118
+ * technician to enable an integration that was already enabled, and blocked a
119
+ * fill that would have succeeded. So a `whoami` failure falls through to a
120
+ * vault-listing probe, which is what this command actually needs to do.
121
+ */
122
+ async function opPreflight(execFileImpl, platform) {
106
123
  try {
107
124
  await execFileImpl("op", ["whoami"]);
108
125
  return true;
109
126
  }
110
127
  catch (error) {
111
128
  const { code } = execFailureDetail(error);
112
- if (code === "ENOENT") {
113
- return "install the 1Password CLI (`brew install 1password-cli`) and run `op signin`";
129
+ if (code === "ENOENT")
130
+ return opInstallFix(platform);
131
+ try {
132
+ await execFileImpl("op", ["vault", "list", "--format=json"]);
133
+ return true;
134
+ }
135
+ catch (fallbackError) {
136
+ const detail = execFailureDetail(fallbackError);
137
+ if (detail.code === "ENOENT")
138
+ return opInstallFix(platform);
139
+ return `authenticate the 1Password CLI: ${opIntegrationFix(platform)}`;
114
140
  }
115
- return "sign in to 1Password: run `op signin`";
116
141
  }
117
142
  }
118
143
  async function opRead(execFileImpl, vault, spec) {
@@ -141,21 +166,38 @@ function writableValue(value) {
141
166
  return `'${value}'`;
142
167
  return null;
143
168
  }
144
- /** Replace only the empty `NAME=` lines being filled; leave everything else byte-for-byte. */
169
+ /**
170
+ * Replace only the empty `NAME=` lines being filled; leave everything else
171
+ * byte-for-byte. A var with no line at all (a `.env` made before the var was
172
+ * added to the registry) is appended at the end — without this it was reported
173
+ * "filled" and silently never written.
174
+ */
145
175
  function applyFills(content, fills) {
146
- return content
176
+ const pending = new Map(fills);
177
+ let out = content
147
178
  .split("\n")
148
179
  .map((line) => {
149
180
  const match = line.match(/^(export\s+)?([A-Za-z_][A-Za-z0-9_]*)=\s*$/);
150
181
  if (!match)
151
182
  return line;
152
- const value = fills.get(match[2]);
153
- return value === undefined ? line : `${match[1] ?? ""}${match[2]}=${value}`;
183
+ const name = match[2] ?? "";
184
+ const value = pending.get(name);
185
+ if (value === undefined)
186
+ return line;
187
+ pending.delete(name);
188
+ return `${match[1] ?? ""}${name}=${value}`;
154
189
  })
155
190
  .join("\n");
191
+ if (pending.size === 0)
192
+ return out;
193
+ if (out.length > 0 && !out.endsWith("\n"))
194
+ out += "\n";
195
+ for (const [name, value] of pending)
196
+ out += `${name}=${value}\n`;
197
+ return out;
156
198
  }
157
199
  function personalHomework(existing) {
158
- return ENV_VARS.filter((spec) => spec.source === "personal" &&
200
+ return TECH_ENV_VARS.filter((spec) => spec.source === "personal" &&
159
201
  spec.tier === "required" &&
160
202
  !(typeof existing[spec.name] === "string" && existing[spec.name].length > 0)).map((spec) => ({ name: spec.name, howToGet: spec.howToGet }));
161
203
  }
@@ -1,4 +1,5 @@
1
1
  import { type ExecFileFn } from "./exec.js";
2
+ import { type PlatformInfo } from "./platform.js";
2
3
  export interface EnvPushOptions {
3
4
  /** installagent/ workspace root holding the .env. Defaults to the current dir. */
4
5
  workspaceDir?: string;
@@ -6,6 +7,8 @@ export interface EnvPushOptions {
6
7
  dryRun?: boolean;
7
8
  /** Write every vault var to this vault instead of its registry vault. */
8
9
  vaultOverride?: string;
10
+ /** Injectable for tests; defaults to the running machine. Picks the op fix-it text. */
11
+ platform?: PlatformInfo;
9
12
  /** Injectable for tests; defaults to real `op` via execFile. */
10
13
  execFileImpl?: ExecFileFn;
11
14
  }
package/dist/env-push.js CHANGED
@@ -3,6 +3,8 @@ import { join, resolve } from "node:path";
3
3
  import { parseEnvFile } from "./env-file.js";
4
4
  import { DEFAULT_TECH_VAULT, ENV_VARS } from "./env-registry.js";
5
5
  import { execFailureDetail, execFileAsync } from "./exec.js";
6
+ import { opInstallFix, opIntegrationFix } from "./op-cli.js";
7
+ import { detectPlatformInfo } from "./platform.js";
6
8
  /**
7
9
  * Push the workspace root .env up into the team 1Password vaults via the
8
10
  * `op` CLI: every vault-backed registry var that has a value in .env is
@@ -17,8 +19,12 @@ export async function envPush(options = {}) {
17
19
  const workspaceDir = resolve(options.workspaceDir ?? ".");
18
20
  const dryRun = options.dryRun ?? false;
19
21
  const execFileImpl = options.execFileImpl ?? execFileAsync;
22
+ // Founder-side command: it pushes the whole registry, admin vars included.
23
+ // Role scoping guards what a TECHNICIAN's tools name; whoever runs push
24
+ // already holds the grants.
25
+ const platform = options.platform ?? detectPlatformInfo();
20
26
  const envPath = join(workspaceDir, ".env");
21
- const opReady = await opPreflight(execFileImpl);
27
+ const opReady = await opPreflight(execFileImpl, platform);
22
28
  if (opReady !== true) {
23
29
  return {
24
30
  ok: false,
@@ -93,17 +99,16 @@ export async function envPush(options = {}) {
93
99
  };
94
100
  }
95
101
  /** True when op is installed and signed in; otherwise the fix-it next step. */
96
- async function opPreflight(execFileImpl) {
102
+ async function opPreflight(execFileImpl, platform) {
97
103
  try {
98
104
  await execFileImpl("op", ["whoami"]);
99
105
  return true;
100
106
  }
101
107
  catch (error) {
102
108
  const { code } = execFailureDetail(error);
103
- if (code === "ENOENT") {
104
- return "install the 1Password CLI (`brew install 1password-cli`) and run `op signin`";
105
- }
106
- return "sign in to 1Password: run `op signin`";
109
+ if (code === "ENOENT")
110
+ return opInstallFix(platform);
111
+ return `authenticate the 1Password CLI: ${opIntegrationFix(platform)}`;
107
112
  }
108
113
  }
109
114
  /** Update the vault item if it exists; create it if it doesn't. Never throws. */
@@ -6,6 +6,19 @@ export type EnvVarTier = "required" | "optional";
6
6
  * vaulted, always filled by hand.
7
7
  */
8
8
  export type EnvVarSource = "vault" | "personal";
9
+ /**
10
+ * Who a var is for. `tech` — the day-one set every technician gets on their
11
+ * first afternoon. `admin` — infra, portal and payments secrets granted
12
+ * case-by-case.
13
+ *
14
+ * This governs what a technician's tools are even allowed to MENTION. Before
15
+ * it existed, `ia env fill` attempted every var and printed a red
16
+ * `not-in-vault` line naming every database and payments secret in the
17
+ * company to someone holding no grant to any of them. One key name is not a
18
+ * secret; a complete inventory of them is a map for whoever gets that laptop
19
+ * next.
20
+ */
21
+ export type EnvVarRole = "tech" | "admin";
9
22
  export interface EnvVarSpec {
10
23
  name: string;
11
24
  tier: EnvVarTier;
@@ -21,6 +34,9 @@ export interface EnvVarSpec {
21
34
  field?: string;
22
35
  /** Which command family reads it — shown by doctor and env fill. */
23
36
  neededBy: string;
37
+ /** Another var that satisfies the same need: when THAT var is set, this
38
+ * one's absence is fine (doctor reports ok instead of missing/warn). */
39
+ coveredBy?: string;
24
40
  /** Concrete manual steps (personal vars) or vault pointer (vault vars). */
25
41
  howToGet: string;
26
42
  /** env.example section heading this var renders under. */
@@ -32,6 +48,12 @@ export interface EnvVarSpec {
32
48
  export declare const DEFAULT_TECH_VAULT = "team-techs";
33
49
  /** Payments / DB / deploy secrets — granted case-by-case. */
34
50
  export declare const INFRA_VAULT = "team-admin";
51
+ /** Only `ia secrets mint gemini-api-key` reads it, so it has no owning module. */
52
+ export declare const GEMINI_API_KEY_ENV = "GEMINI_API_KEY";
53
+ /** Read by apps/slack-agent (relay.ts, feedback.ts) — an app, so it has no SDK module. */
54
+ export declare const SLACK_RELAY_SECRET_ENV = "SLACK_RELAY_SECRET";
55
+ /** Read by nothing; registered so every team-techs item is accounted for. */
56
+ export declare const N8N_OAUTH_CALLBACK_URL_ENV = "N8N_OAUTH_CALLBACK_URL";
35
57
  /**
36
58
  * Single source of truth for every workspace-root .env var: doctor derives
37
59
  * its env checks from it, `ia env fill` knows which vars 1Password can
@@ -39,6 +61,13 @@ export declare const INFRA_VAULT = "team-admin";
39
61
  * (`pnpm generate:env-example` — a drift test keeps the two in sync).
40
62
  */
41
63
  export declare const ENV_VARS: EnvVarSpec[];
64
+ export declare function envVarRole(spec: EnvVarSpec): EnvVarRole;
65
+ /** Every var a technician's own tooling may read, fill, or name. */
66
+ export declare const TECH_ENV_VARS: EnvVarSpec[];
67
+ /** The rest — infra, portal, payments. Only ever surfaced behind --admin. */
68
+ export declare const ADMIN_ENV_VARS: EnvVarSpec[];
69
+ /** The var set a command should act on. `includeAdmin` opts in to all of them. */
70
+ export declare function envVarsForRole(includeAdmin: boolean): EnvVarSpec[];
42
71
  /** `op://<vault>/<item>/<field>` for a vault-sourced var. */
43
72
  export declare function opSecretReference(spec: EnvVarSpec): string;
44
73
  /**
@@ -1,8 +1,9 @@
1
1
  import { N8N_API_KEY_ENV, N8N_API_URL_ENV } from "./agent-templates.js";
2
+ import { HOURS_EXPORT_SECRET_ENV } from "./claude-hours.js";
2
3
  import { GITHUB_API_TOKEN_ENV } from "./client-build.js";
3
4
  import { AIRTABLE_API_TOKEN_ENV, GOOGLE_SERVICE_ACCOUNT_KEY_ENV } from "./client-drive.js";
4
5
  import { LINEAR_CLIENT_TEAM_ID_ENV } from "./client-intake.js";
5
- import { DOCS_SESSION_ENV } from "./docs-search.js";
6
+ import { DOCS_SEARCH_TOKEN_ENV, DOCS_SESSION_ENV } from "./docs-search.js";
6
7
  import { FATHOM_API_KEY_ENV } from "./fathom-webhook.js";
7
8
  import { LINEAR_API_TOKEN_ENV } from "./linear-project.js";
8
9
  import { PORTAL_ADMIN_SECRET_ENV } from "./portal-admin.js";
@@ -11,6 +12,12 @@ export const DEFAULT_TECH_VAULT = "team-techs";
11
12
  /** Payments / DB / deploy secrets — granted case-by-case. */
12
13
  export const INFRA_VAULT = "team-admin";
13
14
  const OP_DEFAULT_FIELD = "value";
15
+ /** Only `ia secrets mint gemini-api-key` reads it, so it has no owning module. */
16
+ export const GEMINI_API_KEY_ENV = "GEMINI_API_KEY";
17
+ /** Read by apps/slack-agent (relay.ts, feedback.ts) — an app, so it has no SDK module. */
18
+ export const SLACK_RELAY_SECRET_ENV = "SLACK_RELAY_SECRET";
19
+ /** Read by nothing; registered so every team-techs item is accounted for. */
20
+ export const N8N_OAUTH_CALLBACK_URL_ENV = "N8N_OAUTH_CALLBACK_URL";
14
21
  const SECTION_DRIVERS = "ia CLI: technician daily drivers";
15
22
  const SECTION_INFRA = "shared infra (n8n workflows, team-infra scripts)";
16
23
  const SECTION_PORTAL = "portal / team-web local dev (prod values live in Vercel, never here)";
@@ -73,15 +80,28 @@ export const ENV_VARS = [
73
80
  section: SECTION_DRIVERS,
74
81
  comment: "the fixed Linear client team's ID — filled by `ia env fill`",
75
82
  },
83
+ {
84
+ name: DOCS_SEARCH_TOKEN_ENV,
85
+ tier: "optional",
86
+ source: "vault",
87
+ doctor: true,
88
+ vault: DEFAULT_TECH_VAULT,
89
+ coveredBy: DOCS_SESSION_ENV,
90
+ neededBy: "ia docs search",
91
+ howToGet: `the shared docs-search API bearer (matches the docs app's IA_DOCS_SEARCH_TOKEN deploy env) — ${inTechVault}`,
92
+ section: SECTION_DRIVERS,
93
+ comment: "shared docs-search API bearer (never expires; preferred over the cookie below) — `ia env fill`",
94
+ },
76
95
  {
77
96
  name: DOCS_SESSION_ENV,
78
97
  tier: "required",
79
98
  source: "personal",
80
99
  doctor: true,
100
+ coveredBy: DOCS_SEARCH_TOKEN_ENV,
81
101
  neededBy: "ia docs search",
82
102
  howToGet: "copy the __Secure-authjs.session-token cookie from a logged-in team.installagent.com tab (expires periodically)",
83
103
  section: SECTION_DRIVERS,
84
- comment: "team.installagent.com __Secure-authjs.session-token cookie (expires periodically)",
104
+ comment: "team.installagent.com __Secure-authjs.session-token cookie (expires periodically);\nonly needed when IA_DOCS_SEARCH_TOKEN is unset",
85
105
  },
86
106
  {
87
107
  name: PORTAL_ADMIN_SECRET_ENV,
@@ -89,7 +109,7 @@ export const ENV_VARS = [
89
109
  source: "vault",
90
110
  doctor: true,
91
111
  vault: DEFAULT_TECH_VAULT,
92
- neededBy: "ia portal",
112
+ neededBy: "ia portal, ia triage",
93
113
  howToGet: `the portal admin API bearer — ${inTechVault}`,
94
114
  section: SECTION_DRIVERS,
95
115
  comment: "portal.installagent.com admin API bearer — filled by `ia env fill`",
@@ -111,7 +131,7 @@ export const ENV_VARS = [
111
131
  source: "vault",
112
132
  doctor: true,
113
133
  vault: DEFAULT_TECH_VAULT,
114
- neededBy: "ia client-drive",
134
+ neededBy: "ia client-drive, ia triage",
115
135
  howToGet: `the Drive service-account key JSON — ${inTechVault}`,
116
136
  section: SECTION_DRIVERS,
117
137
  comment: "the Drive service-account key JSON, single line — filled by `ia env fill`",
@@ -150,7 +170,18 @@ export const ENV_VARS = [
150
170
  comment: "n8n → Settings → API — filled by `ia env fill`",
151
171
  },
152
172
  {
153
- name: "GEMINI_API_KEY",
173
+ name: HOURS_EXPORT_SECRET_ENV,
174
+ tier: "optional",
175
+ source: "vault",
176
+ doctor: true,
177
+ vault: DEFAULT_TECH_VAULT,
178
+ neededBy: "ia hours-export",
179
+ howToGet: `the hours-export intake secret — ${inTechVault}`,
180
+ section: SECTION_DRIVERS,
181
+ comment: "lets `ia hours-export` send your file to the ledger keeper — filled by `ia env fill`",
182
+ },
183
+ {
184
+ name: GEMINI_API_KEY_ENV,
154
185
  tier: "optional",
155
186
  source: "vault",
156
187
  doctor: false,
@@ -159,6 +190,37 @@ export const ENV_VARS = [
159
190
  howToGet: inTechVault,
160
191
  section: SECTION_DRIVERS,
161
192
  },
193
+ {
194
+ // Kept in team-techs by the account owner's choice (2026-09-24), under its
195
+ // header name. No `ia` command reads it; the deployed box gets its own copy
196
+ // from SSM (team-infra/agent-hosting).
197
+ name: SLACK_RELAY_SECRET_ENV,
198
+ tier: "optional",
199
+ source: "vault",
200
+ doctor: false,
201
+ vault: DEFAULT_TECH_VAULT,
202
+ item: "x-relay-secret",
203
+ neededBy: "slack-agent (local runs) and the n8n relay / feedback webhooks",
204
+ howToGet: `the Agent Zero relay secret, sent as the x-relay-secret header — ${inTechVault}`,
205
+ section: SECTION_INFRA,
206
+ comment: "Agent Zero relay secret (x-relay-secret header) — filled by `ia env fill`",
207
+ },
208
+ {
209
+ // A public URL, not a secret: the redirect URL n8n shows when an OAuth
210
+ // credential is created, kept in team-techs for pasting into provider consoles.
211
+ name: N8N_OAUTH_CALLBACK_URL_ENV,
212
+ tier: "optional",
213
+ source: "vault",
214
+ doctor: false,
215
+ vault: DEFAULT_TECH_VAULT,
216
+ item: "n8n Install Agent Callback URL",
217
+ // A Secure Note: the URL is the note text, not a `value` field.
218
+ field: "notesPlain",
219
+ neededBy: "setting up OAuth credentials in n8n",
220
+ howToGet: `the n8n OAuth redirect URL — ${inTechVault}`,
221
+ section: SECTION_INFRA,
222
+ comment: "n8n OAuth redirect URL (paste into a provider's OAuth app) — filled by `ia env fill`",
223
+ },
162
224
  infraVar("AIRTABLE_BASE_ID", "n8n workflows, team-infra scripts"),
163
225
  infraVar("AIRTABLE_CLIENTS_TABLE_ID", "n8n workflows, team-infra scripts"),
164
226
  infraVar("N8N_WEBHOOK_URL", "n8n workflows, team-infra scripts"),
@@ -181,6 +243,47 @@ export const ENV_VARS = [
181
243
  paymentsVar("PLAID_ACCESS_TOKEN"),
182
244
  paymentsVar("PLAID_BASE_URL"),
183
245
  ];
246
+ /**
247
+ * The day-one technician set, by name. An ALLOWLIST on purpose, and
248
+ * deliberately not derived from `vault === DEFAULT_TECH_VAULT`: renaming a
249
+ * vault, or moving an item between vaults, must never silently widen what a
250
+ * technician's terminal prints. Anything absent here is `admin` — a new var
251
+ * added to the registry is invisible to technicians until someone adds it
252
+ * here on purpose. Fail closed.
253
+ *
254
+ * env-registry.test.ts pins this against the vault fields, so a name listed
255
+ * here that is neither personal nor in the technician vault fails the build.
256
+ */
257
+ const TECH_ROLE_VAR_NAMES = new Set([
258
+ GITHUB_API_TOKEN_ENV,
259
+ LINEAR_API_TOKEN_ENV,
260
+ LINEAR_CLIENT_TEAM_ID_ENV,
261
+ DOCS_SEARCH_TOKEN_ENV,
262
+ DOCS_SESSION_ENV,
263
+ PORTAL_ADMIN_SECRET_ENV,
264
+ AIRTABLE_API_TOKEN_ENV,
265
+ GOOGLE_SERVICE_ACCOUNT_KEY_ENV,
266
+ FATHOM_API_KEY_ENV,
267
+ N8N_API_URL_ENV,
268
+ N8N_API_KEY_ENV,
269
+ GEMINI_API_KEY_ENV,
270
+ // Every technician's `ia hours-export` sends with it (2026-09-24).
271
+ HOURS_EXPORT_SECRET_ENV,
272
+ // In team-techs by the account owner's choice (2026-09-24); no `ia` command reads them.
273
+ SLACK_RELAY_SECRET_ENV,
274
+ N8N_OAUTH_CALLBACK_URL_ENV,
275
+ ]);
276
+ export function envVarRole(spec) {
277
+ return TECH_ROLE_VAR_NAMES.has(spec.name) ? "tech" : "admin";
278
+ }
279
+ /** Every var a technician's own tooling may read, fill, or name. */
280
+ export const TECH_ENV_VARS = ENV_VARS.filter((spec) => envVarRole(spec) === "tech");
281
+ /** The rest — infra, portal, payments. Only ever surfaced behind --admin. */
282
+ export const ADMIN_ENV_VARS = ENV_VARS.filter((spec) => envVarRole(spec) === "admin");
283
+ /** The var set a command should act on. `includeAdmin` opts in to all of them. */
284
+ export function envVarsForRole(includeAdmin) {
285
+ return includeAdmin ? ENV_VARS : TECH_ENV_VARS;
286
+ }
184
287
  /** `op://<vault>/<item>/<field>` for a vault-sourced var. */
185
288
  export function opSecretReference(spec) {
186
289
  if (spec.source !== "vault" || !spec.vault) {
@@ -192,13 +295,17 @@ const ENV_EXAMPLE_HEADER = `# installagent/ workspace root .env — ONE env file
192
295
  #
193
296
  # - \`ia\` commands load this automatically (vars already set in your shell win).
194
297
  # - Shell scripts in any repo can use it too: set -a; source ../.env; set +a
195
- # - Shared values come from 1Password: run \`ia env fill\` (needs \`op signin\`).
298
+ # - Shared values come from 1Password: run \`ia env fill\` (needs the op CLI
299
+ # authenticated via the 1Password app's CLI integration — \`ia doctor\` checks it).
196
300
  # Personal values (marked below) you fill by hand. NEVER commit this file
197
301
  # anywhere — the root is not a git repo, and no repo may ever contain it.
198
302
  # Only env.example (this placeholder layout, no values) is shareable.
199
303
  # - \`ia doctor -w <workspace>\` tells you which vars are still missing and why.
200
304
  `;
201
305
  const SECTION_RULE_WIDTH = 79;
306
+ /** Rendered under every admin section heading in env.example. */
307
+ const ADMIN_SECTION_NOTE = `# Commented out — granted case-by-case from the ${INFRA_VAULT} vault. If you
308
+ # have the grant, uncomment the line you need, then run \`ia env fill --admin\`.`;
202
309
  function sectionHeading(title) {
203
310
  const prefix = `# ── ${title} `;
204
311
  return prefix + "─".repeat(Math.max(0, SECTION_RULE_WIDTH - prefix.length));
@@ -211,18 +318,25 @@ function sectionHeading(title) {
211
318
  export function renderEnvExample() {
212
319
  const lines = [ENV_EXAMPLE_HEADER];
213
320
  let currentSection = null;
214
- for (const spec of ENV_VARS) {
321
+ for (const [index, spec] of ENV_VARS.entries()) {
322
+ const admin = envVarRole(spec) === "admin";
215
323
  if (spec.section !== currentSection) {
216
324
  currentSection = spec.section;
217
325
  lines.push(sectionHeading(currentSection));
326
+ if (admin)
327
+ lines.push(ADMIN_SECTION_NOTE);
218
328
  }
219
- lines.push(`${spec.name}=`);
329
+ // Admin vars ship commented out. parseEnvFile ignores comment lines, so
330
+ // `ia env fill` never tries to fill one and `ia doctor` never reports it
331
+ // missing — a technician's .env stays a list of their own vars. Uncomment
332
+ // a line only once you have been granted that vault.
333
+ lines.push(admin ? `# ${spec.name}=` : `${spec.name}=`);
220
334
  if (spec.comment) {
221
335
  for (const commentLine of spec.comment.split("\n")) {
222
336
  lines.push(`# ${commentLine}`);
223
337
  }
224
338
  }
225
- const next = ENV_VARS[ENV_VARS.indexOf(spec) + 1];
339
+ const next = ENV_VARS[index + 1];
226
340
  if (!next || next.section !== spec.section)
227
341
  lines.push("");
228
342
  }
package/dist/exec.js CHANGED
@@ -1,8 +1,21 @@
1
1
  import { execFile } from "node:child_process";
2
2
  import { promisify } from "node:util";
3
+ import { createLogger } from "./log.js";
4
+ const log = createLogger("sdk.exec");
3
5
  export const execFileAsync = async (file, args) => {
4
- const { stdout, stderr } = await promisify(execFile)(file, [...args]);
5
- return { stdout, stderr };
6
+ // Only the binary and its subcommand are logged: later args can carry
7
+ // secret values (op item fields, key material) and stdout/stderr may too.
8
+ const shape = { file, subcommand: args[0], argCount: args.length };
9
+ const started = Date.now();
10
+ try {
11
+ const { stdout, stderr } = await promisify(execFile)(file, [...args]);
12
+ log.debug("subprocess", { ...shape, ms: Date.now() - started, ok: true });
13
+ return { stdout, stderr };
14
+ }
15
+ catch (error) {
16
+ log.debug("subprocess", { ...shape, ms: Date.now() - started, ok: false });
17
+ throw error;
18
+ }
6
19
  };
7
20
  /** Pull code/stderr off an execFile rejection without touching stdout (it may hold a secret). */
8
21
  export function execFailureDetail(error) {
package/dist/git.d.ts CHANGED
@@ -14,3 +14,34 @@ export declare const gitClone: CloneFn;
14
14
  export type PullFn = (dir: string) => Promise<void>;
15
15
  export declare const gitPullFfOnly: PullFn;
16
16
  export declare function gitInit(dir: string): Promise<void>;
17
+ /**
18
+ * Injectable fetch function — read-only (`git fetch` never touches the
19
+ * working tree or local branches), so it's always safe to run before a
20
+ * status check.
21
+ */
22
+ export type FetchFn = (dir: string) => Promise<void>;
23
+ export declare const gitFetchAll: FetchFn;
24
+ export interface RepoStatusInfo {
25
+ branch: string | null;
26
+ upstream: string | null;
27
+ /** Local commits not yet on the upstream branch. 0 if no upstream. */
28
+ ahead: number;
29
+ /** Upstream commits not yet merged locally. 0 if no upstream. */
30
+ behind: number;
31
+ /** True if the working tree has staged or unstaged changes to tracked files. */
32
+ dirty: boolean;
33
+ /** Count of untracked files/paths. */
34
+ untracked: number;
35
+ }
36
+ /**
37
+ * Injectable status function — reads `git status --porcelain=v2 --branch`,
38
+ * never mutates anything.
39
+ */
40
+ export type StatusFn = (dir: string) => Promise<RepoStatusInfo>;
41
+ export declare const gitStatus: StatusFn;
42
+ /**
43
+ * Injectable push function — plain `git push` on the current branch
44
+ * (relies on an already-configured upstream). Never force-pushes.
45
+ */
46
+ export type PushFn = (dir: string) => Promise<void>;
47
+ export declare const gitPush: PushFn;
package/dist/git.js CHANGED
@@ -27,3 +27,62 @@ export const gitPullFfOnly = async (dir) => {
27
27
  export async function gitInit(dir) {
28
28
  await execFileAsync("git", ["init"], { cwd: dir });
29
29
  }
30
+ export const gitFetchAll = async (dir) => {
31
+ try {
32
+ await execFileAsync("git", ["fetch", "--all", "--prune"], { cwd: dir });
33
+ }
34
+ catch (error) {
35
+ const detail = error instanceof Error ? error.message : String(error);
36
+ throw new Error(`git fetch failed in ${dir}: ${detail}`);
37
+ }
38
+ };
39
+ export const gitStatus = async (dir) => {
40
+ let stdout;
41
+ try {
42
+ ({ stdout } = await execFileAsync("git", ["status", "--porcelain=v2", "--branch"], {
43
+ cwd: dir,
44
+ }));
45
+ }
46
+ catch (error) {
47
+ const detail = error instanceof Error ? error.message : String(error);
48
+ throw new Error(`git status failed in ${dir}: ${detail}`);
49
+ }
50
+ let branch = null;
51
+ let upstream = null;
52
+ let ahead = 0;
53
+ let behind = 0;
54
+ let dirty = false;
55
+ let untracked = 0;
56
+ for (const line of stdout.split("\n")) {
57
+ if (line.startsWith("# branch.head ")) {
58
+ const head = line.slice("# branch.head ".length).trim();
59
+ branch = head === "(detached)" ? null : head;
60
+ }
61
+ else if (line.startsWith("# branch.upstream ")) {
62
+ upstream = line.slice("# branch.upstream ".length).trim();
63
+ }
64
+ else if (line.startsWith("# branch.ab ")) {
65
+ const match = line.match(/\+(\d+) -(\d+)/);
66
+ if (match) {
67
+ ahead = Number(match[1]);
68
+ behind = Number(match[2]);
69
+ }
70
+ }
71
+ else if (line.startsWith("?")) {
72
+ untracked += 1;
73
+ }
74
+ else if (line.startsWith("1") || line.startsWith("2") || line.startsWith("u")) {
75
+ dirty = true;
76
+ }
77
+ }
78
+ return { branch, upstream, ahead, behind, dirty, untracked };
79
+ };
80
+ export const gitPush = async (dir) => {
81
+ try {
82
+ await execFileAsync("git", ["push"], { cwd: dir });
83
+ }
84
+ catch (error) {
85
+ const detail = error instanceof Error ? error.message : String(error);
86
+ throw new Error(`git push failed in ${dir}: ${detail}`);
87
+ }
88
+ };
@@ -0,0 +1,20 @@
1
+ export declare const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
2
+ /** Thrown when the service-account key is missing, malformed, or rejected by Google. */
3
+ export declare class GoogleServiceAccountAuthError extends Error {
4
+ }
5
+ export declare function buildServiceAccountClaims(clientEmail: string, scope: string, nowMs: number): {
6
+ iss: string;
7
+ scope: string;
8
+ aud: string;
9
+ iat: number;
10
+ exp: number;
11
+ };
12
+ /**
13
+ * Exchange a service-account key for a short-lived access token carrying
14
+ * exactly `scope`. The caller decides the scope — keep it the narrowest that
15
+ * works (`*.readonly` wherever the operation only reads).
16
+ */
17
+ export declare function getServiceAccountAccessToken(serviceAccountKeyRaw: string, scope: string, fetchImpl: typeof fetch, now: () => number): Promise<{
18
+ accessToken: string;
19
+ clientEmail: string;
20
+ }>;