@evcraddock/slug-cli 0.8.0 → 0.9.0

package/README.md

@@ -75,6 +75,33 @@ 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.
 
+## 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.
 
 Example config:

package/dist/commands.js

@@ -2,6 +2,7 @@ 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";
@@ -36,6 +37,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]
@@ -1667,12 +1669,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 +1718,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/package.json

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