@installagent/sdk 0.8.0 → 0.9.1
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/index.d.ts +2 -1
- package/dist/index.js +2 -1
- package/dist/portal-admin.d.ts +26 -0
- package/dist/portal-admin.js +24 -0
- package/dist/portal-sync-builds.d.ts +157 -0
- package/dist/portal-sync-builds.js +424 -0
- package/dist/template-sync.js +8 -0
- package/package.json +1 -1
- package/templates/workspace-root/AGENT.md +2 -0
- package/templates/workspace-root/AGENTS.md +10 -8
- package/templates/workspace-root/GEMINI.md +9 -21
- package/templates/workspace-root/ONBOARDING.md +3 -1
- package/templates/workspace-root/skills/CLAUDE.md +1 -1
- package/templates/workspace-root/skills/README.md +12 -4
- package/templates/workspace-root/skills/client-facing-docs/SKILL.md +3 -0
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +8 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +8 -1
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +32 -5
package/dist/index.d.ts
CHANGED
|
@@ -38,7 +38,8 @@ export { opInstallCommand, opInstallFix, opIntegrationFix } from "./op-cli.js";
|
|
|
38
38
|
export { defaultOpTitle, type MintImpls, type MintToOpOptions, type MintToOpRequest, type MintToOpResult, mintToOnePassword, } from "./op-store.js";
|
|
39
39
|
export { type PingResult, ping } from "./ping.js";
|
|
40
40
|
export { detectPlatform, detectPlatformInfo, detectShell, opNeedsAnotherShell, type Platform, type PlatformInfo, type Shell, } from "./platform.js";
|
|
41
|
-
export { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_BUILD_TYPES, PORTAL_PASSWORD_WARNING, PORTAL_SYNC_MAX_DAYS, PORTAL_URL_ENV, type PortalAddUserInput, type PortalAddUserResult, PortalAdminAuthError, type PortalAdminOptions, type PortalAgent, type PortalAgentSyncRow, type PortalBuild, type PortalBuildType, type PortalCreateAgentInput, type PortalCreateBuildInput, type PortalCreateOrgInput, type PortalCreateOrgResult, type PortalListAgentsResult, type PortalListBuildsResult, type PortalListOrgsResult, type PortalOrg, type PortalOrgUser, PortalRequestError, type PortalSetAgentNameInput, type PortalSetAgentNameResult, type PortalSetAgentStatusInput, type PortalSetAgentStatusResult, type PortalSetAgentTriageResult, type PortalSetAgentWorkflowInput, type PortalSetAgentWorkflowResult, type PortalSetBuildStatusInput, type PortalSetDriveFolderResult, type PortalSetPasswordResult, type PortalSetUserInput, type PortalSetUserResult, type PortalSyncRunsResult, type PortalTriageBackfillResult, type PortalTriageProvider, type PortalTriageRecordsPage, portalAddUser, portalBackfillTriageRecords, portalBuildType, portalBuildWorkflowId, portalCreateAgent, portalCreateBuild, portalCreateOrg, portalListAgents, portalListBuilds, portalListOrgs, portalReadTriageRecords, portalSetAgentName, portalSetAgentStatus, portalSetAgentTriage, portalSetAgentWorkflow, portalSetBuildName, portalSetBuildStatus, portalSetBuildTriage, portalSetBuildWorkflow, portalSetDriveFolder, portalSetOrgSlackChannel, portalSetPassword, portalSetUser, portalSyncRuns, validatePortalBuildFields, } from "./portal-admin.js";
|
|
41
|
+
export { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_BUILD_TYPES, PORTAL_PASSWORD_WARNING, PORTAL_SYNC_MAX_DAYS, PORTAL_URL_ENV, type PortalAddUserInput, type PortalAddUserResult, PortalAdminAuthError, type PortalAdminOptions, type PortalAgent, type PortalAgentSyncRow, type PortalBuild, type PortalBuildType, type PortalCreateAgentInput, type PortalCreateBuildInput, type PortalCreateOrgInput, type PortalCreateOrgResult, type PortalListAgentsResult, type PortalListBuildsResult, type PortalListOrgsResult, type PortalOrg, type PortalOrgUser, PortalRequestError, type PortalSetAgentNameInput, type PortalSetAgentNameResult, type PortalSetAgentStatusInput, type PortalSetAgentStatusResult, type PortalSetAgentTriageResult, type PortalSetAgentWorkflowInput, type PortalSetAgentWorkflowResult, type PortalSetBuildDetailsInput, type PortalSetBuildDetailsResult, type PortalSetBuildStatusInput, type PortalSetDriveFolderResult, type PortalSetPasswordResult, type PortalSetUserInput, type PortalSetUserResult, type PortalSyncRunsResult, type PortalTriageBackfillResult, type PortalTriageProvider, type PortalTriageRecordsPage, portalAddUser, portalBackfillTriageRecords, portalBuildType, portalBuildWorkflowId, portalCreateAgent, portalCreateBuild, portalCreateOrg, portalListAgents, portalListBuilds, portalListOrgs, portalReadTriageRecords, portalSetAgentName, portalSetAgentStatus, portalSetAgentTriage, portalSetAgentWorkflow, portalSetBuildDetails, portalSetBuildName, portalSetBuildStatus, portalSetBuildTriage, portalSetBuildWorkflow, portalSetDriveFolder, portalSetOrgSlackChannel, portalSetPassword, portalSetUser, portalSyncRuns, validatePortalBuildFields, } from "./portal-admin.js";
|
|
42
|
+
export { BUILD_DESCRIPTION_MAX, BUILD_NAME_MAX, BUILDS_MANIFEST_END, BUILDS_MANIFEST_START, type BuildsManifest, type BuildsManifestSource, type BuildsManifestState, type BuildsSyncAction, type BuildsSyncActionResult, type BuildsSyncOptions, type BuildsSyncOrgResult, type BuildsSyncPlan, type BuildsSyncResult, type ManifestBuild, type ManifestBuildStatus, parseBuildsManifest, planBuildsSync, type RemoteClientMdReader, syncBuilds, } from "./portal-sync-builds.js";
|
|
42
43
|
export { expectedGithubAccount, type PrOpenOptions, type PrOpenResult, parseGithubRemote, prOpen, } from "./pr-open.js";
|
|
43
44
|
export { type StandupCallPrep, type StandupCallPrepStatus, type StandupGitState, type StandupIssueRef, type StandupLinear, type StandupOptions, type StandupRepo, type StandupRepoLint, type StandupResult, type StandupStaleTodo, standup, } from "./standup.js";
|
|
44
45
|
export { type SyncRepoResult, type SyncRepoStatus, type SyncReposOptions, type SyncReposResult, syncRepos, workspaceRepoNames, } from "./sync-repos.js";
|
package/dist/index.js
CHANGED
|
@@ -41,7 +41,8 @@ export { opInstallCommand, opInstallFix, opIntegrationFix } from "./op-cli.js";
|
|
|
41
41
|
export { defaultOpTitle, mintToOnePassword, } from "./op-store.js";
|
|
42
42
|
export { ping } from "./ping.js";
|
|
43
43
|
export { detectPlatform, detectPlatformInfo, detectShell, opNeedsAnotherShell, } from "./platform.js";
|
|
44
|
-
export { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_BUILD_TYPES, PORTAL_PASSWORD_WARNING, PORTAL_SYNC_MAX_DAYS, PORTAL_URL_ENV, PortalAdminAuthError, PortalRequestError, portalAddUser, portalBackfillTriageRecords, portalBuildType, portalBuildWorkflowId, portalCreateAgent, portalCreateBuild, portalCreateOrg, portalListAgents, portalListBuilds, portalListOrgs, portalReadTriageRecords, portalSetAgentName, portalSetAgentStatus, portalSetAgentTriage, portalSetAgentWorkflow, portalSetBuildName, portalSetBuildStatus, portalSetBuildTriage, portalSetBuildWorkflow, portalSetDriveFolder, portalSetOrgSlackChannel, portalSetPassword, portalSetUser, portalSyncRuns, validatePortalBuildFields, } from "./portal-admin.js";
|
|
44
|
+
export { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_BUILD_TYPES, PORTAL_PASSWORD_WARNING, PORTAL_SYNC_MAX_DAYS, PORTAL_URL_ENV, PortalAdminAuthError, PortalRequestError, portalAddUser, portalBackfillTriageRecords, portalBuildType, portalBuildWorkflowId, portalCreateAgent, portalCreateBuild, portalCreateOrg, portalListAgents, portalListBuilds, portalListOrgs, portalReadTriageRecords, portalSetAgentName, portalSetAgentStatus, portalSetAgentTriage, portalSetAgentWorkflow, portalSetBuildDetails, portalSetBuildName, portalSetBuildStatus, portalSetBuildTriage, portalSetBuildWorkflow, portalSetDriveFolder, portalSetOrgSlackChannel, portalSetPassword, portalSetUser, portalSyncRuns, validatePortalBuildFields, } from "./portal-admin.js";
|
|
45
|
+
export { BUILD_DESCRIPTION_MAX, BUILD_NAME_MAX, BUILDS_MANIFEST_END, BUILDS_MANIFEST_START, parseBuildsManifest, planBuildsSync, syncBuilds, } from "./portal-sync-builds.js";
|
|
45
46
|
export { expectedGithubAccount, parseGithubRemote, prOpen, } from "./pr-open.js";
|
|
46
47
|
export { standup, } from "./standup.js";
|
|
47
48
|
export { syncRepos, workspaceRepoNames, } from "./sync-repos.js";
|
package/dist/portal-admin.d.ts
CHANGED
|
@@ -265,6 +265,32 @@ export declare function portalSetBuildName(input: {
|
|
|
265
265
|
}, options?: PortalAdminOptions): Promise<PortalSetAgentNameResult>;
|
|
266
266
|
/** Old name of `portalSetBuildName`. */
|
|
267
267
|
export declare function portalSetAgentName(input: PortalSetAgentNameInput, options?: PortalAdminOptions): Promise<PortalSetAgentNameResult>;
|
|
268
|
+
export interface PortalSetBuildDetailsInput {
|
|
269
|
+
slug: string;
|
|
270
|
+
build: string;
|
|
271
|
+
/** Omit to leave as is. */
|
|
272
|
+
description?: string;
|
|
273
|
+
/** Omit to leave as is; null clears the Open link. https only. */
|
|
274
|
+
url?: string | null;
|
|
275
|
+
}
|
|
276
|
+
export interface PortalSetBuildDetailsResult {
|
|
277
|
+
org: string;
|
|
278
|
+
agent: string;
|
|
279
|
+
previous: {
|
|
280
|
+
description: string;
|
|
281
|
+
url: string | null;
|
|
282
|
+
};
|
|
283
|
+
description: string;
|
|
284
|
+
url: string | null;
|
|
285
|
+
/** False when nothing differed — the call is idempotent. */
|
|
286
|
+
changed: boolean;
|
|
287
|
+
}
|
|
288
|
+
/**
|
|
289
|
+
* Change the card text under a build's name: its description and/or its url
|
|
290
|
+
* (an app's Open link). Before this route (team-web, 2026-10-31) only the
|
|
291
|
+
* create could set either. A portal without the route answers 404.
|
|
292
|
+
*/
|
|
293
|
+
export declare function portalSetBuildDetails(input: PortalSetBuildDetailsInput, options?: PortalAdminOptions): Promise<PortalSetBuildDetailsResult>;
|
|
268
294
|
/**
|
|
269
295
|
* Repoint an agent build at a different n8n workflow — for a version bump (v2
|
|
270
296
|
* replacing a retired v1), which is the same agent from the client's side.
|
package/dist/portal-admin.js
CHANGED
|
@@ -239,6 +239,30 @@ export async function portalSetBuildName(input, options = {}) {
|
|
|
239
239
|
export async function portalSetAgentName(input, options = {}) {
|
|
240
240
|
return portalSetBuildName({ slug: input.slug, build: input.agent, name: input.name }, options);
|
|
241
241
|
}
|
|
242
|
+
/**
|
|
243
|
+
* Change the card text under a build's name: its description and/or its url
|
|
244
|
+
* (an app's Open link). Before this route (team-web, 2026-10-31) only the
|
|
245
|
+
* create could set either. A portal without the route answers 404.
|
|
246
|
+
*/
|
|
247
|
+
export async function portalSetBuildDetails(input, options = {}) {
|
|
248
|
+
const slug = normalizeSlug(input.slug, "org");
|
|
249
|
+
const build = normalizeSlug(input.build, "build");
|
|
250
|
+
const description = input.description?.trim();
|
|
251
|
+
if (input.description !== undefined && !description)
|
|
252
|
+
throw new Error("description is empty");
|
|
253
|
+
const url = input.url === null ? null : input.url?.trim();
|
|
254
|
+
if (url && !isHttpsUrl(url))
|
|
255
|
+
throw new Error(`url must be an https:// address (got "${url}")`);
|
|
256
|
+
if (description === undefined && url === undefined) {
|
|
257
|
+
throw new Error("give a description and/or a url to change");
|
|
258
|
+
}
|
|
259
|
+
return portalRequest("POST", `${BUILDS_PATH}/details`, options, {
|
|
260
|
+
slug,
|
|
261
|
+
agent: build,
|
|
262
|
+
...(description !== undefined ? { description } : {}),
|
|
263
|
+
...(url !== undefined ? { url: url || null } : {}),
|
|
264
|
+
});
|
|
265
|
+
}
|
|
242
266
|
/**
|
|
243
267
|
* Repoint an agent build at a different n8n workflow — for a version bump (v2
|
|
244
268
|
* replacing a retired v1), which is the same agent from the client's side.
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
import type { ExecFileFn } from "./exec.js";
|
|
2
|
+
import { type PortalAdminOptions, type PortalBuild, type PortalTriageProvider } from "./portal-admin.js";
|
|
3
|
+
export declare const BUILDS_MANIFEST_START = "<!-- BUILDS:START -->";
|
|
4
|
+
export declare const BUILDS_MANIFEST_END = "<!-- BUILDS:END -->";
|
|
5
|
+
export declare const BUILD_NAME_MAX = 120;
|
|
6
|
+
export declare const BUILD_DESCRIPTION_MAX = 140;
|
|
7
|
+
declare const STATUSES: readonly ["active", "paused", "retired"];
|
|
8
|
+
export type ManifestBuildStatus = (typeof STATUSES)[number];
|
|
9
|
+
export interface ManifestBuild {
|
|
10
|
+
/** The build slug (the portal's `agent` field); never changes once registered. */
|
|
11
|
+
build: string;
|
|
12
|
+
type: "agent" | "app";
|
|
13
|
+
name: string;
|
|
14
|
+
description: string;
|
|
15
|
+
/** The n8n workflow id; agents only. */
|
|
16
|
+
workflowId: string | null;
|
|
17
|
+
/** The Open link; apps only, https or null. */
|
|
18
|
+
url: string | null;
|
|
19
|
+
status: ManifestBuildStatus;
|
|
20
|
+
/** Absent = not managed here; null = explicitly not a triage agent. */
|
|
21
|
+
triage?: PortalTriageProvider | null;
|
|
22
|
+
}
|
|
23
|
+
export type BuildsManifestState =
|
|
24
|
+
/** No markers: the repo predates the manifest. Skipped. */
|
|
25
|
+
"missing"
|
|
26
|
+
/** The template's REPLACE_WITH_* placeholder is still there. Skipped. */
|
|
27
|
+
| "placeholder"
|
|
28
|
+
/** Parsed and every row is valid. */
|
|
29
|
+
| "ok"
|
|
30
|
+
/** At least one error: the org is not synced until it is fixed. */
|
|
31
|
+
| "invalid";
|
|
32
|
+
export interface BuildsManifest {
|
|
33
|
+
state: BuildsManifestState;
|
|
34
|
+
rows: ManifestBuild[];
|
|
35
|
+
errors: string[];
|
|
36
|
+
}
|
|
37
|
+
/** Reads and validates the `## Builds` block of a CLIENT.md. Pure. */
|
|
38
|
+
export declare function parseBuildsManifest(clientMd: string): BuildsManifest;
|
|
39
|
+
export type BuildsSyncAction = {
|
|
40
|
+
kind: "create";
|
|
41
|
+
build: string;
|
|
42
|
+
type: "agent" | "app";
|
|
43
|
+
name: string;
|
|
44
|
+
description: string;
|
|
45
|
+
workflowId: string | null;
|
|
46
|
+
url: string | null;
|
|
47
|
+
status: ManifestBuildStatus;
|
|
48
|
+
triage: PortalTriageProvider | null;
|
|
49
|
+
} | {
|
|
50
|
+
kind: "repoint";
|
|
51
|
+
build: string;
|
|
52
|
+
from: string | null;
|
|
53
|
+
to: string;
|
|
54
|
+
} | {
|
|
55
|
+
kind: "rename";
|
|
56
|
+
build: string;
|
|
57
|
+
from: string;
|
|
58
|
+
to: string;
|
|
59
|
+
} | {
|
|
60
|
+
kind: "details";
|
|
61
|
+
build: string;
|
|
62
|
+
description?: {
|
|
63
|
+
from: string;
|
|
64
|
+
to: string;
|
|
65
|
+
};
|
|
66
|
+
url?: {
|
|
67
|
+
from: string | null;
|
|
68
|
+
to: string | null;
|
|
69
|
+
};
|
|
70
|
+
} | {
|
|
71
|
+
kind: "status";
|
|
72
|
+
build: string;
|
|
73
|
+
from: string;
|
|
74
|
+
to: ManifestBuildStatus;
|
|
75
|
+
} | {
|
|
76
|
+
kind: "triage";
|
|
77
|
+
build: string;
|
|
78
|
+
from: PortalTriageProvider | null;
|
|
79
|
+
to: PortalTriageProvider | null;
|
|
80
|
+
};
|
|
81
|
+
export interface BuildsSyncPlan {
|
|
82
|
+
/** In the order apply runs them. */
|
|
83
|
+
actions: BuildsSyncAction[];
|
|
84
|
+
/** Registry builds of this org the manifest does not name. Never changed. */
|
|
85
|
+
registryOnly: {
|
|
86
|
+
build: string;
|
|
87
|
+
type: "agent" | "app";
|
|
88
|
+
name: string;
|
|
89
|
+
status: string;
|
|
90
|
+
}[];
|
|
91
|
+
/** Manifest rows that cannot be synced as written. Nothing is done for them. */
|
|
92
|
+
conflicts: string[];
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Plans one org. Pure: `registry` is every build in the registry (all orgs),
|
|
96
|
+
* because an n8n workflow id is unique across the whole registry.
|
|
97
|
+
*
|
|
98
|
+
* Match rule: an agent matches by workflow id; an app by its build slug. An
|
|
99
|
+
* agent row whose workflow id is new but whose slug is a registered agent is a
|
|
100
|
+
* REPOINT (a v2 keeps the card), never a second card.
|
|
101
|
+
*/
|
|
102
|
+
export declare function planBuildsSync(org: string, manifest: ManifestBuild[], registry: PortalBuild[]): BuildsSyncPlan;
|
|
103
|
+
export type BuildsManifestSource = "workspace" | "github" | "none";
|
|
104
|
+
export interface BuildsSyncActionResult {
|
|
105
|
+
action: BuildsSyncAction;
|
|
106
|
+
/** Set only with apply: "done", or the error the portal gave. */
|
|
107
|
+
outcome?: "done" | {
|
|
108
|
+
error: string;
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
export interface BuildsSyncOrgResult {
|
|
112
|
+
org: string;
|
|
113
|
+
/** Where CLIENT.md was read from; "none" = no repo found. */
|
|
114
|
+
source: BuildsManifestSource;
|
|
115
|
+
manifest: BuildsManifestState | "no-repo";
|
|
116
|
+
errors: string[];
|
|
117
|
+
actions: BuildsSyncActionResult[];
|
|
118
|
+
registryOnly: BuildsSyncPlan["registryOnly"];
|
|
119
|
+
conflicts: string[];
|
|
120
|
+
}
|
|
121
|
+
export interface BuildsSyncResult {
|
|
122
|
+
applied: boolean;
|
|
123
|
+
orgs: BuildsSyncOrgResult[];
|
|
124
|
+
/** Orgs left out on purpose (Install Agent's own). */
|
|
125
|
+
skippedOrgs: string[];
|
|
126
|
+
/** Actions planned (dry run) or attempted (apply), across all orgs. */
|
|
127
|
+
actionCount: number;
|
|
128
|
+
/** Apply only: actions the portal refused. */
|
|
129
|
+
failedCount: number;
|
|
130
|
+
}
|
|
131
|
+
/** Reads `clients/client-<slug>/CLIENT.md` from GitHub when the repo is not cloned. Null = not there. */
|
|
132
|
+
export type RemoteClientMdReader = (slug: string) => Promise<string | null>;
|
|
133
|
+
export interface BuildsSyncOptions {
|
|
134
|
+
/** The installagent/ workspace root (the dir that contains clients/). */
|
|
135
|
+
workspaceDir: string;
|
|
136
|
+
/** One org only. */
|
|
137
|
+
slug?: string;
|
|
138
|
+
/** Write to the portal. Default false: plan and report only. */
|
|
139
|
+
apply?: boolean;
|
|
140
|
+
/** Portal admin options (secret, base URL, fetch). */
|
|
141
|
+
portal?: PortalAdminOptions;
|
|
142
|
+
/** Fallback for an org with no local repo; defaults to the GitHub contents API. */
|
|
143
|
+
readRemoteClientMd?: RemoteClientMdReader;
|
|
144
|
+
/** GitHub token for the default fallback; defaults to $GITHUB_API_TOKEN, then `gh auth token`. */
|
|
145
|
+
githubToken?: string;
|
|
146
|
+
execFileImpl?: ExecFileFn;
|
|
147
|
+
githubFetchImpl?: typeof fetch;
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* Compares every client repo's `## Builds` manifest with the portal's builds
|
|
151
|
+
* registry and, with `apply`, moves the registry to match: create, rename,
|
|
152
|
+
* description/url, status, triage, repoint. Never deletes, never touches
|
|
153
|
+
* Install Agent's own org, never writes a client repo. A second run after an
|
|
154
|
+
* apply plans nothing.
|
|
155
|
+
*/
|
|
156
|
+
export declare function syncBuilds(options: BuildsSyncOptions): Promise<BuildsSyncResult>;
|
|
157
|
+
export {};
|
|
@@ -0,0 +1,424 @@
|
|
|
1
|
+
import { existsSync } from "node:fs";
|
|
2
|
+
import { readdir, readFile } from "node:fs/promises";
|
|
3
|
+
import { join, resolve } from "node:path";
|
|
4
|
+
import { GITHUB_TOKEN_FIX, resolveGithubToken } from "./github-token.js";
|
|
5
|
+
import { portalBuildType, portalBuildWorkflowId, portalCreateBuild, portalListBuilds, portalListOrgs, portalSetBuildDetails, portalSetBuildName, portalSetBuildStatus, portalSetBuildTriage, portalSetBuildWorkflow, } from "./portal-admin.js";
|
|
6
|
+
// ─── The manifest: the `## Builds` block of a client repo's CLIENT.md ───────
|
|
7
|
+
//
|
|
8
|
+
// One fenced JSON array between these two markers. The client repo is the
|
|
9
|
+
// source of truth for which builds a client sees on the portal; this module
|
|
10
|
+
// reads it, compares it with the portal's builds registry, and (with apply)
|
|
11
|
+
// moves the registry to match. It never deletes: a registry build the
|
|
12
|
+
// manifest does not name is reported, not changed.
|
|
13
|
+
//
|
|
14
|
+
// The validator below has a twin in client-template (`ci/builds-manifest.mjs`,
|
|
15
|
+
// repo-lint rule 11). The repos never import each other, so a rule change
|
|
16
|
+
// lands in both files in the same piece of work.
|
|
17
|
+
export const BUILDS_MANIFEST_START = "<!-- BUILDS:START -->";
|
|
18
|
+
export const BUILDS_MANIFEST_END = "<!-- BUILDS:END -->";
|
|
19
|
+
export const BUILD_NAME_MAX = 120;
|
|
20
|
+
export const BUILD_DESCRIPTION_MAX = 140;
|
|
21
|
+
const BUILD_SLUG = /^[a-z0-9][a-z0-9-]*$/;
|
|
22
|
+
const STATUSES = ["active", "paused", "retired"];
|
|
23
|
+
const ROW_KEYS = new Set([
|
|
24
|
+
"build",
|
|
25
|
+
"type",
|
|
26
|
+
"name",
|
|
27
|
+
"description",
|
|
28
|
+
"workflow_id",
|
|
29
|
+
"url",
|
|
30
|
+
"status",
|
|
31
|
+
"triage",
|
|
32
|
+
]);
|
|
33
|
+
function isHttps(value) {
|
|
34
|
+
try {
|
|
35
|
+
return new URL(value).protocol === "https:" && value.startsWith("https://");
|
|
36
|
+
}
|
|
37
|
+
catch {
|
|
38
|
+
return false;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
/** Validates one parsed row; pushes its errors (prefixed with its place) and returns it when valid. */
|
|
42
|
+
function readRow(raw, index, errors) {
|
|
43
|
+
const where = `row ${index + 1}`;
|
|
44
|
+
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
|
|
45
|
+
errors.push(`${where}: must be an object`);
|
|
46
|
+
return null;
|
|
47
|
+
}
|
|
48
|
+
const row = raw;
|
|
49
|
+
const label = typeof row.build === "string" && row.build ? `${where} (${row.build})` : where;
|
|
50
|
+
const before = errors.length;
|
|
51
|
+
const fail = (message) => errors.push(`${label}: ${message}`);
|
|
52
|
+
for (const key of Object.keys(row))
|
|
53
|
+
if (!ROW_KEYS.has(key))
|
|
54
|
+
fail(`unknown field "${key}"`);
|
|
55
|
+
if (typeof row.build !== "string" || !BUILD_SLUG.test(row.build))
|
|
56
|
+
fail("build must be a kebab-case slug");
|
|
57
|
+
if (row.type !== "agent" && row.type !== "app")
|
|
58
|
+
fail("type must be agent|app");
|
|
59
|
+
const name = typeof row.name === "string" ? row.name.trim() : "";
|
|
60
|
+
if (!name)
|
|
61
|
+
fail("name required");
|
|
62
|
+
else if (name.length > BUILD_NAME_MAX)
|
|
63
|
+
fail(`name must be ${BUILD_NAME_MAX} characters or fewer`);
|
|
64
|
+
else if (/\bINS-\d+\b/i.test(name) || /\bn8n\b/i.test(name))
|
|
65
|
+
fail("name is client-facing: no ticket numbers, no tool names");
|
|
66
|
+
const description = typeof row.description === "string" ? row.description.trim() : "";
|
|
67
|
+
if (!description)
|
|
68
|
+
fail("description required");
|
|
69
|
+
else if (description.length > BUILD_DESCRIPTION_MAX)
|
|
70
|
+
fail(`description must be ${BUILD_DESCRIPTION_MAX} characters or fewer`);
|
|
71
|
+
const workflowId = typeof row.workflow_id === "string" && row.workflow_id.trim() ? row.workflow_id.trim() : null;
|
|
72
|
+
if (row.workflow_id !== undefined && row.workflow_id !== null && workflowId === null)
|
|
73
|
+
fail("workflow_id must be a non-empty string");
|
|
74
|
+
const url = typeof row.url === "string" && row.url.trim() ? row.url.trim() : null;
|
|
75
|
+
if (row.url !== undefined && row.url !== null && typeof row.url !== "string")
|
|
76
|
+
fail("url must be a string or null");
|
|
77
|
+
if (url && !isHttps(url))
|
|
78
|
+
fail("url must be a full https:// address");
|
|
79
|
+
if (row.type === "agent") {
|
|
80
|
+
if (!workflowId)
|
|
81
|
+
fail("an agent needs its workflow_id");
|
|
82
|
+
if (url)
|
|
83
|
+
fail("an agent has no url (only an app has an Open link)");
|
|
84
|
+
}
|
|
85
|
+
if (row.type === "app") {
|
|
86
|
+
if (workflowId)
|
|
87
|
+
fail("an app has no workflow_id");
|
|
88
|
+
if (row.triage !== undefined && row.triage !== null)
|
|
89
|
+
fail("an app cannot be a triage agent");
|
|
90
|
+
}
|
|
91
|
+
if (!STATUSES.includes(row.status))
|
|
92
|
+
fail(`status must be ${STATUSES.join("|")}`);
|
|
93
|
+
if (row.triage !== undefined &&
|
|
94
|
+
row.triage !== null &&
|
|
95
|
+
row.triage !== "gmail" &&
|
|
96
|
+
row.triage !== "outlook")
|
|
97
|
+
fail("triage must be gmail|outlook (or null)");
|
|
98
|
+
if (errors.length > before)
|
|
99
|
+
return null;
|
|
100
|
+
return {
|
|
101
|
+
build: row.build,
|
|
102
|
+
type: row.type,
|
|
103
|
+
name,
|
|
104
|
+
description,
|
|
105
|
+
workflowId,
|
|
106
|
+
url,
|
|
107
|
+
status: row.status,
|
|
108
|
+
...(row.triage !== undefined ? { triage: row.triage } : {}),
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
/** Reads and validates the `## Builds` block of a CLIENT.md. Pure. */
|
|
112
|
+
export function parseBuildsManifest(clientMd) {
|
|
113
|
+
const start = clientMd.indexOf(BUILDS_MANIFEST_START);
|
|
114
|
+
const end = clientMd.indexOf(BUILDS_MANIFEST_END);
|
|
115
|
+
if (start === -1 && end === -1)
|
|
116
|
+
return { state: "missing", rows: [], errors: [] };
|
|
117
|
+
if (start === -1 || end === -1 || end < start) {
|
|
118
|
+
return {
|
|
119
|
+
state: "invalid",
|
|
120
|
+
rows: [],
|
|
121
|
+
errors: [`need both ${BUILDS_MANIFEST_START} and ${BUILDS_MANIFEST_END}, in that order`],
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
const block = clientMd.slice(start + BUILDS_MANIFEST_START.length, end);
|
|
125
|
+
if (block.includes("REPLACE_WITH_"))
|
|
126
|
+
return { state: "placeholder", rows: [], errors: [] };
|
|
127
|
+
const fence = block.match(/```json\s*\n([\s\S]*?)\n\s*```/);
|
|
128
|
+
if (!fence) {
|
|
129
|
+
return { state: "invalid", rows: [], errors: ["the block needs one ```json fenced array"] };
|
|
130
|
+
}
|
|
131
|
+
let parsed;
|
|
132
|
+
try {
|
|
133
|
+
parsed = JSON.parse(fence[1]);
|
|
134
|
+
}
|
|
135
|
+
catch (error) {
|
|
136
|
+
return {
|
|
137
|
+
state: "invalid",
|
|
138
|
+
rows: [],
|
|
139
|
+
errors: [`the JSON does not parse: ${error instanceof Error ? error.message : error}`],
|
|
140
|
+
};
|
|
141
|
+
}
|
|
142
|
+
if (!Array.isArray(parsed)) {
|
|
143
|
+
return { state: "invalid", rows: [], errors: ["the JSON must be an array of builds"] };
|
|
144
|
+
}
|
|
145
|
+
const errors = [];
|
|
146
|
+
const rows = [];
|
|
147
|
+
parsed.forEach((raw, index) => {
|
|
148
|
+
const row = readRow(raw, index, errors);
|
|
149
|
+
if (row)
|
|
150
|
+
rows.push(row);
|
|
151
|
+
});
|
|
152
|
+
const seenSlugs = new Set();
|
|
153
|
+
const seenWorkflows = new Set();
|
|
154
|
+
for (const row of rows) {
|
|
155
|
+
if (seenSlugs.has(row.build))
|
|
156
|
+
errors.push(`build "${row.build}" is listed twice`);
|
|
157
|
+
seenSlugs.add(row.build);
|
|
158
|
+
if (row.workflowId) {
|
|
159
|
+
if (seenWorkflows.has(row.workflowId))
|
|
160
|
+
errors.push(`workflow_id ${row.workflowId} is listed twice`);
|
|
161
|
+
seenWorkflows.add(row.workflowId);
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
return errors.length > 0 ? { state: "invalid", rows: [], errors } : { state: "ok", rows, errors };
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Plans one org. Pure: `registry` is every build in the registry (all orgs),
|
|
168
|
+
* because an n8n workflow id is unique across the whole registry.
|
|
169
|
+
*
|
|
170
|
+
* Match rule: an agent matches by workflow id; an app by its build slug. An
|
|
171
|
+
* agent row whose workflow id is new but whose slug is a registered agent is a
|
|
172
|
+
* REPOINT (a v2 keeps the card), never a second card.
|
|
173
|
+
*/
|
|
174
|
+
export function planBuildsSync(org, manifest, registry) {
|
|
175
|
+
const orgBuilds = registry.filter((build) => build.org === org);
|
|
176
|
+
const matched = new Set();
|
|
177
|
+
const actions = [];
|
|
178
|
+
const followUps = [];
|
|
179
|
+
const conflicts = [];
|
|
180
|
+
for (const row of manifest) {
|
|
181
|
+
const bySlug = orgBuilds.find((build) => build.slug === row.build);
|
|
182
|
+
let current;
|
|
183
|
+
if (row.type === "agent" && row.workflowId) {
|
|
184
|
+
const holder = registry.find((build) => portalBuildWorkflowId(build) === row.workflowId);
|
|
185
|
+
if (holder && holder.org !== org) {
|
|
186
|
+
conflicts.push(`${row.build}: workflow ${row.workflowId} is registered to ${holder.org}/${holder.slug}`);
|
|
187
|
+
continue;
|
|
188
|
+
}
|
|
189
|
+
if (holder && holder.slug !== row.build) {
|
|
190
|
+
conflicts.push(`${row.build}: workflow ${row.workflowId} is registered here as "${holder.slug}" — ` +
|
|
191
|
+
"a build slug never changes, so use that slug in the manifest");
|
|
192
|
+
continue;
|
|
193
|
+
}
|
|
194
|
+
if (holder)
|
|
195
|
+
current = holder;
|
|
196
|
+
else if (bySlug && portalBuildType(bySlug) === "agent") {
|
|
197
|
+
current = bySlug;
|
|
198
|
+
actions.push({
|
|
199
|
+
kind: "repoint",
|
|
200
|
+
build: row.build,
|
|
201
|
+
from: portalBuildWorkflowId(bySlug),
|
|
202
|
+
to: row.workflowId,
|
|
203
|
+
});
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
else if (bySlug) {
|
|
207
|
+
current = bySlug;
|
|
208
|
+
}
|
|
209
|
+
if (bySlug && portalBuildType(bySlug) !== row.type) {
|
|
210
|
+
conflicts.push(`${row.build}: the manifest says ${row.type}, the portal has an ${portalBuildType(bySlug)} ` +
|
|
211
|
+
"with that slug — a build's type never changes, pick another slug");
|
|
212
|
+
continue;
|
|
213
|
+
}
|
|
214
|
+
if (!current) {
|
|
215
|
+
actions.push({
|
|
216
|
+
kind: "create",
|
|
217
|
+
build: row.build,
|
|
218
|
+
type: row.type,
|
|
219
|
+
name: row.name,
|
|
220
|
+
description: row.description,
|
|
221
|
+
workflowId: row.workflowId,
|
|
222
|
+
url: row.url,
|
|
223
|
+
status: row.status,
|
|
224
|
+
triage: row.triage ?? null,
|
|
225
|
+
});
|
|
226
|
+
continue;
|
|
227
|
+
}
|
|
228
|
+
matched.add(current.slug);
|
|
229
|
+
if (current.name.trim() !== row.name) {
|
|
230
|
+
followUps.push({ kind: "rename", build: row.build, from: current.name, to: row.name });
|
|
231
|
+
}
|
|
232
|
+
const details = {
|
|
233
|
+
kind: "details",
|
|
234
|
+
build: row.build,
|
|
235
|
+
};
|
|
236
|
+
if (current.description.trim() !== row.description) {
|
|
237
|
+
details.description = { from: current.description, to: row.description };
|
|
238
|
+
}
|
|
239
|
+
const currentUrl = current.url ?? null;
|
|
240
|
+
if (row.type === "app" && currentUrl !== row.url) {
|
|
241
|
+
details.url = { from: currentUrl, to: row.url };
|
|
242
|
+
}
|
|
243
|
+
if (details.description || details.url)
|
|
244
|
+
followUps.push(details);
|
|
245
|
+
if (current.status !== row.status) {
|
|
246
|
+
followUps.push({ kind: "status", build: row.build, from: current.status, to: row.status });
|
|
247
|
+
}
|
|
248
|
+
const currentTriage = current.triageProvider ?? null;
|
|
249
|
+
if (row.triage !== undefined && currentTriage !== row.triage) {
|
|
250
|
+
followUps.push({ kind: "triage", build: row.build, from: currentTriage, to: row.triage });
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
// A row in conflict leaves its registry build unmatched, so it shows here
|
|
254
|
+
// too: nothing is synced for it until the manifest is fixed.
|
|
255
|
+
const registryOnly = orgBuilds
|
|
256
|
+
.filter((build) => !matched.has(build.slug))
|
|
257
|
+
.map((build) => ({
|
|
258
|
+
build: build.slug,
|
|
259
|
+
type: portalBuildType(build),
|
|
260
|
+
name: build.name,
|
|
261
|
+
status: build.status,
|
|
262
|
+
}));
|
|
263
|
+
return { actions: [...actions, ...followUps], registryOnly, conflicts };
|
|
264
|
+
}
|
|
265
|
+
function githubClientMdReader(options) {
|
|
266
|
+
return async (slug) => {
|
|
267
|
+
const resolved = await resolveGithubToken({
|
|
268
|
+
token: options.githubToken,
|
|
269
|
+
execFileImpl: options.execFileImpl,
|
|
270
|
+
});
|
|
271
|
+
if (!resolved)
|
|
272
|
+
throw new Error(`GitHub auth required to read client-${slug} — ${GITHUB_TOKEN_FIX}`);
|
|
273
|
+
const res = await (options.githubFetchImpl ?? fetch)(`https://api.github.com/repos/InstallAgent/client-${slug}/contents/CLIENT.md`, {
|
|
274
|
+
headers: {
|
|
275
|
+
Authorization: `Bearer ${resolved.token}`,
|
|
276
|
+
Accept: "application/vnd.github.raw+json",
|
|
277
|
+
"X-GitHub-Api-Version": "2022-11-28",
|
|
278
|
+
},
|
|
279
|
+
});
|
|
280
|
+
if (res.status === 404)
|
|
281
|
+
return null;
|
|
282
|
+
if (!res.ok)
|
|
283
|
+
throw new Error(`GitHub read of client-${slug}/CLIENT.md failed: HTTP ${res.status}`);
|
|
284
|
+
return res.text();
|
|
285
|
+
};
|
|
286
|
+
}
|
|
287
|
+
async function localClientSlugs(workspaceDir) {
|
|
288
|
+
const clientsDir = join(workspaceDir, "clients");
|
|
289
|
+
if (!existsSync(clientsDir))
|
|
290
|
+
return [];
|
|
291
|
+
const entries = await readdir(clientsDir, { withFileTypes: true });
|
|
292
|
+
return entries
|
|
293
|
+
.filter((entry) => entry.isDirectory() && entry.name.startsWith("client-") && entry.name !== "client-template")
|
|
294
|
+
.map((entry) => entry.name.slice("client-".length))
|
|
295
|
+
.filter((slug) => existsSync(join(clientsDir, `client-${slug}`, "CLIENT.md")));
|
|
296
|
+
}
|
|
297
|
+
async function applyAction(action, org, portal) {
|
|
298
|
+
const ref = { slug: org, build: action.build };
|
|
299
|
+
switch (action.kind) {
|
|
300
|
+
case "create":
|
|
301
|
+
await portalCreateBuild({
|
|
302
|
+
...ref,
|
|
303
|
+
name: action.name,
|
|
304
|
+
description: action.description,
|
|
305
|
+
buildType: action.type,
|
|
306
|
+
...(action.workflowId ? { workflowId: action.workflowId } : {}),
|
|
307
|
+
...(action.url ? { url: action.url } : {}),
|
|
308
|
+
}, portal);
|
|
309
|
+
// A create always lands active and not a triage agent.
|
|
310
|
+
if (action.status !== "active")
|
|
311
|
+
await portalSetBuildStatus({ ...ref, status: action.status }, portal);
|
|
312
|
+
if (action.triage)
|
|
313
|
+
await portalSetBuildTriage({ ...ref, provider: action.triage }, portal);
|
|
314
|
+
return;
|
|
315
|
+
case "repoint":
|
|
316
|
+
await portalSetBuildWorkflow({ ...ref, workflowId: action.to }, portal);
|
|
317
|
+
return;
|
|
318
|
+
case "rename":
|
|
319
|
+
await portalSetBuildName({ ...ref, name: action.to }, portal);
|
|
320
|
+
return;
|
|
321
|
+
case "details":
|
|
322
|
+
await portalSetBuildDetails({
|
|
323
|
+
...ref,
|
|
324
|
+
...(action.description ? { description: action.description.to } : {}),
|
|
325
|
+
...(action.url ? { url: action.url.to } : {}),
|
|
326
|
+
}, portal);
|
|
327
|
+
return;
|
|
328
|
+
case "status":
|
|
329
|
+
await portalSetBuildStatus({ ...ref, status: action.to }, portal);
|
|
330
|
+
return;
|
|
331
|
+
case "triage":
|
|
332
|
+
await portalSetBuildTriage({ ...ref, provider: action.to }, portal);
|
|
333
|
+
return;
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
/**
|
|
337
|
+
* Compares every client repo's `## Builds` manifest with the portal's builds
|
|
338
|
+
* registry and, with `apply`, moves the registry to match: create, rename,
|
|
339
|
+
* description/url, status, triage, repoint. Never deletes, never touches
|
|
340
|
+
* Install Agent's own org, never writes a client repo. A second run after an
|
|
341
|
+
* apply plans nothing.
|
|
342
|
+
*/
|
|
343
|
+
export async function syncBuilds(options) {
|
|
344
|
+
const workspaceDir = resolve(options.workspaceDir);
|
|
345
|
+
const portal = options.portal ?? {};
|
|
346
|
+
const apply = options.apply ?? false;
|
|
347
|
+
const readRemote = options.readRemoteClientMd ?? githubClientMdReader(options);
|
|
348
|
+
const [{ orgs: portalOrgs }, { agents: registry }] = await Promise.all([
|
|
349
|
+
portalListOrgs(portal),
|
|
350
|
+
portalListBuilds({}, portal),
|
|
351
|
+
]);
|
|
352
|
+
const internal = new Set(portalOrgs.filter((o) => o.kind === "internal").map((o) => o.slug));
|
|
353
|
+
const local = await localClientSlugs(workspaceDir);
|
|
354
|
+
let slugs = [...new Set([...local, ...portalOrgs.map((o) => o.slug)])].sort();
|
|
355
|
+
if (options.slug) {
|
|
356
|
+
slugs = [options.slug.toLowerCase().replace(/^client-/, "")];
|
|
357
|
+
}
|
|
358
|
+
const skippedOrgs = slugs.filter((slug) => internal.has(slug));
|
|
359
|
+
const orgs = [];
|
|
360
|
+
for (const org of slugs.filter((slug) => !internal.has(slug))) {
|
|
361
|
+
let source = "none";
|
|
362
|
+
let clientMd = null;
|
|
363
|
+
const errors = [];
|
|
364
|
+
if (local.includes(org)) {
|
|
365
|
+
source = "workspace";
|
|
366
|
+
clientMd = await readFile(join(workspaceDir, "clients", `client-${org}`, "CLIENT.md"), "utf8");
|
|
367
|
+
}
|
|
368
|
+
else {
|
|
369
|
+
try {
|
|
370
|
+
clientMd = await readRemote(org);
|
|
371
|
+
if (clientMd !== null)
|
|
372
|
+
source = "github";
|
|
373
|
+
}
|
|
374
|
+
catch (error) {
|
|
375
|
+
errors.push(error instanceof Error ? error.message : String(error));
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
const empty = { actions: [], registryOnly: [], conflicts: [] };
|
|
379
|
+
if (clientMd === null) {
|
|
380
|
+
orgs.push({ org, source, manifest: "no-repo", errors, ...empty });
|
|
381
|
+
continue;
|
|
382
|
+
}
|
|
383
|
+
const manifest = parseBuildsManifest(clientMd);
|
|
384
|
+
if (manifest.state !== "ok") {
|
|
385
|
+
orgs.push({ org, source, manifest: manifest.state, errors: manifest.errors, ...empty });
|
|
386
|
+
continue;
|
|
387
|
+
}
|
|
388
|
+
const plan = planBuildsSync(org, manifest.rows, registry);
|
|
389
|
+
const actions = [];
|
|
390
|
+
for (const action of plan.actions) {
|
|
391
|
+
if (!apply) {
|
|
392
|
+
actions.push({ action });
|
|
393
|
+
continue;
|
|
394
|
+
}
|
|
395
|
+
try {
|
|
396
|
+
await applyAction(action, org, portal);
|
|
397
|
+
actions.push({ action, outcome: "done" });
|
|
398
|
+
}
|
|
399
|
+
catch (error) {
|
|
400
|
+
actions.push({
|
|
401
|
+
action,
|
|
402
|
+
outcome: { error: error instanceof Error ? error.message : String(error) },
|
|
403
|
+
});
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
orgs.push({
|
|
407
|
+
org,
|
|
408
|
+
source,
|
|
409
|
+
manifest: "ok",
|
|
410
|
+
errors,
|
|
411
|
+
actions,
|
|
412
|
+
registryOnly: plan.registryOnly,
|
|
413
|
+
conflicts: plan.conflicts,
|
|
414
|
+
});
|
|
415
|
+
}
|
|
416
|
+
const all = orgs.flatMap((org) => org.actions);
|
|
417
|
+
return {
|
|
418
|
+
applied: apply,
|
|
419
|
+
orgs,
|
|
420
|
+
skippedOrgs,
|
|
421
|
+
actionCount: all.length,
|
|
422
|
+
failedCount: all.filter((a) => typeof a.outcome === "object").length,
|
|
423
|
+
};
|
|
424
|
+
}
|
package/dist/template-sync.js
CHANGED
|
@@ -41,6 +41,14 @@ export const TEMPLATE_SYNCED_FILES = [
|
|
|
41
41
|
// repo-lint imports log-progress (rule 9), so the two always travel together.
|
|
42
42
|
"ci/log-progress.mjs",
|
|
43
43
|
"ci/log-progress.test.mjs",
|
|
44
|
+
// repo-lint also imports roadmap (rule 10): the Roadmap tab + client roadmap
|
|
45
|
+
// are generated from docs/06-roadmap.md.
|
|
46
|
+
"ci/roadmap.mjs",
|
|
47
|
+
"ci/roadmap.test.mjs",
|
|
48
|
+
// repo-lint also imports builds-manifest (rule 11): the `## Builds` block
|
|
49
|
+
// of CLIENT.md, the source of `ia portal sync-builds`.
|
|
50
|
+
"ci/builds-manifest.mjs",
|
|
51
|
+
"ci/builds-manifest.test.mjs",
|
|
44
52
|
"lefthook.yml",
|
|
45
53
|
".github/workflows/repo-lint.yml",
|
|
46
54
|
".github/workflows/pr-to-slack.yml",
|
package/package.json
CHANGED
|
@@ -34,6 +34,8 @@ installagent/
|
|
|
34
34
|
├── team-design/ # Install Agent design system source (tokens, components, guidelines)
|
|
35
35
|
├── team-branding/ # Logo files (static assets only)
|
|
36
36
|
├── skills/ # Cross-cutting agent skills (client deliverables pipeline, brand kit, …)
|
|
37
|
+
├── team-tools/ # Internal technician tooling: the `ia` CLI, SDK, MCP server (see its AGENT.md)
|
|
38
|
+
├── systems-department/ # Independent self-serve storefront repo (working name, unbranded) — own stack, no cross-imports
|
|
37
39
|
├── AGENT.md # ← you are here
|
|
38
40
|
└── ONBOARDING.md # New-contractor orientation — read once, first
|
|
39
41
|
```
|
|
@@ -1,11 +1,13 @@
|
|
|
1
|
-
# AGENTS.md
|
|
1
|
+
# AGENTS.md — installagent workspace root
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Pointer file for agents that read `AGENTS.md` (Codex, Copilot, Aider,
|
|
4
|
+
Continue, and others). It holds no rules of its own.
|
|
5
5
|
|
|
6
|
-
`
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
1. Read [`AGENT.md`](./AGENT.md). It is the source of truth for the whole
|
|
7
|
+
workspace: layout, the "where to start a task" table, the golden rules,
|
|
8
|
+
and how the agentic files are layered.
|
|
9
|
+
2. Read [`ONBOARDING.md`](./ONBOARDING.md) if you are landing here cold.
|
|
10
|
+
3. Inside a repo, read that repo's `AGENT.md` (or `AGENTS.md`). It overrides
|
|
11
|
+
the root rules while you work there.
|
|
9
12
|
|
|
10
|
-
|
|
11
|
-
drift.
|
|
13
|
+
Do not add rule content to this file. Edit `AGENT.md` instead.
|
|
@@ -1,24 +1,12 @@
|
|
|
1
|
-
# GEMINI.md
|
|
1
|
+
# GEMINI.md — installagent workspace root
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Pointer file for the Gemini CLI and other Google-powered agents. It holds no
|
|
4
|
+
rules of its own.
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
1. Read [`AGENT.md`](./AGENT.md). It is the source of truth for the whole
|
|
7
|
+
workspace.
|
|
8
|
+
2. Read [`ONBOARDING.md`](./ONBOARDING.md) if you are landing here cold.
|
|
9
|
+
3. Inside a repo, read that repo's `AGENT.md` (or `AGENTS.md`), then its
|
|
10
|
+
`GEMINI.md` if one exists (for example `team-web/apps/docs/GEMINI.md`).
|
|
7
11
|
|
|
8
|
-
|
|
9
|
-
source of truth.**
|
|
10
|
-
2. [`README.md`](./README.md) — workspace overview.
|
|
11
|
-
3. The `AGENT.md` (or `AGENTS.md`) inside the repo you're working in:
|
|
12
|
-
- [`clients/client-template/AGENT.md`](./clients/client-template/AGENT.md)
|
|
13
|
-
- [`team-clients/AGENT.md`](./team-clients/AGENT.md)
|
|
14
|
-
- [`team-infra/AGENT.md`](./team-infra/AGENT.md)
|
|
15
|
-
- [`team-web/AGENT.md`](./team-web/AGENT.md)
|
|
16
|
-
|
|
17
|
-
This root is a folder of independent git repos (`clients/client-*`,
|
|
18
|
-
`team-*`); it is deliberately not a git repo itself. Each repo has its own
|
|
19
|
-
conventions — always read the repo-level agentic file before editing inside it.
|
|
20
|
-
|
|
21
|
-
## Updating conventions
|
|
22
|
-
|
|
23
|
-
Edit `AGENT.md` (root or repo) and any affected skills, not this file.
|
|
24
|
-
This file is a pointer.
|
|
12
|
+
Do not add rule content to this file. Edit `AGENT.md` instead.
|
|
@@ -134,7 +134,9 @@ installagent/
|
|
|
134
134
|
├── team-web/ # installagent.com + team hub (Next.js pnpm workspace)
|
|
135
135
|
├── team-design/ # Install Agent design system source
|
|
136
136
|
├── team-branding/ # logo files
|
|
137
|
-
|
|
137
|
+
├── skills/ # cross-cutting agent skills (client deliverables pipeline)
|
|
138
|
+
├── team-tools/ # the `ia` CLI + SDK + MCP server for technicians
|
|
139
|
+
└── systems-department/ # independent self-serve storefront repo (unbranded working name)
|
|
138
140
|
```
|
|
139
141
|
|
|
140
142
|
## Orient yourself in this order
|
|
@@ -35,7 +35,7 @@ skills/
|
|
|
35
35
|
├── ia-cli/ # route internal ops through the `ia` CLI (team-tools) — decision map + guardrails
|
|
36
36
|
├── gcloud-cli-setup/ # one named gcloud configuration per account/client + check-before-you-run discipline
|
|
37
37
|
├── slack-voice/ # INTERNAL messages (Slack, email, chat): ~100 words, terse bullets, hard numbers (client → house-voice)
|
|
38
|
-
├── github-profile/ # force gh CLI + git commits onto the
|
|
38
|
+
├── github-profile/ # force gh CLI + git commits onto the work account in root `.github-account` before any GitHub action
|
|
39
39
|
└── init_repo/ # explicit-only /init_repo — dev branch + default branch + one milestone/root-branch per leaf issue
|
|
40
40
|
```
|
|
41
41
|
|
|
@@ -17,7 +17,7 @@ workflows, and diagrams across more than one repo. Repo-local skills live in
|
|
|
17
17
|
## How these get loaded
|
|
18
18
|
|
|
19
19
|
Every skill is `<name>/SKILL.md` with YAML frontmatter (`name`, `description`).
|
|
20
|
-
|
|
20
|
+
22 of them are symlinked into [`../.claude/skills/`](../.claude/skills/), so Claude
|
|
21
21
|
Code and Cowork register them automatically — they appear in the skill menu and
|
|
22
22
|
fire on their own without being invoked by name. The `description` is the
|
|
23
23
|
trigger; the body is only read once the skill fires.
|
|
@@ -76,9 +76,17 @@ context, intake, agent bank, secrets, `wizard`/`doctor`). Check it before
|
|
|
76
76
|
writing any custom script against GitHub, Airtable, Linear, Drive, n8n, or the
|
|
77
77
|
portal.
|
|
78
78
|
|
|
79
|
-
[`github-profile`](./github-profile/) — force gh CLI + git commits onto
|
|
80
|
-
|
|
81
|
-
logged in; only one
|
|
79
|
+
[`github-profile`](./github-profile/) — force gh CLI + git commits onto this
|
|
80
|
+
machine's work account before any GitHub action. The account comes from the
|
|
81
|
+
workspace-root `.github-account` file (two accounts are logged in; only one
|
|
82
|
+
is the work identity).
|
|
83
|
+
|
|
84
|
+
[`slack-voice`](./slack-voice/) — internal messages (Slack, email, chat):
|
|
85
|
+
terse, bulleted, hard numbers, about 100 words for an update. Client-facing
|
|
86
|
+
words stay with `house-voice`.
|
|
87
|
+
|
|
88
|
+
[`gcloud-cli-setup`](./gcloud-cli-setup/) — one named gcloud configuration
|
|
89
|
+
per account or client, and the check-before-you-run discipline.
|
|
82
90
|
|
|
83
91
|
[`init_repo`](./init_repo/) — **explicit-invocation only**, never fires on
|
|
84
92
|
its own. Run `/init_repo` against an existing `client-<slug>` repo to create
|
|
@@ -119,6 +119,9 @@ The onboarding checklist must **not feel overwhelming**. Rules:
|
|
|
119
119
|
- **Measurable, hedged outcomes** — never guarantees.
|
|
120
120
|
- **State the full commercial model** including the capped API-credit pass-through.
|
|
121
121
|
- **No secrets / customer data / real VINs** in any doc.
|
|
122
|
+
- **No dates in the PDFs.** `brand.render_pdf` refuses them. Use "month one",
|
|
123
|
+
"week 4" or "at acceptance" in place of a calendar date. Pass
|
|
124
|
+
`allow_dates=True` only when the user explicitly asks for a date.
|
|
122
125
|
|
|
123
126
|
## Before you finish — checklist
|
|
124
127
|
|
|
@@ -80,6 +80,12 @@ numbers. Then `brand.render_pdf(body, out)` rasterizes via WeasyPrint. Content
|
|
|
80
80
|
discipline stays with `engagement-spec` (overviews/onboarding) and
|
|
81
81
|
`contract-tech-agnostic` (SOWs) — this skill only guarantees the brand.
|
|
82
82
|
|
|
83
|
+
**No dates in a generated PDF.** `render_pdf` raises `ValueError` if the visible
|
|
84
|
+
text holds a calendar date (cover date, "as of", ISO stamp). A dated PDF is
|
|
85
|
+
stale the day after it ships. Pass `allow_dates=True` only when the user
|
|
86
|
+
explicitly asks for a date (for example a dated timeline or an effective date).
|
|
87
|
+
Blank signature date lines are fine.
|
|
88
|
+
|
|
83
89
|
### Client deck (Google Slides)
|
|
84
90
|
|
|
85
91
|
Two paths, one gate — full detail in
|
|
@@ -143,6 +149,8 @@ images. The logo assets here are copies of
|
|
|
143
149
|
other hue.
|
|
144
150
|
- [ ] Official logo used (PDF hero + running header); no generic glyph.
|
|
145
151
|
- [ ] Generator imports `scripts/brand.py` — no hard-coded hexes.
|
|
152
|
+
- [ ] PDF has no dates (`render_pdf` enforces it); `allow_dates=True` only on
|
|
153
|
+
an explicit ask.
|
|
146
154
|
- [ ] Excalidraw validates / opens; PDF previewed as PNG.
|
|
147
155
|
- [ ] Deck: `deck_lint.py --render` clean **and every slide looked at** — a
|
|
148
156
|
clean geometry pass is not a clean deck.
|
|
@@ -15,12 +15,17 @@ body = brand.pdf_hero(
|
|
|
15
15
|
kicker="Statement of Work & Proposal",
|
|
16
16
|
title="CarVision Pricing Agent — Phase 1",
|
|
17
17
|
sub="A daily used-car repricing co-pilot.",
|
|
18
|
-
meta_html='<div class="kicker" style="color:#8a93a0">
|
|
18
|
+
meta_html='<div class="kicker" style="color:#8a93a0">Confidential</div>',
|
|
19
19
|
)
|
|
20
20
|
body += "<h2><span class='n'>1</span>Summary</h2><p>…</p>" # your content
|
|
21
21
|
brand.render_pdf(body, "client-<slug>/.../Proposal.pdf")
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
+
**No dates.** `render_pdf()` scans the visible text and raises `ValueError` on
|
|
25
|
+
any calendar date (`June 16, 2026`, `16 June 2026`, `October 2026`,
|
|
26
|
+
`2026-10-20`, `10/20/26`). Do not date the cover, the footer, or an "as of"
|
|
27
|
+
line. Pass `allow_dates=True` only when the user explicitly asks for a date.
|
|
28
|
+
|
|
24
29
|
- `pdf_hero()` emits the **official logo** (full lockup in the hero, icon-only in
|
|
25
30
|
the running header) — no generic mark. The wordmark is set to ink on white.
|
|
26
31
|
- `pdf_css()` provides page setup (Letter, margins), a running footer with
|
|
@@ -62,5 +67,7 @@ brand.render_pdf(body, "client-<slug>/.../Proposal.pdf")
|
|
|
62
67
|
- Client-facing wording follows **contract-tech-agnostic** (SOWs) and
|
|
63
68
|
**engagement-spec** (overviews/onboarding) — this skill governs *brand*, those
|
|
64
69
|
govern *content*.
|
|
70
|
+
- **No dates in a generated PDF** unless the user explicitly asks
|
|
71
|
+
(`allow_dates=True`). Undated copy never goes stale.
|
|
65
72
|
- Flag placeholders (`[legal entity]`, `[signatory]`) so they're filled before
|
|
66
73
|
sending.
|
|
@@ -12,7 +12,7 @@ Light surfaces (client PDFs + diagrams on white) use the ink/muted neutrals
|
|
|
12
12
|
below; the dark marketing-site neutrals in theme.css are NOT for documents.
|
|
13
13
|
"""
|
|
14
14
|
from __future__ import annotations
|
|
15
|
-
import json, math, random
|
|
15
|
+
import html, json, math, random, re
|
|
16
16
|
from pathlib import Path
|
|
17
17
|
|
|
18
18
|
# ─── Brand palette (mirror of theme.css — Design System v1.0 Signal Red) ─────
|
|
@@ -167,9 +167,36 @@ def pdf_hero(kicker, title, sub, meta_html="") -> str:
|
|
|
167
167
|
{meta_html}
|
|
168
168
|
</div>"""
|
|
169
169
|
|
|
170
|
-
|
|
171
|
-
|
|
170
|
+
_MONTH = (r"(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|June?|July?|"
|
|
171
|
+
r"Aug(?:ust)?|Sep(?:t(?:ember)?)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)")
|
|
172
|
+
_DATE_RES = [re.compile(p) for p in (
|
|
173
|
+
rf"\b{_MONTH}\.? \d{{1,2}}(?:st|nd|rd|th)?\b(?:,? \d{{4}})?", # June 16, 2026 / Oct 20
|
|
174
|
+
rf"\b\d{{1,2}}(?:st|nd|rd|th)? {_MONTH}\b\.?(?:,? \d{{4}})?", # 16 June 2026
|
|
175
|
+
rf"\b{_MONTH}\.?,? \d{{4}}\b", # October 2026
|
|
176
|
+
r"\b\d{4}-\d{2}-\d{2}\b", # 2026-10-20
|
|
177
|
+
r"\b\d{1,2}/\d{1,2}/\d{2,4}\b", # 10/20/26
|
|
178
|
+
)]
|
|
179
|
+
|
|
180
|
+
def find_dates(html_body: str) -> list[str]:
|
|
181
|
+
"""Calendar dates in the VISIBLE text of an HTML body (tags, <style> and
|
|
182
|
+
<script> are ignored). Used by render_pdf to refuse dated PDFs."""
|
|
183
|
+
text = re.sub(r"(?is)<(style|script)\b.*?</\1>", " ", html_body)
|
|
184
|
+
text = re.sub(r"\s+", " ", html.unescape(re.sub(r"<[^>]+>", " ", text))) # \s covers
|
|
185
|
+
return [m.group(0) for rx in _DATE_RES for m in rx.finditer(text)]
|
|
186
|
+
|
|
187
|
+
def render_pdf(html_body: str, out_path: str, head_extra: str = "", allow_dates: bool = False):
|
|
188
|
+
"""Render an HTML body (after pdf_hero + content) to a branded PDF.
|
|
189
|
+
|
|
190
|
+
House rule: a generated PDF carries NO dates (no cover date, no "as of",
|
|
191
|
+
no ISO stamps). A dated PDF goes stale the day after it is sent. Pass
|
|
192
|
+
allow_dates=True only when a date is explicitly requested (a signed
|
|
193
|
+
effective date, a dated timeline). Blank signature date lines are fine."""
|
|
194
|
+
found = find_dates(html_body)
|
|
195
|
+
if found and not allow_dates:
|
|
196
|
+
raise ValueError(
|
|
197
|
+
"PDF text contains date(s): " + ", ".join(sorted(set(found))[:8])
|
|
198
|
+
+ ". Remove them, or pass allow_dates=True if the date was explicitly requested.")
|
|
172
199
|
from weasyprint import HTML
|
|
173
|
-
|
|
174
|
-
HTML(string=
|
|
200
|
+
html_doc =f"<!DOCTYPE html><html><head><meta charset='utf-8'><style>{pdf_css()}{head_extra}</style></head><body>{html_body}</body></html>"
|
|
201
|
+
HTML(string=html_doc, base_url=str(ASSET_DIR)).write_pdf(out_path)
|
|
175
202
|
return out_path
|