@evcraddock/slug-cli 0.9.0 → 0.11.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
 ---
@@ -67,13 +67,94 @@ date: 2020-01-02
 tags:
   - writing
   - updates
-banner: images/hero.png
+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.
+An article `banner` starting with `./` is a local file path resolved from the Markdown file. It is uploaded through the Slugkit media API under `posts/<slug>/banner.<extension>` and saved as the post's explicit `bannerUrl` without modifying Markdown content. Re-importing that local banner uploads the current file again to refresh the deterministic media object key. A banner without `./` is an existing same-site media key, not a local file.
+
+**Migration:** change existing local banner references such as `banner: images/hero.png` to `banner: ./images/hero.png`. There is no local-file fallback for missing media keys. Full URLs, absolute filesystem paths, `..` path segments (including `../`), empty values, backslashes, and URL-encoded or reserved path characters (`:`, `%`, `?`, `#`) are rejected.
+
+The command looks up the post by slug: it creates a missing post and updates an existing one, applying the supplied metadata, body, and tags. A new article without `date` or `publishedAt` is unpublished. Re-importing an existing article preserves its ID, slug, and publication timestamp when dates are omitted. Omitting `banner` leaves an existing banner unchanged; for a new article it means no banner. Link imports continue to map `banner_url` directly to `bannerUrl`.
+
+### Upload once and reuse an article banner
+
+Upload a shared image with a stable key:
+
+```bash
+slug --site my-site media upload ./technology.png \
+  --key banners/technology.png \
+  --alt "Technology banner"
+```
+
+Use that key in any number of articles:
+
+```markdown
+---
+title: Technology notes
+slug: technology-notes
+type: article
+banner: banners/technology.png
+---
+
+The article body.
+```
+
+```bash
+slug --site my-site post import ./technology-notes.md
+```
+
+For an API base of `https://your-site.example/api/v1`, the importer verifies `https://your-site.example/media/banners/technology.png`. It uses the API's origin and the site's `/media/` route, not a separately configured external media hostname. It sends an unauthenticated `HEAD` request with a five-second timeout and requires HTTP 200 with an `image/*` content type. No image body is downloaded, no media database lookup is required, and no new upload is made. Redirects are rejected rather than followed.
+
+A missing shared image or local file stops import before post or media mutations. Non-image responses, unsupported HEAD requests, network failures, and server errors also stop import with contextual errors; they are not silently treated as missing images or replaced with defaults.
+
+Replacing an image at a shared key changes it for every article using that key, subject to browser or proxy caching. Deleting it affects all those articles too: when viewed in a JavaScript-enabled browser, unavailable article banners are removed without a broken-image placeholder or default banner. Articles with no banner have none. URL verification at import time is only a point-in-time availability check; it does not prevent later deletion.
+
+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/banner-import.d.ts

@@ -0,0 +1,12 @@
+export interface ArticleBanner {
+    bannerPath?: string;
+    bannerKey?: string;
+}
+interface VerifyBannerKeyOptions {
+    apiBaseUrl: string;
+    key: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function readArticleBanner(frontmatter: Record<string, unknown>, filePath: string): ArticleBanner;
+export declare function verifyBannerKey(options: VerifyBannerKeyOptions): Promise<string>;
+export {};

package/dist/banner-import.js

@@ -0,0 +1,62 @@
+import { dirname, resolve } from "node:path";
+import { CliError, createInvalidUsageError, ExitCode } from "./errors.js";
+export function readArticleBanner(frontmatter, filePath) {
+    if (!("banner" in frontmatter))
+        return {};
+    const value = frontmatter.banner;
+    if (typeof value !== "string" || value.trim() === "") {
+        throw createInvalidUsageError("frontmatter.banner must be a non-empty string");
+    }
+    const local = value.startsWith("./");
+    assertBannerKey(local ? value.slice(2) : value);
+    return local ? { bannerPath: resolve(dirname(filePath), value) } : { bannerKey: value };
+}
+function assertBannerKey(key) {
+    const invalidSegment = key
+        .split("/")
+        .some((part) => part === "" || part === "." || part === "..");
+    const hasControlCharacter = [...key].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127);
+    if (invalidSegment || hasControlCharacter || key !== key.trim() || /[:\\%?#]/u.test(key)) {
+        throw createInvalidUsageError("frontmatter.banner must be a media key or ./local-file path; URLs, absolute paths, traversal, and URL-encoded or reserved path characters are not allowed");
+    }
+}
+export async function verifyBannerKey(options) {
+    assertBannerKey(options.key);
+    const key = options.key.split("/").map(encodeURIComponent).join("/");
+    const url = new URL(`/media/${key}`, options.apiBaseUrl).toString();
+    let response;
+    try {
+        response = await (options.fetchImpl ?? fetch)(url, {
+            method: "HEAD",
+            headers: { accept: "image/*" },
+            credentials: "omit",
+            redirect: "manual",
+            signal: AbortSignal.timeout(5_000),
+        });
+    }
+    catch {
+        throw new CliError(`Cannot verify banner: network request failed or timed out for ${url}`, ExitCode.NetworkError);
+    }
+    assertBannerResponse(response, url);
+    return url;
+}
+function assertBannerResponse(response, url) {
+    let reason;
+    if (response.status === 404 || response.status === 410) {
+        reason = "Banner image not found";
+    }
+    else if (response.status >= 300 && response.status < 400) {
+        reason = "Cannot verify banner: redirects are not allowed";
+    }
+    else if (response.status === 405 || response.status === 501) {
+        reason = "Cannot verify banner: HEAD requests are not supported";
+    }
+    else if (response.status !== 200) {
+        reason = `Cannot verify banner: HTTP ${response.status}`;
+    }
+    else if (!/^image\/[a-z0-9.+-]+(?:\s*;|$)/iu.test(response.headers.get("content-type") ?? "")) {
+        reason = "Cannot verify banner: response is not an image";
+    }
+    if (reason !== undefined)
+        throw new CliError(`${reason}: ${url}`, ExitCode.ApiError, response.status);
+}

package/dist/commands.js

@@ -5,8 +5,10 @@ import AdmZip from "adm-zip";
 import { parse as parseYaml } from "yaml";
 import { SLUGKIT_API_MAJOR_VERSION, SLUGKIT_API_NAME, compareSlugkitApiVersions, normalizeApiBaseUrl, readSlugkitApiMajorVersion, } from "@evcraddock/slug-core";
 import { isValidSiteName, readConfig, removeConfigSite, setConfigSiteApiBaseUrl, setConfigSiteApiKey, toDisplayConfig, writeConfig, } from "./config.js";
+import { readArticleBanner, verifyBannerKey } from "./banner-import.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 +23,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]
@@ -142,7 +144,7 @@ const GENERATED_SITE_SLUGKIT_DEPENDENCIES = {
     "@evcraddock/slug-auth": "0.1.0",
     "@evcraddock/slug-core": "0.1.1",
     "@evcraddock/slug-federation": "0.1.0",
-    "@evcraddock/slug-media": "0.1.0",
+    "@evcraddock/slug-media": "0.1.1",
 };
 const INIT_HELP_TEXT = `slug init - create a standalone Slugkit-compatible website
 
@@ -924,24 +926,52 @@ 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 = post.bannerKey === undefined
+        ? (uploadedBannerUrl ?? post.bannerUrl)
+        : await verifyBannerKey({
+            apiBaseUrl: api.apiBaseUrl,
+            key: post.bannerKey,
+            fetchImpl: context.fetchImpl,
+        });
+    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 +1007,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 = type === "article" ? readArticleBanner(frontmatter, filePath) : {};
+    const linkBannerUrl = readMarkdownOptionalString(frontmatter, "banner_url", "frontmatter");
     return {
         slug,
         type,
@@ -1000,75 +1041,179 @@ async function readMarkdownPostImport(filePath) {
         ...(url === undefined ? {} : { url }),
         ...(tags === undefined ? {} : { tags }),
         ...(publishedAt === undefined ? {} : { publishedAt }),
-        ...(banner === undefined ? {} : { bannerPath: resolve(dirname(filePath), banner) }),
+        ...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);
     }
-    if (value.startsWith("'") && value.endsWith("'")) {
-        return value.slice(1, -1).replace(/''/gu, "'");
+    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"}`);
     }
-    return value;
+    return matches[0];
 }
-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 findMarkdownRelationshipMatches(records, input) {
+    if (input.url === undefined) {
+        const name = normalizeImportName(input.name);
+        return records.filter((record) => normalizeImportName(record.name) === name);
+    }
+    const url = canonicalizeImportUrl(input.url);
+    return records.filter((record) => record.url !== undefined && record.url !== null && canonicalizeImportUrl(record.url) === url);
 }
-function readOptionalFrontmatterString(frontmatter, key) {
-    const value = frontmatter.get(key);
-    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+function canonicalizeImportUrl(value) {
+    const url = new URL(value);
+    url.hash = "";
+    if (url.pathname !== "/")
+        url.pathname = url.pathname.replace(/\/+$/u, "");
+    return url.toString();
 }
-function readFrontmatterTags(frontmatter) {
-    const value = frontmatter.get("tags");
-    return Array.isArray(value) ? value : undefined;
+function normalizeImportName(value) {
+    return value.trim().replace(/\s+/gu, " ").toLocaleLowerCase("en-US");
 }
-function readImportPublishedAt(frontmatter) {
-    const publishedAt = readOptionalFrontmatterString(frontmatter, "publishedAt") ??
-        readOptionalFrontmatterString(frontmatter, "date");
-    return publishedAt === undefined ? undefined : normalizeCliPublishedAt(publishedAt);
+function mergeIds(existing, added) {
+    return [...new Set([...existing, ...added])];
+}
+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 +1227,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 +1284,7 @@ async function runPostsCreateCommand(context, args) {
         "title",
         "url",
         "excerpt",
+        "banner-url",
         "tag",
         "source-id",
         "credit-contact-id",
@@ -1169,6 +1312,7 @@ async function runPostsEditCommand(context, args) {
         "title",
         "url",
         "excerpt",
+        "banner-url",
         "tag",
         "source-id",
         "credit-contact-id",
@@ -1255,6 +1399,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 +1496,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.11.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"
   }
 }