@evcraddock/slug-cli 0.6.4 → 0.7.0

package/README.md

@@ -25,7 +25,7 @@ Create a standalone site with:
 slug init ./my-site --name my-site --site-title "My Site"
 ```
 
-Run `slug init --help` for template options. By default, `slug init` downloads the default template zip artifact. `--template-dir` remains available for local template development, `--template-url` supports alternate remote zip artifacts, and `--template` reserves the selection path for future named templates.
+Run `slug init --help` for template options. By default, `slug init` downloads the latest template zip artifact and falls back to the template artifact published with the installed CLI version if the latest artifact is missing. `--template-dir` remains available for local template development, `--template-url` supports alternate remote zip artifacts, and `--template` reserves the selection path for future named templates. Explicit `--template-url` and `SLUGKIT_TEMPLATE_URL` overrides do not fall back.
 
 ## Login and configuration
 
@@ -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]
@@ -155,7 +156,7 @@ Options:
   --json                 Print command output as JSON.
   --help, -h             Show this help.
 
-By default, slug init downloads the default template zip artifact. Set SLUGKIT_TEMPLATE_URL or pass --template-url to use a different zip artifact. Generated sites do not depend on the template artifact at runtime.`;
+By default, slug init downloads the latest template zip artifact and falls back to the CLI-versioned artifact if latest is missing. Set SLUGKIT_TEMPLATE_URL or pass --template-url to use a different zip artifact without fallback. Generated sites do not depend on the template artifact at runtime.`;
 const SITE_INIT_NEXT_STEPS = [
     "Install dependencies",
     "Copy and edit .env",
@@ -438,17 +439,37 @@ async function resolveInitTemplateSource(context, options) {
     if (options.template !== undefined && options.template !== DEFAULT_TEMPLATE_NAME) {
         throw createInvalidUsageError(`Unsupported template: ${options.template}. Use --template-url for external template zip artifacts.`);
     }
-    return downloadTemplateSite(context, getDefaultTemplateUrl(context));
+    return downloadDefaultTemplateSite(context, getDefaultTemplateResolution(context));
 }
-function getDefaultTemplateUrl(context) {
-    if (context.templateAssetBaseUrl !== undefined) {
-        return `${context.templateAssetBaseUrl.replace(/\/+$/u, "")}/slugkit-site-template.zip`;
-    }
+function getDefaultTemplateResolution(context) {
     const environmentUrl = process.env.SLUGKIT_TEMPLATE_URL?.trim();
     if (environmentUrl !== undefined && environmentUrl !== "") {
-        return environmentUrl;
+        return { primaryUrl: environmentUrl };
+    }
+    const primaryUrl = context.templateAssetBaseUrl !== undefined
+        ? `${context.templateAssetBaseUrl.replace(/\/+$/u, "")}/slugkit-site-template.zip`
+        : DEFAULT_TEMPLATE_URL;
+    return {
+        primaryUrl,
+        fallbackUrl: getVersionedTemplateUrl(context.packageVersion),
+    };
+}
+function getVersionedTemplateUrl(packageVersion) {
+    const version = packageVersion.trim().replace(/^v/u, "");
+    return `https://forge.caradoc.com/erik/slugkit/releases/download/v${version}/slugkit-site-template-v${version}.zip`;
+}
+async function downloadDefaultTemplateSite(context, resolution) {
+    try {
+        return await downloadTemplateSite(context, resolution.primaryUrl);
+    }
+    catch (error) {
+        if (resolution.fallbackUrl === undefined ||
+            !(error instanceof TemplateDownloadError) ||
+            error.status !== 404) {
+            throw error;
+        }
+        return downloadTemplateSite(context, resolution.fallbackUrl);
     }
-    return DEFAULT_TEMPLATE_URL;
 }
 async function downloadTemplateSite(context, templateUrl) {
     let parsedUrl;
@@ -464,7 +485,7 @@ async function downloadTemplateSite(context, templateUrl) {
     const fetchImpl = context.fetchImpl ?? fetch;
     const response = await fetchImpl(parsedUrl);
     if (!response.ok) {
-        throw new CliError(`Failed to download Slugkit template from ${parsedUrl.toString()}: HTTP ${response.status}`, ExitCode.NetworkError);
+        throw new TemplateDownloadError(parsedUrl.toString(), response.status);
     }
     const tempDirectory = await mkdtemp(join(tmpdir(), "slug-template-"));
     const archivePath = join(tempDirectory, "template.zip");
@@ -479,6 +500,13 @@ async function downloadTemplateSite(context, templateUrl) {
         cleanup: () => rm(tempDirectory, { force: true, recursive: true }),
     };
 }
+class TemplateDownloadError extends CliError {
+    status;
+    constructor(templateUrl, status) {
+        super(`Failed to download Slugkit template from ${templateUrl}: HTTP ${status}`, ExitCode.NetworkError);
+        this.status = status;
+    }
+}
 async function findExtractedTemplateDirectory(extractDirectory) {
     if (await isTemplateSiteDirectory(extractDirectory)) {
         return extractDirectory;
@@ -877,6 +905,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":
@@ -888,8 +918,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.4",
+  "version": "0.7.0",
   "description": "Command-line tool for Slugkit sites.",
   "private": false,
   "type": "module",