light-plan 0.0.0-stage → 0.1.0

package/dist/core/operations/user.js

@@ -0,0 +1,68 @@
+import { findResource, isGenericResource } from '../board/query.js';
+import { BoardError } from '../errors.js';
+import { hasResources } from '../model/types.js';
+import { profileUserRef } from '../profile/current.js';
+import { USER_ENV_VAR, readLocal, writeLocal } from '../storage/local.js';
+export function currentUser(board) {
+    const found = (() => {
+        const fromEnv = process.env[USER_ENV_VAR]?.trim();
+        if (fromEnv)
+            return { ref: fromEnv, source: 'env' };
+        const fromProfile = profileUserRef(board.paths);
+        if (fromProfile)
+            return { ref: fromProfile, source: 'profile' };
+        const stored = readLocal(board.paths).user;
+        return stored ? { ref: stored, source: 'local' } : null;
+    })();
+    if (!found)
+        return null;
+    return { ref: found.ref, resource: findResource(board, found.ref), source: found.source };
+}
+/** The current user, or a `BoardError` explaining how to set one. */
+export function requireCurrentUser(board) {
+    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 user = currentUser(board);
+    if (!user) {
+        throw new BoardError('No current user set', [
+            'Run `lpm me <id or name>` to say who you are.',
+        ]);
+    }
+    if (!user.resource) {
+        throw new BoardError(`Current user "${user.ref}" is not in the roster`, [
+            user.source === 'profile'
+                ? 'It came from your profile; fix its `user:` or run `lpm profile --clear`.'
+                : 'Run `lpm me <id or name>` to pick someone who is.',
+        ]);
+    }
+    return user.resource;
+}
+export function setCurrentUser(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; create someone with `lpm new <type> -t "Your name"`.',
+        ]);
+    }
+    if (isGenericResource(board, resource)) {
+        throw new BoardError(`${resource.id} (${resource.title}) is a pool, not a person`, [
+            'The current user has to be a named resource.',
+        ]);
+    }
+    writeLocal(board.paths, { ...readLocal(board.paths), user: resource.id });
+    return resource;
+}
+export function clearCurrentUser(board) {
+    writeLocal(board.paths, { ...readLocal(board.paths), user: null });
+}
+//# sourceMappingURL=user.js.map

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

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

package/dist/core/profile/current.d.ts

@@ -0,0 +1,35 @@
+import type { LoadedBoard } from '../board/load.js';
+import type { ResolvedScope } from '../board/scope.js';
+import type { Profile } from '../model/profile.js';
+import type { BoardPaths } from '../storage/paths.js';
+import type { ProfileSource } from '../storage/local.js';
+/**
+ * The profile in force for this checkout, and what it means on this board.
+ *
+ * Read fresh every time rather than cached on the board: the file lives outside
+ * `.lpm`, a `LoadedBoard` handle outlives it, and it is a few hundred bytes.
+ */
+export interface CurrentProfile {
+    /** The absolute path it was read from. */
+    file: string;
+    /** How that path was found. */
+    source: ProfileSource;
+    /** Null when the file is missing or does not parse; see `errors`. */
+    profile: Profile | null;
+    /** Why it did not load, or why it should not be trusted. Never thrown. */
+    errors: string[];
+}
+/**
+ * A broken profile is reported, never fatal. The alternative is a developer
+ * whose every command fails because a file they were handed has a typo in it,
+ * which helps nobody — the CLI says so, and carries on unscoped.
+ */
+export declare function currentProfile(paths: BoardPaths): CurrentProfile | null;
+/** The identity a profile claims, for the precedence chain in `currentUser`. */
+export declare function profileUserRef(paths: BoardPaths): string | null;
+/**
+ * What this developer should be offered, resolved against this board. No
+ * profile, an unreadable one, or one that declares no scope all mean the whole
+ * board — the scope has to be *stated* to bite.
+ */
+export declare function currentScope(board: LoadedBoard): ResolvedScope;

package/dist/core/profile/current.js

@@ -0,0 +1,31 @@
+import { fullScope, resolveScope } from '../board/scope.js';
+import { profileRef, resolveProfilePath } from '../storage/local.js';
+import { loadProfileFile } from './schema.js';
+/**
+ * A broken profile is reported, never fatal. The alternative is a developer
+ * whose every command fails because a file they were handed has a typo in it,
+ * which helps nobody — the CLI says so, and carries on unscoped.
+ */
+export function currentProfile(paths) {
+    const ref = profileRef(paths);
+    if (!ref)
+        return null;
+    const file = resolveProfilePath(paths, ref.ref);
+    const { profile, errors } = loadProfileFile(file);
+    return { file, source: ref.source, profile, errors };
+}
+/** The identity a profile claims, for the precedence chain in `currentUser`. */
+export function profileUserRef(paths) {
+    return currentProfile(paths)?.profile?.user ?? null;
+}
+/**
+ * What this developer should be offered, resolved against this board. No
+ * profile, an unreadable one, or one that declares no scope all mean the whole
+ * board — the scope has to be *stated* to bite.
+ */
+export function currentScope(board) {
+    const current = currentProfile(board.paths);
+    const scope = current?.profile?.scope;
+    return scope ? resolveScope(board, scope) : fullScope();
+}
+//# sourceMappingURL=current.js.map

package/dist/core/profile/current.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"current.js","sourceRoot":"","sources":["../../../src/core/profile/current.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAI5D,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAmB9C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAiB;IAC9C,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,IAAI,GAAG,kBAAkB,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACvD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,cAAc,CAAC,KAAiB;IAC9C,OAAO,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAkB;IAC7C,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC;IACtC,OAAO,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;AAC1D,CAAC"}

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

@@ -0,0 +1,14 @@
+/**
+ * Developer profiles: the file one person is handed that says who they are and
+ * which part of the board is theirs.
+ *
+ *   schema.ts   parsing and validating the file (strict: a typo is an error)
+ *   current.ts  finding the one in force, and resolving its scope for a board
+ *
+ * The types live in `model/profile.ts` and the evaluation in `board/scope.ts`,
+ * because a scope is a way of reading a board and this layer is only the file
+ * it arrived in. Nothing here is board truth: a profile is never committed to
+ * `.lpm`, and `check` neither reads one nor cares that it exists.
+ */
+export * from './current.js';
+export * from './schema.js';

package/dist/core/profile/index.js

@@ -0,0 +1,15 @@
+/**
+ * Developer profiles: the file one person is handed that says who they are and
+ * which part of the board is theirs.
+ *
+ *   schema.ts   parsing and validating the file (strict: a typo is an error)
+ *   current.ts  finding the one in force, and resolving its scope for a board
+ *
+ * The types live in `model/profile.ts` and the evaluation in `board/scope.ts`,
+ * because a scope is a way of reading a board and this layer is only the file
+ * it arrived in. Nothing here is board truth: a profile is never committed to
+ * `.lpm`, and `check` neither reads one nor cares that it exists.
+ */
+export * from './current.js';
+export * from './schema.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/profile/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/core/profile/schema.d.ts

@@ -0,0 +1,9 @@
+import type { Profile } from '../model/profile.js';
+export interface ProfileResult {
+    profile: Profile | null;
+    errors: string[];
+}
+export declare function parseProfileText(text: string): ProfileResult;
+export declare function loadProfileFile(file: string): ProfileResult;
+/** The starter `lpm profile --init` writes, and the format's worked example. */
+export declare function profileTemplate(user?: string): string;

package/dist/core/profile/schema.js

@@ -0,0 +1,100 @@
+import { readFileSync } from 'node:fs';
+import YAML from 'yaml';
+import { z } from 'zod';
+/**
+ * Parsing a profile file: `.lpm/config.yml`'s counterpart for one developer.
+ *
+ * Deliberately strict. The board config can afford to be forgiving about a key
+ * it does not recognise; a profile cannot, because the failure mode is silent
+ * and one-directional — a mistyped `excludes:` would hand someone the whole
+ * board and nothing would ever say so. An unknown key is an error.
+ *
+ * YAML is a superset of JSON, so a `.json` profile parses here too.
+ */
+/**
+ * A list, written as one either way: `under: LP-2` and `under: [LP-2]`. A key
+ * left empty is the same as not writing it — `scope:` with every line beneath
+ * it commented out is the shape the starter file ships in, and it has to mean
+ * "no opinion" rather than "scope me to nothing".
+ */
+const nameList = z
+    .union([z.string(), z.array(z.string())])
+    .transform((value) => (typeof value === 'string' ? [value] : value))
+    .pipe(z.array(z.string().trim().min(1)))
+    .nullish()
+    .transform((value) => value ?? undefined);
+const scopeSchema = z
+    .object({
+    under: nameList,
+    exclude: nameList,
+    types: nameList,
+    periods: nameList,
+})
+    .strict();
+const profileSchema = z
+    .object({
+    user: z.string().trim().min(1).nullish(),
+    scope: scopeSchema.nullish().transform((value) => value ?? {}),
+})
+    .strict();
+import { formatZodIssues } from '../model/zod.js';
+export function parseProfileText(text) {
+    let doc;
+    try {
+        doc = YAML.parse(text);
+    }
+    catch (error) {
+        return { profile: null, errors: [`invalid YAML: ${error.message}`] };
+    }
+    // An empty file is a profile that claims nothing, not a broken one.
+    if (doc === null || doc === undefined)
+        return { profile: { user: null, scope: {} }, errors: [] };
+    const parsed = profileSchema.safeParse(doc);
+    if (!parsed.success)
+        return { profile: null, errors: formatZodIssues(parsed.error) };
+    const { user, scope } = parsed.data;
+    // A key with nothing under it is dropped, so `scope: { under: undefined }`
+    // never reaches `resolveScope` claiming to have been declared.
+    return {
+        profile: {
+            user: user ?? null,
+            scope: Object.fromEntries(Object.entries(scope).filter(([, value]) => value !== undefined)),
+        },
+        errors: [],
+    };
+}
+export function loadProfileFile(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        return { profile: null, errors: [`cannot read profile: ${error.message}`] };
+    }
+    return parseProfileText(text);
+}
+/** The starter `lpm profile --init` writes, and the format's worked example. */
+export function profileTemplate(user) {
+    return `# A light-plan profile: who you are, and which part of the board is yours.
+# Point light-plan at it with \`lpm profile <this file>\` or LPM_PROFILE.
+
+# The roster entry you act as — an id or a name.
+user: ${user ?? 'RS-1'}
+
+# What gets offered to you. Every key is optional; leave the section out
+# entirely to be offered the whole board.
+scope:
+  # Only work at or below these documents.
+  # under: [LP-2]
+
+  # Never these documents, nor anything below them. Wins over \`under\`.
+  # exclude: [LP-9]
+
+  # Only issues of these types.
+  # types: [story, bug]
+
+  # Only work scheduled in these periods, or in a period below one of them.
+  # periods: [TL-2]
+`;
+}
+//# sourceMappingURL=schema.js.map

package/dist/core/profile/schema.js.map

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

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

@@ -0,0 +1,78 @@
+/**
+ * Activity section codec — pure text in, text out.
+ *
+ * An activity section is a delimited block at the end of an issue body that
+ * records flag raise, clear and auto-clear events. It looks like this:
+ *
+ * ```
+ * <!-- lpm:activity -->
+ *
+ * ## Activity
+ *
+ * ### 2026-08-10T14:03:11.000Z — fran — flagged: blocked
+ *
+ * Waiting on the API contract from LP-12.
+ * ```
+ *
+ * The marker is the seam: everything before it is the prose (editable body
+ * content); everything from the marker to EOF is the activity section.
+ *
+ * This module has no I/O and imports nothing beyond what pure text handling
+ * needs. It sits beside `comments.ts` in `src/core/storage/` because both
+ * answer the same question — "how do we record a timestamped note against a
+ * document?" — and they agree on the answer: append to a plain-text block so
+ * git merges it without conflict.
+ */
+export declare const ACTIVITY_MARKER = "<!-- lpm:activity -->";
+export interface ActivityEntry {
+    /** ISO timestamp. */
+    at: string;
+    author: string;
+    /** Event label, e.g. "flagged: blocked", "flag cleared". */
+    heading: string;
+    /** Entry body (optional prose under the heading line). */
+    text: string;
+}
+/**
+ * Split `body` at the first activity marker.
+ *
+ * Returns `prose` (everything before the marker) and `activity` (the marker
+ * through EOF).  When there is no marker, `prose` is the entire body and
+ * `activity` is empty.
+ *
+ * A second marker appearing later in the body — hand-written or from a merge —
+ * stays inside `activity` verbatim (degraded, never lossy).
+ */
+export declare function splitActivity(body: string): {
+    prose: string;
+    activity: string;
+};
+/**
+ * Append an activity entry to `body`, creating the marker and section heading
+ * when they are absent.
+ *
+ * The entry's `heading` is the event label (e.g. "flagged: blocked"), rendered
+ * as a level-3 heading with the timestamp and author before it.
+ */
+export declare function appendActivityEntry(body: string, entry: {
+    at: string;
+    author: string;
+    heading: string;
+    text: string;
+}): string;
+/**
+ * Merge an incoming body edit with the on-disk body so a stale body write
+ * cannot clobber the activity section.
+ *
+ * Rule: the incoming body's own activity section (if any) is discarded; the
+ * disk's activity section is re-attached to the incoming prose.  This is the
+ * anti-clobber primitive — whatever a stale edit carries in its own activity
+ * section is replaced by disk truth.
+ */
+export declare function mergeActivity(incomingBody: string, diskBody: string): string;
+/**
+ * Parse an activity section body (the part after the marker and heading) into
+ * individual entries.  Used by tests and by anything that needs to inspect
+ * history.
+ */
+export declare function parseActivity(body: string): ActivityEntry[];

package/dist/core/storage/activity.js

@@ -0,0 +1,131 @@
+/**
+ * Activity section codec — pure text in, text out.
+ *
+ * An activity section is a delimited block at the end of an issue body that
+ * records flag raise, clear and auto-clear events. It looks like this:
+ *
+ * ```
+ * <!-- lpm:activity -->
+ *
+ * ## Activity
+ *
+ * ### 2026-08-10T14:03:11.000Z — fran — flagged: blocked
+ *
+ * Waiting on the API contract from LP-12.
+ * ```
+ *
+ * The marker is the seam: everything before it is the prose (editable body
+ * content); everything from the marker to EOF is the activity section.
+ *
+ * This module has no I/O and imports nothing beyond what pure text handling
+ * needs. It sits beside `comments.ts` in `src/core/storage/` because both
+ * answer the same question — "how do we record a timestamped note against a
+ * document?" — and they agree on the answer: append to a plain-text block so
+ * git merges it without conflict.
+ */
+export const ACTIVITY_MARKER = '<!-- lpm:activity -->';
+const ACTIVITY_HEADING = '## Activity';
+/**
+ * An entry heading strict enough that prose cannot be mistaken for one: the
+ * timestamp has to come first, followed by an em-dash, the author, another
+ * em-dash, and the event label.  Anything else after a `###` in the body is
+ * left alone.
+ */
+const ENTRY_HEADING = /^###[ \t]+(\d{4}-\d{2}-\d{2}T[0-9:.]+Z)[ \t]+—[ \t]+(.+?)[ \t]+—[ \t]+(.+)$/;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Split `body` at the first activity marker.
+ *
+ * Returns `prose` (everything before the marker) and `activity` (the marker
+ * through EOF).  When there is no marker, `prose` is the entire body and
+ * `activity` is empty.
+ *
+ * A second marker appearing later in the body — hand-written or from a merge —
+ * stays inside `activity` verbatim (degraded, never lossy).
+ */
+export function splitActivity(body) {
+    const idx = body.indexOf(ACTIVITY_MARKER);
+    if (idx === -1)
+        return { prose: body, activity: '' };
+    // Slice at the marker so `activity` includes the marker line itself.
+    return {
+        prose: body.slice(0, idx).trimEnd(),
+        activity: body.slice(idx),
+    };
+}
+/**
+ * Append an activity entry to `body`, creating the marker and section heading
+ * when they are absent.
+ *
+ * The entry's `heading` is the event label (e.g. "flagged: blocked"), rendered
+ * as a level-3 heading with the timestamp and author before it.
+ */
+export function appendActivityEntry(body, entry) {
+    let formatted = `\n### ${entry.at} — ${entry.author} — ${entry.heading}\n`;
+    if (entry.text.trim())
+        formatted += `\n${entry.text.trim()}\n`;
+    const { prose, activity } = splitActivity(body);
+    if (activity) {
+        // Append to the existing section.
+        return prose + '\n' + activity.trimEnd() + formatted;
+    }
+    // Create the section.
+    const markerBlock = `\n\n${ACTIVITY_MARKER}\n\n${ACTIVITY_HEADING}\n`;
+    return prose.trimEnd() + markerBlock + formatted;
+}
+/**
+ * Merge an incoming body edit with the on-disk body so a stale body write
+ * cannot clobber the activity section.
+ *
+ * Rule: the incoming body's own activity section (if any) is discarded; the
+ * disk's activity section is re-attached to the incoming prose.  This is the
+ * anti-clobber primitive — whatever a stale edit carries in its own activity
+ * section is replaced by disk truth.
+ */
+export function mergeActivity(incomingBody, diskBody) {
+    const incoming = splitActivity(incomingBody);
+    const disk = splitActivity(diskBody);
+    if (!disk.activity)
+        return incomingBody;
+    return incoming.prose.trimEnd() + '\n' + disk.activity;
+}
+/**
+ * Parse an activity section body (the part after the marker and heading) into
+ * individual entries.  Used by tests and by anything that needs to inspect
+ * history.
+ */
+export function parseActivity(body) {
+    const { activity } = splitActivity(body);
+    if (!activity)
+        return [];
+    const entries = [];
+    let current = null;
+    const lines = [];
+    const flush = () => {
+        if (!current)
+            return;
+        current.text = lines.join('\n').trim();
+        entries.push(current);
+        lines.length = 0;
+    };
+    for (const line of activity.split(/\r?\n/)) {
+        const match = ENTRY_HEADING.exec(line);
+        if (match) {
+            flush();
+            current = {
+                at: match[1],
+                author: match[2].trim(),
+                heading: match[3].trim(),
+                text: '',
+            };
+            continue;
+        }
+        if (current)
+            lines.push(line);
+    }
+    flush();
+    return entries;
+}
+//# sourceMappingURL=activity.js.map

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

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

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

@@ -0,0 +1,34 @@
+/**
+ * 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 declare function sleepSync(ms: number): void;
+/**
+ * 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 declare function writeFileAtomic(file: string, data: string): void;
+/** The identity of a file as some reader saw it. */
+export interface DocStamp {
+    /** Modification time in nanoseconds, which is what a same-second rewrite needs. */
+    mtimeNs: bigint;
+    size: number;
+}
+/** Stamp `file` as it stands now, or null when it does not exist. */
+export declare function stampOf(file: string): DocStamp | 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 declare function sameStamp(a: DocStamp, b: DocStamp): boolean;