@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
|
@@ -50,19 +50,33 @@ export interface SaveAgentTemplateResult {
|
|
|
50
50
|
nodeCount: number;
|
|
51
51
|
strippedCredentials: StrippedCredential[];
|
|
52
52
|
manifestCreated: boolean;
|
|
53
|
+
/** True when this save scaffolded sop.md (an existing one is never touched). */
|
|
54
|
+
sopCreated: boolean;
|
|
53
55
|
nextSteps: string[];
|
|
54
56
|
}
|
|
55
57
|
/**
|
|
56
58
|
* Bank a live n8n workflow: fetch by id, sanitize, write
|
|
57
|
-
* agents/<template>/workflow.json (+ template.md
|
|
58
|
-
* existing
|
|
59
|
+
* agents/<template>/workflow.json (+ template.md and sop.md scaffolds on first
|
|
60
|
+
* save; existing files are never overwritten).
|
|
59
61
|
*/
|
|
60
62
|
export declare function saveAgentTemplate(input: SaveAgentTemplateInput, opts?: SaveAgentTemplateOptions): Promise<SaveAgentTemplateResult>;
|
|
63
|
+
/** sop.md status: absent, still the unfilled save-time scaffold, or written. */
|
|
64
|
+
export type SopState = "missing" | "scaffold" | "filled";
|
|
61
65
|
export interface AgentTemplateInfo {
|
|
62
66
|
slug: string;
|
|
63
67
|
workflowName: string;
|
|
64
68
|
description: string | null;
|
|
65
69
|
hasManifest: boolean;
|
|
70
|
+
/**
|
|
71
|
+
* Whether the template ships a FILLED delivery SOP (sopState === "filled").
|
|
72
|
+
* False means the template is not deliverable yet — the SOP is missing or
|
|
73
|
+
* still the scaffold `save` wrote, so a technician has the machine but not
|
|
74
|
+
* the method (agents/AGENT.md § "The delivery SOP contract"), and callers
|
|
75
|
+
* surface it.
|
|
76
|
+
*/
|
|
77
|
+
hasSop: boolean;
|
|
78
|
+
/** Distinguishes a missing sop.md from a scaffold-only one (see hasSop). */
|
|
79
|
+
sopState: SopState;
|
|
66
80
|
}
|
|
67
81
|
export interface ListAgentTemplatesResult {
|
|
68
82
|
agentsDir: string;
|
|
@@ -70,6 +84,26 @@ export interface ListAgentTemplatesResult {
|
|
|
70
84
|
}
|
|
71
85
|
/** Catalog the bank: every agents/<slug>/ dir that holds a workflow.json. */
|
|
72
86
|
export declare function listAgentTemplates(opts?: AgentBankOptions): Promise<ListAgentTemplatesResult>;
|
|
87
|
+
export interface AgentTemplateMatch extends AgentTemplateInfo {
|
|
88
|
+
/** Term-centered slice of template.md; empty when the template has no manifest. */
|
|
89
|
+
snippet: string;
|
|
90
|
+
}
|
|
91
|
+
export interface SearchAgentTemplatesResult {
|
|
92
|
+
agentsDir: string;
|
|
93
|
+
query: string;
|
|
94
|
+
matches: AgentTemplateMatch[];
|
|
95
|
+
}
|
|
96
|
+
export interface SearchAgentTemplatesOptions extends AgentBankOptions {
|
|
97
|
+
/** Max matches returned (default 5). */
|
|
98
|
+
limit?: number;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* "Do we already have a workflow for X?" — rank banked templates against
|
|
102
|
+
* search terms, weighting slug + workflow-name hits over manifest-body hits
|
|
103
|
+
* (same scoring shape as docsSearch/clientBuild). Templates without a
|
|
104
|
+
* manifest still match on slug/name so `save` gaps stay findable.
|
|
105
|
+
*/
|
|
106
|
+
export declare function searchAgentTemplates(query: string, opts?: SearchAgentTemplatesOptions): Promise<SearchAgentTemplatesResult>;
|
|
73
107
|
export interface CreateFromTemplateInput {
|
|
74
108
|
template: string;
|
|
75
109
|
/** Where the JSON lands; defaults to the current working directory. */
|
package/dist/agent-templates.js
CHANGED
|
@@ -66,10 +66,68 @@ ${credLines}
|
|
|
66
66
|
(\`ia portal create-agent\`).
|
|
67
67
|
`;
|
|
68
68
|
}
|
|
69
|
+
/**
|
|
70
|
+
* Scaffold for the delivery SOP. Deliberately mostly questions: the SOP has to
|
|
71
|
+
* be written from the engagement the technician is actually in, and a
|
|
72
|
+
* confidently-worded template invites someone to leave the defaults in place.
|
|
73
|
+
* Contract: agents/AGENT.md § "The delivery SOP (`sop.md`) contract".
|
|
74
|
+
*/
|
|
75
|
+
function sopScaffold(template, workflowName) {
|
|
76
|
+
return `# ${template} — delivery SOP
|
|
77
|
+
|
|
78
|
+
> Banked from n8n workflow “${workflowName}”. **This is a scaffold, not an
|
|
79
|
+
> SOP.** Fill it from the engagement you are in — a rollout method written
|
|
80
|
+
> from memory is the thing this file exists to prevent. Contract:
|
|
81
|
+
> \`agents/AGENT.md\` § *The delivery SOP contract*. Worked example:
|
|
82
|
+
> \`agents/email-gmail-triage/sop.md\`.
|
|
83
|
+
|
|
84
|
+
One paragraph: how many stages, roughly how long, and what the client has at
|
|
85
|
+
the end.
|
|
86
|
+
|
|
87
|
+
## Preconditions
|
|
88
|
+
|
|
89
|
+
Credentials, access, client agreements, anything that must be pre-created.
|
|
90
|
+
A checklist. Anything missing here blocks stage 1.
|
|
91
|
+
|
|
92
|
+
- [ ] …
|
|
93
|
+
|
|
94
|
+
## Stages
|
|
95
|
+
|
|
96
|
+
Does this automation write to a system the client depends on? Then it needs at
|
|
97
|
+
least an observe-only first stage and a full stage. "Deploy it and watch" is
|
|
98
|
+
not a stage. Selection is **one config value**, never a disabled node.
|
|
99
|
+
|
|
100
|
+
| Stage | Config value | What runs | Deliberately off | Exit gate |
|
|
101
|
+
|---|---|---|---|---|
|
|
102
|
+
| 1. | | | | |
|
|
103
|
+
|
|
104
|
+
## Gate proof
|
|
105
|
+
|
|
106
|
+
Per promotion: the sample, the thresholds, the zero-tolerance list, and the
|
|
107
|
+
\`evidence/\` filename. **A gate with no number is not a gate.** Name the
|
|
108
|
+
errors that are never acceptable at any percentage.
|
|
109
|
+
|
|
110
|
+
## Client comms
|
|
111
|
+
|
|
112
|
+
What we tell the client at each promotion, and over which channel. Use the
|
|
113
|
+
\`house-voice\` skill. A silent promotion is how a client finds out by
|
|
114
|
+
noticing something changed.
|
|
115
|
+
|
|
116
|
+
## Steady state
|
|
117
|
+
|
|
118
|
+
After the last stage: who watches what, how often, and the one signal that
|
|
119
|
+
says it is still healthy.
|
|
120
|
+
|
|
121
|
+
## Rollback
|
|
122
|
+
|
|
123
|
+
How to undo each stage, and the pause switch. Every action that looks
|
|
124
|
+
irreversible should be recoverable by one search or one config value.
|
|
125
|
+
`;
|
|
126
|
+
}
|
|
69
127
|
/**
|
|
70
128
|
* Bank a live n8n workflow: fetch by id, sanitize, write
|
|
71
|
-
* agents/<template>/workflow.json (+ template.md
|
|
72
|
-
* existing
|
|
129
|
+
* agents/<template>/workflow.json (+ template.md and sop.md scaffolds on first
|
|
130
|
+
* save; existing files are never overwritten).
|
|
73
131
|
*/
|
|
74
132
|
export async function saveAgentTemplate(input, opts = {}) {
|
|
75
133
|
if (!SLUG_PATTERN.test(input.template)) {
|
|
@@ -105,6 +163,15 @@ export async function saveAgentTemplate(input, opts = {}) {
|
|
|
105
163
|
await writeFile(manifestPath, manifestScaffold(input.template, workflow.name, strippedCredentials));
|
|
106
164
|
manifestCreated = true;
|
|
107
165
|
}
|
|
166
|
+
const sopPath = join(dir, "sop.md");
|
|
167
|
+
let sopCreated = false;
|
|
168
|
+
try {
|
|
169
|
+
await readFile(sopPath, "utf8");
|
|
170
|
+
}
|
|
171
|
+
catch {
|
|
172
|
+
await writeFile(sopPath, sopScaffold(input.template, workflow.name));
|
|
173
|
+
sopCreated = true;
|
|
174
|
+
}
|
|
108
175
|
return {
|
|
109
176
|
template: input.template,
|
|
110
177
|
dir,
|
|
@@ -112,11 +179,15 @@ export async function saveAgentTemplate(input, opts = {}) {
|
|
|
112
179
|
nodeCount: workflow.nodes.length,
|
|
113
180
|
strippedCredentials,
|
|
114
181
|
manifestCreated,
|
|
182
|
+
sopCreated,
|
|
115
183
|
nextSteps: [
|
|
116
184
|
"Review workflow.json for client-specific parameter values (replace with REPLACE_ME_*).",
|
|
117
185
|
manifestCreated
|
|
118
186
|
? "Fill in the description paragraph in template.md."
|
|
119
187
|
: "template.md already existed — confirm it still matches the export.",
|
|
188
|
+
sopCreated
|
|
189
|
+
? "Fill in sop.md — stages, numbered gates, client comms, rollback. A template with an unfilled SOP is not deliverable (agents/AGENT.md)."
|
|
190
|
+
: "sop.md already existed — confirm its stages still match the export.",
|
|
120
191
|
"Commit the template in the agents/ repo.",
|
|
121
192
|
],
|
|
122
193
|
};
|
|
@@ -134,6 +205,17 @@ function manifestDescription(markdown) {
|
|
|
134
205
|
}
|
|
135
206
|
return null;
|
|
136
207
|
}
|
|
208
|
+
// sopScaffold() hard-wraps this sentence inside a blockquote, so detection
|
|
209
|
+
// strips markdown quote/emphasis markup and collapses whitespace first.
|
|
210
|
+
const SOP_SCAFFOLD_MARKER = "This is a scaffold, not an SOP";
|
|
211
|
+
// Fallback for a scaffold whose intro was trimmed: the stage table still
|
|
212
|
+
// holds the empty placeholder row sopScaffold() wrote.
|
|
213
|
+
const SOP_EMPTY_STAGE_ROW = /^\|\s*1\.\s*\|\s*\|\s*\|\s*\|\s*\|\s*$/m;
|
|
214
|
+
/** True when sop.md is still the unfilled scaffold from sopScaffold(). */
|
|
215
|
+
function isSopScaffold(markdown) {
|
|
216
|
+
const normalized = markdown.replace(/[>*_`]/g, "").replace(/\s+/g, " ");
|
|
217
|
+
return normalized.includes(SOP_SCAFFOLD_MARKER) || SOP_EMPTY_STAGE_ROW.test(markdown);
|
|
218
|
+
}
|
|
137
219
|
/** Catalog the bank: every agents/<slug>/ dir that holds a workflow.json. */
|
|
138
220
|
export async function listAgentTemplates(opts = {}) {
|
|
139
221
|
const dir = agentsDir(opts);
|
|
@@ -165,11 +247,99 @@ export async function listAgentTemplates(opts = {}) {
|
|
|
165
247
|
catch {
|
|
166
248
|
// manifest missing — listed anyway so `save` gaps are visible
|
|
167
249
|
}
|
|
168
|
-
|
|
250
|
+
let sopState = "missing";
|
|
251
|
+
try {
|
|
252
|
+
const sop = await readFile(join(dir, entry.name, "sop.md"), "utf8");
|
|
253
|
+
sopState = isSopScaffold(sop) ? "scaffold" : "filled";
|
|
254
|
+
}
|
|
255
|
+
catch {
|
|
256
|
+
// SOP missing — listed anyway; callers flag it as not-yet-deliverable
|
|
257
|
+
}
|
|
258
|
+
templates.push({
|
|
259
|
+
slug: entry.name,
|
|
260
|
+
workflowName,
|
|
261
|
+
description,
|
|
262
|
+
hasManifest,
|
|
263
|
+
hasSop: sopState === "filled",
|
|
264
|
+
sopState,
|
|
265
|
+
});
|
|
169
266
|
}
|
|
170
267
|
templates.sort((a, b) => a.slug.localeCompare(b.slug));
|
|
171
268
|
return { agentsDir: dir, templates };
|
|
172
269
|
}
|
|
270
|
+
const DEFAULT_SEARCH_LIMIT = 5;
|
|
271
|
+
const SNIPPET_RADIUS = 120;
|
|
272
|
+
function countOccurrences(text, term) {
|
|
273
|
+
return term ? text.split(term).length - 1 : 0;
|
|
274
|
+
}
|
|
275
|
+
function termSnippet(markdown, terms) {
|
|
276
|
+
const haystack = markdown.toLowerCase();
|
|
277
|
+
let index = -1;
|
|
278
|
+
for (const term of terms) {
|
|
279
|
+
index = haystack.indexOf(term);
|
|
280
|
+
if (index !== -1)
|
|
281
|
+
break;
|
|
282
|
+
}
|
|
283
|
+
if (index === -1)
|
|
284
|
+
return "";
|
|
285
|
+
const start = Math.max(0, index - SNIPPET_RADIUS);
|
|
286
|
+
const end = Math.min(markdown.length, index + SNIPPET_RADIUS);
|
|
287
|
+
const slice = markdown.slice(start, end).replace(/\s+/g, " ").trim();
|
|
288
|
+
return `${start > 0 ? "…" : ""}${slice}${end < markdown.length ? "…" : ""}`;
|
|
289
|
+
}
|
|
290
|
+
/**
|
|
291
|
+
* "Do we already have a workflow for X?" — rank banked templates against
|
|
292
|
+
* search terms, weighting slug + workflow-name hits over manifest-body hits
|
|
293
|
+
* (same scoring shape as docsSearch/clientBuild). Templates without a
|
|
294
|
+
* manifest still match on slug/name so `save` gaps stay findable.
|
|
295
|
+
*/
|
|
296
|
+
export async function searchAgentTemplates(query, opts = {}) {
|
|
297
|
+
const trimmed = query.trim();
|
|
298
|
+
if (!trimmed) {
|
|
299
|
+
throw new Error("searchAgentTemplates needs a non-empty query — use listAgentTemplates for the full catalog.");
|
|
300
|
+
}
|
|
301
|
+
const { agentsDir: dir, templates } = await listAgentTemplates(opts);
|
|
302
|
+
const terms = trimmed.toLowerCase().split(/\s+/).filter(Boolean);
|
|
303
|
+
const limit = opts.limit ?? DEFAULT_SEARCH_LIMIT;
|
|
304
|
+
const scored = await Promise.all(templates.map(async (template) => {
|
|
305
|
+
let manifest = "";
|
|
306
|
+
if (template.hasManifest) {
|
|
307
|
+
try {
|
|
308
|
+
manifest = await readFile(join(dir, template.slug, "template.md"), "utf8");
|
|
309
|
+
}
|
|
310
|
+
catch {
|
|
311
|
+
// listed with hasManifest just above; a race here only costs the snippet
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
// A filled SOP is searched too, so rollout questions ("staged rollout",
|
|
315
|
+
// "soak week", "promotion gate") find the template that answers them.
|
|
316
|
+
// Scaffold-only SOPs are skipped — the boilerplate mentions stages,
|
|
317
|
+
// gates and rollback, so it would false-match every rollout query.
|
|
318
|
+
// The snippet still comes from the manifest — that's the front door.
|
|
319
|
+
let sop = "";
|
|
320
|
+
if (template.sopState === "filled") {
|
|
321
|
+
try {
|
|
322
|
+
sop = await readFile(join(dir, template.slug, "sop.md"), "utf8");
|
|
323
|
+
}
|
|
324
|
+
catch {
|
|
325
|
+
// same race as above; costs only this template's SOP-body score
|
|
326
|
+
}
|
|
327
|
+
}
|
|
328
|
+
const title = `${template.slug} ${template.workflowName}`.toLowerCase();
|
|
329
|
+
const body = `${manifest}\n${sop}`.toLowerCase();
|
|
330
|
+
let score = 0;
|
|
331
|
+
for (const term of terms) {
|
|
332
|
+
score += countOccurrences(title, term) * 5 + countOccurrences(body, term);
|
|
333
|
+
}
|
|
334
|
+
return { template, manifest, score };
|
|
335
|
+
}));
|
|
336
|
+
const matches = scored
|
|
337
|
+
.filter((entry) => entry.score > 0)
|
|
338
|
+
.sort((a, b) => b.score - a.score)
|
|
339
|
+
.slice(0, limit)
|
|
340
|
+
.map(({ template, manifest }) => ({ ...template, snippet: termSnippet(manifest, terms) }));
|
|
341
|
+
return { agentsDir: dir, query: trimmed, matches };
|
|
342
|
+
}
|
|
173
343
|
/**
|
|
174
344
|
* Start a client build from a banked template: copy its workflow.json to
|
|
175
345
|
* <destDir>/<template>.json, ready to import into the client's n8n. Never
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { type ClientLinearProjectOptions } from "./client-linear.js";
|
|
2
|
+
import { type ProjectNode } from "./linear-project.js";
|
|
3
|
+
export interface ClientLinearCreateIssueInput {
|
|
4
|
+
/** Issue title; required, non-empty. */
|
|
5
|
+
title: string;
|
|
6
|
+
/** Optional markdown body. */
|
|
7
|
+
description?: string;
|
|
8
|
+
}
|
|
9
|
+
export interface ClientLinearCreateIssueResult {
|
|
10
|
+
project: ProjectNode;
|
|
11
|
+
issue: {
|
|
12
|
+
identifier: string;
|
|
13
|
+
title: string;
|
|
14
|
+
url: string;
|
|
15
|
+
};
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Create one issue in a client's Linear project. The project is resolved
|
|
19
|
+
* exactly like `clientLinearProject` reads it — from the client's own
|
|
20
|
+
* CLIENT.md `linear_project` URL, never a typed or guessed name — so the
|
|
21
|
+
* issue can only land on that engagement's board. The team is taken from the
|
|
22
|
+
* resolved project itself (its first team), not from configuration, for the
|
|
23
|
+
* same reason. Issues land in the team's default state (triage/backlog);
|
|
24
|
+
* status moves stay a human act in Linear.
|
|
25
|
+
*/
|
|
26
|
+
export declare function clientLinearCreateIssue(slug: string, input: ClientLinearCreateIssueInput, options?: ClientLinearProjectOptions): Promise<ClientLinearCreateIssueResult>;
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { resolveClientLinearProject } from "./client-linear.js";
|
|
2
|
+
import { linearRequest } from "./linear-project.js";
|
|
3
|
+
const PROJECT_TEAMS_QUERY = `
|
|
4
|
+
query ProjectTeams($id: String!) {
|
|
5
|
+
project(id: $id) {
|
|
6
|
+
teams(first: 1) { nodes { id } }
|
|
7
|
+
}
|
|
8
|
+
}
|
|
9
|
+
`;
|
|
10
|
+
const CREATE_ISSUE_MUTATION = `
|
|
11
|
+
mutation CreateIssue($input: IssueCreateInput!) {
|
|
12
|
+
issueCreate(input: $input) {
|
|
13
|
+
success
|
|
14
|
+
issue { identifier title url }
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
`;
|
|
18
|
+
/**
|
|
19
|
+
* Create one issue in a client's Linear project. The project is resolved
|
|
20
|
+
* exactly like `clientLinearProject` reads it — from the client's own
|
|
21
|
+
* CLIENT.md `linear_project` URL, never a typed or guessed name — so the
|
|
22
|
+
* issue can only land on that engagement's board. The team is taken from the
|
|
23
|
+
* resolved project itself (its first team), not from configuration, for the
|
|
24
|
+
* same reason. Issues land in the team's default state (triage/backlog);
|
|
25
|
+
* status moves stay a human act in Linear.
|
|
26
|
+
*/
|
|
27
|
+
export async function clientLinearCreateIssue(slug, input, options = {}) {
|
|
28
|
+
const title = input.title.trim();
|
|
29
|
+
if (!title) {
|
|
30
|
+
throw new Error("clientLinearCreateIssue needs a non-empty issue title");
|
|
31
|
+
}
|
|
32
|
+
const description = input.description?.trim() || undefined;
|
|
33
|
+
const { project, linearToken, fetchImpl } = await resolveClientLinearProject(slug, options);
|
|
34
|
+
const teams = await linearRequest(fetchImpl, linearToken, PROJECT_TEAMS_QUERY, { id: project.id });
|
|
35
|
+
const teamId = teams.project?.teams.nodes[0]?.id;
|
|
36
|
+
if (!teamId) {
|
|
37
|
+
throw new Error(`Linear project "${project.name}" has no team — can't create an issue without one.`);
|
|
38
|
+
}
|
|
39
|
+
const created = await linearRequest(fetchImpl, linearToken, CREATE_ISSUE_MUTATION, {
|
|
40
|
+
input: { teamId, projectId: project.id, title, ...(description ? { description } : {}) },
|
|
41
|
+
});
|
|
42
|
+
if (!created.issueCreate.success || !created.issueCreate.issue) {
|
|
43
|
+
throw new Error(`Linear did not create the issue in "${project.name}" (success=false).`);
|
|
44
|
+
}
|
|
45
|
+
return { project, issue: created.issueCreate.issue };
|
|
46
|
+
}
|
package/dist/client-linear.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ExecFileFn } from "./exec.js";
|
|
2
|
-
import { type LinearProjectOptions, type LinearProjectResult } from "./linear-project.js";
|
|
2
|
+
import { type LinearProjectOptions, type LinearProjectResult, type ProjectNode } from "./linear-project.js";
|
|
3
3
|
/** Thrown when the GitHub token is missing or rejected while fetching CLIENT.md. */
|
|
4
4
|
export declare class ClientLinearAuthError extends Error {
|
|
5
5
|
}
|
|
@@ -13,16 +13,35 @@ export interface ClientLinearProjectOptions extends LinearProjectOptions {
|
|
|
13
13
|
/** Defaults to "client-". */
|
|
14
14
|
repoPrefix?: string;
|
|
15
15
|
}
|
|
16
|
+
/**
|
|
17
|
+
* The slug id is the segment right after /project/ — a copied URL often
|
|
18
|
+
* carries a view tail (".../project/<slugId>/overview" or "/issues"), which
|
|
19
|
+
* a naive last-segment parse mistakes for the id (found live 2026-08-22).
|
|
20
|
+
*/
|
|
21
|
+
export declare function parseLinearProjectSlugId(url: string): string | undefined;
|
|
22
|
+
export interface ResolvedClientLinearProject {
|
|
23
|
+
project: ProjectNode;
|
|
24
|
+
/** The Linear API key that resolved the project — reuse it for follow-up calls. */
|
|
25
|
+
linearToken: string;
|
|
26
|
+
fetchImpl: typeof fetch;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Resolve a client engagement's Linear project from its own `CLIENT.md`
|
|
30
|
+
* `linear_project` field (a `linear.app/.../project/<slugId>` URL, read via
|
|
31
|
+
* the GitHub contents API — same source of truth `clientBuild` reads from,
|
|
32
|
+
* never cloned) rather than guessing from the client's name: Linear project
|
|
33
|
+
* display names don't reliably match a client slug (spacing, capitalization,
|
|
34
|
+
* rebrands), and a guessed name could silently resolve to the wrong project.
|
|
35
|
+
* Shared by `clientLinearProject` (reads) and `clientLinearCreateIssue`
|
|
36
|
+
* (the one write) so both hit the identical project, resolved the identical
|
|
37
|
+
* way.
|
|
38
|
+
*/
|
|
39
|
+
export declare function resolveClientLinearProject(slug: string, options?: ClientLinearProjectOptions): Promise<ResolvedClientLinearProject>;
|
|
16
40
|
/**
|
|
17
41
|
* Open (not completed/canceled/duplicate) issues in a client's Linear
|
|
18
|
-
* project — "what's left to do" for that engagement.
|
|
19
|
-
*
|
|
20
|
-
* `
|
|
21
|
-
* same source of truth `clientBuild` reads from, never cloned) rather than
|
|
22
|
-
* guessed from the client's name: Linear project display names don't
|
|
23
|
-
* reliably match a client slug (spacing, capitalization, rebrands), and a
|
|
24
|
-
* guessed name could silently resolve to the wrong project. Once resolved,
|
|
25
|
-
* behaves exactly like `linearProject` — see `linearProjectIssues`.
|
|
42
|
+
* project — "what's left to do" for that engagement. Resolution is
|
|
43
|
+
* `resolveClientLinearProject` above; once resolved, behaves exactly like
|
|
44
|
+
* `linearProject` — see `linearProjectIssues`.
|
|
26
45
|
*
|
|
27
46
|
* Strictly read-only: never touches CLIENT.md or Linear beyond GraphQL
|
|
28
47
|
* queries.
|
package/dist/client-linear.js
CHANGED
|
@@ -9,33 +9,42 @@ const LINEAR_PROJECT_FIELD_PATTERN = /^linear_project:\s*(\S+)\s*$/m;
|
|
|
9
9
|
/** Thrown when the GitHub token is missing or rejected while fetching CLIENT.md. */
|
|
10
10
|
export class ClientLinearAuthError extends Error {
|
|
11
11
|
}
|
|
12
|
+
/**
|
|
13
|
+
* The slug id is the segment right after /project/ — a copied URL often
|
|
14
|
+
* carries a view tail (".../project/<slugId>/overview" or "/issues"), which
|
|
15
|
+
* a naive last-segment parse mistakes for the id (found live 2026-08-22).
|
|
16
|
+
*/
|
|
17
|
+
export function parseLinearProjectSlugId(url) {
|
|
18
|
+
const segments = url.split("/").filter(Boolean);
|
|
19
|
+
const projectIndex = segments.lastIndexOf("project");
|
|
20
|
+
if (projectIndex !== -1 && segments[projectIndex + 1])
|
|
21
|
+
return segments[projectIndex + 1];
|
|
22
|
+
return segments.pop();
|
|
23
|
+
}
|
|
12
24
|
function parseSlugId(clientMd, slug) {
|
|
13
25
|
const match = clientMd.match(LINEAR_PROJECT_FIELD_PATTERN);
|
|
14
26
|
if (!match) {
|
|
15
27
|
throw new Error(`"${slug}"'s CLIENT.md has no linear_project field — can't resolve its Linear project.`);
|
|
16
28
|
}
|
|
17
29
|
const url = match[1];
|
|
18
|
-
const slugId = url
|
|
30
|
+
const slugId = parseLinearProjectSlugId(url);
|
|
19
31
|
if (!slugId) {
|
|
20
32
|
throw new Error(`Could not parse a Linear project slug id out of "${url}" (from "${slug}"'s CLIENT.md).`);
|
|
21
33
|
}
|
|
22
34
|
return slugId;
|
|
23
35
|
}
|
|
24
36
|
/**
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
* Strictly read-only: never touches CLIENT.md or Linear beyond GraphQL
|
|
36
|
-
* queries.
|
|
37
|
+
* Resolve a client engagement's Linear project from its own `CLIENT.md`
|
|
38
|
+
* `linear_project` field (a `linear.app/.../project/<slugId>` URL, read via
|
|
39
|
+
* the GitHub contents API — same source of truth `clientBuild` reads from,
|
|
40
|
+
* never cloned) rather than guessing from the client's name: Linear project
|
|
41
|
+
* display names don't reliably match a client slug (spacing, capitalization,
|
|
42
|
+
* rebrands), and a guessed name could silently resolve to the wrong project.
|
|
43
|
+
* Shared by `clientLinearProject` (reads) and `clientLinearCreateIssue`
|
|
44
|
+
* (the one write) so both hit the identical project, resolved the identical
|
|
45
|
+
* way.
|
|
37
46
|
*/
|
|
38
|
-
export async function
|
|
47
|
+
export async function resolveClientLinearProject(slug, options = {}) {
|
|
39
48
|
if (slug.startsWith("client-")) {
|
|
40
49
|
throw new Error(`pass the bare slug ("${slug.slice("client-".length)}"), not "${slug}" — the repo prefix is added for you`);
|
|
41
50
|
}
|
|
@@ -81,5 +90,18 @@ export async function clientLinearProject(slug, options = {}) {
|
|
|
81
90
|
throw new LinearAuthError(`Linear API key required — set ${LINEAR_API_TOKEN_ENV} (a personal API key with read access) or pass token`);
|
|
82
91
|
}
|
|
83
92
|
const project = await findProjectBySlugId(fetchImpl, linearToken, slugId);
|
|
93
|
+
return { project, linearToken, fetchImpl };
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Open (not completed/canceled/duplicate) issues in a client's Linear
|
|
97
|
+
* project — "what's left to do" for that engagement. Resolution is
|
|
98
|
+
* `resolveClientLinearProject` above; once resolved, behaves exactly like
|
|
99
|
+
* `linearProject` — see `linearProjectIssues`.
|
|
100
|
+
*
|
|
101
|
+
* Strictly read-only: never touches CLIENT.md or Linear beyond GraphQL
|
|
102
|
+
* queries.
|
|
103
|
+
*/
|
|
104
|
+
export async function clientLinearProject(slug, options = {}) {
|
|
105
|
+
const { project, linearToken, fetchImpl } = await resolveClientLinearProject(slug, options);
|
|
84
106
|
return linearProjectIssues(fetchImpl, linearToken, project, options);
|
|
85
107
|
}
|
package/dist/docs-search.d.ts
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
export declare const TEAM_DOCS_BASE_URL = "https://team.installagent.com";
|
|
2
2
|
export declare const DOCS_SESSION_ENV = "IA_DOCS_SESSION";
|
|
3
|
+
/**
|
|
4
|
+
* Shared bearer token for the /api/search endpoint — the same value as the
|
|
5
|
+
* docs app's IA_DOCS_SEARCH_TOKEN deployment env (see team-web
|
|
6
|
+
* apps/docs/lib/access.ts). Unlike the session cookie it never expires, so
|
|
7
|
+
* it's the right credential for headless callers (the Slack agent, CI).
|
|
8
|
+
*/
|
|
9
|
+
export declare const DOCS_SEARCH_TOKEN_ENV = "IA_DOCS_SEARCH_TOKEN";
|
|
3
10
|
export interface DocsSearchResult {
|
|
4
11
|
title: string;
|
|
5
12
|
url: string;
|
|
@@ -19,7 +26,13 @@ export interface DocsSearchOptions {
|
|
|
19
26
|
baseUrl?: string;
|
|
20
27
|
limit?: number;
|
|
21
28
|
/**
|
|
22
|
-
*
|
|
29
|
+
* Bearer token for the /api/search endpoint. Preferred over the session
|
|
30
|
+
* cookie when both are set. Defaults to the IA_DOCS_SEARCH_TOKEN env var.
|
|
31
|
+
*/
|
|
32
|
+
token?: string;
|
|
33
|
+
/**
|
|
34
|
+
* Browser session, used as the /api/search credential when no token is set
|
|
35
|
+
* and for the crawl fallback: either the raw value of the
|
|
23
36
|
* __Secure-authjs.session-token cookie or a full Cookie header string.
|
|
24
37
|
* Defaults to the IA_DOCS_SESSION env var.
|
|
25
38
|
*/
|
|
@@ -35,10 +48,10 @@ export declare class DocsSessionError extends Error {
|
|
|
35
48
|
* results can't drift from what's deployed and don't require a team-web
|
|
36
49
|
* checkout.
|
|
37
50
|
*
|
|
38
|
-
* Tries the
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
* to crawling the SSO-gated /docs pages
|
|
42
|
-
* cookie and ranking them client-side.
|
|
51
|
+
* Tries the Fumadocs search endpoint (/api/search) first — the docs app
|
|
52
|
+
* gates it on a NextAuth session OR the shared IA_DOCS_SEARCH_TOKEN bearer,
|
|
53
|
+
* so either credential gets real full-text search. When the endpoint says no
|
|
54
|
+
* (or is unreachable), we fall back to crawling the SSO-gated /docs pages
|
|
55
|
+
* with the session cookie and ranking them client-side.
|
|
43
56
|
*/
|
|
44
57
|
export declare function docsSearch(query: string, options?: DocsSearchOptions): Promise<DocsSearchResponse>;
|
package/dist/docs-search.js
CHANGED
|
@@ -2,6 +2,13 @@ export const TEAM_DOCS_BASE_URL = "https://team.installagent.com";
|
|
|
2
2
|
/** NextAuth v5 production session cookie on team.installagent.com. */
|
|
3
3
|
const SESSION_COOKIE = "__Secure-authjs.session-token";
|
|
4
4
|
export const DOCS_SESSION_ENV = "IA_DOCS_SESSION";
|
|
5
|
+
/**
|
|
6
|
+
* Shared bearer token for the /api/search endpoint — the same value as the
|
|
7
|
+
* docs app's IA_DOCS_SEARCH_TOKEN deployment env (see team-web
|
|
8
|
+
* apps/docs/lib/access.ts). Unlike the session cookie it never expires, so
|
|
9
|
+
* it's the right credential for headless callers (the Slack agent, CI).
|
|
10
|
+
*/
|
|
11
|
+
export const DOCS_SEARCH_TOKEN_ENV = "IA_DOCS_SEARCH_TOKEN";
|
|
5
12
|
const CONCURRENCY = 8;
|
|
6
13
|
/** Thrown when the crawl fallback has no usable Google SSO session. */
|
|
7
14
|
export class DocsSessionError extends Error {
|
|
@@ -11,11 +18,11 @@ export class DocsSessionError extends Error {
|
|
|
11
18
|
* results can't drift from what's deployed and don't require a team-web
|
|
12
19
|
* checkout.
|
|
13
20
|
*
|
|
14
|
-
* Tries the
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
* to crawling the SSO-gated /docs pages
|
|
18
|
-
* cookie and ranking them client-side.
|
|
21
|
+
* Tries the Fumadocs search endpoint (/api/search) first — the docs app
|
|
22
|
+
* gates it on a NextAuth session OR the shared IA_DOCS_SEARCH_TOKEN bearer,
|
|
23
|
+
* so either credential gets real full-text search. When the endpoint says no
|
|
24
|
+
* (or is unreachable), we fall back to crawling the SSO-gated /docs pages
|
|
25
|
+
* with the session cookie and ranking them client-side.
|
|
19
26
|
*/
|
|
20
27
|
export async function docsSearch(query, options = {}) {
|
|
21
28
|
const q = query.trim();
|
|
@@ -25,14 +32,26 @@ export async function docsSearch(query, options = {}) {
|
|
|
25
32
|
const base = (options.baseUrl ?? TEAM_DOCS_BASE_URL).replace(/\/+$/, "");
|
|
26
33
|
const limit = options.limit ?? 8;
|
|
27
34
|
const fetchImpl = options.fetchImpl ?? fetch;
|
|
28
|
-
const
|
|
35
|
+
const token = options.token ?? process.env[DOCS_SEARCH_TOKEN_ENV];
|
|
36
|
+
const session = options.session ?? process.env[DOCS_SESSION_ENV];
|
|
37
|
+
const apiResults = await tryApiSearch(fetchImpl, base, q, searchAuthHeaders(token, session));
|
|
29
38
|
if (apiResults) {
|
|
30
39
|
return { query: q, source: "api", results: apiResults.slice(0, limit) };
|
|
31
40
|
}
|
|
32
|
-
const session = options.session ?? process.env[DOCS_SESSION_ENV];
|
|
33
41
|
const results = await crawlSearch(fetchImpl, base, q, limit, session);
|
|
34
42
|
return { query: q, source: "crawl", results };
|
|
35
43
|
}
|
|
44
|
+
/** The bearer token wins when both are set: it never expires, the cookie does. */
|
|
45
|
+
function searchAuthHeaders(token, session) {
|
|
46
|
+
if (token)
|
|
47
|
+
return { authorization: `Bearer ${token}` };
|
|
48
|
+
if (session)
|
|
49
|
+
return { cookie: sessionCookieHeader(session) };
|
|
50
|
+
return {};
|
|
51
|
+
}
|
|
52
|
+
function sessionCookieHeader(session) {
|
|
53
|
+
return session.includes("=") ? session : `${SESSION_COOKIE}=${session}`;
|
|
54
|
+
}
|
|
36
55
|
function isFumadocsEntry(value) {
|
|
37
56
|
if (typeof value !== "object" || value === null)
|
|
38
57
|
return false;
|
|
@@ -41,10 +60,11 @@ function isFumadocsEntry(value) {
|
|
|
41
60
|
typeof entry.type === "string" &&
|
|
42
61
|
typeof entry.content === "string");
|
|
43
62
|
}
|
|
44
|
-
async function tryApiSearch(fetchImpl, base, query) {
|
|
63
|
+
async function tryApiSearch(fetchImpl, base, query, headers) {
|
|
45
64
|
let data;
|
|
46
65
|
try {
|
|
47
66
|
const res = await fetchImpl(`${base}/api/search?query=${encodeURIComponent(query)}`, {
|
|
67
|
+
headers,
|
|
48
68
|
redirect: "manual",
|
|
49
69
|
});
|
|
50
70
|
if (!res.ok)
|
|
@@ -85,14 +105,15 @@ async function tryApiSearch(fetchImpl, base, query) {
|
|
|
85
105
|
async function crawlSearch(fetchImpl, base, query, limit, session) {
|
|
86
106
|
if (!session) {
|
|
87
107
|
throw new DocsSessionError([
|
|
88
|
-
`The team docs (${base}) are gated
|
|
108
|
+
`The team docs (${base}) are gated, so searching needs a credential.`,
|
|
109
|
+
`Preferred: set ${DOCS_SEARCH_TOKEN_ENV} to the shared docs-search bearer token — \`ia env fill\` reads it from 1Password, and it never expires.`,
|
|
110
|
+
`Or use your own browser session (expires periodically):`,
|
|
89
111
|
`1. Open ${base} in your browser and sign in with your @installagent.com account.`,
|
|
90
112
|
`2. DevTools → Application → Cookies → copy the value of ${SESSION_COOKIE}.`,
|
|
91
113
|
`3. export ${DOCS_SESSION_ENV}="<that value>" (or pass --session).`,
|
|
92
114
|
].join("\n"));
|
|
93
115
|
}
|
|
94
|
-
const
|
|
95
|
-
const headers = { cookie };
|
|
116
|
+
const headers = { cookie: sessionCookieHeader(session) };
|
|
96
117
|
const rootRes = await fetchImpl(`${base}/docs`, { headers, redirect: "manual" });
|
|
97
118
|
if (rootRes.status >= 300 && rootRes.status < 400) {
|
|
98
119
|
throw new DocsSessionError(`Your docs session was rejected (redirected to login). Grab a fresh ${SESSION_COOKIE} cookie from ${base} and update ${DOCS_SESSION_ENV}.`);
|
package/dist/doctor.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type ExecFileFn } from "./exec.js";
|
|
2
|
+
import { type PlatformInfo } from "./platform.js";
|
|
2
3
|
export interface DoctorOptions {
|
|
3
4
|
/** installagent/ workspace root to inspect. Defaults to the current dir. */
|
|
4
5
|
workspaceDir?: string;
|
|
@@ -10,6 +11,8 @@ export interface DoctorOptions {
|
|
|
10
11
|
offline?: boolean;
|
|
11
12
|
/** Injectable for tests; defaults to global fetch. */
|
|
12
13
|
fetchImpl?: typeof fetch;
|
|
14
|
+
/** Injectable for tests; defaults to the running machine. Picks fix-it text. */
|
|
15
|
+
platform?: PlatformInfo;
|
|
13
16
|
}
|
|
14
17
|
export type DoctorStatus = "ok" | "missing" | "warn";
|
|
15
18
|
export interface DoctorCheck {
|
|
@@ -21,6 +24,12 @@ export interface DoctorCheck {
|
|
|
21
24
|
detail: string;
|
|
22
25
|
/** Concrete next step when the check isn't ok. */
|
|
23
26
|
fixIt?: string;
|
|
27
|
+
/**
|
|
28
|
+
* Background detail, not part of the daily checkup — printed only by
|
|
29
|
+
* `ia doctor --all`. The check still travels in the result so MCP callers
|
|
30
|
+
* and the wizard see everything; only the default human view hides it.
|
|
31
|
+
*/
|
|
32
|
+
verboseOnly?: boolean;
|
|
24
33
|
}
|
|
25
34
|
export interface DoctorResult {
|
|
26
35
|
/** True when nothing is `missing` — warnings don't fail the checkup. */
|