@evcraddock/slug-cli 0.9.0 → 0.10.0

package/README.md

@@ -55,7 +55,7 @@ Use `slug --site <name> post list`, `slug --site <name> post show <slug>`, `slug
 
 ## Markdown imports
 
-Import one Markdown file with `slug --site <name> post import <file.md>`. Imports require YAML frontmatter delimited by `---` with `slug` and `type`; articles also require `title`. Supported frontmatter fields are `title`, `slug`, `type`, `excerpt`, `date`, `publishedAt`, `tags`, `url`, and `banner`. `date` is used when `publishedAt` is absent. Dates must be ISO dates or datetimes. Tags support either a YAML list or a flow-style list such as `[writing, notes]`.
+Import one Markdown file with `slug --site <name> post import <file.md>`. Imports require YAML frontmatter delimited by `---` with `slug` and `type`; articles also require `title`. Supported frontmatter fields are `title`, `slug`, `type`, `excerpt`, `date`, `publishedAt`, `tags`, `url`, `banner`, `banner_url`, `source`, and `authors`. `source` and `authors` are supported only for links. `date` is used when `publishedAt` is absent. Dates must be ISO dates or datetimes. Tags support either a YAML list or a flow-style list such as `[writing, notes]`.
 
 ```markdown
 ---
@@ -73,7 +73,51 @@ banner: images/hero.png
 The imported body.
 ```
 
-A relative `banner` path is resolved from the Markdown file, uploaded through the Slugkit media API under `posts/<slug>/banner.<extension>`, and inserted as the first Markdown image in the post body so standard Slugkit article previews render it. The command looks up the post by slug: it creates a missing post and updates an existing one, replacing the imported metadata, body, tags, and publication date. Re-importing a banner uploads the current file again to refresh the deterministic media object key.
+A relative article `banner` path is resolved from the Markdown file, uploaded through the Slugkit media API under `posts/<slug>/banner.<extension>`, and saved as the post's explicit `bannerUrl` without modifying Markdown content. Link imports map `banner_url` directly to `bannerUrl`. The command looks up the post by slug: it creates a missing post and updates an existing one, replacing the imported metadata, body, tags, and publication date. Re-importing a banner uploads the current file again to refresh the deterministic media object key.
+
+Link imports may include one source and one or more authors:
+
+```markdown
+---
+type: link
+slug: how-to-stop-being-boring
+title: How to stop being boring
+url: https://www.joanwestenberg.com/how-to-stop-being-boring/
+banner_url: https://example.com/banner.jpg
+excerpt: A short description.
+tags: [adulting]
+publishedAt: 2026-02-07
+source:
+  name: Joan Westenberg
+  url: https://www.joanwestenberg.com
+authors:
+  - name: Joan Westenberg
+    url: https://www.joanwestenberg.com/about
+---
+
+Optional commentary about the link.
+```
+
+Link files may omit either or both relationship fields:
+
+```markdown
+---
+type: link
+slug: discovered-link
+title: Discovered link
+url: https://publication.example/posts/discovered-link
+---
+
+Optional commentary.
+```
+
+Explicit `source` and `authors` values override discovery independently. For each missing field, the importer fetches the link page without sending Slugkit API credentials. Source discovery prefers JSON-LD publisher data, then standard site-name metadata. Author discovery uses JSON-LD author data and standard author metadata. If source metadata is unavailable, the normalized destination hostname and origin become the source. Missing or malformed author metadata does not block the import; the link is imported without author contacts.
+
+Remote discovery accepts HTML responses, uses a five-second timeout, and reads at most 1 MiB. Network errors, non-HTML responses, malformed metadata, timeouts, and oversized responses use the hostname source fallback. Duplicate discovered authors are collapsed by canonical URL or normalized name, preferring a direct author URL over fragment identifiers.
+
+When a relationship URL is available, the importer matches existing sources and contacts by a canonical URL with fragments and trailing slashes removed. Without a URL, it matches a unique name after normalizing case and whitespace. Ambiguous matches fail instead of silently selecting a record. Missing authors are created as contacts, then associated with the resolved or newly created source and credited on the post. Existing source contacts and post credits are preserved. Re-importing the same file reuses records and relationships without duplicates.
+
+All explicit source and author metadata is validated before API mutations. For relationship imports, missing contacts are created first, the source is created or updated second, and the post is created or updated last. The API does not provide a bulk transaction, so a later failure stops the import but records created by earlier successful requests remain; relationship mutation errors identify the failed frontmatter path.
 
 ## Source imports
 

package/dist/commands.js

@@ -7,6 +7,7 @@ import { SLUGKIT_API_MAJOR_VERSION, SLUGKIT_API_NAME, compareSlugkitApiVersions,
 import { isValidSiteName, readConfig, removeConfigSite, setConfigSiteApiBaseUrl, setConfigSiteApiKey, toDisplayConfig, writeConfig, } from "./config.js";
 import { CliError, createInvalidUsageError, ExitCode } from "./errors.js";
 import { SlugHttpClient } from "./http.js";
+import { discoverLinkRelationships } from "./link-metadata.js";
 import { writeJson } from "./output.js";
 const HELP_TEXT = `slug - manage Slugkit sites
 
@@ -21,8 +22,8 @@ Usage:
   slug [--config <file>] --site <name> post list [--type article|link|note] [--status draft|published|all] [--tag <slug>] [--json]
   slug [--config <file>] post show <slug> [--json]
   slug [--config <file>] post import <file.md> [--json]
-  slug [--config <file>] post create --type article|link|note --slug <slug> --content <text> [--title <text>] [--url <url>] [--excerpt <text>] [--published-at <datetime>] [--tag <slug>]... [--source-id <id>] [--credit-contact-id <id>]... [--json]
-  slug [--config <file>] post edit <slug> [--slug <new-slug>] [--title <text>] [--content <text>] [--url <url>] [--excerpt <text>] [--published-at <datetime>] [--tag <slug>]... [--source-id <id>] [--credit-contact-id <id>]... [--json]
+  slug [--config <file>] post create --type article|link|note --slug <slug> --content <text> [--title <text>] [--url <url>] [--excerpt <text>] [--banner-url <url>] [--published-at <datetime>] [--tag <slug>]... [--source-id <id>] [--credit-contact-id <id>]... [--json]
+  slug [--config <file>] post edit <slug> [--slug <new-slug>] [--title <text>] [--content <text>] [--url <url>] [--excerpt <text>] [--banner-url <url>] [--published-at <datetime>] [--tag <slug>]... [--source-id <id>] [--credit-contact-id <id>]... [--json]
   slug [--config <file>] post delete <slug> [--json]
   slug [--config <file>] post publish <slug> [--published-at <datetime>] [--json]
   slug [--config <file>] post unpublish <slug> [--json]
@@ -924,24 +925,46 @@ async function runPostsCommand(context, args) {
 }
 async function runPostsImportCommand(context, args) {
     const { filePath, json } = readPostImportArgs(args);
-    const post = await readMarkdownPostImport(filePath);
+    let post = await readMarkdownPostImport(filePath);
+    if (post.type === "link" && post.url !== undefined) {
+        const discovered = await discoverLinkRelationships({
+            url: post.url,
+            source: post.source === undefined,
+            authors: post.authors === undefined,
+            fetchImpl: context.fetchImpl,
+        });
+        post = {
+            ...post,
+            ...(post.source !== undefined || discovered.source === undefined
+                ? {}
+                : { source: discovered.source }),
+            ...(post.authors !== undefined || discovered.authors === undefined
+                ? {}
+                : { authors: discovered.authors }),
+        };
+    }
     const api = await createConfiguredApiContext(context);
-    const bannerUrl = post.bannerPath === undefined
+    const uploadedBannerUrl = post.bannerPath === undefined
         ? undefined
         : await uploadPostImportBanner(api, post, post.bannerPath);
-    const content = bannerUrl === undefined ? post.content : createBannerContent(post, bannerUrl);
+    const bannerUrl = uploadedBannerUrl ?? post.bannerUrl;
+    writeMutationTarget(context.writer, api.apiBaseUrl, json);
+    const existing = await findImportedPost(api.client, post.slug);
+    const relationships = await resolveMarkdownImportRelationships(api.client, post);
+    const creditContactIds = mergeIds(existing?.creditContactIds ?? [], relationships.authorContactIds);
     const body = {
         type: post.type,
         slug: post.slug,
-        content,
+        content: post.content,
         ...(post.title === undefined ? {} : { title: post.title }),
         ...(post.excerpt === undefined ? {} : { excerpt: post.excerpt }),
         ...(post.url === undefined ? {} : { url: post.url }),
+        ...(bannerUrl === undefined ? {} : { bannerUrl }),
+        ...(relationships.sourceId === undefined ? {} : { sourceId: relationships.sourceId }),
+        ...(post.authors === undefined ? {} : { creditContactIds }),
         ...(post.tags === undefined ? {} : { tagSlugs: post.tags }),
         ...(post.publishedAt === undefined ? {} : { publishedAt: post.publishedAt }),
     };
-    writeMutationTarget(context.writer, api.apiBaseUrl, json);
-    const existing = await findImportedPost(api.client, post.slug);
     const response = existing === undefined
         ? await api.client.requestJson({ method: "POST", path: "/posts", body })
         : await api.client.requestJson({
@@ -977,21 +1000,32 @@ async function readMarkdownPostImport(filePath) {
     if (match === null) {
         throw createInvalidUsageError("Markdown import requires YAML frontmatter delimited by ---");
     }
-    const frontmatter = parseMarkdownFrontmatter(match[1]);
-    const slug = readRequiredFrontmatterString(frontmatter, "slug");
-    const type = readRequiredFrontmatterString(frontmatter, "type");
+    const frontmatter = parseMarkdownPostFrontmatter(match[1]);
+    const slug = readMarkdownRequiredString(frontmatter, "slug", "frontmatter");
+    const type = readMarkdownRequiredString(frontmatter, "type", "frontmatter");
     if (type !== "article" && type !== "link" && type !== "note") {
-        throw createInvalidUsageError("Frontmatter type must be article, link, or note");
+        throw createInvalidUsageError("frontmatter.type must be article, link, or note");
     }
-    const title = readOptionalFrontmatterString(frontmatter, "title");
+    const title = readMarkdownOptionalString(frontmatter, "title", "frontmatter");
     if (type === "article" && title === undefined) {
-        throw createInvalidUsageError("Article imports require frontmatter title");
-    }
-    const excerpt = readOptionalFrontmatterString(frontmatter, "excerpt");
-    const url = readOptionalFrontmatterString(frontmatter, "url");
-    const tags = readFrontmatterTags(frontmatter);
-    const publishedAt = readImportPublishedAt(frontmatter);
-    const banner = readOptionalFrontmatterString(frontmatter, "banner");
+        throw createInvalidUsageError("Article imports require frontmatter.title");
+    }
+    const source = readMarkdownRelationship(frontmatter, "source", "frontmatter");
+    const authors = readMarkdownAuthors(frontmatter);
+    if (type !== "link" && (source !== undefined || authors !== undefined)) {
+        throw createInvalidUsageError("frontmatter.source and frontmatter.authors require type: link");
+    }
+    const excerpt = readMarkdownOptionalString(frontmatter, "excerpt", "frontmatter");
+    const url = readMarkdownOptionalString(frontmatter, "url", "frontmatter");
+    if (type === "link") {
+        if (url === undefined)
+            throw createInvalidUsageError("Link imports require frontmatter.url");
+        assertSourceImportUrl(url, "frontmatter.url", ["http:", "https:"]);
+    }
+    const tags = readMarkdownTags(frontmatter);
+    const publishedAt = readMarkdownPublishedAt(frontmatter);
+    const banner = readMarkdownOptionalString(frontmatter, "banner", "frontmatter");
+    const linkBannerUrl = readMarkdownOptionalString(frontmatter, "banner_url", "frontmatter");
     return {
         slug,
         type,
@@ -1000,75 +1034,181 @@ async function readMarkdownPostImport(filePath) {
         ...(url === undefined ? {} : { url }),
         ...(tags === undefined ? {} : { tags }),
         ...(publishedAt === undefined ? {} : { publishedAt }),
-        ...(banner === undefined ? {} : { bannerPath: resolve(dirname(filePath), banner) }),
+        ...(type !== "article" || banner === undefined
+            ? {}
+            : { bannerPath: resolve(dirname(filePath), banner) }),
+        ...(type !== "link" || linkBannerUrl === undefined ? {} : { bannerUrl: linkBannerUrl }),
+        ...(source === undefined ? {} : { source }),
+        ...(authors === undefined ? {} : { authors }),
         content: markdown.slice(match[0].length),
     };
 }
-function parseMarkdownFrontmatter(value) {
-    const frontmatter = new Map();
-    const lines = value.split(/\r?\n/u);
-    for (let index = 0; index < lines.length; index += 1) {
-        const line = lines[index];
-        const match = /^([A-Za-z][A-Za-z0-9]*):(?:\s*(.*))?$/u.exec(line);
-        if (match === null || match[1] === undefined)
-            continue;
-        const key = match[1];
-        const rawValue = match[2]?.trim() ?? "";
-        if (key === "tags" && rawValue === "") {
-            const tags = [];
-            while (/^\s+-\s+/u.test(lines[index + 1] ?? "")) {
-                index += 1;
-                tags.push(parseFrontmatterScalar((lines[index] ?? "").replace(/^\s+-\s+/u, "")));
-            }
-            frontmatter.set(key, tags);
+function parseMarkdownPostFrontmatter(value) {
+    let parsed;
+    try {
+        parsed = parseYaml(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unable to parse YAML";
+        throw createInvalidUsageError(`Invalid Markdown frontmatter YAML: ${message}`);
+    }
+    if (!isRecord(parsed))
+        throw createInvalidUsageError("frontmatter must be an object");
+    return parsed;
+}
+function readMarkdownRequiredString(record, key, path) {
+    const value = readMarkdownOptionalString(record, key, path);
+    if (value === undefined) {
+        throw createInvalidUsageError(`${path}.${key} must be a non-empty string`);
+    }
+    return value;
+}
+function readMarkdownOptionalString(record, key, path) {
+    if (!(key in record))
+        return undefined;
+    const value = record[key];
+    if (typeof value !== "string") {
+        throw createInvalidUsageError(`${path}.${key} must be a string`);
+    }
+    return value.trim() === "" ? undefined : value;
+}
+function readMarkdownTags(record) {
+    if (!("tags" in record))
+        return undefined;
+    if (!Array.isArray(record.tags)) {
+        throw createInvalidUsageError("frontmatter.tags must be an array");
+    }
+    return record.tags.map((tag, index) => {
+        if (typeof tag !== "string" || tag.trim() === "") {
+            throw createInvalidUsageError(`frontmatter.tags[${index}] must be a non-empty string`);
         }
-        else {
-            frontmatter.set(key, key === "tags" ? parseFrontmatterTags(rawValue) : parseFrontmatterScalar(rawValue));
+        return tag;
+    });
+}
+function readMarkdownRelationship(record, key, path) {
+    if (!(key in record))
+        return undefined;
+    return parseMarkdownRelationship(record[key], `${path}.${key}`);
+}
+function parseMarkdownRelationship(value, path) {
+    if (!isRecord(value))
+        throw createInvalidUsageError(`${path} must be an object`);
+    for (const field of Object.keys(value)) {
+        if (field !== "name" && field !== "url") {
+            throw createInvalidUsageError(`${path}.${field} is not supported`);
         }
     }
-    return frontmatter;
+    const name = readMarkdownRequiredString(value, "name", path);
+    const url = readMarkdownOptionalString(value, "url", path);
+    if (url !== undefined)
+        assertSourceImportUrl(url, `${path}.url`, ["http:", "https:"]);
+    return { name, ...(url === undefined ? {} : { url }) };
 }
-function parseFrontmatterScalar(value) {
-    if (value.startsWith('"') && value.endsWith('"')) {
-        try {
-            const parsed = JSON.parse(value);
-            if (typeof parsed === "string")
-                return parsed;
-        }
-        catch {
-            // Report the unparsed value below so the API can validate it where applicable.
+function readMarkdownAuthors(record) {
+    if (!("authors" in record))
+        return undefined;
+    if (!Array.isArray(record.authors) || record.authors.length === 0) {
+        throw createInvalidUsageError("frontmatter.authors must be a non-empty array");
+    }
+    return record.authors.map((author, index) => parseMarkdownRelationship(author, `frontmatter.authors[${index}]`));
+}
+function readMarkdownPublishedAt(record) {
+    const publishedAt = readMarkdownOptionalString(record, "publishedAt", "frontmatter") ??
+        readMarkdownOptionalString(record, "date", "frontmatter");
+    return publishedAt === undefined ? undefined : normalizeCliPublishedAt(publishedAt);
+}
+async function resolveMarkdownImportRelationships(client, post) {
+    if (post.source === undefined && post.authors === undefined)
+        return { authorContactIds: [] };
+    const sources = post.source === undefined
+        ? []
+        : (await client.requestJson({ path: "/sources" })).data;
+    const contacts = post.authors === undefined
+        ? []
+        : (await client.requestJson({ path: "/contacts" })).data;
+    if (post.source !== undefined) {
+        findMarkdownRelationshipMatch(sources, post.source, "frontmatter.source", "sources");
+    }
+    post.authors?.forEach((author, index) => findMarkdownRelationshipMatch(contacts, author, `frontmatter.authors[${index}]`, "contacts"));
+    const authorContactIds = await resolveMarkdownAuthors(client, post.authors ?? [], contacts);
+    const sourceId = await resolveMarkdownSource(client, post.source, sources, authorContactIds);
+    return { ...(sourceId === undefined ? {} : { sourceId }), authorContactIds };
+}
+async function resolveMarkdownAuthors(client, authors, contacts) {
+    const ids = [];
+    for (const [index, author] of authors.entries()) {
+        let contact = findMarkdownRelationshipMatch(contacts, author, `frontmatter.authors[${index}]`, "contacts");
+        if (contact === undefined) {
+            const response = await requestMarkdownRelationship(client, "POST", "/contacts", { name: author.name, ...(author.url === undefined ? {} : { url: author.url }) }, `frontmatter.authors[${index}]`);
+            contact = response.data;
+            contacts.push(contact);
         }
+        ids.push(contact.id);
+    }
+    return [...new Set(ids)];
+}
+async function resolveMarkdownSource(client, input, sources, authorContactIds) {
+    if (input === undefined)
+        return undefined;
+    const existing = findMarkdownRelationshipMatch(sources, input, "frontmatter.source", "sources");
+    if (existing === undefined)
+        return createMarkdownSource(client, input, authorContactIds);
+    await addMarkdownSourceContacts(client, existing, authorContactIds);
+    return existing.id;
+}
+async function createMarkdownSource(client, input, contactIds) {
+    const response = await requestMarkdownRelationship(client, "POST", "/sources", {
+        name: input.name,
+        ...(input.url === undefined ? {} : { url: input.url }),
+        ...(contactIds.length === 0 ? {} : { contactIds }),
+    }, "frontmatter.source");
+    return response.data.id;
+}
+async function addMarkdownSourceContacts(client, source, authorContactIds) {
+    const existingIds = source.contacts?.map((contact) => contact.id) ?? [];
+    const contactIds = mergeIds(existingIds, authorContactIds);
+    if (contactIds.length === existingIds.length)
+        return;
+    await requestMarkdownRelationship(client, "PUT", `/sources/${encodeURIComponent(source.id.toString())}`, { contactIds }, "frontmatter.source.contacts");
+}
+function findMarkdownRelationshipMatch(records, input, path, label) {
+    const matches = findMarkdownRelationshipMatches(records, input);
+    if (matches.length > 1) {
+        throw createInvalidUsageError(`${path} matches multiple ${label} by ${input.url === undefined ? "name" : "URL"}`);
     }
-    if (value.startsWith("'") && value.endsWith("'")) {
-        return value.slice(1, -1).replace(/''/gu, "'");
+    return matches[0];
+}
+function findMarkdownRelationshipMatches(records, input) {
+    if (input.url === undefined) {
+        const name = normalizeImportName(input.name);
+        return records.filter((record) => normalizeImportName(record.name) === name);
     }
-    return value;
+    const url = canonicalizeImportUrl(input.url);
+    return records.filter((record) => record.url !== undefined && record.url !== null && canonicalizeImportUrl(record.url) === url);
 }
-function parseFrontmatterTags(value) {
-    const trimmed = value.trim();
-    const items = trimmed.startsWith("[") && trimmed.endsWith("]")
-        ? trimmed.slice(1, -1).split(",")
-        : trimmed.split(",");
-    return items.map((item) => parseFrontmatterScalar(item.trim())).filter((item) => item !== "");
-}
-function readRequiredFrontmatterString(frontmatter, key) {
-    const value = readOptionalFrontmatterString(frontmatter, key);
-    if (value === undefined)
-        throw createInvalidUsageError(`Markdown frontmatter requires ${key}`);
-    return value;
+function canonicalizeImportUrl(value) {
+    const url = new URL(value);
+    url.hash = "";
+    if (url.pathname !== "/")
+        url.pathname = url.pathname.replace(/\/+$/u, "");
+    return url.toString();
 }
-function readOptionalFrontmatterString(frontmatter, key) {
-    const value = frontmatter.get(key);
-    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+function normalizeImportName(value) {
+    return value.trim().replace(/\s+/gu, " ").toLocaleLowerCase("en-US");
 }
-function readFrontmatterTags(frontmatter) {
-    const value = frontmatter.get("tags");
-    return Array.isArray(value) ? value : undefined;
+function mergeIds(existing, added) {
+    return [...new Set([...existing, ...added])];
 }
-function readImportPublishedAt(frontmatter) {
-    const publishedAt = readOptionalFrontmatterString(frontmatter, "publishedAt") ??
-        readOptionalFrontmatterString(frontmatter, "date");
-    return publishedAt === undefined ? undefined : normalizeCliPublishedAt(publishedAt);
+async function requestMarkdownRelationship(client, method, path, body, importPath) {
+    try {
+        return await client.requestJson({ method, path, body });
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            throw new CliError(`Failed to import ${importPath}: ${error.message}`, error.exitCode, error.status);
+        }
+        throw error;
+    }
 }
 async function uploadPostImportBanner(api, post, bannerPath) {
     const file = await readMediaUploadFile(bannerPath);
@@ -1082,10 +1222,7 @@ async function uploadPostImportBanner(api, post, bannerPath) {
         path: "/media",
         body,
     });
-    return response.data.url;
-}
-function createBannerContent(post, bannerUrl) {
-    return `![${post.title ?? post.slug} banner](${bannerUrl})\n\n${post.content}`;
+    return new URL(response.data.url, api.apiBaseUrl).toString();
 }
 async function findImportedPost(client, slug) {
     try {
@@ -1142,6 +1279,7 @@ async function runPostsCreateCommand(context, args) {
         "title",
         "url",
         "excerpt",
+        "banner-url",
         "tag",
         "source-id",
         "credit-contact-id",
@@ -1169,6 +1307,7 @@ async function runPostsEditCommand(context, args) {
         "title",
         "url",
         "excerpt",
+        "banner-url",
         "tag",
         "source-id",
         "credit-contact-id",
@@ -1255,6 +1394,7 @@ function createPostMutationInput(options, requireCreateFields) {
     copyStringOption(options, input, "content", "content");
     copyStringOption(options, input, "url", "url");
     copyStringOption(options, input, "excerpt", "excerpt");
+    copyStringOption(options, input, "banner-url", "bannerUrl");
     copyNumberOption(options, input, "source-id", "sourceId");
     if (typeof options["published-at"] === "string") {
         input.publishedAt = normalizeCliPublishedAt(options["published-at"]);
@@ -1351,6 +1491,7 @@ function writePost(writer, post) {
     writer.stdout(`slug: ${post.slug}`);
     writer.stdout(`type: ${post.type}`);
     writer.stdout(`title: ${post.title ?? ""}`);
+    writer.stdout(`bannerUrl: ${post.bannerUrl ?? ""}`);
     writer.stdout(`publishedAt: ${post.publishedAt ?? "draft"}`);
 }
 function writePostMutationOutput(writer, response, json) {

package/dist/link-metadata.d.ts

@@ -0,0 +1,18 @@
+export interface LinkRelationshipMetadata {
+    name: string;
+    url?: string;
+}
+export interface DiscoveredLinkRelationships {
+    source?: LinkRelationshipMetadata;
+    authors?: LinkRelationshipMetadata[];
+}
+interface DiscoverLinkRelationshipsOptions {
+    url: string;
+    source: boolean;
+    authors: boolean;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+}
+export declare function discoverLinkRelationships(options: DiscoverLinkRelationshipsOptions): Promise<DiscoveredLinkRelationships>;
+export {};

package/dist/link-metadata.js

@@ -0,0 +1,234 @@
+import { load } from "cheerio";
+const defaultTimeoutMs = 5_000;
+const defaultMaxResponseBytes = 1_048_576;
+export async function discoverLinkRelationships(options) {
+    if (!options.source && !options.authors)
+        return {};
+    const fallbackSource = options.source ? createHostnameSource(options.url) : undefined;
+    const html = await fetchLinkHtml(options);
+    if (html === undefined) {
+        return fallbackSource === undefined ? {} : { source: fallbackSource };
+    }
+    const document = load(html);
+    const jsonLd = readJsonLdRecords(document("script[type='application/ld+json']")
+        .toArray()
+        .map((element) => document(element).text()));
+    const source = options.source
+        ? (readJsonLdSource(jsonLd) ?? readMetaSource(document, options.url) ?? fallbackSource)
+        : undefined;
+    const authors = options.authors
+        ? deduplicateRelationships([...readJsonLdAuthors(jsonLd), ...readMetaAuthors(document)])
+        : [];
+    return {
+        ...(source === undefined ? {} : { source }),
+        ...(authors.length === 0 ? {} : { authors }),
+    };
+}
+async function fetchLinkHtml(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    let response;
+    try {
+        response = await fetchImpl(options.url, {
+            headers: {
+                accept: "text/html,application/xhtml+xml",
+                "user-agent": "Slugkit link importer",
+            },
+            signal: AbortSignal.timeout(options.timeoutMs ?? defaultTimeoutMs),
+        });
+    }
+    catch {
+        return undefined;
+    }
+    if (!response.ok || !isHtmlResponse(response))
+        return undefined;
+    try {
+        return await readBoundedText(response, options.maxResponseBytes ?? defaultMaxResponseBytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isHtmlResponse(response) {
+    const contentType = response.headers.get("content-type");
+    return (contentType !== null &&
+        (contentType.toLowerCase().includes("text/html") ||
+            contentType.toLowerCase().includes("application/xhtml+xml")));
+}
+async function readBoundedText(response, maxBytes) {
+    const declaredLength = Number.parseInt(response.headers.get("content-length") ?? "0", 10);
+    if (declaredLength > maxBytes)
+        throw new Error("Link metadata response is too large");
+    if (response.body === null)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    while (true) {
+        const result = await reader.read();
+        if (result.done)
+            break;
+        totalBytes += result.value.byteLength;
+        if (totalBytes > maxBytes) {
+            await reader.cancel();
+            throw new Error("Link metadata response is too large");
+        }
+        chunks.push(result.value);
+    }
+    const body = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(body);
+}
+function readJsonLdRecords(values) {
+    const records = [];
+    for (const value of values) {
+        try {
+            collectJsonLdRecords(JSON.parse(value), records);
+        }
+        catch {
+            // Ignore malformed structured metadata and continue with other discovery signals.
+        }
+    }
+    return records;
+}
+function collectJsonLdRecords(value, records) {
+    if (Array.isArray(value)) {
+        value.forEach((item) => collectJsonLdRecords(item, records));
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    records.push(value);
+    if ("@graph" in value)
+        collectJsonLdRecords(value["@graph"], records);
+}
+function readJsonLdSource(records) {
+    for (const record of records) {
+        const relationships = readJsonLdRelationships(record.publisher, records);
+        if (relationships.length > 0)
+            return relationships[0];
+    }
+    return undefined;
+}
+function readJsonLdAuthors(records) {
+    return records.flatMap((record) => readJsonLdRelationships(record.author, records));
+}
+function readJsonLdRelationships(value, records, visitedIds = new Set()) {
+    if (Array.isArray(value)) {
+        return value.flatMap((item) => readJsonLdRelationships(item, records, visitedIds));
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+        if (!isHttpUrl(value))
+            return [{ name: value }];
+        return readJsonLdReference(value, records, visitedIds);
+    }
+    if (!isRecord(value))
+        return [];
+    if (typeof value.name !== "string" || value.name.trim() === "") {
+        const id = typeof value["@id"] === "string" ? value["@id"] : undefined;
+        return id === undefined ? [] : readJsonLdReference(id, records, visitedIds);
+    }
+    const url = readJsonLdUrl(value);
+    return [{ name: value.name, ...(url === undefined ? {} : { url }) }];
+}
+function readJsonLdReference(id, records, visitedIds) {
+    if (visitedIds.has(id))
+        return [];
+    const referenced = records.find((record) => record["@id"] === id);
+    if (referenced === undefined)
+        return [];
+    const visited = new Set(visitedIds);
+    visited.add(id);
+    return readJsonLdRelationships(referenced, records, visited);
+}
+function readJsonLdUrl(value) {
+    for (const candidate of [value.url, value["@id"]]) {
+        if (typeof candidate === "string" && isHttpUrl(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function readMetaSource(document, destinationUrl) {
+    const name = readFirstMeta(document, [
+        "meta[property='og:site_name']",
+        "meta[name='application-name']",
+        "meta[name='apple-mobile-web-app-title']",
+    ]);
+    return name === undefined ? undefined : { name, url: new URL(destinationUrl).origin };
+}
+function readMetaAuthors(document) {
+    return [
+        ...readMetaValues(document, "meta[name='author']"),
+        ...readMetaValues(document, "meta[property='article:author']"),
+    ]
+        .filter((value) => !isHttpUrl(value))
+        .map((name) => ({ name }));
+}
+function readFirstMeta(document, selectors) {
+    for (const selector of selectors) {
+        const value = document(selector).first().attr("content")?.trim();
+        if (value !== undefined && value !== "")
+            return value;
+    }
+    return undefined;
+}
+function readMetaValues(document, selector) {
+    return document(selector)
+        .toArray()
+        .map((element) => document(element).attr("content")?.trim() ?? "")
+        .filter((value) => value !== "");
+}
+function createHostnameSource(value) {
+    const url = new URL(value);
+    return { name: url.hostname.replace(/^www\./iu, ""), url: url.origin };
+}
+function deduplicateRelationships(relationships) {
+    const unique = [];
+    for (const relationship of relationships) {
+        const index = unique.findIndex((candidate) => relationshipsMatch(candidate, relationship));
+        if (index === -1) {
+            unique.push(relationship);
+        }
+        else if (relationshipUrlScore(relationship) > relationshipUrlScore(unique[index])) {
+            unique[index] = relationship;
+        }
+    }
+    return unique;
+}
+function relationshipsMatch(left, right) {
+    if (normalizeName(left.name) === normalizeName(right.name))
+        return true;
+    return (left.url !== undefined &&
+        right.url !== undefined &&
+        canonicalizeUrl(left.url) === canonicalizeUrl(right.url));
+}
+function relationshipUrlScore(relationship) {
+    if (relationship.url === undefined)
+        return 0;
+    return new URL(relationship.url).hash === "" ? 2 : 1;
+}
+function normalizeName(value) {
+    return value.trim().replace(/\s+/gu, " ").toLocaleLowerCase("en-US");
+}
+function canonicalizeUrl(value) {
+    const url = new URL(value);
+    url.hash = "";
+    if (url.pathname !== "/")
+        url.pathname = url.pathname.replace(/\/+$/u, "");
+    return url.toString();
+}
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evcraddock/slug-cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Command-line tool for Slugkit sites.",
   "private": false,
   "type": "module",
@@ -28,6 +28,7 @@
   "dependencies": {
     "@evcraddock/slug-core": "0.1.1",
     "adm-zip": "^0.5.18",
+    "cheerio": "^1.2.0",
     "yaml": "^2.9.0"
   }
 }