primitive-admin 1.0.61 → 1.0.63

package/dist/src/lib/toml-scalar-edit.js

@@ -0,0 +1,283 @@
+/**
+ * Set one scalar key in a TOML file, textually (issue #2645).
+ *
+ * `config set` exists so a script can change a single configuration field without
+ * a here-document. It must not parse the file and re-stringify it: the CLI's
+ * TOML layer is a `smol-toml` wrapper (`config-toml.ts`) with no comment or
+ * ordering fidelity, so a round-trip edit would quietly strip an author's
+ * comments and reorder their keys. The precedents for a textual splice are
+ * `databases schema generate` (`commands/databases.ts`) and
+ * `workflow-include-preserve.ts`.
+ *
+ * The edit is deliberately narrow — one scalar, in one table:
+ *   - the value is replaced in place when the key exists,
+ *   - the key is appended to the end of its table when it does not,
+ *   - the table is appended to the file when IT does not,
+ *   - anything else (a table path, an array value, a path that descends
+ *     through an array of tables) is refused rather than guessed at.
+ *
+ * Every result is re-parsed before it is returned, so a splice that would
+ * produce invalid TOML fails instead of writing a broken file.
+ */
+import { parseConfigToml, stringifyConfigToml } from "./config-toml.js";
+import { canonicalJsonStringify } from "./canonical-json.js";
+/** A `config set` edit that must not be applied. */
+export class TomlEditError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TomlEditError";
+    }
+}
+/**
+ * Read a command-line value into the scalar it denotes.
+ *
+ * `true`/`false` are booleans and a numeric literal is a number, so
+ * `config set workflow/x workflow.syncCallable=true` writes a boolean rather than
+ * the string `"true"`. Wrapping the value in double quotes forces a string, so
+ * a field that genuinely holds `"true"` is still expressible.
+ */
+export function parseScalarLiteral(raw) {
+    if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+        return raw.slice(1, -1);
+    }
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    // Only a complete numeric literal counts; `1.2.3` and `12px` stay strings.
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return Number(raw);
+    return raw;
+}
+/** TOML bare keys need no quoting; anything else is quoted. */
+function renderKey(key) {
+    return /^[A-Za-z0-9_-]+$/.test(key) ? key : JSON.stringify(key);
+}
+/** Render `key = value` the way smol-toml would, so escaping is not hand-rolled. */
+function renderAssignment(key, value) {
+    // `stringifyConfigToml({ k: v })` yields `k = <value>`; take the value half so
+    // string escaping, float formatting and integer formatting all come from the
+    // one TOML serializer rather than a second implementation here.
+    const rendered = stringifyConfigToml({ __v: value }).trim();
+    const eq = rendered.indexOf("=");
+    const valueText = rendered.slice(eq + 1).trim();
+    return `${renderKey(key)} = ${valueText}`;
+}
+/** Match a table header line, returning its dotted path. */
+function tableHeaderPath(line) {
+    const match = line.match(/^\s*\[([^\[\]]+)\]\s*(#.*)?$/);
+    return match ? match[1].trim() : null;
+}
+/** True for an array-of-tables header, e.g. `[[steps]]`. */
+function isArrayTableHeader(line) {
+    return /^\s*\[\[[^\[\]]+\]\]\s*(#.*)?$/.test(line);
+}
+/** True when `line` assigns `key` at the start of the line. */
+function assignsKey(line, key) {
+    const match = line.match(/^\s*("([^"]*)"|'([^']*)'|[A-Za-z0-9_-]+)\s*=/);
+    if (!match)
+        return false;
+    const found = match[2] ?? match[3] ?? match[1];
+    return found === key;
+}
+/**
+ * Replace or insert `path` in `text`.
+ *
+ * `path` is dotted TOML: the last segment is the key, the rest is the table it
+ * lives in (`workflow.status` → key `status` in table `[workflow]`). A
+ * single-segment path addresses a root-level key.
+ */
+export function setTomlScalar(text, path, value) {
+    if (!path || !path.trim()) {
+        throw new TomlEditError("a field path is required, e.g. workflow.status");
+    }
+    const segments = path.split(".").map((s) => s.trim());
+    if (segments.some((s) => s === "")) {
+        throw new TomlEditError(`'${path}' is not a valid dotted TOML path`);
+    }
+    let parsed;
+    try {
+        parsed = parseConfigToml(text);
+    }
+    catch (e) {
+        throw new TomlEditError(`the file is not valid TOML: ${e?.message || e}`);
+    }
+    // Refuse a path the file writes in a form a dotted path cannot address.
+    // A quoted key containing a dot (`"a.b" = 1`) parses to the single key `a.b`,
+    // which `workflow.a.b` cannot reach — the splice would append a NEW `[a]`
+    // table and leave the author's key untouched, giving the file two
+    // declarations of one field. That is the exact drift this issue exists to
+    // remove, so it is refused rather than written.
+    const shadow = findShadowingDottedKey(parsed, segments);
+    if (shadow) {
+        throw new TomlEditError(`'${path}' is shadowed by the quoted key '${shadow}', which a dotted ` +
+            `path cannot address — edit the file directly`);
+    }
+    // Refuse anything that is not a scalar slot. Walking the PARSED document is
+    // what makes this reliable: it sees the real shape, including a value written
+    // as an inline table or reached through an array of tables.
+    let cursor = parsed;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const next = cursor?.[segments[i]];
+        if (next === undefined || next === null) {
+            cursor = undefined;
+            break;
+        }
+        if (Array.isArray(next)) {
+            throw new TomlEditError(`'${path}' descends through the array '${segments
+                .slice(0, i + 1)
+                .join(".")}' — edit the file directly, config set only writes scalars`);
+        }
+        if (typeof next !== "object") {
+            throw new TomlEditError(`'${segments.slice(0, i + 1).join(".")}' is a value, not a table`);
+        }
+        cursor = next;
+    }
+    const existing = cursor === undefined ? undefined : cursor[segments[segments.length - 1]];
+    if (Array.isArray(existing)) {
+        throw new TomlEditError(`'${path}' is an array — edit the file directly, config set only writes scalars`);
+    }
+    if (existing !== undefined && existing !== null && typeof existing === "object") {
+        throw new TomlEditError(`'${path}' is a table — edit the file directly, config set only writes scalars`);
+    }
+    const key = segments[segments.length - 1];
+    const tablePath = segments.slice(0, -1).join(".");
+    const assignment = renderAssignment(key, value);
+    // Split preserving the trailing newline so a rewrite never adds or drops one.
+    const lines = text.split("\n");
+    // Find the span of the target table: from its header to the next header.
+    let start = 0;
+    let end = lines.length;
+    if (tablePath) {
+        let headerIndex = -1;
+        for (let i = 0; i < lines.length; i++) {
+            if (tableHeaderPath(lines[i]) === tablePath) {
+                headerIndex = i;
+                break;
+            }
+        }
+        if (headerIndex === -1) {
+            // No such table: append it, with the assignment under it.
+            const needsBlank = text.length > 0 && !text.endsWith("\n\n");
+            const prefix = text.endsWith("\n") ? "" : "\n";
+            return verify(text, `${text}${prefix}${needsBlank ? "\n" : ""}[${tablePath}]\n${assignment}\n`, path, value);
+        }
+        start = headerIndex + 1;
+        end = lines.length;
+        for (let i = start; i < lines.length; i++) {
+            if (tableHeaderPath(lines[i]) !== null || isArrayTableHeader(lines[i])) {
+                end = i;
+                break;
+            }
+        }
+    }
+    else {
+        // Root-level keys live before the first table header.
+        for (let i = 0; i < lines.length; i++) {
+            if (tableHeaderPath(lines[i]) !== null || isArrayTableHeader(lines[i])) {
+                end = i;
+                break;
+            }
+        }
+    }
+    for (let i = start; i < end; i++) {
+        if (assignsKey(lines[i], key)) {
+            lines[i] = assignment;
+            return verify(text, lines.join("\n"), path, value);
+        }
+    }
+    // Not present: insert after the table's last non-blank line so the key lands
+    // inside the table rather than after the blank line that separates it from
+    // the next one.
+    let insertAt = end;
+    while (insertAt > start && lines[insertAt - 1].trim() === "")
+        insertAt--;
+    lines.splice(insertAt, 0, assignment);
+    return verify(text, lines.join("\n"), path, value);
+}
+/**
+ * Re-parse the spliced text and confirm it differs from the original in exactly
+ * one way: `path` now holds `value`.
+ *
+ * Checking only that the target path is correct is not enough, and both ways it
+ * fails were found in review. A quoted key containing a dot (`"a.b" = 1`) is
+ * unaddressable by a dotted path, so the splice appended a NEW `[a]` table —
+ * and the target check passed, because `a.b` really did hold the new value
+ * afterwards, in a second declaration the author never wrote. Separately, the
+ * line-oriented scan can match an assignment-shaped line inside a multi-line
+ * string; when the new value equals the old one the target check still passes
+ * while the string's contents have been rewritten.
+ *
+ * Comparing the WHOLE parsed document against the expected result closes both:
+ * an edit that changes anything the caller did not ask for is refused, and
+ * refusing is safe because nothing has been written yet.
+ */
+function verify(before, next, path, value) {
+    let parsed;
+    try {
+        parsed = parseConfigToml(next);
+    }
+    catch (e) {
+        throw new TomlEditError(`the edit would produce invalid TOML (${e?.message || e}) — nothing was written`);
+    }
+    const found = path
+        .split(".")
+        .reduce((cursor, segment) => cursor?.[segment], parsed);
+    if (found !== value) {
+        throw new TomlEditError(`the edit did not take effect at '${path}' — nothing was written`);
+    }
+    const expected = withScalarAt(parseConfigToml(before), path, value);
+    if (canonicalJsonStringify(parsed) !== canonicalJsonStringify(expected)) {
+        throw new TomlEditError(`the edit would change more of the file than '${path}' — nothing was ` +
+            `written. This happens when the key is written in a form a dotted path ` +
+            `cannot address (a quoted key containing '.'), or when the assignment ` +
+            `also appears inside a multi-line string. Edit the file directly.`);
+    }
+    return next;
+}
+/**
+ * The dotted-path spelling of a key that already covers `segments` but is
+ * written as a single quoted key, or `null` when none does.
+ *
+ * Walks the tables the path descends through, checking at each level for a key
+ * that literally contains a dot and whose expansion is the requested path or a
+ * prefix of it.
+ */
+function findShadowingDottedKey(document, segments) {
+    const path = segments.join(".");
+    let cursor = document;
+    const prefix = [];
+    for (let depth = 0; depth <= segments.length; depth++) {
+        if (!cursor || typeof cursor !== "object" || Array.isArray(cursor))
+            break;
+        for (const key of Object.keys(cursor)) {
+            if (!key.includes("."))
+                continue;
+            const expanded = [...prefix, key].join(".");
+            if (path === expanded || path.startsWith(`${expanded}.`))
+                return expanded;
+        }
+        if (depth === segments.length)
+            break;
+        prefix.push(segments[depth]);
+        cursor = cursor[segments[depth]];
+    }
+    return null;
+}
+/** A deep copy of `document` with `path` set to `value`, creating tables as needed. */
+function withScalarAt(document, path, value) {
+    const copy = structuredClone(document);
+    const segments = path.split(".");
+    let cursor = copy;
+    for (const segment of segments.slice(0, -1)) {
+        if (cursor[segment] === undefined ||
+            cursor[segment] === null ||
+            typeof cursor[segment] !== "object") {
+            cursor[segment] = {};
+        }
+        cursor = cursor[segment];
+    }
+    cursor[segments[segments.length - 1]] = value;
+    return copy;
+}
+//# sourceMappingURL=toml-scalar-edit.js.map

package/dist/src/lib/toml-scalar-edit.js.map

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

package/dist/src/lib/user-selector.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolve the user selector for a list/inspection command (issue #2357).
+ *
+ * `--user-id <id>` is the canonical spelling across the CLI's list and
+ * inspection selectors — `documents list`, `documents export-all`, `workflows
+ * runs list` and `analytics` all use it, and it matches the `<user-id>`
+ * argument metavar used by `groups`, `collections` and `databases permissions`.
+ * `connections list`, `sessions list` and `tokens list` originally shipped
+ * `--user`, so that spelling stays accepted as a hidden alias: it resolves to
+ * the same value and prints one deprecation line on **stderr** (never
+ * suppressed under `--json`, because stderr cannot corrupt stdout and a
+ * scripted caller is exactly who needs to see it).
+ *
+ * Supplying both spellings exits non-zero rather than applying a silent
+ * precedence.
+ *
+ * Note: the write-side `--user` flags (`tokens create`, `tokens inject`) and
+ * the diagnostic `rule-sets debug --user` are deliberately out of scope — this
+ * is the list/inspection selector convention, not a CLI-wide rename.
+ */
+export declare function resolveUserSelector(options: {
+    user?: string;
+    userId?: string;
+}, commandLabel: string): string | undefined;

package/dist/src/lib/user-selector.js

@@ -0,0 +1,33 @@
+import { error, warn } from "./output.js";
+/**
+ * Resolve the user selector for a list/inspection command (issue #2357).
+ *
+ * `--user-id <id>` is the canonical spelling across the CLI's list and
+ * inspection selectors — `documents list`, `documents export-all`, `workflows
+ * runs list` and `analytics` all use it, and it matches the `<user-id>`
+ * argument metavar used by `groups`, `collections` and `databases permissions`.
+ * `connections list`, `sessions list` and `tokens list` originally shipped
+ * `--user`, so that spelling stays accepted as a hidden alias: it resolves to
+ * the same value and prints one deprecation line on **stderr** (never
+ * suppressed under `--json`, because stderr cannot corrupt stdout and a
+ * scripted caller is exactly who needs to see it).
+ *
+ * Supplying both spellings exits non-zero rather than applying a silent
+ * precedence.
+ *
+ * Note: the write-side `--user` flags (`tokens create`, `tokens inject`) and
+ * the diagnostic `rule-sets debug --user` are deliberately out of scope — this
+ * is the list/inspection selector convention, not a CLI-wide rename.
+ */
+export function resolveUserSelector(options, commandLabel) {
+    if (options.user && options.userId) {
+        error(`Provide only one of --user-id or --user (--user is a deprecated alias of --user-id).`);
+        process.exit(1);
+    }
+    if (options.user) {
+        warn(`--user is deprecated for \`${commandLabel}\`; use --user-id instead.`);
+        return options.user;
+    }
+    return options.userId;
+}
+//# sourceMappingURL=user-selector.js.map

package/dist/src/lib/user-selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-selector.js","sourceRoot":"","sources":["../../../src/lib/user-selector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA2C,EAC3C,YAAoB;IAEpB,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnC,KAAK,CACH,sFAAsF,CACvF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,IAAI,CACF,8BAA8B,YAAY,4BAA4B,CACvE,CAAC;QACF,OAAO,OAAO,CAAC,IAAI,CAAC;IACtB,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,CAAC;AACxB,CAAC"}

package/dist/src/lib/version-check.d.ts

@@ -1,3 +1,28 @@
+import { type GlobalInstall, type InstallKind } from "./package-manager.js";
+/**
+ * Renders the update notice. Pure — no network, no filesystem — so the exact
+ * wording is assertable in unit tests.
+ *
+ * `command` is null for installs we can't upgrade (a source checkout); the
+ * notice then prints the version line only.
+ */
+export declare function formatUpdateNotice(opts: {
+    currentVersion: string;
+    latestVersion: string;
+    command: string | null;
+}): string[];
+/**
+ * Renders a one-line note about *other* global copies of the CLI, or null when
+ * there is nothing to warn about. Pure.
+ *
+ * Only a global install can have a duplicate: the warning tells the user to
+ * remove a global copy, which is wrong advice for anyone running the CLI from
+ * a source checkout, a project dependency, or `npx` — for them the one global
+ * copy on the machine is not a duplicate, it is their install. So the notice
+ * requires the running copy to be global itself, and to be identifiable (a
+ * null `runningPath` would make every global copy look like "another" one).
+ */
+export declare function formatDuplicateWarning(globals: GlobalInstall[], runningPath: string | null, runningInstall: InstallKind | null): string | null;
 /**
  * Checks if a newer version of the CLI is available on npm.
  *

package/dist/src/lib/version-check.js

@@ -1,14 +1,16 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+import { fileURLToPath } from "url";
 import chalk from "chalk";
+import { detectInstall, findDuplicateGlobalInstalls, normalize as normalizePath, upgradeCommand, PRIMITIVE_CLI_PACKAGE, } from "./package-manager.js";
 const CONFIG_DIR = process.env.PRIMITIVE_CONFIG_DIR || join(homedir(), ".primitive");
 const VERSION_CHECK_FILE = join(CONFIG_DIR, "version-check.json");
 // Cache the result for 4 hours — short enough that users see new
 // releases the same day they drop, long enough that chatty commands
-// (sync push, tests in loops, etc.) don't hammer the npm registry.
+// (config push, tests in loops, etc.) don't hammer the npm registry.
 const CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000;
-const NPM_PACKAGE_NAME = "primitive-admin";
+const NPM_PACKAGE_NAME = PRIMITIVE_CLI_PACKAGE;
 const FETCH_TIMEOUT_MS = 3000;
 function ensureConfigDir() {
     if (!existsSync(CONFIG_DIR)) {
@@ -124,6 +126,68 @@ async function fetchLatestVersion(distTag) {
         return null;
     }
 }
+/** The realpath of this file, or null if it can't be resolved. */
+function selfPath() {
+    try {
+        return realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Renders the update notice. Pure — no network, no filesystem — so the exact
+ * wording is assertable in unit tests.
+ *
+ * `command` is null for installs we can't upgrade (a source checkout); the
+ * notice then prints the version line only.
+ */
+export function formatUpdateNotice(opts) {
+    const lines = [
+        chalk.yellow(`Update available: ${chalk.dim(opts.currentVersion)} -> ${chalk.green.bold(opts.latestVersion)}`),
+    ];
+    if (opts.command) {
+        lines.push(chalk.yellow(`Run ${chalk.cyan.bold(opts.command)} to update`));
+    }
+    return lines;
+}
+/**
+ * True when `runningPath` (the resolved path of the running CLI file) sits
+ * inside `install`. Both the install's own location and its symlink-resolved
+ * location are checked: pnpm's global `node_modules/<pkg>` is a link into the
+ * virtual store, so a pnpm user's running path only ever matches `realPath`.
+ */
+function isRunningInstall(install, runningPath) {
+    // Case-insensitive: `classifyInstallPath` lowercases, and on Windows the
+    // discovered install path and the running path can differ only in case.
+    const running = normalizePath(runningPath).toLowerCase();
+    return [install.path, install.realPath].some((candidate) => {
+        if (!candidate)
+            return false;
+        const base = normalizePath(candidate).toLowerCase();
+        return running === base || running.startsWith(`${base}/`);
+    });
+}
+/**
+ * Renders a one-line note about *other* global copies of the CLI, or null when
+ * there is nothing to warn about. Pure.
+ *
+ * Only a global install can have a duplicate: the warning tells the user to
+ * remove a global copy, which is wrong advice for anyone running the CLI from
+ * a source checkout, a project dependency, or `npx` — for them the one global
+ * copy on the machine is not a duplicate, it is their install. So the notice
+ * requires the running copy to be global itself, and to be identifiable (a
+ * null `runningPath` would make every global copy look like "another" one).
+ */
+export function formatDuplicateWarning(globals, runningPath, runningInstall) {
+    if (!runningPath || runningInstall?.kind !== "global")
+        return null;
+    const others = globals.filter((g) => !isRunningInstall(g, runningPath));
+    if (others.length === 0)
+        return null;
+    const described = others.map((g) => `${g.manager} (${g.path})`).join(", ");
+    return chalk.dim(`Another global copy of ${NPM_PACKAGE_NAME} is installed by ${described} — remove it to avoid running the wrong version.`);
+}
 /**
  * Checks if a newer version of the CLI is available on npm.
  *
@@ -157,12 +221,17 @@ export async function checkForUpdate(currentVersion) {
             }
         }
         if (latestVersion && compareVersions(currentVersion, latestVersion) < 0) {
-            const installCmd = channel
-                ? `npm i -g ${NPM_PACKAGE_NAME}@${channel}`
-                : `npm i -g ${NPM_PACKAGE_NAME}`;
+            const install = detectInstall();
+            const command = upgradeCommand(install, NPM_PACKAGE_NAME, distTag);
             console.error();
-            console.error(chalk.yellow(`Update available: ${chalk.dim(currentVersion)} -> ${chalk.green.bold(latestVersion)}`));
-            console.error(chalk.yellow(`Run ${chalk.cyan.bold(installCmd)} to update`));
+            for (const line of formatUpdateNotice({ currentVersion, latestVersion, command })) {
+                console.error(line);
+            }
+            // Only alongside an update notice: if another package manager also owns
+            // a global copy, say where it is so the user can remove the duplicate.
+            const duplicateWarning = formatDuplicateWarning(findDuplicateGlobalInstalls(NPM_PACKAGE_NAME), selfPath(), install);
+            if (duplicateWarning)
+                console.error(duplicateWarning);
         }
     }
     catch {

package/dist/src/lib/version-check.js.map

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

package/dist/src/lib/watch.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared poll-based tailing helpers for `--watch` / `--follow` (#1969).
+ *
+ * Two render modes over one abortable poll loop:
+ *   - `--watch`  → periodic full-snapshot redraw (a repeated `list`/`get`).
+ *   - `--follow` → append-only tail: fetch rows after an opaque server-owned
+ *                  `resumeAfter` checkpoint each tick.
+ *
+ * The loop is endpoint-agnostic. `--follow` consumers supply a {@link FollowSource}
+ * that knows how to fetch the page after a checkpoint; `--watch` consumers supply
+ * a `snapshot()` and a renderer. The renderer is injected (there is no `json`
+ * flag in the options) so this file never decides output shape or clears the
+ * terminal — that is entirely the caller's renderer.
+ *
+ * `--follow` is near-lossless observed-version tailing: it re-emits a row when a
+ * newer version is observed, holds no per-item dedup state, and asserts only
+ * forward progress — never a total-order or exactly-once property (the
+ * underlying GSI sorts by `modifiedAt` alone and is eventually consistent). See
+ * the design in #1969.
+ *
+ * Unit-tested against fake sources (the `cli/src/lib/paginate.ts` pattern) with
+ * no server.
+ */
+/** Interval floor: reject anything below this (prevents a request storm). */
+export declare const MIN_INTERVAL_SECONDS = 1;
+/** Default poll interval when `--interval` is omitted. */
+export declare const DEFAULT_INTERVAL_SECONDS = 2;
+/**
+ * Default cap on how many pages `followLoop` drains within a single tick when a
+ * burst is larger than one page. Bounds the within-tick work and, with the
+ * non-advancing-checkpoint guard, prevents an infinite drain.
+ */
+export declare const DEFAULT_MAX_PAGES_PER_TICK = 20;
+/**
+ * Validate an `--interval` value (in seconds). Returns the interval in seconds,
+ * or throws with a clear message for a missing/NaN/sub-floor value. Command
+ * handlers call this and surface the error; the library loops take a validated
+ * `intervalMs`.
+ */
+export declare function parseIntervalSeconds(raw: string | undefined): number;
+/**
+ * Sleep for `ms`, resolving early (never rejecting) if `signal` aborts. The
+ * timer and abort listener are always cleaned up, so a resolved delay leaves no
+ * dangling timer. Used by every poll loop so Ctrl-C stops promptly between
+ * ticks.
+ */
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+/** Error policy for the poll loops: keep polling, or throw out of the loop. */
+export type PollErrorPolicy = "continue" | "throw";
+export interface PollUntilOptions<T> {
+    /** Validated poll interval in milliseconds. */
+    intervalMs: number;
+    /** Abort signal (Ctrl-C at the command level). */
+    signal: AbortSignal;
+    /** What to do when `probe` throws. Default `"throw"`. */
+    onError?: PollErrorPolicy;
+    /** Called with each probed value (e.g. to report progress). */
+    onValue?: (value: T) => void;
+}
+/**
+ * Delay-then-probe until `done(value)` is true or the signal aborts. Returns
+ * the last probed value. Delay-first (not probe-first) so a caller that already
+ * holds a fresh value — the batch-status loops — keeps its "poll every N
+ * seconds" cadence with no extra immediate request.
+ */
+export declare function pollUntil<T>(probe: () => Promise<T>, done: (value: T) => boolean, options: PollUntilOptions<T>): Promise<T>;
+/** One page of follow results, carrying the opaque next checkpoint. */
+export interface FollowPage<T> {
+    items: T[];
+    /** More rows remain past this page right now (drives the within-tick drain). */
+    hasMore: boolean;
+    /** Opaque server-owned checkpoint; always present, even on an empty page. */
+    resumeAfter: string;
+}
+/**
+ * A source of follow pages. `fetchAfter(undefined)` is the bootstrap poll — it
+ * establishes the baseline checkpoint and its items are NOT emitted (tail
+ * semantics: "show me what happens from now"). `fetchAfter(<token>)` returns the
+ * bounded page after that checkpoint.
+ */
+export interface FollowSource<T> {
+    fetchAfter: (resumeAfter: string | undefined) => Promise<FollowPage<T>>;
+    /**
+     * Max pages to drain within one tick when a burst exceeds one page. Defaults
+     * to {@link DEFAULT_MAX_PAGES_PER_TICK}. The drain also stops early if the
+     * checkpoint fails to advance (non-advancing-checkpoint guard).
+     */
+    maxPagesPerTick?: number;
+}
+export interface FollowOptions<T> {
+    intervalMs: number;
+    signal: AbortSignal;
+    /** What to do when a poll throws. Default `"continue"` (keep tailing). */
+    onError?: PollErrorPolicy;
+    /** Render newly-observed rows (server-ascending; no client sort). */
+    render: (items: T[]) => void;
+}
+export interface WatchOptions<T> {
+    intervalMs: number;
+    signal: AbortSignal;
+    /** What to do when a poll throws. Default `"continue"`. */
+    onError?: PollErrorPolicy;
+    /**
+     * Render the full snapshot. The renderer owns any clearing/redraw — the loop
+     * never clears the terminal itself.
+     */
+    render: (items: T[]) => void;
+}
+/**
+ * Append-only tail. Bootstraps the baseline checkpoint (emitting nothing), then
+ * each tick drains forward while `hasMore` (bounded by `maxPagesPerTick`,
+ * stopping if the checkpoint fails to advance), rendering rows server-ascending.
+ * Holds no per-item state — the only carried state is the single opaque
+ * `resumeAfter` string.
+ */
+export declare function followLoop<T>(source: FollowSource<T>, options: FollowOptions<T>): Promise<void>;
+/**
+ * Snapshot redraw. Each tick fetches the full current snapshot and hands it to
+ * the renderer, which owns any clearing/redraw. No checkpoint, no dedup.
+ */
+export declare function watchLoop<T>(snapshot: () => Promise<T[]>, options: WatchOptions<T>): Promise<void>;