@minamocms/framework 0.0.0-stage → 0.10.2

package/dist/server.js

@@ -0,0 +1,235 @@
+import rateLimitPlugin from '@fastify/rate-limit';
+import Fastify, {} from 'fastify';
+import { bootSite } from "./boot.js";
+import { loadServerConfig } from "./server-config.js";
+import { adminRedirectRoutes } from "./routes/admin-redirect.js";
+import { assetsRoutes } from "./routes/assets.js";
+import { v1Routes } from "./routes/index.js";
+import { mediaPublicRoutes } from "./routes/media-public.js";
+import { publicRoutes } from "./routes/public.js";
+import { searchPublicRoutes } from "./routes/search-public.js";
+import { sitemapRoutes } from "./routes/sitemap.js";
+import { CHECKPOINT_AUTHOR, runCheckpoint } from "./services/checkpoint.js";
+import { startDevTunnel } from "./services/dev-tunnel.js";
+import { startIntervalJob } from "./services/interval-job.js";
+import { reindexOnBootIfMissing } from "./services/reindex-on-write.js";
+import { isProcessAlive, readPidFile, removeOwnPidFile, writePidFile } from "./services/pid-file.js";
+// Never wrap v1Routes (or any route-group plugin it registers) with
+// fastify-plugin (fp()): plain app.register() gives each file its own
+// encapsulation scope by default, which Group B's auth preHandler
+// hooks depend on. Wrapping would silently hoist decorators/hooks to
+// the parent scope and break that later.
+export function buildServer(booted, serverConfig, options = {}) {
+    const app = Fastify({ logger: options.logger ?? false, trustProxy: serverConfig.trustProxy });
+    // global: false - only routes that explicitly opt in via a
+    // config: { rateLimit: {...} } marker on their own route options
+    // (see src/services/rate-limit-config.ts) are ever limited. The
+    // max/timeWindow set here are the configured (or defaulted)
+    // site.config.json values - an opting-in route's own empty
+    // { rateLimit: {} } marker inherits these, verified empirically.
+    // Registered once here, on the root app (an ancestor of v1Routes and
+    // everything it nests), so no individual route file needs to import
+    // this plugin itself. Its own 429 response body shape
+    // ({statusCode, error, message}) already matches this project's own
+    // error-JSON convention exactly - verified empirically before relying
+    // on it, no errorResponseBuilder override needed.
+    app.register(rateLimitPlugin, {
+        global: false,
+        max: serverConfig.rateLimit.max,
+        timeWindow: serverConfig.rateLimit.windowMs,
+    });
+    // Fastify's own default 500 body leaks the raw thrown Error.message
+    // to the client verbatim - confirmed empirically before this was
+    // written. Anything below 500 (e.g. a future route's schema-
+    // validation failure) already carries a safe, specific message and
+    // is passed through unchanged; only 500-and-above gets sanitised.
+    app.setErrorHandler((error, request, reply) => {
+        const statusCode = error.statusCode ?? 500;
+        if (statusCode >= 500) {
+            request.log.error(error);
+            reply.code(statusCode).send({
+                statusCode,
+                error: 'Internal Server Error',
+                message: 'Internal Server Error',
+            });
+            return;
+        }
+        reply.code(statusCode).send({ statusCode, error: error.name || 'Bad Request', message: error.message });
+    });
+    app.register(v1Routes, {
+        prefix: '/v1',
+        config: booted.config,
+        theme: booted.theme,
+        tokens: serverConfig.tokens,
+        ipAllowlist: serverConfig.ipAllowlist,
+        maxUploadBytes: serverConfig.media.maxUploadBytes,
+    });
+    // Registered without a /v1 prefix, alongside v1Routes: this is the
+    // site's own public website, not part of the site agent API. Order
+    // relative to v1Routes is not load-bearing - Fastify's router
+    // prefers exact/prefixed matches over this route's wildcard
+    // regardless of registration order (verified empirically). What
+    // actually protects unmatched /v1/* paths from being swallowed as
+    // page lookups is the explicit guard inside publicRoutes itself.
+    app.register(publicRoutes, {
+        config: booted.config,
+        theme: booted.theme,
+        renderCache: booted.renderCache,
+    });
+    // A more specific static-prefixed route than the public catch-all's
+    // own /* wildcard - Fastify prefers it regardless of registration
+    // order (verified empirically), so no guard is needed here the way
+    // publicRoutes needs one against /v1/*.
+    app.register(assetsRoutes, { config: booted.config });
+    // Same "more specific than the public catch-all" reasoning as
+    // assetsRoutes above. Deliberately not registered inside v1Routes
+    // (media.ts's own authenticated /v1/media CRUD routes are what live
+    // there) - this is the public, unauthenticated read side, matching
+    // assetsRoutes/publicRoutes' own placement.
+    //
+    // @fastify/multipart itself is NOT registered here, only inside
+    // media.ts's own plugin scope - see that file's comment for why
+    // (confining it to media routes only, leaving every other route
+    // file's default JSON body parsing untouched).
+    app.register(mediaPublicRoutes, { config: booted.config });
+    // Same "more specific than the public catch-all" reasoning again -
+    // this exact path always wins over publicRoutes' /* wildcard, and
+    // also always wins over a same-named static file under
+    // theme/root/sitemap.xml (see routes/public.ts's root-mirror check).
+    app.register(sitemapRoutes, { config: booted.config });
+    // Same "more specific than the public catch-all" reasoning again - a
+    // stable, public, front-end-facing contract (a theme's own JS calls
+    // it directly), not part of the versioned /v1 admin/integration
+    // surface, so it lives alongside these other unprefixed routes
+    // rather than inside v1Routes (search.ts's /v1/search/rebuild is the
+    // authenticated write side that does). GET /search.json, not
+    // GET /search: a single reserved path, not a whole prefix, so a
+    // site's own content page can still live at the bare /search URL
+    // (granite-starter's search-demo section does exactly that).
+    app.register(searchPublicRoutes, { config: booted.config });
+    // Conditional, unlike every other registration above - this is what
+    // makes GET /admin genuinely opt-in rather than a reserved
+    // namespace: with no adminBaseUrl configured, the route is never
+    // registered at all, so an unconfigured site can still use "admin"
+    // as an ordinary page path. See routes/admin-redirect.ts's own
+    // comment for the full reasoning.
+    if (serverConfig.adminBaseUrl) {
+        app.register(adminRedirectRoutes, { adminBaseUrl: serverConfig.adminBaseUrl });
+    }
+    return app;
+}
+// Neither a recurring timer nor process signal handling exists
+// anywhere else in this codebase - this is genuinely new machinery for
+// the low-frequency draft-checkpoint background job (checklist H4).
+// Wired only here, never in buildServer: every existing route test
+// uses buildServer + .inject() directly and must stay completely
+// unaffected by any of this.
+export async function startServer(siteRoot, options = {}) {
+    const booted = bootSite(siteRoot);
+    const serverConfig = loadServerConfig(siteRoot);
+    const app = buildServer(booted, serverConfig, options);
+    // Previously these three failure cases (missing/invalid {% schema %}
+    // block, or a required property with no valid default) were
+    // completely silent - a broken component just stopped being
+    // selectable, with nothing distinguishing "deliberately excluded"
+    // from "you have a typo". Never a boot failure (loadThemeSchemas's
+    // own contract), just no longer silent about it either.
+    for (const warning of booted.themeSchemas.warnings ?? []) {
+        console.warn(warning);
+    }
+    const doCheckpoint = () => runCheckpoint(booted.config, CHECKPOINT_AUTHOR);
+    const scheduler = startIntervalJob(doCheckpoint, serverConfig.checkpointIntervalMs, (error) => {
+        app.log.error(error, 'background draft checkpoint failed');
+    });
+    let tunnel;
+    // Node's default action for an unhandled SIGTERM/SIGINT is immediate
+    // process termination, bypassing all JS-level cleanup - without
+    // this, a real kill/Ctrl-C would never run the final checkpoint
+    // (build plan: "and on graceful shutdown"). process.once (not .on)
+    // self-removes after firing, and is explicitly removed again inside
+    // onClose below, so a test calling app.close() leaves zero global
+    // process-level listeners behind across the many startServer/
+    // buildServer calls the suite makes.
+    const shutdown = () => {
+        app.close().catch((error) => app.log.error(error, 'error during shutdown'));
+    };
+    process.once('SIGTERM', shutdown);
+    process.once('SIGINT', shutdown);
+    app.addHook('onClose', async () => {
+        tunnel?.close();
+        scheduler.stop();
+        process.removeListener('SIGTERM', shutdown);
+        process.removeListener('SIGINT', shutdown);
+        removeOwnPidFile(booted.config);
+        try {
+            await doCheckpoint();
+        }
+        catch (error) {
+            app.log.error(error, 'final draft checkpoint on shutdown failed');
+        }
+    });
+    // host: '0.0.0.0' - Fastify's own default binds 127.0.0.1 only,
+    // which is unreachable from outside any container or remote host.
+    try {
+        await app.listen({ port: serverConfig.port, host: '0.0.0.0' });
+    }
+    catch (error) {
+        // A raw EADDRINUSE crash is a wall of Node internals with no
+        // indication of what to actually do about it. This is the single
+        // most likely startup failure a developer hits on their own
+        // machine (something else already using the default port) - tell
+        // them the two real ways to pick a different one instead of
+        // rethrowing Node's own stack trace.
+        if (error instanceof Error && 'code' in error && error.code === 'EADDRINUSE') {
+            // Most often it's this same site, started earlier in another
+            // terminal - say so, and how to stop it from this one.
+            const running = readPidFile(booted.config);
+            if (running && running.port === serverConfig.port && running.pid !== process.pid && isProcessAlive(running.pid)) {
+                console.error(`This site is already running on port ${serverConfig.port} (process ${running.pid}).`);
+                console.error('Stop it with "npm run stop" from vhost/, then start it again.');
+                process.exit(1);
+            }
+            console.error(`Port ${serverConfig.port} is already in use.`);
+            console.error(`Set a different port with the PORT environment variable (e.g. PORT=3001 node server.js), or "port" in vhost/site.config.json.`);
+            process.exit(1);
+        }
+        throw error;
+    }
+    // The real bound port, not just serverConfig.port verbatim - the
+    // same reasoning tests already rely on (app.server.address()):
+    // port 0 means "OS picks a free one", so echoing the configured
+    // value back would print a meaningless 0 in that case. 127.0.0.1,
+    // not the 0.0.0.0 bind host above - that's what's actually
+    // reachable and clickable from the machine running this.
+    const address = app.server.address();
+    if (address !== null && typeof address !== 'string') {
+        console.log(`Site running at http://127.0.0.1:${address.port}`);
+        // Recorded only once the port is really bound, so a start that
+        // fails never leaves a record of a site that isn't running.
+        writePidFile(booted.config, address.port);
+    }
+    // A search index is never git-tracked (constraint 3), so a fresh
+    // clone or first-ever boot has no index file - without this,
+    // GET /search.json would stay empty until the first content write.
+    // Fire-and-forget, after the port is already bound: never blocks
+    // startup, and a slow/failed rebuild is never a reason the server
+    // itself fails to come up.
+    reindexOnBootIfMissing(booted.config);
+    if (options.tunnel) {
+        try {
+            tunnel = await (options.startTunnel ?? startDevTunnel)(serverConfig.port);
+            console.log(`Tunnel open: ${tunnel.url}`);
+            console.log('This URL is publicly reachable for as long as this process runs - anyone with it (and a valid access token) can reach this site. Do not leave it running unattended.');
+        }
+        catch (error) {
+            // The site itself is already up and correctly serving locally -
+            // a failed tunnel is not a reason to fail the whole boot.
+            app.log.error(error, 'failed to start dev tunnel');
+            console.error('Failed to start the dev tunnel - the site is still running locally.');
+        }
+    }
+    else {
+        console.log('Tip: run with --tunnel to expose this site publicly for testing against a hosted admin.');
+    }
+    return app;
+}

package/dist/services/batch.d.ts

@@ -0,0 +1,35 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+import type { ThemeSchemas } from './validation.ts';
+export type BatchOperation = {
+    type: 'draft-write';
+    path: string;
+    content: unknown;
+    expectedEtag: string;
+} | {
+    type: 'draft-discard';
+    path: string;
+} | {
+    type: 'content-delete';
+    path: string;
+    redirectTo?: string;
+} | {
+    type: 'move';
+    from: string;
+    to: string;
+};
+export interface BatchPublish {
+    relativePaths: string[];
+}
+export type BatchReason = 'validation-failed' | 'conflict' | 'page-not-found' | 'has-children' | 'redirect-cycle' | 'invalid-redirect-target' | 'source-not-found' | 'destination-exists' | 'draft-not-found' | 'duplicate-path' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class BatchError extends Error {
+    readonly reason: BatchReason;
+    readonly stage?: 'operation' | 'publish';
+    readonly operationIndex?: number;
+    constructor(reason: BatchReason, message: string, options?: {
+        cause?: unknown;
+        stage?: 'operation' | 'publish';
+        operationIndex?: number;
+    });
+}
+export declare function runBatch(config: SiteConfig, themeSchemas: ThemeSchemas, operations: BatchOperation[], publish: BatchPublish | undefined, message: string, author: CommitAuthor): Promise<void>;

package/dist/services/batch.js

@@ -0,0 +1,145 @@
+import { DraftError, prepareDiscardDraft, prepareSaveDraft } from "./drafts.js";
+import { DeleteContentError, prepareDeleteContent } from "./delete-content.js";
+import { commitPaths } from "./git.js";
+import { MoveError, prepareMovePage } from "./move.js";
+import { PublishError, preparePublishDrafts } from "./publish.js";
+import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
+export class BatchError extends Error {
+    reason;
+    // Which part of the batch failed. operationIndex indexes into the
+    // operations array; the trailing publish step is a distinct stage,
+    // not folded into that same index space (index 3 could otherwise
+    // ambiguously mean "the 4th operation" or "there were only 3
+    // operations, so this must be publish").
+    stage;
+    operationIndex;
+    constructor(reason, message, options) {
+        super(message, { cause: options?.cause });
+        this.name = 'BatchError';
+        this.reason = reason;
+        this.stage = options?.stage;
+        this.operationIndex = options?.operationIndex;
+    }
+}
+// No whole-batch duplicate-path pre-check: rejected in design review.
+// publishDrafts's own internal duplicate check exists because its
+// rollback restores multiple snapshots in *forward* order within a
+// single call - a real hazard specific to that shape. Undo across
+// batch *operations* runs in *reverse* chronological order instead
+// (see batchJob below), which composes correctly even when multiple
+// operations touch the same path (e.g. move A->B then content-delete
+// B in the same batch unwinds correctly: undo delete restores B to
+// what move wrote, then undo move renames B back to A). Genuine
+// conflicts (two moves to the same destination, etc.) are already
+// caught fresh by each sub-service's own real-time validation when it
+// runs, precisely because processing is sequential.
+async function runOperation(config, themeSchemas, operation) {
+    switch (operation.type) {
+        case 'draft-write':
+            return prepareSaveDraft(config, themeSchemas, operation.path, operation.content, operation.expectedEtag);
+        case 'draft-discard':
+            return prepareDiscardDraft(config, operation.path);
+        case 'content-delete':
+            return prepareDeleteContent(config, operation.path, operation.redirectTo);
+        case 'move':
+            return prepareMovePage(config, operation.from, operation.to);
+    }
+}
+function reasonFromError(error) {
+    if (error instanceof DraftError ||
+        error instanceof DeleteContentError ||
+        error instanceof MoveError ||
+        error instanceof PublishError) {
+        return error.reason;
+    }
+    return undefined;
+}
+async function batchJob(config, themeSchemas, operations, publish, message, author) {
+    const allPaths = [];
+    const undoStack = [];
+    // Sequential, not two-phase validate-then-write: operations can be
+    // order-dependent within a single batch (e.g. write a draft, then
+    // publish that same draft, in one call) - a later step's validation
+    // may depend on an earlier step's write having already happened.
+    for (let index = 0; index < operations.length; index++) {
+        const operation = operations[index];
+        try {
+            const prepared = await runOperation(config, themeSchemas, operation);
+            allPaths.push(...prepared.paths);
+            undoStack.push(prepared.undo);
+        }
+        catch (error) {
+            await rollbackAndThrow(undoStack, error, { stage: 'operation', operationIndex: index });
+        }
+    }
+    if (publish) {
+        try {
+            const prepared = preparePublishDrafts(config, themeSchemas, publish.relativePaths);
+            allPaths.push(...prepared.paths);
+            undoStack.push(prepared.undo);
+        }
+        catch (error) {
+            await rollbackAndThrow(undoStack, error, { stage: 'publish' });
+        }
+    }
+    // A batch of pure draft-write/draft-discard operations legitimately
+    // produces zero git-tracked paths (drafts are never git-tracked).
+    // git commit with nothing staged exits non-zero ("nothing to
+    // commit") - verified empirically - which would otherwise produce a
+    // spurious commit-failed (or a spurious full rollback) for a batch
+    // that did nothing wrong. Skip the commit entirely when there is
+    // nothing to stage.
+    if (allPaths.length === 0) {
+        return;
+    }
+    try {
+        commitPaths(config.siteRoot, allPaths, message, author);
+    }
+    catch (error) {
+        await rollbackAndThrow(undoStack, error, {});
+    }
+}
+// Runs every already-succeeded operation's undo, in reverse order,
+// then throws. Never returns normally - always throws either
+// BatchError('rollback-failed') (if any undo itself failed) or a
+// BatchError carrying the original failure's own reason.
+async function rollbackAndThrow(undoStack, cause, context) {
+    const failures = [];
+    for (const undo of [...undoStack].reverse()) {
+        failures.push(...undo());
+    }
+    if (failures.length > 0) {
+        throw new BatchError('rollback-failed', 'Batch failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause, ...context });
+    }
+    const reason = reasonFromError(cause);
+    if (reason) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        throw new BatchError(reason, `Batch failed: ${detail}`, { cause, ...context });
+    }
+    // context.stage is only ever set when this was called from the
+    // operations/publish loop, never from the post-loop commitPaths call
+    // below - so a non-domain error reaching here (e.g. PathSafetyError
+    // thrown by sanitisePath deep inside a prepareX function) came from
+    // there too. Rethrow it as-is rather than mislabelling it
+    // 'commit-failed': callers up the stack (the route's own
+    // PathSafetyError check) need to see the original error type.
+    if (context.stage) {
+        throw cause;
+    }
+    // No stage means this can only have come from the commitPaths call
+    // just above, which only ever throws GitOperationError.
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new BatchError('commit-failed', `Batch failed: ${detail}`, { cause, ...context });
+}
+export function runBatch(config, themeSchemas, operations, publish, message, author) {
+    const result = enqueue(() => batchJob(config, themeSchemas, operations, publish, message, author));
+    // One trigger for the whole batch, regardless of which operation
+    // types it contained (content-delete/move/publish affect the index,
+    // draft-write/draft-discard don't) - simpler and no real cost than
+    // inspecting `operations` to decide, since this never blocks the
+    // caller either way. See reindex-on-write.ts for why this is
+    // fire-and-forget, chained onto `result` rather than awaited here.
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
+}

package/dist/services/checkpoint.d.ts

@@ -0,0 +1,4 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+export declare const CHECKPOINT_AUTHOR: CommitAuthor;
+export declare function runCheckpoint(config: SiteConfig, author: CommitAuthor): Promise<'committed' | 'clean'>;

package/dist/services/checkpoint.js

@@ -0,0 +1,45 @@
+import { execFileSync } from 'node:child_process';
+import { relative } from 'node:path';
+import { CHECKPOINT_MESSAGE } from "./git-history.js";
+import { commitPaths } from "./git.js";
+import { enqueue } from "./write-queue.js";
+// Resolves the checklist's own carried-forward open question 3: the
+// same shape of question boot.ts already declined to answer for
+// boot-time migrations. A fixed, hardcoded in-code identity - not
+// configurable per-site - so this never depends on host config
+// (matching the Phase 1 sign-off that commits never fall back to
+// ~/.gitconfig), and there's zero possibility of a site operator
+// misconfiguring or omitting it.
+export const CHECKPOINT_AUTHOR = { name: 'Minamo', email: 'minamo@localhost' };
+async function checkpointJob(config, author) {
+    // Derived from config.draftsRoot, never a hardcoded literal - Group N
+    // nested draftsRoot inside contentRoot (content/drafts), so a fixed
+    // 'drafts' pathspec would silently match nothing there, making this
+    // checkpoint a permanent no-op with zero error output. Always
+    // relative to siteRoot, matching commitPaths'/git status's own
+    // pathspec convention below.
+    const draftsPathspec = relative(config.siteRoot, config.draftsRoot);
+    // "When drafts have changed" (checklist H4) - checked before ever
+    // staging/committing, matching the empty-commit lesson batch.ts and
+    // git-revert.ts already learned: git commit with nothing staged
+    // exits non-zero, which must not surface as a spurious failure for
+    // a checkpoint tick that legitimately had nothing to do.
+    const status = execFileSync('git', ['status', '--porcelain', '--', draftsPathspec], {
+        cwd: config.siteRoot,
+    }).toString('utf-8');
+    if (status.trim().length === 0) {
+        return 'clean';
+    }
+    // Reuses commitPaths (not commitWorkingTree, which stages the
+    // *entire* working tree) - scoped to a single drafts-directory
+    // pathspec. Verified empirically that a bare pathspec (no -A flag)
+    // correctly stages both modifications and deletions under that
+    // directory, essential since a discarded draft (a pure fs removal
+    // today, no git call) must be captured by the next checkpoint as a
+    // real change, not silently missed.
+    commitPaths(config.siteRoot, [draftsPathspec], CHECKPOINT_MESSAGE, author);
+    return 'committed';
+}
+export function runCheckpoint(config, author) {
+    return enqueue(() => checkpointJob(config, author));
+}

package/dist/services/content-read.d.ts

@@ -0,0 +1,27 @@
+import type { SiteConfig } from '../config.ts';
+export type ContentReadReason = 'not-found';
+export declare class ContentReadError extends Error {
+    readonly reason: ContentReadReason;
+    constructor(reason: ContentReadReason, message: string);
+}
+export interface ReadResult {
+    bytes: Buffer;
+    etag: string;
+}
+export declare function readContentFile(root: string, relativePath: string): ReadResult;
+export interface ContentListFilters {
+    type?: string;
+    prefix?: string;
+    draftStatus?: 'has-draft' | 'no-draft';
+}
+export interface ContentListEntry {
+    path: string;
+    name: string;
+    title: string;
+    type: string;
+    published: boolean;
+    hasDraft: boolean;
+    url: string | null;
+    changedAt: string | null;
+}
+export declare function listContent(config: SiteConfig, filters: ContentListFilters): ContentListEntry[];

package/dist/services/content-read.js

@@ -0,0 +1,151 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { computeEtag } from "./etag.js";
+import { listFilesRecursively } from "./fs-walk.js";
+import { sanitisePath } from "./path-safety.js";
+import { pagePathToUrl } from "./urls.js";
+export class ContentReadError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'ContentReadError';
+        this.reason = reason;
+    }
+}
+// Shared by both content.ts (root = config.contentRoot) and drafts.ts
+// (root = config.draftsRoot) - identical read+hash logic, just a
+// different root. sanitisePath's PathSafetyError is left to propagate
+// uncaught: the route handlers catch it explicitly and map it to 404,
+// the same precedent preview.ts already established (PathSafetyError
+// has no .statusCode, so left uncaught it would fall through to the
+// global handler's generic sanitised 500).
+export function readContentFile(root, relativePath) {
+    const fullPath = sanitisePath(root, relativePath);
+    if (!existsSync(fullPath)) {
+        throw new ContentReadError('not-found', `No file at "${relativePath}"`);
+    }
+    const bytes = readFileSync(fullPath);
+    return { bytes, etag: computeEtag(bytes) };
+}
+// Both contentRoot-relative live paths and draftsRoot-relative draft
+// paths share the identical pages/menus subroot prefix shape
+// (content/drafts/ mirrors content/'s own layout), so one function
+// handles both with no branching on which root an entry came from.
+// Menus have no public URL - there is no preview route for them.
+function computeContentUrl(relativePath) {
+    if (relativePath.startsWith('pages/')) {
+        return pagePathToUrl(relativePath.slice('pages/'.length));
+    }
+    return null;
+}
+// The later of the live file's and the draft's own mtime, whichever
+// exist - a page with a pending draft edit should show that edit's
+// recency, not just whichever file readSummary happened to prefer.
+// File mtime, not a git commit date: a per-path git-log call for
+// every entry in a listing that can run to hundreds of pages isn't
+// viable, and mtime is a reasonable proxy for "last touched" - a
+// known, accepted imprecision (e.g. a fresh git clone/checkout can
+// reset it), not a claim of exact publish history (that's what the
+// page history view's own real git log is for).
+function latestMtime(candidatePaths) {
+    let latest = null;
+    for (const fullPath of candidatePaths) {
+        try {
+            const { mtime } = statSync(fullPath);
+            if (latest === null || mtime > latest) {
+                latest = mtime;
+            }
+        }
+        catch {
+            // A path that vanished between the directory walk and this stat
+            // (e.g. a concurrent delete) just doesn't contribute - not fatal
+            // to the rest of the listing.
+        }
+    }
+    return latest ? latest.toISOString() : null;
+}
+// Defensive, not the strict PageContent shape from render-page.ts:
+// boot.ts deliberately never auto-migrates content at startup, so a
+// file sitting at an old schemaVersion (and therefore missing a field
+// as new as "type") is a real, persistent possibility, not a
+// hypothetical - matching rebuild-index.ts's PageForIndex precedent.
+function readSummary(fullPath) {
+    try {
+        return JSON.parse(readFileSync(fullPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// GET /v1/content lists the union of contentRoot and draftsRoot paths,
+// not live content alone: Group D's own checklist heading is "content
+// AND draft reads", and there is no separate "list drafts" endpoint
+// anywhere in the build plan - this is the only place a draft-only
+// page (never yet published) is discoverable at all.
+//
+// Deliberately two named walks (pages/menus), not one broad walk of
+// contentRoot: since Group N nested draftsRoot and redirectsPath
+// inside contentRoot (content/drafts/, content/redirects.json), a
+// single broad contentRoot walk would descend into content/drafts/
+// too, double-listing draft files under two different relative-path
+// keys, and would pick up redirects.json as if it were a page. An
+// inclusion-based walk sidesteps both problems structurally, with no
+// exclusion list to maintain. base stays config.contentRoot for both
+// (not each subroot) so the resulting relative paths ("pages/x.json")
+// line up with draftPaths below for the hasDraft/hasLive union logic.
+export function listContent(config, filters) {
+    const contentPaths = new Set([
+        ...listFilesRecursively(config.pagesRoot, config.contentRoot, '.json'),
+        ...listFilesRecursively(config.menusRoot, config.contentRoot, '.json'),
+    ]);
+    const draftPaths = new Set(listFilesRecursively(config.draftsRoot, config.draftsRoot, '.json'));
+    const allPaths = new Set([...contentPaths, ...draftPaths]);
+    const entries = [];
+    for (const relativePath of allPaths) {
+        const hasDraft = draftPaths.has(relativePath);
+        const hasLive = contentPaths.has(relativePath);
+        // Prefer the live file's fields on conflict - the draft is a
+        // pending edit, not yet the source of truth for a content
+        // inventory view - but hasDraft still reports the draft's
+        // presence either way.
+        const summary = hasLive
+            ? readSummary(join(config.contentRoot, relativePath))
+            : readSummary(join(config.draftsRoot, relativePath));
+        if (!summary) {
+            continue;
+        }
+        const title = typeof summary.title === 'string' ? summary.title : '';
+        const entry = {
+            path: relativePath,
+            // Falls back to title, not '', for content written before "name"
+            // existed and not yet migrated (migrations aren't wired to run
+            // automatically) - the same default migrateV4ToV5 itself writes,
+            // just applied defensively at read time too.
+            name: typeof summary.name === 'string' ? summary.name : title,
+            title,
+            type: typeof summary.type === 'string' ? summary.type : '',
+            published: summary.published === true,
+            hasDraft,
+            url: computeContentUrl(relativePath),
+            changedAt: latestMtime([
+                ...(hasLive ? [join(config.contentRoot, relativePath)] : []),
+                ...(hasDraft ? [join(config.draftsRoot, relativePath)] : []),
+            ]),
+        };
+        if (filters.type !== undefined && entry.type !== filters.type) {
+            continue;
+        }
+        if (filters.prefix !== undefined && !entry.path.startsWith(filters.prefix)) {
+            continue;
+        }
+        if (filters.draftStatus === 'has-draft' && !entry.hasDraft) {
+            continue;
+        }
+        if (filters.draftStatus === 'no-draft' && entry.hasDraft) {
+            continue;
+        }
+        entries.push(entry);
+    }
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    return entries;
+}

package/dist/services/delete-content.d.ts

@@ -0,0 +1,12 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+import type { PreparedOperation } from './prepared-operation.ts';
+export type DeleteContentReason = 'page-not-found' | 'has-children' | 'redirect-cycle' | 'invalid-redirect-target' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class DeleteContentError extends Error {
+    readonly reason: DeleteContentReason;
+    constructor(reason: DeleteContentReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function prepareDeleteContent(config: SiteConfig, relativePath: string, redirectTo: string | undefined): PreparedOperation;
+export declare function deleteContent(config: SiteConfig, relativePath: string, redirectTo: string | undefined, message: string, author: CommitAuthor): Promise<void>;