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

package/dist/core/item-attachments.js

@@ -0,0 +1,317 @@
+/**
+ * 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 { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { writeBytesAtomic } from '../utils/atomic-write.js';
+import { attachmentTarget, LINK_PATTERN, linkTarget, stripCode } from './doctor-attachments.js';
+import { AttachmentError } from './item-attachments-error.js';
+import { mapFsError, moveExclusive, rethrowAfterRollback, statEntry, unlinkWithRetrySync, writeBytesExclusive, } from './item-attachments-io.js';
+import { captureAttachmentStorage } from './item-attachments-storage.js';
+import { isCanonicalItemFile } from './item-paths.js';
+import { readItem, writeItemDescription } from './item-store.js';
+import { validateWorkspacePath } from './path-guard.js';
+export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+export const MAX_ATTACHMENT_NAME = 120;
+export { AttachmentError };
+const FORBIDDEN_CHARS = /[/\\:*?"<>|]/;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what is rejected
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+const DEVICE_NAME = /^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³]|conin\$|conout\$)$/i;
+const norm = (name) => name.normalize('NFC');
+const fold = (name) => norm(name).toLowerCase();
+/** null when valid, else the code and message. Pure, no fs. */
+export function validateAttachmentName(id, name) {
+    const n = norm(name);
+    const bad = (code, message) => ({ code, message });
+    if (n === '' || n.trim() === '')
+        return bad('INVALID_NAME', 'The name is empty');
+    if (CONTROL_CHARS.test(n))
+        return bad('INVALID_NAME', 'The name contains a control character');
+    if (FORBIDDEN_CHARS.test(n)) {
+        return bad('INVALID_NAME', 'The name must be one file name without / \\ : * ? " < > |');
+    }
+    if (n.startsWith('.'))
+        return bad('INVALID_NAME', 'The name must not start with a dot');
+    if (n.endsWith('.') || n.endsWith(' ')) {
+        return bad('INVALID_NAME', 'The name must not end with a dot or a space');
+    }
+    if (n.length > MAX_ATTACHMENT_NAME) {
+        return bad('INVALID_NAME', `The name is longer than ${MAX_ATTACHMENT_NAME} characters`);
+    }
+    if (DEVICE_NAME.test(n.split('.')[0].replace(/[ .]+$/, ''))) {
+        return bad('RESERVED_NAME', `${n} is a reserved device name on Windows`);
+    }
+    const lower = n.toLowerCase();
+    if (lower === `${id}.json`.toLowerCase() || lower === `${id}.md`.toLowerCase()) {
+        return bad('RESERVED_NAME', `${n} is the item's own file`);
+    }
+    return null;
+}
+function assertName(id, name) {
+    const problem = validateAttachmentName(id, name);
+    if (problem)
+        throw new AttachmentError(problem.code, problem.message, id, name);
+    return norm(name);
+}
+/** The folder of a live item, or ITEM_NOT_FOUND for an archived, unknown or malformed ID. */
+function itemDir(devstepsDir, id) {
+    return captureAttachmentStorage(devstepsDir, id).dir;
+}
+function destination(devstepsDir, id, dir, name) {
+    const dest = join(dir, name);
+    const checked = validateWorkspacePath(dest, devstepsDir);
+    if (checked === null || dirname(checked) !== resolve(dir)) {
+        throw new AttachmentError('INVALID_NAME', `${name} would land outside the item folder`, id, name);
+    }
+    return dest;
+}
+function entriesOf(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** The entry of `dir` that collides with `name` case-insensitively, if any. */
+function collidingEntry(dir, name) {
+    return entriesOf(dir).find((entry) => fold(entry) === fold(name));
+}
+/** First free name: `shot.png` becomes `shot-2.png`, `shot-3.png`, ... */
+export function uniqueAttachmentName(devstepsDir, id, name) {
+    const dir = itemDir(devstepsDir, id);
+    const clean = assertName(id, name);
+    if (!collidingEntry(dir, clean) && !isCanonicalItemFile(id, clean))
+        return clean;
+    const dot = clean.lastIndexOf('.');
+    const stem = dot > 0 ? clean.slice(0, dot) : clean;
+    const ext = dot > 0 ? clean.slice(dot) : '';
+    for (let n = 2;; n++) {
+        const candidate = `${stem}-${n}${ext}`;
+        if (!collidingEntry(dir, candidate))
+            return candidate;
+    }
+}
+function describe(dir, name, id) {
+    const stat = statEntry(join(dir, name), id, name);
+    return { name, size: stat.size, modified: stat.mtime.toISOString() };
+}
+function tooLarge(id, name, size) {
+    return new AttachmentError('TOO_LARGE', `${name} is ${size} bytes, above the ${MAX_ATTACHMENT_BYTES} byte limit`, id, name);
+}
+/** Bytes/text from a caller. Refuses an existing name unless `overwrite`. */
+export function addAttachmentContent(devstepsDir, id, name, content, options = {}) {
+    const storage = captureAttachmentStorage(devstepsDir, id);
+    return addContentToStorage(devstepsDir, id, name, content, options, storage);
+}
+function addContentToStorage(devstepsDir, id, name, content, options, storage) {
+    storage.assertUnchanged();
+    const { dir } = storage;
+    const clean = assertName(id, name);
+    const dest = destination(devstepsDir, id, dir, clean);
+    const size = typeof content === 'string' ? Buffer.byteLength(content) : content.byteLength;
+    if (size > MAX_ATTACHMENT_BYTES)
+        throw tooLarge(id, clean, size);
+    const existing = collidingEntry(dir, clean);
+    storage.assertUnchanged();
+    let replaced = false;
+    if (existing !== undefined) {
+        const kind = statEntry(join(dir, existing), id, existing);
+        if (!options.overwrite || existing !== clean) {
+            throw new AttachmentError('EXISTS', `${existing} already exists`, id, existing);
+        }
+        if (!kind.isFile() && !kind.isSymbolicLink()) {
+            throw new AttachmentError('NOT_A_FILE', `${existing} is not a file`, id, existing);
+        }
+        replaced = true;
+    }
+    try {
+        if (replaced) {
+            writeBytesAtomic(dest, content, {
+                beforeWrite: storage.assertUnchanged,
+                beforeRename: storage.assertUnchanged,
+            });
+        }
+        else
+            writeBytesExclusive(dest, content, id, clean, storage.assertUnchanged);
+    }
+    catch (error) {
+        throw mapFsError(error, id, clean);
+    }
+    storage.assertUnchanged();
+    return { attachment: describe(dir, clean, id), replaced };
+}
+/** Copy a file the user picked: a regular file only, its size checked before reading. */
+export function importAttachmentFile(devstepsDir, id, sourcePath, options = {}) {
+    const name = options.name ?? sourcePath.split(/[\\/]/).pop() ?? '';
+    const storage = captureAttachmentStorage(devstepsDir, id);
+    assertName(id, name);
+    let stat;
+    try {
+        stat = lstatSync(sourcePath);
+    }
+    catch (error) {
+        throw new AttachmentError('SOURCE_UNREADABLE', `Cannot read ${sourcePath}: ${error}`, id, name);
+    }
+    if (!stat.isFile()) {
+        throw new AttachmentError('NOT_A_FILE', `${sourcePath} is not a regular file`, id, name);
+    }
+    if (stat.size > MAX_ATTACHMENT_BYTES)
+        throw tooLarge(id, name, stat.size);
+    let bytes;
+    storage.assertUnchanged();
+    try {
+        bytes = readFileSync(sourcePath);
+    }
+    catch (error) {
+        throw new AttachmentError('SOURCE_UNREADABLE', `Cannot read ${sourcePath}: ${error}`, id, name);
+    }
+    return addContentToStorage(devstepsDir, id, name, bytes, options, storage);
+}
+function targetOf(name) {
+    return /[\s()<>%#?[\]"]/.test(name)
+        ? encodeURIComponent(name).replace(/[()]/g, (c) => (c === '(' ? '%28' : '%29'))
+        : name;
+}
+/** Rewrite links to `from` outside code. Returns the new text and the count. */
+function rewriteLinks(markdown, from, to) {
+    let count = 0;
+    const pattern = new RegExp(`\`\`\`[\\s\\S]*?\`\`\`|~~~[\\s\\S]*?~~~|\`[^\`\\n]*\`|${LINK_PATTERN.source}`, 'g');
+    const text = markdown.replace(pattern, (match, angled, bare) => {
+        const target = angled ?? bare;
+        if (target === undefined || attachmentTarget(target) === null)
+            return match;
+        if (fold(attachmentTarget(target) ?? '') !== fold(from))
+            return match;
+        const open = match.indexOf('](');
+        const at = match.indexOf(target, open + 2);
+        count += 1;
+        const suffix = /[?#].*$/.exec(target)?.[0] ?? '';
+        const name = angled !== undefined && !to.includes('%') ? to : targetOf(to);
+        return match.slice(0, at) + name + suffix + match.slice(at + target.length);
+    });
+    return { text, count };
+}
+function countLinks(markdown, name) {
+    let count = 0;
+    for (const match of stripCode(markdown).matchAll(LINK_PATTERN)) {
+        const target = attachmentTarget(linkTarget(match));
+        if (target !== null && fold(target) === fold(name))
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Resolve an existing entry for rename-from and remove. Only traversal-shaped input is
+ * refused, so a file stored under a name the strict rules reject (NFD, legacy characters)
+ * stays reachable. Returns the on-disk name: exact match first, else the single NFC and
+ * case-folded match.
+ */
+function resolveExisting(dir, id, name) {
+    const bad = (message) => new AttachmentError('INVALID_NAME', message, id, name);
+    if (name === '' || name.trim() === '')
+        throw bad('The name is empty');
+    if (name === '.' || name === '..' || /[/\\\0]/.test(name)) {
+        throw bad('The name must be one file name inside the item folder');
+    }
+    const lower = norm(name).toLowerCase();
+    if (lower === `${id}.json`.toLowerCase() || lower === `${id}.md`.toLowerCase()) {
+        throw new AttachmentError('RESERVED_NAME', `${name} is the item's own file`, id, name);
+    }
+    const entries = entriesOf(dir);
+    if (entries.includes(name))
+        return name;
+    const matches = entries.filter((entry) => fold(entry) === fold(name));
+    if (matches.length === 1)
+        return matches[0];
+    const why = matches.length === 0 ? 'is not in the item folder' : 'matches several entries';
+    throw new AttachmentError('NOT_FOUND', `${name} ${why}`, id, name);
+}
+/**
+ * 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 function attachmentFilePath(devstepsDir, id, name) {
+    const dir = itemDir(devstepsDir, id);
+    const entry = resolveExisting(dir, id, name);
+    return destination(devstepsDir, id, dir, entry);
+}
+export function renameAttachment(devstepsDir, id, from, to, options = {}) {
+    const storage = captureAttachmentStorage(devstepsDir, id);
+    const { dir } = storage;
+    const oldName = resolveExisting(dir, id, from);
+    const newName = assertName(id, to);
+    const source = join(dir, oldName);
+    if (!statEntry(source, id, oldName).isFile()) {
+        throw new AttachmentError('NOT_A_FILE', `${oldName} is not a file`, id, oldName);
+    }
+    const dest = destination(devstepsDir, id, dir, newName);
+    const clash = entriesOf(dir).find((e) => e !== oldName && fold(e) === fold(newName));
+    storage.assertUnchanged();
+    if (clash !== undefined) {
+        throw new AttachmentError('EXISTS', `${clash} already exists`, id, clash);
+    }
+    const caseOnly = fold(oldName) === fold(newName) && oldName !== newName;
+    // Rename first, then write the description last under the stamps readItem returned: a
+    // concurrent change to <ID>.json or <ID>.md raises StaleItemError and only the cheap,
+    // reliable file rename has to be undone, so no text is ever rolled back over a newer edit.
+    const stored = options.updateLinks !== false && oldName !== newName ? readItem(devstepsDir, id) : null;
+    const rewritten = stored ? rewriteLinks(stored.description, oldName, newName) : null;
+    try {
+        if (oldName !== newName) {
+            moveExclusive(source, dest, id, newName, caseOnly, storage.assertUnchanged);
+        }
+    }
+    catch (error) {
+        throw mapFsError(error, id, newName);
+    }
+    if (stored && rewritten && rewritten.count > 0) {
+        try {
+            storage.assertUnchanged();
+            writeItemDescription(devstepsDir, id, rewritten.text, {
+                metadata: stored.stamp,
+                description: stored.descriptionStamp,
+            });
+        }
+        catch (error) {
+            rethrowAfterRollback(error, newName, () => moveExclusive(dest, source, id, oldName, caseOnly, storage.assertUnchanged));
+        }
+    }
+    storage.assertUnchanged();
+    return { attachment: describe(dir, newName, id), linksUpdated: rewritten?.count ?? 0 };
+}
+export function removeAttachment(devstepsDir, id, name) {
+    const storage = captureAttachmentStorage(devstepsDir, id);
+    const { dir } = storage;
+    const clean = resolveExisting(dir, id, name);
+    const target = join(dir, clean);
+    const kind = statEntry(target, id, clean);
+    if (!kind.isFile() && !kind.isSymbolicLink()) {
+        throw new AttachmentError('NOT_A_FILE', `${clean} is not a file`, id, clean);
+    }
+    try {
+        unlinkWithRetrySync(target, storage.assertUnchanged);
+    }
+    catch (error) {
+        throw mapFsError(error, id, clean);
+    }
+    storage.assertUnchanged();
+    return {
+        removed: clean,
+        danglingLinks: countLinks(readItem(devstepsDir, id).description, clean),
+    };
+}
+//# sourceMappingURL=item-attachments.js.map

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

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

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

@@ -0,0 +1,70 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The item folder layout (STORY-427) — the one place that knows where an item lives.
+ *
+ * ```
+ * .devsteps/items/bugs/BUG-127/
+ *   BUG-127.md        master document — human-owned, edited in place
+ *   BUG-127.json      metadata — tool-owned
+ *   screenshot.png    attachment: anything else in the folder
+ * ```
+ *
+ * `archive/items/<type>s/<ID>/` mirrors the layout. Nothing outside this module
+ * appends a file name to a type directory.
+ */
+import type { ItemType } from '../schemas/index.js';
+export interface ItemPaths {
+    /** The item's folder: master document, metadata and attachments. */
+    dir: string;
+    /** `<ID>.json` — tool-owned metadata. */
+    metadata: string;
+    /** `<ID>.md` — the human-owned master document. */
+    description: string;
+}
+/** `items/<type>s/` for live items. */
+export declare function typeDirectory(devstepsDir: string, type: ItemType): string;
+/** `archive/items/<type>s/` for archived items. */
+export declare function archivedTypeDirectory(devstepsDir: string, type: ItemType): string;
+/** Paths of a live item. Throws for an ID that is not a work item ID. */
+export declare function itemPaths(devstepsDir: string, id: string): ItemPaths;
+/** Paths of an archived item. Throws for an ID that is not a work item ID. */
+export declare function archivedItemPaths(devstepsDir: string, id: string): ItemPaths;
+/** The two canonical files of an item folder; every other entry is an attachment. */
+export declare function isCanonicalItemFile(id: string, name: string): boolean;
+/** A file (or sub-folder) that sits in an item folder beside the canonical pair. */
+export interface ItemAttachment {
+    /** Name relative to the item folder — what the master document links to. */
+    name: string;
+    size: number;
+    /** ISO timestamp of the last modification. */
+    modified: string;
+    /** Present for a sub-folder; its size is 0. */
+    directory?: true;
+}
+/**
+ * Attachments of a live item: every entry of its folder except `<ID>.json` and
+ * `<ID>.md`, sorted by name. The folder is the record — nothing in the metadata lists
+ * them, so a file dropped in through the explorer is never out of sync.
+ */
+export declare function listAttachments(devstepsDir: string, id: string): ItemAttachment[];
+/**
+ * IDs of the item folders directly under `typeDir`, ordered by number so a `limit`
+ * cuts the same slice on every filesystem. A missing directory yields nothing —
+ * a methodology that does not use the type has no directory for it.
+ */
+export declare function listItemFolders(typeDir: string, type: ItemType): string[];
+/**
+ * Claim the next free ID above `from` by creating its folder (STORY-428).
+ *
+ * A non-recursive `mkdir` is atomic on every filesystem: when two writers race for
+ * the same number, exactly one succeeds and the other sees `EEXIST` and moves on.
+ * The caller writes the item into the returned paths and then advances the counter.
+ */
+export declare function claimItemFolder(devstepsDir: string, type: ItemType, from: number): {
+    itemId: string;
+    number: number;
+    paths: ItemPaths;
+};
+//# sourceMappingURL=item-paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"item-paths.d.ts","sourceRoot":"","sources":["../../src/core/item-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAIpD,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;CACrB;AAKD,uCAAuC;AACvC,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEzE;AAED,mDAAmD;AACnD,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEjF;AAeD,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CAEpE;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CAE5E;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAErE;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,EAAE,CAyBjF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAgBzE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,GACX;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAkBtD"}

package/dist/core/item-paths.js

@@ -0,0 +1,135 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The item folder layout (STORY-427) — the one place that knows where an item lives.
+ *
+ * ```
+ * .devsteps/items/bugs/BUG-127/
+ *   BUG-127.md        master document — human-owned, edited in place
+ *   BUG-127.json      metadata — tool-owned
+ *   screenshot.png    attachment: anything else in the folder
+ * ```
+ *
+ * `archive/items/<type>s/<ID>/` mirrors the layout. Nothing outside this module
+ * appends a file name to a type directory.
+ */
+import { mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { ATOMIC_TEMP_NAME } from '../utils/atomic-write.js';
+import { generateItemId, parseItemId, TYPE_TO_DIRECTORY } from '../utils/index.js';
+/** Numbers tried past the counter before an ID claim gives up. */
+const CLAIM_ATTEMPTS = 1000;
+/** `items/<type>s/` for live items. */
+export function typeDirectory(devstepsDir, type) {
+    return join(devstepsDir, TYPE_TO_DIRECTORY[type]);
+}
+/** `archive/items/<type>s/` for archived items. */
+export function archivedTypeDirectory(devstepsDir, type) {
+    return join(devstepsDir, 'archive', TYPE_TO_DIRECTORY[type]);
+}
+function pathsIn(typeDir, id) {
+    const dir = join(typeDir, id);
+    return { dir, metadata: join(dir, `${id}.json`), description: join(dir, `${id}.md`) };
+}
+function typeOf(id) {
+    const parsed = parseItemId(id);
+    if (!parsed) {
+        throw new Error(`Invalid item ID: ${id}`);
+    }
+    return parsed.type;
+}
+/** Paths of a live item. Throws for an ID that is not a work item ID. */
+export function itemPaths(devstepsDir, id) {
+    return pathsIn(typeDirectory(devstepsDir, typeOf(id)), id);
+}
+/** Paths of an archived item. Throws for an ID that is not a work item ID. */
+export function archivedItemPaths(devstepsDir, id) {
+    return pathsIn(archivedTypeDirectory(devstepsDir, typeOf(id)), id);
+}
+/** The two canonical files of an item folder; every other entry is an attachment. */
+export function isCanonicalItemFile(id, name) {
+    return name === `${id}.json` || name === `${id}.md`;
+}
+/**
+ * Attachments of a live item: every entry of its folder except `<ID>.json` and
+ * `<ID>.md`, sorted by name. The folder is the record — nothing in the metadata lists
+ * them, so a file dropped in through the explorer is never out of sync.
+ */
+export function listAttachments(devstepsDir, id) {
+    const { dir } = itemPaths(devstepsDir, id);
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const attachments = [];
+    for (const name of names.sort()) {
+        if (isCanonicalItemFile(id, name) || ATOMIC_TEMP_NAME.test(name))
+            continue;
+        try {
+            const stat = statSync(join(dir, name));
+            attachments.push({
+                name,
+                size: stat.isDirectory() ? 0 : stat.size,
+                modified: stat.mtime.toISOString(),
+                ...(stat.isDirectory() ? { directory: true } : {}),
+            });
+        }
+        catch {
+            /* removed between readdir and stat */
+        }
+    }
+    return attachments;
+}
+/**
+ * IDs of the item folders directly under `typeDir`, ordered by number so a `limit`
+ * cuts the same slice on every filesystem. A missing directory yields nothing —
+ * a methodology that does not use the type has no directory for it.
+ */
+export function listItemFolders(typeDir, type) {
+    let entries;
+    try {
+        entries = readdirSync(typeDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const numbered = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const parsed = parseItemId(entry.name);
+        if (parsed?.type === type)
+            numbered.push({ id: entry.name, number: parsed.number });
+    }
+    numbered.sort((a, b) => a.number - b.number);
+    return numbered.map((entry) => entry.id);
+}
+/**
+ * Claim the next free ID above `from` by creating its folder (STORY-428).
+ *
+ * A non-recursive `mkdir` is atomic on every filesystem: when two writers race for
+ * the same number, exactly one succeeds and the other sees `EEXIST` and moves on.
+ * The caller writes the item into the returned paths and then advances the counter.
+ */
+export function claimItemFolder(devstepsDir, type, from) {
+    const typeDir = typeDirectory(devstepsDir, type);
+    mkdirSync(typeDir, { recursive: true });
+    for (let number = from + 1; number <= from + CLAIM_ATTEMPTS; number++) {
+        const itemId = generateItemId(type, number);
+        const paths = pathsIn(typeDir, itemId);
+        try {
+            mkdirSync(paths.dir);
+            return { itemId, number, paths };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+    throw new Error(`Could not claim a free ${type} ID within ${CLAIM_ATTEMPTS} numbers past ${from}`);
+}
+//# sourceMappingURL=item-paths.js.map

package/dist/core/item-paths.js.map

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

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

@@ -0,0 +1,36 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Read-only access to stored metadata, including schema-invalid JSON (TASK-1069).
+ */
+import { type ItemAttachment } from './item-paths.js';
+import { type FileStamp } from './item-store.js';
+export interface RawItemSnapshot {
+    /** Original UTF-8 source, retained without schema defaults or JSON reserialization. */
+    readonly text: string;
+    readonly stamp: FileStamp;
+    readonly raw: unknown;
+}
+export interface RawItemInspection {
+    /** The requested path identity, separate from any identity in the stored value. */
+    requested_id: string;
+    raw_metadata: unknown;
+    schema_valid: boolean;
+    schema_issues: string[];
+    description: string;
+    attachments: ItemAttachment[];
+}
+/**
+ * Load the stored JSON without interpreting or repairing its domain fields.
+ * Parser diagnostics are omitted because they can include metadata contents.
+ */
+export declare function readRawItemSnapshot(devstepsDir: string, id: string): RawItemSnapshot;
+/** Compare both the loaded source and stamp; a missing target is also stale. */
+export declare function assertRawItemSnapshot(devstepsDir: string, id: string, snapshot: RawItemSnapshot): void;
+/**
+ * Inspect stored data without inventing work-item identity, defaults or lifecycle intent.
+ * Validation supplies issues only; its parsed/defaulted output is never returned.
+ */
+export declare function inspectRawItem(devstepsDir: string, id: string): RawItemInspection;
+//# sourceMappingURL=item-raw.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"item-raw.d.ts","sourceRoot":"","sources":["../../src/core/item-raw.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,KAAK,cAAc,EAA8B,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,KAAK,SAAS,EAAkB,MAAM,iBAAiB,CAAC;AAGjE,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,cAAc,EAAE,CAAC;CAC/B;AAiDD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,CASpF;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,eAAe,GACxB,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,iBAAiB,CAiBjF"}