@evcraddock/slug-cli 0.8.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,78 @@ 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
+
+Import link sources and their optional contacts and accounts from YAML with `slug --site <name> sources import <file.yaml>`. The file has one required top-level `sources` array. Each source requires `name` and may include `url`, `description`, `imageUrl`, `faviconUrl`, `contacts`, and `accounts`. Contacts require `name` and may include `url` and `accounts`. Accounts require `label` and `url` and may include `avatarUrl`, `kind`, `protocol`, `default`, and `sortOrder`.
+
+```yaml
+sources:
+  - name: Example Blog
+    url: https://example.com
+    description: Example writing
+    accounts:
+      - label: Feed
+        url: https://example.com/feed.xml
+        kind: feed
+        protocol: rss
+        default: true
+    contacts:
+      - name: Jane Example
+        url: https://example.com/jane
+        accounts:
+          - label: Mastodon
+            url: https://social.example/@jane
+            kind: social
+            protocol: activitypub
+```
+
+The CLI validates the complete file before sending requests. It creates contacts first, associates their returned IDs when creating each source, and then creates accounts with the returned contact or source owner ID. Sources may omit both `contacts` and `accounts`. An API failure stops the import; because the API does not provide a bulk transaction, records created by earlier successful requests remain.
 
 Use `slug tag list` to list tags and post usage counts through the Slugkit tags API.
 

package/dist/commands.js

@@ -2,10 +2,12 @@ import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/
 import { tmpdir } from "node:os";
 import { dirname, basename, extname, join, resolve } from "node:path";
 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 { 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
 
@@ -20,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]
@@ -36,6 +38,7 @@ Usage:
   slug [--config <file>] sources list [--json]
   slug [--config <file>] sources show <id> [--json]
   slug [--config <file>] sources create --name <name> [--url <url>] [--description <text>] [--image-url <url>] [--favicon-url <url>] [--contact-id <id>]... [--json]
+  slug [--config <file>] sources import <file.yaml> [--json]
   slug [--config <file>] sources edit <id> [--name <name>] [--url <url>] [--description <text>] [--image-url <url>] [--favicon-url <url>] [--contact-id <id>]... [--json]
   slug [--config <file>] sources delete <id> [--json]
   slug [--config <file>] accounts list [--owner-type contact|source|site] [--owner-id <id>] [--json]
@@ -922,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({
@@ -975,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,
@@ -998,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);
-        }
-        else {
-            frontmatter.set(key, key === "tags" ? parseFrontmatterTags(rawValue) : parseFrontmatterScalar(rawValue));
-        }
+function parseMarkdownPostFrontmatter(value) {
+    let parsed;
+    try {
+        parsed = parseYaml(value);
     }
-    return frontmatter;
+    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 parseFrontmatterScalar(value) {
-    if (value.startsWith('"') && value.endsWith('"')) {
-        try {
-            const parsed = JSON.parse(value);
-            if (typeof parsed === "string")
-                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`);
         }
-        catch {
-            // Report the unparsed value below so the API can validate it where applicable.
+        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`);
         }
     }
-    if (value.startsWith("'") && value.endsWith("'")) {
-        return value.slice(1, -1).replace(/''/gu, "'");
+    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 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 value;
+    return record.authors.map((author, index) => parseMarkdownRelationship(author, `frontmatter.authors[${index}]`));
 }
-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 readMarkdownPublishedAt(record) {
+    const publishedAt = readMarkdownOptionalString(record, "publishedAt", "frontmatter") ??
+        readMarkdownOptionalString(record, "date", "frontmatter");
+    return publishedAt === undefined ? undefined : normalizeCliPublishedAt(publishedAt);
 }
-function readOptionalFrontmatterString(frontmatter, key) {
-    const value = frontmatter.get(key);
-    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+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 readFrontmatterTags(frontmatter) {
-    const value = frontmatter.get("tags");
-    return Array.isArray(value) ? value : undefined;
+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 matches[0];
 }
-function readImportPublishedAt(frontmatter) {
-    const publishedAt = readOptionalFrontmatterString(frontmatter, "publishedAt") ??
-        readOptionalFrontmatterString(frontmatter, "date");
-    return publishedAt === undefined ? undefined : normalizeCliPublishedAt(publishedAt);
+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 canonicalizeImportUrl(value) {
+    const url = new URL(value);
+    url.hash = "";
+    if (url.pathname !== "/")
+        url.pathname = url.pathname.replace(/\/+$/u, "");
+    return url.toString();
+}
+function normalizeImportName(value) {
+    return value.trim().replace(/\s+/gu, " ").toLocaleLowerCase("en-US");
+}
+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);
@@ -1080,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 {
@@ -1140,6 +1279,7 @@ async function runPostsCreateCommand(context, args) {
         "title",
         "url",
         "excerpt",
+        "banner-url",
         "tag",
         "source-id",
         "credit-contact-id",
@@ -1167,6 +1307,7 @@ async function runPostsEditCommand(context, args) {
         "title",
         "url",
         "excerpt",
+        "banner-url",
         "tag",
         "source-id",
         "credit-contact-id",
@@ -1253,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"]);
@@ -1349,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) {
@@ -1667,12 +1810,14 @@ async function runSourcesCommand(context, args) {
             return runSourcesShowCommand(context, args.slice(1));
         case "create":
             return runSourcesCreateCommand(context, args.slice(1));
+        case "import":
+            return runSourcesImportCommand(context, args.slice(1));
         case "edit":
             return runSourcesEditCommand(context, args.slice(1));
         case "delete":
             return runSourcesDeleteCommand(context, args.slice(1));
         default:
-            throw createInvalidUsageError("Usage: slug sources <list|show|create|edit|delete>");
+            throw createInvalidUsageError("Usage: slug sources <list|show|create|import|edit|delete>");
     }
 }
 async function runSourcesListCommand(context, args) {
@@ -1714,6 +1859,250 @@ async function runSourcesCreateCommand(context, args) {
     writeSourceMutationOutput(context.writer, response, parsed.json);
     return { exitCode: ExitCode.Ok };
 }
+async function runSourcesImportCommand(context, args) {
+    const { filePath, json } = readSourceImportArgs(args);
+    const sources = await readSourceImportFile(filePath);
+    const api = await createConfiguredApiContext(context);
+    const result = {
+        sources: [],
+        totals: { sources: 0, contacts: 0, accounts: 0 },
+    };
+    writeMutationTarget(context.writer, api.apiBaseUrl, json);
+    for (const [sourceIndex, source] of sources.entries()) {
+        result.sources.push(await importSource(api.client, source, sourceIndex, result.totals));
+    }
+    if (json) {
+        writeJson(context.writer, { data: result });
+    }
+    else {
+        writeSourceImportSummary(context.writer, result.totals);
+    }
+    return { exitCode: ExitCode.Ok };
+}
+function readSourceImportArgs(args) {
+    const json = args.includes("--json");
+    const positional = args.filter((arg) => arg !== "--json");
+    if (positional.length !== 1 || positional[0] === undefined || positional[0].startsWith("--")) {
+        throw createInvalidUsageError("Usage: slug sources import <file.yaml> [--json]");
+    }
+    return { filePath: positional[0], json };
+}
+async function readSourceImportFile(filePath) {
+    let content;
+    try {
+        content = await readFile(filePath, "utf8");
+    }
+    catch {
+        throw createInvalidUsageError(`Cannot read source import file: ${filePath}`);
+    }
+    let document;
+    try {
+        document = parseYaml(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unable to parse YAML";
+        throw createInvalidUsageError(`Invalid source import YAML: ${message}`);
+    }
+    return parseSourceImportDocument(document);
+}
+function parseSourceImportDocument(value) {
+    const root = readSourceImportRecord(value, "document", ["sources"]);
+    if (!Array.isArray(root.sources) || root.sources.length === 0) {
+        throw createInvalidUsageError("sources must be a non-empty array");
+    }
+    return root.sources.map((source, index) => parseSourceImportSource(source, `sources[${index}]`));
+}
+function parseSourceImportSource(value, path) {
+    const record = readSourceImportRecord(value, path, [
+        "name",
+        "url",
+        "description",
+        "imageUrl",
+        "faviconUrl",
+        "contacts",
+        "accounts",
+    ]);
+    return {
+        name: readSourceImportRequiredString(record, "name", path),
+        ...readSourceImportOptionalUrl(record, "url", path, ["http:", "https:"]),
+        ...readSourceImportOptionalString(record, "description", path),
+        ...readSourceImportOptionalUrl(record, "imageUrl", path, ["http:", "https:"]),
+        ...readSourceImportOptionalUrl(record, "faviconUrl", path, ["http:", "https:"]),
+        contacts: readSourceImportArray(record, "contacts", path, parseSourceImportContact),
+        accounts: readSourceImportArray(record, "accounts", path, parseSourceImportAccount),
+    };
+}
+function parseSourceImportContact(value, path) {
+    const record = readSourceImportRecord(value, path, ["name", "url", "accounts"]);
+    return {
+        name: readSourceImportRequiredString(record, "name", path),
+        ...readSourceImportOptionalUrl(record, "url", path, ["http:", "https:"]),
+        accounts: readSourceImportArray(record, "accounts", path, parseSourceImportAccount),
+    };
+}
+function parseSourceImportAccount(value, path) {
+    const record = readSourceImportRecord(value, path, [
+        "label",
+        "url",
+        "avatarUrl",
+        "kind",
+        "protocol",
+        "default",
+        "sortOrder",
+    ]);
+    const account = {
+        label: readSourceImportRequiredString(record, "label", path),
+        url: readSourceImportRequiredUrl(record, "url", path, ["http:", "https:", "mailto:"]),
+        ...readSourceImportOptionalUrl(record, "avatarUrl", path, ["http:", "https:"]),
+        ...readSourceImportOptionalString(record, "kind", path),
+        ...readSourceImportOptionalString(record, "protocol", path),
+    };
+    if ("default" in record)
+        account.default = readSourceImportBoolean(record, "default", path);
+    if ("sortOrder" in record)
+        account.sortOrder = readSourceImportInteger(record, "sortOrder", path);
+    return account;
+}
+function readSourceImportRecord(value, path, allowedFields) {
+    if (!isRecord(value))
+        throw createInvalidUsageError(`${path} must be an object`);
+    for (const key of Object.keys(value)) {
+        if (!allowedFields.includes(key)) {
+            throw createInvalidUsageError(`${path}.${key} is not supported`);
+        }
+    }
+    return value;
+}
+function readSourceImportRequiredString(record, key, path) {
+    const value = record[key];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw createInvalidUsageError(`${path}.${key} must be a non-empty string`);
+    }
+    return value;
+}
+function readSourceImportOptionalString(record, key, path) {
+    if (!(key in record))
+        return {};
+    if (typeof record[key] !== "string") {
+        throw createInvalidUsageError(`${path}.${key} must be a string`);
+    }
+    return { [key]: record[key] };
+}
+function readSourceImportRequiredUrl(record, key, path, protocols) {
+    const value = readSourceImportRequiredString(record, key, path);
+    assertSourceImportUrl(value, `${path}.${key}`, protocols);
+    return value;
+}
+function readSourceImportOptionalUrl(record, key, path, protocols) {
+    if (!(key in record))
+        return {};
+    const value = readSourceImportRequiredString(record, key, path);
+    assertSourceImportUrl(value, `${path}.${key}`, protocols);
+    return { [key]: value };
+}
+function assertSourceImportUrl(value, path, protocols) {
+    try {
+        const url = new URL(value);
+        if (!protocols.includes(url.protocol))
+            throw new Error("Unsupported protocol");
+    }
+    catch {
+        throw createInvalidUsageError(`${path} must be a valid ${protocols.join(" or ")} URL`);
+    }
+}
+function readSourceImportArray(record, key, path, parseItem) {
+    if (!(key in record))
+        return [];
+    const value = record[key];
+    if (!Array.isArray(value))
+        throw createInvalidUsageError(`${path}.${key} must be an array`);
+    return value.map((item, index) => parseItem(item, `${path}.${key}[${index}]`));
+}
+function readSourceImportBoolean(record, key, path) {
+    if (typeof record[key] !== "boolean") {
+        throw createInvalidUsageError(`${path}.${key} must be a boolean`);
+    }
+    return record[key];
+}
+function readSourceImportInteger(record, key, path) {
+    if (typeof record[key] !== "number" || !Number.isInteger(record[key])) {
+        throw createInvalidUsageError(`${path}.${key} must be an integer`);
+    }
+    return record[key];
+}
+async function importSource(client, source, sourceIndex, totals) {
+    const contacts = [];
+    for (const [contactIndex, contact] of source.contacts.entries()) {
+        const response = await requestSourceImport(client, "/contacts", { name: contact.name, ...(contact.url === undefined ? {} : { url: contact.url }) }, `sources[${sourceIndex}].contacts[${contactIndex}]`);
+        contacts.push({ input: contact, document: response.data, accountIds: [] });
+        totals.contacts += 1;
+    }
+    const sourceResponse = await requestSourceImport(client, "/sources", createImportedSourceBody(source, contacts.map((contact) => contact.document.id)), `sources[${sourceIndex}]`);
+    totals.sources += 1;
+    for (const [contactIndex, contact] of contacts.entries()) {
+        contact.accountIds.push(...(await importAccounts(client, contact.input.accounts, "contact", contact.document.id, `sources[${sourceIndex}].contacts[${contactIndex}].accounts`, totals)));
+    }
+    const accountIds = await importAccounts(client, source.accounts, "source", sourceResponse.data.id, `sources[${sourceIndex}].accounts`, totals);
+    return {
+        id: sourceResponse.data.id,
+        name: sourceResponse.data.name,
+        contacts: contacts.map((contact) => ({
+            id: contact.document.id,
+            name: contact.document.name,
+            accountIds: contact.accountIds,
+        })),
+        accountIds,
+    };
+}
+function createImportedSourceBody(source, contactIds) {
+    return {
+        name: source.name,
+        ...(source.url === undefined ? {} : { url: source.url }),
+        ...(source.description === undefined ? {} : { description: source.description }),
+        ...(source.imageUrl === undefined ? {} : { imageUrl: source.imageUrl }),
+        ...(source.faviconUrl === undefined ? {} : { faviconUrl: source.faviconUrl }),
+        ...(contactIds.length === 0 ? {} : { contactIds }),
+    };
+}
+async function importAccounts(client, accounts, ownerType, ownerId, path, totals) {
+    const ids = [];
+    for (const [index, account] of accounts.entries()) {
+        const response = await requestSourceImport(client, "/accounts", createImportedAccountBody(account, ownerType, ownerId), `${path}[${index}]`);
+        ids.push(response.data.id);
+        totals.accounts += 1;
+    }
+    return ids;
+}
+function createImportedAccountBody(account, ownerType, ownerId) {
+    return {
+        ownerType,
+        ownerId,
+        label: account.label,
+        url: account.url,
+        ...(account.avatarUrl === undefined ? {} : { avatarUrl: account.avatarUrl }),
+        ...(account.kind === undefined ? {} : { kind: account.kind }),
+        ...(account.protocol === undefined ? {} : { protocol: account.protocol }),
+        ...(account.default === undefined ? {} : { isDefault: account.default }),
+        ...(account.sortOrder === undefined ? {} : { sortOrder: account.sortOrder }),
+    };
+}
+async function requestSourceImport(client, path, body, importPath) {
+    try {
+        return await client.requestJson({ method: "POST", path, body });
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            throw new CliError(`Failed to import ${importPath}: ${error.message}`, error.exitCode, error.status);
+        }
+        throw error;
+    }
+}
+function writeSourceImportSummary(writer, totals) {
+    writer.stdout(`Imported ${formatImportCount(totals.sources, "source")}, ${formatImportCount(totals.contacts, "contact")}, and ${formatImportCount(totals.accounts, "account")}.`);
+}
+function formatImportCount(count, label) {
+    return `${count} ${label}${count === 1 ? "" : "s"}`;
+}
 async function runSourcesEditCommand(context, args) {
     const idArg = args[0];
     if (idArg === undefined || idArg.startsWith("--")) {

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.8.0",
+  "version": "0.10.0",
   "description": "Command-line tool for Slugkit sites.",
   "private": false,
   "type": "module",
@@ -27,6 +27,8 @@
   },
   "dependencies": {
     "@evcraddock/slug-core": "0.1.1",
-    "adm-zip": "^0.5.18"
+    "adm-zip": "^0.5.18",
+    "cheerio": "^1.2.0",
+    "yaml": "^2.9.0"
   }
 }