@installagent/sdk 0.1.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 +90 -0
- package/dist/agent-templates.js +211 -0
- package/dist/client-build.d.ts +50 -0
- package/dist/client-build.js +155 -0
- package/dist/client-context.d.ts +40 -0
- package/dist/client-context.js +70 -0
- package/dist/client-drive.d.ts +67 -0
- package/dist/client-drive.js +278 -0
- package/dist/client-intake.d.ts +68 -0
- package/dist/client-intake.js +189 -0
- package/dist/client-linear.d.ts +30 -0
- package/dist/client-linear.js +85 -0
- package/dist/docs-search.d.ts +44 -0
- package/dist/docs-search.js +187 -0
- package/dist/doctor.d.ts +43 -0
- package/dist/doctor.js +425 -0
- package/dist/env-file.d.ts +25 -0
- package/dist/env-file.js +69 -0
- package/dist/env-fill.d.ts +43 -0
- package/dist/env-fill.js +161 -0
- package/dist/env-push.d.ts +37 -0
- package/dist/env-push.js +137 -0
- package/dist/env-registry.d.ts +49 -0
- package/dist/env-registry.js +230 -0
- package/dist/exec.d.ts +14 -0
- package/dist/exec.js +16 -0
- package/dist/fathom-webhook.d.ts +44 -0
- package/dist/fathom-webhook.js +123 -0
- package/dist/fs-utils.d.ts +9 -0
- package/dist/fs-utils.js +34 -0
- package/dist/gcp-service-account-key.d.ts +37 -0
- package/dist/gcp-service-account-key.js +66 -0
- package/dist/gemini-api-key.d.ts +47 -0
- package/dist/gemini-api-key.js +132 -0
- package/dist/git.d.ts +16 -0
- package/dist/git.js +29 -0
- package/dist/github-token.d.ts +24 -0
- package/dist/github-token.js +30 -0
- package/dist/index.d.ts +25 -0
- package/dist/index.js +28 -0
- package/dist/init.d.ts +47 -0
- package/dist/init.js +101 -0
- package/dist/linear-project.d.ts +81 -0
- package/dist/linear-project.js +192 -0
- package/dist/new-client.d.ts +32 -0
- package/dist/new-client.js +89 -0
- package/dist/ping.d.ts +6 -0
- package/dist/ping.js +7 -0
- package/dist/portal-admin.d.ts +133 -0
- package/dist/portal-admin.js +144 -0
- package/dist/sync-templates.d.ts +58 -0
- package/dist/sync-templates.js +109 -0
- package/dist/template-sync.d.ts +55 -0
- package/dist/template-sync.js +90 -0
- package/dist/templates.d.ts +19 -0
- package/dist/templates.js +24 -0
- package/dist/wizard.d.ts +78 -0
- package/dist/wizard.js +213 -0
- package/package.json +30 -0
- package/templates/env.example +60 -0
- package/templates/workspace-root/.claude/settings.json +39 -0
- package/templates/workspace-root/AGENT.md +205 -0
- package/templates/workspace-root/AGENTS.md +11 -0
- package/templates/workspace-root/CLAUDE.md +63 -0
- package/templates/workspace-root/GEMINI.md +24 -0
- package/templates/workspace-root/ONBOARDING.md +164 -0
- package/templates/workspace-root/README.md +67 -0
- package/templates/workspace-root/skills/CLAUDE.md +79 -0
- package/templates/workspace-root/skills/client-deliverables/SKILL.md +131 -0
- package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +103 -0
- package/templates/workspace-root/skills/client-facing-docs/SKILL.md +131 -0
- package/templates/workspace-root/skills/client-facing-docs/references/doc-structures.md +81 -0
- package/templates/workspace-root/skills/client-llm-setup/SKILL.md +97 -0
- package/templates/workspace-root/skills/client-llm-setup/references/guide-template.md +87 -0
- package/templates/workspace-root/skills/client-workflow-diagram/SKILL.md +141 -0
- package/templates/workspace-root/skills/client-workflow-diagram/references/excalidraw-format.md +140 -0
- package/templates/workspace-root/skills/contract-tech-agnostic/SKILL.md +99 -0
- package/templates/workspace-root/skills/contract-tech-agnostic/references/Install_Agent_SOW_Template.docx +0 -0
- package/templates/workspace-root/skills/design-system/SKILL.md +118 -0
- package/templates/workspace-root/skills/design-system/references/tokens.md +139 -0
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +272 -0
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +220 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +158 -0
- package/templates/workspace-root/skills/house-voice/references/source-copy.md +173 -0
- package/templates/workspace-root/skills/ia-cli/SKILL.md +87 -0
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +112 -0
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-logo.svg +1 -0
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-mark.svg +1 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/brand-tokens.md +71 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +66 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/excalidraw-red-theme.md +73 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +175 -0
- package/templates/workspace-root/skills/linear/SKILL.md +186 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +141 -0
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
export declare const PORTAL_ADMIN_SECRET_ENV = "IA_PORTAL_ADMIN_SECRET";
|
|
2
|
+
export declare const PORTAL_URL_ENV = "IA_PORTAL_URL";
|
|
3
|
+
export declare const DEFAULT_PORTAL_URL = "https://portal.installagent.com";
|
|
4
|
+
export declare const PORTAL_PASSWORD_WARNING = "Password shown ONCE \u2014 store it in the password manager; never chat, email, or files.";
|
|
5
|
+
export declare const PORTAL_SYNC_MAX_DAYS = 90;
|
|
6
|
+
/** Thrown when the portal admin secret is missing or rejected. */
|
|
7
|
+
export declare class PortalAdminAuthError extends Error {
|
|
8
|
+
}
|
|
9
|
+
export interface PortalAdminOptions {
|
|
10
|
+
/** Bearer secret; defaults to $IA_PORTAL_ADMIN_SECRET. */
|
|
11
|
+
secret?: string;
|
|
12
|
+
/** Portal base URL; defaults to $IA_PORTAL_URL, then the prod portal. */
|
|
13
|
+
baseUrl?: string;
|
|
14
|
+
/** Injectable for tests; defaults to global fetch. */
|
|
15
|
+
fetchImpl?: typeof fetch;
|
|
16
|
+
}
|
|
17
|
+
export interface PortalOrgUser {
|
|
18
|
+
name: string;
|
|
19
|
+
email: string | null;
|
|
20
|
+
role: "member" | "owner";
|
|
21
|
+
status: string;
|
|
22
|
+
}
|
|
23
|
+
export interface PortalOrg {
|
|
24
|
+
slug: string;
|
|
25
|
+
name: string;
|
|
26
|
+
kind: "client" | "internal";
|
|
27
|
+
status: string;
|
|
28
|
+
driveFolderId: string | null;
|
|
29
|
+
airtableRecordId: string | null;
|
|
30
|
+
users: PortalOrgUser[];
|
|
31
|
+
}
|
|
32
|
+
export interface PortalAgent {
|
|
33
|
+
org: string;
|
|
34
|
+
slug: string;
|
|
35
|
+
name: string;
|
|
36
|
+
description: string;
|
|
37
|
+
workflowId: string;
|
|
38
|
+
status: "active" | "paused" | "retired";
|
|
39
|
+
n8nActive: boolean | null;
|
|
40
|
+
lastSyncedAt: string | null;
|
|
41
|
+
}
|
|
42
|
+
export interface PortalCreateOrgInput {
|
|
43
|
+
slug: string;
|
|
44
|
+
name: string;
|
|
45
|
+
/** Install Agent's own org — no client login, password discarded. */
|
|
46
|
+
internal?: boolean;
|
|
47
|
+
driveFolderId?: string;
|
|
48
|
+
airtableRecordId?: string;
|
|
49
|
+
}
|
|
50
|
+
export interface PortalCreateOrgResult {
|
|
51
|
+
org: PortalOrg;
|
|
52
|
+
/** null for internal orgs (deliberately discarded server-side). */
|
|
53
|
+
password: string | null;
|
|
54
|
+
warning: string;
|
|
55
|
+
}
|
|
56
|
+
export interface PortalSetPasswordResult {
|
|
57
|
+
slug: string;
|
|
58
|
+
password: string;
|
|
59
|
+
warning: string;
|
|
60
|
+
}
|
|
61
|
+
export interface PortalSetDriveFolderResult {
|
|
62
|
+
slug: string;
|
|
63
|
+
driveFolderId: string;
|
|
64
|
+
}
|
|
65
|
+
export interface PortalAddUserInput {
|
|
66
|
+
slug: string;
|
|
67
|
+
name: string;
|
|
68
|
+
email?: string;
|
|
69
|
+
role?: "member" | "owner";
|
|
70
|
+
}
|
|
71
|
+
export interface PortalAddUserResult {
|
|
72
|
+
slug: string;
|
|
73
|
+
user: PortalOrgUser;
|
|
74
|
+
}
|
|
75
|
+
export interface PortalListOrgsResult {
|
|
76
|
+
orgs: PortalOrg[];
|
|
77
|
+
}
|
|
78
|
+
export interface PortalCreateAgentInput {
|
|
79
|
+
slug: string;
|
|
80
|
+
agent: string;
|
|
81
|
+
name: string;
|
|
82
|
+
description: string;
|
|
83
|
+
workflowId: string;
|
|
84
|
+
}
|
|
85
|
+
export interface PortalSetAgentStatusInput {
|
|
86
|
+
slug: string;
|
|
87
|
+
agent: string;
|
|
88
|
+
status: "active" | "paused" | "retired";
|
|
89
|
+
}
|
|
90
|
+
export interface PortalSetAgentStatusResult {
|
|
91
|
+
org: string;
|
|
92
|
+
agent: string;
|
|
93
|
+
status: "active" | "paused" | "retired";
|
|
94
|
+
}
|
|
95
|
+
export interface PortalListAgentsResult {
|
|
96
|
+
agents: PortalAgent[];
|
|
97
|
+
}
|
|
98
|
+
export interface PortalAgentSyncRow {
|
|
99
|
+
org: string;
|
|
100
|
+
agent: string;
|
|
101
|
+
fetched: number;
|
|
102
|
+
inserted: number;
|
|
103
|
+
n8nActive: boolean | null;
|
|
104
|
+
error?: string;
|
|
105
|
+
}
|
|
106
|
+
export type PortalSyncRunsResult = {
|
|
107
|
+
since: string;
|
|
108
|
+
fetched: number;
|
|
109
|
+
inserted: number;
|
|
110
|
+
agents: PortalAgentSyncRow[];
|
|
111
|
+
} | {
|
|
112
|
+
skipped: string;
|
|
113
|
+
};
|
|
114
|
+
export declare function portalCreateOrg(input: PortalCreateOrgInput, options?: PortalAdminOptions): Promise<PortalCreateOrgResult>;
|
|
115
|
+
export declare function portalSetPassword(input: {
|
|
116
|
+
slug: string;
|
|
117
|
+
}, options?: PortalAdminOptions): Promise<PortalSetPasswordResult>;
|
|
118
|
+
export declare function portalSetDriveFolder(input: {
|
|
119
|
+
slug: string;
|
|
120
|
+
folderId: string;
|
|
121
|
+
}, options?: PortalAdminOptions): Promise<PortalSetDriveFolderResult>;
|
|
122
|
+
export declare function portalAddUser(input: PortalAddUserInput, options?: PortalAdminOptions): Promise<PortalAddUserResult>;
|
|
123
|
+
export declare function portalListOrgs(options?: PortalAdminOptions): Promise<PortalListOrgsResult>;
|
|
124
|
+
export declare function portalCreateAgent(input: PortalCreateAgentInput, options?: PortalAdminOptions): Promise<{
|
|
125
|
+
agent: PortalAgent;
|
|
126
|
+
}>;
|
|
127
|
+
export declare function portalSetAgentStatus(input: PortalSetAgentStatusInput, options?: PortalAdminOptions): Promise<PortalSetAgentStatusResult>;
|
|
128
|
+
export declare function portalListAgents(input?: {
|
|
129
|
+
slug?: string;
|
|
130
|
+
}, options?: PortalAdminOptions): Promise<PortalListAgentsResult>;
|
|
131
|
+
export declare function portalSyncRuns(input?: {
|
|
132
|
+
days?: number;
|
|
133
|
+
}, options?: PortalAdminOptions): Promise<PortalSyncRunsResult>;
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
// Portal administration over the /api/admin/* HTTP API that
|
|
2
|
+
// team-web/apps/portal exposes (bearer PORTAL_ADMIN_API_SECRET on the server,
|
|
3
|
+
// held locally as IA_PORTAL_ADMIN_SECRET). This is how techs onboard client
|
|
4
|
+
// orgs and manage the agent registry without a team-web checkout or database
|
|
5
|
+
// credentials. Mirrors the 9 commands of the portal's break-glass script.
|
|
6
|
+
//
|
|
7
|
+
// create-org / set-password results carry the org password EXACTLY ONCE —
|
|
8
|
+
// treat like the secrets-minting ops: print once, store in the password
|
|
9
|
+
// manager, never persist.
|
|
10
|
+
import { SLUG_PATTERN } from "./new-client.js";
|
|
11
|
+
export const PORTAL_ADMIN_SECRET_ENV = "IA_PORTAL_ADMIN_SECRET";
|
|
12
|
+
export const PORTAL_URL_ENV = "IA_PORTAL_URL";
|
|
13
|
+
export const DEFAULT_PORTAL_URL = "https://portal.installagent.com";
|
|
14
|
+
export const PORTAL_PASSWORD_WARNING = "Password shown ONCE — store it in the password manager; never chat, email, or files.";
|
|
15
|
+
// Mirrors the API's bounds; the server re-validates. Deep backfills go
|
|
16
|
+
// through the portal's break-glass script, not this API.
|
|
17
|
+
export const PORTAL_SYNC_MAX_DAYS = 90;
|
|
18
|
+
/** Thrown when the portal admin secret is missing or rejected. */
|
|
19
|
+
export class PortalAdminAuthError extends Error {
|
|
20
|
+
}
|
|
21
|
+
/** Lowercase then validate, matching the server (and the old script). */
|
|
22
|
+
function normalizeSlug(value, field) {
|
|
23
|
+
const slug = value.toLowerCase();
|
|
24
|
+
if (!SLUG_PATTERN.test(slug)) {
|
|
25
|
+
throw new Error(`invalid slug "${value}" for ${field} — use lowercase letters, digits, and hyphens`);
|
|
26
|
+
}
|
|
27
|
+
return slug;
|
|
28
|
+
}
|
|
29
|
+
async function portalRequest(method, path, options, body) {
|
|
30
|
+
const secret = options.secret ?? process.env[PORTAL_ADMIN_SECRET_ENV];
|
|
31
|
+
if (!secret) {
|
|
32
|
+
throw new PortalAdminAuthError(`portal admin secret required — set ${PORTAL_ADMIN_SECRET_ENV} (from 1Password; it matches the ` +
|
|
33
|
+
"portal's PORTAL_ADMIN_API_SECRET) or pass secret");
|
|
34
|
+
}
|
|
35
|
+
const baseUrl = options.baseUrl ?? process.env[PORTAL_URL_ENV] ?? DEFAULT_PORTAL_URL;
|
|
36
|
+
const fetchImpl = options.fetchImpl ?? fetch;
|
|
37
|
+
const res = await fetchImpl(`${baseUrl}${path}`, {
|
|
38
|
+
method,
|
|
39
|
+
headers: {
|
|
40
|
+
Authorization: `Bearer ${secret}`,
|
|
41
|
+
...(body ? { "Content-Type": "application/json" } : {}),
|
|
42
|
+
},
|
|
43
|
+
...(body ? { body: JSON.stringify(body) } : {}),
|
|
44
|
+
});
|
|
45
|
+
if (res.status === 401 || res.status === 403) {
|
|
46
|
+
throw new PortalAdminAuthError(`portal rejected ${PORTAL_ADMIN_SECRET_ENV} (HTTP ${res.status}) — check it against the ` +
|
|
47
|
+
"PORTAL_ADMIN_API_SECRET in 1Password (it may have rotated).");
|
|
48
|
+
}
|
|
49
|
+
if (!res.ok) {
|
|
50
|
+
const serverError = await res
|
|
51
|
+
.json()
|
|
52
|
+
.then((data) => typeof data === "object" && data !== null && "error" in data
|
|
53
|
+
? String(data.error)
|
|
54
|
+
: null)
|
|
55
|
+
.catch(() => null);
|
|
56
|
+
throw new Error(`${method} ${path} failed: HTTP ${res.status}${serverError ? ` — ${serverError}` : ""}`);
|
|
57
|
+
}
|
|
58
|
+
return (await res.json());
|
|
59
|
+
}
|
|
60
|
+
export async function portalCreateOrg(input, options = {}) {
|
|
61
|
+
const slug = normalizeSlug(input.slug, "org");
|
|
62
|
+
const result = await portalRequest("POST", "/api/admin/orgs", options, {
|
|
63
|
+
slug,
|
|
64
|
+
name: input.name,
|
|
65
|
+
...(input.internal ? { internal: true } : {}),
|
|
66
|
+
...(input.driveFolderId ? { driveFolderId: input.driveFolderId } : {}),
|
|
67
|
+
...(input.airtableRecordId ? { airtableRecordId: input.airtableRecordId } : {}),
|
|
68
|
+
});
|
|
69
|
+
return { ...result, warning: PORTAL_PASSWORD_WARNING };
|
|
70
|
+
}
|
|
71
|
+
export async function portalSetPassword(input, options = {}) {
|
|
72
|
+
const slug = normalizeSlug(input.slug, "org");
|
|
73
|
+
const result = await portalRequest("POST", "/api/admin/orgs/password", options, { slug });
|
|
74
|
+
return { ...result, warning: PORTAL_PASSWORD_WARNING };
|
|
75
|
+
}
|
|
76
|
+
export async function portalSetDriveFolder(input, options = {}) {
|
|
77
|
+
const slug = normalizeSlug(input.slug, "org");
|
|
78
|
+
return portalRequest("POST", "/api/admin/orgs/drive-folder", options, {
|
|
79
|
+
slug,
|
|
80
|
+
folderId: input.folderId,
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
export async function portalAddUser(input, options = {}) {
|
|
84
|
+
const slug = normalizeSlug(input.slug, "org");
|
|
85
|
+
if (input.role !== undefined && input.role !== "member" && input.role !== "owner") {
|
|
86
|
+
throw new Error("role must be member|owner");
|
|
87
|
+
}
|
|
88
|
+
return portalRequest("POST", "/api/admin/users", options, {
|
|
89
|
+
slug,
|
|
90
|
+
name: input.name,
|
|
91
|
+
...(input.email ? { email: input.email } : {}),
|
|
92
|
+
...(input.role ? { role: input.role } : {}),
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
export async function portalListOrgs(options = {}) {
|
|
96
|
+
return portalRequest("GET", "/api/admin/orgs", options);
|
|
97
|
+
}
|
|
98
|
+
export async function portalCreateAgent(input, options = {}) {
|
|
99
|
+
const slug = normalizeSlug(input.slug, "org");
|
|
100
|
+
const agent = normalizeSlug(input.agent, "agent");
|
|
101
|
+
return portalRequest("POST", "/api/admin/agents", options, {
|
|
102
|
+
slug,
|
|
103
|
+
agent,
|
|
104
|
+
name: input.name,
|
|
105
|
+
description: input.description,
|
|
106
|
+
workflowId: input.workflowId,
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
export async function portalSetAgentStatus(input, options = {}) {
|
|
110
|
+
const slug = normalizeSlug(input.slug, "org");
|
|
111
|
+
const agent = normalizeSlug(input.agent, "agent");
|
|
112
|
+
if (input.status !== "active" && input.status !== "paused" && input.status !== "retired") {
|
|
113
|
+
throw new Error("status must be active|paused|retired");
|
|
114
|
+
}
|
|
115
|
+
return portalRequest("POST", "/api/admin/agents/status", options, {
|
|
116
|
+
slug,
|
|
117
|
+
agent,
|
|
118
|
+
status: input.status,
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
export async function portalListAgents(input = {}, options = {}) {
|
|
122
|
+
const query = input.slug ? `?slug=${encodeURIComponent(normalizeSlug(input.slug, "org"))}` : "";
|
|
123
|
+
return portalRequest("GET", `/api/admin/agents${query}`, options);
|
|
124
|
+
}
|
|
125
|
+
export async function portalSyncRuns(input = {}, options = {}) {
|
|
126
|
+
if (input.days !== undefined) {
|
|
127
|
+
if (!Number.isInteger(input.days) || input.days < 1 || input.days > PORTAL_SYNC_MAX_DAYS) {
|
|
128
|
+
throw new Error(`days must be an integer between 1 and ${PORTAL_SYNC_MAX_DAYS}`);
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
try {
|
|
132
|
+
return await portalRequest("POST", "/api/admin/sync-runs", options, {
|
|
133
|
+
...(input.days !== undefined ? { days: input.days } : {}),
|
|
134
|
+
});
|
|
135
|
+
}
|
|
136
|
+
catch (error) {
|
|
137
|
+
if (error instanceof PortalAdminAuthError)
|
|
138
|
+
throw error;
|
|
139
|
+
// The sync walks every agent sequentially and can outlive the function's
|
|
140
|
+
// time budget; it is idempotent, so the right move is simply to retry.
|
|
141
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
142
|
+
throw new Error(`${message} (the sync is idempotent — safe to re-run, or use a smaller --days)`);
|
|
143
|
+
}
|
|
144
|
+
}
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The canonical workspace-root docs and skills are loose, ungitted files at
|
|
3
|
+
* the live installagent/ root — there is no repo to clone them from, so the
|
|
4
|
+
* static copy bundled in this repo (templates/workspace-root/, what `ia
|
|
5
|
+
* init`/`ia wizard` lay down) drifts unless someone re-syncs it. This
|
|
6
|
+
* operation is that re-sync: canonical root → bundle, never the other way.
|
|
7
|
+
* Fix the canonical file at the workspace root first, then run this — edits
|
|
8
|
+
* made directly to the bundle get silently reverted by the next sync.
|
|
9
|
+
*/
|
|
10
|
+
/** The exact template set: six root orientation docs … */
|
|
11
|
+
export declare const TEMPLATE_ROOT_DOCS: string[];
|
|
12
|
+
/** … plus the shared agent-permission preset. Never settings.local.json or
|
|
13
|
+
* anything else machine-local from .claude/. */
|
|
14
|
+
export declare const TEMPLATE_CLAUDE_SETTINGS = ".claude/settings.json";
|
|
15
|
+
export interface SyncTemplatesOptions {
|
|
16
|
+
/** The installagent/ workspace root (holds the canonical docs + skills/). */
|
|
17
|
+
workspaceDir: string;
|
|
18
|
+
/** Write the bundle. Default false — report drift only. */
|
|
19
|
+
apply?: boolean;
|
|
20
|
+
}
|
|
21
|
+
export type SyncTemplatesFileStatus =
|
|
22
|
+
/** bundle matches the canonical file */
|
|
23
|
+
"in-sync"
|
|
24
|
+
/** bundle differs from the canonical file */
|
|
25
|
+
| "drifted"
|
|
26
|
+
/** canonical file has no bundle copy yet */
|
|
27
|
+
| "missing"
|
|
28
|
+
/** bundle-only file with no canonical counterpart (deleted at the root) */
|
|
29
|
+
| "stale"
|
|
30
|
+
/** drifted/missing, copied over (apply) */
|
|
31
|
+
| "fixed"
|
|
32
|
+
/** stale, deleted from the bundle (apply) */
|
|
33
|
+
| "removed";
|
|
34
|
+
export interface SyncTemplatesFileResult {
|
|
35
|
+
/** Bundle-relative path, e.g. `skills/tech-call-prep/SKILL.md`. */
|
|
36
|
+
file: string;
|
|
37
|
+
status: SyncTemplatesFileStatus;
|
|
38
|
+
}
|
|
39
|
+
export interface SyncTemplatesResult {
|
|
40
|
+
workspaceDir: string;
|
|
41
|
+
/** templates/workspace-root inside the team-tools checkout. */
|
|
42
|
+
templateDir: string;
|
|
43
|
+
files: SyncTemplatesFileResult[];
|
|
44
|
+
/** Files not in-sync (report) / touched (apply). */
|
|
45
|
+
changedCount: number;
|
|
46
|
+
applied: boolean;
|
|
47
|
+
/** What a human must still do after an apply — review, test, commit. */
|
|
48
|
+
nextSteps: string[];
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Re-sync the workspace-root template bundle (root docs + skills/ +
|
|
52
|
+
* .claude/settings.json) from the canonical files at the live workspace
|
|
53
|
+
* root. Report-only by default; `apply` copies drifted/missing files in and
|
|
54
|
+
* deletes bundle skills that no longer exist at the root. Only ever writes
|
|
55
|
+
* inside templates/workspace-root/ — and never reads or copies `.env`,
|
|
56
|
+
* settings.local.json, or anything machine-local.
|
|
57
|
+
*/
|
|
58
|
+
export declare function syncTemplates(options: SyncTemplatesOptions): Promise<SyncTemplatesResult>;
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
import { existsSync } from "node:fs";
|
|
2
|
+
import { copyFile, mkdir, readFile, rm } from "node:fs/promises";
|
|
3
|
+
import { dirname, join, resolve } from "node:path";
|
|
4
|
+
import { listFiles } from "./fs-utils.js";
|
|
5
|
+
/**
|
|
6
|
+
* The canonical workspace-root docs and skills are loose, ungitted files at
|
|
7
|
+
* the live installagent/ root — there is no repo to clone them from, so the
|
|
8
|
+
* static copy bundled in this repo (templates/workspace-root/, what `ia
|
|
9
|
+
* init`/`ia wizard` lay down) drifts unless someone re-syncs it. This
|
|
10
|
+
* operation is that re-sync: canonical root → bundle, never the other way.
|
|
11
|
+
* Fix the canonical file at the workspace root first, then run this — edits
|
|
12
|
+
* made directly to the bundle get silently reverted by the next sync.
|
|
13
|
+
*/
|
|
14
|
+
/** The exact template set: six root orientation docs … */
|
|
15
|
+
export const TEMPLATE_ROOT_DOCS = [
|
|
16
|
+
"AGENT.md",
|
|
17
|
+
"AGENTS.md",
|
|
18
|
+
"CLAUDE.md",
|
|
19
|
+
"GEMINI.md",
|
|
20
|
+
"ONBOARDING.md",
|
|
21
|
+
"README.md",
|
|
22
|
+
];
|
|
23
|
+
/** … plus the shared agent-permission preset. Never settings.local.json or
|
|
24
|
+
* anything else machine-local from .claude/. */
|
|
25
|
+
export const TEMPLATE_CLAUDE_SETTINGS = ".claude/settings.json";
|
|
26
|
+
/** Junk that must never land in the bundle. */
|
|
27
|
+
const JUNK_PATH = /(^|\/)(__pycache__(\/|$)|\.DS_Store$)|\.pyc$/;
|
|
28
|
+
/**
|
|
29
|
+
* Re-sync the workspace-root template bundle (root docs + skills/ +
|
|
30
|
+
* .claude/settings.json) from the canonical files at the live workspace
|
|
31
|
+
* root. Report-only by default; `apply` copies drifted/missing files in and
|
|
32
|
+
* deletes bundle skills that no longer exist at the root. Only ever writes
|
|
33
|
+
* inside templates/workspace-root/ — and never reads or copies `.env`,
|
|
34
|
+
* settings.local.json, or anything machine-local.
|
|
35
|
+
*/
|
|
36
|
+
export async function syncTemplates(options) {
|
|
37
|
+
const workspaceDir = resolve(options.workspaceDir);
|
|
38
|
+
const apply = options.apply ?? false;
|
|
39
|
+
for (const marker of ["AGENT.md", "skills"]) {
|
|
40
|
+
if (!existsSync(join(workspaceDir, marker))) {
|
|
41
|
+
throw new Error(`${workspaceDir} does not look like the installagent/ workspace root (no ${marker}) — the canonical docs/skills live there`);
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
const templateDir = join(workspaceDir, "team-tools", "packages", "sdk", "templates", "workspace-root");
|
|
45
|
+
if (!existsSync(templateDir)) {
|
|
46
|
+
throw new Error(`${templateDir} not found — syncing needs the team-tools checkout at the workspace root`);
|
|
47
|
+
}
|
|
48
|
+
// The canonical set, bundle-relative → absolute source path.
|
|
49
|
+
const sources = new Map();
|
|
50
|
+
for (const doc of TEMPLATE_ROOT_DOCS) {
|
|
51
|
+
const abs = join(workspaceDir, doc);
|
|
52
|
+
if (existsSync(abs))
|
|
53
|
+
sources.set(doc, abs);
|
|
54
|
+
}
|
|
55
|
+
for (const rel of await listFiles(join(workspaceDir, "skills"))) {
|
|
56
|
+
if (JUNK_PATH.test(rel))
|
|
57
|
+
continue;
|
|
58
|
+
sources.set(`skills/${rel}`, join(workspaceDir, "skills", rel));
|
|
59
|
+
}
|
|
60
|
+
const claudeSettings = join(workspaceDir, ".claude", "settings.json");
|
|
61
|
+
if (existsSync(claudeSettings))
|
|
62
|
+
sources.set(TEMPLATE_CLAUDE_SETTINGS, claudeSettings);
|
|
63
|
+
const files = [];
|
|
64
|
+
for (const [rel, sourcePath] of sources) {
|
|
65
|
+
const bundlePath = join(templateDir, rel);
|
|
66
|
+
let status;
|
|
67
|
+
if (!existsSync(bundlePath)) {
|
|
68
|
+
status = "missing";
|
|
69
|
+
}
|
|
70
|
+
else {
|
|
71
|
+
const same = (await readFile(sourcePath)).equals(await readFile(bundlePath));
|
|
72
|
+
status = same ? "in-sync" : "drifted";
|
|
73
|
+
}
|
|
74
|
+
if (apply && status !== "in-sync") {
|
|
75
|
+
await mkdir(dirname(bundlePath), { recursive: true });
|
|
76
|
+
await copyFile(sourcePath, bundlePath);
|
|
77
|
+
status = "fixed";
|
|
78
|
+
}
|
|
79
|
+
files.push({ file: rel, status });
|
|
80
|
+
}
|
|
81
|
+
// Bundle-only skills: deleted (or junk) at the root, so they leave the
|
|
82
|
+
// bundle too — mirroring the old `rm -rf skills && cp -R` procedure.
|
|
83
|
+
const bundleSkillsDir = join(templateDir, "skills");
|
|
84
|
+
if (existsSync(bundleSkillsDir)) {
|
|
85
|
+
for (const rel of await listFiles(bundleSkillsDir)) {
|
|
86
|
+
const bundleRel = `skills/${rel}`;
|
|
87
|
+
if (sources.has(bundleRel))
|
|
88
|
+
continue;
|
|
89
|
+
let status = "stale";
|
|
90
|
+
if (apply) {
|
|
91
|
+
await rm(join(bundleSkillsDir, rel), { force: true });
|
|
92
|
+
status = "removed";
|
|
93
|
+
}
|
|
94
|
+
files.push({ file: bundleRel, status });
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
files.sort((a, b) => a.file.localeCompare(b.file));
|
|
98
|
+
const changedCount = files.filter((f) => f.status !== "in-sync").length;
|
|
99
|
+
const nextSteps = apply && changedCount > 0
|
|
100
|
+
? [
|
|
101
|
+
"review the diff before committing: `git -C team-tools diff packages/sdk/templates/workspace-root` — the bundle is copied verbatim to every technician's machine, so check nothing secret-shaped or client-specific slipped into the root docs",
|
|
102
|
+
"run `pnpm -r test` in team-tools (the init tests assert the expected doc set)",
|
|
103
|
+
"commit in team-tools with a message noting which root docs changed",
|
|
104
|
+
]
|
|
105
|
+
: !apply && changedCount > 0
|
|
106
|
+
? ["re-run with --apply to write the bundle, then review/test/commit in team-tools"]
|
|
107
|
+
: [];
|
|
108
|
+
return { workspaceDir, templateDir, files, changedCount, applied: apply, nextSteps };
|
|
109
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Files that must stay byte-identical between clients/client-template/ and
|
|
3
|
+
* every clients/client-<slug>/ repo — the enforcement chain (the lint script
|
|
4
|
+
* plus the hooks/CI that run it) and CADENCE.md (the shipping contract). Drift
|
|
5
|
+
* here means a repo silently stops enforcing the current skeleton rules. This
|
|
6
|
+
* isn't hypothetical: three client-<slug> repos were found running a
|
|
7
|
+
* pre-2026-07 repo-lint.mjs that still required the retired diagrams/ +
|
|
8
|
+
* client-facing/ dirs instead of data/ — nobody had re-synced them since
|
|
9
|
+
* client-template moved on.
|
|
10
|
+
*
|
|
11
|
+
* CADENCE.md carries no client-specific content by design (per-client process
|
|
12
|
+
* quirks belong in that repo's AGENT.md), so it syncs verbatim: one contract,
|
|
13
|
+
* one wording, every engagement.
|
|
14
|
+
*
|
|
15
|
+
* repo-lint's own test file rides along because lefthook runs it whenever
|
|
16
|
+
* ci/ changes — syncing the lint without its test leaves every repo running
|
|
17
|
+
* (or failing on) assertions about a previous skeleton. AGENT.md, CLIENT.md,
|
|
18
|
+
* and onboarding.html are deliberately NOT here: they're per-client by
|
|
19
|
+
* design, so byte-drift is expected, and repo-lint already enforces their
|
|
20
|
+
* presence.
|
|
21
|
+
*/
|
|
22
|
+
export declare const TEMPLATE_SYNCED_FILES: string[];
|
|
23
|
+
export interface TemplateSyncOptions {
|
|
24
|
+
/** The installagent/ workspace root (the dir that contains clients/). */
|
|
25
|
+
workspaceDir: string;
|
|
26
|
+
/** Repo-relative paths to compare; defaults to TEMPLATE_SYNCED_FILES. */
|
|
27
|
+
files?: string[];
|
|
28
|
+
/** Copy the template's version over any drifted/missing file. Default false — report only. */
|
|
29
|
+
apply?: boolean;
|
|
30
|
+
}
|
|
31
|
+
export type TemplateSyncFileStatus = "in-sync" | "drifted" | "missing" | "fixed";
|
|
32
|
+
export interface TemplateSyncFileResult {
|
|
33
|
+
file: string;
|
|
34
|
+
status: TemplateSyncFileStatus;
|
|
35
|
+
}
|
|
36
|
+
export interface TemplateSyncRepoResult {
|
|
37
|
+
slug: string;
|
|
38
|
+
dir: string;
|
|
39
|
+
files: TemplateSyncFileResult[];
|
|
40
|
+
inSync: boolean;
|
|
41
|
+
}
|
|
42
|
+
export interface TemplateSyncResult {
|
|
43
|
+
templateDir: string;
|
|
44
|
+
files: string[];
|
|
45
|
+
repos: TemplateSyncRepoResult[];
|
|
46
|
+
driftedRepoCount: number;
|
|
47
|
+
applied: boolean;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Compare (and optionally fix) the shared infra files every client-<slug>
|
|
51
|
+
* build repo copies verbatim from client-template at creation time. Never
|
|
52
|
+
* touches anything outside those named files — no client content, no
|
|
53
|
+
* registry, no Airtable.
|
|
54
|
+
*/
|
|
55
|
+
export declare function templateSync(options: TemplateSyncOptions): Promise<TemplateSyncResult>;
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { existsSync } from "node:fs";
|
|
2
|
+
import { copyFile, mkdir, readdir, readFile } from "node:fs/promises";
|
|
3
|
+
import { dirname, join, resolve } from "node:path";
|
|
4
|
+
/**
|
|
5
|
+
* Files that must stay byte-identical between clients/client-template/ and
|
|
6
|
+
* every clients/client-<slug>/ repo — the enforcement chain (the lint script
|
|
7
|
+
* plus the hooks/CI that run it) and CADENCE.md (the shipping contract). Drift
|
|
8
|
+
* here means a repo silently stops enforcing the current skeleton rules. This
|
|
9
|
+
* isn't hypothetical: three client-<slug> repos were found running a
|
|
10
|
+
* pre-2026-07 repo-lint.mjs that still required the retired diagrams/ +
|
|
11
|
+
* client-facing/ dirs instead of data/ — nobody had re-synced them since
|
|
12
|
+
* client-template moved on.
|
|
13
|
+
*
|
|
14
|
+
* CADENCE.md carries no client-specific content by design (per-client process
|
|
15
|
+
* quirks belong in that repo's AGENT.md), so it syncs verbatim: one contract,
|
|
16
|
+
* one wording, every engagement.
|
|
17
|
+
*
|
|
18
|
+
* repo-lint's own test file rides along because lefthook runs it whenever
|
|
19
|
+
* ci/ changes — syncing the lint without its test leaves every repo running
|
|
20
|
+
* (or failing on) assertions about a previous skeleton. AGENT.md, CLIENT.md,
|
|
21
|
+
* and onboarding.html are deliberately NOT here: they're per-client by
|
|
22
|
+
* design, so byte-drift is expected, and repo-lint already enforces their
|
|
23
|
+
* presence.
|
|
24
|
+
*/
|
|
25
|
+
export const TEMPLATE_SYNCED_FILES = [
|
|
26
|
+
"CADENCE.md",
|
|
27
|
+
"ci/repo-lint.mjs",
|
|
28
|
+
"ci/repo-lint.test.mjs",
|
|
29
|
+
"lefthook.yml",
|
|
30
|
+
".github/workflows/repo-lint.yml",
|
|
31
|
+
];
|
|
32
|
+
/**
|
|
33
|
+
* Compare (and optionally fix) the shared infra files every client-<slug>
|
|
34
|
+
* build repo copies verbatim from client-template at creation time. Never
|
|
35
|
+
* touches anything outside those named files — no client content, no
|
|
36
|
+
* registry, no Airtable.
|
|
37
|
+
*/
|
|
38
|
+
export async function templateSync(options) {
|
|
39
|
+
const workspaceDir = resolve(options.workspaceDir);
|
|
40
|
+
const templateDir = join(workspaceDir, "clients", "client-template");
|
|
41
|
+
if (!existsSync(templateDir)) {
|
|
42
|
+
throw new Error(`${templateDir} not found — this operation compares against the local client-template checkout`);
|
|
43
|
+
}
|
|
44
|
+
const files = options.files ?? TEMPLATE_SYNCED_FILES;
|
|
45
|
+
const apply = options.apply ?? false;
|
|
46
|
+
const clientsDir = join(workspaceDir, "clients");
|
|
47
|
+
const entries = existsSync(clientsDir) ? await readdir(clientsDir, { withFileTypes: true }) : [];
|
|
48
|
+
const slugs = entries
|
|
49
|
+
.filter((entry) => entry.isDirectory() && entry.name.startsWith("client-") && entry.name !== "client-template")
|
|
50
|
+
.map((entry) => entry.name.slice("client-".length))
|
|
51
|
+
.sort();
|
|
52
|
+
const repos = [];
|
|
53
|
+
for (const slug of slugs) {
|
|
54
|
+
const dir = join(clientsDir, `client-${slug}`);
|
|
55
|
+
const fileResults = [];
|
|
56
|
+
for (const rel of files) {
|
|
57
|
+
const templateFile = join(templateDir, rel);
|
|
58
|
+
if (!existsSync(templateFile))
|
|
59
|
+
continue; // nothing to compare against
|
|
60
|
+
const templateContent = await readFile(templateFile, "utf8");
|
|
61
|
+
const repoFile = join(dir, rel);
|
|
62
|
+
const repoExists = existsSync(repoFile);
|
|
63
|
+
const repoContent = repoExists ? await readFile(repoFile, "utf8") : undefined;
|
|
64
|
+
let status = !repoExists
|
|
65
|
+
? "missing"
|
|
66
|
+
: repoContent === templateContent
|
|
67
|
+
? "in-sync"
|
|
68
|
+
: "drifted";
|
|
69
|
+
if (apply && status !== "in-sync") {
|
|
70
|
+
await mkdir(dirname(repoFile), { recursive: true });
|
|
71
|
+
await copyFile(templateFile, repoFile);
|
|
72
|
+
status = "fixed";
|
|
73
|
+
}
|
|
74
|
+
fileResults.push({ file: rel, status });
|
|
75
|
+
}
|
|
76
|
+
repos.push({
|
|
77
|
+
slug,
|
|
78
|
+
dir,
|
|
79
|
+
files: fileResults,
|
|
80
|
+
inSync: fileResults.every((f) => f.status === "in-sync" || f.status === "fixed"),
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
return {
|
|
84
|
+
templateDir,
|
|
85
|
+
files,
|
|
86
|
+
repos,
|
|
87
|
+
driftedRepoCount: repos.filter((r) => !r.inSync).length,
|
|
88
|
+
applied: apply,
|
|
89
|
+
};
|
|
90
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Absolute path to the bundled workspace-root template assets
|
|
3
|
+
* (templates/workspace-root/ inside this package): the installagent/ root
|
|
4
|
+
* orientation docs plus the skills/ directory. These exist only as loose,
|
|
5
|
+
* ungitted files at the live workspace root — there is no repo to clone them
|
|
6
|
+
* from — so `ia init` ships a copy. See docs/spec.md for the rationale and
|
|
7
|
+
* the re-sync caveat.
|
|
8
|
+
*
|
|
9
|
+
* Resolved relative to this module so it works both from src/ (tsx) and
|
|
10
|
+
* dist/ (built) — both sit one level below the package root.
|
|
11
|
+
*/
|
|
12
|
+
export declare function workspaceRootTemplateDir(): string;
|
|
13
|
+
/**
|
|
14
|
+
* The bundled root-.env placeholder layout (all var names, no values).
|
|
15
|
+
* Kept OUTSIDE templates/workspace-root/ on purpose: that tree is synced
|
|
16
|
+
* verbatim from the live root (which must never contain a committed .env),
|
|
17
|
+
* and wizard treats .env specially — created once, never overwritten.
|
|
18
|
+
*/
|
|
19
|
+
export declare function envExampleTemplatePath(): string;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { fileURLToPath } from "node:url";
|
|
2
|
+
/**
|
|
3
|
+
* Absolute path to the bundled workspace-root template assets
|
|
4
|
+
* (templates/workspace-root/ inside this package): the installagent/ root
|
|
5
|
+
* orientation docs plus the skills/ directory. These exist only as loose,
|
|
6
|
+
* ungitted files at the live workspace root — there is no repo to clone them
|
|
7
|
+
* from — so `ia init` ships a copy. See docs/spec.md for the rationale and
|
|
8
|
+
* the re-sync caveat.
|
|
9
|
+
*
|
|
10
|
+
* Resolved relative to this module so it works both from src/ (tsx) and
|
|
11
|
+
* dist/ (built) — both sit one level below the package root.
|
|
12
|
+
*/
|
|
13
|
+
export function workspaceRootTemplateDir() {
|
|
14
|
+
return fileURLToPath(new URL("../templates/workspace-root", import.meta.url));
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* The bundled root-.env placeholder layout (all var names, no values).
|
|
18
|
+
* Kept OUTSIDE templates/workspace-root/ on purpose: that tree is synced
|
|
19
|
+
* verbatim from the live root (which must never contain a committed .env),
|
|
20
|
+
* and wizard treats .env specially — created once, never overwritten.
|
|
21
|
+
*/
|
|
22
|
+
export function envExampleTemplatePath() {
|
|
23
|
+
return fileURLToPath(new URL("../templates/env.example", import.meta.url));
|
|
24
|
+
}
|