@mrsf/cli 0.2.2 → 0.3.0

package/README.md

@@ -1,6 +1,11 @@
 # MRSF CLI
 
-Command-line tool and Node.js library for the **Markdown Review Sidecar Format** ([MRSF v1.0](../MRSF-v1.0.md)).
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![MRSF v1.0 Draft](https://img.shields.io/badge/MRSF-v1.0%20Draft-blue)](MRSF-v1.0.md)
+[![@mrsf/cli on npm](https://img.shields.io/npm/v/@mrsf/cli?label=%40mrsf%2Fcli)](https://www.npmjs.com/package/@mrsf/cli)
+[![npm downloads (cli)](https://img.shields.io/npm/dm/@mrsf/cli?label=cli%20downloads)](https://www.npmjs.com/package/@mrsf/cli)
+
+Command-line tool and Node.js library for **Sidemark** — the **Markdown Review Sidecar Format** ([MRSF v1.0](../MRSF-v1.0.md)).
 
 Validate sidecars, add and resolve review comments, re-anchor comments after document edits, and integrate MRSF into CI/CD pipelines — all from the terminal.
 
@@ -242,6 +247,48 @@ mrsf rename docs/old-name.md docs/new-name.md
 
 Updates the `document` field inside the sidecar, writes it to the new path, and removes the old sidecar file.
 
+### `mrsf watch [files...]`
+
+Watch files for changes and continuously validate (and optionally reanchor).
+
+```bash
+# Validate all sidecars on every change
+mrsf watch
+
+# Watch specific files
+mrsf watch docs/api.md docs/guide.md
+
+# Auto-reanchor when Markdown files change
+mrsf watch --reanchor
+
+# Preview reanchor changes without writing
+mrsf watch --reanchor --dry-run
+
+# Custom threshold and strict validation
+mrsf watch --reanchor --threshold 0.8 --strict
+```
+
+**Trigger rules** (avoids feedback loops):
+
+| File type | Action |
+|---|---|
+| `.md` (Markdown) | Reanchor (if `--reanchor` is set), then validate sidecar |
+| `.review.yaml` / `.review.json` | Validate only |
+
+| Option | Description |
+|---|---|
+| `--reanchor` | Auto-reanchor when Markdown files change |
+| `-n, --dry-run` | Preview reanchor changes without writing |
+| `-t, --threshold <n>` | Fuzzy match threshold 0.0–1.0 (default `0.6`) |
+| `-s, --strict` | Treat validation warnings as errors |
+| `--no-git` | Disable git integration |
+| `--from <commit>` | Override from-commit for reanchor |
+| `--update-text` | Update `selected_text` on reanchor |
+| `-f, --force` | Force reanchor — update commit, clear audit fields |
+| `--debounce <ms>` | Debounce interval in ms (default `300`) |
+
+Press `Ctrl+C` to stop — a summary of events, reanchors, and errors is printed.
+
 ## Global Options
 
 These apply to all commands:
@@ -298,16 +345,18 @@ The CLI is built library-first. All functionality is available as importable fun
 ```typescript
 import {
   parseSidecar,
+  parseSidecarLenient,
   writeSidecar,
   validate,
   reanchorDocument,
   addComment,
   resolveComment,
+  removeComment,
   filterComments,
   summarize,
   discoverSidecar,
   discoverAllSidecars,
-} from "mrsf";
+} from "@mrsf/cli";
 
 // Validate a sidecar programmatically
 const doc = await parseSidecar("docs/api.md.review.yaml");

package/dist/bin.js

@@ -17,6 +17,7 @@ import { registerList } from "./commands/list.js";
 import { registerInit } from "./commands/init.js";
 import { registerStatus } from "./commands/status.js";
 import { registerRename } from "./commands/rename.js";
+import { registerWatch } from "./commands/watch.js";
 /* ── Banner ────────────────────────────────────────────────────────── */
 /**
  * Detect CI/CD or non-interactive environments where the banner should
@@ -73,5 +74,6 @@ registerList(program);
 registerInit(program);
 registerStatus(program);
 registerRename(program);
+registerWatch(program);
 program.parse();
 //# sourceMappingURL=bin.js.map

package/dist/commands/watch.d.ts

@@ -0,0 +1,24 @@
+/**
+ * mrsf watch — Monitor files and validate / reanchor on change.
+ *
+ * By default, validation is run on every change.  Pass `--reanchor` to
+ * also auto-fix drifted anchors when a Markdown file is saved.
+ *
+ * Trigger rules (avoids feedback loops):
+ *   - `.md` change       → reanchor (if enabled), then validate sidecar
+ *   - `.review.yaml/json` change → validate only
+ */
+import type { Command } from "commander";
+export interface WatchOptions {
+    reanchor?: boolean;
+    dryRun?: boolean;
+    threshold: string;
+    git: boolean;
+    from?: string;
+    updateText?: boolean;
+    force?: boolean;
+    strict?: boolean;
+    debounce: string;
+}
+export declare function registerWatch(program: Command): void;
+//# sourceMappingURL=watch.d.ts.map

package/dist/commands/watch.js

@@ -0,0 +1,277 @@
+/**
+ * mrsf watch — Monitor files and validate / reanchor on change.
+ *
+ * By default, validation is run on every change.  Pass `--reanchor` to
+ * also auto-fix drifted anchors when a Markdown file is saved.
+ *
+ * Trigger rules (avoids feedback loops):
+ *   - `.md` change       → reanchor (if enabled), then validate sidecar
+ *   - `.review.yaml/json` change → validate only
+ */
+import path from "node:path";
+import chalk from "chalk";
+import { watch as chokidarWatch } from "chokidar";
+import { findWorkspaceRoot, discoverSidecar, sidecarToDocument, } from "../lib/discovery.js";
+import { resolveSidecarPaths } from "../lib/resolve-files.js";
+import { validateFile } from "../lib/validator.js";
+import { reanchorFile } from "../lib/reanchor.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const SIDECAR_EXTS = [".review.yaml", ".review.json"];
+function isSidecar(file) {
+    return SIDECAR_EXTS.some((ext) => file.endsWith(ext));
+}
+function timestamp() {
+    return new Date().toLocaleTimeString("en-GB", { hour12: false });
+}
+function statusIcon(status) {
+    switch (status) {
+        case "anchored":
+            return chalk.green("●");
+        case "shifted":
+            return chalk.blue("↕");
+        case "fuzzy":
+            return chalk.yellow("≈");
+        case "ambiguous":
+            return chalk.magenta("?");
+        case "orphaned":
+            return chalk.red("✗");
+        default:
+            return "·";
+    }
+}
+function printReanchorResults(label, results, changed, written, dryRun, verbose) {
+    const prefix = dryRun ? chalk.dim("[dry-run] ") : "";
+    console.log(`  ${prefix}${chalk.cyan("reanchor")} ${label}`);
+    for (const r of results) {
+        const icon = statusIcon(r.status);
+        const line = r.newLine != null ? `:${r.newLine}` : "";
+        console.log(`    ${icon} ${r.commentId}${line} — ${r.reason}`);
+        if (verbose && r.score != null) {
+            console.log(`        score: ${r.score.toFixed(3)}`);
+        }
+    }
+    if (!dryRun && written) {
+        console.log(`  ${chalk.green("✓")} ${changed} comment(s) updated`);
+    }
+    else if (dryRun) {
+        console.log(`  ${chalk.dim(`${changed} comment(s) would change`)}`);
+    }
+}
+function printValidateResults(label, result, strict) {
+    const effectiveValid = strict
+        ? result.valid && result.warnings.length === 0
+        : result.valid;
+    const icon = effectiveValid ? chalk.green("✓") : chalk.red("✗");
+    console.log(`  ${chalk.cyan("validate")} ${icon} ${label}`);
+    for (const e of result.errors) {
+        console.log(chalk.red(`    error: ${e.message}${e.path ? ` (${e.path})` : ""}`));
+    }
+    for (const w of result.warnings) {
+        const fn = strict ? chalk.red : chalk.yellow;
+        const tag = strict ? "error" : "warn";
+        console.log(fn(`    ${tag}: ${w.message}${w.path ? ` (${w.path})` : ""}`));
+    }
+}
+export function registerWatch(program) {
+    program
+        .command("watch [files...]")
+        .description("Watch files for changes and validate (+ optionally reanchor)")
+        .option("--reanchor", "Auto-reanchor when Markdown files change")
+        .option("-n, --dry-run", "Preview reanchor changes without writing")
+        .option("-t, --threshold <n>", "Fuzzy match threshold 0.0–1.0", "0.6")
+        .option("-s, --strict", "Treat validation warnings as errors")
+        .option("--no-git", "Disable git integration")
+        .option("--from <commit>", "Override from-commit for reanchor")
+        .option("--update-text", "Update selected_text on reanchor")
+        .option("-f, --force", "Force reanchor — update commit, clear audit fields")
+        .option("--debounce <ms>", "Debounce interval in ms", "300")
+        .action(async (files, opts) => {
+        const parentOpts = program.opts();
+        const cwd = parentOpts.cwd ?? process.cwd();
+        const quiet = parentOpts.quiet ?? false;
+        const verbose = parentOpts.verbose ?? false;
+        const debounceMs = parseInt(opts.debounce, 10) || 300;
+        const threshold = parseFloat(opts.threshold);
+        const noGit = !opts.git;
+        // ── Resolve watch targets ────────────────────────────
+        let watchPaths;
+        if (files.length === 0) {
+            // Watch the whole workspace
+            const root = findWorkspaceRoot(cwd) ?? cwd;
+            watchPaths = [root];
+        }
+        else {
+            // Resolve explicit paths — collect both sidecars and documents
+            const sidecarPaths = await resolveSidecarPaths(files, cwd);
+            const docPaths = sidecarPaths.map((sp) => sidecarToDocument(sp));
+            watchPaths = [...new Set([...sidecarPaths, ...docPaths])];
+        }
+        // ── Start watcher ────────────────────────────────────
+        const watcher = chokidarWatch(watchPaths, {
+            ignoreInitial: true,
+            ignored: [
+                "**/node_modules/**",
+                "**/.git/**",
+                ...(files.length === 0
+                    ? []
+                    : [
+                    // When watching specific files, chokidar might get
+                    // extra events from parent dirs — no extra ignores needed.
+                    ]),
+            ],
+            // Only watch files matching our extensions when watching a dir
+            ...(files.length === 0
+                ? {}
+                : {}),
+        });
+        // Track debounce per file
+        const timers = new Map();
+        // Track files we just wrote (to skip re-trigger)
+        const selfWrites = new Set();
+        // Stats
+        let totalEvents = 0;
+        let totalErrors = 0;
+        let totalReanchors = 0;
+        // ── Event handler ────────────────────────────────────
+        async function handleChange(filePath) {
+            const abs = path.resolve(filePath);
+            const rel = path.relative(cwd, abs);
+            // Skip files we just wrote ourselves
+            if (selfWrites.has(abs)) {
+                selfWrites.delete(abs);
+                return;
+            }
+            // Only process markdown and sidecar files
+            const isSidecarFile = isSidecar(abs);
+            const isMarkdown = abs.endsWith(".md");
+            if (!isSidecarFile && !isMarkdown)
+                return;
+            totalEvents++;
+            if (!quiet) {
+                console.log(`\n${chalk.dim(`[${timestamp()}]`)} ${chalk.bold(rel)}`);
+            }
+            if (isSidecarFile) {
+                // ── Sidecar changed → validate ──────────────────
+                await runValidate(abs, rel);
+            }
+            else if (isMarkdown) {
+                // ── Markdown changed → reanchor (opt-in) + validate sidecar ──
+                let sidecarPath;
+                try {
+                    sidecarPath = await discoverSidecar(abs, { cwd });
+                }
+                catch {
+                    // No sidecar for this markdown file — skip silently
+                    if (verbose) {
+                        console.log(chalk.dim(`  no sidecar found — skipping`));
+                    }
+                    return;
+                }
+                if (opts.reanchor) {
+                    await runReanchor(sidecarPath, rel);
+                }
+                // Validate the sidecar in all modes
+                await runValidate(sidecarPath, path.relative(cwd, sidecarPath));
+            }
+        }
+        async function runValidate(sidecarPath, label) {
+            try {
+                const result = await validateFile(sidecarPath);
+                const effectiveValid = opts.strict
+                    ? result.valid && result.warnings.length === 0
+                    : result.valid;
+                if (!effectiveValid)
+                    totalErrors++;
+                if (!quiet || !effectiveValid) {
+                    printValidateResults(label, result, !!opts.strict);
+                }
+            }
+            catch (err) {
+                totalErrors++;
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(chalk.red(`  validate ✗ ${label}: ${msg}`));
+            }
+        }
+        async function runReanchor(sidecarPath, label) {
+            try {
+                const { results, changed, written } = await reanchorFile(sidecarPath, {
+                    cwd,
+                    dryRun: opts.dryRun,
+                    threshold,
+                    noGit,
+                    fromCommit: opts.from,
+                    updateText: opts.updateText,
+                    force: opts.force,
+                });
+                totalReanchors++;
+                if (written) {
+                    // Mark the sidecar as self-written to avoid re-triggering
+                    selfWrites.add(path.resolve(sidecarPath));
+                }
+                const orphaned = results.filter((r) => r.status === "orphaned").length;
+                if (orphaned > 0)
+                    totalErrors++;
+                if (!quiet) {
+                    printReanchorResults(label, results, changed, written, !!opts.dryRun, verbose);
+                }
+            }
+            catch (err) {
+                totalErrors++;
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(chalk.red(`  reanchor ✗ ${label}: ${msg}`));
+            }
+        }
+        // ── Wire events with debounce ────────────────────────
+        function onFileChange(filePath) {
+            const abs = path.resolve(filePath);
+            const existing = timers.get(abs);
+            if (existing)
+                clearTimeout(existing);
+            timers.set(abs, setTimeout(() => {
+                timers.delete(abs);
+                handleChange(abs).catch((err) => {
+                    console.error(chalk.red(`  unexpected error: ${String(err)}`));
+                });
+            }, debounceMs));
+        }
+        watcher.on("change", onFileChange);
+        watcher.on("add", onFileChange);
+        // ── Startup banner ───────────────────────────────────
+        if (!quiet) {
+            const mode = opts.reanchor
+                ? opts.dryRun
+                    ? "validate + reanchor (dry-run)"
+                    : "validate + reanchor"
+                : "validate";
+            const pathDesc = files.length === 0
+                ? "workspace"
+                : `${watchPaths.length} path(s)`;
+            console.log(chalk.green(`Watching ${pathDesc} — mode: ${chalk.bold(mode)}`));
+            console.log(chalk.dim("Press Ctrl+C to stop.\n"));
+        }
+        // ── Graceful shutdown ────────────────────────────────
+        async function shutdown() {
+            // Clear pending debounce timers
+            for (const t of timers.values())
+                clearTimeout(t);
+            timers.clear();
+            await watcher.close();
+            if (!quiet) {
+                console.log(`\n${chalk.dim("──────────────────────────────────────")}`);
+                console.log(`Events processed: ${totalEvents}  |  ` +
+                    `Reanchors: ${totalReanchors}  |  ` +
+                    `Errors: ${totalErrors}`);
+            }
+            process.exit(totalErrors > 0 ? 1 : 0);
+        }
+        process.on("SIGINT", () => void shutdown());
+        process.on("SIGTERM", () => void shutdown());
+        // Keep the process alive
+        await new Promise(() => {
+            // Never resolves — the process runs until interrupted
+        });
+    });
+}
+//# sourceMappingURL=watch.js.map

package/dist/index.d.ts

@@ -7,7 +7,8 @@
 export type { MrsfDocument, Comment, MrsfConfig, DiagnosticSeverity, ValidationDiagnostic, ValidationResult, ReanchorStatus, ReanchorResult, FuzzyCandidate, DiffHunk, AddCommentOptions, CommentFilter, AnchorHealth, StatusResult, BaseOptions, ReanchorOptions, ValidateOptions, } from "./lib/types.js";
 export { findWorkspaceRoot, loadConfig, discoverSidecar, sidecarToDocument, discoverAllSidecars, } from "./lib/discovery.js";
 export { resolveSidecarPaths } from "./lib/resolve-files.js";
-export { parseSidecar, parseSidecarContent, readDocumentLines, } from "./lib/parser.js";
+export { parseSidecar, parseSidecarContent, parseSidecarLenient, parseSidecarContentLenient, readDocumentLines, } from "./lib/parser.js";
+export type { LenientParseResult } from "./lib/parser.js";
 export { computeHash, syncHash, toYaml, toJson, writeSidecar, } from "./lib/writer.js";
 export { validate, validateFile } from "./lib/validator.js";
 export { exactMatch, normalizedMatch, fuzzySearch, combinedScore, } from "./lib/fuzzy.js";

package/dist/index.js

@@ -9,7 +9,7 @@ export { findWorkspaceRoot, loadConfig, discoverSidecar, sidecarToDocument, disc
 // File resolution
 export { resolveSidecarPaths } from "./lib/resolve-files.js";
 // Parsing
-export { parseSidecar, parseSidecarContent, readDocumentLines, } from "./lib/parser.js";
+export { parseSidecar, parseSidecarContent, parseSidecarLenient, parseSidecarContentLenient, readDocumentLines, } from "./lib/parser.js";
 // Writing
 export { computeHash, syncHash, toYaml, toJson, writeSidecar, } from "./lib/writer.js";
 // Validation

package/dist/lib/parser.d.ts

@@ -1,7 +1,16 @@
 /**
  * MRSF Parser — load and parse MRSF sidecar files (YAML or JSON).
  */
-import type { MrsfDocument } from "./types.js";
+import type { MrsfDocument, Comment } from "./types.js";
+/** Result from a lenient (non-throwing) parse attempt. */
+export interface LenientParseResult {
+    /** Fully parsed document, or null if parsing failed entirely. */
+    doc: MrsfDocument | null;
+    /** If parsing failed or produced warnings, the error message. */
+    error?: string;
+    /** Comments that could be salvaged from a partially-corrupted sidecar. */
+    partialComments?: Comment[];
+}
 /**
  * Parse an MRSF sidecar file from disk.
  */
@@ -11,6 +20,18 @@ export declare function parseSidecar(filePath: string): Promise<MrsfDocument>;
  * Detects JSON vs YAML based on content or optional filename hint.
  */
 export declare function parseSidecarContent(content: string, filenameHint?: string): MrsfDocument;
+/**
+ * Lenient parse: attempts to parse a sidecar file from disk without
+ * throwing.  On complete failure, returns `{ doc: null, error }`.
+ * On success, returns `{ doc }`.  For partially-corrupted YAML (where
+ * the top-level parses but some comments are malformed), attempts to
+ * salvage individual well-formed comments.
+ */
+export declare function parseSidecarLenient(filePath: string): Promise<LenientParseResult>;
+/**
+ * Lenient parse from string content.
+ */
+export declare function parseSidecarContentLenient(content: string, filenameHint?: string): LenientParseResult;
 /**
  * Read a Markdown document from disk and return its lines.
  * Lines are 1-indexed in the returned array (index 0 is unused).

package/dist/lib/parser.js

@@ -43,6 +43,132 @@ export function parseSidecarContent(content, filenameHint) {
     }
     return parsed;
 }
+/**
+ * Lenient parse: attempts to parse a sidecar file from disk without
+ * throwing.  On complete failure, returns `{ doc: null, error }`.
+ * On success, returns `{ doc }`.  For partially-corrupted YAML (where
+ * the top-level parses but some comments are malformed), attempts to
+ * salvage individual well-formed comments.
+ */
+export async function parseSidecarLenient(filePath) {
+    const abs = path.resolve(filePath);
+    let content;
+    try {
+        content = await readFile(abs, "utf-8");
+    }
+    catch (e) {
+        return { doc: null, error: `Cannot read file: ${e.message}` };
+    }
+    return parseSidecarContentLenient(content, abs);
+}
+/**
+ * Lenient parse from string content.
+ */
+export function parseSidecarContentLenient(content, filenameHint) {
+    const trimmed = content.trim();
+    if (!trimmed) {
+        return { doc: null, error: "File is empty" };
+    }
+    const isJson = trimmed.startsWith("{") ||
+        (filenameHint && filenameHint.endsWith(".review.json"));
+    // First, try a normal parse
+    let parsed;
+    try {
+        parsed = isJson ? JSON.parse(trimmed) : yaml.load(trimmed);
+    }
+    catch (e) {
+        // Total parse failure — try to salvage what we can from YAML
+        if (!isJson) {
+            return salvageYaml(trimmed);
+        }
+        return { doc: null, error: `Failed to parse JSON: ${e.message}` };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { doc: null, error: "MRSF sidecar must be a YAML/JSON object" };
+    }
+    const obj = parsed;
+    const doc = {
+        mrsf_version: typeof obj.mrsf_version === "string" ? obj.mrsf_version : "1.0",
+        document: typeof obj.document === "string" ? obj.document : "unknown",
+        comments: [],
+    };
+    if (!Array.isArray(obj.comments)) {
+        return {
+            doc,
+            error: "comments field is not an array — file may be corrupted",
+        };
+    }
+    // Validate each comment individually
+    const good = [];
+    const bad = [];
+    for (let i = 0; i < obj.comments.length; i++) {
+        const c = obj.comments[i];
+        if (c && typeof c === "object" && !Array.isArray(c) && typeof c.id === "string") {
+            good.push(c);
+        }
+        else {
+            bad.push(i);
+        }
+    }
+    doc.comments = good;
+    if (bad.length > 0) {
+        return {
+            doc,
+            error: `${bad.length} comment(s) at indices [${bad.join(", ")}] were malformed and skipped`,
+            partialComments: good,
+        };
+    }
+    return { doc };
+}
+/**
+ * Attempt to extract individual comment blocks from corrupted YAML by
+ * splitting on `- id:` patterns and parsing each block independently.
+ */
+function salvageYaml(content) {
+    const salvaged = [];
+    let mrsf_version = "1.0";
+    let document = "unknown";
+    // Try to extract top-level fields from the beginning
+    const versionMatch = content.match(/^mrsf_version:\s*["']?([^"'\n]+)/m);
+    if (versionMatch)
+        mrsf_version = versionMatch[1].trim();
+    const docMatch = content.match(/^document:\s*["']?([^"'\n]+)/m);
+    if (docMatch)
+        document = docMatch[1].trim();
+    // Split on comment block boundaries (- id: ...)
+    const blocks = content.split(/(?=^  - id:\s)/m);
+    for (const block of blocks) {
+        const trimmed = block.trim();
+        if (!trimmed.startsWith("- id:"))
+            continue;
+        // Wrap in a minimal YAML array context and try to parse
+        try {
+            const parsed = yaml.load(trimmed);
+            if (Array.isArray(parsed) && parsed.length > 0) {
+                const c = parsed[0];
+                if (c && typeof c === "object" && typeof c.id === "string") {
+                    salvaged.push(c);
+                }
+            }
+            else if (parsed && typeof parsed === "object" && typeof parsed.id === "string") {
+                salvaged.push(parsed);
+            }
+        }
+        catch {
+            // This block is unparseable — skip
+        }
+    }
+    const doc = {
+        mrsf_version,
+        document,
+        comments: salvaged,
+    };
+    return {
+        doc: salvaged.length > 0 ? doc : null,
+        error: `YAML parse failed. Salvaged ${salvaged.length} comment(s) from raw content.`,
+        partialComments: salvaged.length > 0 ? salvaged : undefined,
+    };
+}
 /**
  * Read a Markdown document from disk and return its lines.
  * Lines are 1-indexed in the returned array (index 0 is unused).

package/dist/lib/writer.d.ts

@@ -37,6 +37,9 @@ export declare function toJson(doc: MrsfDocument): string;
  * whitespace byte-for-byte for unchanged content.
  *
  * For new files or JSON, writes from scratch.
+ *
+ * Writes to the same file path are serialized (queued) to prevent race
+ * conditions from concurrent calls.  All writes are atomic (temp + rename).
  */
 export declare function writeSidecar(filePath: string, doc: MrsfDocument): Promise<void>;
 //# sourceMappingURL=writer.d.ts.map

package/dist/lib/writer.js

@@ -10,12 +10,62 @@
  *
  * Auto-computes selected_text_hash when selected_text changes.
  */
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, writeFile, rename, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import path from "node:path";
 import { Document, Parser, CST, parse as yamlParse } from "yaml";
 /* ------------------------------------------------------------------ */
+/*  Per-file write serialization                                       */
+/* ------------------------------------------------------------------ */
+/**
+ * Map of absolute file paths to pending write promises.
+ * Ensures that concurrent writes to the same sidecar file are serialized
+ * (queued), preventing race conditions during the read-modify-write cycle.
+ */
+const writeQueue = new Map();
+/**
+ * Enqueue a write operation for the given file path, ensuring only one
+ * write executes at a time per file.
+ */
+function enqueueWrite(abs, fn) {
+    const prev = writeQueue.get(abs) ?? Promise.resolve();
+    const next = prev.then(fn, fn); // run fn even if previous write failed
+    writeQueue.set(abs, next);
+    // Clean up map entry when the queue drains
+    next.then(() => {
+        if (writeQueue.get(abs) === next)
+            writeQueue.delete(abs);
+    }, () => {
+        if (writeQueue.get(abs) === next)
+            writeQueue.delete(abs);
+    });
+    return next;
+}
+/* ------------------------------------------------------------------ */
+/*  Atomic file write                                                  */
+/* ------------------------------------------------------------------ */
+/**
+ * Atomically write content to a file by writing to a temporary file in
+ * the same directory, then renaming.  On POSIX this is atomic; on
+ * Windows it replaces the target.
+ */
+async function atomicWriteFile(filePath, content) {
+    const tmp = filePath + "." + randomBytes(6).toString("hex") + ".tmp";
+    try {
+        await writeFile(tmp, content, "utf-8");
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        // Clean up temp file on failure
+        try {
+            await unlink(tmp);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+/* ------------------------------------------------------------------ */
 /*  Hash helpers                                                       */
 /* ------------------------------------------------------------------ */
 /**
@@ -51,22 +101,46 @@ const COMMENT_KEY_ORDER = [
  * Convert a JS value to its YAML source text representation.
  * Strings that require quoting get double-quoted; numbers and booleans
  * are plain scalars.
+ *
+ * Uses an allowlist approach: only strings that consist entirely of
+ * "safe" characters are emitted as bare scalars.  Everything else is
+ * double-quoted via JSON.stringify, which is always valid YAML.
  */
 function valueToSource(v) {
     if (typeof v === "number" || typeof v === "boolean")
         return String(v);
     if (typeof v === "string") {
-        // Strings that need quoting
-        if (/[:\n"{}[\],&#*?|><!%@`]/.test(v) ||
-            v.includes(" #") ||
-            v === "" ||
-            v === "true" ||
-            v === "false" ||
-            v === "null" ||
-            /^\d/.test(v)) {
+        // Empty string must be quoted
+        if (v === "")
+            return JSON.stringify(v);
+        // YAML reserved words / null aliases must be quoted
+        if (v === "true" || v === "false" || v === "null" ||
+            v === "True" || v === "False" || v === "Null" ||
+            v === "TRUE" || v === "FALSE" || v === "NULL" ||
+            v === "yes" || v === "no" || v === "on" || v === "off" ||
+            v === "Yes" || v === "No" || v === "On" || v === "Off" ||
+            v === "YES" || v === "NO" || v === "ON" || v === "OFF" ||
+            v === "~" || v === ".inf" || v === "-.inf" || v === ".nan") {
             return JSON.stringify(v);
         }
-        return v;
+        // Strings starting with digits (could be parsed as number) must be quoted
+        if (/^\d/.test(v))
+            return JSON.stringify(v);
+        // Allowlist: safe plain scalars consist of word chars, hyphens (not
+        // leading), dots, slashes, spaces (not leading/trailing), parentheses,
+        // and @ — but NO YAML indicators or ambiguous sequences.
+        // A safe string:
+        //   • starts with a letter, underscore
+        //   • contains only [A-Za-z0-9 _./()@+-] (note: hyphen mid-string is OK)
+        //   • does NOT contain " #" (inline comment)
+        //   • does NOT start with "- " or end with ":"
+        //   • has no leading/trailing whitespace
+        //   • contains no newlines or tabs
+        if (/^[A-Za-z_][A-Za-z0-9 _./()\-@+]*$/.test(v) && !v.includes(" #") && !/\s$/.test(v)) {
+            return v;
+        }
+        // Everything else: double-quote (JSON.stringify handles escaping)
+        return JSON.stringify(v);
     }
     return String(v);
 }
@@ -262,22 +336,31 @@ export function toJson(doc) {
  * whitespace byte-for-byte for unchanged content.
  *
  * For new files or JSON, writes from scratch.
+ *
+ * Writes to the same file path are serialized (queued) to prevent race
+ * conditions from concurrent calls.  All writes are atomic (temp + rename).
  */
 export async function writeSidecar(filePath, doc) {
     const abs = path.resolve(filePath);
+    return enqueueWrite(abs, () => writeSidecarInternal(abs, doc));
+}
+/**
+ * Internal implementation of writeSidecar (runs inside the per-file queue).
+ */
+async function writeSidecarInternal(abs, doc) {
     const isJson = abs.endsWith(".review.json");
     if (isJson) {
         // For JSON, always sync hashes and write fresh
         for (const comment of doc.comments)
             syncHash(comment);
-        await writeFile(abs, toJson(doc), "utf-8");
+        await atomicWriteFile(abs, toJson(doc));
         return;
     }
     // ── YAML round-trip path ──────────────────────────────────────────
     if (!existsSync(abs)) {
         for (const comment of doc.comments)
             syncHash(comment);
-        await writeFile(abs, toYaml(doc), "utf-8");
+        await atomicWriteFile(abs, toYaml(doc));
         return;
     }
     let raw;
@@ -285,7 +368,7 @@ export async function writeSidecar(filePath, doc) {
         raw = await readFile(abs, "utf-8");
     }
     catch {
-        await writeFile(abs, toYaml(doc), "utf-8");
+        await atomicWriteFile(abs, toYaml(doc));
         return;
     }
     // Parse to CST tokens
@@ -295,7 +378,7 @@ export async function writeSidecar(filePath, doc) {
     }
     catch {
         // Unparseable — write fresh
-        await writeFile(abs, toYaml(doc), "utf-8");
+        await atomicWriteFile(abs, toYaml(doc));
         return;
     }
     // Also parse to plain JS object for value comparison (so we compare
@@ -307,6 +390,13 @@ export async function writeSidecar(filePath, doc) {
     catch {
         // ignore — we'll fall through to source-level comparison
     }
+    // ── Structural validation of parsed YAML ──────────────────────────
+    // If CST parsed OK but the content isn't a valid MrsfDocument shape
+    // (e.g. comments is not an array due to injection), discard and write fresh.
+    if (currentDoc && (!Array.isArray(currentDoc.comments))) {
+        await atomicWriteFile(abs, toYaml(doc));
+        return;
+    }
     // Build lookup of current parsed values by comment id
     const currentById = new Map();
     if (currentDoc?.comments) {
@@ -340,7 +430,7 @@ export async function writeSidecar(filePath, doc) {
     }
     const docToken = findCstDocument(tokens);
     if (!docToken?.value || docToken.value.type !== "block-map") {
-        await writeFile(abs, toYaml(doc), "utf-8");
+        await atomicWriteFile(abs, toYaml(doc));
         return;
     }
     const body = docToken.value;
@@ -357,7 +447,7 @@ export async function writeSidecar(filePath, doc) {
     const commentsEntry = findCstMapEntry(body, "comments");
     if (!commentsEntry?.value || commentsEntry.value.type !== "block-seq") {
         // No existing comments seq — write fresh
-        await writeFile(abs, toYaml(doc), "utf-8");
+        await atomicWriteFile(abs, toYaml(doc));
         return;
     }
     const seq = commentsEntry.value;
@@ -393,8 +483,47 @@ export async function writeSidecar(filePath, doc) {
         }
     }
     seq.items = newSeqItems;
+    // ── Fix first-item indentation after reorder / removal ────────────
+    //
+    // In the YAML CST, the `comments:` map-entry's `sep` array often
+    // contains trailing whitespace (space tokens) that provide the indent
+    // *before* the first seq-item indicator (`-`).  Non-first seq items
+    // carry their own leading space tokens in `start`.
+    //
+    // When the original first item is removed and a formerly non-first
+    // item becomes the new first, those extra space tokens stack with
+    // the sep whitespace, doubling the indent.  We fix this by stripping
+    // any leading space tokens (before the `seq-item-ind`) from the new
+    // first item's start — the sep already provides that whitespace.
+    //
+    // We also ensure the previous item's value ends with a newline so
+    // subsequent items render on their own line.
+    // ──────────────────────────────────────────────────────────────────
+    if (newSeqItems.length > 0) {
+        const originalFirstIdx = seq.items === newSeqItems ? 0 : -1; // always true after assignment
+        const origFirstItem = existingById.size > 0
+            ? [...existingById.values()].find((e) => e.index === 0)
+            : undefined;
+        const newFirst = newSeqItems[0];
+        // Check if the new first item is NOT the original first item
+        const isOriginalFirst = origFirstItem &&
+            seq.items[0]?.value === origFirstItem.map;
+        if (!isOriginalFirst && newFirst.start) {
+            // Strip leading space tokens before the seq-item-ind
+            const dashIdx = newFirst.start.findIndex((t) => t.type === "seq-item-ind");
+            if (dashIdx > 0) {
+                // Remove all tokens before the dash that are space/newline
+                const toRemove = newFirst.start
+                    .slice(0, dashIdx)
+                    .every((t) => t.type === "space" || t.type === "newline");
+                if (toRemove) {
+                    newFirst.start.splice(0, dashIdx);
+                }
+            }
+        }
+    }
     // ── Stringify via CST (byte-identical for untouched content) ───────
     const result = tokens.map((t) => CST.stringify(t)).join("");
-    await writeFile(abs, result, "utf-8");
+    await atomicWriteFile(abs, result);
 }
 //# sourceMappingURL=writer.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrsf/cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "CLI and library for the Markdown Review Sidecar Format (MRSF)",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,6 +55,7 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "chalk": "^5.4.1",
+    "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "fastest-levenshtein": "^1.0.16",
     "js-yaml": "^4.1.0",