@daz4126/swifty 3.2.0 → 4.1.0

package/MIGRATION.md

@@ -0,0 +1,60 @@
+# Migrating to Swifty 4
+
+Swifty 4 focuses on deterministic builds, safer deployment, and explicit errors.
+
+## Requirements
+
+- Upgrade Node.js to version 22 or 24. Older Node.js releases are no longer supported.
+- Run `npm install` after upgrading so the tracked lockfile installs the new minifiers.
+
+## Clean Output and Public Files
+
+Every full build empties the output directory. Files written directly to `dist/` are removed.
+
+Move files that must pass through unchanged into `public/`:
+
+```text
+public/manifest.webmanifest -> dist/manifest.webmanifest
+public/fonts/site.woff2     -> dist/fonts/site.woff2
+```
+
+Optimized images remain cached in `.swifty-cache/`, which should not be committed.
+
+## Folder Index Pages
+
+`pages/blog/index.md` is now the content and front matter for `/blog`. It no longer creates `/blog/index` or gets treated as a child page.
+
+## Permalinks and Base Paths
+
+Use `permalink` in page front matter to override a page URL:
+
+```yaml
+permalink: /company/about.html
+```
+
+For deployment below an origin path, set `base_path` and keep `site_url` as the origin:
+
+```yaml
+site_url: https://example.com
+base_path: /project
+```
+
+The base path changes public URLs but does not add a `dist/project/` directory.
+
+## Strict Build Errors
+
+Invalid configuration, front matter, JSON/YAML data, Eta templates, partial references, images, CSS, JavaScript, or generated HTML now fail the build. Fix the path reported in the error before deploying.
+
+## Minification
+
+Swifty now uses CleanCSS, Terser, and html-minifier-terser. JavaScript is compressed but identifiers are not mangled. Set `minify`, `minify_html`, `minify_css`, or `minify_js` to `false` if source formatting must be retained.
+
+## Development Server
+
+`swifty start` now uses Swifty's built-in static server. Set `server_port` in `config.yaml` to change its default port from `3000`.
+
+## Deploy Command
+
+`swifty deploy` stages only the configured output directory. It refuses to proceed when other changes are already staged, and it does not commit source changes automatically.
+
+Commit source changes separately before deploying.

package/README.md

@@ -25,6 +25,10 @@ Swifty uses convention over configuration to make it super simple to build blazi
 - **Previous/next navigation** - Auto-generated links between sibling pages
 - **[Eta templating](https://eta.js.org/)** - Full JavaScript in templates with EJS syntax
 - **Idiomorph navigation** with optional intent prefetching for SPA-like transitions
+- **Custom permalinks and base paths** for flexible deployment URLs
+- **Public asset passthrough** for files that should be copied unchanged
+
+Requires Node.js 22 or newer. See [Migrating to Swifty 4](MIGRATION.md) when upgrading an existing site.
 
 ## Quickstart
 
@@ -48,6 +52,7 @@ your-site/
 ├── css/            # Stylesheets (auto-injected)
 ├── js/             # JavaScript (auto-injected)
 ├── images/         # Images (auto-optimized to responsive WebP)
+├── public/         # Files copied unchanged to the output root
 ├── template.html   # Base HTML template
 └── config.yaml     # Site configuration
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daz4126/swifty",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "main": "./src/index.js",
   "type": "module",
   "exports": {
@@ -10,15 +10,18 @@
     "swifty": "./src/cli.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "files": [
-    "src/"
+    "src/",
+    "MIGRATION.md"
   ],
   "scripts": {
     "test": "mocha",
+    "test:package": "node scripts/verify-package.js",
+    "check": "npm test && npm run test:package",
     "build": "node src/build.js",
-    "start": "node src/build.js && serve dist",
+    "start": "node src/cli.js start",
     "init": "node src/init.js",
     "watch": "node src/watcher.js"
   },
@@ -32,16 +35,17 @@
   "description": "Super Speedy Static Site Generator",
   "dependencies": {
     "chokidar": "^4.0.0",
+    "clean-css": "^5.3.3",
     "eta": "^4.5.0",
     "fs-extra": "^11.2.0",
-    "gray-matter": "^4.0.3",
     "highlight.js": "^11.11.1",
+    "html-minifier-terser": "^7.2.0",
     "js-yaml": "^4.1.0",
     "livereload": "^0.10.3",
     "marked": "^14.1.3",
     "marked-highlight": "^2.2.1",
-    "serve": "^14.2.5",
-    "sharp": "^0.33.5"
+    "sharp": "^0.33.5",
+    "terser": "^5.48.0"
   },
   "devDependencies": {
     "mocha": "^11.1.0"

package/src/assets.js

@@ -9,6 +9,11 @@ import sharp from "sharp";
 import { dirs, defaultConfig } from "./config.js";
 import { mapLimit } from "./concurrency.js";
 import { minifyCss, minifyJs } from "./minify.js";
+import {
+  applyBasePathToCss,
+  withBasePath,
+  withoutBasePath,
+} from "./urls.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -33,7 +38,52 @@ const getBuildConcurrency = () => defaultConfig.build_concurrency || 16;
 const navigationEnabled = () => defaultConfig.morphing !== false;
 const minificationEnabled = (type) =>
   defaultConfig.minify !== false && defaultConfig[`minify_${type}`] !== false;
-const normalizeImageUrl = (url) => (url || "").split(/[?#]/)[0];
+const normalizeImageUrl = (url) =>
+  withoutBasePath((url || "").split(/[?#]/)[0]);
+
+const getImageCacheDirectory = () => {
+  const signature = crypto
+    .createHash("sha256")
+    .update(
+      JSON.stringify({
+        image_quality: defaultConfig.image_quality || 80,
+        max_image_width: defaultConfig.max_image_width || 800,
+        responsive_image_widths:
+          defaultConfig.responsive_image_widths || [320, 640, 800],
+      }),
+    )
+    .digest("hex")
+    .slice(0, 12);
+  return path.join(dirs.cache, "images", signature);
+};
+
+const prepareImageCache = async () => {
+  const cacheRoot = path.join(dirs.cache, "images");
+  const cacheDirectory = getImageCacheDirectory();
+  await fsExtra.ensureDir(cacheDirectory);
+
+  const entries = await fs.readdir(cacheRoot, { withFileTypes: true });
+  await Promise.all(
+    entries
+      .filter(
+        (entry) =>
+          entry.isDirectory() &&
+          path.join(cacheRoot, entry.name) !== cacheDirectory,
+      )
+      .map((entry) => fsExtra.remove(path.join(cacheRoot, entry.name))),
+  );
+
+  return cacheDirectory;
+};
+
+const removeStaleCachedImages = async (cacheDirectory, expectedFiles) => {
+  const files = await fs.readdir(cacheDirectory);
+  await Promise.all(
+    files
+      .filter((file) => !expectedFiles.has(file))
+      .map((file) => fsExtra.remove(path.join(cacheDirectory, file))),
+  );
+};
 
 const getResponsiveWidths = (originalWidth) => {
   const maxWidth = defaultConfig.max_image_width || 800;
@@ -62,7 +112,7 @@ const variantFilename = (filename, ext, width, outputWidth) =>
 const registerResponsiveImage = (filename, ext, variants) => {
   const basename = path.basename(filename, ext);
   const entry = {
-    src: `/images/${basename}.webp`,
+    src: withBasePath(`/images/${basename}.webp`),
     srcset: variants
       .map((variant) => `${variant.url} ${variant.width}w`)
       .join(", "),
@@ -70,7 +120,7 @@ const registerResponsiveImage = (filename, ext, variants) => {
     variants,
   };
 
-  responsiveImageMap.set(normalizeImageUrl(`/images/${filename}`), entry);
+  responsiveImageMap.set(normalizeImageUrl(withBasePath(`/images/${filename}`)), entry);
   responsiveImageMap.set(normalizeImageUrl(entry.src), entry);
 };
 
@@ -91,7 +141,7 @@ const getNavigationAssetName = async (filename = "swifty-navigation.js") => {
 
 const getNavigationScriptSrc = async () => {
   if (!navigationEnabled()) return "";
-  return `/swifty/${await getNavigationAssetName()}`;
+  return withBasePath(`/swifty/${await getNavigationAssetName()}`);
 };
 
 const isDestinationFresh = async (source, destination) => {
@@ -115,22 +165,37 @@ const copyIfStale = async (source, destination) => {
   return true;
 };
 
-const optimizeImageVariantToWebp = async (source, destination, width) => {
-  if (await isDestinationFresh(source, destination)) {
-    return false;
+const optimizeImageVariantToWebp = async (
+  source,
+  destination,
+  cacheDestination,
+  width,
+) => {
+  let optimized = false;
+
+  if (!(await isDestinationFresh(source, cacheDestination))) {
+    const imageQuality = defaultConfig.image_quality || 80;
+    await fsExtra.ensureDir(path.dirname(cacheDestination));
+
+    await sharp(source)
+      .resize({ width })
+      .toFormat("webp", { quality: imageQuality })
+      .toFile(cacheDestination);
+    optimized = true;
   }
 
-  const imageQuality = defaultConfig.image_quality || 80;
-
-  await sharp(source)
-    .resize({ width })
-    .toFormat("webp", { quality: imageQuality })
-    .toFile(destination);
-
-  return true;
+  await copyIfStale(cacheDestination, destination);
+  return optimized;
 };
 
-const optimizeImageToWebp = async (source, imagesFolder, filename, ext) => {
+const optimizeImageToWebp = async (
+  source,
+  imagesFolder,
+  cacheDirectory,
+  filename,
+  ext,
+  expectedCacheFiles,
+) => {
   const metadata = await sharp(source).metadata();
   const originalWidth = metadata.width || 0;
   const maxWidth = defaultConfig.max_image_width || 800;
@@ -138,17 +203,24 @@ const optimizeImageToWebp = async (source, imagesFolder, filename, ext) => {
     originalWidth > 0 ? Math.min(originalWidth, maxWidth) : maxWidth;
   const variants = getResponsiveWidths(originalWidth).map((width) => {
     const file = variantFilename(filename, ext, width, outputWidth);
+    expectedCacheFiles?.add(file);
     return {
       width,
       file,
-      url: `/images/${file}`,
+      url: withBasePath(`/images/${file}`),
       destination: path.join(imagesFolder, file),
+      cacheDestination: path.join(cacheDirectory, file),
     };
   });
 
   const results = await Promise.all(
     variants.map((variant) =>
-      optimizeImageVariantToWebp(source, variant.destination, variant.width),
+      optimizeImageVariantToWebp(
+        source,
+        variant.destination,
+        variant.cacheDestination,
+        variant.width,
+      ),
     ),
   );
 
@@ -163,12 +235,21 @@ const optimizeImageToWebp = async (source, imagesFolder, filename, ext) => {
 
 const processTextAsset = async (source, destination, type) => {
   const content = await fs.readFile(source, "utf-8");
-  const nextContent =
-    type === "css" && minificationEnabled("css")
-      ? minifyCss(content)
-      : type === "js" && minificationEnabled("js")
-        ? minifyJs(content)
-        : content;
+  let nextContent = content;
+
+  try {
+    if (type === "css" && minificationEnabled("css")) {
+      nextContent = minifyCss(applyBasePathToCss(content));
+    } else if (type === "js" && minificationEnabled("js")) {
+      nextContent = await minifyJs(content);
+    } else if (type === "css") {
+      nextContent = applyBasePathToCss(content);
+    }
+  } catch (error) {
+    throw new Error(`Unable to minify ${source}: ${error.message}`, {
+      cause: error,
+    });
+  }
 
   try {
     const currentContent = await fs.readFile(destination, "utf-8");
@@ -236,6 +317,9 @@ const copyNavigationAssets = async (outputDir = dirs.dist) => {
 };
 
 const copyAssets = async (outputDir = dirs.dist) => {
+  if (await fsExtra.pathExists(dirs.public)) {
+    await fsExtra.copy(dirs.public, outputDir, { overwrite: true });
+  }
   await ensureAndCopy(
     dirs.css,
     path.join(outputDir, "css"),
@@ -249,11 +333,14 @@ async function optimizeImages(outputDir = dirs.dist) {
 
   try {
     if (!(await fsExtra.pathExists(dirs.images))) {
+      await fsExtra.remove(path.join(dirs.cache, "images"));
       console.log(`No ${path.basename(dirs.images)} found in ${dirs.images}`);
       return;
     }
 
     const imagesFolder = path.join(outputDir, "images");
+    const cacheDirectory = await prepareImageCache();
+    const expectedCacheFiles = new Set();
     await fsExtra.ensureDir(imagesFolder);
 
     const files = await fs.readdir(dirs.images);
@@ -278,8 +365,10 @@ async function optimizeImages(outputDir = dirs.dist) {
         const optimized = await optimizeImageToWebp(
           filePath,
           imagesFolder,
+          cacheDirectory,
           file,
           ext,
+          expectedCacheFiles,
         );
         if (optimized) {
           console.log(`Optimized ${file}`);
@@ -287,8 +376,11 @@ async function optimizeImages(outputDir = dirs.dist) {
       },
       getBuildConcurrency(),
     );
+    await removeStaleCachedImages(cacheDirectory, expectedCacheFiles);
   } catch (error) {
-    console.error("Error optimizing images:", error);
+    throw new Error(`Unable to optimize images: ${error.message}`, {
+      cause: error,
+    });
   }
 }
 const generateAssetImports = async (dir, tagTemplate, validExts) => {
@@ -309,25 +401,25 @@ const generateAssetImports = async (dir, tagTemplate, validExts) => {
 const getCssImports = () =>
   generateAssetImports(
     dirs.css,
-    (file, mtime) => `<link rel="stylesheet" href="/css/${file}?v=${mtime}" />`,
+    (file, mtime) => `<link rel="stylesheet" href="${withBasePath(`/css/${file}`)}?v=${mtime}" />`,
     validExtensions.css,
   );
 const getJsImports = () =>
   generateAssetImports(
     dirs.js,
-    (file, mtime) => `<script src="/js/${file}?v=${mtime}"></script>`,
+    (file, mtime) => `<script src="${withBasePath(`/js/${file}`)}?v=${mtime}"></script>`,
     validExtensions.js,
   );
 const getCssPreloads = () =>
   generateAssetImports(
     dirs.css,
-    (file, mtime) => `<link rel="preload" href="/css/${file}?v=${mtime}" as="style" />`,
+    (file, mtime) => `<link rel="preload" href="${withBasePath(`/css/${file}`)}?v=${mtime}" as="style" />`,
     validExtensions.css,
   );
 const getJsPreloads = () =>
   generateAssetImports(
     dirs.js,
-    (file, mtime) => `<link rel="preload" href="/js/${file}?v=${mtime}" as="script" />`,
+    (file, mtime) => `<link rel="preload" href="${withBasePath(`/js/${file}`)}?v=${mtime}" as="script" />`,
     validExtensions.js,
   );
 
@@ -359,6 +451,7 @@ const optimizeSingleImage = async (filePath, outputDir = dirs.dist) => {
   const filename = path.basename(filePath);
   const ext = path.extname(filePath).toLowerCase();
   const imagesFolder = path.join(outputDir, "images");
+  const cacheDirectory = await prepareImageCache();
 
   await fsExtra.ensureDir(imagesFolder);
 
@@ -374,6 +467,7 @@ const optimizeSingleImage = async (filePath, outputDir = dirs.dist) => {
   const optimized = await optimizeImageToWebp(
     filePath,
     imagesFolder,
+    cacheDirectory,
     filename,
     ext,
   );
@@ -394,4 +488,5 @@ export {
   optimizeSingleImage,
   getNavigationScriptSrc,
   getResponsiveImage,
+  getImageCacheDirectory,
 };

package/src/build.js

@@ -18,8 +18,15 @@ const prepareOutputDirectory = async (outputDir) => {
   const outputPath = path.resolve(baseDir, outputDir);
   const outputContainsProject =
     projectPath === outputPath || projectPath.startsWith(`${outputPath}${path.sep}`);
+  const sourceDirectories = Object.entries(dirs)
+    .filter(([name]) => name !== "dist")
+    .map(([, directory]) => path.resolve(directory));
+  const outputOverlapsSource = sourceDirectories.some(
+    (directory) =>
+      outputPath === directory || outputPath.startsWith(`${directory}${path.sep}`),
+  );
 
-  if (outputContainsProject) {
+  if (outputContainsProject || outputOverlapsSource) {
     throw new Error(`Refusing to empty unsafe output directory: ${outputPath}`);
   }
 

package/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { execFileSync, spawn, spawnSync } from "child_process";
+import { execFileSync, spawnSync } from "child_process";
 import { fileURLToPath } from "url";
 
 const args = process.argv.slice(2);
@@ -92,8 +92,8 @@ async function main() {
         watcher.default(outDir);
       }
 
-      // Start the server (blocking)
-      spawn("npx", ["serve", outDir], { stdio: "inherit" });
+      const server = await import("./server.js");
+      await server.default(outDir);
       break;
     }
     case "watch": {
@@ -139,7 +139,10 @@ async function main() {
 }
 
 if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-  main();
+  main().catch((error) => {
+    console.error(`Swifty failed: ${error.message}`);
+    process.exitCode = 1;
+  });
 }
 
 export { commitAndPushOutput, main };

package/src/config.js

@@ -17,24 +17,105 @@ const dirs = {
   js: path.join(baseDir, "js"),
   partials: path.join(baseDir, "partials"),
   data: path.join(baseDir, "data"),
+  public: path.join(baseDir, "public"),
+  cache: path.join(baseDir, ".swifty-cache"),
 };
 
 async function loadConfig(dir) {
   const configFiles = ['config.yaml', 'config.yml', 'config.json'];
   for (const file of configFiles) {
     const filePath = path.join(dir, file);
+    let content;
+
     try {
-      await fs.access(filePath);
-      const content = await fs.readFile(filePath, 'utf-8');
-      return file.endsWith('.json') ? JSON.parse(content) : yaml.load(content);
-    } catch {}
+      content = await fs.readFile(filePath, 'utf-8');
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw new Error(`Unable to read config ${filePath}: ${error.message}`, {
+        cause: error,
+      });
+    }
+
+    try {
+      const config = file.endsWith('.json') ? JSON.parse(content) : yaml.load(content);
+      return validateConfig(config || {}, filePath);
+    } catch (error) {
+      throw new Error(`Unable to parse config ${filePath}: ${error.message}`, {
+        cause: error,
+      });
+    }
   }
   return {};
 }
 
+const validateConfig = (config, filePath = "config") => {
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new TypeError(`${filePath} must contain a configuration object`);
+  }
+
+  const booleans = [
+    "minify",
+    "minify_html",
+    "minify_css",
+    "minify_js",
+    "morphing",
+    "prefetching",
+  ];
+  const positiveNumbers = [
+    "build_concurrency",
+    "image_quality",
+    "livereload_port",
+    "max_image_width",
+    "server_port",
+    "watcher_delay",
+    "watcher_interval",
+    "words_per_minute",
+  ];
+
+  for (const key of booleans) {
+    if (config[key] !== undefined && typeof config[key] !== "boolean") {
+      throw new TypeError(`${key} in ${filePath} must be a boolean`);
+    }
+  }
+  for (const key of positiveNumbers) {
+    if (
+      config[key] !== undefined &&
+      (!Number.isFinite(config[key]) || config[key] <= 0)
+    ) {
+      throw new TypeError(`${key} in ${filePath} must be a positive number`);
+    }
+  }
+  if (
+    config.base_path !== undefined &&
+    (typeof config.base_path !== "string" ||
+      /^(?:[a-z]+:)?\/\//i.test(config.base_path) ||
+      config.base_path.includes("..") ||
+      /[?#]/.test(config.base_path))
+  ) {
+    throw new TypeError(`base_path in ${filePath} must be a URL path`);
+  }
+  if (
+    config.responsive_image_widths !== undefined &&
+    (!Array.isArray(config.responsive_image_widths) ||
+      config.responsive_image_widths.some(
+        (width) => !Number.isInteger(width) || width <= 0,
+      ))
+  ) {
+    throw new TypeError(
+      `responsive_image_widths in ${filePath} must contain positive integers`,
+    );
+  }
+  if (config.rss_feeds !== undefined && !Array.isArray(config.rss_feeds)) {
+    throw new TypeError(`rss_feeds in ${filePath} must be an array`);
+  }
+
+  return config;
+};
+
 // Hardcoded defaults (used if not specified in config file)
 const builtInDefaults = {
   default_layout_name: 'default',
+  base_path: '',
   // Reading time calculation
   words_per_minute: 200,
   // Image optimization settings
@@ -49,6 +130,7 @@ const builtInDefaults = {
   minify_css: true,
   minify_js: true,
   // LiveReload and watcher settings
+  server_port: 3000,
   livereload_port: 35729,
   watcher_delay: 100,
   watcher_interval: 500,
@@ -87,4 +169,4 @@ const reloadConfig = async () => {
 
 await reloadConfig();
 
-export { baseDir, dirs, defaultConfig, loadConfig, reloadConfig };
+export { baseDir, dirs, defaultConfig, loadConfig, reloadConfig, validateConfig };

package/src/data.js

@@ -24,36 +24,41 @@ async function loadData() {
     return data;
   }
 
+  let files;
   try {
-    const files = await fs.readdir(dirs.data);
+    files = await fs.readdir(dirs.data);
+  } catch (error) {
+    throw new Error(`Unable to read data directory ${dirs.data}: ${error.message}`, {
+      cause: error,
+    });
+  }
 
-    for (const file of files) {
-      const filePath = path.join(dirs.data, file);
-      const stat = await fs.stat(filePath);
+  for (const file of files) {
+    const filePath = path.join(dirs.data, file);
+    const stat = await fs.stat(filePath);
 
-      // Skip directories
-      if (stat.isDirectory()) continue;
+    // Skip directories
+    if (stat.isDirectory()) continue;
 
-      const ext = path.extname(file).toLowerCase();
-      const name = path.basename(file, ext);
+    const ext = path.extname(file).toLowerCase();
+    const name = path.basename(file, ext);
 
-      // Only process JSON and YAML files
-      if (!['.json', '.yaml', '.yml'].includes(ext)) continue;
+    // Only process JSON and YAML files
+    if (!['.json', '.yaml', '.yml'].includes(ext)) continue;
 
-      try {
-        const content = await fs.readFile(filePath, 'utf-8');
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
 
-        if (ext === '.json') {
-          data[name] = JSON.parse(content);
-        } else {
-          data[name] = yaml.load(content);
-        }
-      } catch (error) {
-        console.warn(`Error loading data file ${file}: ${error.message}`);
+      if (ext === '.json') {
+        data[name] = JSON.parse(content);
+      } else {
+        data[name] = yaml.load(content);
       }
+    } catch (error) {
+      throw new Error(`Unable to parse data file ${filePath}: ${error.message}`, {
+        cause: error,
+      });
     }
-  } catch (error) {
-    console.warn(`Error reading data directory: ${error.message}`);
   }
 
   dataCache = data;

package/src/frontmatter.js

@@ -0,0 +1,27 @@
+import yaml from "js-yaml";
+
+const frontMatterPattern =
+  /^---[ \t]*\r?\n([\s\S]*?)^---[ \t]*(?:\r?\n|$)/m;
+
+const parseFrontMatter = (source) => {
+  if (!/^---[ \t]*(?:\r?\n|$)/.test(source)) {
+    return { data: {}, content: source };
+  }
+
+  const match = source.match(frontMatterPattern);
+  if (!match) {
+    throw new Error("Front matter is missing a closing --- delimiter");
+  }
+
+  const data = yaml.load(match[1]) || {};
+  if (typeof data !== "object" || Array.isArray(data)) {
+    throw new TypeError("Front matter must contain a YAML object");
+  }
+
+  return {
+    data,
+    content: source.slice(match[0].length),
+  };
+};
+
+export { parseFrontMatter };