light-plan 0.0.0-stage → 0.1.0

package/dist/remote/links.d.ts

@@ -0,0 +1,411 @@
+/**
+ * The correspondence store — which document is which remote issue, and what it
+ * looked like last time both sides agreed.
+ *
+ * Lives under `.lpm/remotes/<name>/links.json`, committed like everything else.
+ * Its sibling `mapping.json` holds the mapping fingerprint every sync compares
+ * against (LP-370, `fingerprint.ts`).
+ *
+ * Why not a frontmatter field?  `remote_id:` would be a breaking reserved field
+ * (it would shadow a user attribute of that name), it does not extend to two
+ * remotes, and it has nowhere to keep the base snapshot.  Same reasoning that
+ * keeps derived inverses out of the documents.
+ *
+ * ## Merge safety
+ *
+ * Keys are written sorted and each link entry is a contiguous line-group, so
+ * two people syncing different issues on different branches produce a
+ * non-overlapping diff.  The file ends with a trailing newline.  A hand-edited
+ * or merge-mangled file is rejected with a `BoardError` naming the path and the
+ * offending key — never a bare JSON parse error.
+ *
+ * ## Concurrency
+ *
+ * Two syncs can race on this file (CI plus a laptop, two teammates).  The
+ * design decision is **last-writer-wins with git as the backstop**: no lockfile
+ * in the per-remote folder.  The store's public API (`loadLinkStore` /
+ * `saveLinkStore`) is free of the single-file assumption so a per-document split
+ * under `links/` remains an internal change if the single file proves
+ * conflict-prone in practice.
+ */
+import type { BoardPaths } from '../core/storage/paths.js';
+import type { HierarchyRecord } from './hierarchy.js';
+/** One document's remote twin, as stored on disk. */
+export interface LinkEntry {
+    /** The remote system's opaque id for this issue. */
+    remoteId: string;
+    /** A human-readable key, e.g. `acme/payments#418`. */
+    remoteKey: string;
+    /** Full URL to the remote issue, so nothing has to reconstruct it. */
+    remoteUrl: string;
+    /**
+     * The remote's GraphQL node id, where the platform has one (GitHub's
+     * `node_id`). Recorded beside the number (`remoteId`) and the URL so a later
+     * story (sub-issues, Projects v2) can address the issue on the GraphQL side
+     * without a second lookup (LP-307). Absent on a platform without one.
+     */
+    nodeId?: string;
+    /**
+     * The remote parent this twin was actually filed under, as the last write
+     * left it: the remote id, or `null` for "filed with no remote parent".
+     *
+     * The base snapshot records the *local* parent (`base.parent`), which
+     * answers "did somebody reparent this locally?" and cannot answer the
+     * question a plan filed a piece at a time asks — **was the parent on the
+     * remote yet when this was created?** A story pushed before its feature is
+     * filed at the remote's top level with its local parent unchanged, so no
+     * diff ever appears, and pushing the feature afterwards left the story
+     * hanging at the root for good. Recorded as `null` in that case, the next
+     * push of the story sees a parent that has since become resolvable and
+     * repairs the shape.
+     *
+     * Absent on a link written before this was recorded, which is read as "we do
+     * not know" and changes nothing — an unknown must not manufacture a
+     * reparent for every twin on the board.
+     */
+    parentRemoteId?: string | null;
+    /** When this link was last written (ISO-8601). */
+    syncedAt: string;
+    /**
+     * The remote's own revision marker at the time of sync — a timestamp or a
+     * content hash, whatever the connector supplies.  Used on the next pull to
+     * ask "has the remote side changed?".
+     */
+    remoteRev: string;
+    /**
+     * Every mapped field's value as it stood when both sides last agreed, keyed
+     * by local attribute name.  Absent when no base snapshot has been stored yet
+     * (the link was just created and a pull has not confirmed it).
+     *
+     * Fields encoded in a managed block rather than a native remote field still
+     * appear here under their local names — the base is vocabulary-agnostic.
+     */
+    base?: Record<string, unknown>;
+    /**
+     * The remote id of the managed comment holding this twin's degraded fields,
+     * when `encoding: comment` (or a refused body write) put them there. Absent
+     * when the block lives in the body, or when no managed comment exists yet.
+     * The next push needs this id to edit rather than duplicate the comment.
+     */
+    managedCommentId?: string;
+    /**
+     * Local user-comment index (1-based, as a string) → the remote comment id
+     * that comment was posted as (LP-316). The push posts only indexes absent
+     * from this map; the pull appends only remote ids absent from its values.
+     * The managed comment is tracked separately (`managedCommentId`) and never
+     * appears here, so it is excluded from comment sync in both directions.
+     */
+    commentIds?: Record<string, string>;
+    /**
+     * The hierarchy encoding the remote last used (LP-493), recorded after a
+     * successful sync so the next sync can detect an encoding switch. Absent
+     * before the first sync, or on a store predating LP-493.
+     */
+    hierarchy?: HierarchyRecord;
+    /**
+     * Content hash of `base` at write time, so a reader can detect an edit to
+     * the file without comparing every field.  Absent when `base` is absent.
+     */
+    baseHash?: string;
+}
+/**
+ * A decoupled document's tombstone — the memory that a human deliberately
+ * dropped a link, so no later sync re-files it (LP-366 writes these; the
+ * lifecycle resolver only reads them).  Unlike a link, a tombstone names no
+ * living twin: the link is gone, and the last known remote key plus the reason
+ * it was dropped are the whole record.
+ */
+export interface Tombstone {
+    /** The last known human-readable key, e.g. `acme/payments#418`. */
+    remoteKey: string;
+    /** Why the link was dropped: `manual`, `out_of_scope`, or a policy reason. */
+    reason: string;
+    /** When it happened (ISO-8601). */
+    at: string;
+}
+/** What lives on disk inside `.lpm/remotes/<name>/links.json`. */
+export interface LinkStoreFile {
+    version: 1;
+    /**
+     * The remote's cursor at the last successful pull — a page token, a
+     * timestamp, or whatever the provider returns.  Lets the next pull ask only
+     * for what changed since last time.  Null before the first pull.
+     */
+    cursor: string | null;
+    /** Every linked document, keyed by local id.  Written in sorted key order. */
+    links: Record<string, LinkEntry>;
+    /**
+     * The hierarchy encoding the remote last used, recorded after a successful
+     * sync (LP-493).  Absent on a store that has never synced.
+     */
+    hierarchy?: HierarchyRecord;
+    /**
+     * Documents deliberately decoupled, keyed by local id.  Written in sorted key
+     * order under a key separate from `links`, so the merge-friendliness of the
+     * file covers tombstones too (LP-366).  Absent when there are none.
+     */
+    tombstones?: Record<string, Tombstone>;
+    /**
+     * When a person first confirmed writing to this remote (ISO-8601), the
+     * one-time first-write consent (LP-350). Absent until then; a sync that
+     * would make the first write asks for confirmation once and records this.
+     */
+    consentedAt?: string;
+}
+/**
+ * The link store in memory: forward and reverse indexes for O(1) lookup in
+ * both directions.
+ */
+export interface LinkStore {
+    version: number;
+    cursor: string | null;
+    /** Local id → remote twin. */
+    links: Map<string, LinkEntry>;
+    /** Remote id → local id.  Built on load; never written to disk. */
+    byRemote: Map<string, string>;
+    /** Local id → tombstone, for documents deliberately decoupled. */
+    tombstones: Map<string, Tombstone>;
+    /** The hierarchy encoding the remote last used (LP-493). */
+    hierarchy?: HierarchyRecord;
+    /** When first-write consent was recorded (LP-350); absent until then. */
+    consentedAt?: string;
+}
+/** The path to one remote's link store. */
+export declare function linksPath(paths: BoardPaths, remoteName: string): string;
+/**
+ * Read the link store from disk.  A missing file is a valid empty store — the
+ * first sync creates it.  A file that exists but cannot be parsed is a
+ * `BoardError` naming the path.
+ */
+export declare function loadLinkStore(paths: BoardPaths, remoteName: string): LinkStore;
+/**
+ * Write the link store to disk.  Creates the per-remote folder if it does not
+ * exist.  Keys are written in sorted order so two people syncing different
+ * issues produce a mergeable diff.
+ */
+export declare function saveLinkStore(paths: BoardPaths, remoteName: string, store: LinkStore): void;
+/** The remote twin of `localId`, or undefined when it is not linked. */
+export declare function getLink(store: LinkStore, localId: string): LinkEntry | undefined;
+/** The tombstone for `localId`, when the document was deliberately decoupled. */
+export declare function getTombstone(store: LinkStore, localId: string): Tombstone | undefined;
+/** True when `localId` was deliberately decoupled (LP-366 records these). */
+export declare function isDecoupled(store: LinkStore, localId: string): boolean;
+/**
+ * Record (or replace) the tombstone for `localId`.  A tombstone is the memory
+ * that a human dropped the link on purpose; it never names a living twin.
+ */
+export declare function setTombstone(store: LinkStore, localId: string, tombstone: Tombstone): void;
+/**
+ * Remove the tombstone for `localId` — the document is free to be linked (and
+ * therefore filed) again.  Returns true when there was one to remove.
+ */
+export declare function clearTombstone(store: LinkStore, localId: string): boolean;
+/**
+ * Decouple a document: drop its link (and with it the base snapshot — there is
+ * nothing left to be a base for) and record a tombstone carrying the last
+ * known remote key, the reason, and when it happened.  The remote twin is
+ * never touched by this — decoupling is a local decision that leaves the
+ * remote issue alone.
+ *
+ * Works whether or not the document is currently linked: a never-linked
+ * document is decoupled with an empty remote key, which still marks it as
+ * "never file this".  Returns the tombstone written.
+ */
+export declare function decoupleLink(store: LinkStore, localId: string, reason: string, at: string): Tombstone;
+/** The local id linked to `remoteId`, or undefined when it is not linked. */
+export declare function getLocalId(store: LinkStore, remoteId: string): string | undefined;
+/** True when `localId` has a recorded remote twin. */
+export declare function isLinked(store: LinkStore, localId: string): boolean;
+/**
+ * Record (or replace) the remote twin of `localId`.  If this local id was
+ * previously linked to a different remote id the old reverse entry is dropped.
+ */
+export declare function setLink(store: LinkStore, localId: string, entry: LinkEntry): void;
+/**
+ * Remove the link for `localId`.  Returns true when there was one to remove.
+ */
+export declare function removeLink(store: LinkStore, localId: string): boolean;
+/** The remote id of the managed comment recorded for `localId`, or undefined. */
+export declare function getManagedCommentId(store: LinkStore, localId: string): string | undefined;
+/**
+ * True when a remote comment is the managed comment for `localId` — our own
+ * output, excluded from comment sync in both directions (LP-278).  Known by
+ * id where the link store records it; by body where the id was lost.  A push
+ * never re-posts it as a user comment, and a pull never imports it as one.
+ */
+export declare function isManagedComment(store: LinkStore, localId: string, commentId: string, body: string): boolean;
+/**
+ * Record (or clear) the managed comment id for `localId`.  A no-op when the
+ * document is not linked — the comment is an attribute of an existing link.
+ */
+export declare function setManagedCommentId(store: LinkStore, localId: string, commentId: string | undefined): void;
+/**
+ * The local comment indexes (1-based, as a string) already synced for
+ * `localId`, or an empty set when the document is unlinked or has none.  The
+ * push posts only indexes absent from this set; a comment the log has since
+ * grown past (new entries appended below) is still present, because appends
+ * never shift the indexes recorded for earlier entries.
+ */
+export declare function getSyncedCommentIndexes(store: LinkStore, localId: string): Set<number>;
+/**
+ * The remote comment ids already synced for `localId`, or an empty set.  The
+ * pull appends only remote ids absent from this set; the managed comment's id
+ * is deliberately not among them, so the caller still excludes it by body/id
+ * rather than trusting the absence to be meaningful.
+ */
+export declare function getSyncedRemoteCommentIds(store: LinkStore, localId: string): Set<string>;
+/**
+ * Record that the local comment at `index` (1-based) is the remote comment
+ * `commentId` for `localId` (LP-316).  A no-op when the document is not
+ * linked.  Clearing a synced comment is not offered — the log is append-only
+ * and a recorded id stays recorded, so nothing is ever posted twice.
+ */
+export declare function setCommentId(store: LinkStore, localId: string, index: number, commentId: string): void;
+/**
+ * Change the local id a link is keyed under.  Does nothing when `oldId` has no
+ * link or when the two ids are equal, and overwrites any existing link at
+ * `newId` as the safe default — the caller must resolve that collision first.
+ */
+export declare function rewriteLinkId(store: LinkStore, oldId: string, newId: string): void;
+/**
+ * Report links whose local document no longer exists.  Never prunes silently —
+ * the caller decides whether to call `removeLink` for each.  The returned array
+ * is the list of local ids that have no matching document.
+ */
+export declare function findMissingLinks(store: LinkStore, existingIds: Set<string>): string[];
+/**
+ * Remove every link whose local document is not in `existingIds`.  Returns the
+ * ids that were pruned.
+ */
+export declare function pruneMissingLinks(store: LinkStore, existingIds: Set<string>): string[];
+/**
+ * Tombstones whose local document no longer exists.  Like `findMissingLinks`,
+ * never prunes silently — the caller decides.  A tombstone left behind by a
+ * deleted document is dead weight, not a correctness bug, but `lpm check`
+ * reports it so the store stays honest.
+ */
+export declare function findMissingTombstones(store: LinkStore, existingIds: Set<string>): string[];
+/**
+ * Remove every tombstone whose local document is not in `existingIds`.
+ * Returns the ids that were pruned.
+ */
+export declare function pruneMissingTombstones(store: LinkStore, existingIds: Set<string>): string[];
+/**
+ * Strip the managed block from a body, returning the text the remote side
+ * wrote — the content the hash should represent.  When there is no managed
+ * block the body is returned unchanged.
+ */
+export declare function stripManagedBlock(body: string): string;
+/**
+ * Compute a stable hash of the *normalised* body — managed block excluded — so
+ * the base snapshot stores a short token rather than the full text.  The
+ * returned string carries a `sha256:` prefix so a reader can tell a hash from
+ * a literal body value at a glance.
+ *
+ * The hash is over the trimmed text after the managed block is removed; two
+ * bodies that differ only in trailing whitespace outside the managed block
+ * produce the same hash.
+ *
+ * **Line endings are normalised first**, and that is not cosmetic. A board
+ * checked out on Windows has `
+` in every document; a remote hands its text
+ * back with `
+`. Hashing them apart makes every document permanently *ahead*:
+ * the push rewrites all of them, the next push does it again, and two
+ * teammates on different operating systems fight over bodies neither has
+ * edited.
+ *
+ * `normalize` is the same argument made for a remote whose body format is not
+ * markdown (`Translator.normalizeBody`): Jira stores ADF, which has paragraphs
+ * but no source line breaks, so a hard-wrapped body comes back as one long
+ * line and would differ from itself for ever. Pass it when hashing a **board**
+ * body that will be compared against a base recorded from the remote's echo;
+ * never when hashing prose the remote just handed back, which has already been
+ * through that round trip.
+ */
+export declare function hashBody(body: string, normalize?: (markdown: string) => string): string;
+/**
+ * True when `value` looks like a body hash — a string that starts with
+ * `sha256:` followed by 64 hex digits.
+ */
+export declare function isBodyHash(value: unknown): value is string;
+/**
+ * Compute the base snapshot for one document: every mapped field's value as it
+ * stands right now.  The body is stored as a hash (`hashBody`), not as the full
+ * text.  Fields carried in the managed block still appear under their local
+ * names — the base is vocabulary-agnostic.
+ *
+ * `mappedFields` is the set of local attribute names the mapping declares.
+ * Only those fields land in the snapshot; nothing else is included, because a
+ * field the mapping does not mention cannot diverge.
+ */
+export declare function computeBase(document: {
+    title: string;
+    body: string;
+    attributes: Record<string, unknown>;
+    status?: string;
+    assignee?: string | null;
+    period?: string | null;
+    dependsOn?: string[];
+    relatesTo?: string[];
+    relatedFiles?: string[];
+}, mappedFields: ReadonlySet<string>, normalizeBody?: (markdown: string) => string): Record<string, unknown>;
+/**
+ * Update the base snapshot for one linked document.  After a successful sync
+ * only the documents that landed should have their base updated — a partially
+ * failed sync must not snapshot work that did not reach the remote.
+ *
+ * The `base` value here should come from `computeBase`; the `baseHash` is
+ * derived from it automatically.
+ */
+export declare function updateBase(store: LinkStore, localId: string, base: Record<string, unknown>, remoteRev: string, syncedAt: string): void;
+/**
+ * Return the cursor to hand to the provider on the next pull, or `null` when
+ * a full scan should be performed.
+ *
+ * A stored cursor lets the pull ask the remote only for issues updated since
+ * the last successful sync.  The cursor is an opaque value the remote supplied
+ * — a page token, a timestamp, a revision hash — and its meaning is the
+ * provider's alone.
+ *
+ * When `fullSync` is `true` (the default on the CLI; `--changed` asks for the
+ * incremental listing instead) the stored cursor
+ * is ignored and `null` is returned, forcing a full listing.  When the
+ * provider does not support incremental queries the caller should also pass
+ * `null` regardless; this function does not inspect capabilities — the caller
+ * knows which provider it is talking to.
+ */
+export declare function getCursorForPull(store: LinkStore, opts?: {
+    fullSync?: boolean;
+}): string | null;
+/**
+ * Advance the cursor to a value the **remote** supplied.
+ *
+ * The cursor must come from the remote's response (a `nextCursor` or
+ * equivalent field), never from `Date.now()`.  Using local wall-clock time
+ * would miss edits made during the sync window whenever the clocks differ —
+ * every provider that supports incremental queries returns a server-side
+ * marker, and the caller must use it.
+ *
+ * This function does not validate the value at runtime; the contract is
+ * enforced by the pull planner, which is the only caller.
+ */
+export declare function advanceCursor(store: LinkStore, cursor: string): void;
+/**
+ * Reset the cursor to `null`, forcing the next pull to do a full scan.
+ *
+ * Safe to call at any time — a store with no cursor is a valid state (it is
+ * how every store starts).  Useful after a failed pull, when the remote
+ * configuration changes, or when the operator wants to rebuild the link
+ * store from a fresh crawl.
+ */
+export declare function clearCursor(store: LinkStore): void;
+/**
+ * Record the one-time first-write consent (LP-350): a person confirmed that
+ * writing to this remote is intended, so the next sync no longer asks. Set
+ * once; an existing consent is never overwritten, because the confirmation is
+ * a fact about the remote, not about this particular run.
+ */
+export declare function recordConsent(store: LinkStore, at: string): void;
+/** True when first-write consent has been recorded for this remote. */
+export declare function isConsented(store: LinkStore): boolean;