@evcraddock/slug-cli 0.10.0 → 0.11.0

package/README.md

@@ -67,13 +67,50 @@ date: 2020-01-02
 tags:
   - writing
   - updates
-banner: images/hero.png
+banner: ./images/hero.png
 ---
 
 The imported body.
 ```
 
-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.
+An article `banner` starting with `./` is a local file path resolved from the Markdown file. It is uploaded through the Slugkit media API under `posts/<slug>/banner.<extension>` and saved as the post's explicit `bannerUrl` without modifying Markdown content. Re-importing that local banner uploads the current file again to refresh the deterministic media object key. A banner without `./` is an existing same-site media key, not a local file.
+
+**Migration:** change existing local banner references such as `banner: images/hero.png` to `banner: ./images/hero.png`. There is no local-file fallback for missing media keys. Full URLs, absolute filesystem paths, `..` path segments (including `../`), empty values, backslashes, and URL-encoded or reserved path characters (`:`, `%`, `?`, `#`) are rejected.
+
+The command looks up the post by slug: it creates a missing post and updates an existing one, applying the supplied metadata, body, and tags. A new article without `date` or `publishedAt` is unpublished. Re-importing an existing article preserves its ID, slug, and publication timestamp when dates are omitted. Omitting `banner` leaves an existing banner unchanged; for a new article it means no banner. Link imports continue to map `banner_url` directly to `bannerUrl`.
+
+### Upload once and reuse an article banner
+
+Upload a shared image with a stable key:
+
+```bash
+slug --site my-site media upload ./technology.png \
+  --key banners/technology.png \
+  --alt "Technology banner"
+```
+
+Use that key in any number of articles:
+
+```markdown
+---
+title: Technology notes
+slug: technology-notes
+type: article
+banner: banners/technology.png
+---
+
+The article body.
+```
+
+```bash
+slug --site my-site post import ./technology-notes.md
+```
+
+For an API base of `https://your-site.example/api/v1`, the importer verifies `https://your-site.example/media/banners/technology.png`. It uses the API's origin and the site's `/media/` route, not a separately configured external media hostname. It sends an unauthenticated `HEAD` request with a five-second timeout and requires HTTP 200 with an `image/*` content type. No image body is downloaded, no media database lookup is required, and no new upload is made. Redirects are rejected rather than followed.
+
+A missing shared image or local file stops import before post or media mutations. Non-image responses, unsupported HEAD requests, network failures, and server errors also stop import with contextual errors; they are not silently treated as missing images or replaced with defaults.
+
+Replacing an image at a shared key changes it for every article using that key, subject to browser or proxy caching. Deleting it affects all those articles too: when viewed in a JavaScript-enabled browser, unavailable article banners are removed without a broken-image placeholder or default banner. Articles with no banner have none. URL verification at import time is only a point-in-time availability check; it does not prevent later deletion.
 
 Link imports may include one source and one or more authors:
 

package/dist/banner-import.d.ts

@@ -0,0 +1,12 @@
+export interface ArticleBanner {
+    bannerPath?: string;
+    bannerKey?: string;
+}
+interface VerifyBannerKeyOptions {
+    apiBaseUrl: string;
+    key: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function readArticleBanner(frontmatter: Record<string, unknown>, filePath: string): ArticleBanner;
+export declare function verifyBannerKey(options: VerifyBannerKeyOptions): Promise<string>;
+export {};

package/dist/banner-import.js

@@ -0,0 +1,62 @@
+import { dirname, resolve } from "node:path";
+import { CliError, createInvalidUsageError, ExitCode } from "./errors.js";
+export function readArticleBanner(frontmatter, filePath) {
+    if (!("banner" in frontmatter))
+        return {};
+    const value = frontmatter.banner;
+    if (typeof value !== "string" || value.trim() === "") {
+        throw createInvalidUsageError("frontmatter.banner must be a non-empty string");
+    }
+    const local = value.startsWith("./");
+    assertBannerKey(local ? value.slice(2) : value);
+    return local ? { bannerPath: resolve(dirname(filePath), value) } : { bannerKey: value };
+}
+function assertBannerKey(key) {
+    const invalidSegment = key
+        .split("/")
+        .some((part) => part === "" || part === "." || part === "..");
+    const hasControlCharacter = [...key].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127);
+    if (invalidSegment || hasControlCharacter || key !== key.trim() || /[:\\%?#]/u.test(key)) {
+        throw createInvalidUsageError("frontmatter.banner must be a media key or ./local-file path; URLs, absolute paths, traversal, and URL-encoded or reserved path characters are not allowed");
+    }
+}
+export async function verifyBannerKey(options) {
+    assertBannerKey(options.key);
+    const key = options.key.split("/").map(encodeURIComponent).join("/");
+    const url = new URL(`/media/${key}`, options.apiBaseUrl).toString();
+    let response;
+    try {
+        response = await (options.fetchImpl ?? fetch)(url, {
+            method: "HEAD",
+            headers: { accept: "image/*" },
+            credentials: "omit",
+            redirect: "manual",
+            signal: AbortSignal.timeout(5_000),
+        });
+    }
+    catch {
+        throw new CliError(`Cannot verify banner: network request failed or timed out for ${url}`, ExitCode.NetworkError);
+    }
+    assertBannerResponse(response, url);
+    return url;
+}
+function assertBannerResponse(response, url) {
+    let reason;
+    if (response.status === 404 || response.status === 410) {
+        reason = "Banner image not found";
+    }
+    else if (response.status >= 300 && response.status < 400) {
+        reason = "Cannot verify banner: redirects are not allowed";
+    }
+    else if (response.status === 405 || response.status === 501) {
+        reason = "Cannot verify banner: HEAD requests are not supported";
+    }
+    else if (response.status !== 200) {
+        reason = `Cannot verify banner: HTTP ${response.status}`;
+    }
+    else if (!/^image\/[a-z0-9.+-]+(?:\s*;|$)/iu.test(response.headers.get("content-type") ?? "")) {
+        reason = "Cannot verify banner: response is not an image";
+    }
+    if (reason !== undefined)
+        throw new CliError(`${reason}: ${url}`, ExitCode.ApiError, response.status);
+}

package/dist/commands.js

@@ -5,6 +5,7 @@ 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 { readArticleBanner, verifyBannerKey } from "./banner-import.js";
 import { CliError, createInvalidUsageError, ExitCode } from "./errors.js";
 import { SlugHttpClient } from "./http.js";
 import { discoverLinkRelationships } from "./link-metadata.js";
@@ -143,7 +144,7 @@ const GENERATED_SITE_SLUGKIT_DEPENDENCIES = {
     "@evcraddock/slug-auth": "0.1.0",
     "@evcraddock/slug-core": "0.1.1",
     "@evcraddock/slug-federation": "0.1.0",
-    "@evcraddock/slug-media": "0.1.0",
+    "@evcraddock/slug-media": "0.1.1",
 };
 const INIT_HELP_TEXT = `slug init - create a standalone Slugkit-compatible website
 
@@ -947,7 +948,13 @@ async function runPostsImportCommand(context, args) {
     const uploadedBannerUrl = post.bannerPath === undefined
         ? undefined
         : await uploadPostImportBanner(api, post, post.bannerPath);
-    const bannerUrl = uploadedBannerUrl ?? post.bannerUrl;
+    const bannerUrl = post.bannerKey === undefined
+        ? (uploadedBannerUrl ?? post.bannerUrl)
+        : await verifyBannerKey({
+            apiBaseUrl: api.apiBaseUrl,
+            key: post.bannerKey,
+            fetchImpl: context.fetchImpl,
+        });
     writeMutationTarget(context.writer, api.apiBaseUrl, json);
     const existing = await findImportedPost(api.client, post.slug);
     const relationships = await resolveMarkdownImportRelationships(api.client, post);
@@ -1024,7 +1031,7 @@ async function readMarkdownPostImport(filePath) {
     }
     const tags = readMarkdownTags(frontmatter);
     const publishedAt = readMarkdownPublishedAt(frontmatter);
-    const banner = readMarkdownOptionalString(frontmatter, "banner", "frontmatter");
+    const banner = type === "article" ? readArticleBanner(frontmatter, filePath) : {};
     const linkBannerUrl = readMarkdownOptionalString(frontmatter, "banner_url", "frontmatter");
     return {
         slug,
@@ -1034,9 +1041,7 @@ async function readMarkdownPostImport(filePath) {
         ...(url === undefined ? {} : { url }),
         ...(tags === undefined ? {} : { tags }),
         ...(publishedAt === undefined ? {} : { publishedAt }),
-        ...(type !== "article" || banner === undefined
-            ? {}
-            : { bannerPath: resolve(dirname(filePath), banner) }),
+        ...banner,
         ...(type !== "link" || linkBannerUrl === undefined ? {} : { bannerUrl: linkBannerUrl }),
         ...(source === undefined ? {} : { source }),
         ...(authors === undefined ? {} : { authors }),

package/package.json

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