@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.
- package/dist/agent-mirror.d.ts +69 -0
- package/dist/agent-mirror.js +275 -0
- package/dist/agent-templates.d.ts +36 -2
- package/dist/agent-templates.js +173 -3
- package/dist/claude-hours.d.ts +118 -0
- package/dist/claude-hours.js +523 -0
- package/dist/client-drive.d.ts +3 -0
- package/dist/client-drive.js +2 -2
- 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 +55 -13
- package/dist/env-push.d.ts +3 -0
- package/dist/env-push.js +11 -6
- package/dist/env-registry.d.ts +29 -0
- package/dist/env-registry.js +123 -9
- package/dist/exec.js +15 -2
- package/dist/git.d.ts +31 -0
- package/dist/git.js +59 -0
- package/dist/google-service-account.d.ts +20 -0
- package/dist/google-service-account.js +49 -0
- package/dist/hours-estimate.d.ts +43 -0
- package/dist/hours-estimate.js +159 -0
- package/dist/hours-export-schedule.d.ts +35 -0
- package/dist/hours-export-schedule.js +188 -0
- package/dist/hours-ledger.d.ts +129 -0
- package/dist/hours-ledger.js +882 -0
- package/dist/index.d.ts +25 -6
- package/dist/index.js +25 -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 +108 -0
- package/dist/portal-admin.js +94 -1
- package/dist/standup.d.ts +88 -0
- package/dist/standup.js +235 -0
- package/dist/sync-repos.d.ts +54 -0
- package/dist/sync-repos.js +89 -0
- package/dist/template-sync.d.ts +11 -0
- package/dist/template-sync.js +16 -0
- package/dist/triage-backfill.d.ts +37 -0
- package/dist/triage-backfill.js +211 -0
- package/dist/triage-enable.d.ts +90 -0
- package/dist/triage-enable.js +428 -0
- package/dist/triage-gates.d.ts +252 -0
- package/dist/triage-gates.js +951 -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/dist/workspace-push.d.ts +39 -0
- package/dist/workspace-push.js +78 -0
- package/dist/workspace-status.d.ts +37 -0
- package/dist/workspace-status.js +114 -0
- package/package.json +2 -2
- package/templates/env.example +37 -23
- package/templates/workspace-root/.claude/settings.json +12 -1
- 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 +127 -0
- package/templates/workspace-root/skills/CLAUDE.md +29 -6
- package/templates/workspace-root/skills/README.md +171 -0
- package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -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-deliverables/SKILL.md +1 -1
- package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
- package/templates/workspace-root/skills/client-latest/SKILL.md +343 -0
- package/templates/workspace-root/skills/client-latest/catchup.command.md +18 -0
- package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +258 -0
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
- package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
- package/templates/workspace-root/skills/github-profile/SKILL.md +106 -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 +49 -7
- package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
- 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
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { type PortalAdminOptions, type PortalTriageProvider } from "./portal-admin.js";
|
|
2
|
+
import { type TriageBackfillResult } from "./triage-backfill.js";
|
|
3
|
+
import { type TriageSourceOptions } from "./triage-gates.js";
|
|
4
|
+
/** The Header Auth credential every record node binds (the portal's AGENT_INGEST_SECRET). */
|
|
5
|
+
export declare const PORTAL_INGEST_CREDENTIAL_NAME = "IA - portal - agent-ingest";
|
|
6
|
+
export declare const TRIAGE_RECORDS_PATH = "/api/triage-records";
|
|
7
|
+
export type TriageWiringCheckId = "record-node" | "credential" | "error-branch" | "workflow-id";
|
|
8
|
+
export interface TriageWiringCheck {
|
|
9
|
+
id: TriageWiringCheckId;
|
|
10
|
+
label: string;
|
|
11
|
+
/** The node the check looked at — a name only, never its parameters. */
|
|
12
|
+
node: string | null;
|
|
13
|
+
ok: boolean;
|
|
14
|
+
/** What to change when the check fails. */
|
|
15
|
+
fix?: string;
|
|
16
|
+
}
|
|
17
|
+
export interface TriageWiringReport {
|
|
18
|
+
/** Which version of the workflow was checked: the published one when it exists. */
|
|
19
|
+
version: "published" | "draft";
|
|
20
|
+
/**
|
|
21
|
+
* True when the saved draft has changes the published version does not
|
|
22
|
+
* have. With `version: "draft"` it means the published version failed and
|
|
23
|
+
* the saved draft passed: publish it (after the mark).
|
|
24
|
+
*/
|
|
25
|
+
draftDiffers: boolean;
|
|
26
|
+
checks: TriageWiringCheck[];
|
|
27
|
+
ok: boolean;
|
|
28
|
+
}
|
|
29
|
+
type WiringOptions = {
|
|
30
|
+
portalUrl?: string;
|
|
31
|
+
provider?: PortalTriageProvider;
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* The four checks on a workflow's record wiring, from a GET /workflows/{id}
|
|
35
|
+
* answer. Pure — exported for tests and for the enable command.
|
|
36
|
+
*
|
|
37
|
+
* The published version is checked when there is one. When it fails and the
|
|
38
|
+
* saved draft differs, the draft is checked too, and a passing draft passes:
|
|
39
|
+
* that is a live workflow whose record nodes are saved but not yet published
|
|
40
|
+
* — exactly when enable must run, because publishing before the mark makes
|
|
41
|
+
* every run 404/409.
|
|
42
|
+
*/
|
|
43
|
+
export declare function checkTriageRecordWiring(workflow: unknown, options?: WiringOptions): TriageWiringReport;
|
|
44
|
+
/** gmail / outlook from a workflow's mailbox nodes; null when it has none, or both. */
|
|
45
|
+
export declare function detectWorkflowProvider(nodes: ReadonlyArray<{
|
|
46
|
+
type: string;
|
|
47
|
+
}>): PortalTriageProvider | null;
|
|
48
|
+
export interface TriageEnableOptions extends Pick<TriageSourceOptions, "csv" | "sheetId" | "workspaceDir" | "serviceAccountKey" | "now"> {
|
|
49
|
+
/** Portal agent slug — needed when the org has more than one active agent. */
|
|
50
|
+
agent?: string;
|
|
51
|
+
/** gmail | outlook; default: the client repo's workflow export, then the live workflow. */
|
|
52
|
+
provider?: PortalTriageProvider;
|
|
53
|
+
/** false = skip the backfill step (`--no-backfill`). */
|
|
54
|
+
backfill?: boolean;
|
|
55
|
+
/** Check only: no mark, no backfill. */
|
|
56
|
+
dryRun?: boolean;
|
|
57
|
+
/** Portal admin API access; the secret defaults to $IA_PORTAL_ADMIN_SECRET. */
|
|
58
|
+
portal?: Omit<PortalAdminOptions, "fetchImpl">;
|
|
59
|
+
/** n8n API access; defaults to $N8N_API_URL (incl. /api/v1) and $N8N_API_KEY. */
|
|
60
|
+
n8n?: {
|
|
61
|
+
baseUrl?: string;
|
|
62
|
+
apiKey?: string;
|
|
63
|
+
env?: Record<string, string | undefined>;
|
|
64
|
+
};
|
|
65
|
+
/** Injectable for tests; used for the portal, n8n and Google Sheets. */
|
|
66
|
+
fetchImpl?: typeof fetch;
|
|
67
|
+
}
|
|
68
|
+
export interface TriageEnableResult {
|
|
69
|
+
slug: string;
|
|
70
|
+
agent: string;
|
|
71
|
+
workflowId: string;
|
|
72
|
+
provider: PortalTriageProvider;
|
|
73
|
+
providerSource: "flag" | "repo" | "portal" | "workflow";
|
|
74
|
+
/** The n8n editor URL of the workflow, for the publish step. */
|
|
75
|
+
workflowUrl: string;
|
|
76
|
+
wiring: TriageWiringReport;
|
|
77
|
+
/** True once the portal holds the agent as a triage agent of `provider`. */
|
|
78
|
+
marked: boolean;
|
|
79
|
+
/** The sheet backfill, `{ notRun }` with the reason, or null when the run stopped earlier. */
|
|
80
|
+
backfill: TriageBackfillResult | {
|
|
81
|
+
notRun: string;
|
|
82
|
+
} | null;
|
|
83
|
+
dryRun: boolean;
|
|
84
|
+
ok: boolean;
|
|
85
|
+
/** Set when the run stopped after the mark: what went wrong, and the fix. */
|
|
86
|
+
failure?: string;
|
|
87
|
+
nextSteps: string[];
|
|
88
|
+
}
|
|
89
|
+
export declare function triageEnable(slug: string, options?: TriageEnableOptions): Promise<TriageEnableResult>;
|
|
90
|
+
export {};
|
|
@@ -0,0 +1,428 @@
|
|
|
1
|
+
import { readdir, readFile } from "node:fs/promises";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { N8N_API_KEY_ENV, N8N_API_URL_ENV, N8nAuthError } from "./agent-templates.js";
|
|
4
|
+
import { DEFAULT_PORTAL_URL, PORTAL_URL_ENV, portalListAgents, portalSetAgentTriage, } from "./portal-admin.js";
|
|
5
|
+
import { triageBackfill } from "./triage-backfill.js";
|
|
6
|
+
import { resolveRecordSheetId } from "./triage-gates.js";
|
|
7
|
+
// `ia triage enable <slug>`: turn a registered agent into a portal triage
|
|
8
|
+
// agent, so its workflow may write classification rows to the portal. The
|
|
9
|
+
// order is the point: CHECK the live workflow's record wiring (read-only),
|
|
10
|
+
// then MARK the agent, then BACKFILL the old record sheet if there is one.
|
|
11
|
+
// A workflow published before the mark posts every run into a 404/409 and the
|
|
12
|
+
// alert branch — so the SOP runs this before the first publish.
|
|
13
|
+
//
|
|
14
|
+
// The live check reads the workflow over the n8n API and reports node NAMES
|
|
15
|
+
// and pass/fail only. It never copies a node parameter into its result:
|
|
16
|
+
// a triage workflow's prompts hold client data.
|
|
17
|
+
/** The Header Auth credential every record node binds (the portal's AGENT_INGEST_SECRET). */
|
|
18
|
+
export const PORTAL_INGEST_CREDENTIAL_NAME = "IA - portal - agent-ingest";
|
|
19
|
+
export const TRIAGE_RECORDS_PATH = "/api/triage-records";
|
|
20
|
+
function isRecord(value) {
|
|
21
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
22
|
+
}
|
|
23
|
+
function nodesOf(value) {
|
|
24
|
+
if (!Array.isArray(value))
|
|
25
|
+
return [];
|
|
26
|
+
return value.filter((n) => isRecord(n) && typeof n.name === "string" && typeof n.type === "string");
|
|
27
|
+
}
|
|
28
|
+
/** The version to check: the published one (n8n's `activeVersion`) when it exists, else the saved draft. */
|
|
29
|
+
function pickVersion(workflow) {
|
|
30
|
+
const draft = isRecord(workflow) ? workflow : {};
|
|
31
|
+
const published = isRecord(draft.activeVersion) ? draft.activeVersion : null;
|
|
32
|
+
if (published && Array.isArray(published.nodes)) {
|
|
33
|
+
return {
|
|
34
|
+
version: "published",
|
|
35
|
+
nodes: nodesOf(published.nodes),
|
|
36
|
+
connections: (isRecord(published.connections)
|
|
37
|
+
? published.connections
|
|
38
|
+
: {}),
|
|
39
|
+
draftDiffers: typeof draft.versionId === "string" &&
|
|
40
|
+
typeof published.versionId === "string" &&
|
|
41
|
+
draft.versionId !== published.versionId,
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
return {
|
|
45
|
+
version: "draft",
|
|
46
|
+
nodes: nodesOf(draft.nodes),
|
|
47
|
+
connections: (isRecord(draft.connections) ? draft.connections : {}),
|
|
48
|
+
draftDiffers: false,
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
function targetsOf(connections, from, output) {
|
|
52
|
+
const branch = connections[from]?.main?.[output];
|
|
53
|
+
if (!Array.isArray(branch))
|
|
54
|
+
return [];
|
|
55
|
+
return branch.map((edge) => edge?.node).filter((n) => typeof n === "string");
|
|
56
|
+
}
|
|
57
|
+
function upstreamOf(connections, to) {
|
|
58
|
+
const sources = [];
|
|
59
|
+
for (const [from, entry] of Object.entries(connections)) {
|
|
60
|
+
for (const branch of entry?.main ?? []) {
|
|
61
|
+
if (Array.isArray(branch) && branch.some((edge) => edge?.node === to)) {
|
|
62
|
+
sources.push(from);
|
|
63
|
+
break;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
return sources;
|
|
68
|
+
}
|
|
69
|
+
const PLACEHOLDER_ID = /^<.*>$|REPLACE_ME|__SET_IN_N8N__/;
|
|
70
|
+
const SENDS_WORKFLOW_ID = /\bworkflowId\s*:\s*\$workflow\.id\b/;
|
|
71
|
+
/**
|
|
72
|
+
* The four checks on a workflow's record wiring, from a GET /workflows/{id}
|
|
73
|
+
* answer. Pure — exported for tests and for the enable command.
|
|
74
|
+
*
|
|
75
|
+
* The published version is checked when there is one. When it fails and the
|
|
76
|
+
* saved draft differs, the draft is checked too, and a passing draft passes:
|
|
77
|
+
* that is a live workflow whose record nodes are saved but not yet published
|
|
78
|
+
* — exactly when enable must run, because publishing before the mark makes
|
|
79
|
+
* every run 404/409.
|
|
80
|
+
*/
|
|
81
|
+
export function checkTriageRecordWiring(workflow, options = {}) {
|
|
82
|
+
const picked = pickVersion(workflow);
|
|
83
|
+
const report = checkVersion(picked, options);
|
|
84
|
+
if (report.ok || !picked.draftDiffers || !isRecord(workflow))
|
|
85
|
+
return report;
|
|
86
|
+
const draft = checkVersion({
|
|
87
|
+
version: "draft",
|
|
88
|
+
nodes: nodesOf(workflow.nodes),
|
|
89
|
+
connections: (isRecord(workflow.connections)
|
|
90
|
+
? workflow.connections
|
|
91
|
+
: {}),
|
|
92
|
+
draftDiffers: true,
|
|
93
|
+
}, options);
|
|
94
|
+
return draft.ok ? draft : report;
|
|
95
|
+
}
|
|
96
|
+
function checkVersion(picked, options) {
|
|
97
|
+
const { version, nodes, connections, draftDiffers } = picked;
|
|
98
|
+
const portalUrl = (options.portalUrl ??
|
|
99
|
+
process.env[PORTAL_URL_ENV] ??
|
|
100
|
+
DEFAULT_PORTAL_URL).replace(/\/+$/, "");
|
|
101
|
+
const expectedUrl = `${portalUrl}${TRIAGE_RECORDS_PATH}`;
|
|
102
|
+
const bank = `agents/email-${options.provider ?? "gmail"}-triage/workflow.json`;
|
|
103
|
+
const names = new Set(nodes.map((n) => n.name));
|
|
104
|
+
const isHttp = (n) => n.type === "n8n-nodes-base.httpRequest";
|
|
105
|
+
const isBatch = (n) => n?.type === "n8n-nodes-base.code" &&
|
|
106
|
+
SENDS_WORKFLOW_ID.test(String(n.parameters?.jsCode ?? n.parameters?.code ?? ""));
|
|
107
|
+
let recordNodes = nodes.filter((n) => isHttp(n) && String(n.parameters?.url ?? "").includes(TRIAGE_RECORDS_PATH));
|
|
108
|
+
if (recordNodes.length === 0) {
|
|
109
|
+
// A record node with a wrong URL: the HTTP node the batch Code node feeds.
|
|
110
|
+
const fed = new Set(nodes.filter(isBatch).flatMap((n) => targetsOf(connections, n.name, 0)));
|
|
111
|
+
recordNodes = nodes.filter((n) => isHttp(n) && fed.has(n.name));
|
|
112
|
+
}
|
|
113
|
+
const record = recordNodes[0];
|
|
114
|
+
if (!record) {
|
|
115
|
+
const none = "no record node — fix the record-node check first";
|
|
116
|
+
return {
|
|
117
|
+
version,
|
|
118
|
+
draftDiffers,
|
|
119
|
+
ok: false,
|
|
120
|
+
checks: [
|
|
121
|
+
{
|
|
122
|
+
id: "record-node",
|
|
123
|
+
label: `an HTTP Request node POSTs to ${expectedUrl}`,
|
|
124
|
+
node: null,
|
|
125
|
+
ok: false,
|
|
126
|
+
fix: `add the three record nodes from ${bank} (🧺 Batch Record Rows → 📊 Record to Portal → ` +
|
|
127
|
+
"📣 Record Failed → #team-techs) after 🔧 Shape Record",
|
|
128
|
+
},
|
|
129
|
+
{ id: "credential", label: "the credential is bound", node: null, ok: false, fix: none },
|
|
130
|
+
{ id: "error-branch", label: "the error output alerts", node: null, ok: false, fix: none },
|
|
131
|
+
{
|
|
132
|
+
id: "workflow-id",
|
|
133
|
+
label: "the batch names the workflow",
|
|
134
|
+
node: null,
|
|
135
|
+
ok: false,
|
|
136
|
+
fix: none,
|
|
137
|
+
},
|
|
138
|
+
],
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
const checks = [];
|
|
142
|
+
// (a) the node POSTs to this portal's ingest, and is switched on.
|
|
143
|
+
const url = String(record.parameters?.url ?? "").trim();
|
|
144
|
+
const method = String(record.parameters?.method ?? "GET").toUpperCase();
|
|
145
|
+
const urlFix = [];
|
|
146
|
+
if (url !== expectedUrl)
|
|
147
|
+
urlFix.push(`set its URL to ${expectedUrl}`);
|
|
148
|
+
if (method !== "POST")
|
|
149
|
+
urlFix.push("set its method to POST");
|
|
150
|
+
if (record.disabled)
|
|
151
|
+
urlFix.push("enable the node (it is deactivated)");
|
|
152
|
+
if (recordNodes.length > 1) {
|
|
153
|
+
urlFix.push(`keep one record node only — ${recordNodes.length} nodes post to ${TRIAGE_RECORDS_PATH}: ` +
|
|
154
|
+
recordNodes.map((n) => n.name).join(", "));
|
|
155
|
+
}
|
|
156
|
+
checks.push({
|
|
157
|
+
id: "record-node",
|
|
158
|
+
label: `an HTTP Request node POSTs to ${expectedUrl}`,
|
|
159
|
+
node: record.name,
|
|
160
|
+
ok: urlFix.length === 0,
|
|
161
|
+
...(urlFix.length ? { fix: urlFix.join("; ") } : {}),
|
|
162
|
+
});
|
|
163
|
+
// (b) the Header Auth credential is bound for real — the API and the MCP cannot bind it.
|
|
164
|
+
const credential = record.credentials?.httpHeaderAuth;
|
|
165
|
+
const credentialId = typeof credential?.id === "string" ? credential.id.trim() : "";
|
|
166
|
+
const credentialName = typeof credential?.name === "string" ? credential.name : "";
|
|
167
|
+
const bindFix = `in the n8n UI, open ${record.name} → Credential → pick "${PORTAL_INGEST_CREDENTIAL_NAME}" ` +
|
|
168
|
+
"(Header Auth), then save. The n8n API and MCP cannot bind a credential.";
|
|
169
|
+
let credentialFix;
|
|
170
|
+
if (!credential || !credentialId)
|
|
171
|
+
credentialFix = `no credential is bound — ${bindFix}`;
|
|
172
|
+
else if (PLACEHOLDER_ID.test(credentialId))
|
|
173
|
+
credentialFix = `the credential id is still the bank placeholder — ${bindFix}`;
|
|
174
|
+
else if (credentialName !== PORTAL_INGEST_CREDENTIAL_NAME)
|
|
175
|
+
credentialFix = `it is bound to another credential — ${bindFix}`;
|
|
176
|
+
else if (record.parameters?.authentication !== "genericCredentialType" ||
|
|
177
|
+
record.parameters?.genericAuthType !== "httpHeaderAuth")
|
|
178
|
+
credentialFix = `set Authentication to Generic Credential Type → Header Auth — ${bindFix}`;
|
|
179
|
+
checks.push({
|
|
180
|
+
id: "credential",
|
|
181
|
+
label: `the credential is "${PORTAL_INGEST_CREDENTIAL_NAME}"`,
|
|
182
|
+
node: record.name,
|
|
183
|
+
ok: credentialFix === undefined,
|
|
184
|
+
...(credentialFix ? { fix: credentialFix } : {}),
|
|
185
|
+
});
|
|
186
|
+
// (c) a failed POST goes down the error output to a real node (the #team-techs alert).
|
|
187
|
+
const errorTargets = targetsOf(connections, record.name, 1).filter((n) => names.has(n));
|
|
188
|
+
let errorFix;
|
|
189
|
+
if (record.onError !== "continueErrorOutput") {
|
|
190
|
+
errorFix =
|
|
191
|
+
`open ${record.name} → Settings → On Error → "Continue (using error output)" ` +
|
|
192
|
+
"(onError: continueErrorOutput), then connect its error output to 📣 Record Failed → #team-techs";
|
|
193
|
+
}
|
|
194
|
+
else if (errorTargets.length === 0) {
|
|
195
|
+
errorFix = `connect the error output (output 1) of ${record.name} to 📣 Record Failed → #team-techs`;
|
|
196
|
+
}
|
|
197
|
+
checks.push({
|
|
198
|
+
id: "error-branch",
|
|
199
|
+
label: "a failed POST goes to the error output, and the error output alerts",
|
|
200
|
+
node: record.name,
|
|
201
|
+
ok: errorFix === undefined,
|
|
202
|
+
...(errorFix ? { fix: errorFix } : {}),
|
|
203
|
+
});
|
|
204
|
+
// (d) the node before it is the Code node that sends workflowId: $workflow.id.
|
|
205
|
+
const batchNodes = upstreamOf(connections, record.name)
|
|
206
|
+
.map((name) => nodes.find((n) => n.name === name))
|
|
207
|
+
.filter((n) => n !== undefined);
|
|
208
|
+
const batch = batchNodes.find(isBatch);
|
|
209
|
+
checks.push({
|
|
210
|
+
id: "workflow-id",
|
|
211
|
+
label: "the Code node before it sends workflowId: $workflow.id",
|
|
212
|
+
node: batch?.name ?? batchNodes[0]?.name ?? null,
|
|
213
|
+
ok: batch !== undefined,
|
|
214
|
+
...(batch
|
|
215
|
+
? {}
|
|
216
|
+
: {
|
|
217
|
+
fix: `put the Code node 🧺 Batch Record Rows from ${bank} directly before ${record.name}; it ` +
|
|
218
|
+
"returns { workflowId: $workflow.id, executionId: $execution.id, rows } — the portal " +
|
|
219
|
+
"finds the agent by that workflowId, so a hard-coded id breaks on a copied workflow",
|
|
220
|
+
}),
|
|
221
|
+
});
|
|
222
|
+
return { version, draftDiffers, checks, ok: checks.every((c) => c.ok) };
|
|
223
|
+
}
|
|
224
|
+
const GMAIL_NODE = /^n8n-nodes-base\.gmail(Trigger)?$/;
|
|
225
|
+
const OUTLOOK_NODE = /^n8n-nodes-base\.microsoftOutlook(Trigger)?$/;
|
|
226
|
+
/** gmail / outlook from a workflow's mailbox nodes; null when it has none, or both. */
|
|
227
|
+
export function detectWorkflowProvider(nodes) {
|
|
228
|
+
const gmail = nodes.some((n) => GMAIL_NODE.test(n.type));
|
|
229
|
+
const outlook = nodes.some((n) => OUTLOOK_NODE.test(n.type));
|
|
230
|
+
if (gmail === outlook)
|
|
231
|
+
return null;
|
|
232
|
+
return gmail ? "gmail" : "outlook";
|
|
233
|
+
}
|
|
234
|
+
/** The provider the client repo's workflow exports say, when they agree on one. */
|
|
235
|
+
async function detectRepoProvider(workspaceDir, slug) {
|
|
236
|
+
const dir = join(workspaceDir, "clients", `client-${slug}`, "workflows");
|
|
237
|
+
let files;
|
|
238
|
+
try {
|
|
239
|
+
files = (await readdir(dir)).filter((f) => f.endsWith(".json")).sort();
|
|
240
|
+
}
|
|
241
|
+
catch {
|
|
242
|
+
return null;
|
|
243
|
+
}
|
|
244
|
+
const found = new Set();
|
|
245
|
+
for (const file of files) {
|
|
246
|
+
let parsed;
|
|
247
|
+
try {
|
|
248
|
+
parsed = JSON.parse(await readFile(join(dir, file), "utf8"));
|
|
249
|
+
}
|
|
250
|
+
catch {
|
|
251
|
+
continue;
|
|
252
|
+
}
|
|
253
|
+
const provider = detectWorkflowProvider(nodesOf(isRecord(parsed) ? parsed.nodes : undefined));
|
|
254
|
+
if (provider)
|
|
255
|
+
found.add(provider);
|
|
256
|
+
}
|
|
257
|
+
return found.size === 1 ? ([...found][0] ?? null) : null;
|
|
258
|
+
}
|
|
259
|
+
function n8nAuth(options) {
|
|
260
|
+
const env = options.n8n?.env ?? process.env;
|
|
261
|
+
const baseUrl = (options.n8n?.baseUrl ?? env[N8N_API_URL_ENV])?.replace(/\/+$/, "");
|
|
262
|
+
const apiKey = options.n8n?.apiKey ?? env[N8N_API_KEY_ENV];
|
|
263
|
+
if (!baseUrl || !apiKey) {
|
|
264
|
+
throw new N8nAuthError(`the live check reads the workflow from n8n — set $${N8N_API_URL_ENV} (incl. /api/v1) and ` +
|
|
265
|
+
`$${N8N_API_KEY_ENV} (ia env fill)`);
|
|
266
|
+
}
|
|
267
|
+
return { baseUrl, apiKey };
|
|
268
|
+
}
|
|
269
|
+
async function fetchWorkflow(workflowId, agentLabel, options) {
|
|
270
|
+
const { baseUrl, apiKey } = n8nAuth(options);
|
|
271
|
+
const fetchImpl = options.fetchImpl ?? fetch;
|
|
272
|
+
const res = await fetchImpl(`${baseUrl}/workflows/${encodeURIComponent(workflowId)}`, {
|
|
273
|
+
headers: { "X-N8N-API-KEY": apiKey, accept: "application/json" },
|
|
274
|
+
});
|
|
275
|
+
if (res.status === 401 || res.status === 403) {
|
|
276
|
+
throw new N8nAuthError(`n8n refused $${N8N_API_KEY_ENV} (HTTP ${res.status}) — check it in 1Password`);
|
|
277
|
+
}
|
|
278
|
+
if (res.status === 404) {
|
|
279
|
+
throw new Error(`n8n has no workflow ${workflowId} (the workflow of ${agentLabel}). If the agent now runs ` +
|
|
280
|
+
"another workflow, repoint it: ia portal set-agent-workflow");
|
|
281
|
+
}
|
|
282
|
+
if (!res.ok)
|
|
283
|
+
throw new Error(`n8n API ${res.status} reading workflow ${workflowId}`);
|
|
284
|
+
return res.json();
|
|
285
|
+
}
|
|
286
|
+
function pickAgent(slug, agents, wanted) {
|
|
287
|
+
if (wanted) {
|
|
288
|
+
const found = agents.find((a) => a.slug === wanted);
|
|
289
|
+
if (!found) {
|
|
290
|
+
throw new Error(`no agent "${wanted}" under ${slug} — registered: ${agents.map((a) => a.slug).join(", ") || "none"}`);
|
|
291
|
+
}
|
|
292
|
+
if (found.status === "retired") {
|
|
293
|
+
throw new Error(`${slug}/${wanted} is retired — a retired agent does not record`);
|
|
294
|
+
}
|
|
295
|
+
return found;
|
|
296
|
+
}
|
|
297
|
+
const active = agents.filter((a) => a.status === "active");
|
|
298
|
+
if (active.length === 0) {
|
|
299
|
+
throw new Error(`${slug} has no active agent in the portal — register the triage workflow first: ` +
|
|
300
|
+
`ia portal create-agent --slug ${slug} --agent <agentSlug> --workflow <n8nId> …`);
|
|
301
|
+
}
|
|
302
|
+
if (active.length > 1) {
|
|
303
|
+
throw new Error(`${slug} has ${active.length} active agents — pass --agent with one of: ` +
|
|
304
|
+
active.map((a) => a.slug).join(", "));
|
|
305
|
+
}
|
|
306
|
+
return active[0];
|
|
307
|
+
}
|
|
308
|
+
function editorUrl(apiBaseUrl, workflowId) {
|
|
309
|
+
return `${apiBaseUrl.replace(/\/api\/v\d+$/, "")}/workflow/${workflowId}`;
|
|
310
|
+
}
|
|
311
|
+
export async function triageEnable(slug, options = {}) {
|
|
312
|
+
if (options.provider && options.provider !== "gmail" && options.provider !== "outlook") {
|
|
313
|
+
throw new Error("--provider must be gmail or outlook");
|
|
314
|
+
}
|
|
315
|
+
const portalOptions = {
|
|
316
|
+
...options.portal,
|
|
317
|
+
...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
|
|
318
|
+
};
|
|
319
|
+
const workspaceDir = options.workspaceDir ?? ".";
|
|
320
|
+
// Fail on a missing n8n key before any portal call.
|
|
321
|
+
const { baseUrl: n8nBase } = n8nAuth(options);
|
|
322
|
+
// 1. The agent.
|
|
323
|
+
const { agents } = await portalListAgents({ slug }, portalOptions);
|
|
324
|
+
const agent = pickAgent(slug, agents, options.agent);
|
|
325
|
+
const label = `${slug}/${agent.slug}`;
|
|
326
|
+
// 2. The live check (read-only), then the provider.
|
|
327
|
+
const workflow = await fetchWorkflow(agent.workflowId, label, options);
|
|
328
|
+
let provider = options.provider ?? null;
|
|
329
|
+
let providerSource = "flag";
|
|
330
|
+
if (!provider) {
|
|
331
|
+
provider = await detectRepoProvider(workspaceDir, slug);
|
|
332
|
+
providerSource = "repo";
|
|
333
|
+
}
|
|
334
|
+
if (!provider && agent.triageProvider) {
|
|
335
|
+
provider = agent.triageProvider;
|
|
336
|
+
providerSource = "portal";
|
|
337
|
+
}
|
|
338
|
+
if (!provider) {
|
|
339
|
+
provider = detectWorkflowProvider(pickVersion(workflow).nodes);
|
|
340
|
+
providerSource = "workflow";
|
|
341
|
+
}
|
|
342
|
+
if (!provider) {
|
|
343
|
+
throw new Error(`cannot tell whether ${label} reads Gmail or Outlook — pass --provider gmail|outlook`);
|
|
344
|
+
}
|
|
345
|
+
if (agent.triageProvider && agent.triageProvider !== provider) {
|
|
346
|
+
throw new Error(`${label} is already an ${agent.triageProvider} triage agent, but the ${providerSource === "flag" ? "--provider flag" : "workflow"} ` +
|
|
347
|
+
`says ${provider}. If the mailbox really changed, clear it first: ` +
|
|
348
|
+
`ia portal set-agent-triage --slug ${slug} --agent ${agent.slug} --provider none`);
|
|
349
|
+
}
|
|
350
|
+
const portalUrl = options.portal?.baseUrl ?? process.env[PORTAL_URL_ENV] ?? DEFAULT_PORTAL_URL;
|
|
351
|
+
const wiring = checkTriageRecordWiring(workflow, { portalUrl, provider });
|
|
352
|
+
const workflowUrl = editorUrl(n8nBase, agent.workflowId);
|
|
353
|
+
const result = {
|
|
354
|
+
slug,
|
|
355
|
+
agent: agent.slug,
|
|
356
|
+
workflowId: agent.workflowId,
|
|
357
|
+
provider,
|
|
358
|
+
providerSource,
|
|
359
|
+
workflowUrl,
|
|
360
|
+
wiring,
|
|
361
|
+
marked: false,
|
|
362
|
+
backfill: null,
|
|
363
|
+
dryRun: options.dryRun === true,
|
|
364
|
+
ok: wiring.ok,
|
|
365
|
+
nextSteps: [],
|
|
366
|
+
};
|
|
367
|
+
if (!wiring.ok) {
|
|
368
|
+
result.nextSteps = [
|
|
369
|
+
`fix the failed check(s) in ${workflowUrl}, save, then run ia triage enable ${slug} again`,
|
|
370
|
+
];
|
|
371
|
+
return result;
|
|
372
|
+
}
|
|
373
|
+
if (options.dryRun) {
|
|
374
|
+
result.nextSteps = [`every check passed — run it again without --dry-run to mark ${label}`];
|
|
375
|
+
return result;
|
|
376
|
+
}
|
|
377
|
+
// 3. The mark — idempotent on the portal side.
|
|
378
|
+
await portalSetAgentTriage({ slug, agent: agent.slug, provider }, portalOptions);
|
|
379
|
+
result.marked = true;
|
|
380
|
+
// 4. The backfill from the old record sheet, when there is one.
|
|
381
|
+
if (options.backfill === false) {
|
|
382
|
+
result.backfill = { notRun: "--no-backfill: the record sheet was not copied" };
|
|
383
|
+
}
|
|
384
|
+
else {
|
|
385
|
+
const hasSheet = options.csv !== undefined ||
|
|
386
|
+
options.sheetId !== undefined ||
|
|
387
|
+
(await resolveRecordSheetId(workspaceDir, slug)) !== undefined;
|
|
388
|
+
if (!hasSheet) {
|
|
389
|
+
result.backfill = { notRun: "no record sheet for this client — nothing to backfill" };
|
|
390
|
+
}
|
|
391
|
+
else {
|
|
392
|
+
try {
|
|
393
|
+
result.backfill = await triageBackfill(slug, {
|
|
394
|
+
agent: agent.slug,
|
|
395
|
+
csv: options.csv,
|
|
396
|
+
sheetId: options.sheetId,
|
|
397
|
+
workspaceDir,
|
|
398
|
+
serviceAccountKey: options.serviceAccountKey,
|
|
399
|
+
now: options.now,
|
|
400
|
+
portal: options.portal,
|
|
401
|
+
fetchImpl: options.fetchImpl,
|
|
402
|
+
});
|
|
403
|
+
}
|
|
404
|
+
catch (error) {
|
|
405
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
406
|
+
result.ok = false;
|
|
407
|
+
result.failure =
|
|
408
|
+
`${label} is marked as a ${provider} triage agent, but the backfill failed: ${message}. ` +
|
|
409
|
+
`The mark stands — fix the sheet source, then run: ia triage backfill ${slug}` +
|
|
410
|
+
(options.csv
|
|
411
|
+
? ` --csv ${options.csv}`
|
|
412
|
+
: options.sheetId
|
|
413
|
+
? ` --sheet ${options.sheetId}`
|
|
414
|
+
: "");
|
|
415
|
+
}
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
const published = wiring.version === "published";
|
|
419
|
+
result.nextSteps = [
|
|
420
|
+
published
|
|
421
|
+
? `the workflow is already published (${workflowUrl}) — ${wiring.draftDiffers ? "the saved draft differs from it: publish it only once you mean to" : "the next execution records to the portal"}`
|
|
422
|
+
: `publish the workflow: ${workflowUrl}`,
|
|
423
|
+
"open the FIRST execution after that and check ONLY the 📊 Record to Portal output: " +
|
|
424
|
+
"HTTP 200 with inserted ≥ 1. Do not open the ⚙️ Stage or trigger nodes — they hold email bodies",
|
|
425
|
+
`the next day: ia triage health ${slug} (the portal's 13:00 UTC watch also alerts #team-techs after 24h with no row)`,
|
|
426
|
+
];
|
|
427
|
+
return result;
|
|
428
|
+
}
|