light-plan 0.0.0-stage → 0.1.0

package/dist/core/storage/atomic.js

@@ -0,0 +1,117 @@
+import { randomBytes } from 'node:crypto';
+import { renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * The three primitives that make a board safe to share.
+ *
+ * A `.lpm` folder has no server in front of it: two people, a web session and a
+ * swarm of agents can all be writing to one checkout at the same moment, and
+ * every one of them is a separate process holding its own `LoadedBoard`. Three
+ * things have to be true for that to work, and this file is the first two of
+ * them.
+ *
+ * **Nobody reads half a document.** `writeFileAtomic` writes a temporary file
+ * beside the target and renames it into place. `rename` over an existing file is
+ * atomic on POSIX and on Windows (`MoveFileEx` with replace), so a concurrent
+ * reader sees either the whole old document or the whole new one — never the
+ * torn middle, which on a YAML frontmatter file reads as a corrupt board.
+ *
+ * **A writer can tell whether the file moved underneath it.** A `DocStamp` is
+ * the identity of a file as it was read: modification time to nanosecond
+ * precision plus size. `loadBoard` records one per document, and an operation
+ * compares it against disk before writing, so a stale handle is refused rather
+ * than silently winning. This is the same evidence `DocumentCache` trusts, and
+ * it carries the same caveat — see `sameStamp`.
+ *
+ * The third is `lock.ts`, which serializes the writers so the compare and the
+ * write cannot be interleaved.
+ *
+ * Deliberately *not* here: `fsync`. The failure this guards against is another
+ * process reading at the wrong moment, not the machine losing power; a board is
+ * versioned in git, and paying a flush on every status change would make the
+ * common case slower to defend against the case git already covers.
+ */
+/** How long to keep retrying a rename a virus scanner or indexer is holding. */
+const RENAME_RETRY_MS = 200;
+/** Errors a Windows filesystem raises when something else has the file open. */
+const TRANSIENT = new Set(['EPERM', 'EACCES', 'EBUSY']);
+/**
+ * Block the calling thread for `ms`. Everything in the engine is synchronous —
+ * operations are called from a CLI process that then exits — so the lock's
+ * retry loop and the rename retry below need a wait that does not need an event
+ * loop turn. `Atomics.wait` is the only one Node offers on the main thread.
+ */
+export function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function tempNameFor(file) {
+    const base = path.basename(file);
+    // Leading dot so a temporary that outlives a killed process is hidden from a
+    // file tree and from `scanDir`, which skips dot-entries.
+    return path.join(path.dirname(file), `.${base}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`);
+}
+function renameWithRetry(from, to) {
+    const until = Date.now() + RENAME_RETRY_MS;
+    for (;;) {
+        try {
+            renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error.code ?? '';
+            if (!TRANSIENT.has(code) || Date.now() >= until)
+                throw error;
+            sleepSync(10);
+        }
+    }
+}
+/**
+ * Write `data` to `file` so that no reader ever observes a partial write.
+ *
+ * The temporary lands in the same directory as the target, because a rename is
+ * only atomic within one filesystem and `.lpm` may well be a mount of its own.
+ * A failed write takes its temporary with it.
+ */
+export function writeFileAtomic(file, data) {
+    const temp = tempNameFor(file);
+    try {
+        writeFileSync(temp, data, 'utf8');
+        renameWithRetry(temp, file);
+    }
+    catch (error) {
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch {
+            // The temporary is already gone, or the directory is unwritable — either
+            // way the original error is the one worth reporting.
+        }
+        throw error;
+    }
+}
+/** Stamp `file` as it stands now, or null when it does not exist. */
+export function stampOf(file) {
+    try {
+        const stat = statSync(file, { bigint: true });
+        return { mtimeNs: stat.mtimeNs, size: Number(stat.size) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether two stamps describe the same version of a file.
+ *
+ * Say what it does not do: a filesystem with a coarse clock (FAT, and some
+ * network mounts) can give two rewrites inside one tick the same timestamp, so
+ * a same-size rewrite in that window compares equal. That is the same racy-index
+ * hole git guards against and `DocumentCache` closes with a two-second window,
+ * and it is why this is the *second* line of defence rather than the only one:
+ * the board lock is what makes two writers take turns in the first place.
+ */
+export function sameStamp(a, b) {
+    return a.mtimeNs === b.mtimeNs && a.size === b.size;
+}
+//# sourceMappingURL=atomic.js.map

package/dist/core/storage/atomic.js.map

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

package/dist/core/storage/comments.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The work log on a document.
+ *
+ * Comments live in a `_comments.md` beside the document's own file, as a flat
+ * append-only list. That shape is chosen for the two things that actually
+ * happen to them: an agent or a person adds one at the end, and two people do
+ * that on different branches. Appends merge; a growing YAML list in the
+ * frontmatter would not, and it would push the fields anyone reads down the
+ * page.
+ *
+ * `load.ts` only ever opens `_issue.md` / `_period.md` / `_resource.md`, and it
+ * only walks directories, so an extra file here is invisible to the engine.
+ * Comments are read on demand rather than with the board.
+ */
+export declare const COMMENTS_FILE = "_comments.md";
+export interface Comment {
+    /** 1-based position in the file, which is also the order it was written. */
+    index: number;
+    /** ISO timestamp. */
+    at: string;
+    author: string;
+    body: string;
+}
+export declare function commentsFile(dir: string): string;
+/** Read a document's comments, oldest first. A missing file means none. */
+export declare function readComments(dir: string): Comment[];
+/** Append one comment, creating the file if this is the first. */
+export declare function appendComment(dir: string, comment: {
+    at: string;
+    author: string;
+    body: string;
+}): void;
+/**
+ * Rewrite the whole log. Used to delete one entry; nothing else needs it.
+ *
+ * Atomic, unlike the append above: this one replaces the file, so a reader
+ * catching it mid-write would see a truncated log rather than a shorter one.
+ */
+export declare function writeComments(dir: string, comments: Comment[]): void;

package/dist/core/storage/comments.js

@@ -0,0 +1,88 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { writeFileAtomic } from './atomic.js';
+/**
+ * The work log on a document.
+ *
+ * Comments live in a `_comments.md` beside the document's own file, as a flat
+ * append-only list. That shape is chosen for the two things that actually
+ * happen to them: an agent or a person adds one at the end, and two people do
+ * that on different branches. Appends merge; a growing YAML list in the
+ * frontmatter would not, and it would push the fields anyone reads down the
+ * page.
+ *
+ * `load.ts` only ever opens `_issue.md` / `_period.md` / `_resource.md`, and it
+ * only walks directories, so an extra file here is invisible to the engine.
+ * Comments are read on demand rather than with the board.
+ */
+export const COMMENTS_FILE = '_comments.md';
+/**
+ * A heading strict enough that prose cannot be mistaken for it: the timestamp
+ * has to come first. Anything else in the body is left alone.
+ */
+const HEADING = /^##[ \t]+(\d{4}-\d{2}-\d{2}T[0-9:.]+Z)[ \t]+—[ \t]+(.*)$/;
+export function commentsFile(dir) {
+    return path.join(dir, COMMENTS_FILE);
+}
+function formatEntry(comment) {
+    return `## ${comment.at} — ${comment.author}\n\n${comment.body.trim()}\n`;
+}
+/** Read a document's comments, oldest first. A missing file means none. */
+export function readComments(dir) {
+    const file = commentsFile(dir);
+    if (!existsSync(file))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const comments = [];
+    let current = null;
+    const lines = [];
+    const flush = () => {
+        if (!current)
+            return;
+        current.body = lines.join('\n').trim();
+        comments.push(current);
+        lines.length = 0;
+    };
+    for (const line of raw.split(/\r?\n/)) {
+        const match = HEADING.exec(line);
+        if (match) {
+            flush();
+            current = {
+                index: comments.length + 1,
+                at: match[1],
+                author: match[2].trim(),
+                body: '',
+            };
+            continue;
+        }
+        if (current)
+            lines.push(line);
+    }
+    flush();
+    return comments;
+}
+/** Append one comment, creating the file if this is the first. */
+export function appendComment(dir, comment) {
+    const file = commentsFile(dir);
+    const entry = formatEntry(comment);
+    if (existsSync(file))
+        appendFileSync(file, `\n${entry}`, 'utf8');
+    else
+        writeFileSync(file, entry, 'utf8');
+}
+/**
+ * Rewrite the whole log. Used to delete one entry; nothing else needs it.
+ *
+ * Atomic, unlike the append above: this one replaces the file, so a reader
+ * catching it mid-write would see a truncated log rather than a shorter one.
+ */
+export function writeComments(dir, comments) {
+    writeFileAtomic(commentsFile(dir), comments.map(formatEntry).join('\n'));
+}
+//# sourceMappingURL=comments.js.map

package/dist/core/storage/comments.js.map

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

package/dist/core/storage/document.d.ts

@@ -0,0 +1,16 @@
+import type { AnyNode, BoardConfig } from '../model/types.js';
+/**
+ * Render a document to markdown. Frontmatter key order is stable: reserved
+ * fields first, then attributes in the order the config declares them, then any
+ * extra keys the user added by hand (preserved rather than dropped).
+ */
+export declare function serializeNode(node: AnyNode, config: BoardConfig): string;
+/**
+ * Write a document. Atomically, because another process may be reading this
+ * very file: half a YAML frontmatter block reads as a corrupt board, and a
+ * board is read far more often than it is written.
+ */
+export declare function writeNode(node: AnyNode, config: BoardConfig): void;
+export declare function nowIso(): string;
+/** File mtime, used as a last-resort `created` timestamp. */
+export declare function fileTimestamp(file: string): string;

package/dist/core/storage/document.js

@@ -0,0 +1,98 @@
+import { statSync } from 'node:fs';
+import { typesFor } from '../config/lookup.js';
+import { writeFileAtomic } from './atomic.js';
+import { stringifyFrontmatter } from './frontmatter.js';
+/**
+ * Render a document to markdown. Frontmatter key order is stable: reserved
+ * fields first, then attributes in the order the config declares them, then any
+ * extra keys the user added by hand (preserved rather than dropped).
+ */
+export function serializeNode(node, config) {
+    const data = { id: node.id };
+    // An unresolved type is left out rather than written as an empty string, so
+    // `check` keeps reporting it instead of the file gaining a bogus value.
+    if (node.type)
+        data.type = node.type;
+    data.title = node.title;
+    if (node.kind === 'issue') {
+        data.status = node.status;
+        data.assignee = node.assignee;
+        data.period = node.period;
+        // Only written once somebody has raised one. An absent key is the ordinary
+        // case, and `flag: null` on every issue on the board would bury the few
+        // that are actually asking for something.
+        if (node.flag)
+            data.flag = node.flag;
+        data.depends_on = node.depends_on;
+        data.relates_to = node.relates_to;
+        data.related_files = node.related_files;
+    }
+    else if (node.kind === 'period') {
+        if (node.starts !== undefined)
+            data.starts = node.starts;
+        if (node.ends !== undefined)
+            data.ends = node.ends;
+        // Only written once somebody has held the switch: an absent key is what
+        // says "the dates decide", and writing `active: null` would blur that.
+        if (node.active !== undefined)
+            data.active = node.active;
+        data.squad = node.squad;
+    }
+    else if (node.kind === 'resource') {
+        data.capacity = node.capacity;
+        data.covers = node.covers;
+    }
+    else if (node.kind === 'template') {
+        data.description = node.description;
+        // Only a root declares parameters, and only when it has any: `params: {}`
+        // on every folder in the registry would bury the templates that ask for
+        // something. @see src/shared/template-params.ts
+        if (Object.keys(node.params).length)
+            data.params = node.params;
+        data.depends_on = node.depends_on;
+        data.relates_to = node.relates_to;
+        data.related_files = node.related_files;
+    }
+    else {
+        data.members = node.members;
+    }
+    if (node.created)
+        data.created = node.created;
+    if (node.updated)
+        data.updated = node.updated;
+    if (node.author)
+        data.author = node.author;
+    const types = typesFor(config, node.kind);
+    const declared = Object.keys(types[node.type]?.attributes ?? {});
+    for (const key of declared) {
+        if (key in node.attributes)
+            data[key] = node.attributes[key];
+    }
+    for (const [key, value] of Object.entries(node.attributes)) {
+        if (!declared.includes(key))
+            data[key] = value;
+    }
+    return stringifyFrontmatter(data, node.body);
+}
+/**
+ * Write a document. Atomically, because another process may be reading this
+ * very file: half a YAML frontmatter block reads as a corrupt board, and a
+ * board is read far more often than it is written.
+ */
+export function writeNode(node, config) {
+    writeFileAtomic(node.file, serializeNode(node, config));
+}
+export function nowIso() {
+    return new Date().toISOString();
+}
+/** File mtime, used as a last-resort `created` timestamp. */
+export function fileTimestamp(file) {
+    try {
+        const stats = statSync(file);
+        return (stats.birthtimeMs > 0 ? stats.birthtime : stats.mtime).toISOString();
+    }
+    catch {
+        return new Date().toISOString();
+    }
+}
+//# sourceMappingURL=document.js.map

package/dist/core/storage/document.js.map

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

package/dist/core/storage/frontmatter.d.ts

@@ -0,0 +1,16 @@
+export interface ParsedDocument {
+    data: Record<string, unknown>;
+    body: string;
+    hadFrontmatter: boolean;
+}
+/**
+ * Split a markdown document into YAML frontmatter and body.
+ * Throws if the frontmatter block exists but is not valid YAML.
+ */
+export declare function parseFrontmatter(raw: string): ParsedDocument;
+export declare function stringifyFrontmatter(data: Record<string, unknown>, body: string): string;
+/**
+ * First level-1 heading in a markdown body, used to recover a missing title.
+ * Deliberately h1-only: issue body templates open with h2 section headings.
+ */
+export declare function firstHeading(body: string): string | null;

package/dist/core/storage/frontmatter.js

@@ -0,0 +1,33 @@
+import YAML from 'yaml';
+const BOM = '\\uFEFF';
+const FRONTMATTER_RE = new RegExp(`^${BOM}?---[ \\t]*\\r?\\n([\\s\\S]*?)(?:\\r?\\n)?---[ \\t]*(?:\\r?\\n|$)`);
+const LEADING_BOM_RE = new RegExp(`^${BOM}`);
+/**
+ * Split a markdown document into YAML frontmatter and body.
+ * Throws if the frontmatter block exists but is not valid YAML.
+ */
+export function parseFrontmatter(raw) {
+    const match = FRONTMATTER_RE.exec(raw);
+    if (!match) {
+        return { data: {}, body: raw.replace(LEADING_BOM_RE, ''), hadFrontmatter: false };
+    }
+    const parsed = YAML.parse(match[1]);
+    const data = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed
+        : {};
+    return { data, body: raw.slice(match[0].length), hadFrontmatter: true };
+}
+export function stringifyFrontmatter(data, body) {
+    const yaml = YAML.stringify(data, { lineWidth: 0 }).trimEnd();
+    const trimmed = body.replace(/^\s+/, '').trimEnd();
+    return trimmed ? `---\n${yaml}\n---\n\n${trimmed}\n` : `---\n${yaml}\n---\n`;
+}
+/**
+ * First level-1 heading in a markdown body, used to recover a missing title.
+ * Deliberately h1-only: issue body templates open with h2 section headings.
+ */
+export function firstHeading(body) {
+    const match = /^#[ \t]+(.+?)[ \t]*$/m.exec(body);
+    return match ? match[1] : null;
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/core/storage/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../../src/core/storage/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,GAAG,GAAG,SAAS,CAAC;AACtB,MAAM,cAAc,GAAG,IAAI,MAAM,CAC/B,IAAI,GAAG,mEAAmE,CAC3E,CAAC;AACF,MAAM,cAAc,GAAG,IAAI,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;AAQ7C;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IACpF,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAE,CAAY,CAAC;IAChD,MAAM,IAAI,GACR,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAC5D,CAAC,CAAE,MAAkC;QACrC,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAA6B,EAAE,IAAY;IAC9E,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACnD,OAAO,OAAO,CAAC,CAAC,CAAC,QAAQ,IAAI,YAAY,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,SAAS,CAAC;AAC/E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAClC,CAAC"}

package/dist/core/storage/git.d.ts

@@ -0,0 +1,8 @@
+export declare function isGitRepo(dir: string): boolean;
+/** The root of the git work tree `dir` sits in, or null outside one. */
+export declare function gitTopLevel(dir: string): string | null;
+export declare function gitInit(dir: string): boolean;
+/** `Name <email>` from git config, falling back to the OS user. */
+export declare function gitIdentity(cwd: string): string;
+/** ISO date of the commit that added `file`, if it is tracked. */
+export declare function gitFileCreationDate(file: string): string | null;

package/dist/core/storage/git.js

@@ -0,0 +1,48 @@
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+function git(cwd, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function isGitRepo(dir) {
+    return git(dir, ['rev-parse', '--is-inside-work-tree']) === 'true';
+}
+/** The root of the git work tree `dir` sits in, or null outside one. */
+export function gitTopLevel(dir) {
+    const top = git(dir, ['rev-parse', '--show-toplevel']);
+    return top ? path.resolve(top) : null;
+}
+export function gitInit(dir) {
+    return git(dir, ['init']) !== null;
+}
+/** `Name <email>` from git config, falling back to the OS user. */
+export function gitIdentity(cwd) {
+    const name = git(cwd, ['config', 'user.name']);
+    const email = git(cwd, ['config', 'user.email']);
+    if (name && email)
+        return `${name} <${email}>`;
+    if (name)
+        return name;
+    try {
+        return os.userInfo().username;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** ISO date of the commit that added `file`, if it is tracked. */
+export function gitFileCreationDate(file) {
+    const dir = path.dirname(file);
+    const out = git(dir, ['log', '--diff-filter=A', '--format=%aI', '-1', '--', file]);
+    return out ? out.split('\n')[0] : null;
+}
+//# sourceMappingURL=git.js.map

package/dist/core/storage/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../../src/core/storage/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,SAAS,GAAG,CAAC,GAAW,EAAE,IAAc;IACtC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE;YAC/B,GAAG;YACH,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,GAAG,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,uBAAuB,CAAC,CAAC,KAAK,MAAM,CAAC;AACrE,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC;IACvD,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,OAAO,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,CAAC;AACrC,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;IACjD,IAAI,IAAI,IAAI,KAAK;QAAE,OAAO,GAAG,IAAI,KAAK,KAAK,GAAG,CAAC;IAC/C,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IACnF,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1C,CAAC"}

package/dist/core/storage/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The filesystem and git adapters — everything that knows how a board is laid
+ * out on disk: where things live (paths), how a document is encoded
+ * (frontmatter, document), the work log beside it (comments), the activity
+ * section inside a document's body (activity), the id counters (state),
+ * per-checkout settings (local), saved views (views), the context templates a
+ * brief is rendered with (templates), and authorship (git).  Nothing here knows
+ * what a valid board looks like; that is validation's job.
+ *
+ * Two of them are about sharing the folder rather than laying it out: `atomic`
+ * (a write nobody can see half of, and the stamp that says whether a file moved
+ * underneath a reader) and `lock` (one writer at a time, across processes).
+ * Every write in this folder goes through the first; every operation that
+ * changes a board goes through the second.
+ */
+export * from './activity.js';
+export * from './atomic.js';
+export * from './comments.js';
+export * from './document.js';
+export * from './frontmatter.js';
+export * from './git.js';
+export * from './local.js';
+export * from './lock.js';
+export * from './paths.js';
+export * from './state.js';
+export * from './templates.js';
+export * from './views.js';

package/dist/core/storage/index.js

@@ -0,0 +1,28 @@
+/**
+ * The filesystem and git adapters — everything that knows how a board is laid
+ * out on disk: where things live (paths), how a document is encoded
+ * (frontmatter, document), the work log beside it (comments), the activity
+ * section inside a document's body (activity), the id counters (state),
+ * per-checkout settings (local), saved views (views), the context templates a
+ * brief is rendered with (templates), and authorship (git).  Nothing here knows
+ * what a valid board looks like; that is validation's job.
+ *
+ * Two of them are about sharing the folder rather than laying it out: `atomic`
+ * (a write nobody can see half of, and the stamp that says whether a file moved
+ * underneath a reader) and `lock` (one writer at a time, across processes).
+ * Every write in this folder goes through the first; every operation that
+ * changes a board goes through the second.
+ */
+export * from './activity.js';
+export * from './atomic.js';
+export * from './comments.js';
+export * from './document.js';
+export * from './frontmatter.js';
+export * from './git.js';
+export * from './local.js';
+export * from './lock.js';
+export * from './paths.js';
+export * from './state.js';
+export * from './templates.js';
+export * from './views.js';
+//# sourceMappingURL=index.js.map

package/dist/core/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}

package/dist/core/storage/local.d.ts

@@ -0,0 +1,57 @@
+import type { BoardPaths } from './paths.js';
+/**
+ * Per-checkout settings, kept in `.lpm/local.json` and deliberately not
+ * committed: who is sitting at this machine is not a property of the board.
+ * `.lpm/.gitignore` excludes the file; `ensureLocalIgnored` adds the entry to
+ * boards created before this existed.
+ */
+export interface LocalSettings {
+    /** Id of the resource driving the CLI, or null when nobody is set. */
+    user: string | null;
+    /**
+     * Path to this developer's profile file, or null. Stored as it was given, so
+     * a path relative to the board root survives the checkout moving; read
+     * through `profileRef`, which is what resolves it.
+     */
+    profile: string | null;
+}
+/** Overrides the stored user; handy for CI and shared machines. */
+export declare const USER_ENV_VAR = "LPM_USER";
+/** Overrides the stored profile path, for a shell that serves one developer. */
+export declare const PROFILE_ENV_VAR = "LPM_PROFILE";
+export declare function readLocal(paths: BoardPaths): LocalSettings;
+export declare function writeLocal(paths: BoardPaths, settings: LocalSettings): void;
+/**
+ * Whoever the CLI should act as, as written (an id or a name — the caller
+ * resolves it against the roster). The environment wins over the stored value.
+ */
+export declare function currentUserRef(paths: BoardPaths): string | null;
+/** Where a reference to a profile file came from, so the CLI can say. */
+export type ProfileSource = 'env' | 'local';
+/**
+ * The profile file to use, as written, and where that answer came from. The
+ * environment wins, so one shell can serve a different developer than the
+ * checkout is set up for.
+ */
+export declare function profileRef(paths: BoardPaths): {
+    ref: string;
+    source: ProfileSource;
+} | null;
+/**
+ * A stored path, made absolute. `~` is expanded because a profile is a file a
+ * developer keeps in their home directory as often as in the repository, and
+ * anything relative is resolved against the board root rather than the cwd, so
+ * `lpm` gives the same answer from any folder in the checkout.
+ */
+export declare function resolveProfilePath(paths: BoardPaths, ref: string): string;
+/**
+ * The ignore entries this board's `.lpm/.gitignore` is still missing, in the
+ * order they should appear. The read-only half of `ensureLocalIgnored`; the
+ * check reports from this, and the fix calls the writer.
+ */
+export declare function missingIgnoredEntries(paths: BoardPaths): string[];
+/**
+ * Add `local.json`, the credentials file, the write lock and remote credential
+ * patterns to `.lpm/.gitignore`. Returns true if the file changed.
+ */
+export declare function ensureLocalIgnored(paths: BoardPaths): boolean;