@minamocms/framework 0.0.0-stage → 0.10.2

package/dist/services/migration-runner.js

@@ -0,0 +1,169 @@
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { listFilesRecursively } from "./fs-walk.js";
+import { GitOperationError, commitPaths } from "./git.js";
+import { validateContent } from "./validation.js";
+import { enqueue } from "./write-queue.js";
+export class MigrationError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'MigrationError';
+        this.reason = reason;
+    }
+}
+// Walks the migration chain one step at a time until currentVersion is
+// reached. Throws if a step is missing, or if a migration doesn't
+// actually advance the version (a defensive check against a broken
+// migration function).
+function applyMigrationChain(content, migrations, currentVersion, path) {
+    let current = content;
+    const initialVersion = current.schemaVersion;
+    if (typeof initialVersion !== 'number') {
+        throw new MigrationError('migration-failed', `"${path}" has no numeric schemaVersion`);
+    }
+    let version = initialVersion;
+    while (version < currentVersion) {
+        const migrate = migrations[version];
+        if (!migrate) {
+            throw new MigrationError('migration-failed', `No migration registered for schemaVersion ${version} ("${path}")`);
+        }
+        const next = migrate(current);
+        const nextVersion = next.schemaVersion;
+        if (typeof nextVersion !== 'number' || nextVersion <= version) {
+            throw new MigrationError('migration-failed', `Migration from schemaVersion ${version} did not advance schemaVersion ("${path}")`);
+        }
+        current = next;
+        version = nextVersion;
+    }
+    return current;
+}
+// Hand-rolled fs snapshot/restore, matching publish.ts's established
+// shape - but simpler: every file the write phase touches already
+// existed with real prior bytes (F3's skip logic guarantees this), so
+// there is no "did this file exist before" branch to carry. A
+// relocated file (targetPath !== path) is undone by removing whatever
+// landed at targetPath and restoring the original at its original path.
+function rollback(files) {
+    const failures = [];
+    for (const file of files) {
+        try {
+            if (file.targetPath !== file.path) {
+                try {
+                    unlinkSync(file.targetPath);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                }
+            }
+            writeFileSync(file.path, file.originalBytes);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    return failures;
+}
+async function runMigrationsJob(config, themeSchemas, migrations, currentVersion, author, options) {
+    // content/posts/ is a legacy root: posts were folded into pages, and
+    // no code walks a postsRoot for anything else any more (see
+    // config.ts) - it's computed locally, here only, purely to find any
+    // leftover legacy files this migration needs to relocate. A site
+    // that never had posts has no such directory; listFilesRecursively
+    // already returns [] for a missing root, same as every other caller.
+    const legacyPostsRoot = join(config.contentRoot, 'posts');
+    // Named walks (pages/menus/legacy posts), not one broad walk of
+    // contentRoot - see content-read.ts's listContent for the identical
+    // reasoning (Group N nested draftsRoot/redirectsPath inside
+    // contentRoot; a broad walk would double-migrate drafts and try to
+    // validate redirects.json as a page). base stays config.contentRoot
+    // for pages/menus so relativePath matches what validateContent
+    // expects. Legacy posts get their own targetPath: content/posts/
+    // was always flat (no nested slugs), so relocating each file to
+    // content/pages/blog/<slug>.json preserves its old /blog/<slug> URL
+    // as an ordinary nested page - no reserved namespace needed any more.
+    const files = [
+        ...listFilesRecursively(config.pagesRoot, config.contentRoot, '.json').map((rel) => ({
+            path: join(config.contentRoot, rel),
+            targetPath: join(config.contentRoot, rel),
+            relativePath: rel,
+        })),
+        ...listFilesRecursively(config.menusRoot, config.contentRoot, '.json').map((rel) => ({
+            path: join(config.contentRoot, rel),
+            targetPath: join(config.contentRoot, rel),
+            relativePath: rel,
+        })),
+        ...listFilesRecursively(legacyPostsRoot, legacyPostsRoot, '.json').map((rel) => ({
+            path: join(legacyPostsRoot, rel),
+            targetPath: join(config.contentRoot, 'pages', 'blog', rel),
+            relativePath: join('pages', 'blog', rel),
+        })),
+        ...listFilesRecursively(config.draftsRoot, config.draftsRoot, '.json').map((rel) => ({
+            path: join(config.draftsRoot, rel),
+            targetPath: join(config.draftsRoot, rel),
+            relativePath: rel,
+        })),
+    ];
+    // Compute every migration before writing anything. If any file's
+    // migration or validation throws, everything computed for other
+    // files so far is simply discarded - a mid-list failure aborts with
+    // literally zero writes having happened (F4's primary scenario).
+    const toMigrate = [];
+    for (const { path, targetPath, relativePath } of files) {
+        const originalBytes = readFileSync(path);
+        const parsed = JSON.parse(originalBytes.toString('utf-8'));
+        const schemaVersion = parsed.schemaVersion;
+        // A legacy posts/ file can never already be at currentVersion: the
+        // posts/ directory only ever held content written before this very
+        // migration existed, so this skip and the relocation above never
+        // conflict in practice.
+        if (typeof schemaVersion === 'number' && schemaVersion >= currentVersion) {
+            continue;
+        }
+        const migrated = applyMigrationChain(parsed, migrations, currentVersion, path);
+        const result = validateContent(relativePath, migrated, themeSchemas);
+        if (!result.valid) {
+            throw new MigrationError('validation-failed', `Migrated content at "${path}" failed validation: ${JSON.stringify(result.errors)}`);
+        }
+        const migratedBytes = Buffer.from(JSON.stringify(migrated, null, 2));
+        toMigrate.push({ path, targetPath, originalBytes, migratedBytes });
+    }
+    if (toMigrate.length === 0) {
+        return [];
+    }
+    try {
+        for (const file of toMigrate) {
+            if (file.targetPath !== file.path) {
+                mkdirSync(dirname(file.targetPath), { recursive: true });
+            }
+            writeFileSync(file.targetPath, file.migratedBytes);
+            if (file.targetPath !== file.path) {
+                unlinkSync(file.path);
+            }
+        }
+        const committedPaths = new Set();
+        for (const file of toMigrate) {
+            committedPaths.add(file.path);
+            committedPaths.add(file.targetPath);
+        }
+        if (options.commit !== false) {
+            commitPaths(config.siteRoot, [...committedPaths], `chore: migrate content to schema version ${currentVersion}`, author);
+        }
+    }
+    catch (error) {
+        const failures = rollback(toMigrate);
+        if (failures.length > 0) {
+            throw new MigrationError('rollback-failed', 'Migration run failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: error });
+        }
+        const reason = error instanceof GitOperationError ? 'commit-failed' : 'write-failed';
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new MigrationError(reason, `Migration run failed: ${detail}`, { cause: error });
+    }
+    return toMigrate.map((file) => file.path);
+}
+// Resolves to the files migrated (their original paths).
+export function runMigrations(config, themeSchemas, migrations, currentVersion, author, options = {}) {
+    return enqueue(() => runMigrationsJob(config, themeSchemas, migrations, currentVersion, author, options));
+}

package/dist/services/mime-types.d.ts

@@ -0,0 +1,3 @@
+export declare const MIME_TYPES: Record<string, string>;
+export declare const DEFAULT_MIME_TYPE = "application/octet-stream";
+export declare function mimeTypeFor(path: string): string;

package/dist/services/mime-types.js

@@ -0,0 +1,43 @@
+import { extname } from 'node:path';
+// A small hand-rolled lookup, not a dependency (@fastify/static would
+// be the obvious ecosystem package, but this is a handful of lines and
+// matches this codebase's existing minimal-dependency posture). Only
+// the common web asset types - nothing here needs to be exhaustive.
+//
+// Shared by both routes/assets.ts (theme CSS/JS/images/fonts) and
+// routes/public.ts's theme/root/ mirror (robots.txt, .well-known/*,
+// site-verification HTML files) via services/static-file.ts - the
+// text/xml/html entries below exist specifically for that second,
+// broader use case. Found live: robots.txt fell back to
+// DEFAULT_MIME_TYPE (application/octet-stream), which every browser
+// treats as "download this" rather than displaying it inline, even
+// though the actual content is plain text.
+export const MIME_TYPES = {
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    // Video: without these an uploaded .mp4 serves as the
+    // DEFAULT_MIME_TYPE below (application/octet-stream), which every
+    // browser treats as "download this" rather than playing it - and
+    // media-public.ts sets X-Content-Type-Options: nosniff, so nothing
+    // rescues it by sniffing. Same failure robots.txt already hit.
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.txt': 'text/plain; charset=utf-8',
+    '.xml': 'application/xml; charset=utf-8',
+    '.html': 'text/html; charset=utf-8',
+    '.htm': 'text/html; charset=utf-8',
+};
+export const DEFAULT_MIME_TYPE = 'application/octet-stream';
+export function mimeTypeFor(path) {
+    return MIME_TYPES[extname(path).toLowerCase()] ?? DEFAULT_MIME_TYPE;
+}

package/dist/services/move.d.ts

@@ -0,0 +1,16 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+import type { PreparedOperation } from './prepared-operation.ts';
+export type MoveReason = 'source-not-found' | 'destination-exists' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class MoveError extends Error {
+    readonly reason: MoveReason;
+    constructor(reason: MoveReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function prepareMovePage(config: SiteConfig, fromUrl: string, toUrl: string, options?: {
+    createRedirect?: boolean;
+}): PreparedOperation;
+export declare function movePage(config: SiteConfig, fromUrl: string, toUrl: string, message: string, author: CommitAuthor, options?: {
+    createRedirect?: boolean;
+}): Promise<void>;

package/dist/services/move.js

@@ -0,0 +1,236 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { listFilesRecursively } from "./fs-walk.js";
+import { commitPaths } from "./git.js";
+import { sanitisePath } from "./path-safety.js";
+import { linkSources, rewriteLinks } from "./links.js";
+import { addRedirect, loadRedirects, removeRedirectForPath, serialiseRedirects } from "./redirects.js";
+import { pagePathToUrl, urlToPagePath } from "./urls.js";
+import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
+export class MoveError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'MoveError';
+        this.reason = reason;
+    }
+}
+// Validates and writes everything a move needs, stopping short of the
+// commit itself - used both by the standalone movePageJob (which
+// commits immediately after) and by batch.ts (which accumulates this
+// alongside other operations and commits once for the whole batch). A
+// write-phase failure is caught and rolled back here, inside prepare
+// itself, so prepare either fully succeeds or fully undoes itself
+// before throwing.
+//
+// options.createRedirect defaults true - existing callers (and
+// batch.ts) keep today's behaviour unchanged. false skips only
+// addRedirect (the "old URL now redirects to the new one" step);
+// removeRedirectForPath still always runs regardless, since that's a
+// correctness cleanup (the destination URL can't stay claimed by a
+// stale redirect once a real page exists there), not a new redirect
+// being created.
+export function prepareMovePage(config, fromUrl, toUrl, options = {}) {
+    const createRedirect = options.createRedirect ?? true;
+    const fromRelative = urlToPagePath(fromUrl);
+    const toRelative = urlToPagePath(toUrl);
+    const fromPageFile = sanitisePath(config.pagesRoot, fromRelative);
+    const toPageFile = sanitisePath(config.pagesRoot, toRelative);
+    if (!existsSync(fromPageFile)) {
+        throw new MoveError('source-not-found', `No page found at "${fromUrl}"`);
+    }
+    if (existsSync(toPageFile)) {
+        throw new MoveError('destination-exists', `A page already exists at "${toUrl}"`);
+    }
+    const fromDirRelative = fromRelative.replace(/\.json$/, '');
+    const toDirRelative = toRelative.replace(/\.json$/, '');
+    const fromDir = sanitisePath(config.pagesRoot, fromDirRelative);
+    const toDir = sanitisePath(config.pagesRoot, toDirRelative);
+    const fromDirExists = existsSync(fromDir) && statSync(fromDir).isDirectory();
+    if (fromDirExists && existsSync(toDir)) {
+        throw new MoveError('destination-exists', `A directory already exists at the destination for "${toUrl}"`);
+    }
+    // A draft-only page (never published) already at the destination
+    // would be overwritten by this page's own draft moving there.
+    const hasDrafts = existsSync(config.draftsRoot);
+    if (hasDrafts && existsSync(sanitisePath(config.draftsRoot, join('pages', toRelative)))) {
+        throw new MoveError('destination-exists', `A draft page already exists at "${toUrl}"`);
+    }
+    // Enumerate every affected page (the page itself, plus every
+    // descendant if it has any) before touching disk. This list drives
+    // both the redirect entries (E3: one per affected page) and the git
+    // staging list.
+    const affected = [
+        { oldRelativePath: fromRelative, newRelativePath: toRelative, oldUrl: fromUrl, newUrl: toUrl },
+    ];
+    if (fromDirExists) {
+        for (const rel of listFilesRecursively(fromDir, fromDir, '.json')) {
+            const oldRelativePath = join(fromDirRelative, rel);
+            const newRelativePath = join(toDirRelative, rel);
+            affected.push({
+                oldRelativePath,
+                newRelativePath,
+                oldUrl: pagePathToUrl(oldRelativePath),
+                newUrl: pagePathToUrl(newRelativePath),
+            });
+        }
+    }
+    const performedRenames = [];
+    // Files whose links were rewritten, with what they held before.
+    const rewrittenFiles = [];
+    let redirectsBefore = null;
+    let redirectsChanged = false;
+    // Reverses every rename (in reverse order) and restores/removes
+    // redirects.json. Attempts everything even if one step fails,
+    // reporting every failure - matches publish.ts's rollback()
+    // philosophy exactly (a filesystem cannot give a true atomicity
+    // guarantee, so the honest contract is "restores everything it can,
+    // and is loud if it can't").
+    function undoMoveWrites() {
+        const restoreFailures = [];
+        // Links first: they were rewritten after the renames, in the files'
+        // new places.
+        for (const rewritten of [...rewrittenFiles].reverse()) {
+            try {
+                writeFileSync(rewritten.file, rewritten.before);
+            }
+            catch (restoreError) {
+                restoreFailures.push(restoreError);
+            }
+        }
+        for (const rename of [...performedRenames].reverse()) {
+            try {
+                renameSync(rename.to, rename.from);
+            }
+            catch (restoreError) {
+                restoreFailures.push(restoreError);
+            }
+        }
+        if (redirectsChanged) {
+            try {
+                if (redirectsBefore === null) {
+                    rmSync(config.redirectsPath, { force: true });
+                }
+                else {
+                    writeFileSync(config.redirectsPath, redirectsBefore);
+                }
+            }
+            catch (restoreError) {
+                restoreFailures.push(restoreError);
+            }
+        }
+        return restoreFailures;
+    }
+    try {
+        mkdirSync(dirname(toPageFile), { recursive: true });
+        renameSync(fromPageFile, toPageFile);
+        performedRenames.push({ from: fromPageFile, to: toPageFile });
+        if (fromDirExists) {
+            mkdirSync(dirname(toDir), { recursive: true });
+            renameSync(fromDir, toDir);
+            performedRenames.push({ from: fromDir, to: toDir });
+        }
+        // Each affected page's draft moves with it: left behind, it became
+        // a draft-only page at the old address (found while adding link
+        // rewriting). Drafts aren't committed, so they're renamed but never
+        // staged; undo still puts them back.
+        for (const page of hasDrafts ? affected : []) {
+            const draftFrom = sanitisePath(config.draftsRoot, join('pages', page.oldRelativePath));
+            if (existsSync(draftFrom)) {
+                const draftTo = sanitisePath(config.draftsRoot, join('pages', page.newRelativePath));
+                mkdirSync(dirname(draftTo), { recursive: true });
+                renameSync(draftFrom, draftTo);
+                performedRenames.push({ from: draftFrom, to: draftTo });
+            }
+        }
+        redirectsBefore = existsSync(config.redirectsPath)
+            ? readFileSync(config.redirectsPath, 'utf-8')
+            : null;
+        let entries = loadRedirects(config).entries;
+        for (const page of affected) {
+            // E5 (move half) must run BEFORE addRedirect, not after: if the
+            // destination held a stale redirect (page.newUrl was itself a
+            // key), addRedirect's chain-walk would otherwise treat it as a
+            // legitimate hop and silently collapse straight through it,
+            // rather than the new page superseding it.
+            entries = removeRedirectForPath(entries, page.newUrl);
+            if (createRedirect) {
+                entries = addRedirect(entries, page.oldUrl, page.newUrl).entries;
+            }
+        }
+        const redirectsAfter = serialiseRedirects(entries);
+        if (redirectsAfter !== (redirectsBefore ?? '')) {
+            writeFileSync(config.redirectsPath, redirectsAfter);
+            redirectsChanged = true;
+        }
+        // Every link to the moved page (or a page under it) now points at
+        // its new address - in live pages, drafts, menus and the site
+        // settings - in this same commit, so links never lean on the
+        // redirect above. The redirect stays for links from elsewhere.
+        for (const source of linkSources(config)) {
+            const before = readFileSync(source.file, 'utf-8');
+            let parsed;
+            try {
+                parsed = JSON.parse(before);
+            }
+            catch {
+                continue;
+            }
+            const rewritten = rewriteLinks(parsed, fromUrl, toUrl);
+            if (!rewritten.changed) {
+                continue;
+            }
+            writeFileSync(source.file, `${JSON.stringify(rewritten.value, null, 2)}${before.endsWith('\n') ? '\n' : ''}`);
+            rewrittenFiles.push({ file: source.file, before, commit: source.kind !== 'draft' });
+        }
+    }
+    catch (error) {
+        // A write-phase failure: roll back immediately, inside prepare
+        // itself, and always classify as write-failed - commitPaths hasn't
+        // been called yet, so this can never be a GitOperationError.
+        const failures = undoMoveWrites();
+        if (failures.length > 0) {
+            throw new MoveError('rollback-failed', 'Move failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: error });
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new MoveError('write-failed', `Move failed: ${detail}`, { cause: error });
+    }
+    const paths = [];
+    for (const page of affected) {
+        paths.push(sanitisePath(config.pagesRoot, page.oldRelativePath));
+        paths.push(sanitisePath(config.pagesRoot, page.newRelativePath));
+    }
+    if (redirectsChanged) {
+        paths.push(config.redirectsPath);
+    }
+    // Drafts are never committed; everything else rewritten is.
+    for (const rewritten of rewrittenFiles) {
+        if (rewritten.commit && !paths.includes(rewritten.file)) {
+            paths.push(rewritten.file);
+        }
+    }
+    return { paths, undo: undoMoveWrites };
+}
+async function movePageJob(config, fromUrl, toUrl, message, author, options = {}) {
+    const { paths, undo } = prepareMovePage(config, fromUrl, toUrl, options);
+    try {
+        commitPaths(config.siteRoot, paths, message, author);
+    }
+    catch (error) {
+        const failures = undo();
+        if (failures.length > 0) {
+            throw new MoveError('rollback-failed', 'Move failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: error });
+        }
+        // Always commit-failed here, structurally: prepare already
+        // succeeded, so anything caught in this try can only have come
+        // from commitPaths itself.
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new MoveError('commit-failed', `Move failed: ${detail}`, { cause: error });
+    }
+}
+export function movePage(config, fromUrl, toUrl, message, author, options = {}) {
+    const result = enqueue(() => movePageJob(config, fromUrl, toUrl, message, author, options));
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
+}

package/dist/services/path-safety.d.ts

@@ -0,0 +1,6 @@
+export type PathSafetyReason = 'absolute-path' | 'traversal-segment' | 'malformed-encoding' | 'outside-root' | 'resolves-to-root' | 'symlink-escape' | 'invalid-path';
+export declare class PathSafetyError extends Error {
+    readonly reason: PathSafetyReason;
+    constructor(reason: PathSafetyReason, message: string);
+}
+export declare function sanitisePath(root: string, requestedPath: string): string;

package/dist/services/path-safety.js

@@ -0,0 +1,112 @@
+import { realpathSync } from 'node:fs';
+import { dirname, isAbsolute, resolve, sep } from 'node:path';
+export class PathSafetyError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'PathSafetyError';
+        this.reason = reason;
+    }
+}
+function isWithin(root, candidate) {
+    return candidate === root || candidate.startsWith(root + sep);
+}
+// Only existing path segments can be symlinks, so for a target that
+// doesn't exist yet (e.g. a new draft being written for the first time)
+// it is sufficient to realpath the nearest existing ancestor and confirm
+// that stays within the root; segments that don't exist can't smuggle a
+// symlink escape.
+function realpathOfNearestExisting(candidate) {
+    let current = candidate;
+    for (;;) {
+        try {
+            return realpathSync(current);
+        }
+        catch (error) {
+            const code = error.code;
+            // ENOENT/ENOTDIR mean only "this segment doesn't exist yet" -
+            // walk up to the nearest ancestor that does, per this function's
+            // own doc comment. Any other failure (ENAMETOOLONG for an
+            // over-length segment, ERR_INVALID_ARG_VALUE for an embedded null
+            // byte, etc. - verified empirically, not an exhaustive enum by
+            // design) means the path itself is malformed, not merely absent.
+            // Rejecting it here as a PathSafetyError is required, not
+            // optional: left as a raw rethrow, it would escape every route
+            // handler's `instanceof PathSafetyError` check and surface as an
+            // unsanitised 500, the exact failure mode this file exists to
+            // prevent (CLAUDE.md's #1 security concern).
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw new PathSafetyError('invalid-path', `Path could not be resolved: "${candidate}"`);
+            }
+            const parent = dirname(current);
+            if (parent === current) {
+                throw new PathSafetyError('invalid-path', `Path could not be resolved: "${candidate}"`);
+            }
+            current = parent;
+        }
+    }
+}
+// The single shared path-sanitisation helper. Every fs-touching code
+// path that handles a request-supplied :path parameter must resolve it
+// through this function before touching disk (enforced by a grep test,
+// see test/static/static-analysis.test.ts).
+export function sanitisePath(root, requestedPath) {
+    const normalisedRoot = resolve(root);
+    // Step 1: reject a raw absolute path before any decoding.
+    if (isAbsolute(requestedPath)) {
+        throw new PathSafetyError('absolute-path', `Path must be relative, got "${requestedPath}"`);
+    }
+    // Step 2: percent-decode. Decoding before splitting into segments (not
+    // decoding each segment independently) is what's actually required to
+    // catch an encoded slash disguising a segment boundary, e.g.
+    // "a%2f..%2fetc" decodes to "a/../etc" and is then caught by the
+    // segment scan below; decoding per-segment would miss it. Malformed
+    // encoding is rejected outright rather than passed through: this will
+    // also reject a benign filename containing a literal unencoded "%",
+    // which is an acceptable reject-on-ambiguity trade-off, not a bug.
+    let decoded;
+    try {
+        decoded = decodeURIComponent(requestedPath);
+    }
+    catch {
+        throw new PathSafetyError('malformed-encoding', `Path contains malformed percent-encoding: "${requestedPath}"`);
+    }
+    // Step 3: an encoded absolute path (e.g. "%2fetc%2fpasswd") doesn't
+    // look absolute in raw form, so check again after decoding.
+    if (isAbsolute(decoded)) {
+        throw new PathSafetyError('absolute-path', `Path must be relative, got "${requestedPath}"`);
+    }
+    // Step 4: reject any ".." segment, covering both plain and encoded
+    // traversal now that decoding has already happened.
+    if (decoded.split('/').includes('..')) {
+        throw new PathSafetyError('traversal-segment', `Path must not contain ".." segments: "${requestedPath}"`);
+    }
+    // Step 5: string-only containment check, still no fs call.
+    const resolved = resolve(normalisedRoot, decoded);
+    if (!isWithin(normalisedRoot, resolved)) {
+        throw new PathSafetyError('outside-root', `Path resolves outside the allowed root: "${requestedPath}"`);
+    }
+    // Step 6: deliberate hardening beyond the literal B3-B6 wording. A
+    // request that resolves to exactly the root (e.g. "", ".") must not be
+    // handed to a caller expecting a single file path.
+    if (resolved === normalisedRoot) {
+        throw new PathSafetyError('resolves-to-root', `Path must not resolve to the root itself: "${requestedPath}"`);
+    }
+    // Step 7: only now touch the filesystem, to catch a symlink inside the
+    // tree pointing outside the root.
+    const realRoot = realpathSync(normalisedRoot);
+    const realResolved = realpathOfNearestExisting(resolved);
+    if (!isWithin(realRoot, realResolved)) {
+        throw new PathSafetyError('symlink-escape', `Path escapes the allowed root via a symlink: "${requestedPath}"`);
+    }
+    // Accepted residual risk, not a structural gap: the symlink check
+    // above and the fs operation a caller performs with the returned
+    // path are not atomic, so a symlink swapped in between could in
+    // principle slip through (TOCTOU). Given the actual threat model -
+    // a single-operator site, all writes serialised through one queue,
+    // no concurrent untrusted filesystem access - this is low realistic
+    // risk. Flagged by plan-reviewer's Phase 1 audit; noted rather than
+    // solved, the same way other accepted trade-offs in this codebase
+    // are (see publish.ts's rollback() comment).
+    return resolved;
+}

package/dist/services/pid-file.d.ts

@@ -0,0 +1,13 @@
+import type { SiteConfig } from '../config.ts';
+export interface PidRecord {
+    pid: number;
+    serverPid: number;
+    port: number;
+    startedAt: string;
+}
+export declare function pidFilePath(config: SiteConfig): string;
+export declare function writePidFile(config: SiteConfig, port: number): void;
+export declare function readPidFile(config: SiteConfig): PidRecord | null;
+export declare function removeOwnPidFile(config: SiteConfig): void;
+export declare function removePidFile(config: SiteConfig): void;
+export declare function isProcessAlive(pid: number): boolean;

package/dist/services/pid-file.js

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function pidFilePath(config) {
+    return join(config.dataRoot, 'server.pid');
+}
+// Node sets WATCH_REPORT_DEPENDENCIES in the child it runs under
+// --watch, whose parent is then the watcher itself.
+function stopTarget() {
+    return process.env.WATCH_REPORT_DEPENDENCIES ? process.ppid : process.pid;
+}
+export function writePidFile(config, port) {
+    const record = { pid: stopTarget(), serverPid: process.pid, port, startedAt: new Date().toISOString() };
+    mkdirSync(config.dataRoot, { recursive: true });
+    writeFileSync(pidFilePath(config), `${JSON.stringify(record, null, 2)}\n`);
+}
+export function readPidFile(config) {
+    try {
+        const parsed = JSON.parse(readFileSync(pidFilePath(config), 'utf-8'));
+        const { pid, serverPid, port, startedAt } = parsed;
+        if (typeof pid !== 'number' ||
+            typeof serverPid !== 'number' ||
+            typeof port !== 'number' ||
+            typeof startedAt !== 'string') {
+            return null;
+        }
+        return { pid, serverPid, port, startedAt };
+    }
+    catch {
+        return null;
+    }
+}
+// Only removes the file if it is still this process's own record: under
+// `npm run dev` the watcher starts a new process on a theme change, and
+// the old one shutting down must not delete the record the new one has
+// just written.
+export function removeOwnPidFile(config) {
+    if (readPidFile(config)?.serverPid === process.pid) {
+        removePidFile(config);
+    }
+}
+export function removePidFile(config) {
+    rmSync(pidFilePath(config), { force: true });
+}
+// Whether a process with this id exists. EPERM means it does, but
+// belongs to another user.
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && 'code' in error && error.code === 'EPERM';
+    }
+}

package/dist/services/post-urls.d.ts

@@ -0,0 +1,3 @@
+export declare function isBlogUrl(url: string): boolean;
+export declare function urlToPostPath(url: string): string | null;
+export declare function postPathToUrl(relativePostPath: string): string;