light-plan 0.0.0-stage → 0.1.0

package/dist/core/gitsync/sync.js

@@ -0,0 +1,275 @@
+import { BoardError, ConflictError } from '../errors.js';
+import { withBoardLock } from '../storage/lock.js';
+import { integrate, materialize } from './integrate.js';
+import { changedBetween, commitFiles, dirtyPaths, fileState, headOf, isOwnRepo, moveHead, remoteUrl, syncIndex, trackingRef, writeWorkingFile, } from './repo.js';
+import { firstLine, git, gitAsync } from './run.js';
+/**
+ * The network half: fetching, pulling, and the transaction every board write
+ * runs inside when the board is shared through git.
+ *
+ * ## The transaction
+ *
+ * `sharedWrite` wraps an operation that is about to change the board. It
+ * notes which files were already dirty, runs the operation, commits **exactly
+ * the files the operation changed**, and pushes. Then one of three things:
+ *
+ *   - the push lands — done;
+ *   - the push is rejected because somebody pushed first — fetch, `integrate`,
+ *     push again. If their change and ours touched different files, both stand.
+ *     If they touched the same file, ours is **undone** and a `ConflictError`
+ *     names the documents: the board on disk is theirs, and nothing of ours is
+ *     left half-applied. That is the claim guarantee — two people claiming one
+ *     story both write its `_issue.md`, and the second to push is told;
+ *   - the remote cannot be reached — ours is undone and the write refused,
+ *     because a claim nobody else can see is not a claim. `LPM_GIT_OFFLINE=1`
+ *     is the explicit way to work without the remote: commits stay local and
+ *     the next sync pushes them.
+ *
+ * Undoing is not `reset --hard`: the board folder is somebody's working tree,
+ * with views the web app keeps saving and hand edits in progress. Only the
+ * files this operation changed are put back, each to what it was before the
+ * operation ran — committed content, or the uncommitted edit it carried.
+ *
+ * Freshness is the front ends' job (they pull before they load); correctness
+ * is this file's. A front end that forgot to pull still cannot overwrite
+ * somebody else's work — it is refused at the push instead.
+ */
+/** Set to work without the remote: no fetch, no push, commits stay local. */
+export const GIT_OFFLINE_ENV = 'LPM_GIT_OFFLINE';
+export function isOffline() {
+    const raw = process.env[GIT_OFFLINE_ENV]?.trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes';
+}
+/** Why sync cannot run here, or null when it can. */
+export function syncProblem(dir, sync) {
+    if (!isOwnRepo(dir))
+        return 'the board folder is not a git repository of its own';
+    if (!remoteUrl(dir, sync.remote))
+        return `the board repository has no git remote named "${sync.remote}"`;
+    if (!headOf(dir))
+        return 'the board repository has no commits yet';
+    return null;
+}
+function requireTarget(paths, sync) {
+    const problem = syncProblem(paths.lpmDir, sync);
+    if (problem) {
+        throw new BoardError(`This board is shared through git, but ${problem}`, [
+            'Run `lpm git setup` to connect it, or `lpm git join` in a fresh project to clone it.',
+            'To stop sharing it instead, remove the `git_sync:` block from .lpm/config.yml.',
+        ]);
+    }
+    return { dir: paths.lpmDir, sync };
+}
+const lastFetch = new Map();
+export function lastFetchOf(dir) {
+    return lastFetch.get(dir) ?? null;
+}
+function fetchArgs(sync) {
+    return ['fetch', '--no-tags', sync.remote, `+refs/heads/${sync.branch}:${trackingRef(sync.remote, sync.branch)}`];
+}
+function settleFetch(dir, sync, ok, stderr) {
+    if (ok) {
+        lastFetch.set(dir, { at: Date.now(), error: null });
+        return { ok: true, missing: false };
+    }
+    if (/couldn't find remote ref/i.test(stderr)) {
+        // Not an error: nobody has pushed the branch yet. Forget any stale copy.
+        git(dir, ['update-ref', '-d', trackingRef(sync.remote, sync.branch)]);
+        lastFetch.set(dir, { at: Date.now(), error: null });
+        return { ok: true, missing: true };
+    }
+    const error = firstLine(stderr);
+    lastFetch.set(dir, { at: Date.now(), error });
+    return { ok: false, error };
+}
+export function fetchBoard(dir, sync) {
+    const result = git(dir, fetchArgs(sync), { network: true });
+    return settleFetch(dir, sync, result.ok, result.stderr);
+}
+/** The same fetch without blocking the event loop, for the server's background pull. */
+export async function fetchBoardAsync(dir, sync) {
+    const result = await gitAsync(dir, fetchArgs(sync), { network: true });
+    return settleFetch(dir, sync, result.ok, result.stderr);
+}
+/**
+ * Fetch, then integrate under the board lock. Never throws for the network or
+ * for a conflict — those are outcomes a reader carries on past — only for a
+ * repository git itself cannot read.
+ */
+export function pullBoard(paths, sync, options = {}) {
+    if (!sync)
+        return { kind: 'disabled' };
+    const dir = paths.lpmDir;
+    const problem = syncProblem(dir, sync);
+    if (problem)
+        return { kind: 'unavailable', error: problem };
+    if (!options.noFetch) {
+        if (isOffline())
+            return { kind: 'offline' };
+        const last = lastFetch.get(dir);
+        const fresh = options.maxAgeMs !== undefined && last && last.error === null && Date.now() - last.at < options.maxAgeMs;
+        if (fresh)
+            return { kind: 'fresh' };
+        const fetched = fetchBoard(dir, sync);
+        if (!fetched.ok)
+            return { kind: 'unreachable', error: fetched.error };
+    }
+    return withBoardLock(paths, 'bring in the latest board from git', () => integrate(dir, sync, options));
+}
+function pushHead(dir, sync) {
+    const result = git(dir, ['push', '--porcelain', sync.remote, `HEAD:refs/heads/${sync.branch}`], {
+        network: true,
+    });
+    if (result.ok) {
+        // Keep the tracking ref honest even for a remote with no fetch refspec.
+        git(dir, ['update-ref', trackingRef(sync.remote, sync.branch), 'HEAD']);
+        lastFetch.set(dir, { at: Date.now(), error: null });
+        return { kind: 'ok' };
+    }
+    const text = `${result.stdout}\n${result.stderr}`;
+    if (/\[rejected\]|non-fast-forward|fetch first|\[remote rejected\].*(?:lock|cannot lock)/i.test(text)) {
+        return { kind: 'rejected' };
+    }
+    return { kind: 'failed', error: firstLine(result.stderr || result.stdout) };
+}
+/** Push whatever is committed, integrating and retrying when somebody got there first. */
+export function publish(paths, sync, options = {}) {
+    const dir = paths.lpmDir;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+        const pushed = pushHead(dir, sync);
+        if (pushed.kind === 'ok')
+            return { kind: 'pushed' };
+        if (pushed.kind === 'failed') {
+            throw new BoardError(`Could not push the board to ${sync.remote}`, [pushed.error]);
+        }
+        const fetched = fetchBoard(dir, sync);
+        if (!fetched.ok)
+            throw new BoardError(`Could not fetch the board from ${sync.remote}`, [fetched.error]);
+        const result = integrate(dir, sync, options);
+        if (result.kind === 'conflict')
+            return result;
+    }
+    throw new BoardError(`${sync.remote} kept moving while the board was being pushed`, [
+        `Tried ${MAX_ATTEMPTS} times. Somebody is writing to the board continuously; try again in a moment.`,
+    ]);
+}
+const MAX_ATTEMPTS = 3;
+// ---------------------------------------------------------------------------
+// The write transaction
+/** How deep this process is inside a shared write, per board. */
+const depth = new Map();
+function snapshot(dir) {
+    const out = new Map();
+    for (const file of dirtyPaths(dir))
+        out.set(file, fileState(dir, file));
+    return out;
+}
+/** Files whose content differs between two snapshots. */
+function changedFiles(dir, before, after) {
+    const out = [];
+    for (const file of new Set([...before.keys(), ...after.keys()])) {
+        const a = before.get(file)?.hash;
+        // A file dirty before and clean after was rewritten to what HEAD holds —
+        // still a change the operation made.
+        const b = after.has(file) ? after.get(file).hash : before.has(file) ? fileState(dir, file).hash : undefined;
+        if (a !== b)
+            out.push(file);
+    }
+    return out.sort();
+}
+/**
+ * Put every file the operation changed back to what it was before it ran, and
+ * move the branch back to where it was. Files the operation did not touch —
+ * somebody's uncommitted view, a hand edit — are left exactly alone.
+ */
+function undo(dir, base, files, before) {
+    // A retry may already have laid our commit over somebody else's, so the
+    // branch can be ahead of `base` by more than our own files.
+    const head = headOf(dir);
+    const moved = head && head !== base ? changedBetween(dir, base, head) : [];
+    const all = [...new Set([...moved, ...files])];
+    materialize(dir, base, all);
+    moveHead(dir, base, 'lpm: undo a board change that could not be shared');
+    syncIndex(dir, all);
+    for (const file of files) {
+        const prior = before.get(file);
+        if (prior && (prior.bytes !== null || prior.hash === null))
+            writeWorkingFile(dir, file, prior.bytes);
+    }
+}
+/** Document ids (or plain paths) for a list of board files, for a message. */
+export function describeFiles(files) {
+    const out = new Set();
+    for (const file of files) {
+        const parts = file.split('/');
+        const name = parts.at(-1) ?? file;
+        const folder = parts.at(-2);
+        const id = folder?.match(/^[A-Z][A-Z0-9]*-\d+/)?.[0];
+        out.add(id && name.startsWith('_') ? id : file);
+    }
+    return [...out];
+}
+/**
+ * Run `run` as a write to a board shared through git: commit what it changed,
+ * push it, and undo it when it cannot be shared. Re-entrant — an operation
+ * built from operations commits once, at the outermost call.
+ *
+ * With no `sync`, `run` is simply called: a board that is not shared behaves
+ * exactly as it always did.
+ */
+export function sharedWrite(paths, sync, what, run, options = {}) {
+    const dir = paths.lpmDir;
+    const level = depth.get(dir) ?? 0;
+    if (!sync || level > 0)
+        return run();
+    requireTarget(paths, sync);
+    depth.set(dir, level + 1);
+    try {
+        const before = snapshot(dir);
+        const result = run();
+        const files = changedFiles(dir, before, snapshot(dir));
+        if (!files.length)
+            return result;
+        const base = headOf(dir);
+        const commit = commitFiles(dir, files, `lpm: ${what}`);
+        if (!commit || isOffline())
+            return result;
+        let outcome;
+        try {
+            outcome = publish(paths, sync, options);
+        }
+        catch (error) {
+            undo(dir, base, files, before);
+            const details = error instanceof BoardError ? [error.message, ...error.details] : [String(error)];
+            throw new BoardError(`Nothing was changed: the board could not be shared through ${sync.remote}`, [
+                ...details,
+                `Check the connection with \`lpm git status\`. To work offline on purpose, set ${GIT_OFFLINE_ENV}=1 — changes are then committed locally and pushed by the next \`lpm git sync\`.`,
+            ]);
+        }
+        if (outcome.kind === 'conflict') {
+            undo(dir, base, files, before);
+            // Show the reader what won, now that ours is out of the way. Best effort:
+            // a board that cannot be brought level is still a board that refused.
+            try {
+                integrate(dir, sync, options);
+            }
+            catch {
+                // Reported by the next pull.
+            }
+            const documents = describeFiles(outcome.paths);
+            throw new ConflictError(outcome.reason === 'uncommitted'
+                ? `Nothing was changed: incoming board changes collide with uncommitted edits to ${documents.join(', ')}`
+                : `Nothing was changed: ${documents.join(', ')} changed upstream while you were working`, outcome.reason === 'uncommitted'
+                ? ['Commit or discard those edits (`lpm git sync` commits them), then repeat the change.']
+                : [
+                    'Somebody else wrote the same document and pushed first. The board now shows their version.',
+                    'Read it again and repeat the change if it still makes sense.',
+                ]);
+        }
+        return result;
+    }
+    finally {
+        depth.set(dir, level);
+    }
+}
+//# sourceMappingURL=sync.js.map

package/dist/core/gitsync/sync.js.map

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

package/dist/core/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * light-plan core.
+ *
+ * The CLI is a thin shell over this module; a future GUI can import the same
+ * engine. Everything here is synchronous filesystem work over a `.lpm` folder.
+ *
+ * Layers, each depending only on the ones above it:
+ *
+ *   model/       what an issue, period, type and problem are; pure logic
+ *   config/      parsing .lpm/config.yml and answering questions about it
+ *   storage/     how a board is encoded on disk: paths, frontmatter, ids, git
+ *   board/       loading both collections into memory, querying and scoping them
+ *   gitsync/     sharing the board through its own git repository: pull, the
+ *                write transaction, status, the hosts setup knows about
+ *   profile/     the file one developer is handed: who they are, what they see
+ *   instructions/ one issue plus its ancestry, rendered as a working brief
+ *   operations/  the commands that change a board: init, create, move, link
+ *   validation/  check (read-only) and fix (repairs what check marks fixable)
+ *
+ * `errors.ts` sits outside the stack: every layer may throw a BoardError.
+ */
+export * from './board/index.js';
+export * from './config/index.js';
+export * from './errors.js';
+export * from './gitsync/index.js';
+export * from './instructions/index.js';
+export * from './model/index.js';
+export * from './operations/index.js';
+export * from './profile/index.js';
+export * from './storage/index.js';
+export * from './validation/index.js';

package/dist/core/index.js

@@ -0,0 +1,32 @@
+/**
+ * light-plan core.
+ *
+ * The CLI is a thin shell over this module; a future GUI can import the same
+ * engine. Everything here is synchronous filesystem work over a `.lpm` folder.
+ *
+ * Layers, each depending only on the ones above it:
+ *
+ *   model/       what an issue, period, type and problem are; pure logic
+ *   config/      parsing .lpm/config.yml and answering questions about it
+ *   storage/     how a board is encoded on disk: paths, frontmatter, ids, git
+ *   board/       loading both collections into memory, querying and scoping them
+ *   gitsync/     sharing the board through its own git repository: pull, the
+ *                write transaction, status, the hosts setup knows about
+ *   profile/     the file one developer is handed: who they are, what they see
+ *   instructions/ one issue plus its ancestry, rendered as a working brief
+ *   operations/  the commands that change a board: init, create, move, link
+ *   validation/  check (read-only) and fix (repairs what check marks fixable)
+ *
+ * `errors.ts` sits outside the stack: every layer may throw a BoardError.
+ */
+export * from './board/index.js';
+export * from './config/index.js';
+export * from './errors.js';
+export * from './gitsync/index.js';
+export * from './instructions/index.js';
+export * from './model/index.js';
+export * from './operations/index.js';
+export * from './profile/index.js';
+export * from './storage/index.js';
+export * from './validation/index.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC"}

package/dist/core/instructions/analyze.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A static safety check for context templates.
+ *
+ * Eta compiles a template into a JavaScript function and runs it, so a
+ * `.lpm/templates/context/*.md` file is **executable code**, not data — and a
+ * `.lpm` folder arrives over `git pull` from whoever wrote it. Rendering
+ * somebody else's board can therefore run somebody else's JavaScript, with the
+ * full privileges of the person who typed `lpm instructions`.
+ *
+ * There is no published sanitizer for Eta or EJS templates — the ecosystem's
+ * position is that a template is trusted code. This module is the check that
+ * position implies but does not provide. It cannot make an untrusted template
+ * safe; nothing can, short of a real sandbox. What it does is refuse the
+ * constructs that have no legitimate place in a *brief* and every place in an
+ * exploit, so that the residual risk is a template doing something strange
+ * rather than a template reading your SSH keys.
+ *
+ * Two decisions make this worth having rather than security theatre:
+ *
+ * 1. **It tokenizes with Eta's own parser, never a regex.** Eta's lexer skips
+ *    `%>` inside strings and comments, so `<%= "a %> b" %>` is one tag. A
+ *    hand-rolled scanner would disagree with the engine about where code
+ *    begins, and every such disagreement is a hole.
+ * 2. **It parses the code with acorn** rather than matching text, so
+ *    `x [ /*c* / "constructor" ]` and `x["cons" + "tructor"]` are seen for what
+ *    they are. Anything that reaches a property by a computed key is refused
+ *    outright, because that is the evasion route for every name-based rule
+ *    below it.
+ *
+ * What it still cannot stop: a template that only ever prints board values but
+ * prints ones it should not, and any escape route nobody has thought of. Treat
+ * `danger`-free as "no known escape", not as "safe to run untrusted".
+ */
+export type FindingSeverity = 'danger' | 'caution';
+export interface TemplateFinding {
+    /** Machine-readable rule name, e.g. `host-global`. */
+    rule: string;
+    severity: FindingSeverity;
+    message: string;
+    /** 1-based, in the template file. */
+    line: number;
+    column: number;
+    /** The offending source text, clipped. */
+    snippet: string;
+}
+export interface TemplateAnalysis {
+    findings: TemplateFinding[];
+    /** True when the template holds no executable code at all — text and values only. */
+    inert: boolean;
+    /** How many `<% %>` / `<%= %>` tags carry code. */
+    codeTags: number;
+}
+/**
+ * Read a template without running it, and report everything in it that could do
+ * more than lay an issue out.
+ *
+ * Throws only when the template will not parse at all — which is a broken
+ * template rather than a dangerous one, and worth the same error either way.
+ */
+export declare function analyzeTemplate(source: string): TemplateAnalysis;
+export declare function describeFinding(finding: TemplateFinding): string;
+/**
+ * Analyze, and refuse a template that could escape.
+ *
+ * `allowUnsafe` exists because it is the caller's machine and their board, and
+ * a flat refusal with no way past it just teaches people to stop using the
+ * feature. It is never offered to an agent: the MCP server renders whatever the
+ * board holds, so it is the one caller that must not be able to say yes.
+ */
+export declare function assertTemplateSafe(source: string, name: string, allowUnsafe?: boolean): TemplateFinding[];