@installagent/sdk 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/dist/agent-mirror.d.ts +69 -0
  2. package/dist/agent-mirror.js +275 -0
  3. package/dist/agent-templates.d.ts +36 -2
  4. package/dist/agent-templates.js +173 -3
  5. package/dist/claude-hours.d.ts +118 -0
  6. package/dist/claude-hours.js +523 -0
  7. package/dist/client-drive.d.ts +3 -0
  8. package/dist/client-drive.js +2 -2
  9. package/dist/client-linear-create.d.ts +26 -0
  10. package/dist/client-linear-create.js +46 -0
  11. package/dist/client-linear.d.ts +28 -9
  12. package/dist/client-linear.js +36 -14
  13. package/dist/docs-search.d.ts +19 -6
  14. package/dist/docs-search.js +32 -11
  15. package/dist/doctor.d.ts +9 -0
  16. package/dist/doctor.js +126 -23
  17. package/dist/env-fill.d.ts +13 -0
  18. package/dist/env-fill.js +55 -13
  19. package/dist/env-push.d.ts +3 -0
  20. package/dist/env-push.js +11 -6
  21. package/dist/env-registry.d.ts +29 -0
  22. package/dist/env-registry.js +123 -9
  23. package/dist/exec.js +15 -2
  24. package/dist/git.d.ts +31 -0
  25. package/dist/git.js +59 -0
  26. package/dist/google-service-account.d.ts +20 -0
  27. package/dist/google-service-account.js +49 -0
  28. package/dist/hours-estimate.d.ts +43 -0
  29. package/dist/hours-estimate.js +159 -0
  30. package/dist/hours-export-schedule.d.ts +35 -0
  31. package/dist/hours-export-schedule.js +188 -0
  32. package/dist/hours-ledger.d.ts +129 -0
  33. package/dist/hours-ledger.js +882 -0
  34. package/dist/index.d.ts +25 -6
  35. package/dist/index.js +25 -6
  36. package/dist/linear-project.d.ts +2 -2
  37. package/dist/linear-project.js +2 -2
  38. package/dist/log.d.ts +28 -0
  39. package/dist/log.js +73 -0
  40. package/dist/n8n-executions.d.ts +85 -0
  41. package/dist/n8n-executions.js +259 -0
  42. package/dist/op-cli.d.ts +29 -0
  43. package/dist/op-cli.js +52 -0
  44. package/dist/platform.d.ts +35 -0
  45. package/dist/platform.js +39 -0
  46. package/dist/portal-admin.d.ts +108 -0
  47. package/dist/portal-admin.js +94 -1
  48. package/dist/standup.d.ts +88 -0
  49. package/dist/standup.js +235 -0
  50. package/dist/sync-repos.d.ts +54 -0
  51. package/dist/sync-repos.js +89 -0
  52. package/dist/template-sync.d.ts +11 -0
  53. package/dist/template-sync.js +16 -0
  54. package/dist/triage-backfill.d.ts +37 -0
  55. package/dist/triage-backfill.js +211 -0
  56. package/dist/triage-enable.d.ts +90 -0
  57. package/dist/triage-enable.js +428 -0
  58. package/dist/triage-gates.d.ts +252 -0
  59. package/dist/triage-gates.js +951 -0
  60. package/dist/wizard.d.ts +15 -0
  61. package/dist/wizard.js +35 -56
  62. package/dist/workspace-docs.d.ts +44 -0
  63. package/dist/workspace-docs.js +73 -0
  64. package/dist/workspace-push.d.ts +39 -0
  65. package/dist/workspace-push.js +78 -0
  66. package/dist/workspace-status.d.ts +37 -0
  67. package/dist/workspace-status.js +114 -0
  68. package/package.json +2 -2
  69. package/templates/env.example +37 -23
  70. package/templates/workspace-root/.claude/settings.json +12 -1
  71. package/templates/workspace-root/AGENT.md +7 -5
  72. package/templates/workspace-root/ONBOARDING.md +65 -8
  73. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +127 -0
  74. package/templates/workspace-root/skills/CLAUDE.md +29 -6
  75. package/templates/workspace-root/skills/README.md +171 -0
  76. package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
  77. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
  78. package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
  79. package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
  80. package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
  81. package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
  82. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
  83. package/templates/workspace-root/skills/client-latest/SKILL.md +343 -0
  84. package/templates/workspace-root/skills/client-latest/catchup.command.md +18 -0
  85. package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
  86. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +258 -0
  87. package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
  88. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
  89. package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
  90. package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
  91. package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
  92. package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
  93. package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
  94. package/templates/workspace-root/skills/ia-cli/SKILL.md +49 -7
  95. package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
  96. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
  97. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
  98. package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
  99. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
  100. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
  101. package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
  102. package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
  103. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
  104. package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
  105. package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
  106. package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
  107. package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
  108. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
  109. package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
  110. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
  111. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
  112. package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
  113. package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
  114. package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
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
+ }
@@ -0,0 +1,39 @@
1
+ import { type FetchFn, type PushFn, type StatusFn } from "./git.js";
2
+ /**
3
+ * `ia push` — push every repo in the workspace that is clean and strictly
4
+ * ahead of its upstream. Never commits anything and never force-pushes.
5
+ *
6
+ * Deliberately narrow: a repo only gets pushed here if its working tree has
7
+ * no uncommitted changes AND it has local commits not yet on origin AND it
8
+ * is not also behind (a genuine fast-forward push). Anything dirty,
9
+ * diverged, or without an upstream is left alone and reported — those need
10
+ * a human/agent to look at the diff and decide, which is exactly what
11
+ * `ia status` surfaces. This mirrors `ia sync`'s guardrail in the other
12
+ * direction: never do anything to a repo that isn't unambiguously safe.
13
+ */
14
+ export interface WorkspacePushOptions {
15
+ /** installagent/ workspace root. Defaults to the current dir. */
16
+ dir?: string;
17
+ /** Skip the `git fetch` before checking state. Default false. */
18
+ offline?: boolean;
19
+ /** Injectable for tests; defaults to real `git fetch --all --prune`. */
20
+ fetch?: FetchFn;
21
+ /** Injectable for tests; defaults to real `git status --porcelain=v2 --branch`. */
22
+ status?: StatusFn;
23
+ /** Injectable for tests; defaults to real `git push`. */
24
+ push?: PushFn;
25
+ }
26
+ export type WorkspacePushRepoStatus = "pushed" | "skipped" | "absent" | "failed";
27
+ export interface WorkspacePushRepoResult {
28
+ /** Path relative to the workspace root, e.g. `clients/client-mpnrealty`. */
29
+ name: string;
30
+ status: WorkspacePushRepoStatus;
31
+ detail: string;
32
+ }
33
+ export interface WorkspacePushResult {
34
+ ok: boolean;
35
+ dir: string;
36
+ repos: WorkspacePushRepoResult[];
37
+ nextSteps: string[];
38
+ }
39
+ export declare function pushWorkspaceRepos(options?: WorkspacePushOptions): Promise<WorkspacePushResult>;
@@ -0,0 +1,78 @@
1
+ import { existsSync } from "node:fs";
2
+ import { join, resolve } from "node:path";
3
+ import { gitFetchAll, gitPush, gitStatus, } from "./git.js";
4
+ import { workspaceRepoNames } from "./sync-repos.js";
5
+ export async function pushWorkspaceRepos(options = {}) {
6
+ const dir = resolve(options.dir ?? ".");
7
+ const fetch = options.fetch ?? gitFetchAll;
8
+ const status = options.status ?? gitStatus;
9
+ const push = options.push ?? gitPush;
10
+ const offline = options.offline ?? false;
11
+ const targets = workspaceRepoNames(dir);
12
+ const repos = [];
13
+ for (const rel of targets) {
14
+ const path = join(dir, ...rel.split("/"));
15
+ if (!existsSync(join(path, ".git"))) {
16
+ repos.push({ name: rel, status: "absent", detail: "not cloned on this machine" });
17
+ continue;
18
+ }
19
+ try {
20
+ if (!offline)
21
+ await fetch(path);
22
+ const info = await status(path);
23
+ if (info.dirty || info.untracked > 0) {
24
+ repos.push({
25
+ name: rel,
26
+ status: "skipped",
27
+ detail: "uncommitted changes — commit deliberately first (never auto-committed)",
28
+ });
29
+ continue;
30
+ }
31
+ if (!info.upstream) {
32
+ repos.push({ name: rel, status: "skipped", detail: "no tracking remote configured" });
33
+ continue;
34
+ }
35
+ if (info.behind > 0) {
36
+ repos.push({
37
+ name: rel,
38
+ status: "skipped",
39
+ detail: `${info.ahead} ahead / ${info.behind} behind — diverged or needs \`ia sync\` first, not a safe fast-forward push`,
40
+ });
41
+ continue;
42
+ }
43
+ if (info.ahead === 0) {
44
+ repos.push({ name: rel, status: "skipped", detail: "nothing to push" });
45
+ continue;
46
+ }
47
+ await push(path);
48
+ repos.push({
49
+ name: rel,
50
+ status: "pushed",
51
+ detail: `pushed ${info.ahead} commit(s)`,
52
+ });
53
+ }
54
+ catch (error) {
55
+ repos.push({
56
+ name: rel,
57
+ status: "failed",
58
+ detail: String(error instanceof Error ? error.message : error),
59
+ });
60
+ }
61
+ }
62
+ const failed = repos.filter((repo) => repo.status === "failed");
63
+ const skippedDirty = repos.filter((repo) => repo.status === "skipped" && repo.detail.startsWith("uncommitted"));
64
+ const nextSteps = [];
65
+ if (failed.length > 0) {
66
+ nextSteps.push(`${failed.length} repo(s) failed to push — see detail per repo (${failed
67
+ .map((repo) => repo.name)
68
+ .join(", ")})`);
69
+ }
70
+ if (skippedDirty.length > 0) {
71
+ nextSteps.push(`${skippedDirty.length} repo(s) have uncommitted changes to review and commit before ` +
72
+ `they can be pushed (${skippedDirty.map((repo) => repo.name).join(", ")}) — run \`ia status\` for the full picture`);
73
+ }
74
+ if (nextSteps.length === 0) {
75
+ nextSteps.push("nothing left to push");
76
+ }
77
+ return { ok: failed.length === 0, dir, repos, nextSteps };
78
+ }
@@ -0,0 +1,37 @@
1
+ import { type FetchFn, type RepoStatusInfo, type StatusFn } from "./git.js";
2
+ /**
3
+ * `ia status` — report git state across every repo in the workspace (team
4
+ * repos + every `clients/client-*` clone present on this machine) without
5
+ * touching anything but the remote-tracking refs.
6
+ *
7
+ * Read-only: fetches (never pulls, never merges), then reads
8
+ * `git status`. A repo never changes as a result of this command — it only
9
+ * tells you which repos need a human/agent decision (commit the dirty ones,
10
+ * run `ia push` for the clean-but-ahead ones, run `ia sync` for the
11
+ * behind ones).
12
+ */
13
+ export interface WorkspaceStatusOptions {
14
+ /** installagent/ workspace root. Defaults to the current dir. */
15
+ dir?: string;
16
+ /** Skip the `git fetch` and read local refs as last fetched. Default false. */
17
+ offline?: boolean;
18
+ /** Injectable for tests; defaults to real `git fetch --all --prune`. */
19
+ fetch?: FetchFn;
20
+ /** Injectable for tests; defaults to real `git status --porcelain=v2 --branch`. */
21
+ status?: StatusFn;
22
+ }
23
+ export type WorkspaceRepoState = "clean" | "dirty" | "ahead" | "behind" | "diverged" | "absent" | "no-upstream" | "failed";
24
+ export interface WorkspaceRepoStatus {
25
+ /** Path relative to the workspace root, e.g. `clients/client-mpnrealty`. */
26
+ name: string;
27
+ state: WorkspaceRepoState;
28
+ detail: string;
29
+ info?: RepoStatusInfo;
30
+ }
31
+ export interface WorkspaceStatusResult {
32
+ ok: boolean;
33
+ dir: string;
34
+ repos: WorkspaceRepoStatus[];
35
+ nextSteps: string[];
36
+ }
37
+ export declare function workspaceStatus(options?: WorkspaceStatusOptions): Promise<WorkspaceStatusResult>;
@@ -0,0 +1,114 @@
1
+ import { existsSync } from "node:fs";
2
+ import { join, resolve } from "node:path";
3
+ import { gitFetchAll, gitStatus } from "./git.js";
4
+ import { workspaceRepoNames } from "./sync-repos.js";
5
+ export async function workspaceStatus(options = {}) {
6
+ const dir = resolve(options.dir ?? ".");
7
+ const fetch = options.fetch ?? gitFetchAll;
8
+ const status = options.status ?? gitStatus;
9
+ const offline = options.offline ?? false;
10
+ const targets = workspaceRepoNames(dir);
11
+ const repos = [];
12
+ for (const rel of targets) {
13
+ const path = join(dir, ...rel.split("/"));
14
+ if (!existsSync(join(path, ".git"))) {
15
+ repos.push({
16
+ name: rel,
17
+ state: "absent",
18
+ detail: "not cloned on this machine",
19
+ });
20
+ continue;
21
+ }
22
+ try {
23
+ if (!offline)
24
+ await fetch(path);
25
+ const info = await status(path);
26
+ if (info.dirty || info.untracked > 0) {
27
+ repos.push({
28
+ name: rel,
29
+ state: "dirty",
30
+ detail: `${info.dirty ? "uncommitted changes" : ""}` +
31
+ `${info.dirty && info.untracked > 0 ? " + " : ""}` +
32
+ `${info.untracked > 0 ? `${info.untracked} untracked file(s)` : ""} — review before committing`,
33
+ info,
34
+ });
35
+ }
36
+ else if (!info.upstream) {
37
+ repos.push({
38
+ name: rel,
39
+ state: "no-upstream",
40
+ detail: "clean, but this branch has no tracking remote",
41
+ info,
42
+ });
43
+ }
44
+ else if (info.ahead > 0 && info.behind > 0) {
45
+ repos.push({
46
+ name: rel,
47
+ state: "diverged",
48
+ detail: `${info.ahead} ahead / ${info.behind} behind — needs manual resolution`,
49
+ info,
50
+ });
51
+ }
52
+ else if (info.ahead > 0) {
53
+ repos.push({
54
+ name: rel,
55
+ state: "ahead",
56
+ detail: `${info.ahead} commit(s) ready to push`,
57
+ info,
58
+ });
59
+ }
60
+ else if (info.behind > 0) {
61
+ repos.push({
62
+ name: rel,
63
+ state: "behind",
64
+ detail: `${info.behind} commit(s) behind — run \`ia sync\``,
65
+ info,
66
+ });
67
+ }
68
+ else {
69
+ repos.push({ name: rel, state: "clean", detail: "up to date", info });
70
+ }
71
+ }
72
+ catch (error) {
73
+ repos.push({
74
+ name: rel,
75
+ state: "failed",
76
+ detail: String(error instanceof Error ? error.message : error),
77
+ });
78
+ }
79
+ }
80
+ const dirtyRepos = repos.filter((r) => r.state === "dirty");
81
+ const aheadRepos = repos.filter((r) => r.state === "ahead");
82
+ const behindRepos = repos.filter((r) => r.state === "behind");
83
+ const divergedRepos = repos.filter((r) => r.state === "diverged");
84
+ const failedRepos = repos.filter((r) => r.state === "failed");
85
+ const nextSteps = [];
86
+ if (dirtyRepos.length > 0) {
87
+ nextSteps.push(`${dirtyRepos.length} repo(s) have uncommitted changes — review and commit each ` +
88
+ `deliberately (${dirtyRepos.map((r) => r.name).join(", ")}); this command never commits for you`);
89
+ }
90
+ if (aheadRepos.length > 0) {
91
+ nextSteps.push(`${aheadRepos.length} repo(s) have unpushed commits — run \`ia push\` to push them ` +
92
+ `(${aheadRepos.map((r) => r.name).join(", ")})`);
93
+ }
94
+ if (behindRepos.length > 0) {
95
+ nextSteps.push(`${behindRepos.length} repo(s) are behind origin — run \`ia sync\` to fast-forward ` +
96
+ `(${behindRepos.map((r) => r.name).join(", ")})`);
97
+ }
98
+ if (divergedRepos.length > 0) {
99
+ nextSteps.push(`${divergedRepos.length} repo(s) have diverged from origin and need manual resolution ` +
100
+ `(${divergedRepos.map((r) => r.name).join(", ")})`);
101
+ }
102
+ if (failedRepos.length > 0) {
103
+ nextSteps.push(`${failedRepos.length} repo(s) failed to check — see detail per repo ` +
104
+ `(${failedRepos.map((r) => r.name).join(", ")})`);
105
+ }
106
+ if (nextSteps.length === 0)
107
+ nextSteps.push("everything is clean and up to date");
108
+ return {
109
+ ok: failedRepos.length === 0 && divergedRepos.length === 0,
110
+ dir,
111
+ repos,
112
+ nextSteps,
113
+ };
114
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@installagent/sdk",
3
- "version": "0.1.0",
3
+ "version": "0.3.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
  }