@productbrain/cli 0.1.0-beta.14 → 0.1.0-beta.14010

package/dist/lib/update-check.js

@@ -0,0 +1,261 @@
+/**
+ * Ambient update notification for the Product Brain CLI (WP-322 S1 / FEAT-1012).
+ *
+ * Checks npm registry for the latest version of @productbrain/cli and prints
+ * a one-line notification when a newer version is available.
+ *
+ * Rules:
+ *   - Synchronous: reads cache only, never awaits network, never delays the command
+ *   - Multi-source cache at ~/.config/productbrain/update-check.json:
+ *     server header is authoritative within 48h; npm is an isNewer-gated fallback
+ *   - Silent on any error (network down, registry unreachable, etc.)
+ *   - JSON/agent mode: notice goes to stderr (stdout stays bare JSON), throttled once per session
+ *   - Does NOT use undici/fetch directly; uses Node.js built-in https
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
+import { request } from 'node:https';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isJsonMode } from './runner.js';
+import { dim, yellow } from './style.js';
+import { claimNotice } from './notice-marker.js';
+import { CLI_RELEASES_URL } from './constants.js';
+const PKG_NAME = '@productbrain/cli';
+const SERVER_FRESHNESS_MS = 48 * 60 * 60 * 1000;
+// npm fallback freshness — mirrors the single-source 24h cache TTL that existed before the
+// multi-source split, so a cached npm value is revalidated daily instead of served forever.
+const NPM_FRESHNESS_MS = 24 * 60 * 60 * 1000;
+const CONFIG_DIR = join(homedir(), '.config', 'productbrain');
+const CACHE_PATH = join(CONFIG_DIR, 'update-check.json');
+const UPGRADE_PENDING_PATH = join(CONFIG_DIR, 'upgrade-pending');
+const NPM_BETA_URL = `https://registry.npmjs.org/${PKG_NAME}/beta`;
+const CHANNEL_RANK = { alpha: -3, beta: -2, rc: -1 };
+let pendingUpgradeClearedThisProcess = false;
+function readCacheFile() {
+    try {
+        if (!existsSync(CACHE_PATH))
+            return {};
+        return JSON.parse(readFileSync(CACHE_PATH, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeCacheFile(cache) {
+    try {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        writeFileSync(CACHE_PATH, JSON.stringify(cache), 'utf8');
+    }
+    catch { /* non-fatal */ }
+}
+/** Return the newest (highest by semver) of the supplied values, ignoring null/undefined. */
+function newestOf(...values) {
+    let best = null;
+    for (const v of values) {
+        if (!v)
+            continue;
+        if (best === null || isNewer(best, v))
+            best = v;
+    }
+    return best;
+}
+/**
+ * Hot-path resolution from cache only — NEVER fetches. The **newest** in-window source wins: the
+ * server header is preferred only when it is actually the highest version, so a server that lags
+ * npm (its committed `cliVersion.ts` value trails the run-numbered npm publish — see TEN-2199) can
+ * no longer mask a newer npm latest. Returns the best available value even when every source is
+ * stale ("better than nothing"), because the hot path (checkForUpdate) cannot block on a refresh.
+ */
+export function resolveCachedLatest() {
+    if (isVersionCheckDisabled())
+        return null;
+    const cache = readCacheFile();
+    const now = Date.now();
+    const serverFresh = cache.server && now - cache.server.recordedAt < SERVER_FRESHNESS_MS ? cache.server.value : null;
+    // Hot path: an npm value is usable even when stale ("better than nothing"); the live resolver
+    // (resolveLatestVersion) is the one that enforces the npm freshness window and re-fetches.
+    const best = newestOf(serverFresh, cache.npm?.value);
+    if (best !== null)
+        return best;
+    return cache.server?.value ?? null; // stale server (>48h) as last resort — better than nothing
+}
+/** The in-window value from each source (null when the source is absent or past its freshness window). */
+function readFreshSources() {
+    const cache = readCacheFile();
+    const now = Date.now();
+    return {
+        server: cache.server && now - cache.server.recordedAt < SERVER_FRESHNESS_MS ? cache.server.value : null,
+        npm: cache.npm && now - cache.npm.recordedAt < NPM_FRESHNESS_MS ? cache.npm.value : null,
+    };
+}
+/** @deprecated use resolveCachedLatest. Kept for callers migrating. */
+export function readCachedLatestVersion() {
+    return resolveCachedLatest();
+}
+function isVersionCheckDisabled() {
+    return process.env.PB_NO_VERSION_CHECK === '1';
+}
+/** Clear the post-upgrade sentinel and stale update cache on next CLI startup, and say once,
+ *  on stderr, which version is now running and where its releases are listed (TEN-4860). */
+export function clearPendingUpgradeCache(currentVersion) {
+    if (pendingUpgradeClearedThisProcess)
+        return;
+    pendingUpgradeClearedThisProcess = true;
+    try {
+        if (!existsSync(UPGRADE_PENDING_PATH))
+            return;
+        try {
+            unlinkSync(UPGRADE_PENDING_PATH);
+        }
+        catch { /* non-fatal */ }
+        try {
+            if (existsSync(CACHE_PATH))
+                unlinkSync(CACHE_PATH);
+        }
+        catch { /* non-fatal */ }
+        if (!isVersionCheckDisabled()) {
+            const to = currentVersion ? ` to ${currentVersion}` : '';
+            process.stderr.write(`${yellow('pb:')} upgraded${to}. What changed: ${CLI_RELEASES_URL}\n`);
+        }
+    }
+    catch {
+        // Sentinel cleanup must never block CLI startup.
+    }
+}
+/** Written after a successful self-upgrade so the next CLI process drops stale cache. */
+export function writeUpgradePendingSentinel(installedVersion) {
+    try {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        writeFileSync(UPGRADE_PENDING_PATH, JSON.stringify({ upgradedAt: Date.now(), version: installedVersion ?? null /* the requested version, for diagnostics; the notice names the version that actually runs */ }), 'utf8');
+    }
+    catch { /* non-fatal — update checks recover via cache TTL */ }
+}
+/** Test-only: reset module-level per-process guards so each test starts clean. */
+export function _resetProcessGuardsForTest() {
+    pendingUpgradeClearedThisProcess = false;
+}
+/** Fetch latest version from npm registry. Returns null on any error. */
+function fetchLatestVersion() {
+    return new Promise((resolve) => {
+        const req = request(NPM_BETA_URL, { method: 'GET', headers: { 'Accept': 'application/json' } }, (res) => {
+            let body = '';
+            res.on('data', (chunk) => { body += chunk.toString(); });
+            res.on('end', () => {
+                try {
+                    const parsed = JSON.parse(body);
+                    resolve(parsed.version ?? null);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+            res.on('error', () => resolve(null));
+        });
+        req.on('error', () => resolve(null));
+        req.setTimeout(3000, () => {
+            req.destroy();
+            resolve(null);
+        });
+        req.end();
+    });
+}
+/**
+ * Compare two semver strings. Returns true if `b` is strictly newer than `a`.
+ * Handles standard x.y.z and x.y.z-beta.N formats (numeric comparison per part).
+ */
+export function isNewer(current, latest) {
+    if (current === latest)
+        return false;
+    const parseVersion = (v) => {
+        const clean = v.replace(/^v/, '');
+        const [release, pre] = clean.split('-');
+        const parts = (release ?? '').split('.').map((n) => parseInt(n, 10) || 0);
+        if (pre === undefined)
+            return [...parts, 0, 0];
+        const match = pre.match(/^([a-zA-Z]+)\.?(\d+)?/);
+        const channel = match?.[1]?.toLowerCase() ?? '';
+        const preNum = match?.[2] ? parseInt(match[2], 10) : 0;
+        return [...parts, CHANNEL_RANK[channel] ?? -4, Number.isFinite(preNum) ? preNum : 0];
+    };
+    const a = parseVersion(current);
+    const b = parseVersion(latest);
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        if (bv > av)
+            return true;
+        if (bv < av)
+            return false;
+    }
+    return false;
+}
+/** Record the server-supplied latest version (authoritative source). */
+export function recordServerLatest(latestVersion) {
+    if (isVersionCheckDisabled() || !latestVersion)
+        return;
+    const cache = readCacheFile();
+    cache.server = { value: latestVersion, recordedAt: Date.now() };
+    writeCacheFile(cache);
+}
+/** Record an npm-resolved latest version — gated so it never stores <= installed. */
+export function recordNpmLatest(latestVersion, currentVersion) {
+    if (isVersionCheckDisabled() || !latestVersion)
+        return;
+    if (!isNewer(currentVersion, latestVersion))
+        return;
+    const cache = readCacheFile();
+    cache.npm = { value: latestVersion, recordedAt: Date.now() };
+    writeCacheFile(cache);
+}
+/** LIVE resolve — fetches npm and records it (gated). Call ONLY from doctor/upgrade, never the hot path. */
+export async function resolveLatestVersion(currentVersion) {
+    if (isVersionCheckDisabled())
+        return null;
+    const fresh = readFreshSources();
+    // Skip the network ONLY when npm itself is within its freshness window. A fresh server header
+    // alone cannot prove npm isn't newer (the hot path never populates npm, and the server's committed
+    // cliVersion.ts value structurally trails the run-numbered npm publish — TEN-2199), so a
+    // server-only cache MUST trigger a live npm fetch or the lagging server would mask the true latest.
+    if (fresh.npm !== null)
+        return newestOf(fresh.server, fresh.npm);
+    const fetched = await fetchLatestVersion();
+    if (fetched !== null) {
+        // The live registry is ground truth. Record only when strictly newer (the cache never stores a
+        // value <= installed), but compare against any fresh server header so a genuinely-newer server
+        // still wins. A successful fetch REPLACES a stale npm entry rather than falling back to it.
+        if (currentVersion)
+            recordNpmLatest(fetched, currentVersion);
+        return newestOf(fresh.server, fetched);
+    }
+    // Fetch failed (offline / registry unreachable): fall back to any cached value — better than
+    // nothing, and the documented `pb doctor` offline backstop.
+    return resolveCachedLatest();
+}
+/**
+ * Synchronously prints at most one update line. Reads cache only — never fetches.
+ * Reaches agents (JSON mode) on stderr; stdout stays bare JSON. Throttled once per
+ * session (agent) / once per UTC day (human TTY) via O_EXCL markers. Never throws.
+ * NOTE: a session with no authenticated server call writes no cache and fires no
+ * notice; `pb doctor` live-resolves as the backstop. DEC-2.
+ */
+export function checkForUpdate(currentVersion) {
+    clearPendingUpgradeCache(currentVersion);
+    if (isVersionCheckDisabled())
+        return;
+    try {
+        const latest = resolveCachedLatest();
+        if (!latest || !isNewer(currentVersion, latest))
+            return;
+        const channel = isJsonMode() ? 'agent' : 'human';
+        if (!claimNotice(channel))
+            return;
+        const line = `${yellow('pb:')} update available — you're on ${dim(currentVersion)}, latest is ${latest}. ` +
+            `Recommended: tell your operator and run ${dim('pb upgrade')}.\n`;
+        process.stderr.write('\n' + line);
+    }
+    catch {
+        // Advisory notice — never block or crash a command.
+    }
+}
+//# sourceMappingURL=update-check.js.map

package/dist/lib/update-check.js.map

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

package/dist/lib/upgrade-runner.d.ts

@@ -0,0 +1,38 @@
+export type InstallChannel = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'unknown';
+/** Which package manager installed this pb, and for npm the global prefix it lives under. */
+export type PbInstall = {
+    channel: InstallChannel;
+    prefix?: string;
+};
+export type UpgradeCommand = {
+    channel: InstallChannel;
+    command: string;
+    args: string[];
+    display: string;
+};
+export type UpgradeResult = {
+    channel: InstallChannel;
+    command: string;
+    exitCode: number;
+    output: string[];
+};
+export type SpawnUpgradeOptions = {
+    onOutput?: (line: string) => void;
+    env?: NodeJS.ProcessEnv;
+    version?: string;
+};
+/**
+ * TEN-3308: the installer is read from where pb itself lives, never from the node binary running it.
+ * A pb under Homebrew's prefix run by a proto or nvm node was upgraded into that node's prefix, so the
+ * old pb stayed first on PATH. An npm install also names its prefix, so the new pb replaces this one.
+ */
+export declare function detectPbInstall(pbPath?: string, separator?: "/" | "\\", npmGlobalPrefix?: () => string | null): PbInstall;
+/**
+ * One shell word for the printed command (Codex P2 on #1937). The spawn passes an argv array and
+ * needs no quoting; the line a person or agent pastes does, or a prefix such as
+ * `C:\Users\Jane Doe\…` splits in two. Windows shells take double quotes, POSIX shells single quotes.
+ */
+export declare function shellWord(arg: string, platform?: NodeJS.Platform): string;
+export declare function buildUpgradeCommand({ channel, prefix }: PbInstall, version?: string, platform?: NodeJS.Platform): UpgradeCommand;
+export declare function spawnUpgrade(install?: PbInstall, options?: SpawnUpgradeOptions): Promise<UpgradeResult>;
+//# sourceMappingURL=upgrade-runner.d.ts.map

package/dist/lib/upgrade-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-runner.d.ts","sourceRoot":"","sources":["../../src/lib/upgrade-runner.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAEzE,6FAA6F;AAC7F,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAkBF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,SAAkB,EAAE,SAAS,aAAM,EAAE,eAAe,GAAE,MAAM,MAAM,GAAG,IAA0B,GAAG,SAAS,CAgBhJ;AAWD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,MAAM,CAG3F;AAOD,wBAAgB,mBAAmB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,cAAc,CAalJ;AAaD,wBAAgB,YAAY,CAC1B,OAAO,GAAE,SAA6B,EACtC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,aAAa,CAAC,CA6CxB"}

package/dist/lib/upgrade-runner.js

@@ -0,0 +1,140 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { basename, dirname, sep } from 'node:path';
+import { CLIError, ErrorCode } from './errors.js';
+import { writeUpgradePendingSentinel } from './update-check.js';
+function pathSegments(path) {
+    const segments = [];
+    let current = path;
+    while (current && current !== dirname(current)) {
+        segments.push(basename(current).toLowerCase());
+        current = dirname(current);
+    }
+    return segments;
+}
+/** The real path of the running pb script; a symlinked bin resolves to the package that holds it. */
+function runningPbPath() {
+    const script = process.argv[1] ?? '';
+    try {
+        return realpathSync(script);
+    }
+    catch {
+        return script;
+    }
+}
+/**
+ * TEN-3308: the installer is read from where pb itself lives, never from the node binary running it.
+ * A pb under Homebrew's prefix run by a proto or nvm node was upgraded into that node's prefix, so the
+ * old pb stayed first on PATH. An npm install also names its prefix, so the new pb replaces this one.
+ */
+export function detectPbInstall(pbPath = runningPbPath(), separator = sep, npmGlobalPrefix = readNpmGlobalPrefix) {
+    const segments = pathSegments(pbPath);
+    if (segments.some((s) => s.includes('pnpm')))
+        return { channel: 'pnpm' };
+    if (segments.some((s) => s.includes('yarn')))
+        return { channel: 'yarn' };
+    if (segments.some((s) => s === '.bun' || s === 'bun'))
+        return { channel: 'bun' };
+    const marker = ['', 'node_modules', '@productbrain', 'cli', ''].join(separator);
+    const at = pbPath.indexOf(marker);
+    if (at < 0)
+        return { channel: 'unknown' };
+    // Only a global install gets --prefix (Reviewer F1 on #1937): a project-local pb or an npx cache
+    // also sits under node_modules, and `npm install -g --prefix <it>` would write bin/ and lib/ there.
+    // POSIX global installs live in <prefix>/lib/node_modules; on Windows <prefix>\node_modules, and
+    // that root counts only when it is npm's own global prefix. Anything else is the plain -g line.
+    const root = pbPath.slice(0, at);
+    if (separator === '/')
+        return root.endsWith('/lib') ? { channel: 'npm', prefix: root.slice(0, -'/lib'.length) } : { channel: 'unknown' };
+    const global = npmGlobalPrefix();
+    return global && global.toLowerCase() === root.toLowerCase() ? { channel: 'npm', prefix: root } : { channel: 'unknown' };
+}
+/** npm's global prefix, asked only on Windows where the path alone cannot tell a global install from a local one. */
+function readNpmGlobalPrefix() {
+    try {
+        return execFileSync('npm', ['prefix', '-g'], { encoding: 'utf8', shell: true, timeout: 10_000 }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One shell word for the printed command (Codex P2 on #1937). The spawn passes an argv array and
+ * needs no quoting; the line a person or agent pastes does, or a prefix such as
+ * `C:\Users\Jane Doe\…` splits in two. Windows shells take double quotes, POSIX shells single quotes.
+ */
+export function shellWord(arg, platform = process.platform) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(arg))
+        return arg;
+    return platform === 'win32' ? `"${arg.replace(/"/g, '""')}"` : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+/** The only builder of the display line: the same argv the spawn runs, each word quoted for a shell. */
+function upgradeCommand(channel, command, args, platform) {
+    return { channel, command, args, display: [command, ...args].map((a) => shellWord(a, platform)).join(' ') };
+}
+export function buildUpgradeCommand({ channel, prefix }, version, platform = process.platform) {
+    const spec = version ? `@productbrain/cli@${version}` : '@productbrain/cli@beta';
+    switch (channel) {
+        case 'pnpm':
+            return upgradeCommand(channel, 'pnpm', ['add', '-g', spec], platform);
+        case 'yarn':
+            return upgradeCommand(channel, 'yarn', ['global', 'add', spec], platform);
+        case 'bun':
+            return upgradeCommand(channel, 'bun', ['add', '-g', spec], platform);
+        case 'npm':
+        case 'unknown':
+            return upgradeCommand(channel, 'npm', ['install', '-g', ...(prefix ? ['--prefix', prefix] : []), spec], platform);
+    }
+}
+function failureGuidance(message) {
+    const lower = message.toLowerCase();
+    if (lower.includes('eacces') || lower.includes('permission denied')) {
+        return 'Permission denied during global install. Use a Node version manager, fix the global npm prefix, or rerun the install command with the permissions your system requires.';
+    }
+    if (process.platform === 'win32' && (lower.includes('eperm') || lower.includes('busy') || lower.includes('locked'))) {
+        return 'Windows could not replace the active pb executable. Close terminals running pb, then rerun the upgrade command.';
+    }
+    return 'Run the displayed upgrade command manually, then retry pb doctor.';
+}
+export function spawnUpgrade(install = detectPbInstall(), options = {}) {
+    const spec = buildUpgradeCommand(install, options.version);
+    const output = [];
+    return new Promise((resolve, reject) => {
+        const child = spawn(spec.command, spec.args, {
+            env: options.env ?? process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const emit = (chunk) => {
+            const text = chunk.toString();
+            for (const line of text.split(/\r?\n/).filter(Boolean)) {
+                output.push(line);
+                options.onOutput?.(line);
+            }
+        };
+        child.stdout?.on('data', emit);
+        child.stderr?.on('data', emit);
+        child.on('error', (err) => {
+            const message = err.message || `Failed to spawn ${spec.display}`;
+            reject(new CLIError(`Upgrade failed: ${message}`, {
+                code: ErrorCode.UPGRADE_FAILED,
+                category: 'internal',
+                guidance: failureGuidance(message),
+            }));
+        });
+        child.on('close', (code) => {
+            const exitCode = code ?? 1;
+            if (exitCode !== 0) {
+                const message = output.slice(-4).join('\n') || `${spec.display} exited with code ${exitCode}`;
+                reject(new CLIError(`Upgrade failed: ${message}`, {
+                    code: ErrorCode.UPGRADE_FAILED,
+                    category: 'internal',
+                    guidance: failureGuidance(message),
+                }));
+                return;
+            }
+            writeUpgradePendingSentinel(options.version);
+            resolve({ channel: spec.channel, command: spec.display, exitCode, output });
+        });
+    });
+}
+//# sourceMappingURL=upgrade-runner.js.map

package/dist/lib/upgrade-runner.js.map

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

package/dist/lib/workPackageList.d.ts

@@ -0,0 +1,138 @@
+/** What orient adds to a row: the stored priority token (absent for No priority) and, on a team list only,
+ *  yours when the seat's role owns the package. */
+export type WorkPackageListMarks = {
+    priority?: string;
+    yours?: true;
+};
+/** Served only on a team list: the team's live packages, the live packages exactly one other team owns, and
+ *  the live packages with no owner or two or more (they belong to no team), so the three add up to the live total. */
+export type WorkPackageTeamCounts = {
+    team: number;
+    otherTeams: number;
+    noSingleOwner: number;
+};
+export declare const WORK_PACKAGE_LIST_WORDS: {
+    readonly yours: "[yours]";
+    /** Printed once under the heading when a row carries the mark, so a cold reader need not guess it (DEC-2445). */
+    readonly legend: "[yours] = a package your role owns";
+    readonly count: (shown: number, { team, otherTeams, noSingleOwner }: WorkPackageTeamCounts, allCommand: string) => string;
+    /** The command each surface names at the end of the count line: every live work package of the workspace, under listHeading. */
+    readonly allCommand: {
+        readonly cli: "pb brief confidence";
+        readonly mcp: "`context action=brief briefType=\"confidence\"`";
+    };
+    /** The heading of that command's list, so the count line and the list use one word. */
+    readonly listHeading: "Live work packages";
+    /** That list's last line when it stopped at its cap; the brief has no way to continue past it. */
+    readonly listStops: (cap: number) => string;
+    /** A tension linked to a row, named and with its id so a reader can open it; each surface adds its own indent. */
+    readonly tension: (t: {
+        entryId: string | null;
+        name: string;
+    }) => string;
+    readonly setOne: "Set one (urgent, high, medium or low):";
+    /** The command each surface prints after setOne, ending the line so it pastes whole; a live priority change asks one line of why (DEC-2418). */
+    readonly setCommand: {
+        readonly cli: "pb update <WP-ID> -f priority=high --change-reason \"<why>\"";
+        readonly mcp: "`entries action=update entryId=\"<WP-ID>\" data={\"priority\":\"high\"} changeReason=\"<why>\"`";
+    };
+};
+/** The level word a row is listed under: one of the five, No priority for anything else. */
+export declare function priorityWord(value: unknown): string;
+export type WorkPackageListSurface<R> = {
+    /** The row's own lines; `mark` is the yours mark with its leading space, or ''. */
+    row: (row: R, mark: string) => string[];
+    heading: (word: string) => string;
+    /** The surface's command from WORK_PACKAGE_LIST_WORDS.setCommand, printed after setOne. */
+    setCommand: string;
+    /** The surface's command from WORK_PACKAGE_LIST_WORDS.allCommand, ending the count line. */
+    allCommand: string;
+};
+/**
+ * Rows arrive in orient's order (priority first). With no counts (no team bound) and no priority on any
+ * row, the lines are exactly the rows: the list a session saw before priorities existed. A heading is
+ * printed for each level present once any row has a priority; a team list leads with the count line,
+ * the yours legend when a row is marked, and the Set one hint when none of its rows has a priority.
+ */
+export declare function workPackageListLines<R extends WorkPackageListMarks>(rows: readonly R[], counts: WorkPackageTeamCounts | undefined, surface: WorkPackageListSurface<R>): string[];
+/** One open task a role owns outside a live package (DEC-2459): the stored priority token (absent for No priority), in progress
+ *  only on that stage, no owner only on the Team Lead's list for a task no role owns, packageClosed when its only packages are closed. */
+export type OpenTaskRow = {
+    entryId: string;
+    name: string;
+    priority?: string;
+    inProgress?: true;
+    noOwner?: true;
+    packageClosed?: true;
+};
+/** The read's answer: the role, its rows in the one order (priority, stage, last updated), and whether the read stopped at
+ *  its cap; `cappedAt` is how many records it had read when it stopped. */
+export type OpenTaskList = {
+    role: {
+        entryId: string | null;
+        name: string;
+    };
+    rows: OpenTaskRow[];
+    capped: boolean;
+    cappedAt?: number;
+};
+/** What orient serves: the first `shown` rows of the read, and how many it found in all, so the cut note can count the rest. */
+export type OrientOpenTasks = OpenTaskList & {
+    total: number;
+};
+/** The surface a list prints on: it picks the command below. */
+export type OpenTaskSurface = 'cli' | 'mcp';
+/** The words of a role's open-task list (DEC-2459, shaped by Product Design 2026-10-30): orient and the tasks list alike. */
+export declare const OPEN_TASK_LIST_WORDS: {
+    readonly heading: (roleName: string) => string;
+    readonly separator: " · ";
+    readonly inProgress: "(in progress)";
+    readonly noOwner: "(no owner)";
+    /** After a task whose package parents are all done or archived, so the agent finishes it or closes it (Product Design 2026-10-30). */
+    readonly packageClosed: "(its package is closed)";
+    /** Orient shows at most this many rows; the cut note names the command for the rest. */
+    readonly shown: 5;
+    readonly more: (hidden: number, capped: boolean, allCommand: string) => string;
+    readonly allCommand: {
+        readonly cli: "pb tasks list";
+        readonly mcp: "`context action=tasks`";
+    };
+    readonly compact: (count: number, capped: boolean, roleName: string) => string;
+    /** Only for a read that was not cut: a capped read that found none prints its capped line instead, never this. */
+    readonly empty: (roleName: string) => string;
+    /** The tasks list's last line when another page follows. */
+    readonly nextPage: (command: string) => string;
+    /** Printed whenever the read stopped at its cap, so rows it never read are not taken for none (signed by Voice, 2026-10-30).
+     *  The read goes newest ownership first, so what it leaves out is what the role has owned longest. */
+    readonly capped: (records: number) => string;
+    /** The read's refusal when no role is named and the session acts in none; each surface adds noRole with its own command. */
+    readonly noSessionRole: "This session acts in no role.";
+    readonly noRole: (command: string) => string;
+    /** A cursor that is not a page number; the CLI refuses it rather than reading page 1. */
+    readonly badCursor: (value: string) => string;
+};
+/** Each surface's command with its role and cursor inputs, built from allCommand so it is spelled once. */
+export declare function openTaskCommand(surface: OpenTaskSurface, input?: {
+    role?: string;
+    cursor?: number;
+}): string;
+/** `<priority word> · <TASK-id> — <name>`, then the in-progress, no-owner and package-closed marks; each surface adds its own bullet. */
+export declare function openTaskRowText(row: OpenTaskRow): string;
+/** The rows under the heading: at most `shown` (all when absent), then the cut note when rows were left out, then the
+ *  capped line whenever the read stopped at its cap; the cut note's count then reads "n+", since rows past the cap were never read. */
+export declare function openTaskListLines(list: OpenTaskList, surface: {
+    bullet: string;
+    surface: OpenTaskSurface;
+    shown?: number;
+    total?: number;
+}): string[];
+/** Orient's section: nothing when the role owns none and the read was not cut (a cut read that found none still prints the heading
+ *  and its capped line, never silence); otherwise the heading, at most `shown` rows, the cut note and the capped line. */
+export declare function openTaskSectionLines(list: OrientOpenTasks | undefined, surface: {
+    heading: (text: string) => string;
+    bullet: string;
+    surface: OpenTaskSurface;
+}): string[];
+/** Orient's compact count, on the same guard as the section. */
+export declare function openTaskCompactLines(list: OrientOpenTasks | undefined): string[];
+//# sourceMappingURL=workPackageList.d.ts.map

package/dist/lib/workPackageList.d.ts.map

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