@minamocms/framework 0.0.0-stage → 0.10.1

package/dist/services/git-history.js

@@ -0,0 +1,131 @@
+import { execFileSync } from 'node:child_process';
+import { relative } from 'node:path';
+import { isValidGitRef } from "./git.js";
+import { sanitisePath } from "./path-safety.js";
+const DEFAULT_LOG_LIMIT = 100;
+const MAX_LOG_LIMIT = 500;
+// Settled by the build plan itself (docs/cms-build-plan.md): the
+// future (not-yet-built) Group H checkpoint job commits drafts/ with
+// this literal message. Exact match only, deliberately not a prefix
+// match - migration-runner.ts's own automated commit
+// ("chore: migrate content to schema version N") is a different,
+// meaningful category and must not be flagged as checkpoint noise.
+// The checkpoint commit's *author identity* is a separate, still-open
+// question (docs/phase-2-checklist.md) this module does not attempt
+// to resolve - flagging is by message only.
+export const CHECKPOINT_MESSAGE = 'chore: draft checkpoint';
+const FIELD_SEP = '\x1f';
+const RECORD_SEP = '\x1e';
+export function getCommitLog(config, options) {
+    // A brand-new site's repo can exist (startup-checks.ts already
+    // verified it's a real work tree at boot) with zero commits until
+    // the first publish/checkpoint/manual commit ever happens. Plain
+    // `git log` on a HEAD-less repo exits non-zero ("does not have any
+    // commits yet"), which must not surface as an uncaught 500 for what
+    // is simply an empty history.
+    try {
+        execFileSync('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], {
+            cwd: config.siteRoot,
+            stdio: 'ignore',
+        });
+    }
+    catch {
+        return { commits: [], hasMore: false };
+    }
+    const limit = Math.min(Math.max(1, options.limit ?? DEFAULT_LOG_LIMIT), MAX_LOG_LIMIT);
+    const args = [
+        'log',
+        `--format=%H${FIELD_SEP}%an${FIELD_SEP}%ae${FIELD_SEP}%aI${FIELD_SEP}%B${RECORD_SEP}`,
+        '-n',
+        String(limit + 1),
+    ];
+    if (options.path) {
+        // A bare fs-pathspec (not the <rev>:<path> colon syntax
+        // readFileAtRevision below uses), so sanitisePath's absolute
+        // return value is used directly - git resolves an absolute
+        // pathspec fine, same as git.ts's own `git add -- <absolutePaths>`
+        // already relies on.
+        args.push('--', sanitisePath(config.siteRoot, options.path));
+    }
+    const raw = execFileSync('git', args, { cwd: config.siteRoot }).toString('utf-8');
+    const parsed = parseLogOutput(raw);
+    return { commits: parsed.slice(0, limit), hasMore: parsed.length > limit };
+}
+function parseLogOutput(raw) {
+    return raw
+        .split(RECORD_SEP)
+        // `--format=` is shorthand for `--pretty=tformat:`, which appends
+        // its own newline terminator after EVERY record, including after
+        // our own literal RECORD_SEP - that terminator lands as a leading
+        // "\n" on the *next* record, not a trailing one on the record it
+        // belongs to. Verified empirically against a real multi-commit
+        // repo (including a commit with an embedded multi-line message)
+        // before trusting this: without stripping it, every commit but the
+        // first silently fails to parse, since the leading \n corrupts the
+        // hash field.
+        .map((record) => record.replace(/^\n/, ''))
+        .filter((record) => record.length > 0)
+        .map((record) => {
+        const [hash, name, email, date, ...rest] = record.split(FIELD_SEP);
+        // Defensive rejoin: FIELD_SEP is "unlikely" to appear inside a
+        // real commit message, not impossible. If it ever does, this
+        // keeps the message intact rather than corrupting every field
+        // after it.
+        const message = rest.join(FIELD_SEP).trimEnd();
+        return {
+            hash: hash ?? '',
+            author: { name: name ?? '', email: email ?? '' },
+            date: date ?? '',
+            message,
+            isCheckpoint: message === CHECKPOINT_MESSAGE,
+        };
+    });
+}
+export class GitShowError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'GitShowError';
+        this.reason = reason;
+    }
+}
+export function readFileAtRevision(config, ref, relativePath) {
+    if (!isValidGitRef(ref)) {
+        throw new GitShowError('invalid-ref', `Invalid ref: "${ref}"`);
+    }
+    // The <rev>:<path> colon syntax below resolves <path> relative to
+    // cwd (config.siteRoot), never as a literal absolute filesystem path
+    // - unlike getCommitLog's `--` pathspec above. Re-deriving the
+    // repo-relative string from sanitisePath's own already-validated
+    // absolute result (not re-decoding relativePath a second time)
+    // guarantees the exact same string sanitisePath vetted.
+    const repoRelativePath = relative(config.siteRoot, sanitisePath(config.siteRoot, relativePath));
+    try {
+        execFileSync('git', ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {
+            cwd: config.siteRoot,
+            stdio: 'ignore',
+        });
+    }
+    catch {
+        throw new GitShowError('invalid-ref', `Ref does not resolve to a commit: "${ref}"`);
+    }
+    let objectType;
+    try {
+        objectType = execFileSync('git', ['cat-file', '-t', `${ref}:${repoRelativePath}`], {
+            cwd: config.siteRoot,
+        })
+            .toString('utf-8')
+            .trim();
+    }
+    catch {
+        throw new GitShowError('not-found-at-ref', `No file at "${relativePath}" at revision "${ref}"`);
+    }
+    // A directory (tree) at that ref must not fall through to `git show`,
+    // which would print a plain-text directory listing as if it were
+    // file content, with a wrong Content-Type. This route serves file
+    // content only.
+    if (objectType !== 'blob') {
+        throw new GitShowError('not-found-at-ref', `"${relativePath}" is not a file at revision "${ref}"`);
+    }
+    return execFileSync('git', ['show', `${ref}:${repoRelativePath}`], { cwd: config.siteRoot });
+}

package/dist/services/git-revert.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 RevertReason = 'invalid-ref' | 'path-not-found-at-ref' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class RevertError extends Error {
+    readonly reason: RevertReason;
+    constructor(reason: RevertReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function prepareRevertPaths(config: SiteConfig, ref: string, relativePaths: string[]): PreparedOperation;
+export declare function revertPaths(config: SiteConfig, ref: string, relativePaths: string[], message: string, author: CommitAuthor): Promise<void>;

package/dist/services/git-revert.js

@@ -0,0 +1,140 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { commitPaths, isValidGitRef } from "./git.js";
+import { sanitisePath } from "./path-safety.js";
+import { enqueue } from "./write-queue.js";
+export class RevertError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'RevertError';
+        this.reason = reason;
+    }
+}
+// Validates and writes everything a revert needs, stopping short of
+// the commit itself - mirrors publish.ts/move.ts/delete-content.ts's
+// prepareX/xJob split exactly.
+export function prepareRevertPaths(config, ref, relativePaths) {
+    if (!isValidGitRef(ref)) {
+        throw new RevertError('invalid-ref', `Invalid ref: "${ref}"`);
+    }
+    try {
+        execFileSync('git', ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {
+            cwd: config.siteRoot,
+            stdio: 'ignore',
+        });
+    }
+    catch {
+        throw new RevertError('invalid-ref', `Ref does not resolve to a commit: "${ref}"`);
+    }
+    const absolutePaths = relativePaths.map((p) => sanitisePath(config.siteRoot, p));
+    const repoRelativePaths = absolutePaths.map((p) => relative(config.siteRoot, p));
+    // Validate every path exists at ref BEFORE touching any working-tree
+    // file - same "validate everything, write nothing yet" ordering as
+    // publish.ts/move.ts, so a bad path in a multi-path revert fails
+    // clean with zero side effects on the other paths. Deliberately out
+    // of scope: "revert to a state before this file existed" (i.e.
+    // simulate a delete) - surfaced as a clean, distinct error instead of
+    // silently unlinking a file based on inferred intent nobody asked
+    // for.
+    for (let i = 0; i < repoRelativePaths.length; i++) {
+        try {
+            execFileSync('git', ['cat-file', '-e', `${ref}:${repoRelativePaths[i]}`], {
+                cwd: config.siteRoot,
+                stdio: 'ignore',
+            });
+        }
+        catch {
+            throw new RevertError('path-not-found-at-ref', `No file at "${relativePaths[i]}" at revision "${ref}"`);
+        }
+    }
+    const snapshots = [];
+    function undo() {
+        const failures = [];
+        for (const snap of snapshots) {
+            try {
+                if (snap.existed) {
+                    writeFileSync(snap.path, snap.original);
+                }
+                else if (existsSync(snap.path)) {
+                    unlinkSync(snap.path);
+                }
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        return failures;
+        // No explicit unstage here: a failed commitPaths already runs its
+        // own `git reset -- <paths>` internally (git.ts), matching
+        // delete-content.ts's identical precedent - undo only needs to
+        // restore file content.
+    }
+    try {
+        for (const absolutePath of absolutePaths) {
+            const existed = existsSync(absolutePath);
+            snapshots.push({
+                path: absolutePath,
+                existed,
+                original: existed ? readFileSync(absolutePath) : undefined,
+            });
+        }
+        for (const absolutePath of absolutePaths) {
+            execFileSync('git', ['checkout', ref, '--', absolutePath], {
+                cwd: config.siteRoot,
+                stdio: 'ignore',
+            });
+        }
+    }
+    catch (error) {
+        const failures = undo();
+        if (failures.length > 0) {
+            throw new RevertError('rollback-failed', 'Revert 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 RevertError('write-failed', `Revert failed: ${detail}`, { cause: error });
+    }
+    return { paths: absolutePaths, undo };
+}
+async function revertJob(config, ref, relativePaths, message, author) {
+    const { paths, undo } = prepareRevertPaths(config, ref, relativePaths);
+    // The batch.ts empty-commit lesson, triggered here by content-
+    // identity rather than an empty path list: `git checkout` always
+    // stages *something* even when the reverted content is byte-
+    // identical to what's already live (e.g. reverting to HEAD, or a
+    // double-submitted revert) - `git commit` would then fail with
+    // "nothing to commit" for a request that didn't actually do anything
+    // wrong. Scoped to just the reverted paths, not the whole repo, so
+    // an unrelated pre-existing dirty index (exactly what /git/commit's
+    // escape hatch exists for) is never mistaken for "this revert was a
+    // no-op".
+    let hasChanges = true;
+    try {
+        execFileSync('git', ['diff', '--cached', '--quiet', '--', ...paths], {
+            cwd: config.siteRoot,
+            stdio: 'ignore',
+        });
+        hasChanges = false;
+    }
+    catch {
+        hasChanges = true;
+    }
+    if (!hasChanges) {
+        return;
+    }
+    try {
+        commitPaths(config.siteRoot, paths, message, author);
+    }
+    catch (error) {
+        const failures = undo();
+        if (failures.length > 0) {
+            throw new RevertError('rollback-failed', 'Revert 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 RevertError('commit-failed', `Revert failed: ${detail}`, { cause: error });
+    }
+}
+export function revertPaths(config, ref, relativePaths, message, author) {
+    return enqueue(() => revertJob(config, ref, relativePaths, message, author));
+}

package/dist/services/git.d.ts

@@ -0,0 +1,16 @@
+export type GitOperationReason = 'add-failed' | 'commit-failed' | 'reset-failed';
+export declare class GitOperationError extends Error {
+    readonly reason: GitOperationReason;
+    constructor(reason: GitOperationReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface CommitAuthor {
+    name: string;
+    email: string;
+}
+export declare function isValidCommitAuthor(value: unknown): value is CommitAuthor;
+export declare function commitPaths(cwd: string, paths: string[], message: string, author: CommitAuthor): void;
+export declare function resetPaths(cwd: string, paths: string[]): void;
+export declare function isValidGitRef(value: string): boolean;
+export declare function commitWorkingTree(cwd: string, message: string, author: CommitAuthor): 'committed' | 'clean';

package/dist/services/git.js

@@ -0,0 +1,127 @@
+import { execFileSync } from 'node:child_process';
+export class GitOperationError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'GitOperationError';
+        this.reason = reason;
+    }
+}
+const CONTROL_CHAR_PATTERN = /[\r\n]/;
+// The route layer's shape check for a caller-supplied author before it
+// ever reaches `git commit --author` below. execFileSync (not a shell)
+// already rules out command injection, but a name/email containing a
+// literal newline could still smuggle a malformed or multi-line author
+// string into git history - this is the first place in the codebase a
+// caller-supplied identity reaches a real commit (saveDraft/discardDraft
+// never take an author at all), so this check is new, necessary
+// surface, not a repeat of an existing one.
+export function isValidCommitAuthor(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const { name, email } = value;
+    return (typeof name === 'string' &&
+        name.length > 0 &&
+        !CONTROL_CHAR_PATTERN.test(name) &&
+        typeof email === 'string' &&
+        email.length > 0 &&
+        !CONTROL_CHAR_PATTERN.test(email));
+}
+// Author identity always comes from the caller, never host config
+// (constraint: commit authorship passthrough, checklist C5). Passing
+// GIT_AUTHOR_*/GIT_COMMITTER_* explicitly means this never depends on
+// ~/.gitconfig or any host identity being configured at all, which also
+// retires the "usable identity config" startup prerequisite entirely
+// rather than merely deferring it.
+function authorEnv(author) {
+    return {
+        ...process.env,
+        GIT_AUTHOR_NAME: author.name,
+        GIT_AUTHOR_EMAIL: author.email,
+        GIT_COMMITTER_NAME: author.name,
+        GIT_COMMITTER_EMAIL: author.email,
+    };
+}
+// Guarantees its own all-or-nothing contract: either fully committed,
+// or nothing left staged. Callers (publish.ts) therefore only ever need
+// to reason about filesystem state on failure, never git staging state.
+export function commitPaths(cwd, paths, message, author) {
+    try {
+        execFileSync('git', ['add', '--', ...paths], { cwd, stdio: 'ignore' });
+    }
+    catch (error) {
+        throw new GitOperationError('add-failed', `git add failed in ${cwd}`, { cause: error });
+    }
+    try {
+        execFileSync('git', ['commit', '-m', message, '--author', `${author.name} <${author.email}>`], {
+            cwd,
+            env: authorEnv(author),
+            stdio: 'ignore',
+        });
+    }
+    catch (error) {
+        try {
+            execFileSync('git', ['reset', '--', ...paths], { cwd, stdio: 'ignore' });
+        }
+        catch (resetError) {
+            throw new GitOperationError('reset-failed', `git commit failed in ${cwd} and unstaging afterwards also failed; index may be inconsistent`, { cause: resetError });
+        }
+        throw new GitOperationError('commit-failed', `git commit failed in ${cwd}`, { cause: error });
+    }
+}
+export function resetPaths(cwd, paths) {
+    try {
+        execFileSync('git', ['reset', '--', ...paths], { cwd, stdio: 'ignore' });
+    }
+    catch (error) {
+        throw new GitOperationError('reset-failed', `git reset failed in ${cwd}`, { cause: error });
+    }
+}
+// Allowlist, not a denylist of "dangerous" characters - the same
+// reject-on-ambiguity posture sanitisePath itself uses for paths. A
+// denylist (reject leading '-', reject whitespace) is exactly the
+// shape of check that's easy to get subtly wrong one case at a time
+// (reflog @{...} syntax, ^{...} suffixes, unicode whitespace); this
+// closes all of that in one line instead of enumerating each dangerous
+// case as it's discovered.
+const REF_PATTERN = /^[A-Za-z0-9._/-]+$/;
+export function isValidGitRef(value) {
+    return value.length > 0 && !value.startsWith('-') && !value.includes('..') && REF_PATTERN.test(value);
+}
+// The escape hatch (checklist G5): stages and commits literally
+// everything currently changed in the working tree, deliberately
+// unscoped - a path-scoped variant would defeat the entire point of
+// "out-of-band changes the API doesn't otherwise know about" (build
+// plan wording). Respects .gitignore like any git invocation, so
+// data/ stays excluded per existing convention.
+export function commitWorkingTree(cwd, message, author) {
+    const status = execFileSync('git', ['status', '--porcelain'], { cwd }).toString('utf-8');
+    if (status.trim().length === 0) {
+        // Nothing to stage - matches batch.ts's empty-commit lesson
+        // (git commit with nothing staged exits non-zero), simpler here
+        // since there's no path list to check, just the whole tree.
+        return 'clean';
+    }
+    try {
+        execFileSync('git', ['add', '-A'], { cwd, stdio: 'ignore' });
+    }
+    catch (error) {
+        throw new GitOperationError('add-failed', `git add -A failed in ${cwd}`, { cause: error });
+    }
+    try {
+        execFileSync('git', ['commit', '-m', message, '--author', `${author.name} <${author.email}>`], { cwd, env: authorEnv(author), stdio: 'ignore' });
+    }
+    catch (error) {
+        try {
+            // Bare reset (no path list): unstages everything just added,
+            // mirroring commitPaths's own rollback shape.
+            execFileSync('git', ['reset'], { cwd, stdio: 'ignore' });
+        }
+        catch (resetError) {
+            throw new GitOperationError('reset-failed', `git commit failed in ${cwd} and unstaging afterwards also failed; index may be inconsistent`, { cause: resetError });
+        }
+        throw new GitOperationError('commit-failed', `git commit failed in ${cwd}`, { cause: error });
+    }
+    return 'committed';
+}

package/dist/services/interval-job.d.ts

@@ -0,0 +1,4 @@
+export interface IntervalJobHandle {
+    stop: () => void;
+}
+export declare function startIntervalJob(job: () => Promise<unknown>, intervalMs: number, onError: (error: unknown) => void): IntervalJobHandle;

package/dist/services/interval-job.js

@@ -0,0 +1,9 @@
+export function startIntervalJob(job, intervalMs, onError) {
+    const timer = setInterval(() => {
+        job().catch(onError);
+    }, intervalMs);
+    // Must not itself keep a process (or a test) alive - the listening
+    // socket is what should be process-life-sustaining, not this timer.
+    timer.unref();
+    return { stop: () => clearInterval(timer) };
+}

package/dist/services/ip-allowlist.d.ts

@@ -0,0 +1,7 @@
+import type { FastifyRequest } from 'fastify';
+export declare class IpAllowlistError extends Error {
+    readonly statusCode = 403;
+    constructor();
+}
+export declare function isIpAllowed(allowlist: string[], ip: string): boolean;
+export declare function ipAllowlistGuard(allowlist: string[]): (request: FastifyRequest) => Promise<void>;

package/dist/services/ip-allowlist.js

@@ -0,0 +1,31 @@
+// Mirrors token-auth.ts's AuthError shape: statusCode set explicitly
+// in the constructor so the existing global error handler passes this
+// through with its real message intact, never sanitising it as a
+// generic 500.
+export class IpAllowlistError extends Error {
+    statusCode = 403;
+    constructor() {
+        super('This IP address is not permitted to access this API');
+        this.name = 'IpAllowlistError';
+    }
+}
+// An empty allowlist is a no-op (checklist H3), not "nothing is
+// allowed" - exact-IP-only for this pass, no CIDR ranges: IP
+// allowlisting is "optional, not the backbone" per the build plan, a
+// deliberate scope reduction rather than an oversight.
+export function isIpAllowed(allowlist, ip) {
+    return allowlist.length === 0 || allowlist.includes(ip);
+}
+// Applied as a whole-file addHook('onRequest', ...) inside v1Routes's
+// own plugin body (routes/index.ts), not a per-route preHandler like
+// requireScope - an IP allowlist is a coarse "is this client's network
+// address allowed to talk to the API at all" gate, orthogonal to
+// token-scope exemption, so it applies to the entire /v1 surface
+// uniformly, including capabilities.ts and every GET route.
+export function ipAllowlistGuard(allowlist) {
+    return async function guard(request) {
+        if (!isIpAllowed(allowlist, request.ip)) {
+            throw new IpAllowlistError();
+        }
+    };
+}

package/dist/services/links.d.ts

@@ -0,0 +1,22 @@
+import type { SiteConfig } from '../config.ts';
+export declare function linkTarget(href: string): string | null;
+export declare function collectLinks(value: unknown): string[];
+export declare function rewriteLinks(value: unknown, from: string, to: string): {
+    value: unknown;
+    changed: boolean;
+};
+export type LinkSourceKind = 'page' | 'draft' | 'menu' | 'settings';
+export interface LinkSource {
+    kind: LinkSourceKind;
+    path: string;
+    file: string;
+}
+export declare function linkSources(config: SiteConfig): LinkSource[];
+export interface LinkReference {
+    kind: LinkSourceKind;
+    path: string;
+    label: string;
+    url?: string;
+    hrefs: string[];
+}
+export declare function findReferences(config: SiteConfig, to: string): LinkReference[];