@grove-dev/astro 0.1.4 → 0.2.2

package/dist/lib/lenses.js

@@ -0,0 +1,181 @@
+/**
+ * Curated lenses for the list / discovery page.
+ *
+ * A lens is a single-select view that translates into a (possibly
+ * empty) URL search-param filter. The 6 lenses below cover the
+ * "what should I look at next?" mental shortcut:
+ *
+ *   - "all"          — no filter
+ *   - "hot"          — recent attention: stars ≥ 1000 OR pushed within 30d
+ *   - "new"          — fresh entries: pushed within 7d OR curated "new" label
+ *   - "mature"       — long-running projects: curated tier AND pushed > 365d ago
+ *   - "featured"     — curated "featured" label
+ *   - "needs-review" — cleanup candidate (stale / archived / etc.)
+ *
+ * The lens id is what shows up in the URL as `?lens=...`. Filter
+ * resolution happens in `lib/search.ts` (`filterApps`).
+ *
+ * Keep this list in sync with `lib/search.ts` and any UI tabs.
+ */
+const DAY_MS = 86_400_000;
+function daysSince(iso) {
+    if (!iso)
+        return Infinity;
+    const d = new Date(iso);
+    if (Number.isNaN(d.valueOf()))
+        return Infinity;
+    return (Date.now() - d.valueOf()) / DAY_MS;
+}
+function hasLabel(record, label) {
+    return record.curation?.labels?.includes(label) ?? false;
+}
+const CLEANUP_STATUSES = [
+    "stale",
+    "inactive",
+    "archived",
+    "unavailable",
+    "needs_review",
+];
+function isCleanupCandidate(record) {
+    if (record.health?.cleanupCandidate)
+        return true;
+    const status = record.health?.status;
+    if (!status)
+        return false;
+    return CLEANUP_STATUSES.includes(status);
+}
+export const LENSES = [
+    {
+        id: "all",
+        label: "All",
+        description: "Every record in the directory.",
+        match: () => true,
+    },
+    {
+        id: "hot",
+        label: "Trending",
+        description: "Records with recent attention — stars ≥ 1000 or pushed within 30 days.",
+        match: (r) => {
+            const stars = r.github?.stars ?? 0;
+            const pushed = daysSince(r.github?.pushedAt);
+            return stars >= 1000 || pushed <= 30;
+        },
+    },
+    {
+        id: "new",
+        label: "Recently added",
+        description: "Fresh entries — pushed within 7 days or curated with the “new” label.",
+        match: (r) => {
+            const pushed = daysSince(r.github?.pushedAt);
+            return pushed <= 7 || hasLabel(r, "new");
+        },
+    },
+    {
+        id: "mature",
+        label: "Established",
+        description: "Long-running projects — curated tier and last push > 365 days ago.",
+        match: (r) => {
+            const tier = r.health?.tier;
+            const pushed = daysSince(r.github?.pushedAt);
+            return tier === "curated" && pushed > 365;
+        },
+    },
+    {
+        id: "featured",
+        label: "Featured",
+        description: "Records curated with the “featured” label.",
+        match: (r) => hasLabel(r, "featured"),
+    },
+    {
+        id: "needs-review",
+        label: "Needs review",
+        description: "Cleanup candidates — stale, archived, or unmaintained.",
+        match: (r) => isCleanupCandidate(r),
+    },
+];
+/**
+ * The lenses rendered as top-row tabs on the list page. Order
+ * matters — left to right. Keep this in sync with what the design
+ * calls for; URL deep-linking accepts any `LensId` even if it's not
+ * in the primary row.
+ */
+export const PRIMARY_LENSES = [
+    "all",
+    "hot",
+    "new",
+    "mature",
+    "featured",
+    "needs-review",
+];
+export function lensById(id) {
+    if (!id)
+        return undefined;
+    return LENSES.find((l) => l.id === id);
+}
+export function isPrimaryLens(id) {
+    if (!id)
+        return false;
+    return PRIMARY_LENSES.includes(id);
+}
+/**
+ * Resolve the active lens from URL search params. Returns the empty
+ * string when no `lens=...` is set, so callers can treat both
+ * "absent" and "unknown" identically.
+ */
+export function lensFromSearchParams(params) {
+    const v = params.get("lens");
+    if (!v)
+        return "";
+    if (LENSES.some((l) => l.id === v))
+        return v;
+    return "";
+}
+/**
+ * `true` when the URL search params currently reflect this lens's
+ * filter shape. The "all" lens is the implicit "no filter" state —
+ * it's active only when no other lens-shaped params are present.
+ */
+export function isLensActive(lensId, params) {
+    if (lensId === "all") {
+        return lensFromSearchParams(params) === "" && !params.get("label");
+    }
+    return lensFromSearchParams(params) === lensId;
+}
+/**
+ * Build a `href` for a lens tab. Selecting a lens resets the other
+ * "view" params (label, page) and applies only the chosen lens's
+ * filter. Other filters (q, stack, platform, category, sort) are
+ * preserved.
+ *
+ * `pathPrefix` is the URL root for the list page — typically
+ * `/projects` for the project-directory blueprint, `/resources` for
+ * resource-hub, `/entities` for ecosystem-map. Defaults to `/`.
+ */
+export function hrefForLens(lensId, params, pathPrefix = "/") {
+    const sp = new URLSearchParams(params);
+    sp.delete("lens");
+    sp.delete("label");
+    sp.delete("page");
+    if (lensId && lensId !== "all") {
+        sp.set("lens", lensId);
+    }
+    const qs = sp.toString();
+    const base = pathPrefix.replace(/\/$/, "");
+    return qs ? `${base}?${qs}` : base || "/";
+}
+/**
+ * Apply the lens filter to a record array. When `lensId` is
+ * `""` (no lens) or `"all"`, returns the input unchanged.
+ *
+ * Type-parameterized so the same helper works on `ProjectRecord[]`
+ * and on the lighter index payload that list pages ship.
+ */
+export function applyLens(records, lensId) {
+    if (!lensId || lensId === "all")
+        return records;
+    const def = lensById(lensId);
+    if (!def)
+        return records;
+    return records.filter((r) => def.match(r));
+}
+//# sourceMappingURL=lenses.js.map

package/dist/lib/lenses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lenses.js","sourceRoot":"","sources":["../../src/lib/lenses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA4BH,MAAM,MAAM,GAAG,UAAU,CAAC;AAqB1B,SAAS,SAAS,CAAC,GAA8B;IAC/C,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC/C,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC;AAC7C,CAAC;AAED,SAAS,QAAQ,CAAC,MAAe,EAAE,KAAa;IAC9C,OAAO,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;AAC3D,CAAC;AAED,MAAM,gBAAgB,GAAmB;IACvC,OAAO;IACP,UAAU;IACV,UAAU;IACV,aAAa;IACb,cAAc;CACf,CAAC;AAEF,SAAS,kBAAkB,CAAC,MAAe;IACzC,IAAI,MAAM,CAAC,MAAM,EAAE,gBAAgB;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IACrC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,OAAO,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAc;IAC/B;QACE,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,KAAK;QACZ,WAAW,EAAE,gCAAgC;QAC7C,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI;KAClB;IACD;QACE,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,UAAU;QACjB,WAAW,EACT,wEAAwE;QAC1E,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE;YACX,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,CAAC;YACnC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC7C,OAAO,KAAK,IAAI,IAAI,IAAI,MAAM,IAAI,EAAE,CAAC;QACvC,CAAC;KACF;IACD;QACE,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACT,uEAAuE;QACzE,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE;YACX,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC7C,OAAO,MAAM,IAAI,CAAC,IAAI,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC3C,CAAC;KACF;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,aAAa;QACpB,WAAW,EACT,oEAAoE;QACtE,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE;YACX,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC;YAC5B,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC7C,OAAO,IAAI,KAAK,SAAS,IAAI,MAAM,GAAG,GAAG,CAAC;QAC5C,CAAC;KACF;IACD;QACE,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,UAAU;QACjB,WAAW,EAAE,4CAA4C;QACzD,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAC;KACtC;IACD;QACE,EAAE,EAAE,cAAc;QAClB,KAAK,EAAE,cAAc;QACrB,WAAW,EAAE,wDAAwD;QACrE,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC;KACpC;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAa;IACtC,KAAK;IACL,KAAK;IACL,KAAK;IACL,QAAQ;IACR,UAAU;IACV,cAAc;CACf,CAAC;AAEF,MAAM,UAAU,QAAQ,CAAC,EAA6B;IACpD,IAAI,CAAC,EAAE;QAAE,OAAO,SAAS,CAAC;IAC1B,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAA6B;IACzD,IAAI,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IACtB,OAAO,cAAc,CAAC,QAAQ,CAAC,EAAY,CAAC,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAuB;IAEvB,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAClB,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,CAAW,CAAC;IACvD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,MAAuB;IAClE,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,OAAO,oBAAoB,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,oBAAoB,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC;AACjD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,MAAuB,EACvB,aAAqB,GAAG;IAExB,MAAM,EAAE,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClB,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClB,IAAI,MAAM,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QAC/B,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAoB,OAAY,EAAE,MAAmB;IAC5E,IAAI,CAAC,MAAM,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,OAAO,CAAC;IAChD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,GAAG;QAAE,OAAO,OAAO,CAAC;IACzB,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC"}

package/dist/lib/repo.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Parse a GitHub repo URL into its owner and repo components.
+ *
+ * Returns `null` (not `{ owner: null, repo: null }`) if the URL
+ * doesn't match the github.com path shape — this lets callers
+ * distinguish "no URL" from "URL without owner" with a single
+ * null check.
+ *
+ * Used in:
+ *  - ItemCard / AppCard avatar fallback (owner avatar via GitHub
+ *    avatars API).
+ *  - Detail page (showing owner + repo name in breadcrumb / header).
+ *  - Anywhere we need to display "@owner / repo" or link to the owner.
+ */
+export declare function getOwnerAndRepoFromRepoUrl(repoUrl: string | null | undefined): {
+    owner: string;
+    repo: string;
+} | null;
+/**
+ * Build a GitHub avatar URL for a given owner. Defaults to size 80
+ * which is the smallest "high quality" size in GitHub's avatar CDN.
+ *
+ * Returns a string (not nullable) so callers can plug the result
+ * straight into an `src` attribute. The avatar endpoint always
+ * returns a placeholder image for unknown owners, so the only
+ * reason to check `null` upstream is when you specifically want
+ * to render a different fallback (e.g. initials).
+ */
+export declare function getOwnerAvatarUrl(owner: string, size?: number): string;
+//# sourceMappingURL=repo.d.ts.map

package/dist/lib/repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../src/lib/repo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACjC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQxC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,MAAM,CAOlE"}

package/dist/lib/repo.js

@@ -0,0 +1,44 @@
+/**
+ * Parse a GitHub repo URL into its owner and repo components.
+ *
+ * Returns `null` (not `{ owner: null, repo: null }`) if the URL
+ * doesn't match the github.com path shape — this lets callers
+ * distinguish "no URL" from "URL without owner" with a single
+ * null check.
+ *
+ * Used in:
+ *  - ItemCard / AppCard avatar fallback (owner avatar via GitHub
+ *    avatars API).
+ *  - Detail page (showing owner + repo name in breadcrumb / header).
+ *  - Anywhere we need to display "@owner / repo" or link to the owner.
+ */
+export function getOwnerAndRepoFromRepoUrl(repoUrl) {
+    if (!repoUrl || !repoUrl.includes("github.com/"))
+        return null;
+    const m = repoUrl.match(/github\.com\/([^/]+)\/([^/?#]+)/);
+    if (!m)
+        return null;
+    return {
+        owner: m[1],
+        repo: m[2].replace(/\.git$/, ""),
+    };
+}
+/**
+ * Build a GitHub avatar URL for a given owner. Defaults to size 80
+ * which is the smallest "high quality" size in GitHub's avatar CDN.
+ *
+ * Returns a string (not nullable) so callers can plug the result
+ * straight into an `src` attribute. The avatar endpoint always
+ * returns a placeholder image for unknown owners, so the only
+ * reason to check `null` upstream is when you specifically want
+ * to render a different fallback (e.g. initials).
+ */
+export function getOwnerAvatarUrl(owner, size = 80) {
+    if (!owner) {
+        // Defensive: callers may pass a possibly-empty string. Return the
+        // generic GitHub identicon so an `<img>` doesn't 404.
+        return `https://avatars.githubusercontent.com/identicon?v=4&s=${size}`;
+    }
+    return `https://avatars.githubusercontent.com/${owner}?v=4&s=${size}`;
+}
+//# sourceMappingURL=repo.js.map

package/dist/lib/repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.js","sourceRoot":"","sources":["../../src/lib/repo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAkC;IAElC,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9D,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAC3D,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QACX,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;KACjC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,IAAI,GAAG,EAAE;IACxD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,kEAAkE;QAClE,sDAAsD;QACtD,OAAO,yDAAyD,IAAI,EAAE,CAAC;IACzE,CAAC;IACD,OAAO,yCAAyC,KAAK,UAAU,IAAI,EAAE,CAAC;AACxE,CAAC"}

package/dist/lib/scores.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Score-dimension utilities.
+ *
+ * Operates on the `scores` field of a `ProjectRecord` (or any
+ * object that has the same shape — defined as `Score` in
+ * `@grove-dev/core`). All helpers are dependency-free.
+ */
+import type { Score } from "@grove-dev/core";
+/**
+ * Format a single score (0-100) into a 0-5 "tier" used by the UI:
+ *
+ *   0-19  → 0  (very low)
+ *   20-39 → 1  (low)
+ *   40-59 → 2  (medium)
+ *   60-79 → 3  (high)
+ *   80-100 → 4 (very high)
+ *
+ * The list page renders each score as a 4-cell bar; this gives
+ * the visual a stable shape regardless of the underlying number.
+ */
+export declare function scoreTier(n: number): 0 | 1 | 2 | 3 | 4;
+/** Compact textual label for a score tier (used in tooltips). */
+export declare function scoreTierLabel(n: number): string;
+/** Short numeric label used inline next to a score bar, e.g. "82". */
+export declare function scoreLabel(n: number | undefined): string;
+/** Order of score dimensions, used by both list and detail. */
+export declare const SCORE_DIMENSIONS: (keyof Score)[];
+/** Human-readable label for a score dimension. */
+export declare const SCORE_LABELS: Record<keyof Score, string>;
+/**
+ * Reasoning copy per dimension, surfaced in the detail page so the
+ * numbers don't feel magical. These are intentionally short — the
+ * curation notes on each record carry the longer story.
+ */
+export declare const SCORE_REASONING: Record<keyof Score, string>;
+/** Re-export the `Score` type for callers that only need the lib API. */
+export type { Score };
+//# sourceMappingURL=scores.d.ts.map

package/dist/lib/scores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scores.d.ts","sourceRoot":"","sources":["../../src/lib/scores.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAMtD;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAahD;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGxD;AAED,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,EAAE,CAAC,MAAM,KAAK,CAAC,EAO3C,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,KAAK,EAAE,MAAM,CAOpD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,KAAK,EAAE,MAAM,CAavD,CAAC;AAEF,yEAAyE;AACzE,YAAY,EAAE,KAAK,EAAE,CAAC"}

package/dist/lib/scores.js

@@ -0,0 +1,83 @@
+/**
+ * Score-dimension utilities.
+ *
+ * Operates on the `scores` field of a `ProjectRecord` (or any
+ * object that has the same shape — defined as `Score` in
+ * `@grove-dev/core`). All helpers are dependency-free.
+ */
+/**
+ * Format a single score (0-100) into a 0-5 "tier" used by the UI:
+ *
+ *   0-19  → 0  (very low)
+ *   20-39 → 1  (low)
+ *   40-59 → 2  (medium)
+ *   60-79 → 3  (high)
+ *   80-100 → 4 (very high)
+ *
+ * The list page renders each score as a 4-cell bar; this gives
+ * the visual a stable shape regardless of the underlying number.
+ */
+export function scoreTier(n) {
+    if (n < 20)
+        return 0;
+    if (n < 40)
+        return 1;
+    if (n < 60)
+        return 2;
+    if (n < 80)
+        return 3;
+    return 4;
+}
+/** Compact textual label for a score tier (used in tooltips). */
+export function scoreTierLabel(n) {
+    switch (scoreTier(n)) {
+        case 0:
+            return "Very low";
+        case 1:
+            return "Low";
+        case 2:
+            return "Medium";
+        case 3:
+            return "High";
+        case 4:
+            return "Very high";
+    }
+}
+/** Short numeric label used inline next to a score bar, e.g. "82". */
+export function scoreLabel(n) {
+    if (typeof n !== "number")
+        return "—";
+    return Math.round(n).toString();
+}
+/** Order of score dimensions, used by both list and detail. */
+export const SCORE_DIMENSIONS = [
+    "activity",
+    "maturity",
+    "learning",
+    "contribution",
+    "docs",
+    "overall",
+];
+/** Human-readable label for a score dimension. */
+export const SCORE_LABELS = {
+    activity: "Activity",
+    maturity: "Maturity",
+    learning: "Learning",
+    contribution: "Contribution",
+    docs: "Docs",
+    overall: "Overall",
+};
+/**
+ * Reasoning copy per dimension, surfaced in the detail page so the
+ * numbers don't feel magical. These are intentionally short — the
+ * curation notes on each record carry the longer story.
+ */
+export const SCORE_REASONING = {
+    activity: "Recent commits, open and merged PRs, issue response time, release cadence.",
+    maturity: "Repo age, stable structure, real-world production usage, contributor stability.",
+    learning: "Codebase readability, useful architecture patterns, comment quality, examples.",
+    contribution: "Open issues, recent merged PRs from new contributors, maintainer responsiveness, contribution guide.",
+    docs: "README quality, architecture docs, contributing guide, examples, code comments.",
+    overall: "Composite judgment — how likely this record is to satisfy a curious developer.",
+};
+//# sourceMappingURL=scores.js.map

package/dist/lib/scores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scores.js","sourceRoot":"","sources":["../../src/lib/scores.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,CAAC,CAAC;IACrB,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,CAAC,CAAC;IACrB,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,CAAC,CAAC;IACrB,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,CAAC,CAAC;IACrB,OAAO,CAAC,CAAC;AACX,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,cAAc,CAAC,CAAS;IACtC,QAAQ,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,KAAK,CAAC;YACJ,OAAO,UAAU,CAAC;QACpB,KAAK,CAAC;YACJ,OAAO,KAAK,CAAC;QACf,KAAK,CAAC;YACJ,OAAO,QAAQ,CAAC;QAClB,KAAK,CAAC;YACJ,OAAO,MAAM,CAAC;QAChB,KAAK,CAAC;YACJ,OAAO,WAAW,CAAC;IACvB,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,UAAU,CAAC,CAAqB;IAC9C,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AAClC,CAAC;AAED,+DAA+D;AAC/D,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C,UAAU;IACV,UAAU;IACV,UAAU;IACV,cAAc;IACd,MAAM;IACN,SAAS;CACV,CAAC;AAEF,kDAAkD;AAClD,MAAM,CAAC,MAAM,YAAY,GAAgC;IACvD,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,YAAY,EAAE,cAAc;IAC5B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAgC;IAC1D,QAAQ,EACN,4EAA4E;IAC9E,QAAQ,EACN,iFAAiF;IACnF,QAAQ,EACN,gFAAgF;IAClF,YAAY,EACV,sGAAsG;IACxG,IAAI,EACF,iFAAiF;IACnF,OAAO,EACL,gFAAgF;CACnF,CAAC"}

package/dist/lib/search.d.ts

@@ -0,0 +1,199 @@
+/**
+ * URL-driven search/filter/sort state for the directory list page.
+ *
+ * Multi-value fields use repeated keys: `?stack=Flutter&stack=RN`.
+ * Single-value fields (q, sort, page, lens) are scalar. Empty
+ * / undefined fields mean "no filter on this dimension".
+ *
+ * The functions here are generic over a record-like shape that
+ * carries the index payload (see `toIndexRecord` in
+ * `@grove-dev/core`). The list page only needs `name`, `slug`,
+ * `description`, `category`, `tags`, `stack`, `stacks`, `platforms`,
+ * `repoUrl`, `logoUrl`, `health`, `curation`, and `github.{stars,
+ * pushedAt}` — all of which are present in the index projection.
+ */
+import type { HealthStatus, ProjectRecord } from "@grove-dev/core";
+import { type LensId } from "./lenses.js";
+/**
+ * Subset of `ProjectRecord` the search lib actually reads. Defined
+ * inline so the lib works on both full records and the lighter
+ * index payload. Use `ProjectRecord` from core when you have it;
+ * pass any object that satisfies `Searchable` otherwise.
+ *
+ * `Searchable` is a superset of `AppLike` (the lens-matching shape
+ * in `lib/lenses.ts`) — both interfaces share the same optional
+ * field shape, so `Searchable` records can be passed to
+ * `applyLens()` and `filterApps()` interchangeably.
+ */
+export interface Searchable {
+    slug?: string;
+    name: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+    stack?: string;
+    stacks?: string[];
+    platforms?: string[];
+    /** Canonical repo URL — used for owner extraction in text search. */
+    repoUrl?: string;
+    logoUrl?: string;
+    /** Curated labels (new, hot, mature, featured). */
+    curation?: {
+        labels?: string[];
+    };
+    /** Health block — drives status filter + tier fallback. */
+    health?: {
+        status?: HealthStatus;
+        tier?: "curated" | "listed" | "experimental" | "hidden";
+        visibility?: "highlight" | "keep" | "needs_review" | "hide" | "remove" | "historical";
+        cleanupCandidate?: boolean;
+    };
+    /** GitHub metadata used for sort + text search. */
+    github?: {
+        stars?: number;
+        forks?: number;
+        pushedAt?: string | null;
+        license?: string | null;
+    };
+    /** Score block — used for "best-overall" sort. */
+    scores?: {
+        activity?: number;
+        maturity?: number;
+        learning?: number;
+        contribution?: number;
+        docs?: number;
+        overall?: number;
+    };
+}
+export type AppsFilters = {
+    q?: string;
+    /** Stack slugs, repeated URL key `stack=`. Matches against `stack` AND `stacks[]`. */
+    stacks?: string[];
+    /** Platform slugs, repeated URL key `platform=`. Matches `platforms[]`. */
+    platforms?: string[];
+    /** Category names, repeated URL key `category=`. */
+    categories?: string[];
+    /** Curated label ids (new/hot/mature/featured), repeated URL key `label=`. */
+    labels?: string[];
+    /** SPDX license ids, repeated URL key `license=`. */
+    licenses?: string[];
+    /** Health status values, comma-separated repeated URL key `status=`. */
+    statuses?: string[];
+    /** A curated lens (single-select view). */
+    lens?: LensId;
+    /** Sort order. Single value, defaults to "recently-updated". */
+    sort?: AppsSort;
+    /** 1-based page number. */
+    page?: number;
+};
+/** Available sort orders, in UI order. */
+export declare const SORT_OPTIONS: readonly [{
+    readonly value: "recently-updated";
+    readonly label: "Recently updated";
+}, {
+    readonly value: "most-starred";
+    readonly label: "Most starred";
+}, {
+    readonly value: "recently-added";
+    readonly label: "Recently added";
+}, {
+    readonly value: "best-overall";
+    readonly label: "Best overall";
+}, {
+    readonly value: "alphabetical";
+    readonly label: "Alphabetical";
+}];
+export type AppsSort = (typeof SORT_OPTIONS)[number]["value"];
+/**
+ * How many records per page. Constant for now; future versions may
+ * vary per blueprint.
+ */
+export declare const PAGE_SIZE = 24;
+/**
+ * Read filters from a URLSearchParams (or anything URLSearchParams-
+ * shaped, e.g. the result of `new URL(req.url).searchParams`).
+ */
+export declare function filtersFromSearchParams(sp: URLSearchParams): AppsFilters;
+/**
+ * Serialize a filters object back to URLSearchParams. Undefined /
+ * empty values are dropped. Defaults (sort, page 1) are also dropped
+ * to keep URLs short and canonical.
+ */
+export declare function searchParamsFromFilters(f: AppsFilters): URLSearchParams;
+/**
+ * True if any filter is active (i.e. the result list isn't "all
+ * records, default sort").
+ */
+export declare function hasAnyFilter(f: AppsFilters): boolean;
+/**
+ * Return the subset of records that match all active filters (AND
+ * across dimensions, OR within a dimension).
+ *
+ * `q` is a case-insensitive substring search across name, owner,
+ * description, category, stack/stacks/platforms, tags, and license.
+ * Other dimensions are exact match.
+ */
+export declare function filterApps<T extends Searchable>(records: T[], f: AppsFilters): T[];
+/**
+ * Apply lens → filter → sort pipeline. Lens is applied first because
+ * it's a single-select "view" that may be broader or narrower than
+ * the regular filter dimensions.
+ */
+export declare function pipeline<T extends Searchable>(records: T[], filters: AppsFilters): T[];
+/**
+ * Sort records in-place-free: returns a new array. Stable for ties.
+ * Records missing the sort key (e.g. no stars) sink to the bottom
+ * rather than vanishing.
+ */
+export declare function applySort<T extends Searchable>(records: T[], sort: AppsSort): T[];
+/** Slice an array for a given page (1-based). */
+export declare function paginate<T>(items: T[], page: number, pageSize?: number): T[];
+/** Total number of pages given an item count. Always >= 1. */
+export declare function totalPages(itemCount: number, pageSize?: number): number;
+/** Resolve the effective sort from a filters object, applying default. */
+export declare function effectiveSort(f: AppsFilters): AppsSort;
+/** Resolve the effective page from a filters object, applying default. */
+export declare function effectivePage(f: AppsFilters): number;
+/**
+ * Return a flat list of active-filter chips for display + removal.
+ * Used by the "x" button on each chip in the UI.
+ */
+export declare function activeFilterChips(f: AppsFilters): {
+    key: keyof AppsFilters;
+    value: string;
+    label: string;
+}[];
+/**
+ * Build the full list of facet values from the record array,
+ * preserving a sensible order (frequency desc, then alphabetical
+ * for ties).
+ */
+export declare function buildFacets<T extends Searchable>(records: T[]): {
+    stacks: {
+        value: string;
+        count: number;
+    }[];
+    platforms: {
+        value: string;
+        count: number;
+    }[];
+    categories: {
+        value: string;
+        count: number;
+    }[];
+    labels: {
+        value: string;
+        count: number;
+    }[];
+    licenses: {
+        value: string;
+        count: number;
+    }[];
+};
+/**
+ * Re-export the `ProjectRecord` type so consumers of the search lib
+ * can write `import type { ProjectRecord } from "@grove-dev/astro/lib"`
+ * without a second import.
+ */
+export type { ProjectRecord };
+//# sourceMappingURL=search.d.ts.map

package/dist/lib/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"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"}