@o-a/cms-agent 0.1.0

package/dist/services/drafts.js

@@ -0,0 +1,155 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { ContentReadError, readContentFile } from "./content-read.js";
+import { computeEtag, etagsMatch } from "./etag.js";
+import { sanitisePath } from "./path-safety.js";
+import { validateContent } from "./validation.js";
+import { enqueue } from "./write-queue.js";
+export class DraftError extends Error {
+    reason;
+    // Group I: the real ajv errors (already field-pointing, e.g.
+    // /sections/0/settings/columns) - previously only available
+    // stringified inside .message. Always [] for the 'conflict' reason.
+    errors;
+    constructor(reason, message, errors = []) {
+        super(message);
+        this.name = 'DraftError';
+        this.reason = reason;
+        this.errors = errors;
+    }
+}
+// Draft takes precedence over live: the ETag a client's If-Match must
+// match is whatever they would have read from a prior GET, and D1/D2
+// already prefer the draft over the live file at the same path. Reuses
+// readContentFile/computeEtag (etag.ts's own doc comment anticipates
+// this exact reuse) rather than reimplementing hashing here. Returns
+// null when neither a draft nor a live file exists yet (a brand-new
+// page) - see saveDraftJob's own comment for what that means.
+function readCurrentEtag(config, relativePath) {
+    try {
+        return readContentFile(config.draftsRoot, relativePath).etag;
+    }
+    catch (error) {
+        if (!(error instanceof ContentReadError) || error.reason !== 'not-found') {
+            throw error;
+        }
+    }
+    try {
+        return readContentFile(config.contentRoot, relativePath).etag;
+    }
+    catch (error) {
+        if (!(error instanceof ContentReadError) || error.reason !== 'not-found') {
+            throw error;
+        }
+        return null;
+    }
+}
+async function saveDraftJob(config, themeSchemas, relativePath, content, expectedEtag) {
+    const draftPath = sanitisePath(config.draftsRoot, relativePath);
+    // The If-Match check happens here, inside the queued job, never at
+    // the route layer before enqueuing: the queue only serialises the
+    // writes themselves, not a check that happened earlier, so a
+    // route-layer check-then-enqueue has a real TOCTOU gap (verified
+    // empirically: run 2000 times, a check-before-enqueue design lets
+    // both of two racing requests succeed every single time; the same
+    // check run inside the job, like this, produced exactly one winner
+    // every time, no exceptions).
+    const currentEtag = readCurrentEtag(config, relativePath);
+    if (currentEtag !== null && !etagsMatch(currentEtag, expectedEtag)) {
+        throw new DraftError('conflict', `If-Match "${expectedEtag}" does not match the current ETag for "${relativePath}"`);
+    }
+    // currentEtag === null means neither a draft nor a live file exists
+    // yet (a brand-new page) - deliberately not checked further here.
+    // This isn't a race loophole: the *next* write to this same path
+    // lands after this job's write has created a real draft, so that
+    // job's own currentEtag is no longer null and gets checked for
+    // real. Only the very first write to a wholly new path skips the
+    // comparison, and nothing (E1-E6) tests or specifies what that first
+    // write's If-Match value should mean.
+    // Validate before touching disk at all, so a validation failure
+    // writes nothing (checklist C3) structurally, not via cleanup.
+    const result = validateContent(relativePath, content, themeSchemas);
+    if (!result.valid) {
+        throw new DraftError('validation-failed', `Draft at "${relativePath}" failed validation: ${JSON.stringify(result.errors)}`, result.errors);
+    }
+    mkdirSync(dirname(draftPath), { recursive: true });
+    const bytes = Buffer.from(JSON.stringify(content, null, 2));
+    writeFileSync(draftPath, bytes);
+    // No git call: saves are cheap and frequent, and never create history
+    // (checklist C2, constraint 5).
+    // Computed from the exact bytes just written, never a second disk
+    // read (inside or outside the queue) - a second read could itself
+    // race a subsequent queued job and hand the client a stale value.
+    return computeEtag(bytes);
+}
+async function discardDraftJob(config, relativePath) {
+    const draftPath = sanitisePath(config.draftsRoot, relativePath);
+    // Idempotent, matching DELETE semantics: silently succeed if the
+    // draft is already absent rather than inventing a not-found error
+    // the checklist doesn't ask for.
+    if (existsSync(draftPath)) {
+        unlinkSync(draftPath);
+    }
+    // No git call: discard never touches /content/ or history.
+}
+export function saveDraft(config, themeSchemas, relativePath, content, expectedEtag) {
+    return enqueue(() => saveDraftJob(config, themeSchemas, relativePath, content, expectedEtag));
+}
+export function discardDraft(config, relativePath) {
+    return enqueue(() => discardDraftJob(config, relativePath));
+}
+// The batch.ts-composable shape, mirroring publish.ts/move.ts/
+// delete-content.ts's own prepare* exports for a single uniform
+// vocabulary - even though saveDraftJob/discardDraftJob never call
+// commitPaths at all (drafts are never git-tracked, so paths is
+// always []), batch.ts still needs an undo for them: F6 requires "no
+// partial writes" for a whole failed batch, which includes rolling
+// back an earlier draft write if a later operation in the same batch
+// fails. Snapshots the draft's prior bytes/existence *before*
+// delegating to the existing job function, rather than reimplementing
+// its logic here.
+export async function prepareSaveDraft(config, themeSchemas, relativePath, content, expectedEtag) {
+    const draftPath = sanitisePath(config.draftsRoot, relativePath);
+    const existedBefore = existsSync(draftPath);
+    const originalBytes = existedBefore ? readFileSync(draftPath) : null;
+    const etag = await saveDraftJob(config, themeSchemas, relativePath, content, expectedEtag);
+    return {
+        paths: [],
+        etag,
+        undo: () => {
+            try {
+                if (existedBefore) {
+                    writeFileSync(draftPath, originalBytes);
+                }
+                else {
+                    unlinkSync(draftPath);
+                }
+                return [];
+            }
+            catch (error) {
+                return [error];
+            }
+        },
+    };
+}
+export async function prepareDiscardDraft(config, relativePath) {
+    const draftPath = sanitisePath(config.draftsRoot, relativePath);
+    const existedBefore = existsSync(draftPath);
+    const originalBytes = existedBefore ? readFileSync(draftPath) : null;
+    await discardDraftJob(config, relativePath);
+    return {
+        paths: [],
+        undo: () => {
+            try {
+                if (existedBefore) {
+                    mkdirSync(dirname(draftPath), { recursive: true });
+                    writeFileSync(draftPath, originalBytes);
+                }
+                return [];
+            }
+            catch (error) {
+                return [error];
+            }
+        },
+    };
+}

package/dist/services/etag.d.ts

@@ -0,0 +1,2 @@
+export declare function computeEtag(bytes: Buffer): string;
+export declare function etagsMatch(a: string, b: string): boolean;

package/dist/services/etag.js

@@ -0,0 +1,30 @@
+import { createHash } from 'node:crypto';
+// A plain content hash, not a git blob hash: git.ts only shells out to
+// git for actual commits, never for a per-request read, and nothing
+// downstream needs the ETag to coincide with a real git blob hash
+// (the git log/show endpoints address content by ref+path, not by
+// hash lookup). A quoted strong ETag, matching HTTP's own syntax -
+// this is a byte-for-byte digest, so strong semantics are correct.
+//
+// The one hash function every ETag-producing read (D1/D2) and every
+// future If-Match comparison (Group E) must share - never inlined
+// separately, or the two could silently drift.
+export function computeEtag(bytes) {
+    return `"${createHash('sha256').update(bytes).digest('hex')}"`;
+}
+// RFC 7232 weak comparison: a compressing proxy sitting in front of a
+// real deployment (confirmed live against a Railway-hosted admin - its
+// edge downgrades this server's own strong ETag to weak in transit,
+// since the compressed bytes on the wire differ from what computeEtag
+// hashed) is standard, spec-compliant proxy behaviour, not a bug on
+// the proxy's part. A client that captured and echoes back that
+// now-weak value represents the exact same content a strict `===`
+// would wrongly reject as changed - every If-Match check must compare
+// this way, never with a bare `!==`, or any real host behind a
+// compressing proxy/CDN produces spurious conflicts on every save.
+function stripWeakPrefix(etag) {
+    return etag.startsWith('W/') ? etag.slice(2) : etag;
+}
+export function etagsMatch(a, b) {
+    return stripWeakPrefix(a) === stripWeakPrefix(b);
+}

package/dist/services/fs-walk.d.ts

@@ -0,0 +1 @@
+export declare function listFilesRecursively(dir: string, base: string, extension: string): string[];

package/dist/services/fs-walk.js

@@ -0,0 +1,26 @@
+import { readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+// Recursively lists files matching extension under dir, returned as
+// paths relative to base. Agent-configured roots only (content/drafts
+// roots, theme directories), never a request-supplied :path - callers
+// that walk request-shaped paths must go through sanitisePath instead.
+export function listFilesRecursively(dir, base, extension) {
+    let out = [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out = out.concat(listFilesRecursively(full, base, extension));
+        }
+        else if (entry.isFile() && entry.name.endsWith(extension)) {
+            out.push(relative(base, full));
+        }
+    }
+    return out;
+}

package/dist/services/git-commit.d.ts

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

package/dist/services/git-commit.js

@@ -0,0 +1,12 @@
+import { commitWorkingTree } from "./git.js";
+import { enqueue } from "./write-queue.js";
+// The escape hatch (checklist G5). No PreparedOperation/undo-stack
+// here, unlike publish/move/delete/revert: those services write new
+// content themselves on request, so a write can fail independently of
+// the git step, needing an undo. Here the "write" already exists in
+// the working tree before this is ever called - the only failure
+// modes are git add/git commit themselves, which commitWorkingTree's
+// own bare `git reset` already unwinds (git.ts).
+export function commitWorkingTreeChanges(config, message, author) {
+    return enqueue(() => Promise.resolve(commitWorkingTree(config.siteRoot, message, author)));
+}

package/dist/services/git-history.d.ts

@@ -0,0 +1,28 @@
+import type { SiteConfig } from '../config.ts';
+export interface LogEntry {
+    hash: string;
+    author: {
+        name: string;
+        email: string;
+    };
+    date: string;
+    message: string;
+    isCheckpoint: boolean;
+}
+export interface LogResult {
+    commits: LogEntry[];
+    hasMore: boolean;
+}
+export declare const CHECKPOINT_MESSAGE = "chore: draft checkpoint";
+export declare function getCommitLog(config: SiteConfig, options: {
+    path?: string;
+    limit?: number;
+}): LogResult;
+export type GitShowReason = 'invalid-ref' | 'not-found-at-ref';
+export declare class GitShowError extends Error {
+    readonly reason: GitShowReason;
+    constructor(reason: GitShowReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function readFileAtRevision(config: SiteConfig, ref: string, relativePath: string): Buffer;

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';