@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.
Files changed (94) hide show
  1. package/dist/agent-templates.d.ts +90 -0
  2. package/dist/agent-templates.js +211 -0
  3. package/dist/client-build.d.ts +50 -0
  4. package/dist/client-build.js +155 -0
  5. package/dist/client-context.d.ts +40 -0
  6. package/dist/client-context.js +70 -0
  7. package/dist/client-drive.d.ts +67 -0
  8. package/dist/client-drive.js +278 -0
  9. package/dist/client-intake.d.ts +68 -0
  10. package/dist/client-intake.js +189 -0
  11. package/dist/client-linear.d.ts +30 -0
  12. package/dist/client-linear.js +85 -0
  13. package/dist/docs-search.d.ts +44 -0
  14. package/dist/docs-search.js +187 -0
  15. package/dist/doctor.d.ts +43 -0
  16. package/dist/doctor.js +425 -0
  17. package/dist/env-file.d.ts +25 -0
  18. package/dist/env-file.js +69 -0
  19. package/dist/env-fill.d.ts +43 -0
  20. package/dist/env-fill.js +161 -0
  21. package/dist/env-push.d.ts +37 -0
  22. package/dist/env-push.js +137 -0
  23. package/dist/env-registry.d.ts +49 -0
  24. package/dist/env-registry.js +230 -0
  25. package/dist/exec.d.ts +14 -0
  26. package/dist/exec.js +16 -0
  27. package/dist/fathom-webhook.d.ts +44 -0
  28. package/dist/fathom-webhook.js +123 -0
  29. package/dist/fs-utils.d.ts +9 -0
  30. package/dist/fs-utils.js +34 -0
  31. package/dist/gcp-service-account-key.d.ts +37 -0
  32. package/dist/gcp-service-account-key.js +66 -0
  33. package/dist/gemini-api-key.d.ts +47 -0
  34. package/dist/gemini-api-key.js +132 -0
  35. package/dist/git.d.ts +16 -0
  36. package/dist/git.js +29 -0
  37. package/dist/github-token.d.ts +24 -0
  38. package/dist/github-token.js +30 -0
  39. package/dist/index.d.ts +25 -0
  40. package/dist/index.js +28 -0
  41. package/dist/init.d.ts +47 -0
  42. package/dist/init.js +101 -0
  43. package/dist/linear-project.d.ts +81 -0
  44. package/dist/linear-project.js +192 -0
  45. package/dist/new-client.d.ts +32 -0
  46. package/dist/new-client.js +89 -0
  47. package/dist/ping.d.ts +6 -0
  48. package/dist/ping.js +7 -0
  49. package/dist/portal-admin.d.ts +133 -0
  50. package/dist/portal-admin.js +144 -0
  51. package/dist/sync-templates.d.ts +58 -0
  52. package/dist/sync-templates.js +109 -0
  53. package/dist/template-sync.d.ts +55 -0
  54. package/dist/template-sync.js +90 -0
  55. package/dist/templates.d.ts +19 -0
  56. package/dist/templates.js +24 -0
  57. package/dist/wizard.d.ts +78 -0
  58. package/dist/wizard.js +213 -0
  59. package/package.json +30 -0
  60. package/templates/env.example +60 -0
  61. package/templates/workspace-root/.claude/settings.json +39 -0
  62. package/templates/workspace-root/AGENT.md +205 -0
  63. package/templates/workspace-root/AGENTS.md +11 -0
  64. package/templates/workspace-root/CLAUDE.md +63 -0
  65. package/templates/workspace-root/GEMINI.md +24 -0
  66. package/templates/workspace-root/ONBOARDING.md +164 -0
  67. package/templates/workspace-root/README.md +67 -0
  68. package/templates/workspace-root/skills/CLAUDE.md +79 -0
  69. package/templates/workspace-root/skills/client-deliverables/SKILL.md +131 -0
  70. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +103 -0
  71. package/templates/workspace-root/skills/client-facing-docs/SKILL.md +131 -0
  72. package/templates/workspace-root/skills/client-facing-docs/references/doc-structures.md +81 -0
  73. package/templates/workspace-root/skills/client-llm-setup/SKILL.md +97 -0
  74. package/templates/workspace-root/skills/client-llm-setup/references/guide-template.md +87 -0
  75. package/templates/workspace-root/skills/client-workflow-diagram/SKILL.md +141 -0
  76. package/templates/workspace-root/skills/client-workflow-diagram/references/excalidraw-format.md +140 -0
  77. package/templates/workspace-root/skills/contract-tech-agnostic/SKILL.md +99 -0
  78. package/templates/workspace-root/skills/contract-tech-agnostic/references/Install_Agent_SOW_Template.docx +0 -0
  79. package/templates/workspace-root/skills/design-system/SKILL.md +118 -0
  80. package/templates/workspace-root/skills/design-system/references/tokens.md +139 -0
  81. package/templates/workspace-root/skills/engagement-spec/SKILL.md +272 -0
  82. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +220 -0
  83. package/templates/workspace-root/skills/house-voice/SKILL.md +158 -0
  84. package/templates/workspace-root/skills/house-voice/references/source-copy.md +173 -0
  85. package/templates/workspace-root/skills/ia-cli/SKILL.md +87 -0
  86. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +112 -0
  87. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-logo.svg +1 -0
  88. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-mark.svg +1 -0
  89. package/templates/workspace-root/skills/installagent-brand-kit/references/brand-tokens.md +71 -0
  90. package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +66 -0
  91. package/templates/workspace-root/skills/installagent-brand-kit/references/excalidraw-red-theme.md +73 -0
  92. package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +175 -0
  93. package/templates/workspace-root/skills/linear/SKILL.md +186 -0
  94. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +141 -0
package/dist/index.js ADDED
@@ -0,0 +1,28 @@
1
+ // @installagent/sdk — the only place with real logic. apps/cli and
2
+ // apps/mcp are thin adapters over these exports; every operation here must be
3
+ // reachable from both. See ../../docs/spec.md.
4
+ export { createFromAgentTemplate, listAgentTemplates, N8N_API_KEY_ENV, N8N_API_URL_ENV, N8nAuthError, sanitizeN8nWorkflow, saveAgentTemplate, } from "./agent-templates.js";
5
+ export { ClientBuildAuthError, clientBuild, GITHUB_API_TOKEN_ENV, } from "./client-build.js";
6
+ export { clientContext, } from "./client-context.js";
7
+ export { AIRTABLE_API_TOKEN_ENV, buildAssertionClaims, ClientDriveAuthError, clientDriveSearch, GOOGLE_SERVICE_ACCOUNT_KEY_ENV, parseServiceAccountKey, } from "./client-drive.js";
8
+ export { ClientIntakeAuthError, clientIntake, LINEAR_CLIENT_TEAM_ID_ENV, } from "./client-intake.js";
9
+ export { ClientLinearAuthError, clientLinearProject, } from "./client-linear.js";
10
+ export { DOCS_SESSION_ENV, DocsSessionError, docsSearch, TEAM_DOCS_BASE_URL, } from "./docs-search.js";
11
+ export { doctor, } from "./doctor.js";
12
+ export { findWorkspaceRoot, loadWorkspaceEnv, parseEnvFile, } from "./env-file.js";
13
+ export { envFill, } from "./env-fill.js";
14
+ export { envPush, } from "./env-push.js";
15
+ export { DEFAULT_TECH_VAULT, ENV_VARS, INFRA_VAULT, opSecretReference, renderEnvExample, } from "./env-registry.js";
16
+ export { FATHOM_API_BASE_URL, FATHOM_API_KEY_ENV, FATHOM_INCLUDES, FATHOM_TRIGGERS, mintFathomWebhook, } from "./fathom-webhook.js";
17
+ export { MINT_HANDOFF_WARNING, mintGcpServiceAccountKey, } from "./gcp-service-account-key.js";
18
+ export { DEFAULT_GEMINI_KEY_DISPLAY_NAME, GEMINI_API_TARGET, mintGeminiApiKey, } from "./gemini-api-key.js";
19
+ export { gitClone, gitPullFfOnly } from "./git.js";
20
+ export { GITHUB_TOKEN_FIX, resolveGithubToken, } from "./github-token.js";
21
+ export { CLIENT_TEMPLATE_URL, initWorkspace, MCP_RECOMMENDATIONS, TEAM_CLIENTS_URL, } from "./init.js";
22
+ export { findProjectBySlugId, LINEAR_API_TOKEN_ENV, LinearAuthError, LinearProjectNotFoundError, linearProject, linearProjectIssues, } from "./linear-project.js";
23
+ export { newClient, SLUG_PATTERN, } from "./new-client.js";
24
+ export { ping } from "./ping.js";
25
+ export { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_PASSWORD_WARNING, PORTAL_SYNC_MAX_DAYS, PORTAL_URL_ENV, PortalAdminAuthError, portalAddUser, portalCreateAgent, portalCreateOrg, portalListAgents, portalListOrgs, portalSetAgentStatus, portalSetDriveFolder, portalSetPassword, portalSyncRuns, } from "./portal-admin.js";
26
+ export { syncTemplates, TEMPLATE_CLAUDE_SETTINGS, TEMPLATE_ROOT_DOCS, } from "./sync-templates.js";
27
+ export { TEMPLATE_SYNCED_FILES, templateSync, } from "./template-sync.js";
28
+ export { WIZARD_REPO_NAMES, wizardWorkspace, } from "./wizard.js";
package/dist/init.d.ts ADDED
@@ -0,0 +1,47 @@
1
+ import { type CloneFn } from "./git.js";
2
+ export declare const TEAM_CLIENTS_URL = "git@github.com:InstallAgent/team-clients.git";
3
+ export declare const CLIENT_TEMPLATE_URL = "git@github.com:InstallAgent/client-template.git";
4
+ export interface InitStep {
5
+ name: string;
6
+ status: "created" | "skipped" | "failed";
7
+ detail: string;
8
+ }
9
+ export interface McpRecommendation {
10
+ name: string;
11
+ why: string;
12
+ }
13
+ /**
14
+ * Connections a technician should add to their own agent setup (Claude Code:
15
+ * `claude mcp add` or claude.ai connector settings). Recommendations only —
16
+ * init never writes MCP config or handles credentials.
17
+ */
18
+ export declare const MCP_RECOMMENDATIONS: McpRecommendation[];
19
+ export interface InitWorkspaceOptions {
20
+ /** Directory to set up as the installagent/ workspace root. */
21
+ dir: string;
22
+ teamClientsUrl?: string;
23
+ clientTemplateUrl?: string;
24
+ /** Injectable for tests; defaults to real `git clone`. */
25
+ clone?: CloneFn;
26
+ }
27
+ export interface InitWorkspaceResult {
28
+ ok: boolean;
29
+ dir: string;
30
+ steps: InitStep[];
31
+ /** Workspace-root doc/skill files laid down from the bundled templates. */
32
+ docsCreated: string[];
33
+ /** Template files that already existed and were left untouched. */
34
+ docsSkipped: string[];
35
+ mcpRecommendations: McpRecommendation[];
36
+ }
37
+ /**
38
+ * Bootstrap a technician's local installagent/ workspace — selectively:
39
+ * clone team-clients and client-template, create an empty clients/ dir, and
40
+ * lay down the root orientation docs + skills/ from the bundled templates.
41
+ *
42
+ * Idempotent: anything that already exists is skipped, never overwritten, so
43
+ * re-running in a set-up workspace can't clobber uncommitted work. The other
44
+ * client-<slug> repos are deliberately NOT cloned — technicians clone only
45
+ * the client(s) they're assigned.
46
+ */
47
+ export declare function initWorkspace(options: InitWorkspaceOptions): Promise<InitWorkspaceResult>;
package/dist/init.js ADDED
@@ -0,0 +1,101 @@
1
+ import { existsSync } from "node:fs";
2
+ import { copyFile, mkdir } from "node:fs/promises";
3
+ import { dirname, join, resolve } from "node:path";
4
+ import { listFiles } from "./fs-utils.js";
5
+ import { gitClone } from "./git.js";
6
+ import { workspaceRootTemplateDir } from "./templates.js";
7
+ export const TEAM_CLIENTS_URL = "git@github.com:InstallAgent/team-clients.git";
8
+ export const CLIENT_TEMPLATE_URL = "git@github.com:InstallAgent/client-template.git";
9
+ /**
10
+ * Connections a technician should add to their own agent setup (Claude Code:
11
+ * `claude mcp add` or claude.ai connector settings). Recommendations only —
12
+ * init never writes MCP config or handles credentials.
13
+ */
14
+ export const MCP_RECOMMENDATIONS = [
15
+ {
16
+ name: "GitHub",
17
+ why: "PRs, issues, and repo operations across the InstallAgent org",
18
+ },
19
+ {
20
+ name: "Slack",
21
+ why: "the team comms rail — read threads, post updates",
22
+ },
23
+ {
24
+ name: "Airtable",
25
+ why: "CRM of record — read deal/client status (read-only: tools must never write to Airtable)",
26
+ },
27
+ {
28
+ name: "Google Drive",
29
+ why: "per-client folders — signed documents and intake assets live there, not in git",
30
+ },
31
+ ];
32
+ /**
33
+ * Bootstrap a technician's local installagent/ workspace — selectively:
34
+ * clone team-clients and client-template, create an empty clients/ dir, and
35
+ * lay down the root orientation docs + skills/ from the bundled templates.
36
+ *
37
+ * Idempotent: anything that already exists is skipped, never overwritten, so
38
+ * re-running in a set-up workspace can't clobber uncommitted work. The other
39
+ * client-<slug> repos are deliberately NOT cloned — technicians clone only
40
+ * the client(s) they're assigned.
41
+ */
42
+ export async function initWorkspace(options) {
43
+ const dir = resolve(options.dir);
44
+ const clone = options.clone ?? gitClone;
45
+ const steps = [];
46
+ await mkdir(dir, { recursive: true });
47
+ const cloneStep = async (name, url, dest) => {
48
+ if (existsSync(dest)) {
49
+ steps.push({ name, status: "skipped", detail: `${name} already exists — left untouched` });
50
+ return;
51
+ }
52
+ try {
53
+ await clone(url, dest);
54
+ steps.push({ name, status: "created", detail: `cloned ${url}` });
55
+ }
56
+ catch (error) {
57
+ const detail = error instanceof Error ? error.message : String(error);
58
+ steps.push({ name, status: "failed", detail });
59
+ }
60
+ };
61
+ await cloneStep("team-clients/", options.teamClientsUrl ?? TEAM_CLIENTS_URL, join(dir, "team-clients"));
62
+ const clientsDir = join(dir, "clients");
63
+ if (existsSync(clientsDir)) {
64
+ steps.push({ name: "clients/", status: "skipped", detail: "clients/ already exists" });
65
+ }
66
+ else {
67
+ await mkdir(clientsDir, { recursive: true });
68
+ steps.push({
69
+ name: "clients/",
70
+ status: "created",
71
+ detail: "empty clients/ dir — clone or create only the client repos you work on",
72
+ });
73
+ }
74
+ await cloneStep("clients/client-template/", options.clientTemplateUrl ?? CLIENT_TEMPLATE_URL, join(clientsDir, "client-template"));
75
+ const templateDir = workspaceRootTemplateDir();
76
+ const docsCreated = [];
77
+ const docsSkipped = [];
78
+ for (const rel of await listFiles(templateDir)) {
79
+ const target = join(dir, rel);
80
+ if (existsSync(target)) {
81
+ docsSkipped.push(rel);
82
+ continue;
83
+ }
84
+ await mkdir(dirname(target), { recursive: true });
85
+ await copyFile(join(templateDir, rel), target);
86
+ docsCreated.push(rel);
87
+ }
88
+ steps.push({
89
+ name: "root docs + skills/",
90
+ status: docsCreated.length > 0 ? "created" : "skipped",
91
+ detail: `${docsCreated.length} file(s) created, ${docsSkipped.length} already present`,
92
+ });
93
+ return {
94
+ ok: steps.every((step) => step.status !== "failed"),
95
+ dir,
96
+ steps,
97
+ docsCreated,
98
+ docsSkipped,
99
+ mcpRecommendations: MCP_RECOMMENDATIONS,
100
+ };
101
+ }
@@ -0,0 +1,81 @@
1
+ export declare const LINEAR_API_TOKEN_ENV = "LINEAR_API_TOKEN";
2
+ export interface LinearIssue {
3
+ identifier: string;
4
+ title: string;
5
+ url: string;
6
+ state: string;
7
+ stateType: string;
8
+ priorityLabel: string;
9
+ assignee: string | null;
10
+ labels: string[];
11
+ updatedAt: string;
12
+ }
13
+ export interface LinearProjectResult {
14
+ project: {
15
+ id: string;
16
+ name: string;
17
+ url: string;
18
+ };
19
+ query?: string;
20
+ label?: string;
21
+ issues: LinearIssue[];
22
+ }
23
+ export interface LinearProjectOptions {
24
+ /** Search term(s), scored against title + description; omit for the full open-issue list. */
25
+ query?: string;
26
+ /** Restrict to issues carrying this label (case-insensitive exact match). */
27
+ label?: string;
28
+ /** Max issues returned (default 5 with a query, 30 without). */
29
+ limit?: number;
30
+ /** Linear API key; defaults to $LINEAR_API_TOKEN. */
31
+ token?: string;
32
+ /** Injectable for tests; defaults to global fetch. */
33
+ fetchImpl?: typeof fetch;
34
+ }
35
+ /** Thrown when the Linear API key is missing or rejected. */
36
+ export declare class LinearAuthError extends Error {
37
+ }
38
+ /** Thrown when no project (or more than one) matches the given name. */
39
+ export declare class LinearProjectNotFoundError extends Error {
40
+ }
41
+ export interface ProjectNode {
42
+ id: string;
43
+ name: string;
44
+ url: string;
45
+ }
46
+ /** Exported so client-intake.ts can reuse the auth/error handling for its project-create mutation. */
47
+ export declare function linearRequest<T>(fetchImpl: typeof fetch, token: string, query: string, variables: Record<string, unknown>): Promise<T>;
48
+ /**
49
+ * Resolve a project by its exact `slugId` (the opaque trailing path segment
50
+ * of a `linear.app/.../project/<slugId>` URL) rather than its display name —
51
+ * unambiguous, and stable across a project rename. Used for client
52
+ * engagements, whose Linear project is recorded by URL (`CLIENT.md`'s
53
+ * `linear_project` field), never by a name a caller would have to guess.
54
+ */
55
+ export declare function findProjectBySlugId(fetchImpl: typeof fetch, token: string, slugId: string): Promise<ProjectNode>;
56
+ /**
57
+ * Open (not completed/canceled/duplicate) issues in an already-resolved
58
+ * Linear project — "what's left to do" for that project. Either returns the
59
+ * full open-issue index (no `query`) or ranks issues by term matches in
60
+ * title + description (with `query`), same scoring shape as clientBuild and
61
+ * docsSearch. `label` narrows to issues carrying that label first, before
62
+ * query scoring or the index sort — useful for a project that tracks more
63
+ * than one initiative's backlog (e.g. Install Agent's internal "Operations"
64
+ * project) or, for a client project, just as an extra filter.
65
+ *
66
+ * Strictly read-only: only ever sends GraphQL queries, never mutations.
67
+ * Shared by `linearProject` (resolves by name) and `clientLinearProject`
68
+ * (resolves by slug via the client's CLIENT.md) once each has a ProjectNode.
69
+ */
70
+ export declare function linearProjectIssues(fetchImpl: typeof fetch, token: string, project: ProjectNode, options?: LinearProjectOptions): Promise<LinearProjectResult>;
71
+ /**
72
+ * Open issues in a Linear project, resolved by display name (exact match,
73
+ * then a case-insensitive fuzzy fallback that refuses with the candidate
74
+ * list if ambiguous). For Install Agent's internal backlog — e.g. the
75
+ * "Operations" project — where there's no per-client record to resolve a
76
+ * stable ID from. For a client engagement's Linear project, use
77
+ * `clientLinearProject` instead: it resolves by the client's own
78
+ * `CLIENT.md` record rather than a guessed or typed name, and applies the
79
+ * same client-channel guard as the other client tools.
80
+ */
81
+ export declare function linearProject(projectName: string, options?: LinearProjectOptions): Promise<LinearProjectResult>;
@@ -0,0 +1,192 @@
1
+ const LINEAR_API_URL = "https://api.linear.app/graphql";
2
+ export const LINEAR_API_TOKEN_ENV = "LINEAR_API_TOKEN";
3
+ const DEFAULT_QUERY_LIMIT = 5;
4
+ const DEFAULT_INDEX_LIMIT = 30;
5
+ const ISSUE_FETCH_PAGE_SIZE = 250;
6
+ // "duplicate" is its own WorkflowState type distinct from "canceled" — both
7
+ // mean "not left to do" for this tool's purpose.
8
+ const CLOSED_STATE_TYPES = ["completed", "canceled", "duplicate"];
9
+ // Rank actionable work first: in progress, then queued, then triage.
10
+ const STATE_TYPE_RANK = { started: 0, unstarted: 1, backlog: 2, triage: 3 };
11
+ /** Thrown when the Linear API key is missing or rejected. */
12
+ export class LinearAuthError extends Error {
13
+ }
14
+ /** Thrown when no project (or more than one) matches the given name. */
15
+ export class LinearProjectNotFoundError extends Error {
16
+ }
17
+ /** Exported so client-intake.ts can reuse the auth/error handling for its project-create mutation. */
18
+ export async function linearRequest(fetchImpl, token, query, variables) {
19
+ const res = await fetchImpl(LINEAR_API_URL, {
20
+ method: "POST",
21
+ headers: { Authorization: token, "Content-Type": "application/json" },
22
+ body: JSON.stringify({ query, variables }),
23
+ });
24
+ if (res.status === 401 || res.status === 403) {
25
+ throw new LinearAuthError(`Linear rejected ${LINEAR_API_TOKEN_ENV} (HTTP ${res.status}) — check the API key is valid.`);
26
+ }
27
+ if (!res.ok) {
28
+ throw new Error(`Linear API request failed: HTTP ${res.status}`);
29
+ }
30
+ const body = (await res.json());
31
+ if (body.errors?.length) {
32
+ throw new Error(`Linear API error: ${body.errors.map((e) => e.message).join("; ")}`);
33
+ }
34
+ if (!body.data) {
35
+ throw new Error("Linear API returned no data");
36
+ }
37
+ return body.data;
38
+ }
39
+ const FIND_PROJECT_QUERY = `
40
+ query FindProject($filter: ProjectFilter!) {
41
+ projects(filter: $filter, first: 10) {
42
+ nodes { id name url }
43
+ }
44
+ }
45
+ `;
46
+ async function findProject(fetchImpl, token, name) {
47
+ const exact = await linearRequest(fetchImpl, token, FIND_PROJECT_QUERY, { filter: { name: { eqIgnoreCase: name } } });
48
+ if (exact.projects.nodes.length === 1)
49
+ return exact.projects.nodes[0];
50
+ if (exact.projects.nodes.length > 1) {
51
+ // eqIgnoreCase should be unique per workspace in practice; fall through to
52
+ // the fuzzy candidate-listing error below if it somehow isn't.
53
+ return exact.projects.nodes[0];
54
+ }
55
+ const fuzzy = await linearRequest(fetchImpl, token, FIND_PROJECT_QUERY, { filter: { name: { containsIgnoreCase: name } } });
56
+ if (fuzzy.projects.nodes.length === 1)
57
+ return fuzzy.projects.nodes[0];
58
+ if (fuzzy.projects.nodes.length > 1) {
59
+ const names = fuzzy.projects.nodes.map((p) => `"${p.name}"`).join(", ");
60
+ throw new LinearProjectNotFoundError(`"${name}" matches more than one Linear project: ${names} — use the exact name.`);
61
+ }
62
+ throw new LinearProjectNotFoundError(`No Linear project matching "${name}".`);
63
+ }
64
+ /**
65
+ * Resolve a project by its exact `slugId` (the opaque trailing path segment
66
+ * of a `linear.app/.../project/<slugId>` URL) rather than its display name —
67
+ * unambiguous, and stable across a project rename. Used for client
68
+ * engagements, whose Linear project is recorded by URL (`CLIENT.md`'s
69
+ * `linear_project` field), never by a name a caller would have to guess.
70
+ */
71
+ export async function findProjectBySlugId(fetchImpl, token, slugId) {
72
+ const result = await linearRequest(fetchImpl, token, FIND_PROJECT_QUERY, { filter: { slugId: { eq: slugId } } });
73
+ const project = result.projects.nodes[0];
74
+ if (!project) {
75
+ throw new LinearProjectNotFoundError(`No Linear project with slug id "${slugId}".`);
76
+ }
77
+ return project;
78
+ }
79
+ const PROJECT_ISSUES_QUERY = `
80
+ query ProjectIssues($projectId: ID!, $closedStateTypes: [String!]!, $first: Int!) {
81
+ issues(
82
+ filter: { project: { id: { eq: $projectId } }, state: { type: { nin: $closedStateTypes } } }
83
+ first: $first
84
+ orderBy: updatedAt
85
+ ) {
86
+ nodes {
87
+ identifier
88
+ title
89
+ url
90
+ description
91
+ priorityLabel
92
+ updatedAt
93
+ state { name type }
94
+ assignee { name }
95
+ labels { nodes { name } }
96
+ }
97
+ }
98
+ }
99
+ `;
100
+ function toIssue(node) {
101
+ return {
102
+ identifier: node.identifier,
103
+ title: node.title,
104
+ url: node.url,
105
+ state: node.state.name,
106
+ stateType: node.state.type,
107
+ priorityLabel: node.priorityLabel,
108
+ assignee: node.assignee?.name ?? null,
109
+ labels: node.labels.nodes.map((l) => l.name),
110
+ updatedAt: node.updatedAt,
111
+ };
112
+ }
113
+ function countOccurrences(text, term) {
114
+ return term ? text.split(term).length - 1 : 0;
115
+ }
116
+ /**
117
+ * Open (not completed/canceled/duplicate) issues in an already-resolved
118
+ * Linear project — "what's left to do" for that project. Either returns the
119
+ * full open-issue index (no `query`) or ranks issues by term matches in
120
+ * title + description (with `query`), same scoring shape as clientBuild and
121
+ * docsSearch. `label` narrows to issues carrying that label first, before
122
+ * query scoring or the index sort — useful for a project that tracks more
123
+ * than one initiative's backlog (e.g. Install Agent's internal "Operations"
124
+ * project) or, for a client project, just as an extra filter.
125
+ *
126
+ * Strictly read-only: only ever sends GraphQL queries, never mutations.
127
+ * Shared by `linearProject` (resolves by name) and `clientLinearProject`
128
+ * (resolves by slug via the client's CLIENT.md) once each has a ProjectNode.
129
+ */
130
+ export async function linearProjectIssues(fetchImpl, token, project, options = {}) {
131
+ const { issues } = await linearRequest(fetchImpl, token, PROJECT_ISSUES_QUERY, { projectId: project.id, closedStateTypes: CLOSED_STATE_TYPES, first: ISSUE_FETCH_PAGE_SIZE });
132
+ const label = options.label?.trim() || undefined;
133
+ const candidates = label
134
+ ? issues.nodes.filter((n) => n.labels.nodes.some((l) => l.name.toLowerCase() === label.toLowerCase()))
135
+ : issues.nodes;
136
+ const query = options.query?.trim() || undefined;
137
+ const projectSummary = { id: project.id, name: project.name, url: project.url };
138
+ if (!query) {
139
+ const limit = options.limit ?? DEFAULT_INDEX_LIMIT;
140
+ const sorted = [...candidates].sort((a, b) => {
141
+ const rank = (STATE_TYPE_RANK[a.state.type] ?? 9) - (STATE_TYPE_RANK[b.state.type] ?? 9);
142
+ if (rank !== 0)
143
+ return rank;
144
+ return b.updatedAt.localeCompare(a.updatedAt);
145
+ });
146
+ return { project: projectSummary, label, issues: sorted.slice(0, limit).map(toIssue) };
147
+ }
148
+ const limit = options.limit ?? DEFAULT_QUERY_LIMIT;
149
+ const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
150
+ const scored = candidates
151
+ .map((node) => {
152
+ const title = node.title.toLowerCase();
153
+ const body = (node.description ?? "").toLowerCase();
154
+ let score = 0;
155
+ for (const term of terms) {
156
+ score += countOccurrences(title, term) * 5 + countOccurrences(body, term);
157
+ }
158
+ return { node, score };
159
+ })
160
+ .filter((entry) => entry.score > 0)
161
+ .sort((a, b) => b.score - a.score)
162
+ .slice(0, limit);
163
+ return {
164
+ project: projectSummary,
165
+ query,
166
+ label,
167
+ issues: scored.map(({ node }) => toIssue(node)),
168
+ };
169
+ }
170
+ /**
171
+ * Open issues in a Linear project, resolved by display name (exact match,
172
+ * then a case-insensitive fuzzy fallback that refuses with the candidate
173
+ * list if ambiguous). For Install Agent's internal backlog — e.g. the
174
+ * "Operations" project — where there's no per-client record to resolve a
175
+ * stable ID from. For a client engagement's Linear project, use
176
+ * `clientLinearProject` instead: it resolves by the client's own
177
+ * `CLIENT.md` record rather than a guessed or typed name, and applies the
178
+ * same client-channel guard as the other client tools.
179
+ */
180
+ export async function linearProject(projectName, options = {}) {
181
+ const name = projectName.trim();
182
+ if (!name) {
183
+ throw new Error("linearProject needs a non-empty project name");
184
+ }
185
+ const token = options.token ?? process.env[LINEAR_API_TOKEN_ENV];
186
+ if (!token) {
187
+ throw new LinearAuthError(`Linear API key required — set ${LINEAR_API_TOKEN_ENV} (a personal API key with read access) or pass token`);
188
+ }
189
+ const fetchImpl = options.fetchImpl ?? fetch;
190
+ const project = await findProject(fetchImpl, token, name);
191
+ return linearProjectIssues(fetchImpl, token, project, options);
192
+ }
@@ -0,0 +1,32 @@
1
+ import { type CloneFn } from "./git.js";
2
+ export declare const SLUG_PATTERN: RegExp;
3
+ export interface NewClientOptions {
4
+ /** The installagent/ workspace root (the dir that contains clients/). */
5
+ workspaceDir: string;
6
+ clientTemplateUrl?: string;
7
+ /** Injectable for tests; defaults to real `git clone`. */
8
+ clone?: CloneFn;
9
+ }
10
+ export interface NewClientResult {
11
+ slug: string;
12
+ /** Absolute path of the created clients/client-<slug>/ repo. */
13
+ dir: string;
14
+ /** Whether the local clients/client-template/ was used or a fresh shallow clone. */
15
+ templateSource: "local" | "cloned";
16
+ filesCopied: number;
17
+ /** Files where the <slug> placeholder was substituted. */
18
+ substitutedFiles: string[];
19
+ gitInitialized: boolean;
20
+ nextSteps: string[];
21
+ }
22
+ /**
23
+ * Create a new client BUILD repo: clients/client-template/ →
24
+ * clients/client-<slug>/, substituting the template's literal `<slug>`
25
+ * placeholder. Falls back to a shallow temp clone of client-template when
26
+ * the local copy is missing, so `ia init` is not a hard prerequisite.
27
+ *
28
+ * Build repo only, by design: this never touches team-clients/clients/<slug>/
29
+ * (the registry, which holds PII) and never writes to Airtable (the CRM of
30
+ * record). Registry creation stays a separate, manual, human step.
31
+ */
32
+ export declare function newClient(slug: string, options: NewClientOptions): Promise<NewClientResult>;
@@ -0,0 +1,89 @@
1
+ import { existsSync } from "node:fs";
2
+ import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
3
+ import { tmpdir } from "node:os";
4
+ import { dirname, join, resolve } from "node:path";
5
+ import { listFiles, TEXT_FILE } from "./fs-utils.js";
6
+ import { gitClone, gitInit } from "./git.js";
7
+ import { CLIENT_TEMPLATE_URL } from "./init.js";
8
+ export const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
9
+ /**
10
+ * Create a new client BUILD repo: clients/client-template/ →
11
+ * clients/client-<slug>/, substituting the template's literal `<slug>`
12
+ * placeholder. Falls back to a shallow temp clone of client-template when
13
+ * the local copy is missing, so `ia init` is not a hard prerequisite.
14
+ *
15
+ * Build repo only, by design: this never touches team-clients/clients/<slug>/
16
+ * (the registry, which holds PII) and never writes to Airtable (the CRM of
17
+ * record). Registry creation stays a separate, manual, human step.
18
+ */
19
+ export async function newClient(slug, options) {
20
+ if (slug.startsWith("client-")) {
21
+ throw new Error(`pass the bare slug ("${slug.slice("client-".length)}"), not "${slug}" — the client- prefix is added automatically`);
22
+ }
23
+ if (!SLUG_PATTERN.test(slug)) {
24
+ throw new Error(`invalid slug "${slug}" — use lowercase letters, digits, and hyphens (e.g. "acme-hvac")`);
25
+ }
26
+ const workspaceDir = resolve(options.workspaceDir);
27
+ const targetDir = join(workspaceDir, "clients", `client-${slug}`);
28
+ if (existsSync(targetDir)) {
29
+ throw new Error(`${targetDir} already exists — refusing to overwrite`);
30
+ }
31
+ const localTemplate = join(workspaceDir, "clients", "client-template");
32
+ let templateDir = localTemplate;
33
+ let templateSource = "local";
34
+ let tempDir;
35
+ try {
36
+ if (!existsSync(localTemplate)) {
37
+ tempDir = await mkdtemp(join(tmpdir(), "ia-client-template-"));
38
+ templateDir = join(tempDir, "client-template");
39
+ templateSource = "cloned";
40
+ const clone = options.clone ?? gitClone;
41
+ await clone(options.clientTemplateUrl ?? CLIENT_TEMPLATE_URL, templateDir, { depth: 1 });
42
+ }
43
+ const files = await listFiles(templateDir);
44
+ const substitutedFiles = [];
45
+ for (const rel of files) {
46
+ const src = join(templateDir, rel);
47
+ const dest = join(targetDir, rel);
48
+ await mkdir(dirname(dest), { recursive: true });
49
+ // ci/ is copied verbatim: repo-lint's own rules use the literal
50
+ // `<slug>` token, so substituting there would corrupt the lint.
51
+ if (TEXT_FILE.test(rel) && !rel.startsWith("ci/")) {
52
+ const content = await readFile(src, "utf8");
53
+ if (content.includes("<slug>")) {
54
+ await writeFile(dest, content.replaceAll("<slug>", slug));
55
+ substitutedFiles.push(rel);
56
+ continue;
57
+ }
58
+ }
59
+ await copyFile(src, dest);
60
+ }
61
+ let gitInitialized = false;
62
+ try {
63
+ await gitInit(targetDir);
64
+ gitInitialized = true;
65
+ }
66
+ catch {
67
+ // git unavailable — the copied repo is still usable; surfaced in the result.
68
+ }
69
+ return {
70
+ slug,
71
+ dir: targetDir,
72
+ templateSource,
73
+ filesCopied: files.length,
74
+ substitutedFiles,
75
+ gitInitialized,
76
+ nextSteps: [
77
+ "Fill the remaining CLIENT.md context keys (airtable_record, drive_folder, onepassword_vault) — repo-lint fails until they're real",
78
+ `Create the registry profile in team-clients/clients/${slug}/ manually — this tool never writes to the registry or Airtable`,
79
+ "Run `node ci/repo-lint.mjs` inside the new repo once keys are filled to confirm the skeleton passes",
80
+ `Create the GitHub repo (InstallAgent/client-${slug}) and push when the engagement is real`,
81
+ ],
82
+ };
83
+ }
84
+ finally {
85
+ if (tempDir) {
86
+ await rm(tempDir, { recursive: true, force: true });
87
+ }
88
+ }
89
+ }
package/dist/ping.d.ts ADDED
@@ -0,0 +1,6 @@
1
+ export interface PingResult {
2
+ ok: true;
3
+ service: "installagent-tools-sdk";
4
+ timestamp: string;
5
+ }
6
+ export declare function ping(): PingResult;
package/dist/ping.js ADDED
@@ -0,0 +1,7 @@
1
+ export function ping() {
2
+ return {
3
+ ok: true,
4
+ service: "installagent-tools-sdk",
5
+ timestamp: new Date().toISOString(),
6
+ };
7
+ }