@m0saic/templates 0.2.0

package/dist/m0saic/github/weekly-pulse-adapter/v1/weekly-pulse-adapter.d.ts

@@ -0,0 +1,35 @@
+import type { MosaicDocument, MosaicTemplateUpstreamData, MosaicTemplateUpstreamVariables } from "@m0saic/types";
+import type { WeeklyPulse } from "../../../hero/ffmpeg-pulse/_shared/pulse-data";
+/**
+ * `@m0saic/github/weekly-pulse-adapter/v1` — the core-tier PURE adapter (F5
+ * Seam C). Reads the upstream `githubRepoFacts` block (published by
+ * `repo-facts-fetcher/v1`), derives the `WeeklyPulse` sheet the ffmpeg-pulse
+ * beats consume, and re-publishes it under the alias `weeklyPulse` (+ sidecar).
+ *
+ * `role: "adapter"` (new in `@m0saic/types` this Feature). Zero network, zero
+ * clock, zero randomness — a pure function of the facts + props. The
+ * `githubRepoFacts` upstream block is REQUIRED: a missing producer surfaces as a
+ * resolve-time `VARIABLES_SCHEMA_MISMATCH` (the required-key schema below) AND a
+ * hard render error (no props fallback by design).
+ */
+export type WeeklyPulseAdapterProps = {
+    /** Override the adaptive KPI selection (ordered keys). */
+    kpiKeys?: string[];
+    /** Notable-commit feed length (default 5). */
+    notableCount?: number;
+    /** Path segments defining a "changed area" (default 1). */
+    areaDepth?: number;
+    /** Top-N contributors (default 5). */
+    topContributors?: number;
+};
+type WeeklyPulseAdapterSidecars = {
+    weeklyPulse: WeeklyPulse;
+};
+/** The fixed publish alias — part of the adapter's producer contract. */
+export declare const WEEKLY_PULSE_ALIAS = "weeklyPulse";
+/** The upstream alias this adapter consumes. */
+export declare const GITHUB_REPO_FACTS_UPSTREAM_ALIAS = "githubRepoFacts";
+/** Wrap a derived pulse sheet in the carrier + aliased-data + sidecar document. */
+export declare function pulseToDocument(pulse: WeeklyPulse): MosaicDocument;
+export declare const WeeklyPulseAdapter: import("@m0saic/types").MosaicTemplate<WeeklyPulseAdapterProps, WeeklyPulse, MosaicTemplateUpstreamVariables, MosaicTemplateUpstreamData, WeeklyPulseAdapterSidecars>;
+export default WeeklyPulseAdapter;

package/dist/m0saic/github/weekly-pulse-adapter/v1/weekly-pulse-adapter.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WeeklyPulseAdapter = exports.GITHUB_REPO_FACTS_UPSTREAM_ALIAS = exports.WEEKLY_PULSE_ALIAS = void 0;
+exports.pulseToDocument = pulseToDocument;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const derive_pulse_1 = require("./derive-pulse");
+/** The fixed publish alias — part of the adapter's producer contract. */
+exports.WEEKLY_PULSE_ALIAS = "weeklyPulse";
+/** The upstream alias this adapter consumes. */
+exports.GITHUB_REPO_FACTS_UPSTREAM_ALIAS = "githubRepoFacts";
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    kpiKeys: {
+        type: "string[]", required: false,
+        description: "Override the adaptive KPI selection with an explicit ordered key list.",
+        meta: { ui: { label: "KPI keys", order: 1, consumer: "agent" } },
+    },
+    notableCount: {
+        type: "number", required: false,
+        description: "Number of notable commits in the feed.",
+        meta: { constraints: { min: 1, max: 12 }, ui: { label: "Notable count", order: 2 } },
+    },
+    areaDepth: {
+        type: "number", required: false,
+        description: "Path segments that define a changed area (1 = top-level dir).",
+        meta: { constraints: { min: 1, max: 4 }, ui: { label: "Area depth", order: 3 } },
+    },
+    topContributors: {
+        type: "number", required: false,
+        description: "Top-N contributors in the table.",
+        meta: { constraints: { min: 1, max: 12 }, ui: { label: "Top contributors", order: 4 } },
+    },
+});
+/** Wrap a derived pulse sheet in the carrier + aliased-data + sidecar document. */
+function pulseToDocument(pulse) {
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)("1", "weeklyPulse"),
+        assets: {},
+        sources: [
+            { type: "lavfi", color: "#000000" },
+            {
+                type: "data",
+                alias: (0, types_1.asAliasId)(exports.WEEKLY_PULSE_ALIAS),
+                variables: pulse,
+                editor: { owner: "template" },
+            },
+        ],
+        sidecars: { weeklyPulse: pulse },
+    };
+}
+exports.WeeklyPulseAdapter = (0, template_utils_1.defineMosaicTemplate)({
+    id: (0, types_1.asTemplateId)("@m0saic/github/weekly-pulse-adapter/v1"),
+    label: "Weekly Pulse Adapter",
+    version: 1,
+    description: "Pure core-tier adapter: reads the upstream githubRepoFacts block and derives the WeeklyPulse sheet (adaptive KPIs, activity + heatmap, contributors, changes-by-area, notable commits) for the ffmpeg-pulse beats. Zero network/clock/randomness; the githubRepoFacts producer is required.",
+    role: "adapter",
+    capabilities: { tier: "core" },
+    // A data carrier between the fetcher and the beats, not a picture: with no
+    // upstream githubRepoFacts block (the only way a picker can open it) its
+    // render IS the error frame. Off the public shelf like the fetcher
+    // (founder, 2026-09-16) — still reachable by id for pipelines.
+    internal: true,
+    tags: ["utility", "github", "connector", "adapter", "pulse", "developers"],
+    outputHints: {
+        format: { kind: "image", container: "png" },
+        width: 64,
+        height: 64,
+        fps: 1,
+        durationMs: 1000,
+        note: "Publishes weeklyPulse; renders only a degenerate black carrier tile. Wrap in a pipeline step with intermediate:true.",
+    },
+    // REQUIRED upstream block — a present-but-drifted block errors at resolve time
+    // (VARIABLES_SCHEMA_MISMATCH); an absent one errors too (required keys).
+    upstreamDataSchema: {
+        githubRepoFacts: {
+            description: "Repo-facts sheet published by @m0saic/github/repo-facts-fetcher/v1.",
+            variables: {
+                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 },
+                coverage: { type: "object", required: true },
+            },
+        },
+    },
+    outputsSchema: {
+        repo: { type: "object", required: true },
+        period: { type: "object", required: true },
+        kpis: { type: "any", required: true },
+        activity: { type: "object", required: true },
+        contributors: { type: "object", required: true },
+        changes: { type: "object", required: true },
+        notable: { type: "object", required: true },
+        fin: { type: "object", required: true },
+    },
+    propsSchema,
+    defaultProps: {
+        notableCount: 5,
+        areaDepth: 1,
+        topContributors: 5,
+    },
+    async render(props, ctx) {
+        const facts = (0, template_utils_1.getUpstreamBlock)(ctx, exports.GITHUB_REPO_FACTS_UPSTREAM_ALIAS);
+        if (!facts || typeof facts !== "object") {
+            // Degrade, don't throw: return a valid error-frame document so the render
+            // still completes. It publishes NO `weeklyPulse`, so a downstream beat /
+            // runner sees the data is missing and can surface its own error frame. The
+            // required `upstreamDataSchema` block below is the loud resolve-time signal
+            // for a mis-wired pipeline; this is the graceful render-time fallback.
+            return (0, template_utils_1.makeErrorMosaic)("Required upstream block `githubRepoFacts` is absent — wire @m0saic/github/repo-facts-fetcher/v1 as an earlier pipeline step.", {
+                width: Math.max(1, Math.round(ctx.target.width)),
+                height: Math.max(1, Math.round(ctx.target.height)),
+                title: "Weekly Pulse Adapter",
+                errorCode: "MISSING_UPSTREAM_GITHUB_REPO_FACTS",
+            });
+        }
+        const pulse = (0, derive_pulse_1.deriveWeeklyPulse)(facts, {
+            kpiKeys: props.kpiKeys,
+            notableCount: props.notableCount,
+            areaDepth: props.areaDepth,
+            topContributors: props.topContributors,
+        });
+        return pulseToDocument(pulse);
+    },
+});
+(0, template_utils_1.registerTemplate)(exports.WeeklyPulseAdapter);
+exports.default = exports.WeeklyPulseAdapter;

package/dist/m0saic/github/year-card/index.d.ts

@@ -0,0 +1 @@
+export * from "./v1";

package/dist/m0saic/github/year-card/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./v1"), exports);

package/dist/m0saic/github/year-card/v1/index.d.ts

@@ -0,0 +1,2 @@
+export { YearCardV1, SAMPLE_CONTRIBUTIONS, bucketOf, calendarLayout, fmtCount, longestStreak, parseContributions, type CalendarLayout, type YearCardProps } from "./year-card";
+export { default } from "./year-card";

package/dist/m0saic/github/year-card/v1/index.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.parseContributions = exports.longestStreak = exports.fmtCount = exports.calendarLayout = exports.bucketOf = exports.SAMPLE_CONTRIBUTIONS = exports.YearCardV1 = void 0;
+var year_card_1 = require("./year-card");
+Object.defineProperty(exports, "YearCardV1", { enumerable: true, get: function () { return year_card_1.YearCardV1; } });
+Object.defineProperty(exports, "SAMPLE_CONTRIBUTIONS", { enumerable: true, get: function () { return year_card_1.SAMPLE_CONTRIBUTIONS; } });
+Object.defineProperty(exports, "bucketOf", { enumerable: true, get: function () { return year_card_1.bucketOf; } });
+Object.defineProperty(exports, "calendarLayout", { enumerable: true, get: function () { return year_card_1.calendarLayout; } });
+Object.defineProperty(exports, "fmtCount", { enumerable: true, get: function () { return year_card_1.fmtCount; } });
+Object.defineProperty(exports, "longestStreak", { enumerable: true, get: function () { return year_card_1.longestStreak; } });
+Object.defineProperty(exports, "parseContributions", { enumerable: true, get: function () { return year_card_1.parseContributions; } });
+var year_card_2 = require("./year-card");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(year_card_2).default; } });

package/dist/m0saic/github/year-card/v1/year-card.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ============================================================================
+ * @m0saic/github/year-card/v1 — a developer's year on GitHub, on one card
+ * ============================================================================
+ *
+ * The contribution calendar (7 weekday rows × 53 week columns, month labels
+ * along the top, weekday labels down the side, a Less → More legend) with a
+ * row of four numbers above it — commits, pull requests, stars, top language
+ * — and the handle + year in the header. The vanity share every developer
+ * posts; hand it a year of daily counts (365 numbers, or a comma string) and
+ * the totals in the KPI tiles.
+ *
+ * Construction is the alpine heatmap's v2 move at calendar scale: the cell
+ * matrix is one gutterless `grid(7×53)` — its precision is the cell COUNT,
+ * not the canvas — and the inter-cell gap is applied AFTER composition by
+ * lattice retargeting (`latticeCellInset` over the parsed cell rects), so
+ * the cells are equal and the gaps exact at any canvas. The cells are plain
+ * square tiles (no per-tile rounding mask — at 371 tiles that quadruples the
+ * render) and the reveal is ONE curtain track, not 371 overlays. Chrome is the alpine
+ * card kit, RATIO throughout. The weeks are placed by real calendar math
+ * (UTC, deterministic): the first column is the week of January 1st, cells
+ * outside the year paint the card colour.
+ *
+ * Determinism: the sample year is a fixed literal, no clock, no randomness.
+ * ============================================================================
+ */
+import type { MosaicTemplate } from "@m0saic/types";
+import { type ThemeSourceConfig } from "@m0saic/template-utils";
+import { type AlpinePreset } from "../../../alpine/_shared/alpine-theme";
+type RenderMode = "premium" | "light";
+type AnimConfig = {
+    renderMode?: RenderMode;
+    introFrac?: number;
+    reduceMotion?: boolean;
+};
+export type YearCardProps = {
+    /** GitHub handle, shown with the year in the header ("@qsbuilds · 2026 on GitHub"). */
+    handle?: string;
+    /** The calendar year. */
+    year?: number;
+    /** Daily contribution counts from January 1st (365/366 numbers, or one comma-separated string). Missing days are 0. */
+    contributions: number[] | string;
+    commits?: number;
+    pullRequests?: number;
+    stars?: number;
+    topLanguage?: string;
+    /** Show the four KPI tiles above the calendar. Default true. */
+    showKpis?: boolean;
+    preset?: AlpinePreset;
+    anim?: AnimConfig;
+    theme?: ThemeSourceConfig;
+    debugLayout?: boolean;
+};
+/** A fixed sample year (2026): 905 contributions over 217 days, a two-week break in August. */
+export declare const SAMPLE_CONTRIBUTIONS = "4,2,0,0,1,0,5,0,1,0,0,4,5,5,0,4,0,0,6,0,0,0,4,0,0,0,0,0,0,0,4,1,0,0,0,4,1,0,5,7,0,0,0,2,3,1,2,4,2,2,8,0,2,1,3,0,6,0,0,3,5,3,10,5,1,0,0,2,0,0,8,0,11,1,3,1,7,2,1,0,0,3,0,6,1,1,0,0,7,8,0,0,4,3,7,7,5,5,12,0,0,11,6,3,3,1,1,0,0,8,3,3,4,0,1,4,14,1,8,14,9,0,1,6,11,1,5,4,0,1,6,1,15,1,4,0,0,7,9,0,3,2,0,0,4,9,4,1,0,4,0,10,2,2,4,1,0,2,4,1,3,1,1,2,0,0,4,3,0,4,0,0,2,3,1,7,0,0,1,0,11,0,4,4,2,0,0,2,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,5,0,2,0,3,1,2,1,1,0,3,9,6,5,1,1,3,0,7,6,3,8,3,4,0,5,0,8,13,15,0,2,2,2,3,6,11,0,0,2,9,3,1,2,2,0,2,5,3,3,2,15,3,4,3,3,6,3,0,3,3,5,5,5,1,0,0,3,8,5,1,2,0,0,2,3,6,1,7,0,0,10,4,2,6,5,0,1,0,2,10,2,3,0,2,8,5,0,7,6,0,3,9,6,4,5,0,0,0,0,0,5,1,4,2,0,2,1,0,0,0,0,0,5,0,0,0,0,0,0,1,1,0,3,0,0,0,0,0,0,0,0,0,0,0,1,0,0";
+/** Daily counts from an array or a comma string; non-numbers → 0. */
+export declare function parseContributions(v: number[] | string | undefined): number[];
+export type CalendarLayout = {
+    /** Days in the year (365 / 366). */
+    days: number;
+    /** Weekday (0 = Sunday) of January 1st — the row the first cell lands in. */
+    firstDow: number;
+    /** For each month, the week column its first day falls in. */
+    monthCols: Array<{
+        label: string;
+        col: number;
+    }>;
+};
+/** Calendar geometry for `year` — UTC math, no clock. */
+export declare function calendarLayout(year: number): CalendarLayout;
+/** GitHub-style buckets: 0 for none, then four quartiles of the year's max. */
+export declare function bucketOf(v: number, max: number): number;
+/** Longest run of consecutive active days. */
+export declare function longestStreak(counts: number[]): number;
+export declare function fmtCount(n: number): string;
+/**
+ * `n` equal tiles separated by `n − 1` equal gutters of ~`gapFrac` of the row,
+ * as weights whose total is 5-smooth (≤ 120, the lattice). Rounding each band
+ * to a percent on its own (`wOf`) sums to 100 ± a few — 4×24 + 3×2 = 102 → a
+ * 51 = 3·17 basis — and `latticeWeights` cannot rewrite an item/gutter list
+ * onto a smooth total without making the tiles unequal, so the basis is
+ * chosen here, exactly: the smooth total whose gutter is nearest `gapFrac`.
+ */
+export declare function smoothTileRow(n: number, gapFrac: number): {
+    tile: number;
+    gap: number;
+    total: number;
+};
+export declare const YearCardV1: MosaicTemplate<YearCardProps>;
+export default YearCardV1;