@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.
- package/dist/agent-templates.d.ts +36 -2
- package/dist/agent-templates.js +173 -3
- package/dist/client-linear-create.d.ts +26 -0
- package/dist/client-linear-create.js +46 -0
- package/dist/client-linear.d.ts +28 -9
- package/dist/client-linear.js +36 -14
- package/dist/docs-search.d.ts +19 -6
- package/dist/docs-search.js +32 -11
- package/dist/doctor.d.ts +9 -0
- package/dist/doctor.js +126 -23
- package/dist/env-fill.d.ts +13 -0
- package/dist/env-fill.js +34 -9
- package/dist/env-push.d.ts +3 -0
- package/dist/env-push.js +11 -6
- package/dist/env-registry.d.ts +25 -0
- package/dist/env-registry.js +69 -7
- package/dist/exec.js +15 -2
- package/dist/index.d.ts +14 -6
- package/dist/index.js +14 -6
- package/dist/linear-project.d.ts +2 -2
- package/dist/linear-project.js +2 -2
- package/dist/log.d.ts +28 -0
- package/dist/log.js +73 -0
- package/dist/n8n-executions.d.ts +85 -0
- package/dist/n8n-executions.js +259 -0
- package/dist/op-cli.d.ts +29 -0
- package/dist/op-cli.js +52 -0
- package/dist/platform.d.ts +35 -0
- package/dist/platform.js +39 -0
- package/dist/portal-admin.d.ts +40 -0
- package/dist/portal-admin.js +30 -0
- package/dist/standup.d.ts +88 -0
- package/dist/standup.js +235 -0
- package/dist/sync-repos.d.ts +47 -0
- package/dist/sync-repos.js +80 -0
- package/dist/template-sync.d.ts +10 -0
- package/dist/template-sync.js +11 -0
- package/dist/wizard.d.ts +15 -0
- package/dist/wizard.js +35 -56
- package/dist/workspace-docs.d.ts +44 -0
- package/dist/workspace-docs.js +73 -0
- package/package.json +2 -2
- package/templates/env.example +33 -23
- package/templates/workspace-root/AGENT.md +7 -5
- package/templates/workspace-root/ONBOARDING.md +65 -8
- package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +102 -0
- package/templates/workspace-root/skills/CLAUDE.md +24 -6
- package/templates/workspace-root/skills/README.md +156 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
- package/templates/workspace-root/skills/client-latest/SKILL.md +301 -0
- package/templates/workspace-root/skills/client-latest/catchup.command.md +17 -0
- package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +181 -0
- package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
- package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
- package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
- package/templates/workspace-root/skills/ia-cli/SKILL.md +19 -6
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
- package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
- package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
- package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
- package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
package/dist/template-sync.d.ts
CHANGED
|
@@ -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 {
|
package/dist/template-sync.js
CHANGED
|
@@ -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
|
|
3
|
-
import {
|
|
2
|
+
import { copyFile, mkdir } from "node:fs/promises";
|
|
3
|
+
import { join, resolve } from "node:path";
|
|
4
4
|
import { doctor } from "./doctor.js";
|
|
5
|
-
import {
|
|
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 {
|
|
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) =>
|
|
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
|
|
95
|
-
|
|
96
|
-
const
|
|
97
|
-
const
|
|
98
|
-
|
|
99
|
-
:
|
|
100
|
-
|
|
101
|
-
|
|
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
|
|
124
|
-
|
|
125
|
-
?
|
|
126
|
-
:
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
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(
|
|
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(
|
|
177
|
+
steps.push(opInstallFix(platform));
|
|
199
178
|
}
|
|
200
|
-
const vaultVarMissing =
|
|
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
|
|
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.
|
|
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
|
}
|
package/templates/env.example
CHANGED
|
@@ -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
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
|
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 #
|
|
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
|
-
|
|
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 `#
|
|
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
|
-
|
|
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
|
|
20
|
-
ia
|
|
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
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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.
|
|
35
|
-
|
|
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`.
|