light-plan 0.0.0-stage → 0.1.0

package/dist/remote/credentials.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Credential resolution (LP-295).
+ *
+ * A connection block names *where* a secret comes from, never the secret: the
+ * config is committed, so a token written into it travels to every clone. The
+ * resolver turns a connection value into the actual secret at sync time, in
+ * this order:
+ *
+ *   1. `${VAR}`                        — an explicit reference into the
+ *                                        environment;
+ *   2. `.lpm/credentials.json`          — git-ignored, written by
+ *                                        `lpm remote login`;
+ *   3. the platform's own env var       — `GITHUB_TOKEN`, `JIRA_API_TOKEN`, …;
+ *   4. fail, naming all three options.
+ *
+ * A literal secret in the connection is refused here — and reported by the
+ * check — because a secret in the committed config is the one mistake a shared
+ * repo cannot recover from. Nothing here prints the value: a resolved secret
+ * travels only into the connector, and errors name the *where*, never the
+ * secret itself.
+ */
+import type { BoardPaths } from '../core/storage/paths.js';
+/** True when a connection value is an explicit `${VAR}` reference. */
+export declare function isEnvReference(value: unknown): value is string;
+/** The variable name an env reference points at. Call only when `isEnvReference`. */
+export declare function envReferenceName(value: string): string;
+/**
+ * True when a connection value is a literal secret: a non-empty string that is
+ * not a `${VAR}` reference. The check reports these and the resolver refuses
+ * them — one predicate, so the two cannot disagree about what "literal" means.
+ */
+export declare function isLiteralSecret(value: unknown): boolean;
+/** One resolved secret: the value, plus the name and source a 401 can mention. */
+export interface ResolvedSecret {
+    value: string;
+    /** The credential's name — `GITHUB_TOKEN` from the env, or the connection key. */
+    name: string;
+    /** Where the value came from, a phrase like `the environment`. */
+    source: string;
+}
+/** `.lpm/credentials.json`: remote name → connection key → secret value. */
+type CredentialsFile = Record<string, Record<string, string>>;
+/** Read `.lpm/credentials.json`; `{}` when absent, `BoardError` when malformed. */
+export declare function readCredentialsFile(paths: BoardPaths): CredentialsFile;
+/** The credential `.lpm/credentials.json` holds for one remote and key, if any. */
+export declare function readCredential(paths: BoardPaths, remote: string, key: string): string | undefined;
+/**
+ * Write one secret into `.lpm/credentials.json`, preserving every other
+ * remote and key. The file is written owner-only (0600) and healed into
+ * `.lpm/.gitignore`, so it can never be committed by accident.
+ */
+export declare function writeCredential(paths: BoardPaths, remote: string, key: string, value: string): void;
+/** Resolve one connection value into a secret, following the LP-295 order. */
+export declare function resolveSecret(opts: {
+    /** The remote's name, for the error message and the credentials lookup. */
+    remote: string;
+    /** The connection key holding the secret, e.g. `token`. */
+    key: string;
+    /** The platform's own env var, e.g. `GITHUB_TOKEN`. */
+    conventionalEnv?: string;
+    /** The raw connection value: `${VAR}`, a literal, or undefined. */
+    configured: unknown;
+    paths: BoardPaths;
+}): ResolvedSecret;
+/** One secret key's state, without resolving (or printing) the value itself. */
+export interface CredentialState {
+    /** The connection key that holds the secret, e.g. `token`. */
+    key: string;
+    /** The platform's conventional environment variable, when it has one. */
+    env?: string;
+    /** Where the value would come from, or `undefined` when nothing holds one. */
+    source?: string;
+    /** The `${VAR}` name the config points at, when it points at one. */
+    reference?: string;
+}
+/**
+ * Report which of a remote's secrets are already available and from where —
+ * the read-only twin of `resolveSecret`, for a command that wants to *tell a
+ * person what to do next* rather than make a request.
+ *
+ * `resolveSecret` throws when nothing holds the value, which is right for a
+ * sync and wrong for `lpm remote add`: a person who has just declared a remote
+ * needs the instructions, not a stack of errors. So this answers the same
+ * question without the failure, and without ever reading the value into a
+ * place it could be printed — only its *source*.
+ */
+export declare function credentialStates(remote: string, connection: Record<string, unknown>, secrets: Record<string, string>, paths: BoardPaths): CredentialState[];
+/**
+ * Resolve every secret key of a connection block, returning a copy with the
+ * values filled in. Non-secret keys pass through untouched. A secret the
+ * config omits entirely is still resolved through the fallback chain, so a
+ * connector never sees `undefined` where it expected a token.
+ */
+export declare function resolveConnectionSecrets(remote: string, connection: Record<string, unknown>, secrets: Record<string, string>, paths: BoardPaths): Record<string, unknown>;
+export {};

package/dist/remote/credentials.js

@@ -0,0 +1,210 @@
+/**
+ * Credential resolution (LP-295).
+ *
+ * A connection block names *where* a secret comes from, never the secret: the
+ * config is committed, so a token written into it travels to every clone. The
+ * resolver turns a connection value into the actual secret at sync time, in
+ * this order:
+ *
+ *   1. `${VAR}`                        — an explicit reference into the
+ *                                        environment;
+ *   2. `.lpm/credentials.json`          — git-ignored, written by
+ *                                        `lpm remote login`;
+ *   3. the platform's own env var       — `GITHUB_TOKEN`, `JIRA_API_TOKEN`, …;
+ *   4. fail, naming all three options.
+ *
+ * A literal secret in the connection is refused here — and reported by the
+ * check — because a secret in the committed config is the one mistake a shared
+ * repo cannot recover from. Nothing here prints the value: a resolved secret
+ * travels only into the connector, and errors name the *where*, never the
+ * secret itself.
+ */
+import { chmodSync, readFileSync } from 'node:fs';
+import { writeFileAtomic } from '../core/storage/atomic.js';
+import { BoardError } from '../core/errors.js';
+import { displayPath } from '../core/storage/paths.js';
+/** A `${VAR}` reference — the whole value and nothing else. */
+const REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+/** True when a connection value is an explicit `${VAR}` reference. */
+export function isEnvReference(value) {
+    return typeof value === 'string' && REF_RE.test(value.trim());
+}
+/** The variable name an env reference points at. Call only when `isEnvReference`. */
+export function envReferenceName(value) {
+    return REF_RE.exec(value.trim())[1];
+}
+/**
+ * True when a connection value is a literal secret: a non-empty string that is
+ * not a `${VAR}` reference. The check reports these and the resolver refuses
+ * them — one predicate, so the two cannot disagree about what "literal" means.
+ */
+export function isLiteralSecret(value) {
+    return typeof value === 'string' && value.trim() !== '' && !isEnvReference(value);
+}
+/** Normalize a parsed credentials document into `CredentialsFile`. */
+function normalizeCredentials(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    const out = {};
+    for (const [remote, entry] of Object.entries(parsed)) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const values = {};
+        for (const [key, value] of Object.entries(entry)) {
+            if (typeof value === 'string' && value.trim() !== '')
+                values[key] = value;
+        }
+        out[remote] = values;
+    }
+    return out;
+}
+/** Read `.lpm/credentials.json`; `{}` when absent, `BoardError` when malformed. */
+export function readCredentialsFile(paths) {
+    let text;
+    try {
+        text = readFileSync(paths.credentialsPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new BoardError(`Cannot read ${displayPath(paths, paths.credentialsPath)}`, [
+            `The file exists but is not valid JSON: ${error.message}`,
+            'Recreate it with: lpm remote login <name>',
+        ]);
+    }
+    return normalizeCredentials(parsed);
+}
+/**
+ * Read `.lpm/credentials.json` the way `lpm remote login` does: a malformed
+ * file is treated as empty, because login is the fix for one.
+ */
+function readCredentialsFileLenient(paths) {
+    try {
+        return readCredentialsFile(paths);
+    }
+    catch {
+        return {};
+    }
+}
+/** The credential `.lpm/credentials.json` holds for one remote and key, if any. */
+export function readCredential(paths, remote, key) {
+    return readCredentialsFile(paths)[remote]?.[key];
+}
+/**
+ * Write one secret into `.lpm/credentials.json`, preserving every other
+ * remote and key. The file is written owner-only (0600) and healed into
+ * `.lpm/.gitignore`, so it can never be committed by accident.
+ */
+export function writeCredential(paths, remote, key, value) {
+    const file = readCredentialsFileLenient(paths);
+    file[remote] = { ...(file[remote] ?? {}), [key]: value };
+    writeFileAtomic(paths.credentialsPath, `${JSON.stringify(file, null, 2)}\n`);
+    chmodSync(paths.credentialsPath, 0o600);
+}
+/** Resolve one connection value into a secret, following the LP-295 order. */
+export function resolveSecret(opts) {
+    const { remote, key, conventionalEnv, configured, paths } = opts;
+    if (typeof configured === 'string' && configured.trim() !== '') {
+        const value = configured.trim();
+        if (isEnvReference(value)) {
+            const name = envReferenceName(value);
+            const fromEnv = process.env[name];
+            if (fromEnv === undefined || fromEnv === '') {
+                throw new BoardError(`The credential for remote "${remote}" is not set`, [
+                    `connection.${key} references \${${name}}, which is not in the environment`,
+                    `Set it with: export ${name}=...`,
+                ]);
+            }
+            return { value: fromEnv, name, source: 'the environment' };
+        }
+        throw new BoardError(`Remote "${remote}" has a literal credential in config.yml`, [
+            `connection.${key} holds a secret; the config is committed and must never carry one`,
+            `Use connection.${key}: \${${conventionalEnv ?? 'TOKEN'}} instead, or omit it and run: lpm remote login ${remote}`,
+        ]);
+    }
+    const fromFile = readCredential(paths, remote, key);
+    if (fromFile !== undefined) {
+        return { value: fromFile, name: key, source: '.lpm/credentials.json' };
+    }
+    if (conventionalEnv) {
+        const fromEnv = process.env[conventionalEnv];
+        if (fromEnv !== undefined && fromEnv !== '') {
+            return { value: fromEnv, name: conventionalEnv, source: 'the environment' };
+        }
+    }
+    const options = [
+        `${displayPath(paths, paths.credentialsPath)} — write it with: lpm remote login ${remote}`,
+    ];
+    if (conventionalEnv)
+        options.push(`the ${conventionalEnv} environment variable`);
+    options.push(`an explicit connection.${key}: \${VAR} reference in config.yml`);
+    throw new BoardError(`No credential for remote "${remote}"`, options);
+}
+/**
+ * Report which of a remote's secrets are already available and from where —
+ * the read-only twin of `resolveSecret`, for a command that wants to *tell a
+ * person what to do next* rather than make a request.
+ *
+ * `resolveSecret` throws when nothing holds the value, which is right for a
+ * sync and wrong for `lpm remote add`: a person who has just declared a remote
+ * needs the instructions, not a stack of errors. So this answers the same
+ * question without the failure, and without ever reading the value into a
+ * place it could be printed — only its *source*.
+ */
+export function credentialStates(remote, connection, secrets, paths) {
+    const states = [];
+    for (const [key, env] of Object.entries(secrets)) {
+        const configured = connection[key];
+        const state = { key, ...(env ? { env } : {}) };
+        if (isEnvReference(configured)) {
+            const name = envReferenceName(configured);
+            state.reference = name;
+            const value = process.env[name];
+            if (value !== undefined && value !== '')
+                state.source = `$${name}`;
+        }
+        else if (isLiteralSecret(configured)) {
+            // A literal secret is refused by the resolver; report it as unset rather
+            // than as available, so the guidance says what to do instead.
+            states.push(state);
+            continue;
+        }
+        if (state.source === undefined && readCredential(paths, remote, key) !== undefined) {
+            state.source = displayPath(paths, paths.credentialsPath);
+        }
+        if (state.source === undefined && env !== undefined) {
+            const value = process.env[env];
+            if (value !== undefined && value !== '')
+                state.source = `$${env}`;
+        }
+        states.push(state);
+    }
+    return states;
+}
+/**
+ * Resolve every secret key of a connection block, returning a copy with the
+ * values filled in. Non-secret keys pass through untouched. A secret the
+ * config omits entirely is still resolved through the fallback chain, so a
+ * connector never sees `undefined` where it expected a token.
+ */
+export function resolveConnectionSecrets(remote, connection, secrets, paths) {
+    const resolved = { ...connection };
+    for (const [key, conventionalEnv] of Object.entries(secrets)) {
+        resolved[key] = resolveSecret({
+            remote,
+            key,
+            conventionalEnv,
+            configured: connection[key],
+            paths,
+        }).value;
+    }
+    return resolved;
+}
+//# sourceMappingURL=credentials.js.map

package/dist/remote/credentials.js.map

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

package/dist/remote/execute.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The push executor — the push-side mirror of `applyChanges` in `src/sync/apply.ts`.
+ *
+ * `planPush` (`plan.ts`) returns a `RemoteOp[]` and makes no request; `lpm
+ * remote push` (LP-341) is a thin printer.  This file owns the piece between
+ * them: it walks the plan in order, has the provider's translator turn each op
+ * into a request description, sends it through the (already decorated)
+ * connector, and records what landed in the link store **before** attempting
+ * the next op — so an interruption at any point leaves a store that matches the
+ * remote, and re-running the sync is the retry mechanism (LP-298's resumability
+ * rests on this loop).
+ *
+ * The planner stays pure and browser-compatible; this file does the I/O.  It
+ * makes **no planning decision**: a test can hand it a literal plan and an
+ * in-memory connector and assert exactly which requests were made and what was
+ * recorded.  Ordering, scope, direction and diffing all live in `planPush`;
+ * this loop only carries them out.
+ *
+ * ## Recording, per op, from the response
+ *
+ * Every landed write records two things before the next op runs:
+ *
+ *   - the link (`setLink` for a create): remote id, key, url and the remote's
+ *     revision marker, all read off the `ConnectorResult` the request returned;
+ *   - the base snapshot (`updateBase`): the mapped fields as the **remote** now
+ *     holds them, read off the `ConnectorResult.record` the request returned
+ *     and translated back to board vocabulary, with `remoteRev` from that same
+ *     response (LP-288). Recording the local intent instead would make the
+ *     next pull see our own write as a remote edit.
+ *
+ * The base's dependency list is tracked by this executor rather than read from
+ * the document: a create starts with no remote edges and each landed `link` /
+ * `unlink` moves it, so a partially-landed push re-plans exactly the edges that
+ * still need making.
+ *
+ * ## The diff is the planner's; the full document is the executor's
+ *
+ * `planPush` emits an op only when something changed, and its `fields` / `status`
+ * carry that diff.  The executor reads the full document back from the board
+ * instead, because the translator produces a full request from full fields — a
+ * partial set would make it drop the type/status labels and the connector would
+ * then clear them.  Conflict detection (LP-257) will later decide *which* fields
+ * are actually sent; until then a push converges the twin onto the board's whole
+ * current state.
+ */
+import type { LoadedBoard } from '../core/board/load.js';
+import type { LinkStore } from './links.js';
+import type { ResolvedHierarchy } from './hierarchy.js';
+import type { ManagedCommentCapability } from './managed-comment.js';
+import type { RemoteOp } from './plan.js';
+import type { Connector } from './provider.js';
+import type { OpenedRemote } from './remotes.js';
+/** One progress event, emitted before each op is attempted (LP-298). */
+export interface OpProgress {
+    /** 1-based position of this op in the plan. */
+    index: number;
+    /** Total number of ops in the plan. */
+    total: number;
+    /** The op about to be attempted. */
+    op: RemoteOp;
+    /** The board document the op acts on. */
+    localId: string;
+}
+/** An op that landed on the remote and was recorded in the link store. */
+export interface LandedOp {
+    kind: RemoteOp['kind'];
+    localId: string;
+    status: 'landed';
+    /** The remote id the op resolved or wrote. */
+    remoteId?: string;
+}
+/** An op that was attempted and rejected. */
+export interface FailedOp {
+    kind: RemoteOp['kind'];
+    localId: string;
+    status: 'failed';
+    error: string;
+}
+/** An op the remote refused because its twin changed since it was read (a 409). */
+export interface ConflictedOp {
+    kind: RemoteOp['kind'];
+    localId: string;
+    status: 'conflicted';
+    error: string;
+}
+/** An op that was never attempted: it waits on a failed create, or the connector cannot do it. */
+export interface SkippedOp {
+    kind: RemoteOp['kind'];
+    localId: string;
+    status: 'skipped';
+    reason: string;
+}
+/** The counts a summary reports (LP-298), per document-level outcome. */
+export interface PushSummary {
+    /** New twins filed (`create` / `restore` ops that landed). */
+    created: number;
+    /** Existing twins written or re-wired: every other landed op. */
+    updated: number;
+    skipped: number;
+    conflicted: number;
+    failed: number;
+}
+/** Why a run stopped before it reached the end of the plan. */
+export interface StopInfo {
+    reason: 'aborted' | 'budget' | 'limit';
+    /** 1-based position of the op that was in flight, or the next un-attempted one. */
+    atOp: number;
+    /** Human-readable detail: how far the budget got, the limit reached, … */
+    detail: string;
+    /** How many remaining remote-write ops were deferred (`--limit`, LP-350). */
+    deferred?: number;
+}
+/** What one push execution landed, per document. */
+export interface PushExecutionResult {
+    landed: LandedOp[];
+    failed: FailedOp[];
+    skipped: SkippedOp[];
+    /** Ops the remote refused with a conflict (409), split out of `failed` (LP-298). */
+    conflicted: ConflictedOp[];
+    /** Aggregated counts for the CLI/server summary line. */
+    summary: PushSummary;
+    /** Present when the run stopped early — aborted, budget-exhausted, or `--limit`. */
+    stopped?: StopInfo;
+}
+export interface ExecutePushOptions {
+    /** Progress callback, one call per op before it is attempted. */
+    onProgress?: (progress: OpProgress) => void;
+    /** Clock for the `syncedAt` written into each link. Injectable for tests. */
+    now?: () => Date;
+    /**
+     * The resolved comment capability, for the managed-comment op (LP-278).
+     * Defaults to "no comments", so an executor handed no capabilities skips
+     * the op with a reason rather than guessing.
+     */
+    comments?: ManagedCommentCapability;
+    /**
+     * Abort signal (LP-298): checked before each op and threaded into every
+     * connector write, so Ctrl-C aborts the in-flight request and the run stops
+     * at a consistent point — after the current op, nothing further attempted.
+     */
+    signal?: AbortSignal;
+    /**
+     * At most this many remote write ops are performed (LP-298): a cautious
+     * first run stops here and re-running continues from the link store. Local
+     * bookkeeping (`unlinkLocal`, `decouple`) does not count.
+     */
+    limit?: number;
+    /**
+     * The hierarchy encoding resolved for this run (LP-493). Recorded on the
+     * link store after a clean run, so the next push can detect an encoding
+     * switch and migrate the twins whose parent changed carrier.
+     */
+    hierarchy?: ResolvedHierarchy;
+}
+/**
+ * True when an op can invoke a connector write — the ops `--limit` counts
+ * (LP-298). `unlinkLocal` and `decouple` are local link-store edits, never a
+ * remote write, so a cautious first run does not spend its limit on them.
+ */
+export declare function isRemoteWrite(op: RemoteOp): boolean;
+/**
+ * Walk a push plan through a connector, recording each landed operation.
+ *
+ * Mutates `store` in place and writes it back to
+ * `.lpm/remotes/<remote.name>/links.json` after every landed op, so an
+ * interruption at any point leaves the store matching the remote.  A failed op
+ * does not abort the run: independent documents continue, dependents of the
+ * failure (a child of a failed create, an edge naming its endpoint) are skipped
+ * with a reason, and the summary reports created, updated, skipped,
+ * conflicted and failed per document (LP-298).  A budget-exhausted or aborted
+ * failure ends the whole run cleanly rather than cascading through the ops
+ * behind it; `--limit` stops before the next write once it is reached.
+ *
+ * No planning: the plan's order is respected as-is, every op's references are
+ * resolved through the placeholder map a landed create populates, and nothing
+ * here re-derives scope, direction or diffs.
+ */
+export declare function executePush(board: LoadedBoard, remote: OpenedRemote, connector: Connector, store: LinkStore, plan: RemoteOp[], options?: ExecutePushOptions): Promise<PushExecutionResult>;