@installagent/sdk 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/dist/agent-templates.d.ts +36 -2
  2. package/dist/agent-templates.js +173 -3
  3. package/dist/client-linear-create.d.ts +26 -0
  4. package/dist/client-linear-create.js +46 -0
  5. package/dist/client-linear.d.ts +28 -9
  6. package/dist/client-linear.js +36 -14
  7. package/dist/docs-search.d.ts +19 -6
  8. package/dist/docs-search.js +32 -11
  9. package/dist/doctor.d.ts +9 -0
  10. package/dist/doctor.js +126 -23
  11. package/dist/env-fill.d.ts +13 -0
  12. package/dist/env-fill.js +34 -9
  13. package/dist/env-push.d.ts +3 -0
  14. package/dist/env-push.js +11 -6
  15. package/dist/env-registry.d.ts +25 -0
  16. package/dist/env-registry.js +69 -7
  17. package/dist/exec.js +15 -2
  18. package/dist/index.d.ts +14 -6
  19. package/dist/index.js +14 -6
  20. package/dist/linear-project.d.ts +2 -2
  21. package/dist/linear-project.js +2 -2
  22. package/dist/log.d.ts +28 -0
  23. package/dist/log.js +73 -0
  24. package/dist/n8n-executions.d.ts +85 -0
  25. package/dist/n8n-executions.js +259 -0
  26. package/dist/op-cli.d.ts +29 -0
  27. package/dist/op-cli.js +52 -0
  28. package/dist/platform.d.ts +35 -0
  29. package/dist/platform.js +39 -0
  30. package/dist/portal-admin.d.ts +40 -0
  31. package/dist/portal-admin.js +30 -0
  32. package/dist/standup.d.ts +88 -0
  33. package/dist/standup.js +235 -0
  34. package/dist/sync-repos.d.ts +47 -0
  35. package/dist/sync-repos.js +80 -0
  36. package/dist/template-sync.d.ts +10 -0
  37. package/dist/template-sync.js +11 -0
  38. package/dist/wizard.d.ts +15 -0
  39. package/dist/wizard.js +35 -56
  40. package/dist/workspace-docs.d.ts +44 -0
  41. package/dist/workspace-docs.js +73 -0
  42. package/package.json +2 -2
  43. package/templates/env.example +33 -23
  44. package/templates/workspace-root/AGENT.md +7 -5
  45. package/templates/workspace-root/ONBOARDING.md +65 -8
  46. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +102 -0
  47. package/templates/workspace-root/skills/CLAUDE.md +24 -6
  48. package/templates/workspace-root/skills/README.md +156 -0
  49. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
  50. package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
  51. package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
  52. package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
  53. package/templates/workspace-root/skills/client-latest/SKILL.md +301 -0
  54. package/templates/workspace-root/skills/client-latest/catchup.command.md +17 -0
  55. package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
  56. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +181 -0
  57. package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
  58. package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
  59. package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
  60. package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
  61. package/templates/workspace-root/skills/ia-cli/SKILL.md +19 -6
  62. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
  63. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
  64. package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
  65. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
  66. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
  67. package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
  68. package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
  69. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
  70. package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
  71. package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
  72. package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
  73. package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
  74. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
  75. package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
  76. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
  77. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
  78. package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
  79. package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
  80. package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
@@ -18,6 +18,16 @@
18
18
  * and onboarding.html are deliberately NOT here: they're per-client by
19
19
  * design, so byte-drift is expected, and repo-lint already enforces their
20
20
  * presence.
21
+ *
22
+ * pr-to-slack.yml (added 2026-08-22) is the review notification every repo
23
+ * posts to Slack's #notify-prs. It carries no client-specific content — the
24
+ * repo name comes from the GitHub event and the webhook URL from an org-level
25
+ * secret — so it syncs verbatim. Keeping it here matters more than for the
26
+ * lint chain: a per-repo edit to the Block Kit payload silently changes what
27
+ * the reviewer sees, and the n8n receiver ("GitHub PR Actions (Slack)")
28
+ * derives owner/repo/PR number by regex over the PR URL in the message
29
+ * blocks, so a repo that drops or reshapes that block breaks its own buttons
30
+ * with no error anywhere.
21
31
  */
22
32
  export declare const TEMPLATE_SYNCED_FILES: string[];
23
33
  export interface TemplateSyncOptions {
@@ -21,6 +21,16 @@ import { dirname, join, resolve } from "node:path";
21
21
  * and onboarding.html are deliberately NOT here: they're per-client by
22
22
  * design, so byte-drift is expected, and repo-lint already enforces their
23
23
  * presence.
24
+ *
25
+ * pr-to-slack.yml (added 2026-08-22) is the review notification every repo
26
+ * posts to Slack's #notify-prs. It carries no client-specific content — the
27
+ * repo name comes from the GitHub event and the webhook URL from an org-level
28
+ * secret — so it syncs verbatim. Keeping it here matters more than for the
29
+ * lint chain: a per-repo edit to the Block Kit payload silently changes what
30
+ * the reviewer sees, and the n8n receiver ("GitHub PR Actions (Slack)")
31
+ * derives owner/repo/PR number by regex over the PR URL in the message
32
+ * blocks, so a repo that drops or reshapes that block breaks its own buttons
33
+ * with no error anywhere.
24
34
  */
25
35
  export const TEMPLATE_SYNCED_FILES = [
26
36
  "CADENCE.md",
@@ -28,6 +38,7 @@ export const TEMPLATE_SYNCED_FILES = [
28
38
  "ci/repo-lint.test.mjs",
29
39
  "lefthook.yml",
30
40
  ".github/workflows/repo-lint.yml",
41
+ ".github/workflows/pr-to-slack.yml",
31
42
  ];
32
43
  /**
33
44
  * Compare (and optionally fix) the shared infra files every client-<slug>
package/dist/wizard.d.ts CHANGED
@@ -2,12 +2,23 @@ import { type DoctorResult } from "./doctor.js";
2
2
  import type { ExecFileFn } from "./exec.js";
3
3
  import { type CloneFn, type PullFn } from "./git.js";
4
4
  import { type McpRecommendation } from "./init.js";
5
+ import { type PlatformInfo } from "./platform.js";
5
6
  /**
6
7
  * The full team repo set a technician's workspace mirrors — everything at the
7
8
  * installagent/ root that lives on GitHub. client-<slug> build repos are
8
9
  * deliberately excluded: technicians clone only the client(s) they work on.
9
10
  */
10
11
  export declare const WIZARD_REPO_NAMES: readonly ["team-clients", "team-tools", "team-infra", "team-web", "team-design", "agents"];
12
+ /**
13
+ * How the wizard reaches GitHub. HTTPS is the default because onboarding step
14
+ * one is `gh auth login`, which installs git's credential helper — so HTTPS
15
+ * needs zero further setup on any platform. SSH needs a generated key, an
16
+ * ssh-agent and a GitHub upload, which is the single most common place a
17
+ * Windows technician stalls. `--ssh` keeps the old behaviour for anyone whose
18
+ * git already prefers it.
19
+ */
20
+ export type CloneProtocol = "https" | "ssh";
21
+ export declare const repoUrl: (name: string, protocol?: CloneProtocol) => string;
11
22
  export interface WizardStep {
12
23
  name: string;
13
24
  status: "created" | "updated" | "skipped" | "failed";
@@ -26,6 +37,10 @@ export interface WizardWorkspaceOptions {
26
37
  clone?: CloneFn;
27
38
  /** Injectable for tests; defaults to real `git pull --ff-only`. */
28
39
  pull?: PullFn;
40
+ /** Clone over SSH instead of HTTPS. Default https — see repoUrl. */
41
+ protocol?: CloneProtocol;
42
+ /** Injectable for tests; defaults to the running machine. Picks fix-it text. */
43
+ platform?: PlatformInfo;
29
44
  /**
30
45
  * Chain a doctor checkup after setup and derive the numbered next steps
31
46
  * from its live findings. Default true — pass false to skip the gh/op/
package/dist/wizard.js CHANGED
@@ -1,12 +1,13 @@
1
1
  import { existsSync } from "node:fs";
2
- import { copyFile, mkdir, readFile } from "node:fs/promises";
3
- import { dirname, join, resolve } from "node:path";
2
+ import { copyFile, mkdir } from "node:fs/promises";
3
+ import { join, resolve } from "node:path";
4
4
  import { doctor } from "./doctor.js";
5
- import { ENV_VARS } from "./env-registry.js";
6
- import { listFiles } from "./fs-utils.js";
5
+ import { TECH_ENV_VARS } from "./env-registry.js";
7
6
  import { gitClone, gitPullFfOnly } from "./git.js";
8
7
  import { MCP_RECOMMENDATIONS } from "./init.js";
9
- import { envExampleTemplatePath, workspaceRootTemplateDir } from "./templates.js";
8
+ import { opInstallFix } from "./op-cli.js";
9
+ import { detectPlatformInfo } from "./platform.js";
10
+ import { refreshEnvExample, refreshWorkspaceDocs } from "./workspace-docs.js";
10
11
  /**
11
12
  * The full team repo set a technician's workspace mirrors — everything at the
12
13
  * installagent/ root that lives on GitHub. client-<slug> build repos are
@@ -20,7 +21,9 @@ export const WIZARD_REPO_NAMES = [
20
21
  "team-design",
21
22
  "agents",
22
23
  ];
23
- const repoUrl = (name) => `git@github.com:InstallAgent/${name}.git`;
24
+ export const repoUrl = (name, protocol = "https") => protocol === "ssh"
25
+ ? `git@github.com:InstallAgent/${name}.git`
26
+ : `https://github.com/InstallAgent/${name}.git`;
24
27
  /**
25
28
  * `ia wizard` — clone the entire perfected technician environment: the six
26
29
  * team repos, an otherwise-empty clients/ with client-template, and the root
@@ -42,6 +45,8 @@ export async function wizardWorkspace(options) {
42
45
  const update = options.update ?? false;
43
46
  const clone = options.clone ?? gitClone;
44
47
  const pull = options.pull ?? gitPullFfOnly;
48
+ const protocol = options.protocol ?? "https";
49
+ const platform = options.platform ?? detectPlatformInfo();
45
50
  const steps = [];
46
51
  await mkdir(dir, { recursive: true });
47
52
  const repoStep = async (name, url, dest) => {
@@ -76,7 +81,7 @@ export async function wizardWorkspace(options) {
76
81
  }
77
82
  };
78
83
  for (const name of WIZARD_REPO_NAMES) {
79
- await repoStep(`${name}/`, repoUrl(name), join(dir, name));
84
+ await repoStep(`${name}/`, repoUrl(name, protocol), join(dir, name));
80
85
  }
81
86
  const clientsDir = join(dir, "clients");
82
87
  if (existsSync(clientsDir)) {
@@ -90,53 +95,27 @@ export async function wizardWorkspace(options) {
90
95
  detail: "empty clients/ dir — clone or create only the client repos you work on",
91
96
  });
92
97
  }
93
- await repoStep("clients/client-template/", repoUrl("client-template"), join(clientsDir, "client-template"));
94
- // Root docs + skills. The cloned team-tools' template dir is fresher than
95
- // this package's bundled copy (it was just cloned/pulled above), so prefer it.
96
- const cloneTemplateDir = join(dir, "team-tools", "packages", "sdk", "templates", "workspace-root");
97
- const templateSource = existsSync(cloneTemplateDir)
98
- ? "workspace-clone"
99
- : "bundled";
100
- const templateDir = templateSource === "workspace-clone" ? cloneTemplateDir : workspaceRootTemplateDir();
101
- const docs = { created: [], updated: [], kept: [] };
102
- for (const rel of await listFiles(templateDir)) {
103
- const source = join(templateDir, rel);
104
- const target = join(dir, rel);
105
- if (!existsSync(target)) {
106
- await mkdir(dirname(target), { recursive: true });
107
- await copyFile(source, target);
108
- docs.created.push(rel);
109
- continue;
110
- }
111
- if (update && !(await readFile(source)).equals(await readFile(target))) {
112
- await copyFile(source, target);
113
- docs.updated.push(rel);
114
- }
115
- else {
116
- docs.kept.push(rel);
117
- }
118
- }
98
+ await repoStep("clients/client-template/", repoUrl("client-template", protocol), join(clientsDir, "client-template"));
99
+ // Root docs + skills — shared with `ia sync --docs` (see workspace-docs.ts).
100
+ const refreshed = await refreshWorkspaceDocs(dir, { overwrite: update });
101
+ const templateSource = refreshed.templateSource;
102
+ const docs = {
103
+ created: refreshed.created,
104
+ updated: refreshed.updated,
105
+ kept: refreshed.kept,
106
+ };
119
107
  // Root .env: one env file for the whole workspace. `.env.example` (names
120
108
  // only) tracks the template like the docs above; `.env` itself holds the
121
109
  // technician's secrets — created once from the example, NEVER overwritten,
122
110
  // not even in update mode.
123
- const envExampleInClone = join(cloneTemplateDir, "..", "env.example");
124
- const envExampleSource = existsSync(envExampleInClone)
125
- ? envExampleInClone
126
- : envExampleTemplatePath();
127
- const envExampleTarget = join(dir, ".env.example");
128
- if (!existsSync(envExampleTarget)) {
129
- await copyFile(envExampleSource, envExampleTarget);
130
- steps.push({ name: ".env.example", status: "created", detail: "var layout, no values" });
131
- }
132
- else if (update &&
133
- !(await readFile(envExampleSource)).equals(await readFile(envExampleTarget))) {
134
- await copyFile(envExampleSource, envExampleTarget);
135
- steps.push({ name: ".env.example", status: "updated", detail: "refreshed from template" });
136
- }
137
- else {
138
- steps.push({ name: ".env.example", status: "skipped", detail: "up to date" });
139
- }
111
+ const envExample = await refreshEnvExample(dir, { overwrite: update });
112
+ steps.push(envExample === "created"
113
+ ? { name: ".env.example", status: "created", detail: "var layout, no values" }
114
+ : envExample === "updated"
115
+ ? { name: ".env.example", status: "updated", detail: "refreshed from template" }
116
+ : { name: ".env.example", status: "skipped", detail: "up to date" });
117
+ // `.env` holds real secrets: created once from the example, then never
118
+ // touched again by any command, update mode included.
140
119
  const envTarget = join(dir, ".env");
141
120
  if (existsSync(envTarget)) {
142
121
  steps.push({
@@ -146,7 +125,7 @@ export async function wizardWorkspace(options) {
146
125
  });
147
126
  }
148
127
  else {
149
- await copyFile(envExampleSource, envTarget);
128
+ await copyFile(join(dir, ".env.example"), envTarget);
150
129
  steps.push({
151
130
  name: ".env",
152
131
  status: "created",
@@ -180,7 +159,7 @@ export async function wizardWorkspace(options) {
180
159
  templateSource,
181
160
  mcpRecommendations: MCP_RECOMMENDATIONS,
182
161
  ...(checkup ? { doctor: checkup } : {}),
183
- nextSteps: buildNextSteps(dir, checkup),
162
+ nextSteps: buildNextSteps(dir, platform, checkup),
184
163
  };
185
164
  }
186
165
  /**
@@ -188,20 +167,20 @@ export async function wizardWorkspace(options) {
188
167
  * chained doctor findings when available (steps already green are dropped);
189
168
  * the full static list otherwise.
190
169
  */
191
- function buildNextSteps(dir, checkup) {
170
+ function buildNextSteps(dir, platform, checkup) {
192
171
  const notOk = (id) => !checkup || checkup.checks.some((c) => c.id === id && c.status !== "ok");
193
172
  const steps = [];
194
173
  if (notOk("tools/gh")) {
195
174
  steps.push("run `gh auth login` — one-time GitHub OAuth; no PAT, no approval wait");
196
175
  }
197
176
  if (notOk("tools/op")) {
198
- steps.push("install the 1Password CLI if needed (`brew install 1password-cli`), then `op signin`");
177
+ steps.push(opInstallFix(platform));
199
178
  }
200
- const vaultVarMissing = ENV_VARS.some((spec) => spec.doctor && spec.source === "vault" && notOk(`env/${spec.name}`));
179
+ const vaultVarMissing = TECH_ENV_VARS.some((spec) => spec.doctor && spec.source === "vault" && notOk(`env/${spec.name}`));
201
180
  if (vaultVarMissing) {
202
181
  steps.push(`run \`ia env fill -w ${dir}\` — fills the shared secrets from 1Password`);
203
182
  }
204
- for (const spec of ENV_VARS) {
183
+ for (const spec of TECH_ENV_VARS) {
205
184
  if (spec.doctor && spec.source === "personal" && spec.tier === "required") {
206
185
  if (notOk(`env/${spec.name}`)) {
207
186
  steps.push(`set ${spec.name} in ${join(dir, ".env")} — ${spec.howToGet}`);
@@ -0,0 +1,44 @@
1
+ /**
2
+ * The workspace root's orientation docs and skills/ — laid down by
3
+ * `ia wizard` and refreshed by `ia sync --docs`. Extracted so both share one
4
+ * implementation: two copies of "which template wins" would drift, and the
5
+ * whole point of the root docs is that every technician has the same ones.
6
+ */
7
+ export interface WorkspaceDocsResult {
8
+ created: string[];
9
+ updated: string[];
10
+ kept: string[];
11
+ /** Where the files came from — a cloned team-tools beats the bundled copy. */
12
+ templateSource: "workspace-clone" | "bundled";
13
+ }
14
+ /**
15
+ * Prefer the template dir inside the workspace's own team-tools clone. It was
16
+ * just pulled, so it carries the workspace owner's latest root files without
17
+ * waiting for an npm release of the CLI. Falls back to the copy bundled with
18
+ * this package.
19
+ */
20
+ export declare function resolveTemplateDir(workspaceDir: string): {
21
+ dir: string;
22
+ source: WorkspaceDocsResult["templateSource"];
23
+ };
24
+ /**
25
+ * Copy the root docs + skills into the workspace. Absent files are always
26
+ * created. An existing file is overwritten only when `overwrite` is set AND
27
+ * its bytes differ from the template — so an untouched file is reported
28
+ * `kept`, and a technician's edit is only ever replaced on an explicit
29
+ * refresh, never on a plain additive run.
30
+ */
31
+ export declare function refreshWorkspaceDocs(workspaceDir: string, options: {
32
+ overwrite: boolean;
33
+ }): Promise<WorkspaceDocsResult>;
34
+ export type EnvExampleStatus = "created" | "updated" | "unchanged";
35
+ /**
36
+ * The root `.env.example` — the var LAYOUT, never values. Refreshed alongside
37
+ * the docs so a technician whose .env predates a new var can see the line to
38
+ * add. `.env` itself is deliberately not handled here or anywhere near a
39
+ * refresh path: it holds real secrets and is written exactly once, by
40
+ * `ia wizard`, then never overwritten by anything.
41
+ */
42
+ export declare function refreshEnvExample(workspaceDir: string, options: {
43
+ overwrite: boolean;
44
+ }): Promise<EnvExampleStatus>;
@@ -0,0 +1,73 @@
1
+ import { existsSync } from "node:fs";
2
+ import { copyFile, mkdir, readFile } from "node:fs/promises";
3
+ import { dirname, join } from "node:path";
4
+ import { listFiles } from "./fs-utils.js";
5
+ import { envExampleTemplatePath, workspaceRootTemplateDir } from "./templates.js";
6
+ /**
7
+ * Prefer the template dir inside the workspace's own team-tools clone. It was
8
+ * just pulled, so it carries the workspace owner's latest root files without
9
+ * waiting for an npm release of the CLI. Falls back to the copy bundled with
10
+ * this package.
11
+ */
12
+ export function resolveTemplateDir(workspaceDir) {
13
+ const inClone = join(workspaceDir, "team-tools", "packages", "sdk", "templates", "workspace-root");
14
+ return existsSync(inClone)
15
+ ? { dir: inClone, source: "workspace-clone" }
16
+ : { dir: workspaceRootTemplateDir(), source: "bundled" };
17
+ }
18
+ /**
19
+ * Copy the root docs + skills into the workspace. Absent files are always
20
+ * created. An existing file is overwritten only when `overwrite` is set AND
21
+ * its bytes differ from the template — so an untouched file is reported
22
+ * `kept`, and a technician's edit is only ever replaced on an explicit
23
+ * refresh, never on a plain additive run.
24
+ */
25
+ export async function refreshWorkspaceDocs(workspaceDir, options) {
26
+ const { dir: templateDir, source } = resolveTemplateDir(workspaceDir);
27
+ const result = {
28
+ created: [],
29
+ updated: [],
30
+ kept: [],
31
+ templateSource: source,
32
+ };
33
+ for (const rel of await listFiles(templateDir)) {
34
+ const from = join(templateDir, rel);
35
+ const to = join(workspaceDir, rel);
36
+ if (!existsSync(to)) {
37
+ await mkdir(dirname(to), { recursive: true });
38
+ await copyFile(from, to);
39
+ result.created.push(rel);
40
+ continue;
41
+ }
42
+ if (options.overwrite && !(await readFile(from)).equals(await readFile(to))) {
43
+ await copyFile(from, to);
44
+ result.updated.push(rel);
45
+ }
46
+ else {
47
+ result.kept.push(rel);
48
+ }
49
+ }
50
+ return result;
51
+ }
52
+ /**
53
+ * The root `.env.example` — the var LAYOUT, never values. Refreshed alongside
54
+ * the docs so a technician whose .env predates a new var can see the line to
55
+ * add. `.env` itself is deliberately not handled here or anywhere near a
56
+ * refresh path: it holds real secrets and is written exactly once, by
57
+ * `ia wizard`, then never overwritten by anything.
58
+ */
59
+ export async function refreshEnvExample(workspaceDir, options) {
60
+ const inClone = join(workspaceDir, "team-tools", "packages", "sdk", "templates", "env.example");
61
+ const from = existsSync(inClone) ? inClone : envExampleTemplatePath();
62
+ const to = join(workspaceDir, ".env.example");
63
+ if (!existsSync(to)) {
64
+ await mkdir(dirname(to), { recursive: true });
65
+ await copyFile(from, to);
66
+ return "created";
67
+ }
68
+ if (options.overwrite && !(await readFile(from)).equals(await readFile(to))) {
69
+ await copyFile(from, to);
70
+ return "updated";
71
+ }
72
+ return "unchanged";
73
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@installagent/sdk",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Install Agent's shared SDK for internal team operations (client repos, n8n workflows, docs search, and more).",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -24,7 +24,7 @@
24
24
  },
25
25
  "scripts": {
26
26
  "build": "tsc -p tsconfig.json",
27
- "type-check": "tsc -p tsconfig.json --noEmit",
27
+ "type-check": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
28
28
  "test": "vitest run"
29
29
  }
30
30
  }
@@ -2,7 +2,8 @@
2
2
  #
3
3
  # - `ia` commands load this automatically (vars already set in your shell win).
4
4
  # - Shell scripts in any repo can use it too: set -a; source ../.env; set +a
5
- # - Shared values come from 1Password: run `ia env fill` (needs `op signin`).
5
+ # - Shared values come from 1Password: run `ia env fill` (needs the op CLI
6
+ # authenticated via the 1Password app's CLI integration — `ia doctor` checks it).
6
7
  # Personal values (marked below) you fill by hand. NEVER commit this file
7
8
  # anywhere — the root is not a git repo, and no repo may ever contain it.
8
9
  # Only env.example (this placeholder layout, no values) is shareable.
@@ -16,8 +17,11 @@ LINEAR_API_TOKEN=
16
17
  # your personal Linear API key — Linear → Settings → Security & access
17
18
  LINEAR_CLIENT_TEAM_ID=
18
19
  # the fixed Linear client team's ID — filled by `ia env fill`
20
+ IA_DOCS_SEARCH_TOKEN=
21
+ # shared docs-search API bearer (never expires; preferred over the cookie below) — `ia env fill`
19
22
  IA_DOCS_SESSION=
20
- # team.installagent.com __Secure-authjs.session-token cookie (expires periodically)
23
+ # team.installagent.com __Secure-authjs.session-token cookie (expires periodically);
24
+ # only needed when IA_DOCS_SEARCH_TOKEN is unset
21
25
  IA_PORTAL_ADMIN_SECRET=
22
26
  # portal.installagent.com admin API bearer — filled by `ia env fill`
23
27
  AIRTABLE_API_TOKEN=
@@ -33,28 +37,34 @@ N8N_API_KEY=
33
37
  GEMINI_API_KEY=
34
38
 
35
39
  # ── shared infra (n8n workflows, team-infra scripts) ─────────────────────────
36
- AIRTABLE_BASE_ID=
37
- AIRTABLE_CLIENTS_TABLE_ID=
38
- N8N_WEBHOOK_URL=
39
- N8N_WEBHOOK_SECRET=
40
- AGENT_INGEST_SECRET=
41
- CRON_SECRET=
40
+ # Commented out — granted case-by-case from the team-admin vault. If you
41
+ # have the grant, uncomment the line you need, then run `ia env fill --admin`.
42
+ # AIRTABLE_BASE_ID=
43
+ # AIRTABLE_CLIENTS_TABLE_ID=
44
+ # N8N_WEBHOOK_URL=
45
+ # N8N_WEBHOOK_SECRET=
46
+ # AGENT_INGEST_SECRET=
47
+ # CRON_SECRET=
42
48
 
43
49
  # ── portal / team-web local dev (prod values live in Vercel, never here) ─────
44
- DATABASE_URL=
45
- DATABASE_USER=
46
- DATABASE_PASS=
47
- AUTH_SECRET=
48
- AUTH_GOOGLE_ID=
49
- AUTH_GOOGLE_SECRET=
50
- PORTAL_ADMIN_EMAILS=
50
+ # Commented out — granted case-by-case from the team-admin vault. If you
51
+ # have the grant, uncomment the line you need, then run `ia env fill --admin`.
52
+ # DATABASE_URL=
53
+ # DATABASE_USER=
54
+ # DATABASE_PASS=
55
+ # AUTH_SECRET=
56
+ # AUTH_GOOGLE_ID=
57
+ # AUTH_GOOGLE_SECRET=
58
+ # PORTAL_ADMIN_EMAILS=
51
59
 
52
60
  # ── payments (Stripe / Plaid) ────────────────────────────────────────────────
53
- STRIPE_SECRET_KEY=
54
- STRIPE_WEBHOOK_SECRET=
55
- STRIPE_WEBHOOK_URL=
56
- STRIPE_BASE_URL=
57
- PLAID_CLIENT_ID=
58
- PLAID_SECRET=
59
- PLAID_ACCESS_TOKEN=
60
- PLAID_BASE_URL=
61
+ # Commented out — granted case-by-case from the team-admin vault. If you
62
+ # have the grant, uncomment the line you need, then run `ia env fill --admin`.
63
+ # STRIPE_SECRET_KEY=
64
+ # STRIPE_WEBHOOK_SECRET=
65
+ # STRIPE_WEBHOOK_URL=
66
+ # STRIPE_BASE_URL=
67
+ # PLAID_CLIENT_ID=
68
+ # PLAID_SECRET=
69
+ # PLAID_ACCESS_TOKEN=
70
+ # PLAID_BASE_URL=
@@ -43,7 +43,7 @@ installagent/
43
43
  | Task | Go to | Read first |
44
44
  |---|---|---|
45
45
  | Understand who a client/lead is, prep a call | `team-clients/clients/<slug>/` | `team-clients/AGENT.md` |
46
- | Prep a tech discovery / scoping call (call sheet, proposals ready) | `clients/client-<slug>/` via the `tech-call-prep` skill | team hub → Techs → Discovery call |
46
+ | Prep a tech discovery / scoping call (call agenda, proposals ready) | `clients/client-<slug>/` via the `tech-call-prep` skill | team hub → Techs → Discovery call |
47
47
  | Build/edit anything *for* a client (spec, workflow, diagram, PDF, site, agent) | `clients/client-<slug>/` | that repo's `CADENCE.md` (how to ship it) + `AGENT.md` + `CLIENT.md` |
48
48
  | Ship a change into a client repo without causing drift (feature, fix, scope change) | `clients/client-<slug>/CADENCE.md` | it *is* the read — five stages + the surface matrix |
49
49
  | Answer "what did we ship for X / does it work?" | `clients/client-<slug>/docs/00-delivery-log.md` + `evidence/` | same |
@@ -150,7 +150,7 @@ repo; don't invent a per-client process.
150
150
  client-<slug>/
151
151
  ├── CADENCE.md # how work ships: five stages + the anti-drift surface matrix
152
152
  ├── CLIENT.md # context manifest → Airtable record, Drive folder, Linear project, registry profile, n8n tag, 1Password vault
153
- ├── onboarding.html # tabbed open-me-first page: Architecture / Client / Proposals / Public
153
+ ├── onboarding.html # open-me-first page, six sections: Overview / Architecture / Client / Workflows / Proposals / Public
154
154
  ├── docs/ # engagement-spec output + 00-delivery-log.md + diagrams as self-contained HTML
155
155
  ├── workflows/ # n8n JSON exports (credential IDs scrubbed)
156
156
  ├── data/ # client-sent raw data — gitignored (only its README is tracked)
@@ -166,14 +166,16 @@ no `legal/` (signed documents live in the client's Google Drive folder), no
166
166
  files (Airtable owns deal status). No `diagrams/` or `client-facing/` since
167
167
  2026-07: diagrams are HTML files in `docs/`; branded deliverables ship via
168
168
  the client's Drive folder, and the client-presentable view is the Public
169
- tab of `onboarding.html`.
169
+ section of `onboarding.html`.
170
170
 
171
171
  Skills that produce the deliverables: **`client-deliverables`** (orchestrator),
172
172
  **`engagement-spec`** (internal docs), **`client-facing-docs`** (branded PDFs),
173
173
  **`client-workflow-diagram`** (diagrams), **`installagent-brand-kit`** (brand —
174
- official logo + brand red `#9b0506`), **`contract-tech-agnostic`** (contracts
174
+ official logo + brand red `#d11a1a` on white, signal red `#ff2d2d` for
175
+ attention; also the client-deck builder and template),
176
+ **`contract-tech-agnostic`** (contracts
175
177
  by function and outcome, never tech), **`tech-call-prep`** (per-client call
176
- sheet before any client call), **`client-llm-setup`** (the client's own Claude
178
+ agenda before any client call), **`client-llm-setup`** (the client's own Claude
177
179
  workspace guide). All live in `skills/`. The engagement playbook the skills
178
180
  plug into — lifecycle, discovery-call script, LLM-setup runbook — lives on the
179
181
  team hub (`team-web/apps/docs` → Techs).
@@ -16,14 +16,25 @@ One command clones the whole environment (all team repos, an empty
16
16
  `clients/` with `client-template`, these root docs, and `skills/`):
17
17
 
18
18
  ```bash
19
- ia wizard ~/installagent # first-time setup (needs GitHub SSH access)
20
- ia wizard ~/installagent --update # later: pull every repo + refresh root docs/skills
19
+ ia wizard ~/installagent # first-time setup
20
+ ia sync ~/installagent # later: pull every repo, client repos included
21
+ ia sync ~/installagent --docs # ...and refresh root docs/skills/.env.example
21
22
  ```
22
23
 
23
- The `ia` CLI lives in `team-tools/` — for the very first run, clone that repo
24
- alone, `pnpm install && pnpm -r build`, and run `node apps/cli/dist/index.js
25
- wizard …` (or link it). `--update` is how everyone stays on the same
26
- environment: fast-forward-only pulls, root docs refreshed only where drifted.
24
+ `ia wizard` clones over **HTTPS**, so `gh auth login` (step 1 below) is all the
25
+ GitHub access you need — no SSH key to generate, no agent to configure. Pass
26
+ `--ssh` if you prefer SSH URLs.
27
+
28
+ Use `ia sync` day to day, not `ia wizard --update`: sync also pulls your
29
+ `clients/client-<slug>` repos, which the wizard never touched, and it leaves
30
+ your root docs alone unless you ask. Every pull is fast-forward only, so a repo
31
+ with local commits fails loudly instead of being merged over.
32
+
33
+ The `ia` CLI ships as a public npm package —
34
+ [`@installagent/cli`](https://www.npmjs.com/package/@installagent/cli):
35
+ `npm install -g @installagent/cli`, then `ia --version` to confirm.
36
+ `--update` is how everyone stays on the same environment: fast-forward-only
37
+ pulls, root docs refreshed only where drifted.
27
38
 
28
39
  The wizard ends with a **numbered next-steps list** — do those in order and
29
40
  you're set up. They boil down to:
@@ -31,15 +42,61 @@ you're set up. They boil down to:
31
42
  1. `gh auth login` — GitHub auth via one-time OAuth in the browser.
32
43
  **No personal access token, no admin-approval wait.** Every `ia` command
33
44
  that talks to GitHub uses the gh CLI's token automatically.
34
- 2. `op signin` — the 1Password CLI (`brew install 1password-cli` first if
35
- needed). Shared team secrets live in the **team-techs** vault.
45
+ 2. **1Password CLI** — `brew install 1password-cli` on macOS,
46
+ `winget install 1password-cli` on Windows. Before you sign in, open the
47
+ **1Password 8 desktop app → Settings → Developer** and tick
48
+ **"Integrate with 1Password CLI"** (Settings → Security → Touch ID or
49
+ Windows Hello unlock makes it seamless). You need **version 8** — the Mac
50
+ App Store still ships v7, which has no Developer tab. Then `op whoami`
51
+ should work in any terminal.
52
+ Do not skip this: `eval $(op signin)` puts the session in one shell only,
53
+ so `ia env fill` then reports `not-in-vault` in every other window — which
54
+ looks exactly like a missing vault grant.
55
+ **On Windows, run anything that touches `op` from PowerShell.** 1Password
56
+ supports PowerShell only, so the desktop-app integration cannot
57
+ authenticate `op` from Git Bash at all — see the Windows section below.
58
+ Shared team secrets live in the **team-techs** vault — 8 items,
59
+ and that one grant is all a technician needs (`AIRTABLE_API_TOKEN`,
60
+ `GOOGLE_SERVICE_ACCOUNT_KEY`, `N8N_API_URL`, `N8N_API_KEY`,
61
+ `LINEAR_CLIENT_TEAM_ID`, `FATHOM_API_KEY`, `IA_PORTAL_ADMIN_SECRET`,
62
+ `GEMINI_API_KEY`). If you think you need more, you probably don't — ask
63
+ before requesting `team-admin`.
36
64
  3. `ia env fill` — fills the empty vars in the root `.env` straight from
37
65
  1Password. No copy-pasting secrets, nothing goes through a chat window.
66
+ It only touches your own technician var set. The infra, portal and
67
+ payments vars ship commented out in `.env.example` and are reported as a
68
+ count, not by name — if you actually need one, ask, then
69
+ `ia env fill --admin`.
38
70
  4. Two personal values you set by hand in `.env`: your own
39
71
  `LINEAR_API_TOKEN` (Linear → Settings → Security & access) and
40
72
  `IA_DOCS_SESSION` (session cookie from a logged-in team.installagent.com
41
73
  tab).
42
74
  5. `ia doctor -w ~/installagent` — repeat until everything required is green.
75
+ It prints only what still needs doing; `ia doctor --all` shows every check,
76
+ passing ones included.
77
+
78
+ ## On Windows
79
+
80
+ Everything works on native Windows, with three things worth knowing up front.
81
+ Run your terminal as **PowerShell** (Windows Terminal's default profile is
82
+ fine) rather than Git Bash.
83
+
84
+ 1. **`op` does not work in Git Bash.** 1Password documents PowerShell as its
85
+ only supported Windows shell, so the desktop-app integration cannot
86
+ authenticate the CLI from an MSYS shell. `op` will look installed and still
87
+ fail. Run `ia env fill` (and anything else touching `op`) in PowerShell.
88
+ `ia doctor` detects Git Bash and says so instead of printing macOS advice.
89
+ 2. **Prerequisites:** Node 20+, `pnpm`, `git`, and the GitHub CLI
90
+ (`winget install GitHub.cli`). `npm install -g @installagent/cli` gets you
91
+ `ia` itself.
92
+ 3. **git hooks are per-clone.** Inside each client repo you clone, run
93
+ `npx lefthook install` once — client repos carry no `package.json`, so
94
+ there is no local lefthook to call. Without it the repo-lint pre-commit
95
+ gate silently never runs. `ia doctor` warns when a cloned client repo is
96
+ missing it.
97
+
98
+ If something prints advice that is wrong for Windows, that is a bug in the
99
+ CLI — say so, don't work around it quietly.
43
100
 
44
101
  The root `.env` is the ONE env file for the whole workspace: every `ia`
45
102
  command auto-loads it, and shell scripts can `set -a; source .env; set +a`.