@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.
- package/dist/agent-templates.d.ts +90 -0
- package/dist/agent-templates.js +211 -0
- package/dist/client-build.d.ts +50 -0
- package/dist/client-build.js +155 -0
- package/dist/client-context.d.ts +40 -0
- package/dist/client-context.js +70 -0
- package/dist/client-drive.d.ts +67 -0
- package/dist/client-drive.js +278 -0
- package/dist/client-intake.d.ts +68 -0
- package/dist/client-intake.js +189 -0
- package/dist/client-linear.d.ts +30 -0
- package/dist/client-linear.js +85 -0
- package/dist/docs-search.d.ts +44 -0
- package/dist/docs-search.js +187 -0
- package/dist/doctor.d.ts +43 -0
- package/dist/doctor.js +425 -0
- package/dist/env-file.d.ts +25 -0
- package/dist/env-file.js +69 -0
- package/dist/env-fill.d.ts +43 -0
- package/dist/env-fill.js +161 -0
- package/dist/env-push.d.ts +37 -0
- package/dist/env-push.js +137 -0
- package/dist/env-registry.d.ts +49 -0
- package/dist/env-registry.js +230 -0
- package/dist/exec.d.ts +14 -0
- package/dist/exec.js +16 -0
- package/dist/fathom-webhook.d.ts +44 -0
- package/dist/fathom-webhook.js +123 -0
- package/dist/fs-utils.d.ts +9 -0
- package/dist/fs-utils.js +34 -0
- package/dist/gcp-service-account-key.d.ts +37 -0
- package/dist/gcp-service-account-key.js +66 -0
- package/dist/gemini-api-key.d.ts +47 -0
- package/dist/gemini-api-key.js +132 -0
- package/dist/git.d.ts +16 -0
- package/dist/git.js +29 -0
- package/dist/github-token.d.ts +24 -0
- package/dist/github-token.js +30 -0
- package/dist/index.d.ts +25 -0
- package/dist/index.js +28 -0
- package/dist/init.d.ts +47 -0
- package/dist/init.js +101 -0
- package/dist/linear-project.d.ts +81 -0
- package/dist/linear-project.js +192 -0
- package/dist/new-client.d.ts +32 -0
- package/dist/new-client.js +89 -0
- package/dist/ping.d.ts +6 -0
- package/dist/ping.js +7 -0
- package/dist/portal-admin.d.ts +133 -0
- package/dist/portal-admin.js +144 -0
- package/dist/sync-templates.d.ts +58 -0
- package/dist/sync-templates.js +109 -0
- package/dist/template-sync.d.ts +55 -0
- package/dist/template-sync.js +90 -0
- package/dist/templates.d.ts +19 -0
- package/dist/templates.js +24 -0
- package/dist/wizard.d.ts +78 -0
- package/dist/wizard.js +213 -0
- package/package.json +30 -0
- package/templates/env.example +60 -0
- package/templates/workspace-root/.claude/settings.json +39 -0
- package/templates/workspace-root/AGENT.md +205 -0
- package/templates/workspace-root/AGENTS.md +11 -0
- package/templates/workspace-root/CLAUDE.md +63 -0
- package/templates/workspace-root/GEMINI.md +24 -0
- package/templates/workspace-root/ONBOARDING.md +164 -0
- package/templates/workspace-root/README.md +67 -0
- package/templates/workspace-root/skills/CLAUDE.md +79 -0
- package/templates/workspace-root/skills/client-deliverables/SKILL.md +131 -0
- package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +103 -0
- package/templates/workspace-root/skills/client-facing-docs/SKILL.md +131 -0
- package/templates/workspace-root/skills/client-facing-docs/references/doc-structures.md +81 -0
- package/templates/workspace-root/skills/client-llm-setup/SKILL.md +97 -0
- package/templates/workspace-root/skills/client-llm-setup/references/guide-template.md +87 -0
- package/templates/workspace-root/skills/client-workflow-diagram/SKILL.md +141 -0
- package/templates/workspace-root/skills/client-workflow-diagram/references/excalidraw-format.md +140 -0
- package/templates/workspace-root/skills/contract-tech-agnostic/SKILL.md +99 -0
- package/templates/workspace-root/skills/contract-tech-agnostic/references/Install_Agent_SOW_Template.docx +0 -0
- package/templates/workspace-root/skills/design-system/SKILL.md +118 -0
- package/templates/workspace-root/skills/design-system/references/tokens.md +139 -0
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +272 -0
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +220 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +158 -0
- package/templates/workspace-root/skills/house-voice/references/source-copy.md +173 -0
- package/templates/workspace-root/skills/ia-cli/SKILL.md +87 -0
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +112 -0
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-logo.svg +1 -0
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-mark.svg +1 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/brand-tokens.md +71 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +66 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/excalidraw-red-theme.md +73 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +175 -0
- package/templates/workspace-root/skills/linear/SKILL.md +186 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +141 -0
package/dist/doctor.js
ADDED
|
@@ -0,0 +1,425 @@
|
|
|
1
|
+
import { existsSync, readdirSync, readFileSync } from "node:fs";
|
|
2
|
+
import { join, resolve } from "node:path";
|
|
3
|
+
import { N8N_API_KEY_ENV, N8N_API_URL_ENV } from "./agent-templates.js";
|
|
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";
|
|
6
|
+
import { parseEnvFile } from "./env-file.js";
|
|
7
|
+
import { DEFAULT_TECH_VAULT, ENV_VARS, opSecretReference, } from "./env-registry.js";
|
|
8
|
+
import { execFailureDetail, execFileAsync } from "./exec.js";
|
|
9
|
+
import { GITHUB_API_TOKEN_ENV, GITHUB_TOKEN_FIX } from "./github-token.js";
|
|
10
|
+
import { LINEAR_API_TOKEN_ENV } from "./linear-project.js";
|
|
11
|
+
const WORKSPACE_CHECKS = [
|
|
12
|
+
{
|
|
13
|
+
name: "team-clients",
|
|
14
|
+
relPath: "team-clients",
|
|
15
|
+
whenAbsent: "missing",
|
|
16
|
+
fixIt: "run `ia init` in the workspace root to clone it",
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
name: "clients",
|
|
20
|
+
relPath: "clients",
|
|
21
|
+
whenAbsent: "missing",
|
|
22
|
+
fixIt: "run `ia init` in the workspace root to create it",
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
name: "client-template",
|
|
26
|
+
relPath: join("clients", "client-template"),
|
|
27
|
+
whenAbsent: "missing",
|
|
28
|
+
fixIt: "run `ia init` in the workspace root to clone it",
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
name: "root-docs",
|
|
32
|
+
relPath: "AGENT.md",
|
|
33
|
+
whenAbsent: "missing",
|
|
34
|
+
fixIt: "run `ia init` in the workspace root to lay down the orientation docs",
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
name: "skills",
|
|
38
|
+
relPath: "skills",
|
|
39
|
+
whenAbsent: "missing",
|
|
40
|
+
fixIt: "run `ia init` in the workspace root to lay down the bundled skills",
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
// Optional: shell-exported vars work too, so absence only warns.
|
|
44
|
+
name: "root-env",
|
|
45
|
+
relPath: ".env",
|
|
46
|
+
whenAbsent: "warn",
|
|
47
|
+
fixIt: "the one shared env file `ia` auto-loads — run `ia wizard` (or copy .env.example), then `ia env fill`",
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
// ia init deliberately doesn't clone the workflow bank, so absence only warns.
|
|
51
|
+
name: "agents",
|
|
52
|
+
relPath: "agents",
|
|
53
|
+
whenAbsent: "warn",
|
|
54
|
+
fixIt: "only needed for `ia agent` — put the agents/ workflow-bank repo at the workspace root (see workspace AGENT.md)",
|
|
55
|
+
},
|
|
56
|
+
];
|
|
57
|
+
/**
|
|
58
|
+
* Technician checkup: workspace layout, the gcloud/gh/op CLIs, the env vars
|
|
59
|
+
* the `ia` commands read (derived from the ENV_VARS registry so doctor can
|
|
60
|
+
* never drift from what the operations read), per-clone lefthook hooks, and
|
|
61
|
+
* whether the root .env has a line for every registry var. Set credentials
|
|
62
|
+
* are validated live against their APIs — a revoked token or expired cookie
|
|
63
|
+
* reads `missing`, not green — unless `offline` is set (then presence only).
|
|
64
|
+
* Nothing is ever written and no secret value is ever included in a result;
|
|
65
|
+
* a network hiccup during validation downgrades to a warning, never a
|
|
66
|
+
* failure. `ok` is false only when a core check is `missing`; role-specific
|
|
67
|
+
* gaps surface as warnings.
|
|
68
|
+
*/
|
|
69
|
+
export async function doctor(options = {}) {
|
|
70
|
+
const workspaceDir = resolve(options.workspaceDir ?? ".");
|
|
71
|
+
const env = options.env ?? process.env;
|
|
72
|
+
const execFileImpl = options.execFileImpl ?? execFileAsync;
|
|
73
|
+
const fetchImpl = options.fetchImpl ?? fetch;
|
|
74
|
+
const offline = options.offline ?? false;
|
|
75
|
+
const checks = [];
|
|
76
|
+
for (const spec of WORKSPACE_CHECKS) {
|
|
77
|
+
const present = existsSync(join(workspaceDir, spec.relPath));
|
|
78
|
+
checks.push({
|
|
79
|
+
id: `workspace/${spec.name}`,
|
|
80
|
+
group: "workspace",
|
|
81
|
+
status: present ? "ok" : spec.whenAbsent,
|
|
82
|
+
label: `${spec.relPath} in the workspace`,
|
|
83
|
+
detail: present
|
|
84
|
+
? `${spec.relPath} present`
|
|
85
|
+
: `${spec.relPath} not found under ${workspaceDir}`,
|
|
86
|
+
...(present ? {} : { fixIt: spec.fixIt }),
|
|
87
|
+
});
|
|
88
|
+
}
|
|
89
|
+
checks.push(lefthookCheck(workspaceDir));
|
|
90
|
+
const envFreshness = envFreshnessCheck(workspaceDir);
|
|
91
|
+
if (envFreshness)
|
|
92
|
+
checks.push(envFreshness);
|
|
93
|
+
checks.push(await ghCheck(execFileImpl, env));
|
|
94
|
+
checks.push(await opCheck(execFileImpl));
|
|
95
|
+
checks.push(await gcloudCheck(execFileImpl));
|
|
96
|
+
for (const spec of ENV_VARS) {
|
|
97
|
+
if (!spec.doctor)
|
|
98
|
+
continue;
|
|
99
|
+
const value = env[spec.name];
|
|
100
|
+
const present = typeof value === "string" && value.length > 0;
|
|
101
|
+
if (!present) {
|
|
102
|
+
checks.push({
|
|
103
|
+
id: `env/${spec.name}`,
|
|
104
|
+
group: "env",
|
|
105
|
+
status: spec.tier === "required" ? "missing" : "warn",
|
|
106
|
+
label: `$${spec.name}`,
|
|
107
|
+
detail: "not set",
|
|
108
|
+
fixIt: envFixIt(spec),
|
|
109
|
+
});
|
|
110
|
+
continue;
|
|
111
|
+
}
|
|
112
|
+
checks.push(await envValueCheck(spec, value, env, fetchImpl, offline));
|
|
113
|
+
}
|
|
114
|
+
return {
|
|
115
|
+
ok: checks.every((check) => check.status !== "missing"),
|
|
116
|
+
workspaceDir,
|
|
117
|
+
checks,
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
function envFixIt(spec) {
|
|
121
|
+
return spec.source === "vault"
|
|
122
|
+
? `needed by ${spec.neededBy} — run \`ia env fill\` (fills it from 1Password: ${opSecretReference(spec)})`
|
|
123
|
+
: `needed by ${spec.neededBy} — ${spec.howToGet}, then set ${spec.name} in the workspace root .env (or export it in ~/.zshrc)`;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Per-clone git hooks: lefthook wires the repo-lint pre-commit gate, but
|
|
127
|
+
* `lefthook install` is manual after every clone — a repo without it
|
|
128
|
+
* silently stops enforcing the skeleton rules, and client repos are often
|
|
129
|
+
* local-only so no CI catches it either.
|
|
130
|
+
*/
|
|
131
|
+
function lefthookCheck(workspaceDir) {
|
|
132
|
+
const base = {
|
|
133
|
+
id: "workspace/lefthook-hooks",
|
|
134
|
+
group: "workspace",
|
|
135
|
+
label: "lefthook hooks in cloned client repos",
|
|
136
|
+
};
|
|
137
|
+
const clientsDir = join(workspaceDir, "clients");
|
|
138
|
+
if (!existsSync(clientsDir)) {
|
|
139
|
+
return { ...base, status: "ok", detail: "no clients/ dir yet — nothing to check" };
|
|
140
|
+
}
|
|
141
|
+
const gitRepos = readdirSync(clientsDir, { withFileTypes: true })
|
|
142
|
+
.filter((entry) => entry.isDirectory() && entry.name.startsWith("client-"))
|
|
143
|
+
.map((entry) => entry.name)
|
|
144
|
+
.filter((name) => existsSync(join(clientsDir, name, ".git")))
|
|
145
|
+
.sort();
|
|
146
|
+
if (gitRepos.length === 0) {
|
|
147
|
+
return { ...base, status: "ok", detail: "no client git repos cloned yet — nothing to check" };
|
|
148
|
+
}
|
|
149
|
+
const unhooked = gitRepos.filter((name) => {
|
|
150
|
+
const hookPath = join(clientsDir, name, ".git", "hooks", "pre-commit");
|
|
151
|
+
if (!existsSync(hookPath))
|
|
152
|
+
return true;
|
|
153
|
+
return !readFileSync(hookPath, "utf8").includes("lefthook");
|
|
154
|
+
});
|
|
155
|
+
if (unhooked.length === 0) {
|
|
156
|
+
return {
|
|
157
|
+
...base,
|
|
158
|
+
status: "ok",
|
|
159
|
+
detail: `all ${gitRepos.length} client repo(s) have the pre-commit hook installed`,
|
|
160
|
+
};
|
|
161
|
+
}
|
|
162
|
+
return {
|
|
163
|
+
...base,
|
|
164
|
+
status: "warn",
|
|
165
|
+
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)",
|
|
167
|
+
};
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* The root .env is created once from env.example and never overwritten, so
|
|
171
|
+
* vars added to the registry later are silently absent from older files —
|
|
172
|
+
* `ia env fill` can only fill lines that exist. Only key names are compared;
|
|
173
|
+
* values never leave this function.
|
|
174
|
+
*/
|
|
175
|
+
function envFreshnessCheck(workspaceDir) {
|
|
176
|
+
const envPath = join(workspaceDir, ".env");
|
|
177
|
+
if (!existsSync(envPath))
|
|
178
|
+
return null; // the root-env workspace check already covers absence
|
|
179
|
+
const presentNames = new Set(Object.keys(parseEnvFile(readFileSync(envPath, "utf8"))));
|
|
180
|
+
const missing = ENV_VARS.map((spec) => spec.name).filter((name) => !presentNames.has(name));
|
|
181
|
+
const base = {
|
|
182
|
+
id: "workspace/env-freshness",
|
|
183
|
+
group: "workspace",
|
|
184
|
+
label: ".env is current with the var registry",
|
|
185
|
+
};
|
|
186
|
+
if (missing.length === 0) {
|
|
187
|
+
return { ...base, status: "ok", detail: "has a line for every registry var" };
|
|
188
|
+
}
|
|
189
|
+
return {
|
|
190
|
+
...base,
|
|
191
|
+
status: "warn",
|
|
192
|
+
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`",
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
const LIVE_CHECK_TIMEOUT_MS = 5000;
|
|
197
|
+
/**
|
|
198
|
+
* One cheap read-only API call per credential doctor knows how to verify.
|
|
199
|
+
* Secrets travel only to their own service, exactly as the ia commands
|
|
200
|
+
* would send them; nothing from the response beyond validity (and an
|
|
201
|
+
* account label) ends up in the result.
|
|
202
|
+
*/
|
|
203
|
+
const LIVE_VALIDATORS = {
|
|
204
|
+
[LINEAR_API_TOKEN_ENV]: async (value, _env, fetchImpl) => {
|
|
205
|
+
const res = await fetchImpl("https://api.linear.app/graphql", {
|
|
206
|
+
method: "POST",
|
|
207
|
+
headers: { "Content-Type": "application/json", Authorization: value },
|
|
208
|
+
body: JSON.stringify({ query: "{ viewer { email } }" }),
|
|
209
|
+
signal: AbortSignal.timeout(LIVE_CHECK_TIMEOUT_MS),
|
|
210
|
+
});
|
|
211
|
+
if (!res.ok)
|
|
212
|
+
return { outcome: "invalid", detail: `Linear rejected it (HTTP ${res.status})` };
|
|
213
|
+
const body = (await res.json());
|
|
214
|
+
const email = body.data?.viewer?.email;
|
|
215
|
+
if (!email)
|
|
216
|
+
return { outcome: "invalid", detail: "Linear rejected it (no viewer)" };
|
|
217
|
+
return { outcome: "valid", detail: `Linear accepts it (${email})` };
|
|
218
|
+
},
|
|
219
|
+
[AIRTABLE_API_TOKEN_ENV]: async (value, _env, fetchImpl) => {
|
|
220
|
+
const res = await fetchImpl("https://api.airtable.com/v0/meta/whoami", {
|
|
221
|
+
headers: { Authorization: `Bearer ${value}` },
|
|
222
|
+
signal: AbortSignal.timeout(LIVE_CHECK_TIMEOUT_MS),
|
|
223
|
+
});
|
|
224
|
+
if (!res.ok)
|
|
225
|
+
return { outcome: "invalid", detail: `Airtable rejected it (HTTP ${res.status})` };
|
|
226
|
+
return { outcome: "valid", detail: "Airtable accepts it" };
|
|
227
|
+
},
|
|
228
|
+
[DOCS_SESSION_ENV]: async (value, _env, fetchImpl) => {
|
|
229
|
+
const res = await fetchImpl(`${TEAM_DOCS_BASE_URL}/docs`, {
|
|
230
|
+
headers: { cookie: `__Secure-authjs.session-token=${value}` },
|
|
231
|
+
redirect: "manual",
|
|
232
|
+
signal: AbortSignal.timeout(LIVE_CHECK_TIMEOUT_MS),
|
|
233
|
+
});
|
|
234
|
+
if (res.status >= 300 && res.status < 400) {
|
|
235
|
+
return {
|
|
236
|
+
outcome: "invalid",
|
|
237
|
+
detail: `${TEAM_DOCS_BASE_URL} redirected to login — the session cookie expired`,
|
|
238
|
+
};
|
|
239
|
+
}
|
|
240
|
+
if (!res.ok) {
|
|
241
|
+
return {
|
|
242
|
+
outcome: "invalid",
|
|
243
|
+
detail: `${TEAM_DOCS_BASE_URL} rejected it (HTTP ${res.status})`,
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
return { outcome: "valid", detail: "the docs hub accepts it" };
|
|
247
|
+
},
|
|
248
|
+
[N8N_API_KEY_ENV]: async (value, env, fetchImpl) => {
|
|
249
|
+
const baseUrl = env[N8N_API_URL_ENV];
|
|
250
|
+
if (!baseUrl) {
|
|
251
|
+
return { outcome: "unverified", detail: `can't verify without $${N8N_API_URL_ENV}` };
|
|
252
|
+
}
|
|
253
|
+
const res = await fetchImpl(`${baseUrl.replace(/\/+$/, "")}/workflows?limit=1`, {
|
|
254
|
+
headers: { "X-N8N-API-KEY": value },
|
|
255
|
+
signal: AbortSignal.timeout(LIVE_CHECK_TIMEOUT_MS),
|
|
256
|
+
});
|
|
257
|
+
if (!res.ok)
|
|
258
|
+
return { outcome: "invalid", detail: `n8n rejected it (HTTP ${res.status})` };
|
|
259
|
+
return { outcome: "valid", detail: "n8n accepts it" };
|
|
260
|
+
},
|
|
261
|
+
};
|
|
262
|
+
async function envValueCheck(spec, value, env, fetchImpl, offline) {
|
|
263
|
+
const base = { id: `env/${spec.name}`, group: "env", label: `$${spec.name}` };
|
|
264
|
+
// Structural, not network: a Drive key that doesn't parse fails everywhere.
|
|
265
|
+
if (spec.name === GOOGLE_SERVICE_ACCOUNT_KEY_ENV) {
|
|
266
|
+
if (!isServiceAccountKey(value)) {
|
|
267
|
+
return {
|
|
268
|
+
...base,
|
|
269
|
+
status: "missing",
|
|
270
|
+
detail: "set but not a service-account key JSON",
|
|
271
|
+
fixIt: `re-fill it — ${spec.howToGet} (single line, the full key JSON)`,
|
|
272
|
+
};
|
|
273
|
+
}
|
|
274
|
+
return { ...base, status: "ok", detail: `set and parses (needed by ${spec.neededBy})` };
|
|
275
|
+
}
|
|
276
|
+
const validator = LIVE_VALIDATORS[spec.name];
|
|
277
|
+
if (offline || !validator) {
|
|
278
|
+
return { ...base, status: "ok", detail: `set (needed by ${spec.neededBy})` };
|
|
279
|
+
}
|
|
280
|
+
let live;
|
|
281
|
+
try {
|
|
282
|
+
live = await validator(value, env, fetchImpl);
|
|
283
|
+
}
|
|
284
|
+
catch (error) {
|
|
285
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
286
|
+
live = { outcome: "unverified", detail: `could not reach the API (${message})` };
|
|
287
|
+
}
|
|
288
|
+
if (live.outcome === "valid") {
|
|
289
|
+
return { ...base, status: "ok", detail: `set and verified — ${live.detail}` };
|
|
290
|
+
}
|
|
291
|
+
if (live.outcome === "invalid") {
|
|
292
|
+
return {
|
|
293
|
+
...base,
|
|
294
|
+
status: "missing",
|
|
295
|
+
detail: `set but rejected — ${live.detail}`,
|
|
296
|
+
fixIt: `the stored value is stale or revoked — ${spec.howToGet}, then update it (\`ia doctor --offline\` skips live validation)`,
|
|
297
|
+
};
|
|
298
|
+
}
|
|
299
|
+
return {
|
|
300
|
+
...base,
|
|
301
|
+
status: "warn",
|
|
302
|
+
detail: `set but unverified — ${live.detail}`,
|
|
303
|
+
fixIt: "re-run `ia doctor` when online, or pass --offline to skip live validation",
|
|
304
|
+
};
|
|
305
|
+
}
|
|
306
|
+
function isServiceAccountKey(value) {
|
|
307
|
+
try {
|
|
308
|
+
const parsed = JSON.parse(value);
|
|
309
|
+
return parsed.type === "service_account";
|
|
310
|
+
}
|
|
311
|
+
catch {
|
|
312
|
+
return false;
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
const GH_NEEDED_BY = "ia client-build, client-linear, client-intake";
|
|
316
|
+
/**
|
|
317
|
+
* GitHub auth: `gh auth status` is the day-one path (OAuth, no PAT, no
|
|
318
|
+
* org-approval wait); a set $GITHUB_API_TOKEN passes too, as an override.
|
|
319
|
+
* This check carries the required-ness — there is no env check for the
|
|
320
|
+
* override var.
|
|
321
|
+
*/
|
|
322
|
+
async function ghCheck(execFileImpl, env) {
|
|
323
|
+
const base = { id: "tools/gh", group: "tools", label: "GitHub auth (gh CLI)" };
|
|
324
|
+
const override = env[GITHUB_API_TOKEN_ENV];
|
|
325
|
+
try {
|
|
326
|
+
await execFileImpl("gh", ["auth", "status", "--hostname", "github.com"]);
|
|
327
|
+
return { ...base, status: "ok", detail: "gh is logged in to github.com" };
|
|
328
|
+
}
|
|
329
|
+
catch (error) {
|
|
330
|
+
const { code, detail } = execFailureDetail(error);
|
|
331
|
+
const ghState = code === "ENOENT" ? "gh CLI not found on PATH" : `gh is not logged in`;
|
|
332
|
+
if (override) {
|
|
333
|
+
return {
|
|
334
|
+
...base,
|
|
335
|
+
status: "ok",
|
|
336
|
+
detail: `using $${GITHUB_API_TOKEN_ENV} override (${ghState})`,
|
|
337
|
+
};
|
|
338
|
+
}
|
|
339
|
+
if (code === "ENOENT") {
|
|
340
|
+
return {
|
|
341
|
+
...base,
|
|
342
|
+
status: "missing",
|
|
343
|
+
detail: ghState,
|
|
344
|
+
fixIt: `needed by ${GH_NEEDED_BY} — install the GitHub CLI (\`brew install gh\`), then ${GITHUB_TOKEN_FIX}`,
|
|
345
|
+
};
|
|
346
|
+
}
|
|
347
|
+
return {
|
|
348
|
+
...base,
|
|
349
|
+
status: "missing",
|
|
350
|
+
detail: `${ghState}: ${detail}`,
|
|
351
|
+
fixIt: `needed by ${GH_NEEDED_BY} — ${GITHUB_TOKEN_FIX}`,
|
|
352
|
+
};
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
/**
|
|
356
|
+
* 1Password CLI: powers `ia env fill` (shared secrets come from the team
|
|
357
|
+
* vaults). Warn-only — a technician can still fill .env by hand.
|
|
358
|
+
*/
|
|
359
|
+
async function opCheck(execFileImpl) {
|
|
360
|
+
const base = { id: "tools/op", group: "tools", label: "1Password CLI (op)" };
|
|
361
|
+
try {
|
|
362
|
+
const { stdout } = await execFileImpl("op", ["whoami"]);
|
|
363
|
+
const email = stdout.match(/Email:\s*(\S+)/)?.[1];
|
|
364
|
+
return {
|
|
365
|
+
...base,
|
|
366
|
+
status: "ok",
|
|
367
|
+
detail: email ? `signed in as ${email}` : "signed in",
|
|
368
|
+
};
|
|
369
|
+
}
|
|
370
|
+
catch (error) {
|
|
371
|
+
const { code } = execFailureDetail(error);
|
|
372
|
+
if (code === "ENOENT") {
|
|
373
|
+
return {
|
|
374
|
+
...base,
|
|
375
|
+
status: "warn",
|
|
376
|
+
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`",
|
|
378
|
+
};
|
|
379
|
+
}
|
|
380
|
+
return {
|
|
381
|
+
...base,
|
|
382
|
+
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\``,
|
|
385
|
+
};
|
|
386
|
+
}
|
|
387
|
+
}
|
|
388
|
+
async function gcloudCheck(execFileImpl) {
|
|
389
|
+
const base = { id: "tools/gcloud", group: "tools", label: "gcloud CLI" };
|
|
390
|
+
try {
|
|
391
|
+
const { stdout } = await execFileImpl("gcloud", [
|
|
392
|
+
"auth",
|
|
393
|
+
"list",
|
|
394
|
+
"--filter=status:ACTIVE",
|
|
395
|
+
"--format=value(account)",
|
|
396
|
+
]);
|
|
397
|
+
const account = stdout.trim().split("\n")[0] ?? "";
|
|
398
|
+
if (account.length === 0) {
|
|
399
|
+
return {
|
|
400
|
+
...base,
|
|
401
|
+
status: "warn",
|
|
402
|
+
detail: "gcloud is installed but has no active account",
|
|
403
|
+
fixIt: "only needed for `ia secrets mint gcp-*` — run `gcloud auth login`",
|
|
404
|
+
};
|
|
405
|
+
}
|
|
406
|
+
return { ...base, status: "ok", detail: `authenticated as ${account}` };
|
|
407
|
+
}
|
|
408
|
+
catch (error) {
|
|
409
|
+
const { code, detail } = execFailureDetail(error);
|
|
410
|
+
if (code === "ENOENT") {
|
|
411
|
+
return {
|
|
412
|
+
...base,
|
|
413
|
+
status: "warn",
|
|
414
|
+
detail: "gcloud CLI not found on PATH",
|
|
415
|
+
fixIt: "only needed for `ia secrets mint` — install the Google Cloud SDK (https://cloud.google.com/sdk) and run `gcloud auth login`",
|
|
416
|
+
};
|
|
417
|
+
}
|
|
418
|
+
return {
|
|
419
|
+
...base,
|
|
420
|
+
status: "warn",
|
|
421
|
+
detail: `gcloud auth list failed: ${detail}`,
|
|
422
|
+
fixIt: "only needed for `ia secrets mint` — run `gcloud auth login` and retry",
|
|
423
|
+
};
|
|
424
|
+
}
|
|
425
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/** Walk up from `startDir` to the nearest installagent/ workspace root, or null. */
|
|
2
|
+
export declare function findWorkspaceRoot(startDir?: string): string | null;
|
|
3
|
+
/** Minimal .env parser: KEY=value per line, `export ` prefix and quotes allowed. */
|
|
4
|
+
export declare function parseEnvFile(content: string): Record<string, string>;
|
|
5
|
+
export interface LoadWorkspaceEnvOptions {
|
|
6
|
+
/** Where to start the walk-up. Defaults to the current directory. */
|
|
7
|
+
startDir?: string;
|
|
8
|
+
/** Target environment. Defaults to process.env; tests pass a fixture. */
|
|
9
|
+
env?: Record<string, string | undefined>;
|
|
10
|
+
}
|
|
11
|
+
export interface LoadWorkspaceEnvResult {
|
|
12
|
+
/** The .env file that was read, or null when none applies (not an error). */
|
|
13
|
+
path: string | null;
|
|
14
|
+
/** Vars set from the file. */
|
|
15
|
+
loaded: string[];
|
|
16
|
+
/** Vars present in the file but already set in the environment — left alone. */
|
|
17
|
+
skippedExisting: string[];
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Load the workspace root's `.env` into `env`, never overriding anything
|
|
21
|
+
* already set and ignoring empty placeholder values. Silent no-op when run
|
|
22
|
+
* outside a workspace or when the root has no `.env` — callers shouldn't
|
|
23
|
+
* fail just because the technician exports vars in their shell instead.
|
|
24
|
+
*/
|
|
25
|
+
export declare function loadWorkspaceEnv(options?: LoadWorkspaceEnvOptions): LoadWorkspaceEnvResult;
|
package/dist/env-file.js
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
2
|
+
import { dirname, join, resolve } from "node:path";
|
|
3
|
+
/**
|
|
4
|
+
* One shared `.env` at the installagent/ workspace root serves every repo —
|
|
5
|
+
* `ia` loads it automatically (already-set shell vars always win), and shell
|
|
6
|
+
* scripts can `set -a; source .env; set +a`. The file is ungitted and
|
|
7
|
+
* secret-bearing; `ia wizard` lays down a placeholder copy from env.example
|
|
8
|
+
* and never overwrites it afterwards.
|
|
9
|
+
*/
|
|
10
|
+
/** A directory is the workspace root when all of these exist in it. */
|
|
11
|
+
const ROOT_MARKERS = ["AGENT.md", "skills", "clients"];
|
|
12
|
+
/** Walk up from `startDir` to the nearest installagent/ workspace root, or null. */
|
|
13
|
+
export function findWorkspaceRoot(startDir = process.cwd()) {
|
|
14
|
+
let dir = resolve(startDir);
|
|
15
|
+
for (;;) {
|
|
16
|
+
if (ROOT_MARKERS.every((marker) => existsSync(join(dir, marker))))
|
|
17
|
+
return dir;
|
|
18
|
+
const parent = dirname(dir);
|
|
19
|
+
if (parent === dir)
|
|
20
|
+
return null;
|
|
21
|
+
dir = parent;
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
/** Minimal .env parser: KEY=value per line, `export ` prefix and quotes allowed. */
|
|
25
|
+
export function parseEnvFile(content) {
|
|
26
|
+
const out = {};
|
|
27
|
+
for (const rawLine of content.split("\n")) {
|
|
28
|
+
const line = rawLine.trim();
|
|
29
|
+
if (line.length === 0 || line.startsWith("#"))
|
|
30
|
+
continue;
|
|
31
|
+
const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line);
|
|
32
|
+
if (!match)
|
|
33
|
+
continue;
|
|
34
|
+
let value = match[2].trim();
|
|
35
|
+
if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
|
|
36
|
+
(value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
|
|
37
|
+
value = value.slice(1, -1);
|
|
38
|
+
}
|
|
39
|
+
out[match[1]] = value;
|
|
40
|
+
}
|
|
41
|
+
return out;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Load the workspace root's `.env` into `env`, never overriding anything
|
|
45
|
+
* already set and ignoring empty placeholder values. Silent no-op when run
|
|
46
|
+
* outside a workspace or when the root has no `.env` — callers shouldn't
|
|
47
|
+
* fail just because the technician exports vars in their shell instead.
|
|
48
|
+
*/
|
|
49
|
+
export function loadWorkspaceEnv(options = {}) {
|
|
50
|
+
const env = options.env ?? process.env;
|
|
51
|
+
const root = findWorkspaceRoot(options.startDir);
|
|
52
|
+
const path = root ? join(root, ".env") : null;
|
|
53
|
+
if (path === null || !existsSync(path))
|
|
54
|
+
return { path: null, loaded: [], skippedExisting: [] };
|
|
55
|
+
const loaded = [];
|
|
56
|
+
const skippedExisting = [];
|
|
57
|
+
for (const [name, value] of Object.entries(parseEnvFile(readFileSync(path, "utf8")))) {
|
|
58
|
+
if (value.length === 0)
|
|
59
|
+
continue;
|
|
60
|
+
const existing = env[name];
|
|
61
|
+
if (typeof existing === "string" && existing.length > 0) {
|
|
62
|
+
skippedExisting.push(name);
|
|
63
|
+
continue;
|
|
64
|
+
}
|
|
65
|
+
env[name] = value;
|
|
66
|
+
loaded.push(name);
|
|
67
|
+
}
|
|
68
|
+
return { path, loaded, skippedExisting };
|
|
69
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { type ExecFileFn } from "./exec.js";
|
|
2
|
+
export interface EnvFillOptions {
|
|
3
|
+
/** installagent/ workspace root holding the .env. Defaults to the current dir. */
|
|
4
|
+
workspaceDir?: string;
|
|
5
|
+
/** Report what would change without writing anything. */
|
|
6
|
+
dryRun?: boolean;
|
|
7
|
+
/** Read every vault var from 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 EnvFillVarStatus = "filled" | "kept" | "personal" | "not-in-vault" | "failed";
|
|
13
|
+
export interface EnvFillVarResult {
|
|
14
|
+
name: string;
|
|
15
|
+
status: EnvFillVarStatus;
|
|
16
|
+
/** Human detail. NEVER contains the secret value. */
|
|
17
|
+
detail: string;
|
|
18
|
+
}
|
|
19
|
+
export interface EnvFillResult {
|
|
20
|
+
/** False when op is unavailable/signed out, or any var ended up `failed`. */
|
|
21
|
+
ok: boolean;
|
|
22
|
+
envPath: string;
|
|
23
|
+
dryRun: boolean;
|
|
24
|
+
/** True when .env didn't exist and was created from env.example first. */
|
|
25
|
+
created: boolean;
|
|
26
|
+
vars: EnvFillVarResult[];
|
|
27
|
+
/** Personal vars still empty after the fill — the technician's homework. */
|
|
28
|
+
personalRemaining: Array<{
|
|
29
|
+
name: string;
|
|
30
|
+
howToGet: string;
|
|
31
|
+
}>;
|
|
32
|
+
nextSteps: string[];
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Fill the workspace root .env from the team 1Password vaults via the `op`
|
|
36
|
+
* CLI: every vault-backed registry var that is still empty is read from
|
|
37
|
+
* `op://<vault>/<var name>/value` and written in place. Existing values are
|
|
38
|
+
* NEVER overwritten; personal vars (own Linear key, docs session cookie) are
|
|
39
|
+
* never vaulted and come back as homework in `personalRemaining`. The result
|
|
40
|
+
* carries statuses and op:// references only — never secret values — so it
|
|
41
|
+
* is safe to serialize over MCP.
|
|
42
|
+
*/
|
|
43
|
+
export declare function envFill(options?: EnvFillOptions): Promise<EnvFillResult>;
|