@m0saic/templates 0.2.0

package/dist/m0saic/github/repo-facts-fetcher/v1/facts.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `GithubRepoFacts` — the normalized, bounded, near-raw sheet the
+ * `repo-facts-fetcher` publishes under the alias `githubRepoFacts`
+ * (`schemaVersion: 1`). This is the F5 producer→consumer contract: the
+ * `weekly-pulse-adapter` consumes it and derives the `WeeklyPulse` sheet.
+ *
+ * Every field is a cheap GitHub REST read (or a free derivation from one).
+ * Coverage is always recorded, never assumed — a mirror repo (no issues, few
+ * PRs) or an anonymous fetch legitimately drops fields, and `coverage` says so.
+ */
+export type GithubCommitFileFacts = {
+    path: string;
+    additions: number;
+    deletions: number;
+    status: string;
+};
+export type GithubCommitFacts = {
+    sha: string;
+    /** Committer date (window bucketing key). */
+    committedISO: string;
+    /** Author date (may predate committedISO — mailing-list workflows). */
+    authoredISO: string;
+    /** First line of the commit message. */
+    headline: string;
+    /** Parsed message trailers (Reviewed-by, Signed-off-by, …) — names, no emails. */
+    trailers?: Record<string, string[]>;
+    authorName: string;
+    authorLogin?: string;
+    avatarUrl?: string;
+    /** From the per-commit detail call (coverage-gated). */
+    additions?: number;
+    deletions?: number;
+    files?: GithubCommitFileFacts[];
+};
+export type GithubCommitLite = {
+    sha: string;
+    committedISO: string;
+    authorLogin?: string;
+    authorName: string;
+};
+export type GithubWeeklyActivity = {
+    /** Sunday-start week (GitHub's `stats/commit_activity`). */
+    weekStartISO: string;
+    days: number[];
+    total: number;
+};
+export type GithubWeeklyCodeFrequency = {
+    weekStartISO: string;
+    additions: number;
+    deletions: number;
+};
+export type GithubStarFacts = {
+    total: number;
+    deltaInWindow?: number;
+    deltaPrevWindow?: number;
+};
+export type GithubPullFacts = {
+    open: number;
+    openedInWindow: number;
+    mergedInWindow: number;
+};
+export type GithubIssueFacts = {
+    open: number;
+    openedInWindow: number;
+    closedInWindow: number;
+};
+export type GithubCoverage = {
+    authenticated: boolean;
+    commitDetails: "full" | "partial" | "none";
+    pulls: boolean;
+    issues: boolean;
+    starDeltas: boolean;
+    truncated?: {
+        commits?: number;
+        filesPerCommit?: number;
+        callBudgetHit?: boolean;
+    };
+};
+export type GithubRepoFacts = {
+    schemaVersion: 1;
+    repo: {
+        fullName: string;
+        name: string;
+        defaultBranch: string;
+        description?: string;
+        stars: number;
+        forks: number;
+        watchers: number;
+        openIssues: number;
+        hasIssues: boolean;
+        pushedAt: string;
+    };
+    /** UTC Monday..Sunday inclusive. */
+    window: {
+        startISO: string;
+        endISO: string;
+    };
+    /** THE window's commits, committer-date bucketed. */
+    commits: GithubCommitFacts[];
+    /** Window + 7 prior weeks — feeds the grid + all week-over-week deltas. */
+    trailing8WeekCommitsLite: GithubCommitLite[];
+    weeklyActivity: GithubWeeklyActivity[];
+    weeklyCodeFrequency?: GithubWeeklyCodeFrequency[];
+    stars?: GithubStarFacts;
+    pulls?: GithubPullFacts;
+    issues?: GithubIssueFacts;
+    coverage: GithubCoverage;
+    rateLimit?: {
+        limit: number;
+        remaining: number;
+    };
+};

package/dist/m0saic/github/repo-facts-fetcher/v1/facts.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * `GithubRepoFacts` — the normalized, bounded, near-raw sheet the
+ * `repo-facts-fetcher` publishes under the alias `githubRepoFacts`
+ * (`schemaVersion: 1`). This is the F5 producer→consumer contract: the
+ * `weekly-pulse-adapter` consumes it and derives the `WeeklyPulse` sheet.
+ *
+ * Every field is a cheap GitHub REST read (or a free derivation from one).
+ * Coverage is always recorded, never assumed — a mirror repo (no issues, few
+ * PRs) or an anonymous fetch legitimately drops fields, and `coverage` says so.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/m0saic/github/repo-facts-fetcher/v1/repo-facts-fetcher.d.ts

@@ -0,0 +1,67 @@
+import type { MosaicDocument, MosaicEngineContext, MosaicTemplateUpstreamData, MosaicTemplateUpstreamVariables } from "@m0saic/types";
+import type { GithubRepoFacts } from "./facts";
+/**
+ * `@m0saic/github/repo-facts-fetcher/v1` — the capability-tier fetcher that
+ * publishes `githubRepoFacts` (a {@link GithubRepoFacts} sheet) for the
+ * `weekly-pulse-adapter` and other consumers. The FIRST real user of the F1
+ * capability surface (host connections + secrets + upstream threading).
+ *
+ * Two modes, one output shape:
+ *  - `replay` (DEFAULT) — publishes `props.facts` (the embedded {@link
+ *    SAMPLE_FACTS} by default). NO network, byte-deterministic — this is what
+ *    the e2e sweep and CI pipelines render.
+ *  - `live` — fetches `repo` over `window` via the GitHub REST client, records
+ *    coverage, and publishes the assembled facts. Nondeterministic, quarantined
+ *    behind the client; never touched by CI.
+ *
+ * Doc shape mirrors `meta/fixture-fetcher`: a black lavfi CARRIER cell + the
+ * aliased data source (skipped from layout) + a verbatim `sidecars` mirror. Wrap
+ * in an `intermediate:true` pipeline step so the carrier never reaches output.
+ *
+ * Secret hygiene: the token is passed to the client (request headers) ONLY. It
+ * never enters `variables`, `sidecars`, diagnostics, errors, or logs —
+ * `coverage.authenticated` is the only signal that a token was used.
+ */
+export type RepoFactsFetcherProps = {
+    /** `replay` (no network, publish `facts`) or `live` (fetch `repo`). */
+    source?: "replay" | "live";
+    /** Replay payload (also the test seam). Default: the embedded sample. */
+    facts?: GithubRepoFacts;
+    /** `owner/name` (live mode). */
+    repo?: string;
+    /** UTC Monday..Sunday inclusive (live mode). */
+    window?: {
+        startISO: string;
+        endISO: string;
+    };
+    /** Host connection id for non-secret values + the keychain token (live mode). */
+    connectionId?: string;
+    /** Explicit SecretRef escape hatch (e.g. `env:GITHUB_TOKEN`); wins over the connection. */
+    tokenRef?: string;
+    /** Per-commit detail: `auto` (full when authenticated, none anonymous), or force. */
+    commitDetails?: "auto" | "full" | "none";
+    /** Per-window commit cap; overflow → `coverage.truncated.commits`. */
+    maxCommits?: number;
+    /** Hard cap on API calls per render; overflow → truncate + record. */
+    callBudget?: number;
+};
+type RepoFactsFetcherSidecars = {
+    githubRepoFacts: GithubRepoFacts;
+};
+/** The fixed publish alias — part of the producer contract (Seam B). */
+export declare const GITHUB_REPO_FACTS_ALIAS = "githubRepoFacts";
+/**
+ * Resolve the live-mode access: the connection's base URL (non-secret) and the
+ * token. Token precedence: explicit `tokenRef` → connection keychain ref →
+ * anonymous. Never throws on a missing/unresolvable token — degrades to
+ * anonymous (coverage records it). Exported for unit testing with a fake ctx.
+ */
+export declare function resolveGithubAccess(props: RepoFactsFetcherProps, ctx: MosaicEngineContext): Promise<{
+    token?: string;
+    baseUrl?: string;
+}>;
+/** Wrap a facts sheet in the carrier + aliased-data + sidecar document. Pure —
+ *  shared by both render modes and unit-tested directly. */
+export declare function factsToDocument(facts: GithubRepoFacts): MosaicDocument;
+export declare const RepoFactsFetcher: import("@m0saic/types").MosaicTemplate<RepoFactsFetcherProps, GithubRepoFacts, MosaicTemplateUpstreamVariables, MosaicTemplateUpstreamData, RepoFactsFetcherSidecars>;
+export default RepoFactsFetcher;

package/dist/m0saic/github/repo-facts-fetcher/v1/repo-facts-fetcher.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RepoFactsFetcher = exports.GITHUB_REPO_FACTS_ALIAS = void 0;
+exports.resolveGithubAccess = resolveGithubAccess;
+exports.factsToDocument = factsToDocument;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const client_1 = require("../../client");
+const connection_1 = require("../../connection");
+const build_facts_1 = require("./build-facts");
+const sample_facts_1 = require("./sample-facts");
+/** The fixed publish alias — part of the producer contract (Seam B). */
+exports.GITHUB_REPO_FACTS_ALIAS = "githubRepoFacts";
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    source: {
+        type: "string", required: false,
+        description: 'replay = publish `facts` with no network (default); live = fetch `repo` over `window`.',
+        meta: { constraints: { oneOf: ["replay", "live"] }, ui: { label: "Source", order: 1 } },
+    },
+    facts: {
+        type: "json", required: false,
+        description: "Replay payload — a GithubRepoFacts sheet. Defaults to the embedded sample.",
+        meta: { ui: { label: "Facts (replay)", order: 2, consumer: "agent" } },
+    },
+    repo: {
+        type: "string", required: false,
+        description: 'Repository "owner/name" (live mode).',
+        meta: { ui: { label: "Repository", order: 3 } },
+    },
+    window: {
+        type: "json", required: false,
+        description: "UTC { startISO, endISO } — Monday..Sunday inclusive (live mode).",
+        meta: { ui: { label: "Window", order: 4, consumer: "agent" } },
+    },
+    connectionId: {
+        type: "string", required: false,
+        description: "Host connection id for the base URL + keychain token (live mode).",
+        meta: { ui: { label: "Connection", order: 5 } },
+    },
+    tokenRef: {
+        type: "string", required: false,
+        description: "Explicit SecretRef (e.g. env:GITHUB_TOKEN). Wins over the connection token.",
+        meta: { ui: { label: "Token ref", order: 6 } },
+    },
+    commitDetails: {
+        type: "string", required: false,
+        description: "auto (full when authenticated, none anonymous), full, or none.",
+        meta: { constraints: { oneOf: ["auto", "full", "none"] }, ui: { label: "Commit details", order: 7 } },
+    },
+    maxCommits: {
+        type: "number", required: false,
+        description: "Per-window commit cap (overflow recorded in coverage.truncated).",
+        meta: { constraints: { min: 1, max: 5000 }, ui: { label: "Max commits", order: 8 } },
+    },
+    callBudget: {
+        type: "number", required: false,
+        description: "Hard cap on API calls per render (overflow recorded in coverage.truncated).",
+        meta: { constraints: { min: 1, max: 5000 }, ui: { label: "Call budget", order: 9 } },
+    },
+});
+/**
+ * Resolve the live-mode access: the connection's base URL (non-secret) and the
+ * token. Token precedence: explicit `tokenRef` → connection keychain ref →
+ * anonymous. Never throws on a missing/unresolvable token — degrades to
+ * anonymous (coverage records it). Exported for unit testing with a fake ctx.
+ */
+async function resolveGithubAccess(props, ctx) {
+    const connId = props.connectionId && props.connectionId.length > 0 ? props.connectionId : String(connection_1.GITHUB_CONNECTION_ID);
+    let baseUrl;
+    if (ctx.connections) {
+        const vals = await ctx.connections.get(connId);
+        if (vals && typeof vals.baseUrl === "string" && vals.baseUrl.length > 0)
+            baseUrl = vals.baseUrl;
+    }
+    let token;
+    // Escape hatch: an explicit tokenRef wins WHEN it resolves.
+    if (props.tokenRef && props.tokenRef.length > 0 && ctx.secrets && (await ctx.secrets.has(props.tokenRef))) {
+        token = await ctx.secrets.get(props.tokenRef);
+    }
+    // Fall through to the connection's keychain token (Seam A order:
+    // tokenRef → connection → anonymous). So a set-but-unresolvable tokenRef —
+    // e.g. `env:GITHUB_TOKEN` unset in the desktop app — still uses the token
+    // configured under Settings → Integrations rather than dropping to anonymous.
+    if (token === undefined && ctx.secrets && ctx.connections && (await ctx.connections.has(connId))) {
+        const ref = (0, types_1.mintConnectionSecretRef)(connId, connection_1.GITHUB_TOKEN_FIELD);
+        if (await ctx.secrets.has(ref))
+            token = await ctx.secrets.get(ref);
+    }
+    return { token, baseUrl };
+}
+/** Wrap a facts sheet in the carrier + aliased-data + sidecar document. Pure —
+ *  shared by both render modes and unit-tested directly. */
+function factsToDocument(facts) {
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)("1", "githubRepoFacts"),
+        assets: {},
+        sources: [
+            // Degenerate carrier — a mosaic ref must point at something renderable;
+            // intermediate:true keeps this black tile out of the deliverable.
+            { type: "lavfi", color: "#000000" },
+            {
+                type: "data",
+                alias: (0, types_1.asAliasId)(exports.GITHUB_REPO_FACTS_ALIAS),
+                variables: facts,
+                editor: { owner: "template" },
+            },
+        ],
+        sidecars: { githubRepoFacts: facts },
+    };
+}
+exports.RepoFactsFetcher = (0, template_utils_1.defineMosaicTemplate)({
+    id: (0, types_1.asTemplateId)("@m0saic/github/repo-facts-fetcher/v1"),
+    label: "GitHub Repo Facts (fetcher)",
+    version: 1,
+    description: "Capability-tier data fetcher: publishes a normalized GithubRepoFacts sheet (commits, contributors, activity, stars, coverage) under the alias githubRepoFacts. Replay mode (default) is network-free + deterministic; live mode fetches a repo/window over the GitHub REST API with a recorded coverage/degradation ladder. Feeds the weekly-pulse-adapter.",
+    role: "data-fetcher",
+    capabilities: { tier: "capability", caps: { net: { fetch: true } } },
+    // A data carrier, not a picture: it publishes `githubRepoFacts` for a
+    // pipeline step and renders only a 64×64 black tile. Out of the public
+    // pickers (founder, 2026-09-14) — still reachable by id for pipelines and
+    // nested renders.
+    internal: true,
+    tags: ["utility", "github", "connector", "data-fetcher"],
+    outputHints: {
+        format: { kind: "image", container: "png" },
+        width: 64,
+        height: 64,
+        fps: 1,
+        durationMs: 1000,
+        note: "Publishes githubRepoFacts; renders only a degenerate black carrier tile. Wrap in a pipeline step with intermediate:true so the carrier never reaches the deliverable.",
+    },
+    outputsSchema: {
+        schemaVersion: { type: "number", required: true },
+        repo: { type: "object", required: true },
+        window: { type: "object", required: true },
+        commits: { type: "any", required: true },
+        trailing8WeekCommitsLite: { type: "any", required: true },
+        weeklyActivity: { type: "any", required: true },
+        weeklyCodeFrequency: { type: "any", required: false },
+        stars: { type: "object", required: false },
+        pulls: { type: "object", required: false },
+        issues: { type: "object", required: false },
+        coverage: { type: "object", required: true },
+        rateLimit: { type: "object", required: false },
+    },
+    propsSchema,
+    defaultProps: {
+        source: "replay",
+        facts: sample_facts_1.SAMPLE_FACTS,
+        repo: "FFmpeg/FFmpeg",
+        window: sample_facts_1.SAMPLE_FACTS.window,
+        connectionId: String(connection_1.GITHUB_CONNECTION_ID),
+        tokenRef: "",
+        commitDetails: "auto",
+        maxCommits: 500,
+        callBudget: 300,
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const source = (_a = props.source) !== null && _a !== void 0 ? _a : "replay";
+        if (source !== "replay" && source !== "live") {
+            throw new Error(`repo-facts-fetcher: source must be "replay" or "live", got ${JSON.stringify(source)}.`);
+        }
+        if (source === "replay") {
+            const facts = (_b = props.facts) !== null && _b !== void 0 ? _b : sample_facts_1.SAMPLE_FACTS;
+            if (facts === null || typeof facts !== "object" || Array.isArray(facts)) {
+                throw new Error("repo-facts-fetcher: replay `facts` must be a GithubRepoFacts object.");
+            }
+            return factsToDocument(facts);
+        }
+        // ── live ──────────────────────────────────────────────────────
+        const repo = (_c = props.repo) !== null && _c !== void 0 ? _c : "FFmpeg/FFmpeg";
+        if (!/^[^/\s]+\/[^/\s]+$/.test(repo)) {
+            throw new Error(`repo-facts-fetcher: repo must be "owner/name", got ${JSON.stringify(repo)}.`);
+        }
+        const window = (_d = props.window) !== null && _d !== void 0 ? _d : sample_facts_1.SAMPLE_FACTS.window;
+        if (!window || typeof window.startISO !== "string" || typeof window.endISO !== "string") {
+            throw new Error("repo-facts-fetcher: window must be { startISO, endISO } (UTC YYYY-MM-DD).");
+        }
+        const commitDetails = (_e = props.commitDetails) !== null && _e !== void 0 ? _e : "auto";
+        if (commitDetails !== "auto" && commitDetails !== "full" && commitDetails !== "none") {
+            throw new Error(`repo-facts-fetcher: commitDetails must be auto|full|none, got ${JSON.stringify(commitDetails)}.`);
+        }
+        const maxCommits = (_f = props.maxCommits) !== null && _f !== void 0 ? _f : 500;
+        const callBudget = (_g = props.callBudget) !== null && _g !== void 0 ? _g : 300;
+        // Runtime fetch failures (network, 404, keychain) degrade to a valid error
+        // frame — the render survives and publishes no facts, so a downstream
+        // consumer sees the gap and error-frames too. Malformed props above still
+        // fail fast (an author/config error, not a runtime data problem).
+        try {
+            const { token, baseUrl } = await resolveGithubAccess(props, ctx);
+            const client = new client_1.GithubClient({ baseUrl, token, callBudget });
+            const facts = await (0, build_facts_1.buildRepoFacts)(client, { repo, window, commitDetails, maxCommits });
+            return factsToDocument(facts);
+        }
+        catch (e) {
+            return (0, template_utils_1.makeErrorMosaic)(`GitHub fetch failed for ${repo} (${window.startISO}..${window.endISO}): ${e instanceof Error ? e.message : String(e)}`, {
+                width: Math.max(1, Math.round(ctx.target.width)),
+                height: Math.max(1, Math.round(ctx.target.height)),
+                title: "GitHub Repo Facts",
+                errorCode: "GITHUB_FETCH_FAILED",
+            });
+        }
+    },
+});
+(0, template_utils_1.registerTemplate)(exports.RepoFactsFetcher);
+exports.default = exports.RepoFactsFetcher;

package/dist/m0saic/github/repo-facts-fetcher/v1/sample-facts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `SAMPLE_FACTS` — the embedded, deterministic, full-coverage replay payload for
+ * `repo-facts-fetcher/v1`. Serves three jobs:
+ *   1. the network-free default render (so the e2e sweep never touches GitHub),
+ *   2. the byte-equality seam for the fetcher's replay determinism test,
+ *   3. a full-coverage fixture the `weekly-pulse-adapter` (P3) can snapshot
+ *      against before the founder records the real FFmpeg week.
+ *
+ * A coherent single week for a fictional normal repo (`acme/rocket`, June 1–7
+ * 2026, Mon..Sun): 8 window commits across 4 contributors, full commit detail,
+ * star deltas, and PR/issue counts — i.e. every `coverage` flag true, so the
+ * adaptive KPI path lights up. Built via tiny local helpers to stay compact;
+ * the result is a fixed constant (no Date, no randomness).
+ */
+import type { GithubRepoFacts } from "./facts";
+export declare const SAMPLE_FACTS: GithubRepoFacts;

package/dist/m0saic/github/repo-facts-fetcher/v1/sample-facts.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * `SAMPLE_FACTS` — the embedded, deterministic, full-coverage replay payload for
+ * `repo-facts-fetcher/v1`. Serves three jobs:
+ *   1. the network-free default render (so the e2e sweep never touches GitHub),
+ *   2. the byte-equality seam for the fetcher's replay determinism test,
+ *   3. a full-coverage fixture the `weekly-pulse-adapter` (P3) can snapshot
+ *      against before the founder records the real FFmpeg week.
+ *
+ * A coherent single week for a fictional normal repo (`acme/rocket`, June 1–7
+ * 2026, Mon..Sun): 8 window commits across 4 contributors, full commit detail,
+ * star deltas, and PR/issue counts — i.e. every `coverage` flag true, so the
+ * adaptive KPI path lights up. Built via tiny local helpers to stay compact;
+ * the result is a fixed constant (no Date, no randomness).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAMPLE_FACTS = void 0;
+const week_math_1 = require("../../week-math");
+const lite = (sha, committedISO, authorLogin, authorName) => ({
+    sha,
+    committedISO,
+    authorLogin,
+    authorName,
+});
+/** N Sunday-start weekly-activity rows ending at (and including) `lastSundayISO`. */
+function activityWeeks(lastSundayISO, totals) {
+    return totals.map((total, i) => {
+        const weekStartISO = (0, week_math_1.addDaysISO)(lastSundayISO, -7 * (totals.length - 1 - i));
+        // Spread the week's total across weekdays deterministically (Mon-heavy).
+        const days = [0, 0, 0, 0, 0, 0, 0];
+        for (let k = 0; k < total; k++)
+            days[k % 7]++;
+        return { weekStartISO, days, total };
+    });
+}
+function codeFreqWeeks(lastSundayISO, rows) {
+    return rows.map(([additions, deletions], i) => ({
+        weekStartISO: (0, week_math_1.addDaysISO)(lastSundayISO, -7 * (rows.length - 1 - i)),
+        additions,
+        deletions,
+    }));
+}
+// The GitHub "week" that contains the window's Sunday (2026-06-07) starts Sun 2026-06-07.
+const LAST_SUNDAY = (0, week_math_1.formatISODate)((0, week_math_1.civilFromDays)((0, week_math_1.daysFromCivil)(2026, 6, 7)));
+exports.SAMPLE_FACTS = {
+    schemaVersion: 1,
+    repo: {
+        fullName: "acme/rocket",
+        name: "rocket",
+        defaultBranch: "main",
+        description: "A tidy demo repo for the Weekly Pulse.",
+        stars: 4200,
+        forks: 310,
+        watchers: 88,
+        openIssues: 42,
+        hasIssues: true,
+        pushedAt: "2026-06-07T18:04:11Z",
+    },
+    window: { startISO: "2026-06-01", endISO: "2026-06-07" },
+    commits: [
+        {
+            sha: "c0ffee01", committedISO: "2026-06-01T09:12:00Z", authoredISO: "2026-06-01T09:12:00Z",
+            headline: "core: speed up render loop with a SIMD path",
+            trailers: { "Reviewed-by": ["Grace Hopper"] },
+            authorName: "Ada Lovelace", authorLogin: "ada", avatarUrl: "https://avatars.example/ada.png",
+            additions: 180, deletions: 40,
+            files: [{ path: "core/render.ts", additions: 180, deletions: 40, status: "modified" }],
+        },
+        {
+            sha: "c0ffee02", committedISO: "2026-06-01T14:48:00Z", authoredISO: "2026-06-01T14:48:00Z",
+            headline: "io: fix memory leak in the stream reader",
+            trailers: { "Reviewed-by": ["Ada Lovelace"] },
+            authorName: "Grace Hopper", authorLogin: "grace", avatarUrl: "https://avatars.example/grace.png",
+            additions: 24, deletions: 18,
+            files: [{ path: "io/stream.ts", additions: 24, deletions: 18, status: "modified" }],
+        },
+        {
+            sha: "c0ffee03", committedISO: "2026-06-02T11:03:00Z", authoredISO: "2026-06-02T10:50:00Z",
+            headline: "api: add pagination to the list endpoints",
+            trailers: { "Reviewed-by": ["Ada Lovelace", "Grace Hopper"] },
+            authorName: "Alan Turing", authorLogin: "alan", avatarUrl: "https://avatars.example/alan.png",
+            additions: 210, deletions: 12,
+            files: [
+                { path: "api/list.ts", additions: 168, deletions: 12, status: "modified" },
+                { path: "api/types.ts", additions: 42, deletions: 0, status: "modified" },
+            ],
+        },
+        {
+            sha: "c0ffee04", committedISO: "2026-06-03T08:20:00Z", authoredISO: "2026-06-03T08:20:00Z",
+            headline: "core: fix crash on empty input",
+            authorName: "Ada Lovelace", authorLogin: "ada", avatarUrl: "https://avatars.example/ada.png",
+            additions: 12, deletions: 4,
+            files: [{ path: "core/render.ts", additions: 12, deletions: 4, status: "modified" }],
+        },
+        {
+            sha: "c0ffee05", committedISO: "2026-06-03T13:31:00Z", authoredISO: "2026-06-03T13:31:00Z",
+            headline: "docs: document the pagination API",
+            authorName: "Katherine Johnson", authorLogin: "katherine", avatarUrl: "https://avatars.example/katherine.png",
+            additions: 64, deletions: 2,
+            files: [{ path: "docs/api.md", additions: 64, deletions: 2, status: "modified" }],
+        },
+        {
+            sha: "c0ffee06", committedISO: "2026-06-03T17:59:00Z", authoredISO: "2026-06-03T17:59:00Z",
+            headline: "render: cache the glyph atlas between frames",
+            trailers: { "Reviewed-by": ["Alan Turing"] },
+            authorName: "Grace Hopper", authorLogin: "grace", avatarUrl: "https://avatars.example/grace.png",
+            additions: 96, deletions: 30,
+            files: [{ path: "render/atlas.ts", additions: 96, deletions: 30, status: "modified" }],
+        },
+        {
+            sha: "c0ffee07", committedISO: "2026-06-04T10:07:00Z", authoredISO: "2026-06-04T10:07:00Z",
+            headline: "tests: add coverage for pagination edge cases",
+            authorName: "Alan Turing", authorLogin: "alan", avatarUrl: "https://avatars.example/alan.png",
+            additions: 140, deletions: 0,
+            files: [{ path: "tests/api.test.ts", additions: 140, deletions: 0, status: "added" }],
+        },
+        {
+            sha: "c0ffee08", committedISO: "2026-06-06T15:22:00Z", authoredISO: "2026-06-06T15:22:00Z",
+            headline: "cli: add a --watch flag",
+            trailers: { "Reviewed-by": ["Ada Lovelace"] },
+            authorName: "Katherine Johnson", authorLogin: "katherine", avatarUrl: "https://avatars.example/katherine.png",
+            additions: 88, deletions: 6,
+            files: [{ path: "cli/watch.ts", additions: 88, deletions: 6, status: "added" }],
+        },
+    ],
+    trailing8WeekCommitsLite: [
+        // window week (2026-06-01) — mirrors the 8 commits above
+        lite("c0ffee01", "2026-06-01T09:12:00Z", "ada", "Ada Lovelace"),
+        lite("c0ffee02", "2026-06-01T14:48:00Z", "grace", "Grace Hopper"),
+        lite("c0ffee03", "2026-06-02T11:03:00Z", "alan", "Alan Turing"),
+        lite("c0ffee04", "2026-06-03T08:20:00Z", "ada", "Ada Lovelace"),
+        lite("c0ffee05", "2026-06-03T13:31:00Z", "katherine", "Katherine Johnson"),
+        lite("c0ffee06", "2026-06-03T17:59:00Z", "grace", "Grace Hopper"),
+        lite("c0ffee07", "2026-06-04T10:07:00Z", "alan", "Alan Turing"),
+        lite("c0ffee08", "2026-06-06T15:22:00Z", "katherine", "Katherine Johnson"),
+        // prev week (2026-05-25) — 5 commits (this week 8 vs prev 5 → +60%)
+        lite("a0000501", "2026-05-25T09:00:00Z", "ada", "Ada Lovelace"),
+        lite("a0000502", "2026-05-26T09:00:00Z", "grace", "Grace Hopper"),
+        lite("a0000503", "2026-05-27T09:00:00Z", "alan", "Alan Turing"),
+        lite("a0000504", "2026-05-28T09:00:00Z", "ada", "Ada Lovelace"),
+        lite("a0000505", "2026-05-29T09:00:00Z", "grace", "Grace Hopper"),
+        // 2026-05-18 — 4
+        lite("a0001801", "2026-05-18T09:00:00Z", "ada", "Ada Lovelace"),
+        lite("a0001802", "2026-05-19T09:00:00Z", "alan", "Alan Turing"),
+        lite("a0001803", "2026-05-20T09:00:00Z", "grace", "Grace Hopper"),
+        lite("a0001804", "2026-05-22T09:00:00Z", "katherine", "Katherine Johnson"),
+        // 2026-05-11 — 3
+        lite("a0001101", "2026-05-11T09:00:00Z", "ada", "Ada Lovelace"),
+        lite("a0001102", "2026-05-13T09:00:00Z", "grace", "Grace Hopper"),
+        lite("a0001103", "2026-05-15T09:00:00Z", "alan", "Alan Turing"),
+        // 2026-05-04 — 2
+        lite("a0000401", "2026-05-04T09:00:00Z", "ada", "Ada Lovelace"),
+        lite("a0000402", "2026-05-07T09:00:00Z", "katherine", "Katherine Johnson"),
+        // 2026-04-27 — 3
+        lite("a0002701", "2026-04-27T09:00:00Z", "grace", "Grace Hopper"),
+        lite("a0002702", "2026-04-29T09:00:00Z", "ada", "Ada Lovelace"),
+        lite("a0002703", "2026-05-01T09:00:00Z", "alan", "Alan Turing"),
+        // 2026-04-20 — 2
+        lite("a0002001", "2026-04-20T09:00:00Z", "ada", "Ada Lovelace"),
+        lite("a0002002", "2026-04-24T09:00:00Z", "grace", "Grace Hopper"),
+        // 2026-04-13 — 2
+        lite("a0001301", "2026-04-13T09:00:00Z", "alan", "Alan Turing"),
+        lite("a0001302", "2026-04-17T09:00:00Z", "ada", "Ada Lovelace"),
+    ],
+    weeklyActivity: activityWeeks(LAST_SUNDAY, [11, 9, 14, 8, 12, 10, 9, 13]),
+    weeklyCodeFrequency: codeFreqWeeks(LAST_SUNDAY, [
+        [1200, -400], [900, -260], [1500, -520], [640, -180],
+        [1100, -300], [980, -410], [720, -220], [814, -140],
+    ]),
+    stars: { total: 4200, deltaInWindow: 37, deltaPrevWindow: 21 },
+    pulls: { open: 12, openedInWindow: 9, mergedInWindow: 7 },
+    issues: { open: 42, openedInWindow: 6, closedInWindow: 8 },
+    coverage: { authenticated: true, commitDetails: "full", pulls: true, issues: true, starDeltas: true },
+    rateLimit: { limit: 5000, remaining: 4923 },
+};

package/dist/m0saic/github/week-math.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure calendar arithmetic for the GitHub connector — ISO-8601 weeks and
+ * Monday-start week windows.
+ *
+ * DETERMINISM CONTRACT: every function here is a pure integer computation over
+ * `"YYYY-MM-DD"` strings — NO `Date` construction, NO wall-clock. This is what
+ * lets the core-tier `weekly-pulse-adapter` (and the beats) stay deterministic
+ * while still doing week math, and it extends the `parseISODate` idiom already
+ * in `hero/ffmpeg-pulse/_shared/pulse-data.ts`. Shared by: the client (window →
+ * since/until), the adapter (weekNumber, trailing-8 grid), and — later — the
+ * Jobs window tokens (F5 Phase 5), which import these instead of re-deriving.
+ *
+ * The engine (proleptic Gregorian) day-count is Howard Hinnant's
+ * `days_from_civil` / `civil_from_days` — exact for all in-range dates, integer
+ * throughout.
+ */
+/** A calendar date as integer parts (UTC, proleptic Gregorian). */
+export type YMD = {
+    y: number;
+    m: number;
+    d: number;
+};
+/** Parse `"YYYY-MM-DD"` (optionally with a trailing time) into integer parts. */
+export declare function parseISODate(iso: string): YMD;
+/** Format integer parts back to `"YYYY-MM-DD"` (zero-padded). */
+export declare function formatISODate({ y, m, d }: YMD): string;
+/** Days since 1970-01-01 for a civil date. Pure integer (Hinnant). */
+export declare function daysFromCivil(y: number, m: number, d: number): number;
+/** Civil date from a 1970-epoch day-count. Inverse of {@link daysFromCivil}. */
+export declare function civilFromDays(z: number): YMD;
+/** Add `n` days (may be negative) to an ISO date, returning a new ISO date. */
+export declare function addDaysISO(iso: string, n: number): string;
+/** ISO day-of-week: 0 = Monday … 6 = Sunday. */
+export declare function isoDayOfWeek(iso: string): number;
+/** The Monday (`"YYYY-MM-DD"`) of the ISO week containing `iso`. */
+export declare function mondayOfISO(iso: string): string;
+/** ISO-8601 week number (1–53) of the week containing `iso`. */
+export declare function isoWeekNumber(iso: string): number;
+/**
+ * The most recent COMPLETE Monday..Sunday week STRICTLY before `todayISO`.
+ *
+ * The week containing `todayISO` is never complete before its own Sunday
+ * elapses, so the last guaranteed-complete week is always the one before it —
+ * `[thisMonday - 7d, thisMonday - 1d]` — regardless of which weekday `today` is.
+ * This is the window the Jobs `{{lastFullWeek*}}` tokens resolve to (F5 P5).
+ */
+export declare function lastFullWeek(todayISO: string): {
+    startISO: string;
+    endISO: string;
+};