jg-plans 0.1.0 → 0.2.0

package/dist/edits/preparations.js

@@ -0,0 +1,159 @@
+import { randomUUID } from 'node:crypto';
+import { hashValue } from 'jg-crypto';
+import { parseMilestones, parsePlan } from "../documents/index.js";
+import { planErrors } from "../errors/index.js";
+import { PlanDocumentWriteSchema, PlanUpdateSchema, } from "../protocol/index.js";
+import { applyEdits, decodeSource, encodeSource, lineEnding, milestoneEdits, planEdits, } from "./utilities.js";
+/** Package-private expectation guard, also used on original read bytes by filesystem adapters. */
+export const assertSourceExpectation = (source, expected) => {
+    if (expected === undefined)
+        return;
+    const actual = source === null ? null : hashValue(typeof source === 'string' ? encodeSource(source) : source);
+    if (actual !== expected)
+        throw planErrors.create('sourceChanged');
+};
+const prepared = (before, source, diagnostics, assignedMilestoneIds = []) => ({
+    source,
+    changed: before !== source,
+    sha256: hashValue(encodeSource(source)),
+    diagnostics,
+    assignedMilestoneIds,
+});
+const validateSet = (observation, set) => {
+    if (observation.diagnostics.some((item) => item.code === 'INVALID_YAML' || item.code === 'UNTERMINATED_FRONTMATTER'))
+        throw planErrors.create('unsafeEdit', { data: { reason: 'invalid-serialized-frontmatter' } });
+    for (const [key, value] of Object.entries(set))
+        if (!Object.is(observation.metadata[key], value))
+            throw planErrors.create('unsafeEdit', {
+                data: { reason: 'unsupported-serialized-value', field: key },
+            });
+};
+/**
+ * Prepare one guarded metadata/marker patch entirely in memory, without policy updates or I/O.
+ * @param source Original selected document text.
+ * @param patch Explicit narrow patch and optional observed exact-byte SHA-256.
+ * @returns Prepared source, digest, diagnostics, and whether bytes would change.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
+ * - JG_PLANS_UNSAFE_EDIT: The requested edit is unsupported or ambiguous
+ * - JG_PLANS_SOURCE_CHANGED: The document changed before replacement
+ */
+export const preparePlanUpdate = (source, patch) => {
+    const validated = PlanUpdateSchema.safeParse(patch);
+    if (typeof source !== 'string' || !validated.success)
+        throw planErrors.create('invalidInput');
+    const request = validated.data;
+    const bytes = encodeSource(source);
+    assertSourceExpectation(source, request.expectedSha256);
+    const edits = request.document === 'plan' ? planEdits(source, request) : milestoneEdits(source, request);
+    const after = decodeSource(applyEdits(bytes, source, edits));
+    const observation = request.document === 'plan' ? parsePlan(after) : parseMilestones(after);
+    if (request.document === 'plan')
+        validateSet(observation, request.set);
+    return prepared(source, after, observation.diagnostics);
+};
+const assignMilestoneIds = (source) => {
+    const observation = parseMilestones(source);
+    if (observation.frontmatter && !observation.frontmatter.closed)
+        throw planErrors.create('unsafeEdit', { data: { reason: 'unterminated-frontmatter' } });
+    const ambiguous = new Set([
+        'INVALID_MILESTONE_ID',
+        'DUPLICATE_ID_MARKER',
+        'DUPLICATE_ID',
+        'DUPLICATE_ORDINAL',
+        'INVALID_ORDINAL',
+    ]);
+    if (observation.diagnostics.some((item) => ambiguous.has(item.code)))
+        throw planErrors.create('unsafeEdit', { data: { reason: 'ambiguous-milestone-identities' } });
+    const ids = new Set(observation.milestones.flatMap((entry) => (entry.id ? [entry.id.toLowerCase()] : [])));
+    const assigned = [];
+    const changes = [];
+    for (const entry of observation.milestones) {
+        if (entry.id !== null)
+            continue;
+        const status = entry.statusMarkers[0];
+        if (!status ||
+            !status.value ||
+            entry.statusMarkers.length !== 1 ||
+            source.slice(entry.headingEnd, status.lineStart).trim())
+            throw planErrors.create('unsafeEdit', { data: { reason: 'noncanonical-id-insertion' } });
+        let id;
+        do {
+            id = randomUUID();
+        } while (ids.has(id.toLowerCase()));
+        ids.add(id.toLowerCase());
+        assigned.push({ ordinal: entry.ordinal, id });
+        changes.push({ select: { ordinal: entry.ordinal }, set: { id } });
+    }
+    if (!changes.length)
+        return { source, assigned };
+    const after = decodeSource(applyEdits(encodeSource(source), source, milestoneEdits(source, { document: 'milestones', changes })));
+    return { source: after, assigned };
+};
+/**
+ * Prepare guarded body/metadata replacement or explicit milestone source/ID assignment in memory.
+ * A null source is accepted only for explicit absent milestone creation. No timestamps, revisions,
+ * identities, or completion are inferred; missing IDs are assigned only when requested.
+ * @param source Original selected document text, or null for absent milestones.
+ * @param input Explicit document replacement and required source expectation.
+ * @returns The exact source to persist once, its digest, diagnostics, and generated IDs.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
+ * - JG_PLANS_UNSAFE_EDIT: The requested edit is unsupported or ambiguous
+ * - JG_PLANS_SOURCE_CHANGED: The document changed before replacement
+ */
+export const preparePlanDocumentWrite = (source, input) => {
+    const validated = PlanDocumentWriteSchema.safeParse(input);
+    if ((source !== null && typeof source !== 'string') || !validated.success)
+        throw planErrors.create('invalidInput');
+    const request = validated.data;
+    if (request.document === 'plan' && source === null)
+        throw planErrors.create('invalidInput');
+    if (source !== null)
+        encodeSource(source);
+    assertSourceExpectation(source, request.expectedSha256);
+    if (request.document === 'milestones') {
+        encodeSource(request.source);
+        const assigned = request.assignMissingIds
+            ? assignMilestoneIds(request.source)
+            : { source: request.source, assigned: [] };
+        return prepared(source, assigned.source, parseMilestones(assigned.source).diagnostics, assigned.assigned);
+    }
+    const before = source;
+    const observation = parsePlan(before);
+    if (observation.frontmatter && !observation.frontmatter.closed)
+        throw planErrors.create('unsafeEdit', { data: { reason: 'unterminated-frontmatter' } });
+    encodeSource(request.body);
+    const bom = before.startsWith('\uFEFF') ? 1 : 0;
+    const bodyStart = observation.frontmatter?.end ?? bom;
+    // A metadata-free reader includes the encoding marker in body; never duplicate that marker.
+    const body = !observation.frontmatter && bom && request.body.startsWith('\uFEFF')
+        ? request.body.slice(1)
+        : request.body;
+    const eol = lineEnding(before);
+    const edits = request.set ? planEdits(before, { document: 'plan', set: request.set }) : [];
+    const insertion = !observation.frontmatter
+        ? edits.findIndex((edit) => edit.start === bodyStart && edit.end === bodyStart)
+        : -1;
+    let replacement = body;
+    if (insertion >= 0) {
+        const prefix = edits.splice(insertion, 1)[0].replacement;
+        replacement = prefix + (body && !/[\r\n]$/.test(prefix) ? eol : '') + body;
+    }
+    else if (observation.frontmatter &&
+        body &&
+        bodyStart === before.length &&
+        !/[\r\n]$/.test(before)) {
+        replacement = eol + body;
+    }
+    edits.push({ start: bodyStart, end: before.length, replacement });
+    const after = decodeSource(applyEdits(encodeSource(before), before, edits));
+    const result = parsePlan(after);
+    if (!observation.frontmatter && !request.set && result.frontmatter)
+        throw planErrors.create('unsafeEdit', { data: { reason: 'body-would-create-frontmatter' } });
+    if (request.set)
+        validateSet(result, request.set);
+    return prepared(before, after, result.diagnostics);
+};

package/dist/edits/types.d.ts

@@ -1,6 +1,20 @@
+import type { IDiagnostic } from '../protocol/index.ts';
 /** Internal UTF-16 source spans, converted to original byte offsets before replacement. */
 export type ITextEdit = {
     start: number;
     end: number;
     replacement: string;
 };
+/** IDs generated only by an explicit missing-ID assignment request. */
+export type IAssignedMilestoneId = {
+    ordinal: number;
+    id: string;
+};
+/** In-memory preparation performs no filesystem operation or implicit policy update. */
+export type IPreparedPlanEdit = {
+    source: string;
+    changed: boolean;
+    sha256: string;
+    diagnostics: IDiagnostic[];
+    assignedMilestoneIds: IAssignedMilestoneId[];
+};

package/dist/edits/utilities.d.ts

@@ -8,6 +8,7 @@ export declare const decodeSource: (bytes: Uint8Array) => string;
  * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
  */
 export declare const encodeSource: (source: string) => Buffer;
+export declare const lineEnding: (source: string) => string;
 /**
  * Prepare supported metadata edits without changing unrelated YAML or Markdown.
  * @throws

package/dist/edits/utilities.js

@@ -2,7 +2,14 @@ import { isMap, isScalar, parseDocument, Scalar, stringify } from 'yaml';
 import { parseMilestones, parsePlan, sourceLines } from "../documents/index.js";
 import { planErrors } from "../errors/index.js";
 /** Decode strictly while retaining an existing BOM character. */
-export const decodeSource = (bytes) => new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+export const decodeSource = (bytes) => {
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw planErrors.create('unsupportedEncoding');
+    }
+};
 /**
  * Reject unpaired surrogates rather than letting UTF-8 encoding replace them.
  * @throws
@@ -13,7 +20,7 @@ export const encodeSource = (source) => {
         throw planErrors.create('unsupportedEncoding');
     return Buffer.from(source, 'utf8');
 };
-const lineEnding = (source) => /\r\n|\n|\r/.exec(source)?.[0] ?? '\n';
+export const lineEnding = (source) => /\r\n|\n|\r/.exec(source)?.[0] ?? '\n';
 const scalarText = (value, style) => {
     if (typeof value === 'number')
         return String(value);

package/dist/errors/constants.d.ts

@@ -7,5 +7,7 @@ export declare const ERRORS: {
     readonly DESTINATION_EXISTS: "JG_PLANS_DESTINATION_EXISTS";
     readonly SOURCE_CHANGED: "JG_PLANS_SOURCE_CHANGED";
     readonly WRITE_FAILED: "JG_PLANS_WRITE_FAILED";
+    readonly LOCK_BUSY: "JG_PLANS_LOCK_BUSY";
+    readonly LOCK_FAILED: "JG_PLANS_LOCK_FAILED";
 };
-export declare const planErrors: import("jg-exception").IErrorCatalog<"invalidInput" | "readFailed" | "unsupportedEncoding" | "unsafeEdit" | "destinationExists" | "sourceChanged" | "writeFailed">;
+export declare const planErrors: import("jg-exception").IErrorCatalog<"invalidInput" | "readFailed" | "unsupportedEncoding" | "unsafeEdit" | "destinationExists" | "sourceChanged" | "writeFailed" | "lockBusy" | "lockFailed">;

package/dist/errors/constants.js

@@ -8,6 +8,8 @@ export const ERRORS = {
     DESTINATION_EXISTS: 'JG_PLANS_DESTINATION_EXISTS',
     SOURCE_CHANGED: 'JG_PLANS_SOURCE_CHANGED',
     WRITE_FAILED: 'JG_PLANS_WRITE_FAILED',
+    LOCK_BUSY: 'JG_PLANS_LOCK_BUSY',
+    LOCK_FAILED: 'JG_PLANS_LOCK_FAILED',
 };
 // Underlying errors may contain user paths or input snippets. Stable public messages
 // omit that text; causes retain diagnostics, and safe details are explicit data.
@@ -31,4 +33,6 @@ export const planErrors = defineErrorCatalog({
         message: 'The document changed before replacement',
     },
     writeFailed: { code: ERRORS.WRITE_FAILED, message: 'The plan document could not be written' },
+    lockBusy: { code: ERRORS.LOCK_BUSY, message: 'The plan document is locked' },
+    lockFailed: { code: ERRORS.LOCK_FAILED, message: 'The plan document lock operation failed' },
 });

package/dist/files/documents.d.ts

@@ -0,0 +1,46 @@
+import { type IPreparedPlanEdit } from '../edits/index.ts';
+import { type IPlanDocumentWrite, type IReadOptions, type IRemoveMilestones } from '../protocol/index.ts';
+import type { IPlanDocumentWriteResult, IRemoveMilestonesResult } from './types.ts';
+export type IOwnedFile = {
+    path: string;
+    dev: bigint;
+    ino: bigint;
+    bytes: Buffer;
+};
+/** Exclusive creation shared with createPlan; ownership is recorded before any write. */
+export declare const writeExclusive: (root: string, path: string, bytes: Buffer, owned: IOwnedFile[]) => Promise<void>;
+/** Package-private validation shared by all existing-directory mutations. */
+export declare const validateMutationOptions: (directory: string, options: IReadOptions) => void;
+/** Read exact bytes and guard them before decoding or preparing any new content. */
+export declare const readMutationSource: (directory: string, document: "plan" | "milestones", options: IReadOptions, expected: string | null | undefined) => Promise<Buffer | null>;
+/** Persist one prepared result once; null expectations use exclusive creation. */
+export declare const persistPrepared: (directory: string, document: "plan" | "milestones", before: Buffer | null, prepared: IPreparedPlanEdit) => Promise<IPlanDocumentWriteResult>;
+/**
+ * Guard and replace a plan body/core metadata or complete milestone document under its shared lock.
+ * Only the selected document is read; unrelated malformed documents do not block an operation.
+ * Expected null means absent milestones, never overwriting an existing file. No policy is inferred.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * - JG_PLANS_READ_FAILED: The selected document could not be read
+ * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
+ * - JG_PLANS_UNSAFE_EDIT: The requested edit is unsupported or ambiguous
+ * - JG_PLANS_SOURCE_CHANGED: The document changed before replacement
+ * - JG_PLANS_WRITE_FAILED: The plan document could not be written
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
+ */
+export declare const writePlanDocument: (directory: string, input: IPlanDocumentWrite, options?: IReadOptions) => Promise<IPlanDocumentWriteResult>;
+/**
+ * Remove only milestones.md with an explicit exact-byte expectation under its shared lock.
+ * Missing or changed files fail. No plan, directory, or history is removed. A final check detects
+ * observed external edits; nonparticipating writers still have a check-to-unlink race.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * - JG_PLANS_READ_FAILED: The selected document could not be read
+ * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
+ * - JG_PLANS_SOURCE_CHANGED: The document changed before replacement
+ * - JG_PLANS_WRITE_FAILED: The plan document could not be written
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
+ */
+export declare const removeMilestones: (directory: string, input: IRemoveMilestones, options?: IReadOptions) => Promise<IRemoveMilestonesResult>;

package/dist/files/documents.js

@@ -0,0 +1,176 @@
+import { lstat, open, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getErrorCode } from 'jg-exception';
+import { assertNoLinksBelow, readBoundedFile, writeFileAtomicIfUnchanged } from 'jg-fs';
+import { z } from 'zod';
+import { decodeSource, encodeSource, preparePlanDocumentWrite, } from "../edits/index.js";
+import { assertSourceExpectation } from "../edits/preparations.js";
+import { planErrors } from "../errors/index.js";
+import { DEFAULT_MAX_BYTES, PlanDocumentWriteSchema, ReadOptionsSchema, RemoveMilestonesSchema, } from "../protocol/index.js";
+import { withPlanDocumentLocks } from "./locks.js";
+/** Exclusive creation shared with createPlan; ownership is recorded before any write. */
+export const writeExclusive = async (root, path, bytes, owned) => {
+    await assertNoLinksBelow(root, path);
+    const handle = await open(path, 'wx');
+    try {
+        const stat = await handle.stat({ bigint: true });
+        owned.push({ path, dev: stat.dev, ino: stat.ino, bytes });
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Package-private validation shared by all existing-directory mutations. */
+export const validateMutationOptions = (directory, options) => {
+    if (!z
+        .string()
+        .min(1)
+        .refine((value) => !value.includes('\0'))
+        .safeParse(directory).success ||
+        !ReadOptionsSchema.safeParse(options).success)
+        throw planErrors.create('invalidInput');
+};
+/** Read exact bytes and guard them before decoding or preparing any new content. */
+export const readMutationSource = async (directory, document, options, expected) => {
+    const path = join(directory, `${document}.md`);
+    let before;
+    try {
+        await assertNoLinksBelow(directory, path);
+        before = await readBoundedFile(path, options.maxBytes ?? DEFAULT_MAX_BYTES);
+    }
+    catch (cause) {
+        const reason = getErrorCode(cause);
+        if (expected !== undefined && (reason === 'NON_EXISTENT_FILE' || reason === 'ENOENT'))
+            before = null;
+        else
+            throw planErrors.create('readFailed', { cause, ...(reason ? { data: { reason } } : {}) });
+    }
+    assertSourceExpectation(before, expected);
+    return before;
+};
+/** Persist one prepared result once; null expectations use exclusive creation. */
+export const persistPrepared = async (directory, document, before, prepared) => {
+    if (prepared.changed) {
+        try {
+            const path = join(directory, `${document}.md`);
+            await assertNoLinksBelow(directory, path);
+            if (before === null) {
+                const owned = [];
+                try {
+                    await writeExclusive(directory, path, encodeSource(prepared.source), owned);
+                }
+                catch (cause) {
+                    const cleanupFailedPaths = [];
+                    for (const file of owned) {
+                        try {
+                            const stat = await lstat(file.path, { bigint: true });
+                            const bytes = await readBoundedFile(file.path, Math.max(1, file.bytes.length));
+                            if (!stat.isFile() ||
+                                stat.dev !== file.dev ||
+                                stat.ino !== file.ino ||
+                                !bytes.equals(file.bytes.subarray(0, bytes.length)))
+                                cleanupFailedPaths.push(file.path);
+                            else
+                                await unlink(file.path);
+                        }
+                        catch (cleanupCause) {
+                            if (getErrorCode(cleanupCause) !== 'ENOENT' &&
+                                getErrorCode(cleanupCause) !== 'NON_EXISTENT_FILE')
+                                cleanupFailedPaths.push(file.path);
+                        }
+                    }
+                    if (getErrorCode(cause) === 'EEXIST')
+                        throw planErrors.create('sourceChanged', { cause });
+                    throw planErrors.create('writeFailed', {
+                        cause,
+                        ...(cleanupFailedPaths.length ? { data: { cleanupFailedPaths } } : {}),
+                    });
+                }
+            }
+            else
+                await writeFileAtomicIfUnchanged(path, encodeSource(prepared.source), before);
+        }
+        catch (cause) {
+            if (getErrorCode(cause)?.startsWith('JG_PLANS_'))
+                throw cause;
+            if (getErrorCode(cause) === 'FILE_CHANGED')
+                throw planErrors.create('sourceChanged', { cause });
+            throw planErrors.create('writeFailed', { cause });
+        }
+    }
+    return {
+        directory,
+        document,
+        changed: prepared.changed,
+        sha256: prepared.sha256,
+        diagnostics: prepared.diagnostics,
+        assignedMilestoneIds: prepared.assignedMilestoneIds,
+    };
+};
+/**
+ * Guard and replace a plan body/core metadata or complete milestone document under its shared lock.
+ * Only the selected document is read; unrelated malformed documents do not block an operation.
+ * Expected null means absent milestones, never overwriting an existing file. No policy is inferred.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * - JG_PLANS_READ_FAILED: The selected document could not be read
+ * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
+ * - JG_PLANS_UNSAFE_EDIT: The requested edit is unsupported or ambiguous
+ * - JG_PLANS_SOURCE_CHANGED: The document changed before replacement
+ * - JG_PLANS_WRITE_FAILED: The plan document could not be written
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
+ */
+export const writePlanDocument = async (directory, input, options = {}) => {
+    validateMutationOptions(directory, options);
+    const parsed = PlanDocumentWriteSchema.safeParse(input);
+    if (!parsed.success)
+        throw planErrors.create('invalidInput');
+    const request = parsed.data;
+    return withPlanDocumentLocks(directory, [request.document], async (selected) => {
+        const before = await readMutationSource(selected, request.document, options, request.expectedSha256);
+        const prepared = preparePlanDocumentWrite(before === null ? null : decodeSource(before), request);
+        return persistPrepared(selected, request.document, before, prepared);
+    });
+};
+/**
+ * Remove only milestones.md with an explicit exact-byte expectation under its shared lock.
+ * Missing or changed files fail. No plan, directory, or history is removed. A final check detects
+ * observed external edits; nonparticipating writers still have a check-to-unlink race.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * - JG_PLANS_READ_FAILED: The selected document could not be read
+ * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
+ * - JG_PLANS_SOURCE_CHANGED: The document changed before replacement
+ * - JG_PLANS_WRITE_FAILED: The plan document could not be written
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
+ */
+export const removeMilestones = async (directory, input, options = {}) => {
+    validateMutationOptions(directory, options);
+    const parsed = RemoveMilestonesSchema.safeParse(input);
+    if (!parsed.success)
+        throw planErrors.create('invalidInput');
+    return withPlanDocumentLocks(directory, ['milestones'], async (selected) => {
+        const before = await readMutationSource(selected, 'milestones', options, parsed.data.expectedSha256);
+        decodeSource(before);
+        await readMutationSource(selected, 'milestones', options, parsed.data.expectedSha256);
+        try {
+            await unlink(join(selected, 'milestones.md'));
+        }
+        catch (cause) {
+            throw planErrors.create(getErrorCode(cause) === 'ENOENT' ? 'sourceChanged' : 'writeFailed', {
+                cause,
+            });
+        }
+        return {
+            directory: selected,
+            document: 'milestones',
+            changed: true,
+            sha256: null,
+            diagnostics: [],
+        };
+    });
+};

package/dist/files/index.d.ts

@@ -1,4 +1,6 @@
 export { inspectPlan } from './utilities.ts';
 export { createPlan, updatePlan } from './mutations.ts';
+export { writePlanDocument, removeMilestones } from './documents.ts';
+export { withPlanDocumentLocks } from './locks.ts';
 export type { IDocumentRead, IPlanInspection } from './types.ts';
-export type { IPlanCreation, IPlanUpdateResult } from './types.ts';
+export type { IPlanCreation, IPlanUpdateResult, IPlanDocumentWriteResult, IRemoveMilestonesResult, } from './types.ts';

package/dist/files/index.js

@@ -1,2 +1,4 @@
 export { inspectPlan } from "./utilities.js";
 export { createPlan, updatePlan } from "./mutations.js";
+export { writePlanDocument, removeMilestones } from "./documents.js";
+export { withPlanDocumentLocks } from "./locks.js";

package/dist/files/locks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Serialize participating local-filesystem writers using canonical document lock directories.
+ * Acquire plan before milestones and release in reverse order. Busy/dead owners fail immediately;
+ * recovery is an explicit operator decision. Use preparation and your own persistence inside the
+ * callback; nesting a filesystem mutation here would attempt to acquire the same lock again.
+ * @param directory Existing selected directory; aliases share its canonical lock namespace.
+ * @param documents Nonempty unique selection of plan and/or milestones, in any input order.
+ * @param operation One bounded operation, receiving the canonical directory. Never hold a lock across agent turns.
+ * @returns The callback's result after every lock is released.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
+ * - Callback errors propagate after successful lock release.
+ */
+export declare const withPlanDocumentLocks: <T>(directory: string, documents: readonly ("plan" | "milestones")[], operation: (directory: string) => T | Promise<T>) => Promise<T>;

package/dist/files/locks.js

@@ -0,0 +1,127 @@
+import { realpath } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { getErrorCode } from 'jg-exception';
+import { acquireLock } from 'jg-fs';
+import { z } from 'zod';
+import { planErrors } from "../errors/index.js";
+const DocumentsSchema = z
+    .array(z.enum(['plan', 'milestones']))
+    .min(1)
+    .refine((values) => new Set(values).size === values.length);
+const DirectorySchema = z
+    .string()
+    .min(1)
+    .refine((value) => !value.includes('\0'));
+const BusyReasonSchema = z.object({
+    data: z.object({
+        reason: z.enum([
+            'held',
+            'owner-gone',
+            'other-host',
+            'ownerless',
+            'recovery-in-progress',
+            'unexpected-entries',
+        ]),
+    }),
+});
+const reason = (cause) => {
+    const busy = BusyReasonSchema.safeParse(cause);
+    return busy.success ? busy.data.data.reason : (getErrorCode(cause) ?? 'unknown');
+};
+/**
+ * Serialize participating local-filesystem writers using canonical document lock directories.
+ * Acquire plan before milestones and release in reverse order. Busy/dead owners fail immediately;
+ * recovery is an explicit operator decision. Use preparation and your own persistence inside the
+ * callback; nesting a filesystem mutation here would attempt to acquire the same lock again.
+ * @param directory Existing selected directory; aliases share its canonical lock namespace.
+ * @param documents Nonempty unique selection of plan and/or milestones, in any input order.
+ * @param operation One bounded operation, receiving the canonical directory. Never hold a lock across agent turns.
+ * @returns The callback's result after every lock is released.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
+ * - Callback errors propagate after successful lock release.
+ */
+export const withPlanDocumentLocks = async (directory, documents, operation) => {
+    const selected = DocumentsSchema.safeParse(documents);
+    if (!DirectorySchema.safeParse(directory).success ||
+        !selected.success ||
+        typeof operation !== 'function')
+        throw planErrors.create('invalidInput');
+    let canonical;
+    try {
+        canonical = await realpath(resolve(directory));
+    }
+    catch (cause) {
+        throw planErrors.create('lockFailed', {
+            cause,
+            data: {
+                phase: 'canonicalize',
+                reason: reason(cause),
+                mutationOutcome: 'not-applied',
+                operationCompleted: false,
+            },
+        });
+    }
+    const held = [];
+    let started = false;
+    let completed = false;
+    let failed = false;
+    let failure;
+    let result;
+    try {
+        for (const document of ['plan', 'milestones']) {
+            if (!selected.data.includes(document))
+                continue;
+            try {
+                held.push({
+                    document,
+                    lock: await acquireLock(join(canonical, `.${document}.md.jg-plans.lock`)),
+                });
+            }
+            catch (cause) {
+                throw planErrors.create(getErrorCode(cause) === 'LOCK_BUSY' ? 'lockBusy' : 'lockFailed', {
+                    cause,
+                    data: {
+                        document,
+                        phase: 'acquire',
+                        reason: reason(cause),
+                        mutationOutcome: 'not-applied',
+                        operationCompleted: false,
+                    },
+                });
+            }
+        }
+        started = true;
+        result = await operation(canonical);
+        completed = true;
+    }
+    catch (cause) {
+        failed = true;
+        failure = cause;
+    }
+    const releases = [];
+    for (const entry of held.reverse()) {
+        try {
+            await entry.lock.release();
+        }
+        catch (cause) {
+            releases.push({ document: entry.document, cause });
+        }
+    }
+    if (releases.length)
+        throw planErrors.create('lockFailed', {
+            cause: new AggregateError([...(failed ? [failure] : []), ...releases.map((entry) => entry.cause)], 'The document operation or lock release failed'),
+            data: {
+                phase: 'release',
+                documents: releases.map((entry) => entry.document),
+                reason: reason(releases[0].cause),
+                operationCompleted: completed,
+                mutationOutcome: started ? 'uncertain' : 'not-applied',
+            },
+        });
+    if (failed)
+        throw failure;
+    return result;
+};

package/dist/files/mutations.d.ts

@@ -9,13 +9,15 @@ import type { IPlanCreation, IPlanUpdateResult } from './types.ts';
  * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
  * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
  * - JG_PLANS_DESTINATION_EXISTS: The plan destination already exists
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
  * - JG_PLANS_WRITE_FAILED: The plan document could not be written
  */
 export declare const createPlan: (options: ICreatePlanOptions) => Promise<IPlanCreation>;
 /**
- * Apply one explicit metadata or marker patch, preserving every other source byte.
- * Callers serialize the whole read/edit/write operation. The final byte comparison
- * detects observed changes but has a comparison-to-rename race; no retry or lock is used.
+ * Apply an explicit narrow patch under the shared selected-document lock.
+ * Guard optional observed bytes before preparation; unchanged output is never replaced.
+ * Nonparticipating editors retain a final comparison-to-rename race.
  * @throws
  * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
  * - JG_PLANS_READ_FAILED: The selected document could not be read
@@ -23,5 +25,7 @@ export declare const createPlan: (options: ICreatePlanOptions) => Promise<IPlanC
  * - JG_PLANS_UNSAFE_EDIT: The requested edit is unsupported or ambiguous
  * - JG_PLANS_SOURCE_CHANGED: The document changed before replacement
  * - JG_PLANS_WRITE_FAILED: The plan document could not be written
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
  */
 export declare const updatePlan: (directory: string, patch: IPlanUpdate, options?: IReadOptions) => Promise<IPlanUpdateResult>;