@evcraddock/slug-cli 0.7.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]
@@ -344,7 +346,7 @@ function shouldExcludeTemplateEntry(relativePath, name) {
         parts.includes("data") ||
         parts.includes("coverage") ||
         relativePath === "src/__tests__/dev-environment.test.ts" ||
-        relativePath === "src/federation/__tests__/follow.test.ts" ||
+        relativePath === "src/federation/__tests__/follow.integration.test.ts" ||
         relativePath === ".env" ||
         name.endsWith(".log") ||
         name.endsWith(".tsbuildinfo"));
@@ -363,25 +365,24 @@ async function replaceGeneratedSitePlaceholders(directory, options) {
             `intro: ${JSON.stringify(`${options.siteTitle} is ready for posts, feeds, and federation.`)}`,
         ],
     ]);
-    await replaceTextFile(join(directory, "README.md"), [
-        ["# Slugkit Template Site", `# ${options.siteTitle}`],
-        [
-            "This is the in-repo Slugkit template website. It is toolkit source used for local CLI/API development and for `slug init`; it is not itself the deployable website you hand to a site owner. Generated sites should contain this website code without the `slug` CLI source code.\n\nInitialized sites are standalone Slugkit-compatible websites. After `slug init`, the generated site owns its code and may customize routes, templates, styles, assets, and deployment freely while preserving the Slugkit API contract that the `slug` CLI uses.",
-            "This is a standalone Slugkit-compatible website generated from the Slugkit template. This site owns its code and can customize routes, templates, styles, assets, and deployment freely while preserving the Slugkit API contract that the `slug` CLI uses.",
-        ],
-        [
-            "Local toolkit development can run `make garage-setup` from the Slugkit repository root after `make dev` starts Garage. Standalone initialized sites should configure these values for their own local or production S3-compatible service before uploading media.",
-            "Configure these values for your own local or production S3-compatible service before uploading media.",
-        ],
-        [
-            "## In-repository development\n\nWhen working inside the Slugkit toolkit repository, start the full local dev environment from the repository root:\n\n```bash\nmake dev\n```\n\nFrom `template/site`, you can also run the app and Tailwind watcher directly in separate terminals:\n\n```bash\nnpm run dev\nnpm run css:watch\n```\n\nRepository-root workspace commands are useful while developing the template itself:\n\n```bash\nnpm run db:migrate --workspace @slugkit/template-site\nnpm run db:status --workspace @slugkit/template-site\nnpm run test --workspace @slugkit/template-site\n```\n\nStandalone initialized sites should use the non-workspace commands shown in the quick start section.",
-            "## Local development\n\nInstall Overmind if it is not already available, then run the app and Tailwind watcher together from this site directory:\n\n```bash\nmake dev\n```\n\nThe generated `Procfile.dev` runs `npm run dev` for the Hono app and `npm run css:watch` for Tailwind. Use the non-workspace commands shown in the quick start section for migrations and local checks.",
-        ],
-        [
-            "## Related specs\n\n- [Web Spec 08: Template Setup Documentation](../../docs/web-specs/08-template-setup-documentation.md)\n- [CLI Spec 12: Site Init Command](../../docs/cli-specs/12-site-init-command.md)\n- [CLI Specs](../../docs/cli-specs/README.md)\n- [API Route Specs](../../docs/specs/README.md)",
-            "## Related Slugkit references\n\n- Slugkit API documentation is available from a running site at `/api/v1/docs`.\n- The CLI compatibility check is `slug doctor`.\n- The generated site marker is `.slugkit-site.json`.",
-        ],
+    await writeGeneratedSiteReadme(directory, options);
+}
+async function writeGeneratedSiteReadme(directory, options) {
+    const sourcePath = join(directory, "README.generated.md");
+    const source = await readFile(sourcePath, "utf8");
+    const replacements = new Map([
+        ["{{SITE_NAME}}", options.name],
+        ["{{SITE_TITLE}}", options.siteTitle],
     ]);
+    let content = source;
+    for (const [placeholder, value] of replacements) {
+        if (!content.includes(placeholder)) {
+            throw createInvalidUsageError(`Generated README is missing placeholder: ${placeholder}`);
+        }
+        content = content.replaceAll(placeholder, value);
+    }
+    await writeFile(join(directory, "README.md"), content, "utf8");
+    await rm(sourcePath);
 }
 function replaceGeneratedSiteWorkspaceDependencies(value) {
     if (!isRecord(value))
@@ -1668,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) {
@@ -1715,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.7.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"
   }
 }