chapterhouse 0.1.1

package/dist/integrations/ado-client.test.js

@@ -0,0 +1,176 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+async function loadAdoClientModule() {
+    try {
+        return await import(new URL(`./ado-client.js?cachebust=${Date.now()}-${Math.random()}`, import.meta.url).href);
+    }
+    catch {
+        return null;
+    }
+}
+test("getKeyResults returns the expected KR shape", async () => {
+    const ado = await loadAdoClientModule();
+    assert.ok(ado, "ado client module should exist");
+    const queries = [];
+    const client = new ado.AdoClient({
+        org: "https://dev.azure.com/example-org",
+        project: "example-project",
+        pat: "test-pat",
+        workItemTrackingApi: {
+            async queryByWiql(wiql, teamContext) {
+                queries.push(`${teamContext?.project ?? ""}:${wiql.query ?? ""}`);
+                return { workItems: [{ id: 101 }] };
+            },
+            async getWorkItems(ids) {
+                assert.deepEqual(ids, [101]);
+                return [
+                    {
+                        id: 101,
+                        fields: {
+                            "System.Title": "Ship SSO to all tenants",
+                            "Custom.CurrentValue": 75,
+                            "Custom.TargetValue": 100,
+                            "Microsoft.VSTS.Common.BusinessValue": "%",
+                            "Custom.OKROwner": "ada@example.com",
+                            "System.Parent": 7,
+                        },
+                    },
+                ];
+            },
+            async updateWorkItem() {
+                throw new Error("not used in this test");
+            },
+            async addComment() {
+                throw new Error("not used in this test");
+            },
+        },
+    });
+    const keyResults = await client.getKeyResults("2026-Q2");
+    assert.equal(queries.length, 1);
+    assert.match(queries[0] ?? "", /Feature/);
+    assert.match(queries[0] ?? "", /Custom\.OKRPeriod/);
+    assert.deepEqual(keyResults, [
+        {
+            id: 101,
+            title: "Ship SSO to all tenants",
+            currentValue: 75,
+            targetValue: 100,
+            unit: "%",
+            owner: "ada@example.com",
+            parentId: 7,
+        },
+    ]);
+});
+test("updateKRProgress sends the expected patch payload", async () => {
+    const ado = await loadAdoClientModule();
+    assert.ok(ado, "ado client module should exist");
+    const updates = [];
+    const comments = [];
+    const client = new ado.AdoClient({
+        org: "https://dev.azure.com/example-org",
+        project: "example-project",
+        pat: "test-pat",
+        workItemTrackingApi: {
+            async queryByWiql() {
+                throw new Error("not used in this test");
+            },
+            async getWorkItems() {
+                throw new Error("not used in this test");
+            },
+            async updateWorkItem(_customHeaders, document, id, project) {
+                updates.push({ id, project, document });
+                return {};
+            },
+            async addComment(request, project, workItemId) {
+                comments.push({ project, workItemId, text: request.text });
+                return {};
+            },
+        },
+    });
+    await client.updateKRProgress(42, 88, "Recovered from rollout issues");
+    assert.equal(updates.length, 1);
+    assert.deepEqual(updates[0], {
+        id: 42,
+        project: "example-project",
+        document: [
+            { op: "add", path: "/fields/Custom.CurrentValue", value: 88 },
+        ],
+    });
+    assert.deepEqual(comments, [
+        {
+            project: "example-project",
+            workItemId: 42,
+            text: "Recovered from rollout issues",
+        },
+    ]);
+});
+test("getOKRSummary computes percent complete from KR progress", async () => {
+    const ado = await loadAdoClientModule();
+    assert.ok(ado, "ado client module should exist");
+    const client = new ado.AdoClient({
+        org: "https://dev.azure.com/example-org",
+        project: "example-project",
+        pat: "test-pat",
+        workItemTrackingApi: {
+            async queryByWiql(wiql) {
+                if ((wiql.query ?? "").includes("[System.WorkItemType] = 'Epic'")) {
+                    return { workItems: [{ id: 7 }] };
+                }
+                if ((wiql.query ?? "").includes("[System.WorkItemType] = 'Feature'")) {
+                    return { workItems: [{ id: 101 }, { id: 102 }] };
+                }
+                throw new Error(`Unexpected query: ${wiql.query ?? ""}`);
+            },
+            async getWorkItems(ids) {
+                if (ids.includes(7)) {
+                    return [
+                        {
+                            id: 7,
+                            fields: {
+                                "System.Title": "Improve identity coverage",
+                                "Custom.OKROwner": "ada@example.com",
+                            },
+                        },
+                    ];
+                }
+                return [
+                    {
+                        id: 101,
+                        fields: {
+                            "System.Title": "Ship SSO to all tenants",
+                            "Custom.CurrentValue": 75,
+                            "Custom.TargetValue": 100,
+                            "Microsoft.VSTS.Common.BusinessValue": "%",
+                            "Custom.OKROwner": "ada@example.com",
+                            "System.Parent": 7,
+                        },
+                    },
+                    {
+                        id: 102,
+                        fields: {
+                            "System.Title": "Migrate legacy auth flows",
+                            "Custom.CurrentValue": 20,
+                            "Custom.TargetValue": 40,
+                            "Microsoft.VSTS.Common.BusinessValue": "%",
+                            "Custom.OKROwner": "ada@example.com",
+                            "System.Parent": 7,
+                        },
+                    },
+                ];
+            },
+            async updateWorkItem() {
+                throw new Error("not used in this test");
+            },
+            async addComment() {
+                throw new Error("not used in this test");
+            },
+        },
+    });
+    const summary = await client.getOKRSummary("2026-Q2");
+    assert.equal(summary.period, "2026-Q2");
+    assert.equal(summary.objectives.length, 1);
+    assert.equal(summary.objectives[0]?.percentComplete, 63);
+    assert.equal(summary.objectives[0]?.keyResults[0]?.percentComplete, 75);
+    assert.equal(summary.objectives[0]?.keyResults[1]?.percentComplete, 50);
+});
+//# sourceMappingURL=ado-client.test.js.map

package/dist/integrations/ado-schema.js

@@ -0,0 +1,25 @@
+import { config } from "../config.js";
+export const ADO_ORG = config.ADO_ORG;
+export const ADO_PROJECT = config.ADO_PROJECT;
+// Work item type mapping
+export const WIT = {
+    OBJECTIVE: "Epic",
+    KEY_RESULT: "Feature",
+};
+// Custom field names (these need to be created in ADO project settings)
+export const FIELDS = {
+    CURRENT_VALUE: "Custom.CurrentValue",
+    TARGET_VALUE: "Custom.TargetValue",
+    OKR_PERIOD: "Custom.OKRPeriod", // e.g. "2026-Q2"
+    OKR_OWNER: "Custom.OKROwner", // email
+};
+// Standard fields we use
+export const STD_FIELDS = {
+    TITLE: "System.Title",
+    STATE: "System.State",
+    PARENT: "System.Parent",
+    ASSIGNED_TO: "System.AssignedTo",
+    TAGS: "System.Tags",
+};
+export const UNIT_FIELD = "Microsoft.VSTS.Common.BusinessValue";
+//# sourceMappingURL=ado-schema.js.map

package/dist/integrations/ado-schema.test.js

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+const REPO_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+test("exports empty ADO settings when runtime config is unset", async () => {
+    const adoSchemaModule = await import(new URL(`./ado-schema.js?cachebust=${Date.now()}-${Math.random()}`, import.meta.url).href);
+    assert.equal(adoSchemaModule.ADO_ORG, "");
+    assert.equal(adoSchemaModule.ADO_PROJECT, "");
+});
+test("exports overridden ADO settings from runtime config", async () => {
+    const result = spawnSync(process.execPath, [
+        "--import",
+        "tsx",
+        "--input-type=module",
+        "--eval",
+        `
+        const mod = await import("./src/integrations/ado-schema.ts");
+        console.log("__RESULT__" + JSON.stringify({ org: mod.ADO_ORG, project: mod.ADO_PROJECT }));
+      `,
+    ], {
+        cwd: REPO_ROOT,
+        env: {
+            ...process.env,
+            ADO_ORG: "https://dev.azure.com/example-org",
+            ADO_PROJECT: "example-project",
+        },
+        encoding: "utf8",
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const outputLine = result.stdout
+        .split("\n")
+        .find((line) => line.startsWith("__RESULT__"));
+    assert.ok(outputLine, "child process should print the imported ADO settings");
+    const output = JSON.parse(outputLine.replace("__RESULT__", ""));
+    assert.equal(output.org, "https://dev.azure.com/example-org");
+    assert.equal(output.project, "example-project");
+});
+//# sourceMappingURL=ado-schema.test.js.map

package/dist/integrations/ado-skill.js

@@ -0,0 +1,55 @@
+import { AdoClient } from "./ado-client.js";
+function getCurrentQuarter(now = new Date()) {
+    return `${now.getUTCFullYear()}-Q${Math.floor(now.getUTCMonth() / 3) + 1}`;
+}
+function formatValue(value, unit) {
+    return unit === "%" ? `${value}%` : `${value}${unit ? ` ${unit}` : ""}`;
+}
+function renderRow(objectiveTitle, keyResult) {
+    return `| ${objectiveTitle} | ${keyResult.title} | ${keyResult.owner || "—"} | ${formatValue(keyResult.currentValue, keyResult.unit)} / ${formatValue(keyResult.targetValue, keyResult.unit)} | ${keyResult.percentComplete}% |`;
+}
+export function formatOKRSummaryMarkdown(summary) {
+    if (summary.objectives.length === 0) {
+        return `## Azure DevOps OKRs for ${summary.period}\n\nNo objectives found.`;
+    }
+    const lines = [
+        `## Azure DevOps OKRs for ${summary.period}`,
+        "",
+        "| Objective | Key Result | Owner | Progress | Complete |",
+        "| --- | --- | --- | --- | --- |",
+    ];
+    for (const objective of summary.objectives) {
+        if (objective.keyResults.length === 0) {
+            lines.push(`| ${objective.title} | _No key results_ | ${objective.owner || "—"} | — | ${objective.percentComplete}% |`);
+            continue;
+        }
+        for (const keyResult of objective.keyResults) {
+            lines.push(renderRow(objective.title, keyResult));
+        }
+    }
+    return lines.join("\n");
+}
+export async function adoGetOkrs(period) {
+    const resolvedPeriod = period?.trim() || getCurrentQuarter();
+    const client = new AdoClient();
+    const summary = await client.getOKRSummary(resolvedPeriod);
+    return formatOKRSummaryMarkdown(summary);
+}
+export async function adoUpdateKr(workItemId, currentValue, notes) {
+    const client = new AdoClient();
+    await client.updateKRProgress(workItemId, currentValue, notes);
+    const keyResult = (await client.getKeyResults()).find((item) => item.id === workItemId);
+    if (!keyResult) {
+        return `Updated Azure DevOps key result #${workItemId}.`;
+    }
+    const percentComplete = keyResult.targetValue > 0
+        ? Math.round((keyResult.currentValue / keyResult.targetValue) * 100)
+        : 0;
+    return `Updated Azure DevOps key result #${workItemId} to ${keyResult.currentValue}/${keyResult.targetValue} (${percentComplete}%).`;
+}
+export async function adoOkrSummary(period) {
+    const resolvedPeriod = period?.trim() || getCurrentQuarter();
+    const client = new AdoClient();
+    return await client.getOKRSummary(resolvedPeriod);
+}
+//# sourceMappingURL=ado-skill.js.map

package/dist/integrations/report-generator.js

@@ -0,0 +1,114 @@
+import { ensureWikiStructure, listPages, readPage } from "../wiki/fs.js";
+import { sendToOrchestrator } from "../copilot/orchestrator.js";
+import { AdoAnalytics } from "./ado-analytics.js";
+const RECENT_UPDATE_DAYS = 31;
+function getQuarterMonths(period) {
+    const match = /^(\d{4})-Q([1-4])$/.exec(period.trim());
+    if (!match) {
+        return [];
+    }
+    const year = match[1];
+    const quarter = Number(match[2]);
+    const startMonth = (quarter - 1) * 3 + 1;
+    return Array.from({ length: 3 }, (_unused, index) => `${year}-${String(startMonth + index).padStart(2, "0")}`);
+}
+function getRecentQuarterUpdatePaths(period, now, listPagePaths) {
+    ensureWikiStructure();
+    const quarterMonths = new Set(getQuarterMonths(period));
+    const cutoff = new Date(now);
+    cutoff.setUTCDate(cutoff.getUTCDate() - (RECENT_UPDATE_DAYS - 1));
+    const cutoffDate = cutoff.toISOString().slice(0, 10);
+    return listPagePaths()
+        .filter((path) => path.startsWith("pages/okrs/updates/"))
+        .filter((path) => {
+        const pageDate = path.slice("pages/okrs/updates/".length).replace(/\.md$/, "");
+        return pageDate >= cutoffDate && quarterMonths.has(pageDate.slice(0, 7));
+    })
+        .sort()
+        .reverse();
+}
+function renderObjectiveTable(reportData) {
+    const lines = [
+        "| Objective | Owner | Complete | KR Count |",
+        "| --- | --- | --- | --- |",
+        ...reportData.objectives.map((objective) => (`| ${objective.title} | ${objective.owner || "—"} | ${objective.percentComplete}% | ${objective.krs.length} |`)),
+    ];
+    return lines.join("\n");
+}
+function renderKrTable(reportData) {
+    const lines = [
+        "| Objective | KR | Owner | State | Progress | Complete |",
+        "| --- | --- | --- | --- | --- | --- |",
+    ];
+    for (const objective of reportData.objectives) {
+        for (const kr of objective.krs) {
+            lines.push(`| ${objective.title} | ${kr.title} | ${kr.owner || "—"} | ${kr.state || "—"} | ${kr.currentValue}/${kr.targetValue} | ${kr.percentComplete}% |`);
+        }
+    }
+    return lines.join("\n");
+}
+function buildPrompt(reportData, updateLogs) {
+    const highlights = reportData.highlights.length > 0
+        ? reportData.highlights.map((item) => `- ${item}`).join("\n")
+        : "_No highlights extracted from recent updates._";
+    return [
+        "You are generating a monthly OKR report for the team.",
+        "Here is the current data:",
+        "",
+        `Period: ${reportData.period}`,
+        `Generated At: ${reportData.generatedAt}`,
+        `Total KRs: ${reportData.totalKRs}`,
+        `Completed KRs: ${reportData.completedKRs}`,
+        "",
+        "## Objective Summary",
+        renderObjectiveTable(reportData),
+        "",
+        "## Key Result Detail",
+        renderKrTable(reportData),
+        "",
+        "## Highlight Candidates",
+        highlights,
+        "",
+        "Here are the team's recent activity updates:",
+        updateLogs || "_No recent daily update logs found._",
+        "",
+        "Please write a concise executive-style OKR report covering: overall health, objective-by-objective summary, highlights, risks, and next steps.",
+    ].join("\n");
+}
+async function defaultGenerateNarrative(prompt) {
+    return await new Promise((resolve, reject) => {
+        void sendToOrchestrator(prompt, { type: "background" }, (text, done) => {
+            if (!done) {
+                return;
+            }
+            if (text.startsWith("Error: ")) {
+                reject(new Error(text.slice("Error: ".length).trim() || text));
+                return;
+            }
+            resolve(text);
+        });
+    });
+}
+export class ReportGenerator {
+    analytics;
+    now;
+    listPagesImpl;
+    readPageImpl;
+    generateNarrative;
+    constructor(options = {}) {
+        this.analytics = options.analytics ?? new AdoAnalytics({ now: options.now });
+        this.now = options.now ?? (() => new Date());
+        this.listPagesImpl = options.listPages ?? listPages;
+        this.readPageImpl = options.readPage ?? readPage;
+        this.generateNarrative = options.generateNarrative ?? defaultGenerateNarrative;
+    }
+    async generateMonthlyReport(period) {
+        const reportData = await this.analytics.buildReportData(period);
+        const updateLogs = getRecentQuarterUpdatePaths(period, this.now(), this.listPagesImpl)
+            .map((path) => this.readPageImpl(path) ?? "")
+            .filter((content) => content.trim().length > 0)
+            .join("\n\n");
+        return await this.generateNarrative(buildPrompt(reportData, updateLogs));
+    }
+}
+//# sourceMappingURL=report-generator.js.map

package/dist/integrations/report-generator.test.js

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+async function loadReportGeneratorModule() {
+    try {
+        return await import(new URL(`./report-generator.js?cachebust=${Date.now()}-${Math.random()}`, import.meta.url).href);
+    }
+    catch {
+        return null;
+    }
+}
+test("generateMonthlyReport formats analytics data and recent updates into the orchestrator prompt", async () => {
+    const reportGeneratorModule = await loadReportGeneratorModule();
+    assert.ok(reportGeneratorModule, "report generator module should exist");
+    const prompts = [];
+    const generator = new reportGeneratorModule.ReportGenerator({
+        analytics: {
+            async buildReportData() {
+                return {
+                    period: "2026-Q2",
+                    generatedAt: "2026-05-06T00:00:00.000Z",
+                    totalKRs: 2,
+                    completedKRs: 1,
+                    highlights: ["Finished SSO rollout dry-run"],
+                    objectives: [
+                        {
+                            workItemId: 7,
+                            title: "Improve identity coverage",
+                            owner: "ada@example.com",
+                            percentComplete: 63,
+                            krs: [
+                                {
+                                    workItemId: 101,
+                                    title: "Ship SSO to all tenants",
+                                    currentValue: 75,
+                                    targetValue: 100,
+                                    percentComplete: 75,
+                                    owner: "ada@example.com",
+                                    state: "Active",
+                                },
+                            ],
+                        },
+                    ],
+                };
+            },
+        },
+        listPages: () => ["pages/okrs/updates/2026-05-02.md"],
+        readPage: () => "## 2026-05-02T10:00:00.000Z — eng-1\n\n**Activity**: Finished SSO rollout dry-run  \n",
+        generateNarrative: async (prompt) => {
+            prompts.push(prompt);
+            return "Overall health is improving.";
+        },
+    });
+    const report = await generator.generateMonthlyReport("2026-Q2");
+    assert.equal(report, "Overall health is improving.");
+    assert.equal(prompts.length, 1);
+    assert.match(prompts[0] ?? "", /You are generating a monthly OKR report for the team\./);
+    assert.match(prompts[0] ?? "", /\| Objective \| Owner \| Complete \| KR Count \|/);
+    assert.match(prompts[0] ?? "", /Improve identity coverage/);
+    assert.match(prompts[0] ?? "", /Finished SSO rollout dry-run/);
+    assert.match(prompts[0] ?? "", /overall health, objective-by-objective summary, highlights, risks, and next steps/i);
+});
+//# sourceMappingURL=report-generator.test.js.map

package/dist/integrations/team-push.js

@@ -0,0 +1,144 @@
+import { config } from "../config.js";
+export class TeamPushClient {
+    teamChapterhouseUrl;
+    teamChapterhouseToken;
+    standaloneMode;
+    fetchImpl;
+    getAuthorizationHeader;
+    getCurrentUser;
+    constructor(options = {}) {
+        this.teamChapterhouseUrl = (options.teamChapterhouseUrl ?? config.teamChapterhouseUrl).trim().replace(/\/+$/, "");
+        this.teamChapterhouseToken = (options.teamChapterhouseToken ?? config.teamChapterhouseToken).trim();
+        this.standaloneMode = options.standaloneMode ?? config.standaloneMode;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.getAuthorizationHeader = options.getAuthorizationHeader;
+        this.getCurrentUser = options.getCurrentUser;
+    }
+    async pushUpdate(payload) {
+        if (!this.isEnabled()) {
+            return {
+                ok: false,
+                entry: {
+                    disabled: true,
+                    ...payload,
+                },
+            };
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.teamChapterhouseUrl}/api/team/update`, {
+                method: "POST",
+                headers: {
+                    ...this.buildHeaders(),
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    engineerId: this.resolveEngineerId(),
+                    activity: payload.activity,
+                    krId: payload.krId,
+                    delta: payload.delta,
+                    notes: payload.notes,
+                }),
+            });
+        }
+        catch (err) {
+            throw new Error(`Failed to push OKR update: network request failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to push OKR update: ${describeHttpFailure(response.status)}`);
+        }
+        return await response.json();
+    }
+    async fetchOKRs(period) {
+        if (!this.isEnabled()) {
+            return "";
+        }
+        const url = new URL(`${this.teamChapterhouseUrl}/api/team/okrs`);
+        if (period) {
+            url.searchParams.set("period", period);
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                headers: this.buildHeaders(),
+            });
+        }
+        catch (err) {
+            throw new Error(`Failed to fetch OKRs: network request failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to fetch OKRs: ${describeHttpFailure(response.status)}`);
+        }
+        const payload = await response.json();
+        const pages = Array.isArray(payload.pages) ? payload.pages : [];
+        const filtered = period
+            ? pages.filter((page) => page.path.includes(period))
+            : pages;
+        return filtered.map((page) => page.content).join("\n\n---\n\n");
+    }
+    async writePage(path, content) {
+        if (!this.isEnabled()) {
+            return { ok: false, path };
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.teamChapterhouseUrl}/api/team/wiki/${encodeURIComponent(path)}`, {
+                method: "PUT",
+                headers: {
+                    ...this.buildHeaders(),
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({ content }),
+            });
+        }
+        catch (err) {
+            throw new Error(`Failed to write team wiki page: network request failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to write team wiki page: ${describeHttpFailure(response.status)}`);
+        }
+        return await response.json();
+    }
+    buildHeaders() {
+        const headers = {
+            accept: "application/json",
+        };
+        const authorizationHeader = this.resolveAuthorizationHeader();
+        if (authorizationHeader) {
+            headers.authorization = authorizationHeader;
+        }
+        return headers;
+    }
+    resolveAuthorizationHeader() {
+        const currentHeader = this.getAuthorizationHeader?.()?.trim();
+        if (currentHeader) {
+            return currentHeader;
+        }
+        if (!this.teamChapterhouseToken) {
+            return undefined;
+        }
+        return this.teamChapterhouseToken.startsWith("Bearer ")
+            ? this.teamChapterhouseToken
+            : `Bearer ${this.teamChapterhouseToken}`;
+    }
+    resolveEngineerId() {
+        const user = this.getCurrentUser?.();
+        if (user?.id) {
+            return user.id;
+        }
+        throw new Error("Failed to push OKR update: no authenticated engineer identity is available");
+    }
+    isEnabled() {
+        return !this.standaloneMode && this.teamChapterhouseUrl.length > 0;
+    }
+}
+function describeHttpFailure(status) {
+    if (status === 401) {
+        return "unauthorized (HTTP 401)";
+    }
+    if (status === 403) {
+        return "forbidden (HTTP 403)";
+    }
+    return `HTTP ${status}`;
+}
+//# sourceMappingURL=team-push.js.map