light-plan 0.0.0-stage → 0.1.0

package/dist/shared/plans/upstream.js

@@ -0,0 +1,73 @@
+import { upstreamWork } from '../blocking.js';
+import { fail, update } from './breakdown.js';
+import { blockingLookupOf } from './reading.js';
+/**
+ * Work out the upstream schedule, reporting what was skipped as well as what
+ * was planned.
+ *
+ * Callers that only want the changes use `planScheduleUpstream`; the CLI and
+ * the MCP tool use this one, because "nothing happened" is an answer that needs
+ * to say why — three issues already had owners is a different board from no
+ * upstream work at all.
+ */
+export function scheduleUpstream(view, id, options = {}) {
+    const empty = { decisions: [], period: null, assignee: null };
+    const target = view.nodes[id];
+    if (!target)
+        return { ...empty, plan: fail(`No issue with id "${id}"`) };
+    if (target.kind !== 'issue') {
+        return {
+            ...empty,
+            plan: fail(`${id} is a ${target.kind}; only issues have upstream work`),
+        };
+    }
+    const period = options.period === undefined ? target.period : options.period;
+    const assignee = options.assignee === undefined ? target.assignee : options.assignee;
+    if (period === null && assignee === null) {
+        return {
+            ...empty,
+            plan: fail(`${id} is not scheduled and not assigned, so there is nothing to copy onto its upstream work`, [
+                'Schedule or assign it first, or pass a period and an assignee explicitly.',
+            ]),
+        };
+    }
+    const lookup = blockingLookupOf(view);
+    const decisions = [];
+    const changes = [];
+    for (const entry of upstreamWork(id, lookup)) {
+        const issue = view.nodes[entry.id];
+        if (!issue || issue.kind !== 'issue')
+            continue;
+        const skipped = skipReason(issue, lookup.isWorkUnit(entry.id), period, assignee);
+        decisions.push({ ...entry, skipped });
+        if (skipped)
+            continue;
+        // Both fields travel in one patch: the two halves of "this is now yours,
+        // this sprint" must not be able to land separately.
+        const patch = {};
+        if (issue.period !== period)
+            patch.period = period;
+        if (issue.assignee !== assignee)
+            patch.assignee = assignee;
+        changes.push(update(view, entry.id, patch));
+    }
+    return { plan: { ok: true, changes, created: [] }, decisions, period, assignee };
+}
+function skipReason(issue, isUnit, period, assignee) {
+    if (issue.assignee !== null)
+        return 'assigned';
+    if (!isUnit)
+        return 'container';
+    if (issue.period === period && issue.assignee === assignee)
+        return 'unchanged';
+    return null;
+}
+/**
+ * The changes alone, for a caller that just wants to queue them.
+ *
+ * @see scheduleUpstream for the decisions behind them.
+ */
+export function planScheduleUpstream(view, id, options = {}) {
+    return scheduleUpstream(view, id, options).plan;
+}
+//# sourceMappingURL=upstream.js.map

package/dist/shared/plans/upstream.js.map

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

package/dist/shared/remote-api.d.ts

@@ -0,0 +1,413 @@
+/**
+ * The wire shapes for the remote routes (`/api/remotes/*`), served by
+ * `src/server/routes/remotes.ts` (LP-344).
+ *
+ * Import-free, like the rest of this folder: the server maps the remote
+ * layer's results onto these shapes, and the web app consumes them, neither
+ * importing the other.  Credentials never appear here — the server resolves
+ * them itself and nothing on either side of the wire carries one.
+ */
+/** The direction a sync run takes, as the server accepts and reports it. */
+export type RemoteSyncDirection = 'push' | 'pull' | 'both';
+/** One configured remote, as `GET /api/remotes` lists it. */
+export interface RemoteSummaryDto {
+    name: string;
+    provider: string;
+    direction: RemoteSyncDirection;
+    /** The connection value that names where the issues live. */
+    target: string;
+    /** Most recent sync across links, or null when never synced. */
+    lastSync: string | null;
+}
+/** A push-side preflight problem, trimmed to what the panel shows. */
+export interface RemotePreflightProblemDto {
+    level: 'error' | 'warn';
+    message: string;
+}
+/** One field's detail in a preview document: the two sides and what happens. */
+export interface RemotePreviewFieldDto {
+    /** Display name (`title`, `status`, `attributes.story_points`, `depends_on`…). */
+    field: string;
+    /** The local (board) value; null means absent on the board. */
+    local: unknown;
+    /** The remote value — the base snapshot, or null when the remote has none. */
+    remote: unknown;
+    /** What the operation does to this field: `created`, `updated`, `closed`, … */
+    outcome: string;
+}
+/** One document's detail in a preview section. */
+export interface RemotePreviewDocumentDto {
+    /** The local id the operation names. */
+    localId: string;
+    /** The document's title, when known. */
+    title?: string;
+    /** The remote id of the twin, when the operation names one. */
+    remoteId?: string;
+    kind: string;
+    fields: RemotePreviewFieldDto[];
+}
+/** One operation kind, grouped with its count and documents. */
+export interface RemotePreviewSectionDto {
+    kind: string;
+    /** Human label for the kind (`create`, `transition`, `unlink locally`, …). */
+    label: string;
+    count: number;
+    documents: RemotePreviewDocumentDto[];
+}
+/** One rendered plan step of a preview: the direction, its plain-text diff, and
+ * the same plan grouped by operation kind, so the web preview can render the
+ * structure `lpm remote push --dry-run` produces rather than re-deriving it. */
+export interface RemotePreviewRenderDto {
+    direction: 'pull' | 'push';
+    /** Total operations in this step. */
+    total: number;
+    /** One section per operation kind, in the renderer's fixed order. */
+    sections: RemotePreviewSectionDto[];
+    /** The plain-text form the CLI prints. */
+    text: string;
+}
+/** The preview of a sync: the rendered plan, nothing written to either side. */
+export interface RemotePreviewDto {
+    remoteName: string;
+    direction: RemoteSyncDirection;
+    preflight: RemotePreflightProblemDto[];
+    /** True when the push was refused because the preflight found error problems. */
+    preflightBlocked: boolean;
+    /** Why the pull was skipped — the remote could not be reached. */
+    unreachable?: string;
+    /** The rendered plans, pull first (when pulled) then push. */
+    renders: RemotePreviewRenderDto[];
+}
+/** The body of `POST /api/remotes/:name/sync` and `/preview`. */
+export interface RemoteSyncRequestDto {
+    direction?: RemoteSyncDirection;
+    /** Narrow the run to one subtree (`lpm remote push <id>`). */
+    scope?: string;
+    /**
+     * Act on exactly these documents and no others — the push side's
+     * *selection*, `lpm remote push LP-12` with no `--children`.
+     *
+     * It is not `scope` with one entry, and the difference is the one this
+     * layer keeps having to restate: `scope` names a subtree *root* and expands
+     * to everything under it, which is right for "push this feature and its
+     * stories" and wrong for "push this one document". Neither narrows what the
+     * remote *owns*, so the gone pass is untouched by either and a selective run
+     * can never decouple the rest of the board.
+     */
+    only?: string[];
+    /**
+     * Pull exactly these twins, by **remote** id (`lpm remote pull PAY-31`).
+     *
+     * A targeted pull is `partial`: it fetches what it was asked for and says
+     * nothing whatever about what it did not look for, so no twin's absence is
+     * read as a deletion. That is also why it is the right shape for "pull this
+     * document" — narrowing a *scope* to one document would leave the bulk guard
+     * comparing one missing twin against one expected twin, which is always
+     * 100%.
+     */
+    pullIds?: string[];
+    /** At most this many remote write ops on the push side (`--limit`). */
+    limit?: number;
+    /**
+     * Ask the remote only for what changed since the last pull (`--changed`).
+     * The default lists everything the remote holds, which is what refreshes
+     * every mirrored document and the only listing a deletion is detected from.
+     */
+    changed?: boolean;
+    /** Re-probe capabilities instead of reading the cache (`--refresh`). */
+    refresh?: boolean;
+    /** Confirm the first write or an oversized plan (`--yes`, LP-350). */
+    yes?: boolean;
+}
+/** One push op that was refused or rejected, from the applied summary. */
+export interface RemotePushOpDto {
+    kind: string;
+    localId: string;
+    error: string;
+}
+/** The applied push summary, from the `done` event. */
+export interface RemotePushSummaryDto {
+    created: number;
+    updated: number;
+    skipped: number;
+    conflicted: number;
+    failed: number;
+    conflictedOps: RemotePushOpDto[];
+    failedOps: RemotePushOpDto[];
+    /** Present when the run stopped early — aborted, budget-exhausted, or `--limit`. */
+    stopped?: {
+        reason: string;
+        atOp: number;
+        detail: string;
+        deferred?: number;
+    };
+}
+/** A push the consent gate refused (LP-350, LP-351) — nothing was written. */
+export interface RemoteConsentRefusalDto {
+    reason: 'first_write' | 'threshold' | 'delete';
+    target: string;
+    creates: number;
+    closes: number;
+    deletes: number;
+    threshold: number;
+}
+/** The applied pull summary, from the `done` event. */
+export interface RemotePullSummaryDto {
+    applied: number;
+    linked: number;
+    unlinked: number;
+    decoupled: number;
+    appendedComments: number;
+    /** One line per failed change, grouped like the CLI's push-failure summary. */
+    failures: string[];
+}
+/** A pull-side existence decision left for `resolve` (LP-365). */
+export interface RemotePullConflictDto {
+    localId: string;
+    remoteId: string;
+    reason: string;
+    /** The linked child a delete would have orphaned, when that was the refusal. */
+    childId?: string;
+}
+/** A field-level conflict on a linked twin, left for `resolve` (LP-257). */
+export interface RemotePullFieldConflictDto {
+    localId: string;
+    remoteId: string;
+    field: string;
+    local: unknown;
+    remote: unknown;
+}
+/** The conflicts a pull left for `resolve`, never applied silently. */
+export interface RemotePullConflictsDto {
+    conflicts: RemotePullConflictDto[];
+    fieldConflicts: RemotePullFieldConflictDto[];
+}
+/** The final result of an applied sync, streamed as the `done` event. */
+export interface RemoteSyncResultDto {
+    remoteName: string;
+    direction: RemoteSyncDirection;
+    preflight: RemotePreflightProblemDto[];
+    preflightBlocked: boolean;
+    unreachable?: string;
+    /** Present after a pull ran. */
+    pull?: RemotePullSummaryDto;
+    /** Present after a push ran. */
+    push?: RemotePushSummaryDto;
+    pullConflicts: RemotePullConflictsDto;
+    /** Present when the push was refused by the consent gate (LP-350). */
+    consentRefused?: RemoteConsentRefusalDto;
+}
+/** A streamed sync event. Every event carries a `type`. */
+export type RemoteSyncEventDto = {
+    type: 'progress';
+    index: number;
+    total: number;
+    kind: string;
+    localId: string;
+} | {
+    type: 'done';
+    result: RemoteSyncResultDto;
+} | {
+    type: 'error';
+    error: string;
+    details?: string[];
+};
+/** Which side of a conflict wins. */
+export type RemoteResolveOwner = 'local' | 'remote';
+/** The body of `POST /api/remotes/:name/resolve`. */
+export interface RemoteResolveRequestDto {
+    /** The document to settle. */
+    id: string;
+    /** Whole-document winner. */
+    default?: RemoteResolveOwner;
+    /** Per-field winners, most specific first. */
+    fields?: Record<string, RemoteResolveOwner>;
+}
+/** The recorded settlement, as the route returns it. */
+export interface RemoteResolveResultDto {
+    remoteName: string;
+    localId: string;
+    default?: RemoteResolveOwner;
+    fields: Record<string, RemoteResolveOwner>;
+}
+/** One conflicted field, with both sides and the pending choice, for the panel. */
+export interface RemoteConflictFieldDto {
+    /** Display name (`title`, `status`, `attributes.story_points`, …). */
+    field: string;
+    /** The local (board) value; null means absent on the board. */
+    local: unknown;
+    /** The remote value, translated back to board vocabulary. */
+    remote: unknown;
+    /** The pending per-field winner, when one was already recorded. */
+    chosen?: RemoteResolveOwner;
+}
+/** The conflict detail for one document, served to the side panel (LP-346). */
+export interface RemoteConflictDto {
+    remoteName: string;
+    localId: string;
+    remoteId: string;
+    /** Human-readable key, e.g. `acme/payments#418`. */
+    remoteKey: string;
+    /** Full URL to the remote issue; empty when the link recorded none. */
+    remoteUrl: string;
+    /** The fields in conflict, each with both values and the pending choice. */
+    fields: RemoteConflictFieldDto[];
+    /** A pending whole-document winner, when one was recorded. */
+    default?: RemoteResolveOwner;
+}
+/** One non-secret connection key a provider asks for. */
+export interface RemoteConnectionFieldDto {
+    name: string;
+    type: 'string' | 'boolean';
+    /** False for a key the provider defaults for itself. */
+    required: boolean;
+    /** A worked example, shown beside the field. */
+    example?: string;
+}
+/** One credential key — stored beside the board, never in config.yml. */
+export interface RemoteCredentialFieldDto {
+    key: string;
+    /** The platform's conventional env var, which satisfies the key as well. */
+    env?: string;
+    /** True when the value may be shown while typed (an account email); otherwise masked. */
+    visible: boolean;
+}
+/** Everything a connect form needs to know about one provider. */
+export interface RemoteProviderDto {
+    name: string;
+    connection: RemoteConnectionFieldDto[];
+    credentials: RemoteCredentialFieldDto[];
+    /** The page where this credential is created. */
+    credentialUrl?: string;
+    /** What to create, and with what access. */
+    credentialHint?: string;
+    /** Keys only part of a mapping needs, and what breaks without them. */
+    conditional: Array<{
+        key: string;
+        needs: string;
+        why: string;
+    }>;
+}
+/** Where one credential key's value comes from. Never the value itself. */
+export interface RemoteCredentialStateDto {
+    key: string;
+    env?: string;
+    /** e.g. `.lpm/credentials.json` or `$JIRA_API_TOKEN`; absent when nothing holds a value. */
+    source?: string;
+    /** The `${VAR}` name config.yml points at, when it points at one. */
+    reference?: string;
+}
+/** `POST /api/remotes` — declare a remote and store its credential. */
+export interface RemoteConnectRequestDto {
+    name: string;
+    provider: string;
+    /** Non-secret connection values; a blank is not given. */
+    connection?: Record<string, string | boolean>;
+    scope?: string;
+    /** Credential values; a blank is skipped. */
+    credentials?: Record<string, string>;
+    /** Replace a remote of the same name — its mapping is drafted again. */
+    force?: boolean;
+}
+export interface RemoteConnectResultDto {
+    name: string;
+    provider: string;
+    target: string;
+    replaced: boolean;
+    /** Decisions the drafted mapping could not make on its own. */
+    markers: Array<{
+        path: string;
+        question: string;
+    }>;
+    /** Credential keys stored by this call. */
+    stored: string[];
+    credentials: RemoteCredentialStateDto[];
+}
+/** `GET /api/remotes/:name/connection` — a declared remote as an edit form shows it. Holds no secret. */
+export interface RemoteConnectionDto {
+    name: string;
+    provider: string;
+    scope: string | null;
+    /** Non-secret connection values only. */
+    connection: Record<string, string | boolean>;
+    credentials: RemoteCredentialStateDto[];
+    /** How many documents this remote already mirrors — a remote with twins is not re-pointed. */
+    linked: number;
+}
+/** `PUT /api/remotes/:name/connection`. A blank removes an optional key; `false` removes a switch. */
+export interface RemoteConnectionUpdateDto {
+    connection: Record<string, string | boolean>;
+}
+/** `PUT /api/remotes/:name/credentials`. A blank keeps what is there. */
+export interface RemoteCredentialsRequestDto {
+    credentials: Record<string, string>;
+}
+export interface RemoteCredentialsResultDto {
+    stored: string[];
+    credentials: RemoteCredentialStateDto[];
+}
+/** A value the remote offered for a connection key. */
+export interface RemoteCandidateDto {
+    key: string;
+    value: string;
+    label: string;
+}
+/** A connection key the remote answered in several ways, or not at all. */
+export interface RemoteConnectionQuestionDto {
+    key: string;
+    why: string;
+    candidates: RemoteCandidateDto[];
+}
+export interface RemoteReconcileEntryDto {
+    boardKey: string;
+    claimed: string;
+    resolved?: string;
+    verdict: 'ok' | 'renamed' | 'unresolved';
+}
+export interface RemoteReconcileBlockDto {
+    entries: RemoteReconcileEntryDto[];
+    /** The remote's own names — the options for an unresolved entry. */
+    candidates: string[];
+}
+/** `POST /api/remotes/:name/inspect` — what asking the remote about itself found and wrote. */
+export interface RemoteInspectDto {
+    remoteName: string;
+    reachability?: {
+        reachable: boolean;
+        evidence: string;
+    };
+    /** The remote could not be reached; nothing after reachability was asked. */
+    stopped: boolean;
+    /** Keys the remote answered with exactly one value — written. */
+    found: RemoteCandidateDto[];
+    /** Keys the remote offered several values for — a person chooses. */
+    choices: RemoteConnectionQuestionDto[];
+    /** Keys nobody could answer. */
+    needed: RemoteConnectionQuestionDto[];
+    vocabulary?: {
+        types?: RemoteReconcileBlockDto;
+        statuses?: RemoteReconcileBlockDto;
+    };
+    /** True when the provider has no vocabulary to ask about (and the remote was reached). */
+    noVocabulary: boolean;
+    prerequisites?: {
+        labels: string[];
+        projectFields: number;
+        sprints: string[];
+        canListLabels: boolean;
+    };
+    /** config.yml lines this run changed. */
+    written: string[];
+    /** Nothing is left for a person to answer. */
+    ready: boolean;
+}
+/** `POST /api/remotes/:name/answers` — what a person chose. */
+export interface RemoteInspectAnswersDto {
+    /** Discoverable connection keys only. */
+    connection?: Record<string, string>;
+    types?: Record<string, string>;
+    statuses?: Record<string, string>;
+}
+export interface RemoteInspectAnswersResultDto {
+    changed: string[];
+}

package/dist/shared/remote-api.js

@@ -0,0 +1,11 @@
+/**
+ * The wire shapes for the remote routes (`/api/remotes/*`), served by
+ * `src/server/routes/remotes.ts` (LP-344).
+ *
+ * Import-free, like the rest of this folder: the server maps the remote
+ * layer's results onto these shapes, and the web app consumes them, neither
+ * importing the other.  Credentials never appear here — the server resolves
+ * them itself and nothing on either side of the wire carries one.
+ */
+export {};
+//# sourceMappingURL=remote-api.js.map

package/dist/shared/remote-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-api.js","sourceRoot":"","sources":["../../src/shared/remote-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/shared/remote-coverage.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The coverage report: what a remote mirrors, and what is missing *around* it.
+ *
+ * `remote-status.ts` answers "has anything drifted?" for the documents a
+ * remote already holds. This answers the question that comes before it — **is
+ * what the tracker holds a coherent piece of the plan?** Pushing one feature
+ * is an ordinary and supported thing to do (`docs/remote-sync.md` §7f: a plan
+ * is filed a piece at a time, and the shape heals), but nothing until now said
+ * what the piece was missing: its stories, the epic above it, the sprint it is
+ * scheduled into, the work it waits on.
+ *
+ * The unit is a **gap** — a document the remote does not hold that is related
+ * to one it does — and a gap always names *why* it matters, because the reason
+ * is what a person is deciding about. A missing container means the work is
+ * filed at the tracker's root; a missing sprint means the issues in it were
+ * filed unscheduled; a missing blocker means a dependency edge was dropped for
+ * want of a second end. Those consequences are not decoration: they are the
+ * difference between "63 documents are not pushed" — which is the status
+ * report's `unlinked` bucket and tells nobody anything — and "these four are
+ * why the tracker's copy of your plan is wrong".
+ *
+ * Pure data, no imports beyond this folder's own types: the report is computed
+ * by `src/remote/coverage.ts` (offline — the board and the link store are all
+ * it reads, so no tracker is called and nothing is written), served as JSON,
+ * and rendered by the web app. The relation table below travels with it so
+ * every reader says the same sentence about the same gap.
+ */
+/**
+ * How an unmirrored document relates to the mirror — the reason it is a gap.
+ *
+ * Read from the *gap's* point of view: `parent` means this document is the
+ * container of something mirrored, `child` that it sits inside something
+ * mirrored, `blocker` that mirrored work waits on it.
+ */
+export type CoverageRelation = 'parent' | 'child' | 'period' | 'blocker' | 'blocked';
+/** Anchors are sampled rather than listed in full: one sprint can hold hundreds. */
+export declare const COVERAGE_ANCHOR_LIMIT = 5;
+/** One reason a document is a gap, with the mirrored documents behind it. */
+export interface CoverageReason {
+    relation: CoverageRelation;
+    /** Mirrored documents this gap relates to — at most `COVERAGE_ANCHOR_LIMIT`. */
+    anchors: string[];
+    /** How many there are in all; `anchors` may be a sample of them. */
+    count: number;
+}
+/** One document the remote does not hold, and why that shows. */
+export interface CoverageGap {
+    id: string;
+    kind: 'issue' | 'period';
+    type: string;
+    title: string;
+    /** Every reason this document is a gap, in the table's order. */
+    reasons: CoverageReason[];
+}
+/** The gap ids for one relation, so a reader can offer "select all of these". */
+export interface CoverageGroup {
+    relation: CoverageRelation;
+    ids: string[];
+}
+/** What a remote mirrors, and what is missing around it. */
+export interface RemoteCoverageReport {
+    remote: {
+        name: string;
+        provider: string;
+        /** The connection value that names where the issues live. */
+        target: string;
+    };
+    /** Documents this remote holds a twin of. */
+    mirrored: number;
+    /** Documents in this remote's scope it could hold — the denominator. */
+    total: number;
+    /** Unmirrored documents related to mirrored ones, worst first. */
+    gaps: CoverageGap[];
+    /** The same gaps by relation, in the table's order; empty groups are omitted. */
+    groups: CoverageGroup[];
+    /** Gaps deliberately decoupled — reported, never offered for pushing. */
+    decoupled: string[];
+    /** Gaps outside this remote's scope — it cannot file them, and says so. */
+    outOfScope: string[];
+    /**
+     * True when this remote files periods as documents of their own. When it is
+     * false a period has no twin to be missing: the schedule rides the managed
+     * block on the issue, so no `period` gap is ever reported.
+     */
+    filesPeriods: boolean;
+}
+/** The heading and the consequence one relation is described by. */
+export interface CoverageRelationInfo {
+    relation: CoverageRelation;
+    /** What these documents are, as a group heading. */
+    label: string;
+    /** What the tracker's copy of the plan is missing while they are unfiled. */
+    consequence: string;
+    /** The same thing about one document, for a per-document panel. */
+    short: string;
+}
+/**
+ * The relations, in the order a reader should be shown them: the ones that
+ * make the filed plan *wrong* first, the ones that make it *incomplete* after.
+ *
+ * A missing container is first because everything mirrored beneath it is filed
+ * at the tracker's root, which is the failure people report as "the stories
+ * are not under the features". `blocked` is last because it is the widest — on
+ * a board whose foundations are mirrored, a great deal of unstarted work waits
+ * on them, and that is ordinary rather than wrong.
+ */
+export declare const COVERAGE_RELATIONS: readonly CoverageRelationInfo[];
+/** The table entry for one relation. */
+export declare function coverageRelationInfo(relation: CoverageRelation): CoverageRelationInfo;
+/**
+ * The gaps around one document — what the panel shows for the selected node.
+ *
+ * Read from the report rather than computed again, so the panel and the drawer
+ * cannot disagree about what is missing. A document with no gaps around it
+ * answers `[]`, which is also the answer for one the report knows nothing
+ * about.
+ */
+export declare function gapsAround(report: RemoteCoverageReport, id: string): CoverageGap[];
+/** One line for a header or a notice: `12 of 74 mirrored · 9 missing`. */
+export declare function summarizeCoverage(report: RemoteCoverageReport): string;