@grove-dev/core 0.7.0 → 0.9.0

package/dist/schema.js

@@ -1,6 +1,6 @@
-import { z } from "zod";
-import { parse, stringify } from "yaml";
-import { DEFAULT_FACETS, FACET_IDS } from "./directory-facets.js";
+import { parse, stringify } from 'yaml';
+import { z } from 'zod';
+import { DEFAULT_FACETS, FACET_IDS } from './directory-facets.js';
 // ──────────────────────────────────────────────────────────────────────
 // Blueprints and kinds
 // ──────────────────────────────────────────────────────────────────────
@@ -10,91 +10,82 @@ import { DEFAULT_FACETS, FACET_IDS } from "./directory-facets.js";
  * V1 ships three fixed blueprints. They are not extensible — no custom
  * blueprint API in V1.
  */
-export const blueprintSchema = z.enum([
-    "project-directory",
-    "resource-hub",
-    "ecosystem-map",
-]);
+export const blueprintSchema = z.enum(['project-directory', 'resource-hub', 'ecosystem-map']);
 /**
  * Each blueprint is bound to a single resource kind. Records are
  * discriminated by `kind`, which must match the blueprint of the site
  * that owns them.
  */
-export const resourceKindSchema = z.enum(["project", "resource", "entity"]);
+export const resourceKindSchema = z.enum(['project', 'resource', 'entity']);
 export const blueprintKind = {
-    "project-directory": "project",
-    "resource-hub": "resource",
-    "ecosystem-map": "entity",
+    'project-directory': 'project',
+    'resource-hub': 'resource',
+    'ecosystem-map': 'entity',
 };
 // ──────────────────────────────────────────────────────────────────────
 // Health & decision labels
 // ──────────────────────────────────────────────────────────────────────
 export const healthStatusSchema = z.enum([
-    "active",
-    "mature",
-    "stale",
-    "inactive",
-    "archived",
-    "unknown",
-    "historical",
-    "needs_review",
-    "quiet",
-    "unavailable",
+    'active',
+    'mature',
+    'stale',
+    'inactive',
+    'archived',
+    'unknown',
+    'historical',
+    'needs_review',
+    'quiet',
+    'unavailable',
 ]);
 export const decisionVisibilitySchema = z.enum([
-    "highlight",
-    "keep",
-    "needs_review",
-    "hide",
-    "remove",
-    "historical",
-]);
-export const healthTierSchema = z.enum([
-    "curated",
-    "listed",
-    "experimental",
-    "hidden",
+    'highlight',
+    'keep',
+    'needs_review',
+    'hide',
+    'remove',
+    'historical',
 ]);
+export const healthTierSchema = z.enum(['curated', 'listed', 'experimental', 'hidden']);
 // ──────────────────────────────────────────────────────────────────────
 // Curation enums (shared)
 // ──────────────────────────────────────────────────────────────────────
 export const projectTypeSchema = z.enum([
-    "real-app",
-    "production",
-    "reference",
-    "library",
-    "tool",
-    "demo",
-    "template",
-    "historical",
+    'real-app',
+    'production',
+    'reference',
+    'library',
+    'tool',
+    'demo',
+    'template',
+    'historical',
 ]);
 export const resourceTypeSchema = z.enum([
-    "guide",
-    "comparison",
-    "link",
-    "explainer",
-    "tool",
-    "video",
-    "article",
-    "course",
-    "book",
-    "podcast",
-    "other",
+    'guide',
+    'comparison',
+    'link',
+    'explainer',
+    'tool',
+    'video',
+    'article',
+    'course',
+    'book',
+    'podcast',
+    'other',
 ]);
 export const entityTypeSchema = z.enum([
-    "company",
-    "organization",
-    "community",
-    "school",
-    "university",
-    "research-lab",
-    "agency",
-    "service",
-    "product",
-    "person",
-    "other",
+    'company',
+    'organization',
+    'community',
+    'school',
+    'university',
+    'research-lab',
+    'agency',
+    'service',
+    'product',
+    'person',
+    'other',
 ]);
-export const appLabelSchema = z.enum(["new", "hot", "mature", "featured"]);
+export const appLabelSchema = z.enum(['new', 'hot', 'mature', 'featured']);
 export const scoreSchema = z.object({
     activity: z.number().min(0).max(100).optional(),
     maturity: z.number().min(0).max(100).optional(),
@@ -189,20 +180,17 @@ export const githubMetadataSchema = z.object({
     size: z.number().int().nonnegative().optional(),
     files: z.record(z.string(), z.boolean()).optional(),
     monthlyCommits: z
-        .array(z.union([
-        z.number(),
-        z.object({ month: z.string(), commits: z.number() }),
-    ]))
+        .array(z.union([z.number(), z.object({ month: z.string(), commits: z.number() })]))
         .optional(),
 });
 export const healthBlockSchema = z.object({
-    status: healthStatusSchema.default("unknown"),
-    maturity: z.enum(["experimental", "useful", "mature", "unknown"]).default("unknown"),
-    tier: healthTierSchema.default("experimental"),
-    visibility: decisionVisibilitySchema.default("keep"),
+    status: healthStatusSchema.default('unknown'),
+    maturity: z.enum(['experimental', 'useful', 'mature', 'unknown']).default('unknown'),
+    tier: healthTierSchema.default('experimental'),
+    visibility: decisionVisibilitySchema.default('keep'),
     cleanupCandidate: z.boolean().default(false),
     staleReason: z.string().nullable().optional(),
-    confidence: z.enum(["low", "medium", "high"]).default("medium"),
+    confidence: z.enum(['low', 'medium', 'high']).default('medium'),
     reasons: z.array(z.string()).default([]),
 });
 export const healthEntrySchema = z.object({
@@ -259,7 +247,18 @@ const curationBlockSchema = z
 // ──────────────────────────────────────────────────────────────────────
 const resourceBaseSchema = z.object({
     slug: z.string().min(1),
-    description: z.string().default(""),
+    /**
+     * When this record joined the directory — an ISO date or date-time.
+     *
+     * Distinct from `curation.reviewedAt`, which records when a human
+     * last reviewed the record. A record can be added today and reviewed
+     * never, or added last year and reviewed this morning; the
+     * `recently-added` sort and llms.txt's `added:` line want the former.
+     * Optional so records written before this field existed still
+     * validate — `recordAddedAt` falls back for them.
+     */
+    addedAt: z.string().optional(),
+    description: z.string().default(''),
     /**
      * Open Apps-written summary, surfaced as the lead paragraph on the
      * detail page above the original (GitHub-sourced) description.
@@ -275,21 +274,22 @@ const resourceBaseSchema = z.object({
      * overwriting what GitHub says the project is.
      */
     sourceDescription: z.string().optional(),
-    category: z.string().min(1).default("uncategorized"),
+    category: z.string().min(1).default('uncategorized'),
     tags: z.array(z.string()).default([]),
     links: linksSchema,
     content: z.string().optional(), // path to markdown body under content/records/
     source: z
         .object({
-        type: z.enum(["manual", "github-topic", "awesome-list", "submit", "import"])
-            .default("manual"),
+        type: z
+            .enum(['manual', 'github-topic', 'awesome-list', 'submit', 'import'])
+            .default('manual'),
         file: z.string().optional(),
         url: z.string().optional(),
         provider: z.string().optional(),
         owner: z.string().optional(),
         repo: z.string().optional(),
     })
-        .default({ type: "manual" }),
+        .default({ type: 'manual' }),
     curation: curationBlockSchema,
     scores: scoreSchema.default({}),
     /**
@@ -300,13 +300,26 @@ const resourceBaseSchema = z.object({
      * Defaults to "keep" so existing YAML files without the field
      * continue to validate.
      */
-    visibility: decisionVisibilitySchema.default("keep"),
+    visibility: decisionVisibilitySchema.default('keep'),
+    /**
+     * Curator override for the detail page's `<title>`/meta description.
+     * Mirrors `CollectionSeo` (`collections.ts`) — when set, it wins
+     * verbatim over the computed title/descriptor so a curator can hand-
+     * write a sharper title than the generic "Open-source {category}
+     * {noun}" fallback for a specific record.
+     */
+    seo: z
+        .object({
+        title: z.string().optional(),
+        description: z.string().optional(),
+    })
+        .optional(),
 });
 // ──────────────────────────────────────────────────────────────────────
 // Blueprint: project-directory — kind: project
 // ──────────────────────────────────────────────────────────────────────
 export const projectRecordSchema = resourceBaseSchema.extend({
-    kind: z.literal("project"),
+    kind: z.literal('project'),
     name: z.string().min(1),
     projectType: projectTypeSchema.optional(),
     stack: z.string().optional(),
@@ -316,8 +329,8 @@ export const projectRecordSchema = resourceBaseSchema.extend({
     // authored when a record is curated; otherwise derived from the
     // GitHub sync's `license.spdx_id` field at build time.
     licenses: z.array(z.string()).default([]),
-    difficulty: z.enum(["beginner", "intermediate", "advanced"]).optional(),
-    codebaseSize: z.enum(["small", "medium", "large", "huge"]).optional(),
+    difficulty: z.enum(['beginner', 'intermediate', 'advanced']).optional(),
+    codebaseSize: z.enum(['small', 'medium', 'large', 'huge']).optional(),
     // Canonical repo URL. Distinct from `links.github`, which is the
     // human-facing link on the page; `repoUrl` is the single source
     // for owner/repo extraction, avatar fallback, and "view repo" CTAs.
@@ -365,10 +378,7 @@ export const projectRecordSchema = resourceBaseSchema.extend({
         .object({
         repository: githubRepositorySchema.optional(),
         languages: z.record(z.string(), z.number()).optional(),
-        latestRelease: z.record(z.string(), z.unknown()).nullable().optional(),
         activity: z.record(z.string(), z.unknown()).optional(),
-        files: z.record(z.string(), z.boolean()).optional(),
-        labels: z.array(z.record(z.string(), z.unknown())).optional(),
         sync: z.record(z.string(), z.unknown()).optional(),
     })
         .passthrough()
@@ -379,7 +389,7 @@ export const projectRecordSchema = resourceBaseSchema.extend({
 // Blueprint: resource-hub — kind: resource
 // ──────────────────────────────────────────────────────────────────────
 export const resourceRecordSchema = resourceBaseSchema.extend({
-    kind: z.literal("resource"),
+    kind: z.literal('resource'),
     title: z.string().min(1),
     type: resourceTypeSchema,
     topic: z.string().min(1),
@@ -391,7 +401,7 @@ export const resourceRecordSchema = resourceBaseSchema.extend({
 // Blueprint: ecosystem-map — kind: entity
 // ──────────────────────────────────────────────────────────────────────
 export const entityRecordSchema = resourceBaseSchema.extend({
-    kind: z.literal("entity"),
+    kind: z.literal('entity'),
     name: z.string().min(1),
     type: entityTypeSchema,
     founded: z.string().optional(),
@@ -402,7 +412,7 @@ export const entityRecordSchema = resourceBaseSchema.extend({
 // ──────────────────────────────────────────────────────────────────────
 // Discriminated union: Resource
 // ──────────────────────────────────────────────────────────────────────
-export const resourceSchema = z.discriminatedUnion("kind", [
+export const resourceSchema = z.discriminatedUnion('kind', [
     projectRecordSchema,
     resourceRecordSchema,
     entityRecordSchema,
@@ -472,7 +482,7 @@ export const githubIntegrationSchema = z.union([
  * callers (`grove sync`, CI workflows) can gate each feature.
  */
 export function normalizeGithubIntegration(value) {
-    if (typeof value === "boolean") {
+    if (typeof value === 'boolean') {
         return { metadata: value, contributors: value, health: value };
     }
     return {
@@ -489,23 +499,23 @@ export const themeSchema = z.object({
      */
     primaryColor: z
         .string()
-        .regex(/^#[0-9a-fA-F]{3,8}$/, "theme.primaryColor must be a hex color such as #4f46e5")
+        .regex(/^#[0-9a-fA-F]{3,8}$/, 'theme.primaryColor must be a hex color such as #4f46e5')
         .optional(),
-    radius: z.enum(["none", "soft", "round"]).default("soft"),
-    density: z.enum(["compact", "comfortable", "spacious"]).default("comfortable"),
-    containerWidth: z.string().default("72rem"),
+    radius: z.enum(['none', 'soft', 'round']).default('soft'),
+    density: z.enum(['compact', 'comfortable', 'spacious']).default('comfortable'),
+    containerWidth: z.string().default('72rem'),
 });
 // ──────────────────────────────────────────────────────────────────────
 // Audit manifest (consumed by `grove audit`)
 // ──────────────────────────────────────────────────────────────────────
 const auditPageTypeSchema = z.enum([
-    "home",
-    "directory",
-    "collection",
-    "record",
-    "content",
-    "empty",
-    "404",
+    'home',
+    'directory',
+    'collection',
+    'record',
+    'content',
+    'empty',
+    '404',
 ]);
 const auditPageManifestEntrySchema = z.object({
     path: z.string().min(1),
@@ -542,10 +552,10 @@ export const readmeConfigSchema = z.object({
     showBrowseLink: z.boolean().default(true),
 });
 export const groveConfigSchema = z.object({
-    blueprint: blueprintSchema.default("project-directory"),
+    blueprint: blueprintSchema.default('project-directory'),
     site: z.object({
         name: z.string().min(1),
-        tagline: z.string().default("A growing community knowledge site."),
+        tagline: z.string().default('A growing community knowledge site.'),
         description: z.string().optional(),
         url: z.string().url().optional(),
         repoUrl: z.string().url().optional(),
@@ -565,7 +575,7 @@ export const groveConfigSchema = z.object({
          * BCP-47 language tag for the published site. Drives `<html lang>`,
          * `og:locale`, and JSON-LD `inLanguage`.
          */
-        locale: z.string().default("en"),
+        locale: z.string().default('en'),
         /**
          * Twitter/X handle for the site (e.g. `@grove`). Emitted as
          * `twitter:site` on every page when set.
@@ -576,7 +586,7 @@ export const groveConfigSchema = z.object({
         .object({
         googleAnalyticsId: z
             .string()
-            .regex(/^G-[A-Z0-9]+$/, "Expected a GA4 measurement ID such as G-XXXXXX")
+            .regex(/^G-[A-Z0-9]+$/, 'Expected a GA4 measurement ID such as G-XXXXXX')
             .optional(),
     })
         .default({}),
@@ -622,7 +632,7 @@ export const groveConfigSchema = z.object({
         facets: z
             .array(z.enum(FACET_IDS))
             .refine((facets) => new Set(facets).size === facets.length, {
-            message: "browse.facets contains duplicate entries",
+            message: 'browse.facets contains duplicate entries',
         })
             .default([...DEFAULT_FACETS]),
     })
@@ -638,8 +648,8 @@ export const groveConfigSchema = z.object({
         .unknown()
         .optional()
         .refine((value) => value === undefined, {
-        message: "`facets` moved to `browse.facets` in grove.config.ts. " +
-            `Supported ids: ${FACET_IDS.join(", ")} (canonical spellings only).`,
+        message: '`facets` moved to `browse.facets` in grove.config.ts. ' +
+            `Supported ids: ${FACET_IDS.join(', ')} (canonical spellings only).`,
     }),
     integrations: z
         .object({
@@ -678,30 +688,30 @@ export const groveConfigSchema = z.object({
     readme: readmeConfigSchema.optional(),
     paths: z
         .object({
-        dataDir: z.string().default("data"),
-        contentDir: z.string().default("content"),
-        recordsDir: z.string().default("data/records"),
-        pagesDir: z.string().default("content/pages"),
-        bodiesDir: z.string().default("content/records"),
-        publicDir: z.string().default("public"),
-        taxonomyDir: z.string().default("data/taxonomy"),
-        generatedDir: z.string().default("data/generated"),
-        health: z.string().default("data/health.yml"),
-        decisions: z.string().default("data/decisions.yml"),
-        overrides: z.string().default("data/overrides.yml"),
+        dataDir: z.string().default('data'),
+        contentDir: z.string().default('content'),
+        recordsDir: z.string().default('data/records'),
+        pagesDir: z.string().default('content/pages'),
+        bodiesDir: z.string().default('content/records'),
+        publicDir: z.string().default('public'),
+        taxonomyDir: z.string().default('data/taxonomy'),
+        generatedDir: z.string().default('data/generated'),
+        health: z.string().default('data/health.yml'),
+        decisions: z.string().default('data/decisions.yml'),
+        overrides: z.string().default('data/overrides.yml'),
     })
         .default({
-        dataDir: "data",
-        contentDir: "content",
-        recordsDir: "data/records",
-        pagesDir: "content/pages",
-        bodiesDir: "content/records",
-        publicDir: "public",
-        taxonomyDir: "data/taxonomy",
-        generatedDir: "data/generated",
-        health: "data/health.yml",
-        decisions: "data/decisions.yml",
-        overrides: "data/overrides.yml",
+        dataDir: 'data',
+        contentDir: 'content',
+        recordsDir: 'data/records',
+        pagesDir: 'content/pages',
+        bodiesDir: 'content/records',
+        publicDir: 'public',
+        taxonomyDir: 'data/taxonomy',
+        generatedDir: 'data/generated',
+        health: 'data/health.yml',
+        decisions: 'data/decisions.yml',
+        overrides: 'data/overrides.yml',
     }),
 });
 // ──────────────────────────────────────────────────────────────────────
@@ -725,8 +735,8 @@ export function parseRecordYaml(text, fileSlug) {
     // record file cannot smuggle `!!binary` / `!!js/function` / etc.
     // into host objects. The default schema would interpret them.
     // (Implementation-checklist.md #27.)
-    const raw = parse(text, { schema: "core" }) ?? {};
-    if (typeof raw !== "object" || Array.isArray(raw)) {
+    const raw = parse(text, { schema: 'core' }) ?? {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`${fileSlug}: record file must contain a YAML mapping`);
     }
     return raw;
@@ -735,7 +745,7 @@ export function stringifyRecordYaml(record) {
     return stringify(record, {
         lineWidth: 100,
         singleQuote: false,
-        defaultStringType: "PLAIN",
+        defaultStringType: 'PLAIN',
     });
 }
 export function getOwnerRepoFromUrl(repoUrl) {
@@ -748,16 +758,16 @@ export function getOwnerRepoFromUrl(repoUrl) {
     const repo = m[2];
     if (!owner || !repo)
         return null;
-    return { owner, repo: repo.replace(/\.git$/, "") };
+    return { owner, repo: repo.replace(/\.git$/, '') };
 }
 export function isIndexProject(r) {
-    return r.kind === "project";
+    return r.kind === 'project';
 }
 export function isIndexResource(r) {
-    return r.kind === "resource";
+    return r.kind === 'resource';
 }
 export function isIndexEntity(r) {
-    return r.kind === "entity";
+    return r.kind === 'entity';
 }
 /**
  * Project a Resource to a stable, search-index-friendly summary
@@ -775,21 +785,22 @@ export function toIndexRecord(record) {
     const base = {
         slug: record.slug,
         kind: record.kind,
+        addedAt: record.addedAt,
         category: record.category,
         tags: record.tags ?? [],
         links: record.links,
         description: record.description,
         content: record.content,
         curation: record.curation,
-        licenses: record.kind === "project" ? record.licenses ?? [] : [],
+        licenses: record.kind === 'project' ? (record.licenses ?? []) : [],
         summary: record.summary,
         sourceDescription: record.sourceDescription,
     };
-    if (record.kind === "project") {
+    if (record.kind === 'project') {
         const r = record;
         return {
             ...base,
-            kind: "project",
+            kind: 'project',
             name: r.name,
             stack: r.stack,
             stacks: r.stacks ?? [],
@@ -810,10 +821,11 @@ export function toIndexRecord(record) {
             // from signals) or the curation override (`decisions.yml`).
             // The generate step folds the latter in before serialising,
             // so this is a best-effort projection of the current state.
-            visibility: r.health?.visibility ?? "keep",
+            visibility: r.health?.visibility ?? 'keep',
             github: r.github?.repository
                 ? {
                     fullName: r.github.repository.full_name,
+                    createdAt: r.github.repository.created_at ?? null,
                     stars: r.github.repository.stargazers_count ?? 0,
                     forks: r.github.repository.forks_count ?? 0,
                     openIssues: r.github.repository.open_issues_count ?? 0,
@@ -826,11 +838,11 @@ export function toIndexRecord(record) {
                 : undefined,
         };
     }
-    if (record.kind === "resource") {
+    if (record.kind === 'resource') {
         const r = record;
         return {
             ...base,
-            kind: "resource",
+            kind: 'resource',
             title: r.title,
             type: r.type,
             topic: r.topic,
@@ -848,7 +860,7 @@ export function toIndexRecord(record) {
     const e = record;
     return {
         ...base,
-        kind: "entity",
+        kind: 'entity',
         name: e.name,
         type: e.type,
         founded: e.founded,