@hagicode/hagilight-core 0.1.0

package/dist/rss-footer-context.js

@@ -0,0 +1,54 @@
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeLanguageTag(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    const input = value.trim().replaceAll('_', '-');
+    const alias = input.toLowerCase();
+    if (['zh', 'zh-cn', 'zh-hans', 'root'].includes(alias))
+        return 'zh-CN';
+    if (['zh-hant', 'zh-tw', 'zh-hk'].includes(alias))
+        return 'zh-Hant';
+    try {
+        return Intl.getCanonicalLocales(input)[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+function isFooterContext(value) {
+    return isRecord(value)
+        && typeof value.defaultFeedUrl === 'string'
+        && value.defaultFeedUrl !== ''
+        && isRecord(value.localeFeedUrls)
+        && Array.isArray(value.locales)
+        && value.locales.every((entry) => isRecord(entry)
+            && typeof entry.lang === 'string'
+            && typeof entry.filename === 'string');
+}
+/**
+ * Merge generated `hagilightRss()` feed URLs from request locals into Footer
+ * link options. Explicit `rssFeedUrl`/`rssLocaleFeedUrl` values win.
+ */
+export function resolveRssFooterLinks(locals, locale, links = {}) {
+    if (!isRecord(locals) || !Object.hasOwn(locals, 'hagilightRss'))
+        return links;
+    const rss = locals.hagilightRss;
+    if (!isFooterContext(rss)) {
+        throw new TypeError('Hagilight RSS Footer context is malformed.');
+    }
+    const normalizedLocale = normalizeLanguageTag(locale);
+    const configuredLocale = rss.locales.find((entry) => entry.filename !== 'en' && normalizeLanguageTag(entry.lang) === normalizedLocale);
+    const localeFeedUrl = configuredLocale ? rss.localeFeedUrls[configuredLocale.lang] : undefined;
+    if (configuredLocale && (typeof localeFeedUrl !== 'string' || !localeFeedUrl)) {
+        throw new TypeError(`Hagilight RSS Footer context has no URL for "${configuredLocale.lang}".`);
+    }
+    return {
+        ...links,
+        rssFeedUrl: links.rssFeedUrl ?? rss.defaultFeedUrl,
+        ...(typeof localeFeedUrl === 'string' && localeFeedUrl
+            ? { rssLocaleFeedUrl: links.rssLocaleFeedUrl ?? localeFeedUrl }
+            : {}),
+    };
+}

package/dist/rss-ownership.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Coordinates which Hagilight integration owns the generated RSS routes when the
+ * plain-Astro and Starlight packages are both registered in one Astro project.
+ * The registry lives on `globalThis` so that separately installed copies of
+ * this module still observe each other.
+ */
+export type RssOwnerPackage = 'astro' | 'starlight';
+export interface RssOwnerClaim {
+    readonly package: RssOwnerPackage;
+    readonly enabled: boolean;
+}
+/** Property key an integration object uses to advertise its RSS ownership claim. */
+export declare const RSS_OWNER: unique symbol;
+/**
+ * Record a Starlight RSS claim as soon as the Starlight plugin is created, so a
+ * plain-Astro RSS integration earlier in the integration list can defer to it.
+ * Returns a callback that withdraws the claim.
+ */
+export declare function registerStarlightRssOwner(enabled: boolean): () => void;
+/**
+ * Decide whether the plain-Astro RSS integration should generate routes.
+ * Consumes pending Starlight claims. Returns `'starlight'` when an enabled
+ * Starlight RSS integration owns the routes, otherwise `'astro'`.
+ */
+export declare function resolvePlainAstroRssOwner(integrations?: readonly unknown[]): RssOwnerPackage;

package/dist/rss-ownership.js

@@ -0,0 +1,65 @@
+/**
+ * Coordinates which Hagilight integration owns the generated RSS routes when the
+ * plain-Astro and Starlight packages are both registered in one Astro project.
+ * The registry lives on `globalThis` so that separately installed copies of
+ * this module still observe each other.
+ */
+/** Property key an integration object uses to advertise its RSS ownership claim. */
+export const RSS_OWNER = Symbol.for('@hagicode/hagilight-core/rss-owner');
+const RSS_OWNER_REGISTRY = Symbol.for('@hagicode/hagilight-core/rss-owner-registry');
+function registry() {
+    const host = globalThis;
+    host[RSS_OWNER_REGISTRY] ??= new Map();
+    return host[RSS_OWNER_REGISTRY];
+}
+/**
+ * Record a Starlight RSS claim as soon as the Starlight plugin is created, so a
+ * plain-Astro RSS integration earlier in the integration list can defer to it.
+ * Returns a callback that withdraws the claim.
+ */
+export function registerStarlightRssOwner(enabled) {
+    if (typeof enabled !== 'boolean') {
+        throw new TypeError('Hagilight RSS owner enabled flag must be a boolean.');
+    }
+    const token = Symbol('starlight-rss-owner');
+    const owners = registry();
+    owners.set(token, { package: 'starlight', enabled });
+    return () => {
+        owners.delete(token);
+    };
+}
+function isOwnerClaim(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const claim = value;
+    return (claim.package === 'astro' || claim.package === 'starlight') && typeof claim.enabled === 'boolean';
+}
+function claimOf(integration) {
+    if (!integration || typeof integration !== 'object')
+        return undefined;
+    const claim = integration[RSS_OWNER];
+    return isOwnerClaim(claim) ? claim : undefined;
+}
+/**
+ * Decide whether the plain-Astro RSS integration should generate routes.
+ * Consumes pending Starlight claims. Returns `'starlight'` when an enabled
+ * Starlight RSS integration owns the routes, otherwise `'astro'`.
+ */
+export function resolvePlainAstroRssOwner(integrations = []) {
+    const owners = registry();
+    const registered = [...owners.values()];
+    const starlightOwners = registered.length > 0
+        ? registered
+        : integrations.map(claimOf).filter((claim) => claim?.package === 'starlight');
+    owners.clear();
+    const active = starlightOwners.filter((owner) => owner.enabled);
+    if (active.length > 1) {
+        throw new Error('Hagilight RSS cannot determine a sole route owner because multiple Starlight RSS integrations are enabled.');
+    }
+    if (active.length === 1)
+        return 'starlight';
+    if (starlightOwners.length > 0) {
+        throw new Error('Hagilight RSS cannot establish route ownership: Starlight RSS is explicitly disabled while hagilightRss() requests feed generation. Enable Starlight RSS or remove hagilightRss().');
+    }
+    return 'astro';
+}

package/dist/rss.d.ts

@@ -0,0 +1,34 @@
+export type RssPublicationDate = Date | string | number | null;
+export interface RssFeedItem {
+    title: string;
+    link: string;
+    description?: string;
+    date?: RssPublicationDate;
+    pubDate?: RssPublicationDate;
+}
+export interface RssFeedOptions {
+    site: string | URL;
+    baseUrl?: string | URL;
+    language?: string;
+    title: string;
+    description: string;
+    items: readonly RssFeedItem[];
+}
+export type RssLocaleConfig = string | {
+    lang?: string;
+    label?: string;
+};
+export type RssLocalesInput = Readonly<Record<string, RssLocaleConfig | undefined>>;
+export interface RssLocale {
+    /** Starlight-style locale route key, `root` for the default locale. */
+    route: string;
+    /** Canonical BCP 47 language tag. */
+    lang: string;
+    /** Feed filename segment: `en` for English, otherwise the canonical language tag. */
+    filename: string;
+}
+export interface ResolveRssLocalesOptions {
+    requireNonEmpty?: boolean;
+}
+export declare function resolveRssLocales(locales?: RssLocalesInput, { requireNonEmpty }?: ResolveRssLocalesOptions): RssLocale[];
+export declare function generateRssFeed(options: RssFeedOptions): Promise<Response>;

package/dist/rss.js

@@ -0,0 +1,145 @@
+import rss from '@astrojs/rss';
+const LANGUAGE_TAG_PATTERN = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function resolveRssLocales(locales, { requireNonEmpty = false } = {}) {
+    if (locales !== undefined && !isRecord(locales)) {
+        throw new TypeError('Hagilight RSS locales must be an object.');
+    }
+    if (requireNonEmpty && (locales === undefined || Object.keys(locales).length === 0)) {
+        throw new TypeError('Hagilight RSS locales must contain at least one locale.');
+    }
+    const configuredLocales = locales === undefined
+        ? [['root', { lang: 'en' }]]
+        : Object.entries(locales);
+    if (configuredLocales.length === 0)
+        configuredLocales.push(['root', { lang: 'en' }]);
+    const usedFilenames = new Set();
+    return configuredLocales.map(([route, config]) => {
+        const lang = typeof config === 'string' ? config : config?.lang ?? (route === 'root' ? undefined : route);
+        if (typeof lang !== 'string' || !LANGUAGE_TAG_PATTERN.test(lang)) {
+            throw new TypeError(`Hagilight RSS locale "${route}" must have a valid language tag.`);
+        }
+        let normalizedLang;
+        try {
+            [normalizedLang] = Intl.getCanonicalLocales(lang);
+        }
+        catch {
+            throw new TypeError(`Hagilight RSS locale "${route}" has an invalid language tag "${lang}".`);
+        }
+        const filename = /^en(?:-us)?$/iu.test(normalizedLang) ? 'en' : normalizedLang;
+        const collisionKey = filename.toLowerCase();
+        if (usedFilenames.has(collisionKey)) {
+            throw new Error(`Hagilight RSS locales collide on the "${filename}" feed filename.`);
+        }
+        usedFilenames.add(collisionKey);
+        return { route, lang: normalizedLang, filename };
+    });
+}
+function resolveSite(value) {
+    try {
+        const site = new URL(value);
+        if (!['http:', 'https:'].includes(site.protocol) || site.username || site.password) {
+            throw new Error();
+        }
+        return site;
+    }
+    catch {
+        throw new TypeError('Hagilight RSS requires an absolute Astro site URL; configure `site` in astro.config.mjs.');
+    }
+}
+function resolveLanguage(value) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError('Hagilight RSS language must be a valid language tag.');
+    }
+    try {
+        return Intl.getCanonicalLocales(value)[0];
+    }
+    catch {
+        throw new TypeError(`Hagilight RSS language "${value}" must be a valid language tag.`);
+    }
+}
+function resolveBaseUrl(site, baseUrl = '/') {
+    let base;
+    try {
+        base = new URL(baseUrl, site);
+    }
+    catch {
+        throw new TypeError('Hagilight RSS base URL must be a valid path or absolute URL on the configured site.');
+    }
+    if (base.origin !== site.origin) {
+        throw new TypeError('Hagilight RSS base URL must use the configured Astro site origin.');
+    }
+    base.pathname = `${base.pathname.replace(/\/+$/u, '')}/`;
+    base.search = '';
+    base.hash = '';
+    return base;
+}
+function resolveItemUrl(value, base) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError('Hagilight RSS items require a non-empty link.');
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        url = new URL(value.replace(/^\/+/u, ''), base);
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) {
+        throw new TypeError(`Hagilight RSS item link "${value}" must resolve to an absolute HTTP(S) URL.`);
+    }
+    return url.href;
+}
+function resolvePublicationDate(item, index) {
+    const value = item.pubDate ?? item.date;
+    if (value === undefined || value === null)
+        return undefined;
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new TypeError(`Hagilight RSS item ${index + 1} has an invalid publication date.`);
+    }
+    return date;
+}
+export function generateRssFeed(options) {
+    const { site: siteInput, baseUrl = '/', language = 'en', title, description, items, } = (options ?? {});
+    const site = resolveSite(siteInput);
+    const base = resolveBaseUrl(site, baseUrl);
+    const lang = resolveLanguage(language);
+    if (typeof title !== 'string' || !title.trim()) {
+        throw new TypeError('Hagilight RSS requires a non-empty feed title.');
+    }
+    if (typeof description !== 'string' || !description.trim()) {
+        throw new TypeError('Hagilight RSS requires a non-empty feed description.');
+    }
+    if (!Array.isArray(items)) {
+        throw new TypeError('Hagilight RSS items must be an array supplied by the consumer.');
+    }
+    const feedItems = items.map((item, index) => {
+        if (!isRecord(item)) {
+            throw new TypeError(`Hagilight RSS item ${index + 1} must be an object.`);
+        }
+        const entry = item;
+        if (typeof entry.title !== 'string' || !entry.title.trim()) {
+            throw new TypeError(`Hagilight RSS item ${index + 1} requires a non-empty title.`);
+        }
+        if (entry.description !== undefined && typeof entry.description !== 'string') {
+            throw new TypeError(`Hagilight RSS item ${index + 1} description must be a string.`);
+        }
+        const pubDate = resolvePublicationDate(entry, index);
+        return {
+            title: entry.title,
+            ...(entry.description === undefined ? {} : { description: entry.description }),
+            link: resolveItemUrl(entry.link, base),
+            ...(pubDate === undefined ? {} : { pubDate }),
+        };
+    });
+    return rss({
+        title,
+        description,
+        site: base,
+        customData: `<language>${lang}</language>`,
+        items: feedItems,
+    });
+}

package/dist/seo-schema.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'astro/zod';
+/** Frontmatter schema for the optional `seo` object consumed by Hagilight SEO helpers. */
+export declare const seoSchema: z.ZodObject<{
+    seo: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+        author: z.ZodOptional<z.ZodString>;
+        publishedDate: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SeoFrontmatter = z.infer<typeof seoSchema>;

package/dist/seo-schema.js

@@ -0,0 +1,20 @@
+import { z } from 'astro/zod';
+import { isValidSeoImageReference } from './seo.js';
+const optionalText = z.string().trim().min(1).optional();
+const optionalImage = z.string()
+    .trim()
+    .min(1)
+    .refine(isValidSeoImageReference, {
+    message: 'Use an absolute HTTP(S) URL or a site-root path beginning with "/".',
+})
+    .optional();
+/** Frontmatter schema for the optional `seo` object consumed by Hagilight SEO helpers. */
+export const seoSchema = z.object({
+    seo: z.object({
+        title: optionalText,
+        description: optionalText,
+        image: optionalImage,
+        author: optionalText,
+        publishedDate: z.coerce.date().optional(),
+    }).optional(),
+});

package/dist/seo.d.ts

@@ -0,0 +1,78 @@
+import type { HeadEntry } from './head.js';
+export type { HeadAttributeValue, HeadEntry } from './head.js';
+export interface SeoFields {
+    title?: string;
+    description?: string;
+    image?: string;
+}
+export interface PageSeo extends SeoFields {
+    author?: string;
+    publishedDate?: Date | string | number;
+}
+export interface SeoMetadata {
+    title?: string;
+    description?: string;
+    image?: string;
+}
+export interface SeoSiteOptions {
+    site?: string | URL;
+    basePath?: string;
+}
+export interface ResolveSeoMetadataOptions extends SeoSiteOptions {
+    entry?: {
+        data?: {
+            title?: string;
+            description?: string;
+        };
+    };
+    head?: readonly HeadEntry[];
+    pageSeo?: SeoFields;
+    siteSeo?: SeoFields;
+    explicitHead?: readonly (readonly HeadEntry[] | undefined)[];
+    body?: string;
+}
+export interface ComposeCanonicalSeoHeadOptions {
+    canonicalUrl?: string | URL;
+    explicitHead?: readonly (readonly HeadEntry[] | undefined)[];
+}
+export interface ArticleStructuredDataInput {
+    url: string | URL;
+    title: string;
+    description?: string;
+    author?: string;
+    publishedDate?: Date | string | number;
+    modifiedDate?: Date | string | number;
+}
+export interface BreadcrumbItem {
+    name: string;
+    url: string | URL;
+}
+export interface OrganizationStructuredDataInput {
+    name: string;
+    url: string | URL;
+    logo?: string | URL;
+    alternateName?: string;
+}
+export type StructuredData = Record<string, unknown>;
+export declare function resolveAbsoluteHttpUrl(value: unknown, label?: string): URL;
+export declare function resolveCanonicalUrl(pageUrl: string | URL, { site }?: {
+    site?: string | URL;
+}): string;
+export declare function extractSeoDescription(body: unknown): string | undefined;
+export declare function resolveSeoMetadata({ entry, head, pageSeo, siteSeo, site, basePath, explicitHead, body, }?: ResolveSeoMetadataOptions): SeoMetadata;
+export declare function isValidSeoImageReference(value: unknown): value is string;
+export declare function resolveSeoImageUrl(value: string, { site, basePath }?: SeoSiteOptions): string;
+export declare function composeSeoHead(head: readonly HeadEntry[], metadata: SeoMetadata, explicitHead?: readonly (readonly HeadEntry[] | undefined)[]): HeadEntry[];
+/**
+ * Compose Open Graph/Twitter metadata plus exactly one canonical link for a
+ * plain Astro page. An explicit canonical link wins over existing ones, which
+ * win over `canonicalUrl`.
+ */
+export declare function composeCanonicalSeoHead(head: readonly HeadEntry[], metadata: SeoMetadata & {
+    site?: string | URL;
+}, { canonicalUrl, explicitHead }?: ComposeCanonicalSeoHeadOptions): HeadEntry[];
+export declare function buildArticleStructuredData({ url, title, description, author, publishedDate, modifiedDate, }: ArticleStructuredDataInput): StructuredData;
+export declare function buildBreadcrumbStructuredData(items?: readonly BreadcrumbItem[]): StructuredData;
+export declare function buildOrganizationStructuredData({ name, url, logo, alternateName, }: OrganizationStructuredDataInput): StructuredData;
+/** Serialize JSON-LD safely for inline `<script type="application/ld+json">`. */
+export declare function serializeJsonLd(value: unknown): string;