light-plan 0.0.0-stage → 0.1.0

package/dist/core/operations/shared.js

@@ -0,0 +1,383 @@
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import path from 'node:path';
+import { findIssue, findNode, findOfKind, findPeriod, findResource, isGenericResource, nodesOf, subtreeOf } from '../board/query.js';
+import { allowedDepths, hierarchyFor, prefixFor, statusIds } from '../config/lookup.js';
+import { requirePlacement } from '../board/registry.js';
+import { holdsPlaceholder } from '../../shared/template-params.js';
+import { BoardError, ConflictError } from '../errors.js';
+import { initialValueFor, isCalendarDate, validateAttributeValue } from '../model/attributes.js';
+import { hasPeriods, hasResources } from '../model/types.js';
+import { appendActivityEntry } from '../storage/activity.js';
+import { sameStamp, stampOf } from '../storage/atomic.js';
+import { writeNode } from '../storage/document.js';
+import { withBoardWrite } from './git-sync.js';
+import { collectionDir, displayPath, documentFileName, nodeDirName } from '../storage/paths.js';
+import { allocateIds, counterFor } from '../storage/state.js';
+/**
+ * Guards and builders shared by create/move/link. Internal to this folder:
+ * the public surface is the operations themselves.
+ */
+/**
+ * Run an operation as the board's only writer.
+ *
+ * Every exported operation wraps its body in this, so a board on a shared
+ * checkout serializes its writers instead of interleaving them. It nests, so an
+ * operation built out of other operations — `flagIssue` writing a document and
+ * then a comment, `claimIssue` delegating to `moveNode` — takes the lock once.
+ *
+ * `what` is what to tell whoever is waiting; name the document when there is
+ * one. @see src/core/storage/lock.ts
+ */
+export function boardWrite(board, what, run) {
+    // When the board is shared through git, the same call commits what `run`
+    // wrote and pushes it — or undoes it and refuses. See operations/git-sync.ts.
+    return withBoardWrite(board.paths, what, run, board.config);
+}
+/**
+ * Refuse to write over a change this handle never saw.
+ *
+ * The lock stops two writers overlapping; it cannot help a writer that read the
+ * board *before* taking it. That is every operation: a caller loads a board,
+ * decides what to do, and only then calls in — and on a shared checkout the
+ * document may have been rewritten in between. Comparing the file against the
+ * stamp the load recorded is what turns "the last write wins" into "the second
+ * writer is told".
+ *
+ * Called before an operation mutates anything, so a refusal leaves nothing
+ * half-done. A document with no stamp is one this handle never read — a
+ * document being created — and is not a conflict.
+ */
+export function requireUnchanged(board, node) {
+    const expected = board.stamps.get(node.file);
+    if (!expected)
+        return;
+    const actual = stampOf(node.file);
+    if (actual && sameStamp(expected, actual))
+        return;
+    throw new ConflictError(actual
+        ? `${node.id} changed on disk while you were working on it`
+        : `${node.id} was deleted while you were working on it`, [
+        `Somebody else — a person, an agent or an editor — wrote ${displayPath(board.paths, node.file)}.`,
+        'Nothing was written, so nothing was lost. Read it again and repeat the change.',
+    ]);
+}
+/**
+ * Write a document and record what was written, so this handle knows it.
+ *
+ * The stamp update is what lets one operation write the same document twice —
+ * a status roll-up and a flag roll-up can meet on the same container — without
+ * the second write mistaking its own predecessor for somebody else's edit.
+ */
+export function writeDocument(board, node) {
+    writeNode(node, board.config);
+    const stamp = stampOf(node.file);
+    if (stamp)
+        board.stamps.set(node.file, stamp);
+}
+/**
+ * Change an issue's flag and record the change in its body, in one call. The
+ * only way to move a flag, and the reason is that the two must not come apart.
+ *
+ * A flag is the one field on a board that says *work has stopped now*, and it
+ * is set and cleared as often by the engine as by a person: a container gains
+ * one because a story four levels down was flagged, an issue loses one because
+ * somebody finished it, `check --fix` repairs a container that drifted. None of
+ * those writes a comment — `_comments.md` is where a *person* explains a stall,
+ * and one derived entry per ancestor per flag would bury the explanation the
+ * flag exists to carry. So the activity section is the record, and it has to be
+ * written for every flag change including the ones nobody typed. Otherwise the
+ * common case is a red box in `_issue.md`, or a red box that quietly went away,
+ * with nothing in the file or in the board's git history saying when or why.
+ *
+ * Four callers, and there must never be a fifth that skips this:
+ * `flagIssue`/`clearFlag` (somebody said so), `moveNode` (finishing the work
+ * answered the flag), and both roll-ups in `rollup.ts` (the containers above
+ * it). `test/flags.test.ts` greps this package for a bare assignment to
+ * `flag` and fails if one appears anywhere but here.
+ */
+export function setFlag(issue, flag, entry) {
+    issue.flag = flag;
+    issue.body = appendActivityEntry(issue.body, { ...entry, text: entry.text ?? '' });
+}
+import { typeDefOf as typeDefByConfig } from '../config/lookup.js';
+export function typeDefOf(board, kind, type) {
+    return typeDefByConfig(board.config, kind, type);
+}
+export function requireStatus(board, status) {
+    const ids = statusIds(board.config);
+    if (!ids.includes(status)) {
+        throw new BoardError(`Unknown status "${status}"`, [`Available statuses: ${ids.join(', ')}`]);
+    }
+}
+export function requirePeriod(board, periodId) {
+    if (!hasPeriods(board.config)) {
+        throw new BoardError('This board has no time hierarchy', [
+            'Add period_types, period_hierarchy and period_prefix to .lpm/config.yml.',
+        ]);
+    }
+    const period = findPeriod(board, periodId);
+    if (!period)
+        throw new BoardError(`No period with id "${periodId}"`);
+    return period;
+}
+export function requireResource(board, idOrName) {
+    if (!hasResources(board.config)) {
+        throw new BoardError('This board has no team roster', [
+            'Add resource_types, resource_hierarchy and resource_prefix to .lpm/config.yml.',
+        ]);
+    }
+    const resource = findResource(board, idOrName);
+    if (!resource) {
+        throw new BoardError(`No resource with id or name "${idOrName}"`, [
+            board.resources.length
+                ? `Roster: ${board.resources.map((entry) => `${entry.id} (${entry.title})`).join(', ')}`
+                : 'The roster is empty; add someone with `lpm new <resource type> -t "Name"`.',
+        ]);
+    }
+    return resource;
+}
+/** A pool anyone can be drawn from, as opposed to a named person. */
+export function requireGenericResource(board, idOrName) {
+    const resource = requireResource(board, idOrName);
+    if (!isGenericResource(board, resource)) {
+        throw new BoardError(`${resource.id} (${resource.title}) is a named resource, not a pool`, [
+            'Only generic resources — types declared with `generic: true` — can be covered.',
+        ]);
+    }
+    return resource;
+}
+export function requireCapacity(capacity) {
+    if (!Number.isFinite(capacity) || capacity < 0) {
+        throw new BoardError(`Invalid capacity "${capacity}"`, [
+            'Capacity is full-time equivalents: 1 for one person, 0.5 part-time, 3 for a pool of three.',
+        ]);
+    }
+}
+/** Validate the targets of a `covers` list, normalizing ids and dropping duplicates. */
+export function resolveCoverTargets(board, ids) {
+    const resolved = [];
+    for (const raw of ids) {
+        const id = raw.trim();
+        if (!id)
+            continue;
+        const pool = requireGenericResource(board, id);
+        if (!resolved.includes(pool.id))
+            resolved.push(pool.id);
+    }
+    return resolved;
+}
+export function requireDates(starts, ends) {
+    if (!isCalendarDate(starts)) {
+        throw new BoardError(`Invalid start date "${starts}"`, ['Use YYYY-MM-DD.']);
+    }
+    if (!isCalendarDate(ends)) {
+        throw new BoardError(`Invalid end date "${ends}"`, ['Use YYYY-MM-DD.']);
+    }
+    if (ends < starts)
+        throw new BoardError(`Period ends (${ends}) before it starts (${starts})`);
+}
+/**
+ * Resolve the parent for a new document and check it sits at a depth its type
+ * is allowed at.
+ *
+ * Depths are a list rather than one number because of the registry's `folder`,
+ * which stands in for whichever level nobody templatized and so is legal at all
+ * of them. Every declared type appears at exactly one level, so for issues,
+ * periods, resources and squads the list has one entry and this reads as it
+ * always did. @see allowedDepths
+ */
+export function resolveParentFor(board, kind, type, parentId) {
+    const depths = allowedDepths(board.config, kind, type);
+    const levels = hierarchyFor(board.config, kind);
+    const parent = parentId
+        ? (findOfKind(board, kind, parentId) ?? null)
+        : null;
+    if (parentId && !parent)
+        throw new BoardError(`No ${kind} with id "${parentId}"`);
+    const parentsOf = (depth) => levels[depth - 1] ?? [];
+    const allowedParents = [...new Set(depths.flatMap(parentsOf))];
+    if (parent) {
+        if (!depths.includes(parent.depth + 1)) {
+            throw new BoardError(`"${type}" cannot be nested under "${parent.type}" (${parent.id})`, [
+                allowedParents.length
+                    ? `"${type}" belongs under: ${allowedParents.join(', ')}`
+                    : `"${type}" is a top-level type; create it without --parent`,
+            ]);
+        }
+    }
+    else if (!depths.includes(0)) {
+        throw new BoardError(`"${type}" needs a parent ${kind}`, [
+            `Pass --parent <id>, where the parent is one of: ${allowedParents.join(', ')}`,
+        ]);
+    }
+    // The one rule the hierarchy cannot express: a registry folder groups
+    // templates and never sits inside one. @see src/core/board/registry.ts
+    if (kind === 'template')
+        requirePlacement(type, parent);
+    return parent;
+}
+/**
+ * Seed a document's attributes and validate the ones the caller supplied.
+ *
+ * `allowPlaceholders` is for the registry: a template's attributes are declared
+ * by the issue type it will produce, so a placeholder waiting for a parameter
+ * sits in a field of the wrong type until it is filled in. @see holdsPlaceholder
+ */
+export function buildAttributes(typeDef, type, given, allowPlaceholders = false) {
+    const attributes = {};
+    for (const [name, def] of Object.entries(typeDef.attributes)) {
+        attributes[name] = initialValueFor(def);
+    }
+    for (const [name, value] of Object.entries(given ?? {})) {
+        const def = typeDef.attributes[name];
+        if (!def) {
+            throw new BoardError(`"${name}" is not an attribute of "${type}"`, [
+                `Declared attributes: ${Object.keys(typeDef.attributes).join(', ') || '(none)'}`,
+            ]);
+        }
+        if (!(allowPlaceholders && holdsPlaceholder(value))) {
+            const problem = validateAttributeValue(def, value);
+            if (problem)
+                throw new BoardError(`Invalid value for "${name}": ${problem}`);
+        }
+        attributes[name] = value;
+    }
+    return attributes;
+}
+export function allocateFor(board, kind) {
+    // Guard against every collection: a stale or merge-mangled counter in any
+    // namespace must not produce an id that already exists, even though per-kind
+    // prefixes normally keep them apart.
+    const taken = new Set([
+        ...board.issues.map((issue) => issue.id),
+        ...board.periods.map((period) => period.id),
+        ...board.resources.map((resource) => resource.id),
+        ...board.squads.map((squad) => squad.id),
+        ...board.templates.map((template) => template.id),
+    ]);
+    return allocateIds(board.paths, counterFor(kind), prefixFor(board.config, kind), 1, taken)[0];
+}
+export function prepareFolder(board, parentDir, id) {
+    const dir = path.join(parentDir, nodeDirName(id));
+    if (existsSync(dir)) {
+        throw new BoardError(`Folder already exists: ${displayPath(board.paths, dir)}`);
+    }
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/**
+ * Resolve the node a document is being moved under, rejecting the two moves
+ * that would corrupt the tree: onto itself, and onto one of its descendants.
+ */
+export function resolveNewParent(board, node, parentId) {
+    if (parentId === null)
+        return null;
+    const parent = findOfKind(board, node.kind, parentId);
+    if (!parent)
+        throw new BoardError(`No ${node.kind} with id "${parentId}"`);
+    if (parent.dir === node.dir)
+        throw new BoardError('A document cannot be its own parent');
+    if (parent.dir.startsWith(node.dir + path.sep)) {
+        throw new BoardError(`Cannot move ${node.id} under its own descendant ${parent.id}`);
+    }
+    return parent;
+}
+/**
+ * Check that a document and everything below it still sit at a depth their
+ * types are allowed at. `overrideType` stands in for the target's own type when
+ * the caller is about to change it.
+ */
+export function requireSubtreeFits(board, target, newDepth, overrideType) {
+    const levels = hierarchyFor(board.config, target.kind);
+    for (const descendant of subtreeOf(nodesOf(board, target.kind), target)) {
+        const depth = newDepth + (descendant.depth - target.depth);
+        const type = descendant.dir === target.dir ? (overrideType ?? descendant.type) : descendant.type;
+        const allowed = levels[depth] ?? [];
+        if (!allowed.includes(type)) {
+            throw new BoardError(`This would break the hierarchy at ${descendant.id} ("${type}")`, [
+                allowed.length
+                    ? `Level ${depth} allows: ${allowed.join(', ')}`
+                    : `The hierarchy has no level ${depth}`,
+            ]);
+        }
+    }
+}
+/**
+ * Move a document's folder under `parent` (or to the collection root), keeping
+ * `dir`, `file`, `depth` and `parentId` on the passed node in step. Returns the
+ * new board-relative path, or nothing when the folder was already in place.
+ */
+export function relocateFolder(board, node, parent) {
+    const parentDir = parent ? parent.dir : collectionDir(board.paths, node.kind);
+    const newDir = path.join(parentDir, nodeDirName(node.id));
+    node.depth = parent ? parent.depth + 1 : 0;
+    node.parentId = parent ? parent.id : null;
+    if (newDir === node.dir)
+        return undefined;
+    if (existsSync(newDir)) {
+        throw new BoardError(`Folder already exists: ${displayPath(board.paths, newDir)}`);
+    }
+    mkdirSync(path.dirname(newDir), { recursive: true });
+    renameSync(node.dir, newDir);
+    node.dir = newDir;
+    node.file = path.join(newDir, documentFileName(node.kind));
+    return displayPath(board.paths, newDir);
+}
+/**
+ * Tidy a `related_files` list: trim, drop blanks, drop duplicates, keep order.
+ *
+ * Nothing here touches the filesystem or rewrites a path. A reference may name
+ * a file that does not exist yet, may carry a line range (`#L10-L42`), and is
+ * read by people and agents in whatever checkout they have — so normalizing it
+ * to an absolute path would break the one job it has.
+ */
+export function normalizeFileRefs(refs) {
+    const seen = [];
+    for (const raw of refs) {
+        const ref = raw.trim();
+        if (ref && !seen.includes(ref))
+            seen.push(ref);
+    }
+    return seen;
+}
+/** Validate a list of link targets, normalizing ids and dropping duplicates. */
+export function resolveLinkTargets(board, ids) {
+    const resolved = [];
+    for (const raw of ids) {
+        const id = raw.trim();
+        if (!id)
+            continue;
+        const issue = findIssue(board, id);
+        if (!issue) {
+            const node = findNode(board, id);
+            throw new BoardError(node ? `${node.id} is a ${node.type}; only issues can be linked` : `No issue with id "${id}"`);
+        }
+        if (!resolved.includes(issue.id))
+            resolved.push(issue.id);
+    }
+    return resolved;
+}
+/**
+ * The same, inside the registry. A template's dependencies name other templates
+ * — they become dependencies between the issues an instantiation produces — so
+ * an edge out of the registry into the board is refused rather than copied.
+ */
+export function resolveTemplateLinkTargets(board, ids) {
+    const resolved = [];
+    for (const raw of ids) {
+        const id = raw.trim();
+        if (!id)
+            continue;
+        const template = findOfKind(board, 'template', id);
+        if (!template) {
+            const node = findNode(board, id);
+            throw new BoardError(node
+                ? `${node.id} is a ${node.kind}; a template can only be linked to another template`
+                : `No template with id "${id}"`);
+        }
+        if (!resolved.includes(template.id))
+            resolved.push(template.id);
+    }
+    return resolved;
+}
+//# sourceMappingURL=shared.js.map

package/dist/core/operations/shared.js.map

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

package/dist/core/operations/update.d.ts

@@ -0,0 +1,43 @@
+import type { LoadedBoard } from '../board/load.js';
+import type { AnyNode, ParamDefs } from '../model/types.js';
+/**
+ * Edits to a document's own content. Everything that changes where a document
+ * *sits* (parent, status, period, assignee) belongs to `moveNode`, and changing
+ * its type belongs to `retypeNode`; this is the payload of the document itself.
+ *
+ * Nothing here touches the filesystem layout: a folder is named after the id
+ * alone, so a document keeps its folder however often it is retitled.
+ */
+export interface UpdateInput {
+    title?: string;
+    body?: string;
+    /** Merged over the current attributes; `undefined` values remove a key. */
+    attributes?: Record<string, unknown>;
+    /** Issues and templates only: the complete list of files this document is about. */
+    relatedFiles?: string[];
+    /** Templates only: what this template is for, as the registry shows it. */
+    description?: string;
+    /** Templates only: the complete set of parameters this template asks for. */
+    params?: ParamDefs;
+    /** Periods only. */
+    starts?: string;
+    /** Periods only. */
+    ends?: string;
+    /**
+     * Periods only: the switch over the dates. `true` runs it, `false` parks it,
+     * `null` takes the switch off again and hands the period back to its dates.
+     */
+    active?: boolean | null;
+    /** Periods only: squad that owns this period; `null` to clear. */
+    squad?: string | null;
+    /** Resources only. */
+    capacity?: number;
+    /** Resources only: generic resources this one can be drawn from. */
+    covers?: string[];
+    /** Squads only: resource ids that belong to this squad. */
+    members?: string[];
+}
+export interface UpdateResult {
+    node: AnyNode;
+}
+export declare function updateNode(board: LoadedBoard, target: AnyNode, input: UpdateInput): UpdateResult;

package/dist/core/operations/update.js

@@ -0,0 +1,161 @@
+import { BoardError } from '../errors.js';
+import { validateAttributeValue } from '../model/attributes.js';
+import { isFolderTemplate } from '../model/types.js';
+import { holdsPlaceholder } from '../../shared/template-params.js';
+import { nowIso } from '../storage/document.js';
+import { mergeActivity } from '../storage/activity.js';
+import { writeBoardIndex } from './board-index.js';
+import { boardWrite, normalizeFileRefs, requireCapacity, requireDates, requireUnchanged, resolveCoverTargets, typeDefOf, writeDocument, } from './shared.js';
+function forKind(node, kind, field) {
+    if (node.kind !== kind) {
+        throw new BoardError(`${node.id} is a ${node.kind}; "${field}" applies to ${kind}s only`);
+    }
+}
+export function updateNode(board, target, input) {
+    return boardWrite(board, `update ${target.id}`, () => updateUnderLock(board, target, input));
+}
+function updateUnderLock(board, target, input) {
+    requireUnchanged(board, target);
+    const node = { ...target, attributes: { ...target.attributes } };
+    if (input.title !== undefined) {
+        const title = input.title.trim();
+        if (!title)
+            throw new BoardError(`${node.kind} title cannot be empty`);
+        node.title = title;
+    }
+    // Merge the incoming body with the on-disk body so a stale body edit
+    // queued before a flag event and pushed after it cannot clobber the
+    // activity section. Incoming prose wins; on-disk activity section wins.
+    // Consequence: history is not editable through the tools — corrections
+    // are a hand edit to the git-tracked file.
+    if (input.body !== undefined)
+        node.body = mergeActivity(input.body, target.body);
+    if (input.attributes) {
+        const typeDef = node.type ? typeDefOf(board, node.kind, node.type) : null;
+        for (const [name, value] of Object.entries(input.attributes)) {
+            if (value === undefined) {
+                delete node.attributes[name];
+                continue;
+            }
+            const def = typeDef?.attributes[name];
+            // Undeclared keys are preserved rather than rejected: `load` keeps the
+            // extras people add by hand, and `check` is what reports them.
+            // A template's attribute may hold a placeholder instead of a value —
+            // `story_points: "{{points}}"` in an integer field — which is what a
+            // template *is*. @see holdsPlaceholder
+            if (def && !(node.kind === 'template' && holdsPlaceholder(value))) {
+                const problem = validateAttributeValue(def, value);
+                if (problem)
+                    throw new BoardError(`Invalid value for "${name}": ${problem}`);
+            }
+            node.attributes[name] = value;
+        }
+    }
+    if (input.relatedFiles !== undefined) {
+        if (node.kind !== 'issue' && node.kind !== 'template') {
+            throw new BoardError(`${node.id} is a ${node.kind}; "related files" applies to issues and templates only`);
+        }
+        node.related_files = normalizeFileRefs(input.relatedFiles);
+    }
+    if (input.description !== undefined) {
+        forKind(node, 'template', 'description');
+        if (node.kind === 'template')
+            node.description = input.description.trim();
+    }
+    if (input.params !== undefined) {
+        forKind(node, 'template', 'params');
+        if (node.kind === 'template') {
+            // Only a root asks for anything; its children take the answers it was
+            // given. `createTemplate` refuses the same two placements, and `check`
+            // reports a document that already has them. @see isTemplateRoot
+            if (Object.keys(input.params).length) {
+                if (isFolderTemplate(node)) {
+                    throw new BoardError('A folder cannot declare parameters', [
+                        'Parameters belong on the template somebody instantiates, not on the folder holding it.',
+                    ]);
+                }
+                const parent = node.parentId ? board.templatesById.get(node.parentId) : undefined;
+                if (parent && !isFolderTemplate(parent)) {
+                    throw new BoardError('Only a root declares parameters', [
+                        `${node.id} sits inside the template ${parent.id}, so it is part of one.`,
+                        `Put the parameters on whatever root holds ${node.id}.`,
+                    ]);
+                }
+            }
+            node.params = input.params;
+        }
+    }
+    if (input.starts !== undefined || input.ends !== undefined) {
+        forKind(node, 'period', 'starts/ends');
+        const starts = input.starts ?? (node.kind === 'period' ? node.starts : undefined);
+        const ends = input.ends ?? (node.kind === 'period' ? node.ends : undefined);
+        if (!starts || !ends)
+            throw new BoardError('A period needs both a start and an end date');
+        requireDates(starts, ends);
+        if (node.kind === 'period') {
+            node.starts = starts;
+            node.ends = ends;
+        }
+    }
+    if (input.active !== undefined) {
+        forKind(node, 'period', 'active');
+        // `null` removes the key rather than writing a third value: a period is
+        // either switched on, switched off, or back on its dates.
+        if (node.kind === 'period')
+            node.active = input.active ?? undefined;
+    }
+    if (input.squad !== undefined) {
+        forKind(node, 'period', 'squad');
+        if (input.squad !== null) {
+            const squadsById = board.squadsById;
+            if (!squadsById.get(input.squad)) {
+                throw new BoardError(`No squad with id "${input.squad}"`, [
+                    board.squads.length
+                        ? `Available squads: ${board.squads.map((s) => `${s.id} (${s.title})`).join(', ')}`
+                        : 'This board has no squads.',
+                ]);
+            }
+        }
+        if (node.kind === 'period')
+            node.squad = input.squad;
+    }
+    if (input.capacity !== undefined) {
+        forKind(node, 'resource', 'capacity');
+        requireCapacity(input.capacity);
+        if (node.kind === 'resource')
+            node.capacity = input.capacity;
+    }
+    if (input.covers !== undefined) {
+        forKind(node, 'resource', 'covers');
+        const covers = resolveCoverTargets(board, input.covers);
+        if (covers.includes(node.id))
+            throw new BoardError(`${node.id} cannot cover itself`);
+        if (node.kind === 'resource')
+            node.covers = covers;
+    }
+    if (input.members !== undefined) {
+        forKind(node, 'squad', 'members');
+        const resolved = [];
+        for (const raw of input.members) {
+            const id = raw.trim();
+            if (!id)
+                continue;
+            const resource = board.resourcesById.get(id);
+            if (!resource)
+                throw new BoardError(`No resource with id "${id}"`);
+            if (!resolved.includes(resource.id))
+                resolved.push(resource.id);
+        }
+        if (resolved.includes(node.id))
+            throw new BoardError(`${node.id} cannot be a member of itself`);
+        if (node.kind === 'squad')
+            node.members = resolved;
+    }
+    node.updated = nowIso();
+    writeDocument(board, node);
+    // A folder is named after the id, so renaming a document never moves it —
+    // but the index carries the title, so it still has to be rewritten.
+    writeBoardIndex(board, { node });
+    return { node };
+}
+//# sourceMappingURL=update.js.map

package/dist/core/operations/update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../src/core/operations/update.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,SAAS,EACT,aAAa,GACd,MAAM,aAAa,CAAC;AA4CrB,SAAS,OAAO,CAAC,IAAa,EAAE,IAAqB,EAAE,KAAa;IAClE,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,CAAC,EAAE,SAAS,IAAI,CAAC,IAAI,MAAM,KAAK,gBAAgB,IAAI,QAAQ,CAAC,CAAC;IAC5F,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,KAAkB,EAClB,MAAe,EACf,KAAkB;IAElB,OAAO,UAAU,CAAC,KAAK,EAAE,UAAU,MAAM,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAC/F,CAAC;AAED,SAAS,eAAe,CAAC,KAAkB,EAAE,MAAe,EAAE,KAAkB;IAC9E,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,IAAI,GAAY,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;IAE1E,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,CAAC,IAAI,wBAAwB,CAAC,CAAC;QACvE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,qEAAqE;IACrE,oEAAoE;IACpE,wEAAwE;IACxE,uEAAuE;IACvE,2CAA2C;IAC3C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAEjF,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1E,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;gBAC7B,SAAS;YACX,CAAC;YACD,MAAM,GAAG,GAAG,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;YACtC,uEAAuE;YACvE,+DAA+D;YAC/D,qEAAqE;YACrE,qEAAqE;YACrE,uCAAuC;YACvC,IAAI,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;gBAClE,MAAM,OAAO,GAAG,sBAAsB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBACnD,IAAI,OAAO;oBAAE,MAAM,IAAI,UAAU,CAAC,sBAAsB,IAAI,MAAM,OAAO,EAAE,CAAC,CAAC;YAC/E,CAAC;YACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAChC,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACtD,MAAM,IAAI,UAAU,CAClB,GAAG,IAAI,CAAC,EAAE,SAAS,IAAI,CAAC,IAAI,wDAAwD,CACrF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,iBAAiB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;YAAE,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;IAC5E,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;QACpC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC7B,sEAAsE;YACtE,uEAAuE;YACvE,gEAAgE;YAChE,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;gBACrC,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC3B,MAAM,IAAI,UAAU,CAAC,oCAAoC,EAAE;wBACzD,wFAAwF;qBACzF,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBAClF,IAAI,MAAM,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;oBACxC,MAAM,IAAI,UAAU,CAAC,iCAAiC,EAAE;wBACtD,GAAG,IAAI,CAAC,EAAE,6BAA6B,MAAM,CAAC,EAAE,yBAAyB;wBACzE,6CAA6C,IAAI,CAAC,EAAE,GAAG;qBACxD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YACD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3D,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAClF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC5E,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,UAAU,CAAC,6CAA6C,CAAC,CAAC;QAC1F,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC3B,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;YACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAClC,wEAAwE;QACxE,0DAA0D;QAC1D,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,SAAS,CAAC;IACtE,CAAC;IAED,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACjC,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACzB,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;YACpC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjC,MAAM,IAAI,UAAU,CAAC,qBAAqB,KAAK,CAAC,KAAK,GAAG,EAAE;oBACxD,KAAK,CAAC,MAAM,CAAC,MAAM;wBACjB,CAAC,CAAC,qBAAqB,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;wBACnF,CAAC,CAAC,2BAA2B;iBAChC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACvD,CAAC;IAED,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;QACtC,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;YAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAC/D,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,CAAC,EAAE,sBAAsB,CAAC,CAAC;QACrF,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;YAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACrD,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAChC,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;YACtB,IAAI,CAAC,EAAE;gBAAE,SAAS;YAClB,MAAM,QAAQ,GAAG,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC7C,IAAI,CAAC,QAAQ;gBAAE,MAAM,IAAI,UAAU,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;YACnE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,CAAC,EAAE,+BAA+B,CAAC,CAAC;QAChG,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC;IACrD,CAAC;IAED,IAAI,CAAC,OAAO,GAAG,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC3B,0EAA0E;IAC1E,oEAAoE;IACpE,eAAe,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACjC,OAAO,EAAE,IAAI,EAAE,CAAC;AAClB,CAAC"}

package/dist/core/operations/user.d.ts

@@ -0,0 +1,27 @@
+import type { LoadedBoard } from '../board/load.js';
+import type { Resource } from '../model/types.js';
+/**
+ * Who is driving the CLI. Stored per checkout in `.lpm/local.json` (never
+ * committed) and overridable with `LPM_USER`, because the answer belongs to the
+ * machine, not to the board.
+ */
+export interface CurrentUser {
+    /** What was stored or passed in the environment, verbatim. */
+    ref: string;
+    /** The roster entry it resolves to, or null when it matches nothing. */
+    resource: Resource | null;
+    /** Which of the three answers won. */
+    source: UserSource;
+}
+/**
+ * Most specific first: an environment variable is set for one command, a
+ * profile is the file this developer was handed, and `local.json` is what
+ * `lpm me` wrote. `lpm me` therefore reports which one is talking, because a
+ * profile that quietly overrode it would be a confusing way to be someone else.
+ */
+export type UserSource = 'env' | 'profile' | 'local';
+export declare function currentUser(board: LoadedBoard): CurrentUser | null;
+/** The current user, or a `BoardError` explaining how to set one. */
+export declare function requireCurrentUser(board: LoadedBoard): Resource;
+export declare function setCurrentUser(board: LoadedBoard, idOrName: string): Resource;
+export declare function clearCurrentUser(board: LoadedBoard): void;