@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/core/init-project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-project.js","sourceRoot":"","sources":["../../src/core/init-project.ts"],"names":[],"mappings":"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"}

package/dist/core/item-attachments-error.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The typed failure of an attachment operation (STORY-431).
+ */
+export type AttachmentErrorCode = 'INVALID_NAME' | 'RESERVED_NAME' | 'ITEM_NOT_FOUND' | 'EXISTS' | 'NOT_FOUND' | 'NOT_A_FILE' | 'TOO_LARGE' | 'SOURCE_UNREADABLE'
+/** A lock (antivirus scan, indexer, open handle) blocked a write, rename or delete. */
+ | 'IN_USE'
+/** Any other failure while writing, renaming or deleting. */
+ | 'WRITE_FAILED';
+export declare class AttachmentError extends Error {
+    readonly code: AttachmentErrorCode;
+    readonly itemId: string;
+    readonly attachment?: string | undefined;
+    /** A file left under another name when a rollback failed; the original error is thrown. */
+    readonly stranded?: string | undefined;
+    constructor(code: AttachmentErrorCode, message: string, itemId: string, attachment?: string | undefined, 
+    /** A file left under another name when a rollback failed; the original error is thrown. */
+    stranded?: string | undefined);
+}
+//# sourceMappingURL=item-attachments-error.d.ts.map

package/dist/core/item-attachments-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-attachments-error.d.ts","sourceRoot":"","sources":["../../src/core/item-attachments-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,WAAW,GACX,mBAAmB;AACrB,uFAAuF;GACrF,QAAQ;AACV,6DAA6D;GAC3D,cAAc,CAAC;AAEnB,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,IAAI,EAAE,mBAAmB;IAElC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM;IAC5B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM;IAN5B,YACW,IAAI,EAAE,mBAAmB,EAClC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,YAAA;IAC5B,2FAA2F;IAClF,QAAQ,CAAC,EAAE,MAAM,YAAA,EAI3B;CACF"}

package/dist/core/item-attachments-error.js

@@ -0,0 +1,23 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The typed failure of an attachment operation (STORY-431).
+ */
+export class AttachmentError extends Error {
+    code;
+    itemId;
+    attachment;
+    stranded;
+    constructor(code, message, itemId, attachment, 
+    /** A file left under another name when a rollback failed; the original error is thrown. */
+    stranded) {
+        super(message);
+        this.code = code;
+        this.itemId = itemId;
+        this.attachment = attachment;
+        this.stranded = stranded;
+        this.name = 'AttachmentError';
+    }
+}
+//# sourceMappingURL=item-attachments-error.js.map

package/dist/core/item-attachments-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-attachments-error.js","sourceRoot":"","sources":["../../src/core/item-attachments-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAE7B,IAAI;IAEJ,MAAM;IACN,UAAU;IAEV,QAAQ;IANnB,YACW,IAAyB,EAClC,OAAe,EACN,MAAc,EACd,UAAmB;IAC5B,2FAA2F;IAClF,QAAiB;QAE1B,KAAK,CAAC,OAAO,CAAC,CAAC;oBAPN,IAAI;sBAEJ,MAAM;0BACN,UAAU;wBAEV,QAAQ;QAGjB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}

package/dist/core/item-attachments-io.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * File-system steps of the attachment operations (STORY-431): exclusive publish, move,
+ * retrying delete and a rollback that never hides the original error.
+ *
+ * Publishing exclusively (hard link, or a copy with COPYFILE_EXCL where links are not
+ * supported) means a file another process created between the name check and the publish
+ * is refused with EXISTS instead of being replaced.
+ */
+import { type Stats } from 'node:fs';
+import { AttachmentError } from './item-attachments-error.js';
+/** True for the errors a held file raises on Windows. */
+export declare function isLockError(error: unknown): boolean;
+/** The typed error for a raw file-system failure of `name`. */
+export declare function mapFsError(error: unknown, id: string, name: string): AttachmentError;
+/** `lstatSync` whose raw failure (a file deleted a moment ago) becomes a typed error. */
+export declare function statEntry(path: string, id: string, name: string): Stats;
+/** `unlinkSync` that retries a lock error a bounded number of times (10 to 100 ms pauses). */
+export declare function unlinkWithRetrySync(path: string, beforeUnlink?: () => void): void;
+/**
+ * Write `content` to `dest` only when `dest` does not exist: a temp file in the same
+ * folder, then an exclusive publish, then the temp file is removed.
+ */
+export declare function writeBytesExclusive(dest: string, content: Uint8Array | string, id: string, name: string, assertStorage?: () => void): void;
+/**
+ * Move `source` to `dest` without replacing an existing `dest`. A case-only rename of the
+ * same entry keeps the atomic rename (a link would see the entry itself as a clash).
+ */
+export declare function moveExclusive(source: string, dest: string, id: string, name: string, caseOnly: boolean, assertStorage?: () => void): void;
+/**
+ * Run `undo` after a failed step. A rollback that throws too does not replace `original`:
+ * the original is rethrown with `stranded` named in its message and as a property.
+ */
+export declare function rethrowAfterRollback(original: unknown, stranded: string, undo: () => void): never;
+//# sourceMappingURL=item-attachments-io.d.ts.map

package/dist/core/item-attachments-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-attachments-io.d.ts","sourceRoot":"","sources":["../../src/core/item-attachments-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAKL,KAAK,KAAK,EAGX,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAW9D,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGnD;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAOpF;AAED,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAMvE;AASD,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAWjF;AA8BD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,UAAU,GAAG,MAAM,EAC5B,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,aAAa,CAAC,EAAE,MAAM,IAAI,GACzB,IAAI,CAkBN;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,EACjB,aAAa,CAAC,EAAE,MAAM,IAAI,GACzB,IAAI,CAkBN;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,KAAK,CAWjG"}

package/dist/core/item-attachments-io.js

@@ -0,0 +1,156 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * File-system steps of the attachment operations (STORY-431): exclusive publish, move,
+ * retrying delete and a rollback that never hides the original error.
+ *
+ * Publishing exclusively (hard link, or a copy with COPYFILE_EXCL where links are not
+ * supported) means a file another process created between the name check and the publish
+ * is refused with EXISTS instead of being replaced.
+ */
+import { randomBytes } from 'node:crypto';
+import { constants, copyFileSync, linkSync, lstatSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { renameWithRetrySync } from '../utils/atomic-write.js';
+import { AttachmentError } from './item-attachments-error.js';
+const LOCK_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const NO_LINK_CODES = new Set(['EPERM', 'ENOTSUP', 'EXDEV', 'EOPNOTSUPP', 'ENOSYS']);
+const UNLINK_ATTEMPTS = 8;
+const codeOf = (error) => {
+    const code = error?.code;
+    return typeof code === 'string' ? code : undefined;
+};
+/** True for the errors a held file raises on Windows. */
+export function isLockError(error) {
+    const code = codeOf(error);
+    return code !== undefined && LOCK_CODES.has(code);
+}
+/** The typed error for a raw file-system failure of `name`. */
+export function mapFsError(error, id, name) {
+    if (error instanceof AttachmentError)
+        return error;
+    if (codeOf(error) === 'ENOENT') {
+        return new AttachmentError('NOT_FOUND', `${name} was not found`, id, name);
+    }
+    const code = isLockError(error) ? 'IN_USE' : 'WRITE_FAILED';
+    return new AttachmentError(code, `${name}: ${error}`, id, name);
+}
+/** `lstatSync` whose raw failure (a file deleted a moment ago) becomes a typed error. */
+export function statEntry(path, id, name) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        throw mapFsError(error, id, name);
+    }
+}
+const existsError = (id, name) => new AttachmentError('EXISTS', `${name} already exists`, id, name);
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** `unlinkSync` that retries a lock error a bounded number of times (10 to 100 ms pauses). */
+export function unlinkWithRetrySync(path, beforeUnlink) {
+    for (let attempt = 1;; attempt++) {
+        beforeUnlink?.();
+        try {
+            unlinkSync(path);
+            return;
+        }
+        catch (error) {
+            if (attempt >= UNLINK_ATTEMPTS || !isLockError(error))
+                throw error;
+            sleepSync(Math.min(100, 10 * 2 ** (attempt - 1)));
+        }
+    }
+}
+/** Link `source` to `dest` without replacing; copy exclusively where links are unsupported. */
+function linkExclusive(source, dest, id, name, beforePublish) {
+    beforePublish?.();
+    try {
+        linkSync(source, dest);
+        return;
+    }
+    catch (error) {
+        const code = codeOf(error);
+        if (code === 'EEXIST')
+            throw existsError(id, name);
+        if (code === undefined || !NO_LINK_CODES.has(code))
+            throw error;
+    }
+    beforePublish?.();
+    try {
+        copyFileSync(source, dest, constants.COPYFILE_EXCL);
+    }
+    catch (error) {
+        if (codeOf(error) === 'EEXIST')
+            throw existsError(id, name);
+        throw error;
+    }
+}
+let tempCounter = 0;
+/**
+ * Write `content` to `dest` only when `dest` does not exist: a temp file in the same
+ * folder, then an exclusive publish, then the temp file is removed.
+ */
+export function writeBytesExclusive(dest, content, id, name, assertStorage) {
+    tempCounter += 1;
+    const tmp = join(dirname(dest), `.${process.pid}.${tempCounter}.${randomBytes(4).toString('hex')}.tmp`);
+    try {
+        assertStorage?.();
+        writeFileSync(tmp, content);
+        linkExclusive(tmp, dest, id, name, assertStorage);
+    }
+    finally {
+        try {
+            assertStorage?.();
+            unlinkSync(tmp);
+        }
+        catch {
+            /* never clean up through changed storage; the original temp may remain */
+        }
+    }
+}
+/**
+ * Move `source` to `dest` without replacing an existing `dest`. A case-only rename of the
+ * same entry keeps the atomic rename (a link would see the entry itself as a clash).
+ */
+export function moveExclusive(source, dest, id, name, caseOnly, assertStorage) {
+    if (caseOnly) {
+        renameWithRetrySync(source, dest, assertStorage);
+        return;
+    }
+    linkExclusive(source, dest, id, name, assertStorage);
+    try {
+        unlinkWithRetrySync(source, assertStorage);
+    }
+    catch (error) {
+        // The source stays locked: drop the new name again so no second hard link is left behind.
+        try {
+            assertStorage?.();
+            unlinkSync(dest);
+        }
+        catch {
+            /* best effort */
+        }
+        throw error;
+    }
+}
+/**
+ * Run `undo` after a failed step. A rollback that throws too does not replace `original`:
+ * the original is rethrown with `stranded` named in its message and as a property.
+ */
+export function rethrowAfterRollback(original, stranded, undo) {
+    try {
+        undo();
+    }
+    catch {
+        const note = `${stranded} stayed under its new name because the rollback failed`;
+        const error = original instanceof Error ? original : new Error(String(original));
+        error.message = `${error.message} (${note})`;
+        error.stranded = stranded;
+        throw error;
+    }
+    throw original;
+}
+//# sourceMappingURL=item-attachments-io.js.map

package/dist/core/item-attachments-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-attachments-io.js","sourceRoot":"","sources":["../../src/core/item-attachments-io.ts"],"names":[],"mappings":"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"}

package/dist/core/item-attachments-storage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Attachment storage belongs to the named item, not merely somewhere inside .devsteps.
+ * Reject redirected storage components and retain their identities for publication checks.
+ * These path-based checks narrow replacement windows; they are not an OS-level race lock.
+ */
+export interface AttachmentStorage {
+    dir: string;
+    assertUnchanged: () => void;
+}
+/** Validate every storage component before even following the item's metadata marker. */
+export declare function captureAttachmentStorage(devstepsDir: string, id: string): AttachmentStorage;
+//# sourceMappingURL=item-attachments-storage.d.ts.map

package/dist/core/item-attachments-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-attachments-storage.d.ts","sourceRoot":"","sources":["../../src/core/item-attachments-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,yFAAyF;AACzF,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,iBAAiB,CAwE3F"}

package/dist/core/item-attachments-storage.js

@@ -0,0 +1,81 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Attachment storage belongs to the named item, not merely somewhere inside .devsteps.
+ * Reject redirected storage components and retain their identities for publication checks.
+ * These path-based checks narrow replacement windows; they are not an OS-level race lock.
+ */
+import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, relative, resolve } from 'node:path';
+import { AttachmentError } from './item-attachments-error.js';
+import { itemPaths } from './item-paths.js';
+/** Validate every storage component before even following the item's metadata marker. */
+export function captureAttachmentStorage(devstepsDir, id) {
+    let paths;
+    try {
+        paths = itemPaths(resolve(devstepsDir), id);
+    }
+    catch {
+        throw new AttachmentError('ITEM_NOT_FOUND', `Item not found: ${id}`, id);
+    }
+    const root = resolve(devstepsDir);
+    const components = [
+        dirname(root),
+        root,
+        dirname(dirname(paths.dir)),
+        dirname(paths.dir),
+        paths.dir,
+    ];
+    const changed = () => new AttachmentError('INVALID_NAME', `Attachment storage for ${id} is redirected or changed`, id);
+    const inspect = (path, project) => {
+        // The served project may itself have a canonical path different from its spelling.
+        // Storage components below that project must be real directories, including junctions.
+        const stat = project ? statSync(path) : lstatSync(path);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw changed();
+        return { path, canonical: realpathSync.native(path), dev: stat.dev, ino: stat.ino };
+    };
+    let identities;
+    try {
+        identities = [];
+        for (const [index, path] of components.entries()) {
+            const current = inspect(path, index === 0);
+            const parent = identities.at(-1);
+            if (parent && relative(parent.canonical, current.canonical) !== basename(current.path)) {
+                throw changed();
+            }
+            identities.push(current);
+        }
+    }
+    catch (error) {
+        if (error instanceof AttachmentError)
+            throw error;
+        if (error.code === 'ENOENT') {
+            throw new AttachmentError('ITEM_NOT_FOUND', `Item not found: ${id}`, id);
+        }
+        throw changed();
+    }
+    const assertUnchanged = () => {
+        try {
+            for (const [index, expected] of identities.entries()) {
+                const current = inspect(expected.path, index === 0);
+                if (current.dev !== expected.dev ||
+                    current.ino !== expected.ino ||
+                    current.canonical !== expected.canonical) {
+                    throw changed();
+                }
+            }
+        }
+        catch {
+            throw changed();
+        }
+    };
+    assertUnchanged();
+    if (!existsSync(paths.metadata)) {
+        throw new AttachmentError('ITEM_NOT_FOUND', `Item not found: ${id}`, id);
+    }
+    assertUnchanged();
+    return { dir: paths.dir, assertUnchanged };
+}
+//# sourceMappingURL=item-attachments-storage.js.map

package/dist/core/item-attachments-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-attachments-storage.js","sourceRoot":"","sources":["../../src/core/item-attachments-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAc5C,yFAAyF;AACzF,MAAM,UAAU,wBAAwB,CAAC,WAAmB,EAAE,EAAU;IACtE,IAAI,KAAmC,CAAC;IACxC,IAAI,CAAC;QACH,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,eAAe,CAAC,gBAAgB,EAAE,mBAAmB,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAClC,MAAM,UAAU,GAAG;QACjB,OAAO,CAAC,IAAI,CAAC;QACb,IAAI;QACJ,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;QAClB,KAAK,CAAC,GAAG;KACV,CAAC;IACF,MAAM,OAAO,GAAG,GAAG,EAAE,CACnB,IAAI,eAAe,CACjB,cAAc,EACd,0BAA0B,EAAE,2BAA2B,EACvD,EAAE,CACH,CAAC;IAEJ,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,OAAgB,EAAqB,EAAE;QACpE,mFAAmF;QACnF,uFAAuF;QACvF,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,cAAc,EAAE;YAAE,MAAM,OAAO,EAAE,CAAC;QAClE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;IACtF,CAAC,CAAC;IAEF,IAAI,UAA+B,CAAC;IACpC,IAAI,CAAC;QACH,UAAU,GAAG,EAAE,CAAC;QAChB,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;YACjD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC;YAC3C,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YACjC,IAAI,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvF,MAAM,OAAO,EAAE,CAAC;YAClB,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,eAAe;YAAE,MAAM,KAAK,CAAC;QAClD,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,MAAM,IAAI,eAAe,CAAC,gBAAgB,EAAE,mBAAmB,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,OAAO,EAAE,CAAC;IAClB,CAAC;IAED,MAAM,eAAe,GAAG,GAAS,EAAE;QACjC,IAAI,CAAC;YACH,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;gBACrD,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC;gBACpD,IACE,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,GAAG;oBAC5B,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,GAAG;oBAC5B,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS,EACxC,CAAC;oBACD,MAAM,OAAO,EAAE,CAAC;gBAClB,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,OAAO,EAAE,CAAC;QAClB,CAAC;IACH,CAAC,CAAC;IAEF,eAAe,EAAE,CAAC;IAClB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,eAAe,CAAC,gBAAgB,EAAE,mBAAmB,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,eAAe,EAAE,CAAC;IAClB,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,eAAe,EAAE,CAAC;AAC7C,CAAC"}

package/dist/core/item-attachments.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Add, rename and remove item attachments (STORY-431).
+ *
+ * The item folder is the record (DEC-029): adding a file never edits `<ID>.md`,
+ * renaming rewrites the bare-name links that pointed at the old name, and removing
+ * reports the links it leaves dangling without touching the document.
+ *
+ * Attachment writes carry no stamp — only the item files do (STORY-428) — so a name that
+ * another process creates between the existence check and the publish is guarded by an
+ * exclusive publish (hard link or exclusive copy): add without overwrite and rename refuse
+ * it with EXISTS and leave the other file intact. Only an explicit overwrite replaces.
+ */
+import { AttachmentError, type AttachmentErrorCode } from './item-attachments-error.js';
+import { type ItemAttachment } from './item-paths.js';
+export declare const MAX_ATTACHMENT_BYTES: number;
+export declare const MAX_ATTACHMENT_NAME = 120;
+export { AttachmentError, type AttachmentErrorCode };
+export interface AddAttachmentOptions {
+    overwrite?: boolean;
+}
+export interface AddAttachmentResult {
+    attachment: ItemAttachment;
+    replaced: boolean;
+}
+export interface RenameAttachmentResult {
+    attachment: ItemAttachment;
+    linksUpdated: number;
+}
+export interface RemoveAttachmentResult {
+    removed: string;
+    danglingLinks: number;
+}
+/** null when valid, else the code and message. Pure, no fs. */
+export declare function validateAttachmentName(id: string, name: string): {
+    code: AttachmentErrorCode;
+    message: string;
+} | null;
+/** First free name: `shot.png` becomes `shot-2.png`, `shot-3.png`, ... */
+export declare function uniqueAttachmentName(devstepsDir: string, id: string, name: string): string;
+/** Bytes/text from a caller. Refuses an existing name unless `overwrite`. */
+export declare function addAttachmentContent(devstepsDir: string, id: string, name: string, content: Uint8Array | string, options?: AddAttachmentOptions): AddAttachmentResult;
+/** Copy a file the user picked: a regular file only, its size checked before reading. */
+export declare function importAttachmentFile(devstepsDir: string, id: string, sourcePath: string, options?: AddAttachmentOptions & {
+    name?: string;
+}): AddAttachmentResult;
+/**
+ * The on-disk path of an existing attachment, for open and reveal. Applies the lenient
+ * rename-from and remove rules and confines the result to the item folder.
+ */
+export declare function attachmentFilePath(devstepsDir: string, id: string, name: string): string;
+export declare function renameAttachment(devstepsDir: string, id: string, from: string, to: string, options?: {
+    updateLinks?: boolean;
+}): RenameAttachmentResult;
+export declare function removeAttachment(devstepsDir: string, id: string, name: string): RemoveAttachmentResult;
+//# sourceMappingURL=item-attachments.d.ts.map

package/dist/core/item-attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-attachments.d.ts","sourceRoot":"","sources":["../../src/core/item-attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAUxF,OAAO,EAAE,KAAK,cAAc,EAAuB,MAAM,iBAAiB,CAAC;AAI3E,eAAO,MAAM,oBAAoB,QAAmB,CAAC;AACrD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,OAAO,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AACD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,cAAc,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;CACnB;AACD,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,cAAc,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;CACtB;AACD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB;AAUD,+DAA+D;AAC/D,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAuBvD;AAwCD,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAW1F;AAgBD,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,UAAU,GAAG,MAAM,EAC5B,OAAO,GAAE,oBAAyB,GACjC,mBAAmB,CAGrB;AA4CD,yFAAyF;AACzF,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,oBAAoB,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,mBAAmB,CAsBrB;AA8DD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIxF;AAED,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,sBAAsB,CA6CxB;AAED,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX,sBAAsB,CAmBxB"}