@evcraddock/slug-cli 0.6.5 → 0.8.0

package/README.md

@@ -51,7 +51,29 @@ Use `slug --site <name> site config show` to read supported runtime site configu
 
 Use `slug --site <name> doctor` to check API compatibility and package metadata. Use `slug --site <name> upgrade` for advisory, non-destructive package update recommendations; it reports suggested dependency changes without rewriting site files.
 
-Use `slug --site <name> post list`, `slug --site <name> post show <slug>`, `slug --site <name> post create`, `slug --site <name> post edit <slug>`, `slug --site <name> post publish <slug>`, `slug --site <name> post unpublish <slug>`, and `slug --site <name> post delete <slug>` to manage posts through the Slugkit posts API. For migration imports, pass `--published-at <date-or-datetime>` to `post create` or `post publish` to preserve an original publish date without triggering follower delivery by default.
+Use `slug --site <name> post list`, `slug --site <name> post show <slug>`, `slug --site <name> post create`, `slug --site <name> post edit`, `slug --site <name> post publish`, `slug --site <name> post unpublish`, and `slug --site <name> post delete` to manage posts through the Slugkit posts API. For migration imports, pass `--published-at <date-or-datetime>` to `post create` or `post publish` to preserve an original publish date without triggering follower delivery by default.
+
+## 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]`.
+
+```markdown
+---
+title: Hello world
+slug: hello-world
+type: article
+excerpt: A short introduction
+date: 2020-01-02
+tags:
+  - writing
+  - updates
+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.
 
 Use `slug tag list` to list tags and post usage counts through the Slugkit tags API.
 

package/dist/commands.js

@@ -19,6 +19,7 @@ Usage:
   slug [--config <file>] init <directory> --name <name> [--site-title <title>] [--template <name>] [--template-url <url>] [--template-dir <dir>] [--json]
   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 delete <slug> [--json]
@@ -343,7 +344,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"));
@@ -362,25 +363,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))
@@ -904,6 +904,8 @@ async function runPostsCommand(context, args) {
             return runPostsListCommand(context, args.slice(1));
         case "show":
             return runPostsShowCommand(context, args.slice(1));
+        case "import":
+            return runPostsImportCommand(context, args.slice(1));
         case "create":
             return runPostsCreateCommand(context, args.slice(1));
         case "edit":
@@ -915,8 +917,189 @@ async function runPostsCommand(context, args) {
         case "unpublish":
             return runPostsLifecycleCommand(context, args.slice(1), "unpublish");
         default:
-            throw createInvalidUsageError("Usage: slug post <list|show|create|edit|delete|publish|unpublish>");
+            throw createInvalidUsageError("Usage: slug post <list|show|import|create|edit|delete|publish|unpublish>");
+    }
+}
+async function runPostsImportCommand(context, args) {
+    const { filePath, json } = readPostImportArgs(args);
+    const post = await readMarkdownPostImport(filePath);
+    const api = await createConfiguredApiContext(context);
+    const bannerUrl = post.bannerPath === undefined
+        ? undefined
+        : await uploadPostImportBanner(api, post, post.bannerPath);
+    const content = bannerUrl === undefined ? post.content : createBannerContent(post, bannerUrl);
+    const body = {
+        type: post.type,
+        slug: post.slug,
+        content,
+        ...(post.title === undefined ? {} : { title: post.title }),
+        ...(post.excerpt === undefined ? {} : { excerpt: post.excerpt }),
+        ...(post.url === undefined ? {} : { url: post.url }),
+        ...(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({
+            method: "PUT",
+            path: `/posts/${encodeURIComponent(post.slug)}`,
+            body: withoutPostType(body),
+        });
+    if (json) {
+        writeJson(context.writer, response);
     }
+    else {
+        context.writer.stdout(`Imported post ${response.data.slug} (${existing === undefined ? "created" : "updated"}).`);
+    }
+    return { exitCode: ExitCode.Ok };
+}
+function readPostImportArgs(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 post import <file.md> [--json]");
+    }
+    return { filePath: positional[0], json };
+}
+async function readMarkdownPostImport(filePath) {
+    let markdown;
+    try {
+        markdown = await readFile(filePath, "utf8");
+    }
+    catch {
+        throw createInvalidUsageError(`Cannot read Markdown file: ${filePath}`);
+    }
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(markdown);
+    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");
+    if (type !== "article" && type !== "link" && type !== "note") {
+        throw createInvalidUsageError("Frontmatter type must be article, link, or note");
+    }
+    const title = readOptionalFrontmatterString(frontmatter, "title");
+    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");
+    return {
+        slug,
+        type,
+        ...(title === undefined ? {} : { title }),
+        ...(excerpt === undefined ? {} : { excerpt }),
+        ...(url === undefined ? {} : { url }),
+        ...(tags === undefined ? {} : { tags }),
+        ...(publishedAt === undefined ? {} : { publishedAt }),
+        ...(banner === undefined ? {} : { bannerPath: resolve(dirname(filePath), banner) }),
+        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));
+        }
+    }
+    return frontmatter;
+}
+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.
+        }
+    }
+    if (value.startsWith("'") && value.endsWith("'")) {
+        return value.slice(1, -1).replace(/''/gu, "'");
+    }
+    return value;
+}
+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 readOptionalFrontmatterString(frontmatter, key) {
+    const value = frontmatter.get(key);
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function readFrontmatterTags(frontmatter) {
+    const value = frontmatter.get("tags");
+    return Array.isArray(value) ? value : undefined;
+}
+function readImportPublishedAt(frontmatter) {
+    const publishedAt = readOptionalFrontmatterString(frontmatter, "publishedAt") ??
+        readOptionalFrontmatterString(frontmatter, "date");
+    return publishedAt === undefined ? undefined : normalizeCliPublishedAt(publishedAt);
+}
+async function uploadPostImportBanner(api, post, bannerPath) {
+    const file = await readMediaUploadFile(bannerPath);
+    const fileBody = file.body.buffer.slice(file.body.byteOffset, file.body.byteOffset + file.body.byteLength);
+    const body = new FormData();
+    body.set("file", new File([fileBody], file.filename, { type: file.mimeType }));
+    body.set("altText", `${post.title ?? post.slug} banner`);
+    body.set("key", `posts/${post.slug}/banner${extname(file.filename).toLowerCase()}`);
+    const response = await api.client.requestJson({
+        method: "POST",
+        path: "/media",
+        body,
+    });
+    return response.data.url;
+}
+function createBannerContent(post, bannerUrl) {
+    return `![${post.title ?? post.slug} banner](${bannerUrl})\n\n${post.content}`;
+}
+async function findImportedPost(client, slug) {
+    try {
+        return (await client.requestJson({ path: `/posts/${encodeURIComponent(slug)}` }))
+            .data;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.status === 404)
+            return undefined;
+        throw error;
+    }
+}
+function withoutPostType(input) {
+    const { type, ...update } = input;
+    void type;
+    return update;
 }
 async function runPostsListCommand(context, args) {
     const parsed = parsePostFlags(args, ["type", "status", "tag"]);

package/dist/errors.d.ts

@@ -7,7 +7,8 @@ export declare const ExitCode: {
 };
 export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
 export declare class CliError extends Error {
+    readonly status?: number | undefined;
     readonly exitCode: ExitCode;
-    constructor(message: string, exitCode: ExitCode);
+    constructor(message: string, exitCode: ExitCode, status?: number | undefined);
 }
 export declare function createInvalidUsageError(message: string): CliError;

package/dist/errors.js

@@ -6,9 +6,11 @@ export const ExitCode = {
     ApiError: 12,
 };
 export class CliError extends Error {
+    status;
     exitCode;
-    constructor(message, exitCode) {
+    constructor(message, exitCode, status) {
         super(message);
+        this.status = status;
         this.name = "CliError";
         this.exitCode = exitCode;
     }

package/dist/http.js

@@ -25,10 +25,10 @@ export class SlugHttpClient {
                 body: createRequestBody(options.body),
             });
             if (response.status === 401 || response.status === 403) {
-                throw new CliError(await readApiErrorMessage(response, "Authentication failed"), ExitCode.AuthenticationError);
+                throw new CliError(await readApiErrorMessage(response, "Authentication failed"), ExitCode.AuthenticationError, response.status);
             }
             if (!response.ok) {
-                throw new CliError(await readApiErrorMessage(response, `API request failed with status ${response.status}`), ExitCode.ApiError);
+                throw new CliError(await readApiErrorMessage(response, `API request failed with status ${response.status}`), ExitCode.ApiError, response.status);
             }
             return response;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evcraddock/slug-cli",
-  "version": "0.6.5",
+  "version": "0.8.0",
   "description": "Command-line tool for Slugkit sites.",
   "private": false,
   "type": "module",