@installagent/sdk 0.1.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 (94) hide show
  1. package/dist/agent-templates.d.ts +90 -0
  2. package/dist/agent-templates.js +211 -0
  3. package/dist/client-build.d.ts +50 -0
  4. package/dist/client-build.js +155 -0
  5. package/dist/client-context.d.ts +40 -0
  6. package/dist/client-context.js +70 -0
  7. package/dist/client-drive.d.ts +67 -0
  8. package/dist/client-drive.js +278 -0
  9. package/dist/client-intake.d.ts +68 -0
  10. package/dist/client-intake.js +189 -0
  11. package/dist/client-linear.d.ts +30 -0
  12. package/dist/client-linear.js +85 -0
  13. package/dist/docs-search.d.ts +44 -0
  14. package/dist/docs-search.js +187 -0
  15. package/dist/doctor.d.ts +43 -0
  16. package/dist/doctor.js +425 -0
  17. package/dist/env-file.d.ts +25 -0
  18. package/dist/env-file.js +69 -0
  19. package/dist/env-fill.d.ts +43 -0
  20. package/dist/env-fill.js +161 -0
  21. package/dist/env-push.d.ts +37 -0
  22. package/dist/env-push.js +137 -0
  23. package/dist/env-registry.d.ts +49 -0
  24. package/dist/env-registry.js +230 -0
  25. package/dist/exec.d.ts +14 -0
  26. package/dist/exec.js +16 -0
  27. package/dist/fathom-webhook.d.ts +44 -0
  28. package/dist/fathom-webhook.js +123 -0
  29. package/dist/fs-utils.d.ts +9 -0
  30. package/dist/fs-utils.js +34 -0
  31. package/dist/gcp-service-account-key.d.ts +37 -0
  32. package/dist/gcp-service-account-key.js +66 -0
  33. package/dist/gemini-api-key.d.ts +47 -0
  34. package/dist/gemini-api-key.js +132 -0
  35. package/dist/git.d.ts +16 -0
  36. package/dist/git.js +29 -0
  37. package/dist/github-token.d.ts +24 -0
  38. package/dist/github-token.js +30 -0
  39. package/dist/index.d.ts +25 -0
  40. package/dist/index.js +28 -0
  41. package/dist/init.d.ts +47 -0
  42. package/dist/init.js +101 -0
  43. package/dist/linear-project.d.ts +81 -0
  44. package/dist/linear-project.js +192 -0
  45. package/dist/new-client.d.ts +32 -0
  46. package/dist/new-client.js +89 -0
  47. package/dist/ping.d.ts +6 -0
  48. package/dist/ping.js +7 -0
  49. package/dist/portal-admin.d.ts +133 -0
  50. package/dist/portal-admin.js +144 -0
  51. package/dist/sync-templates.d.ts +58 -0
  52. package/dist/sync-templates.js +109 -0
  53. package/dist/template-sync.d.ts +55 -0
  54. package/dist/template-sync.js +90 -0
  55. package/dist/templates.d.ts +19 -0
  56. package/dist/templates.js +24 -0
  57. package/dist/wizard.d.ts +78 -0
  58. package/dist/wizard.js +213 -0
  59. package/package.json +30 -0
  60. package/templates/env.example +60 -0
  61. package/templates/workspace-root/.claude/settings.json +39 -0
  62. package/templates/workspace-root/AGENT.md +205 -0
  63. package/templates/workspace-root/AGENTS.md +11 -0
  64. package/templates/workspace-root/CLAUDE.md +63 -0
  65. package/templates/workspace-root/GEMINI.md +24 -0
  66. package/templates/workspace-root/ONBOARDING.md +164 -0
  67. package/templates/workspace-root/README.md +67 -0
  68. package/templates/workspace-root/skills/CLAUDE.md +79 -0
  69. package/templates/workspace-root/skills/client-deliverables/SKILL.md +131 -0
  70. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +103 -0
  71. package/templates/workspace-root/skills/client-facing-docs/SKILL.md +131 -0
  72. package/templates/workspace-root/skills/client-facing-docs/references/doc-structures.md +81 -0
  73. package/templates/workspace-root/skills/client-llm-setup/SKILL.md +97 -0
  74. package/templates/workspace-root/skills/client-llm-setup/references/guide-template.md +87 -0
  75. package/templates/workspace-root/skills/client-workflow-diagram/SKILL.md +141 -0
  76. package/templates/workspace-root/skills/client-workflow-diagram/references/excalidraw-format.md +140 -0
  77. package/templates/workspace-root/skills/contract-tech-agnostic/SKILL.md +99 -0
  78. package/templates/workspace-root/skills/contract-tech-agnostic/references/Install_Agent_SOW_Template.docx +0 -0
  79. package/templates/workspace-root/skills/design-system/SKILL.md +118 -0
  80. package/templates/workspace-root/skills/design-system/references/tokens.md +139 -0
  81. package/templates/workspace-root/skills/engagement-spec/SKILL.md +272 -0
  82. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +220 -0
  83. package/templates/workspace-root/skills/house-voice/SKILL.md +158 -0
  84. package/templates/workspace-root/skills/house-voice/references/source-copy.md +173 -0
  85. package/templates/workspace-root/skills/ia-cli/SKILL.md +87 -0
  86. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +112 -0
  87. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-logo.svg +1 -0
  88. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-mark.svg +1 -0
  89. package/templates/workspace-root/skills/installagent-brand-kit/references/brand-tokens.md +71 -0
  90. package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +66 -0
  91. package/templates/workspace-root/skills/installagent-brand-kit/references/excalidraw-red-theme.md +73 -0
  92. package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +175 -0
  93. package/templates/workspace-root/skills/linear/SKILL.md +186 -0
  94. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +141 -0
@@ -0,0 +1,161 @@
1
+ import { existsSync } from "node:fs";
2
+ import { copyFile, readFile, writeFile } from "node:fs/promises";
3
+ import { join, resolve } from "node:path";
4
+ import { parseEnvFile } from "./env-file.js";
5
+ import { DEFAULT_TECH_VAULT, ENV_VARS } from "./env-registry.js";
6
+ import { execFailureDetail, execFileAsync } from "./exec.js";
7
+ import { envExampleTemplatePath } from "./templates.js";
8
+ /** Values op read fields are tried in when the registry doesn't pin one. */
9
+ const OP_FIELD_FALLBACKS = ["value", "credential", "password"];
10
+ /** Safe to write unquoted into a KEY=value line. */
11
+ const PLAIN_VALUE = /^[A-Za-z0-9_./:+=@,-]+$/;
12
+ /**
13
+ * Fill the workspace root .env from the team 1Password vaults via the `op`
14
+ * CLI: every vault-backed registry var that is still empty is read from
15
+ * `op://<vault>/<var name>/value` and written in place. Existing values are
16
+ * NEVER overwritten; personal vars (own Linear key, docs session cookie) are
17
+ * never vaulted and come back as homework in `personalRemaining`. The result
18
+ * carries statuses and op:// references only — never secret values — so it
19
+ * is safe to serialize over MCP.
20
+ */
21
+ export async function envFill(options = {}) {
22
+ const workspaceDir = resolve(options.workspaceDir ?? ".");
23
+ const dryRun = options.dryRun ?? false;
24
+ const execFileImpl = options.execFileImpl ?? execFileAsync;
25
+ const envPath = join(workspaceDir, ".env");
26
+ const opReady = await opPreflight(execFileImpl);
27
+ if (opReady !== true) {
28
+ return {
29
+ ok: false,
30
+ envPath,
31
+ dryRun,
32
+ created: false,
33
+ vars: [],
34
+ personalRemaining: personalHomework({}),
35
+ nextSteps: [opReady, "then re-run `ia env fill`"],
36
+ };
37
+ }
38
+ let created = false;
39
+ if (!existsSync(envPath)) {
40
+ if (!dryRun)
41
+ await copyFile(envExampleTemplatePath(), envPath);
42
+ created = true;
43
+ }
44
+ const original = created && dryRun
45
+ ? await readFile(envExampleTemplatePath(), "utf8")
46
+ : await readFile(envPath, "utf8");
47
+ const existing = parseEnvFile(original);
48
+ const vars = [];
49
+ const fills = new Map();
50
+ for (const spec of ENV_VARS) {
51
+ const current = existing[spec.name];
52
+ if (typeof current === "string" && current.length > 0) {
53
+ vars.push({ name: spec.name, status: "kept", detail: "already set — left untouched" });
54
+ continue;
55
+ }
56
+ if (spec.source === "personal") {
57
+ vars.push({ name: spec.name, status: "personal", detail: spec.howToGet });
58
+ continue;
59
+ }
60
+ const vault = options.vaultOverride ?? spec.vault ?? DEFAULT_TECH_VAULT;
61
+ const read = await opRead(execFileImpl, vault, spec);
62
+ if (read === null) {
63
+ vars.push({
64
+ name: spec.name,
65
+ status: "not-in-vault",
66
+ detail: `op could not read op://${vault}/${spec.item ?? spec.name}/${spec.field ?? OP_FIELD_FALLBACKS[0]} — check the item exists and you have access to the ${vault} vault`,
67
+ });
68
+ continue;
69
+ }
70
+ const writable = writableValue(read);
71
+ if (writable === null) {
72
+ vars.push({
73
+ name: spec.name,
74
+ status: "failed",
75
+ detail: `read from 1Password but the value can't be written safely (contains a quote or newline) — paste it into .env by hand from the ${vault} vault`,
76
+ });
77
+ continue;
78
+ }
79
+ fills.set(spec.name, writable);
80
+ vars.push({
81
+ name: spec.name,
82
+ status: "filled",
83
+ detail: `from op://${vault}/${spec.item ?? spec.name}${dryRun ? " (dry run — not written)" : ""}`,
84
+ });
85
+ }
86
+ if (!dryRun && fills.size > 0) {
87
+ await writeFile(envPath, applyFills(original, fills));
88
+ }
89
+ const personalRemaining = personalHomework(existing);
90
+ const nextSteps = [
91
+ ...personalRemaining.map((p) => `set ${p.name} in ${envPath} — ${p.howToGet}`),
92
+ `run \`ia doctor -w ${workspaceDir}\` to confirm`,
93
+ ];
94
+ return {
95
+ ok: vars.every((v) => v.status !== "failed"),
96
+ envPath,
97
+ dryRun,
98
+ created,
99
+ vars,
100
+ personalRemaining,
101
+ nextSteps,
102
+ };
103
+ }
104
+ /** True when op is installed and signed in; otherwise the fix-it next step. */
105
+ async function opPreflight(execFileImpl) {
106
+ try {
107
+ await execFileImpl("op", ["whoami"]);
108
+ return true;
109
+ }
110
+ catch (error) {
111
+ const { code } = execFailureDetail(error);
112
+ if (code === "ENOENT") {
113
+ return "install the 1Password CLI (`brew install 1password-cli`) and run `op signin`";
114
+ }
115
+ return "sign in to 1Password: run `op signin`";
116
+ }
117
+ }
118
+ async function opRead(execFileImpl, vault, spec) {
119
+ const item = spec.item ?? spec.name;
120
+ const fields = spec.field ? [spec.field] : OP_FIELD_FALLBACKS;
121
+ for (const field of fields) {
122
+ try {
123
+ const { stdout } = await execFileImpl("op", ["read", `op://${vault}/${item}/${field}`]);
124
+ const value = stdout.replace(/\n$/, "");
125
+ if (value.length > 0)
126
+ return value;
127
+ }
128
+ catch {
129
+ // try the next field name
130
+ }
131
+ }
132
+ return null;
133
+ }
134
+ /** The .env line-safe rendering of a value, or null when none is safe. */
135
+ function writableValue(value) {
136
+ if (value.includes("\n") || value.includes("\r"))
137
+ return null;
138
+ if (PLAIN_VALUE.test(value))
139
+ return value;
140
+ if (!value.includes("'"))
141
+ return `'${value}'`;
142
+ return null;
143
+ }
144
+ /** Replace only the empty `NAME=` lines being filled; leave everything else byte-for-byte. */
145
+ function applyFills(content, fills) {
146
+ return content
147
+ .split("\n")
148
+ .map((line) => {
149
+ const match = line.match(/^(export\s+)?([A-Za-z_][A-Za-z0-9_]*)=\s*$/);
150
+ if (!match)
151
+ return line;
152
+ const value = fills.get(match[2]);
153
+ return value === undefined ? line : `${match[1] ?? ""}${match[2]}=${value}`;
154
+ })
155
+ .join("\n");
156
+ }
157
+ function personalHomework(existing) {
158
+ return ENV_VARS.filter((spec) => spec.source === "personal" &&
159
+ spec.tier === "required" &&
160
+ !(typeof existing[spec.name] === "string" && existing[spec.name].length > 0)).map((spec) => ({ name: spec.name, howToGet: spec.howToGet }));
161
+ }
@@ -0,0 +1,37 @@
1
+ import { type ExecFileFn } from "./exec.js";
2
+ export interface EnvPushOptions {
3
+ /** installagent/ workspace root holding the .env. Defaults to the current dir. */
4
+ workspaceDir?: string;
5
+ /** Report what would be written without touching 1Password. */
6
+ dryRun?: boolean;
7
+ /** Write every vault var to this vault instead of its registry vault. */
8
+ vaultOverride?: string;
9
+ /** Injectable for tests; defaults to real `op` via execFile. */
10
+ execFileImpl?: ExecFileFn;
11
+ }
12
+ export type EnvPushVarStatus = "pushed" | "skipped" | "personal" | "failed";
13
+ export interface EnvPushVarResult {
14
+ name: string;
15
+ status: EnvPushVarStatus;
16
+ /** Human detail. NEVER contains the secret value. */
17
+ detail: string;
18
+ }
19
+ export interface EnvPushResult {
20
+ /** False when op is unavailable/signed out, .env is missing, or any var ended up `failed`. */
21
+ ok: boolean;
22
+ envPath: string;
23
+ dryRun: boolean;
24
+ vars: EnvPushVarResult[];
25
+ nextSteps: string[];
26
+ }
27
+ /**
28
+ * Push the workspace root .env up into the team 1Password vaults via the
29
+ * `op` CLI: every vault-backed registry var that has a value in .env is
30
+ * written to `op://<vault>/<var name>/value` (updating the item if it
31
+ * exists, creating it otherwise). Personal vars are never pushed — they're
32
+ * per-technician by design. This is the founder-side inverse of
33
+ * `ia env fill`, for keeping the vault current after rotating a key
34
+ * locally. The result carries statuses and op:// references only — never
35
+ * secret values — so it is safe to serialize over MCP.
36
+ */
37
+ export declare function envPush(options?: EnvPushOptions): Promise<EnvPushResult>;
@@ -0,0 +1,137 @@
1
+ import { readFile } from "node:fs/promises";
2
+ import { join, resolve } from "node:path";
3
+ import { parseEnvFile } from "./env-file.js";
4
+ import { DEFAULT_TECH_VAULT, ENV_VARS } from "./env-registry.js";
5
+ import { execFailureDetail, execFileAsync } from "./exec.js";
6
+ /**
7
+ * Push the workspace root .env up into the team 1Password vaults via the
8
+ * `op` CLI: every vault-backed registry var that has a value in .env is
9
+ * written to `op://<vault>/<var name>/value` (updating the item if it
10
+ * exists, creating it otherwise). Personal vars are never pushed — they're
11
+ * per-technician by design. This is the founder-side inverse of
12
+ * `ia env fill`, for keeping the vault current after rotating a key
13
+ * locally. The result carries statuses and op:// references only — never
14
+ * secret values — so it is safe to serialize over MCP.
15
+ */
16
+ export async function envPush(options = {}) {
17
+ const workspaceDir = resolve(options.workspaceDir ?? ".");
18
+ const dryRun = options.dryRun ?? false;
19
+ const execFileImpl = options.execFileImpl ?? execFileAsync;
20
+ const envPath = join(workspaceDir, ".env");
21
+ const opReady = await opPreflight(execFileImpl);
22
+ if (opReady !== true) {
23
+ return {
24
+ ok: false,
25
+ envPath,
26
+ dryRun,
27
+ vars: [],
28
+ nextSteps: [opReady, "then re-run `ia env push`"],
29
+ };
30
+ }
31
+ let existing;
32
+ try {
33
+ existing = parseEnvFile(await readFile(envPath, "utf8"));
34
+ }
35
+ catch {
36
+ return {
37
+ ok: false,
38
+ envPath,
39
+ dryRun,
40
+ vars: [],
41
+ nextSteps: [`no .env found at ${envPath} — run \`ia env fill\` first to create one`],
42
+ };
43
+ }
44
+ const vars = [];
45
+ for (const spec of ENV_VARS) {
46
+ if (spec.source === "personal") {
47
+ vars.push({
48
+ name: spec.name,
49
+ status: "personal",
50
+ detail: "per-technician var — never vaulted, not pushed",
51
+ });
52
+ continue;
53
+ }
54
+ const value = existing[spec.name];
55
+ if (!value) {
56
+ vars.push({ name: spec.name, status: "skipped", detail: "empty in .env — nothing to push" });
57
+ continue;
58
+ }
59
+ const vault = options.vaultOverride ?? spec.vault ?? DEFAULT_TECH_VAULT;
60
+ if (dryRun) {
61
+ vars.push({
62
+ name: spec.name,
63
+ status: "pushed",
64
+ detail: `would write to op://${vault}/${spec.item ?? spec.name} (dry run — not written)`,
65
+ });
66
+ continue;
67
+ }
68
+ const written = await opWrite(execFileImpl, vault, spec, value);
69
+ if (!written) {
70
+ vars.push({
71
+ name: spec.name,
72
+ status: "failed",
73
+ detail: `op could not write op://${vault}/${spec.item ?? spec.name} — check vault access, then set it by hand in the 1Password app`,
74
+ });
75
+ continue;
76
+ }
77
+ vars.push({
78
+ name: spec.name,
79
+ status: "pushed",
80
+ detail: `written to op://${vault}/${spec.item ?? spec.name}`,
81
+ });
82
+ }
83
+ const pushedCount = vars.filter((v) => v.status === "pushed").length;
84
+ const nextSteps = pushedCount > 0 && !dryRun
85
+ ? ["run `ia env fill --dry-run` to confirm every var reads back"]
86
+ : [];
87
+ return {
88
+ ok: vars.every((v) => v.status !== "failed"),
89
+ envPath,
90
+ dryRun,
91
+ vars,
92
+ nextSteps,
93
+ };
94
+ }
95
+ /** True when op is installed and signed in; otherwise the fix-it next step. */
96
+ async function opPreflight(execFileImpl) {
97
+ try {
98
+ await execFileImpl("op", ["whoami"]);
99
+ return true;
100
+ }
101
+ catch (error) {
102
+ 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`";
107
+ }
108
+ }
109
+ /** Update the vault item if it exists; create it if it doesn't. Never throws. */
110
+ async function opWrite(execFileImpl, vault, spec, value) {
111
+ const item = spec.item ?? spec.name;
112
+ const field = spec.field ?? "value";
113
+ const assignment = `${field}[password]=${value}`;
114
+ try {
115
+ await execFileImpl("op", ["item", "edit", item, "--vault", vault, assignment]);
116
+ return true;
117
+ }
118
+ catch {
119
+ try {
120
+ await execFileImpl("op", [
121
+ "item",
122
+ "create",
123
+ "--category",
124
+ "Password",
125
+ "--title",
126
+ item,
127
+ "--vault",
128
+ vault,
129
+ assignment,
130
+ ]);
131
+ return true;
132
+ }
133
+ catch {
134
+ return false;
135
+ }
136
+ }
137
+ }
@@ -0,0 +1,49 @@
1
+ /** `required` fails `ia doctor` when unset; `optional` only warns. */
2
+ export type EnvVarTier = "required" | "optional";
3
+ /**
4
+ * `vault` — a shared secret `ia env fill` can read from 1Password.
5
+ * `personal` — per-technician (own API key, own browser cookie); never
6
+ * vaulted, always filled by hand.
7
+ */
8
+ export type EnvVarSource = "vault" | "personal";
9
+ export interface EnvVarSpec {
10
+ name: string;
11
+ tier: EnvVarTier;
12
+ source: EnvVarSource;
13
+ /** Whether `ia doctor` reports this var. Infra/portal/payments vars stay
14
+ * out of the technician checkup — they gate scripts, not `ia` commands. */
15
+ doctor: boolean;
16
+ /** 1Password vault holding the item. Required when source is `vault`. */
17
+ vault?: string;
18
+ /** 1Password item name; defaults to `name` (item == var convention). */
19
+ item?: string;
20
+ /** 1Password field; defaults to `value`. */
21
+ field?: string;
22
+ /** Which command family reads it — shown by doctor and env fill. */
23
+ neededBy: string;
24
+ /** Concrete manual steps (personal vars) or vault pointer (vault vars). */
25
+ howToGet: string;
26
+ /** env.example section heading this var renders under. */
27
+ section: string;
28
+ /** Extra comment line(s) rendered under the var in env.example. */
29
+ comment?: string;
30
+ }
31
+ /** Day-one shared secrets — every technician gets read access. */
32
+ export declare const DEFAULT_TECH_VAULT = "team-techs";
33
+ /** Payments / DB / deploy secrets — granted case-by-case. */
34
+ export declare const INFRA_VAULT = "team-admin";
35
+ /**
36
+ * Single source of truth for every workspace-root .env var: doctor derives
37
+ * its env checks from it, `ia env fill` knows which vars 1Password can
38
+ * supply, and templates/env.example is generated from it
39
+ * (`pnpm generate:env-example` — a drift test keeps the two in sync).
40
+ */
41
+ export declare const ENV_VARS: EnvVarSpec[];
42
+ /** `op://<vault>/<item>/<field>` for a vault-sourced var. */
43
+ export declare function opSecretReference(spec: EnvVarSpec): string;
44
+ /**
45
+ * Render the canonical templates/env.example content from the registry.
46
+ * scripts/generate-env-example.mjs writes it; a drift test asserts the
47
+ * bundled file matches.
48
+ */
49
+ export declare function renderEnvExample(): string;
@@ -0,0 +1,230 @@
1
+ import { N8N_API_KEY_ENV, N8N_API_URL_ENV } from "./agent-templates.js";
2
+ import { GITHUB_API_TOKEN_ENV } from "./client-build.js";
3
+ import { AIRTABLE_API_TOKEN_ENV, GOOGLE_SERVICE_ACCOUNT_KEY_ENV } from "./client-drive.js";
4
+ import { LINEAR_CLIENT_TEAM_ID_ENV } from "./client-intake.js";
5
+ import { DOCS_SESSION_ENV } from "./docs-search.js";
6
+ import { FATHOM_API_KEY_ENV } from "./fathom-webhook.js";
7
+ import { LINEAR_API_TOKEN_ENV } from "./linear-project.js";
8
+ import { PORTAL_ADMIN_SECRET_ENV } from "./portal-admin.js";
9
+ /** Day-one shared secrets — every technician gets read access. */
10
+ export const DEFAULT_TECH_VAULT = "team-techs";
11
+ /** Payments / DB / deploy secrets — granted case-by-case. */
12
+ export const INFRA_VAULT = "team-admin";
13
+ const OP_DEFAULT_FIELD = "value";
14
+ const SECTION_DRIVERS = "ia CLI: technician daily drivers";
15
+ const SECTION_INFRA = "shared infra (n8n workflows, team-infra scripts)";
16
+ const SECTION_PORTAL = "portal / team-web local dev (prod values live in Vercel, never here)";
17
+ const SECTION_PAYMENTS = "payments (Stripe / Plaid)";
18
+ const inTechVault = `in 1Password (${DEFAULT_TECH_VAULT}) — \`ia env fill\` reads it for you`;
19
+ const inInfraVault = `in 1Password (${INFRA_VAULT}) — granted case-by-case, \`ia env fill\` reads it if you have access`;
20
+ const infraVar = (name, neededBy) => ({
21
+ name,
22
+ tier: "optional",
23
+ source: "vault",
24
+ doctor: false,
25
+ vault: INFRA_VAULT,
26
+ neededBy,
27
+ howToGet: inInfraVault,
28
+ section: SECTION_INFRA,
29
+ });
30
+ const portalVar = (name) => ({
31
+ ...infraVar(name, "team-web portal local dev"),
32
+ section: SECTION_PORTAL,
33
+ });
34
+ const paymentsVar = (name) => ({
35
+ ...infraVar(name, "payments workflows"),
36
+ section: SECTION_PAYMENTS,
37
+ });
38
+ /**
39
+ * Single source of truth for every workspace-root .env var: doctor derives
40
+ * its env checks from it, `ia env fill` knows which vars 1Password can
41
+ * supply, and templates/env.example is generated from it
42
+ * (`pnpm generate:env-example` — a drift test keeps the two in sync).
43
+ */
44
+ export const ENV_VARS = [
45
+ {
46
+ name: GITHUB_API_TOKEN_ENV,
47
+ tier: "optional",
48
+ source: "personal",
49
+ doctor: false,
50
+ neededBy: "ia client-build, client-linear, client-intake",
51
+ howToGet: "normally not needed — run `gh auth login` instead; set only to override the gh CLI token",
52
+ section: SECTION_DRIVERS,
53
+ comment: "normally EMPTY — GitHub auth comes from `gh auth login` (no PAT, no\napproval wait). Set only to override with a fine-grained PAT.",
54
+ },
55
+ {
56
+ name: LINEAR_API_TOKEN_ENV,
57
+ tier: "required",
58
+ source: "personal",
59
+ doctor: true,
60
+ neededBy: "ia linear-project, client-linear, client-intake",
61
+ howToGet: "Linear → Settings → Security & access → personal API key",
62
+ section: SECTION_DRIVERS,
63
+ comment: "your personal Linear API key — Linear → Settings → Security & access",
64
+ },
65
+ {
66
+ name: LINEAR_CLIENT_TEAM_ID_ENV,
67
+ tier: "optional",
68
+ source: "vault",
69
+ doctor: true,
70
+ vault: DEFAULT_TECH_VAULT,
71
+ neededBy: "ia client-intake",
72
+ howToGet: `the fixed Linear client team's ID — ${inTechVault}`,
73
+ section: SECTION_DRIVERS,
74
+ comment: "the fixed Linear client team's ID — filled by `ia env fill`",
75
+ },
76
+ {
77
+ name: DOCS_SESSION_ENV,
78
+ tier: "required",
79
+ source: "personal",
80
+ doctor: true,
81
+ neededBy: "ia docs search",
82
+ howToGet: "copy the __Secure-authjs.session-token cookie from a logged-in team.installagent.com tab (expires periodically)",
83
+ section: SECTION_DRIVERS,
84
+ comment: "team.installagent.com __Secure-authjs.session-token cookie (expires periodically)",
85
+ },
86
+ {
87
+ name: PORTAL_ADMIN_SECRET_ENV,
88
+ tier: "optional",
89
+ source: "vault",
90
+ doctor: true,
91
+ vault: DEFAULT_TECH_VAULT,
92
+ neededBy: "ia portal",
93
+ howToGet: `the portal admin API bearer — ${inTechVault}`,
94
+ section: SECTION_DRIVERS,
95
+ comment: "portal.installagent.com admin API bearer — filled by `ia env fill`",
96
+ },
97
+ {
98
+ name: AIRTABLE_API_TOKEN_ENV,
99
+ tier: "required",
100
+ source: "vault",
101
+ doctor: true,
102
+ vault: DEFAULT_TECH_VAULT,
103
+ neededBy: "ia client-drive",
104
+ howToGet: `read-only Airtable PAT (data.records:read on Clients - Master) — ${inTechVault}`,
105
+ section: SECTION_DRIVERS,
106
+ comment: "read-only Airtable PAT (data.records:read on Clients - Master) — `ia env fill`",
107
+ },
108
+ {
109
+ name: GOOGLE_SERVICE_ACCOUNT_KEY_ENV,
110
+ tier: "required",
111
+ source: "vault",
112
+ doctor: true,
113
+ vault: DEFAULT_TECH_VAULT,
114
+ neededBy: "ia client-drive",
115
+ howToGet: `the Drive service-account key JSON — ${inTechVault}`,
116
+ section: SECTION_DRIVERS,
117
+ comment: "the Drive service-account key JSON, single line — filled by `ia env fill`",
118
+ },
119
+ {
120
+ name: FATHOM_API_KEY_ENV,
121
+ tier: "optional",
122
+ source: "vault",
123
+ doctor: true,
124
+ vault: DEFAULT_TECH_VAULT,
125
+ neededBy: "ia secrets mint fathom-webhook",
126
+ howToGet: `the Fathom account API key — ${inTechVault}`,
127
+ section: SECTION_DRIVERS,
128
+ comment: "Fathom dashboard → Settings → API Access — filled by `ia env fill`",
129
+ },
130
+ {
131
+ name: N8N_API_URL_ENV,
132
+ tier: "required",
133
+ source: "vault",
134
+ doctor: true,
135
+ vault: DEFAULT_TECH_VAULT,
136
+ neededBy: "ia agent save",
137
+ howToGet: `the n8n API base URL including /api/v1 — ${inTechVault}`,
138
+ section: SECTION_DRIVERS,
139
+ comment: "n8n API base INCLUDING /api/v1, e.g. https://n8n.installagent.com/api/v1",
140
+ },
141
+ {
142
+ name: N8N_API_KEY_ENV,
143
+ tier: "required",
144
+ source: "vault",
145
+ doctor: true,
146
+ vault: DEFAULT_TECH_VAULT,
147
+ neededBy: "ia agent save",
148
+ howToGet: `an n8n API key — ${inTechVault}`,
149
+ section: SECTION_DRIVERS,
150
+ comment: "n8n → Settings → API — filled by `ia env fill`",
151
+ },
152
+ {
153
+ name: "GEMINI_API_KEY",
154
+ tier: "optional",
155
+ source: "vault",
156
+ doctor: false,
157
+ vault: DEFAULT_TECH_VAULT,
158
+ neededBy: "ia secrets mint gemini-api-key",
159
+ howToGet: inTechVault,
160
+ section: SECTION_DRIVERS,
161
+ },
162
+ infraVar("AIRTABLE_BASE_ID", "n8n workflows, team-infra scripts"),
163
+ infraVar("AIRTABLE_CLIENTS_TABLE_ID", "n8n workflows, team-infra scripts"),
164
+ infraVar("N8N_WEBHOOK_URL", "n8n workflows, team-infra scripts"),
165
+ infraVar("N8N_WEBHOOK_SECRET", "n8n workflows, team-infra scripts"),
166
+ infraVar("AGENT_INGEST_SECRET", "n8n workflows, team-infra scripts"),
167
+ infraVar("CRON_SECRET", "n8n workflows, team-infra scripts"),
168
+ portalVar("DATABASE_URL"),
169
+ portalVar("DATABASE_USER"),
170
+ portalVar("DATABASE_PASS"),
171
+ portalVar("AUTH_SECRET"),
172
+ portalVar("AUTH_GOOGLE_ID"),
173
+ portalVar("AUTH_GOOGLE_SECRET"),
174
+ portalVar("PORTAL_ADMIN_EMAILS"),
175
+ paymentsVar("STRIPE_SECRET_KEY"),
176
+ paymentsVar("STRIPE_WEBHOOK_SECRET"),
177
+ paymentsVar("STRIPE_WEBHOOK_URL"),
178
+ paymentsVar("STRIPE_BASE_URL"),
179
+ paymentsVar("PLAID_CLIENT_ID"),
180
+ paymentsVar("PLAID_SECRET"),
181
+ paymentsVar("PLAID_ACCESS_TOKEN"),
182
+ paymentsVar("PLAID_BASE_URL"),
183
+ ];
184
+ /** `op://<vault>/<item>/<field>` for a vault-sourced var. */
185
+ export function opSecretReference(spec) {
186
+ if (spec.source !== "vault" || !spec.vault) {
187
+ throw new Error(`${spec.name} is a personal var — it has no 1Password reference`);
188
+ }
189
+ return `op://${spec.vault}/${spec.item ?? spec.name}/${spec.field ?? OP_DEFAULT_FIELD}`;
190
+ }
191
+ const ENV_EXAMPLE_HEADER = `# installagent/ workspace root .env — ONE env file for the whole workspace.
192
+ #
193
+ # - \`ia\` commands load this automatically (vars already set in your shell win).
194
+ # - 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\`).
196
+ # Personal values (marked below) you fill by hand. NEVER commit this file
197
+ # anywhere — the root is not a git repo, and no repo may ever contain it.
198
+ # Only env.example (this placeholder layout, no values) is shareable.
199
+ # - \`ia doctor -w <workspace>\` tells you which vars are still missing and why.
200
+ `;
201
+ const SECTION_RULE_WIDTH = 79;
202
+ function sectionHeading(title) {
203
+ const prefix = `# ── ${title} `;
204
+ return prefix + "─".repeat(Math.max(0, SECTION_RULE_WIDTH - prefix.length));
205
+ }
206
+ /**
207
+ * Render the canonical templates/env.example content from the registry.
208
+ * scripts/generate-env-example.mjs writes it; a drift test asserts the
209
+ * bundled file matches.
210
+ */
211
+ export function renderEnvExample() {
212
+ const lines = [ENV_EXAMPLE_HEADER];
213
+ let currentSection = null;
214
+ for (const spec of ENV_VARS) {
215
+ if (spec.section !== currentSection) {
216
+ currentSection = spec.section;
217
+ lines.push(sectionHeading(currentSection));
218
+ }
219
+ lines.push(`${spec.name}=`);
220
+ if (spec.comment) {
221
+ for (const commentLine of spec.comment.split("\n")) {
222
+ lines.push(`# ${commentLine}`);
223
+ }
224
+ }
225
+ const next = ENV_VARS[ENV_VARS.indexOf(spec) + 1];
226
+ if (!next || next.section !== spec.section)
227
+ lines.push("");
228
+ }
229
+ return `${lines.join("\n").trimEnd()}\n`;
230
+ }
package/dist/exec.d.ts ADDED
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Injectable subprocess runner — mint operations take an `execFileImpl`
3
+ * option so tests substitute a fake instead of invoking the real gcloud.
4
+ */
5
+ export type ExecFileFn = (file: string, args: readonly string[]) => Promise<{
6
+ stdout: string;
7
+ stderr: string;
8
+ }>;
9
+ export declare const execFileAsync: ExecFileFn;
10
+ /** Pull code/stderr off an execFile rejection without touching stdout (it may hold a secret). */
11
+ export declare function execFailureDetail(error: unknown): {
12
+ code?: string;
13
+ detail: string;
14
+ };
package/dist/exec.js ADDED
@@ -0,0 +1,16 @@
1
+ import { execFile } from "node:child_process";
2
+ import { promisify } from "node:util";
3
+ export const execFileAsync = async (file, args) => {
4
+ const { stdout, stderr } = await promisify(execFile)(file, [...args]);
5
+ return { stdout, stderr };
6
+ };
7
+ /** Pull code/stderr off an execFile rejection without touching stdout (it may hold a secret). */
8
+ export function execFailureDetail(error) {
9
+ if (error && typeof error === "object") {
10
+ const err = error;
11
+ const stderr = typeof err.stderr === "string" ? err.stderr.trim() : "";
12
+ const message = error instanceof Error ? error.message : String(error);
13
+ return { code: typeof err.code === "string" ? err.code : undefined, detail: stderr || message };
14
+ }
15
+ return { detail: String(error) };
16
+ }