@vecteur/cli 0.7.1 → 0.9.0

package/src/tui/view.js

@@ -0,0 +1,319 @@
+import stringWidth from "string-width";
+import wrapAnsi from "wrap-ansi";
+import { parseMarkdown } from "../markdown.js";
+import { terminalText } from "../format.js";
+const style = (value, code, color) => color ? `\x1b[${code}m${value}\x1b[0m` : value;
+// One accent (the web's sky cyan, xterm 81), one secondary grey; amber only for attention.
+const ACCENT = "38;5;81", DIM = "90", ATTENTION = "33";
+const SPINNER = ["·", "✢", "✳", "✶", "✻", "✽", "✻", "✶", "✳", "✢"];
+const printableAscii = /^[\x20-\x7e]*$/;
+const measure = value => printableAscii.test(value) ? value.length : stringWidth(value);
+const wrapped = new Map();
+const wrap = (value, width, wordWrap = true) => {
+  width = Math.max(1, width);
+  const key = value.length <= 512 ? `${width}:${wordWrap}:${value}` : null;
+  if (key && wrapped.has(key)) return wrapped.get(key);
+  const lines = !value.includes("\n") && measure(value) <= width ? [value]
+    : wrapAnsi(value, width, { hard: true, trim: false, wordWrap }).split("\n");
+  if (key) {
+    if (wrapped.size === 128) wrapped.delete(wrapped.keys().next().value);
+    wrapped.set(key, lines);
+  }
+  return lines;
+};
+// Prose wraps at word boundaries and drops the break's leading space; the composer keeps every space.
+const prose = (value, width) => wrapAnsi(value, Math.max(1, width), { hard: true, trim: true }).split("\n");
+const pad = (value, width) => value + " ".repeat(Math.max(0, width - measure(value)));
+
+function inline(tokens, color) {
+  return tokens.map(token => {
+    const href = token.href && /^https?:\/\//i.test(token.href) ? ` <${token.href}>` : "";
+    const value = token.text + href;
+    return token.kind === "strong" ? style(value, "1", color)
+      : token.kind === "em" ? style(value, "3", color)
+        : token.kind === "code" ? style(value, ACCENT, color)
+          : token.kind === "link" ? style(value, "4", color) : value;
+  }).join("");
+}
+
+const numeric = /^[-+−~≈<>≤≥±]?\s?\d[\d.,]*(?:\s?[^\s\d]\S*)?$/;
+function table(block, width, color) {
+  const grid = [block.header, ...block.rows].map(row => row.map(cell => inline(cell, false)));
+  const columns = Math.max(...grid.map(row => row.length));
+  const widths = Array.from({ length: columns }, (_, i) => Math.max(1, ...grid.map(row => measure(row[i] ?? ""))));
+  if (widths.reduce((a, b) => a + b, 0) + 3 * (columns - 1) > width) {
+    // Too wide for the terminal: one record per row, never a clipped column.
+    const lines = [];
+    block.rows.forEach((row, index) => {
+      lines.push(style(`Record ${index + 1}`, "1", color));
+      row.forEach((cell, column) => lines.push(...wrap(`${style(grid[0]?.[column] || `Column ${column + 1}`, DIM, color)}  ${inline(cell, color)}`, width)));
+    });
+    return lines;
+  }
+  const right = widths.map((_, i) => block.rows.length > 0 && block.rows.every(row => numeric.test(inline(row[i] ?? [], false).trim() || "0")));
+  const cell = (value, i) => right[i] ? " ".repeat(Math.max(0, widths[i] - measure(value))) + value : pad(value, widths[i]);
+  const bar = style(" │ ", DIM, color);
+  return [style(grid[0].map((value, i) => pad(value, widths[i])).join(" │ "), "1", color),
+    style(widths.map(w => "─".repeat(w)).join("─┼─"), DIM, color),
+    ...grid.slice(1).map(row => widths.map((_, i) => cell(row[i] ?? "", i)).join(bar))];
+}
+
+/** Shared web grammar; only trusted renderer styling can emit terminal controls. */
+export function markdownView(source, width, color = true) {
+  const lines = [];
+  for (const block of parseMarkdown(terminalText(source))) {
+    if (block.kind === "table") lines.push(...table(block, width, color));
+    else if (block.kind === "codeblock") {
+      if (block.language) lines.push(style(block.language, DIM, color));
+      lines.push(...wrap(block.text, width - 2, false).map(line => style("│ ", DIM, color) + line));
+    } else if (block.kind === "hr") {
+      lines.push(style("─".repeat(Math.min(width, 48)), DIM, color));
+    } else if (block.kind === "list") {
+      block.items.forEach((item, index) => {
+        const prefix = block.ordered ? `${index + 1}. ` : "• ";
+        prose(inline(item, color), width - prefix.length).forEach((line, i) => lines.push((i ? " ".repeat(prefix.length) : style(prefix, DIM, color)) + line));
+      });
+    } else {
+      let value = inline(block.inline, color);
+      if (block.kind === "heading") value = style(value, block.level <= 2 ? `1;${ACCENT}` : "1", color);
+      if (block.kind === "quote") lines.push(...prose(value, width - 2).map(line => style("│ ", DIM, color) + line));
+      else lines.push(...prose(value, width));
+    }
+    lines.push("");
+  }
+  while (lines.at(-1) === "") lines.pop();
+  return lines.join("\n");
+}
+
+// One terminal owns this cache. Cursor movement never rewraps unrelated paragraphs.
+let composerText;
+const composerLayouts = new Map();
+function composerViewport(composer, cursor, width, height) {
+  if (composerText !== composer) { composerLayouts.clear(); composerText = composer; }
+  let composerLayout = composerLayouts.get(width);
+  if (!composerLayout) {
+    const paragraphs = [], lines = []; let offset = 0;
+    for (const text of composer.split("\n")) {
+      paragraphs.push({ text, offset, row: lines.length });
+      lines.push(...wrap(terminalText(text), width, false)); offset += text.length + 1;
+    }
+    composerLayout = { paragraphs, lines };
+    if (composerLayouts.size === 3) composerLayouts.delete(composerLayouts.keys().next().value);
+    composerLayouts.set(width, composerLayout);
+  }
+  const { paragraphs, lines } = composerLayout;
+  const paragraph = paragraphs.findLast(row => row.offset <= cursor) ?? paragraphs[0];
+  const local = cursor - paragraph.offset;
+  const before = terminalText(paragraph.text.slice(0, local));
+  const active = wrap(before + "▌" + terminalText(paragraph.text.slice(local)), width, false);
+  const cursorRow = paragraph.row + wrap(before + "▌", width, false).length - 1;
+  const start = Math.max(0, cursorRow - height + 1);
+  const next = paragraphs[paragraphs.indexOf(paragraph) + 1]?.row ?? lines.length;
+  const visible = start < paragraph.row ? lines.slice(start, paragraph.row) : [];
+  visible.push(...active.slice(Math.max(0, start - paragraph.row)), ...lines.slice(next, next + height));
+  return { lines: visible.slice(0, height), position: `Line ${paragraphs.indexOf(paragraph) + 1}/${paragraphs.length}`,
+    scrolling: lines.length > height };
+}
+
+/** One rounded box, the same frame as the prompt: a label may sit in the top or bottom border. */
+function box(rows, width, color, { top = "", bottom = "" } = {}) {
+  const inner = Math.max(1, width - 4);
+  const edge = (left, label, right) => {
+    const text = label ? `─ ${trimEnd(label, inner - 2)} ` : "";
+    return style(left + text + "─".repeat(Math.max(0, width - 2 - measure(text))) + right, DIM, color);
+  };
+  return [edge("╭", top, "╮"), ...rows.map(row => `${style("│", DIM, color)} ${row}${" ".repeat(Math.max(0, inner - measure(row)))} ${style("│", DIM, color)}`),
+    edge("╰", bottom, "╯")];
+}
+
+/** The once-printed welcome: one calm box, a single accent glyph, no ASCII logo. */
+export function welcome(version, origin, columns = 80, color = true, channel, folder) {
+  const width = Math.max(20, columns - 1), inner = width - 4;
+  const label = `${version}${channel === "preview" ? " · Preview" : ""}`;
+  const where = [folder, origin === "https://vecteur.space" ? "" : origin].filter(Boolean).map(terminalText).join(" · ");
+  const head = `${style("▼", ACCENT, color)} ${style("Vecteur", "1", color)} ${style(label, DIM, color)}`;
+  const lines = measure(`▼ Vecteur ${label} · Laplace · Vecteur cloud`) <= inner
+    ? [`${head} ${style("· Laplace · Vecteur cloud", DIM, color)}`] : [head];
+  if (where) lines.push(style(trimEnd(`  ${where}`, inner), DIM, color));
+  return box(lines, width, color).join("\n") + "\n";
+}
+
+// Display-cell truncation with an ellipsis; never more work than the visible width needs.
+function trimEnd(value, max) {
+  const safe = terminalText(value);
+  if (measure(safe) <= max) return safe;
+  const chars = [...safe].slice(0, Math.max(0, max));
+  while (chars.length && measure(chars.join("")) > max - 1) chars.pop();
+  return chars.join("") + "…";
+}
+
+function trimStart(value, max) {
+  const safe = terminalText(value);
+  if (measure(safe) <= max) return safe;
+  const chars = [...safe].slice(-Math.max(1, max));
+  while (chars.length && measure(chars.join("")) > max - 1) chars.shift();
+  return "…" + chars.join("");
+}
+
+/** Bottom-anchored live area: activity, focus, the prompt box, then one or two footer lines. */
+export function richFrame(view, composer, cursor, { columns = 80, rows = 24, color = true, tick = null } = {}) {
+  const width = Math.max(20, columns - 1), budget = Math.max(1, rows - 3);
+  const active = !!view.run?.subject && !view.run.terminal;
+  const readOnly = view.project?.role === "VIEWER", signedOut = view.offline || !view.account;
+  const glyph = tick === null ? "●" : SPINNER[tick % SPINNER.length];
+  const runHint = readOnly ? "Read-only · /help · Ctrl+D detach"
+    : signedOut ? `${view.offline ? "/resume" : "/login"} · /help · Ctrl+D detach`
+      : `${view.run?.question ? "/answer" : "/steer · /answer-now"} · /help${width < 60 ? "\n" : " · "}Esc twice cancel · Ctrl+D detach`;
+  if (rows < 12) {
+    const focus = view.focus ?? view.prompt;
+    const choices = view.choices ?? focus?.options ?? view.palette ?? [];
+    const selected = Math.min(view.selected ?? view.paletteSelected ?? 0, Math.max(0, choices.length - 1));
+    const choice = choices[selected];
+    const content = focus?.title ?? (view.login ? `Sign in · Code ${view.login.user_code}` : view.issue?.text
+      ?? (active ? `${view.run.elapsed ?? "Elapsed unavailable"} · ${view.status}` : view.status));
+    const status = wrap(terminalText(content), width).slice(0, 1);
+    if (choice) status.push(wrap(terminalText(`› ${selected + 1}/${choices.length} ${choice.label ?? '/' + choice.name}`), width)[0]);
+    else if (view.login) status.push(['› Open browser', '› Copy link', '› Work offline'][view.loginAction ?? 0]);
+    const draft = composerViewport(composer, cursor, width - 2, 1).lines[0];
+    const hint = focus || choices.length ? '↑↓ Enter choose · Esc back' : view.login ? 'Tab actions · Enter open · Esc offline'
+      : active ? runHint : '? keys · /help · Ctrl+D exit';
+    return [...status, `${style("›", ACCENT, color)} ${draft}`, ...wrap(style(hint, DIM, color), width).slice(0, 2)].slice(0, budget).join("\n");
+  }
+  if (rows < 8) return wrap(`${view.status} · Ctrl+D exit`, width).slice(0, budget).join("\n");
+  const project = view.projectLabel ?? view.project?.name ?? "New Project on first send";
+  // The steady footer names the Workspace, never a personal address; /status shows the account.
+  const workspaces = view.account?.workspaces ?? [];
+  const account = view.account ? (workspaces.find(row => row.id === view.project?.workspace_id) ?? workspaces[0])?.name ?? "Signed in"
+    : view.offline ? "Offline" : "Not signed in";
+  const compact = width < 60 || rows < 18;
+  const prompt = view.focus ?? view.prompt;
+  const compactFocus = rows < 24 && (view.focus || view.prompt || view.login || view.palette?.length || view.issue);
+  const compactRun = rows < 18 && active;
+
+  // Footer first: it is what keeps every state escapable, so the rest fits around it.
+  const hint = prompt ? prompt.multiple ? "Space toggle · ↑↓ move · Enter confirm · Esc back" : "↑↓ choose · Enter confirm · Esc back · Ctrl+D exit"
+    : view.login ? "Tab actions · Enter on empty activates · Esc offline"
+      : view.palette?.length ? "↑↓ choose · Tab complete · Enter open · Esc close"
+        : active ? runHint
+          : `${readOnly ? "Read-only · /project" : signedOut ? "Enter sign in" : view.busy ? "Please wait" : "Enter send"}`
+            + (width < 60 ? " · /help · Ctrl+D exit" : " · Alt+Enter newline · / commands · ? keys · /help · Ctrl+D exit");
+  const execution = view.location && view.location !== "Vecteur cloud" ? view.location : "Cloud";
+  const context = `${view.lead ? `${view.lead} · ` : ""}${view.model} · ${execution}`;
+  const footer = wrap(style(hint, DIM, color), width - 1).slice(0, 2).map(line => " " + line);
+  const identity = trimEnd(`${project === "New Project on first send" ? "New Project" : project} · ${account}`, width);
+  const where = trimStart(view.folder ?? ".", Math.max(6, width - measure(identity) - measure(context) - 7));
+  const left = where === "." ? identity : `${identity} · ${where}`;
+  if (!compact && measure(left) + measure(context) + 4 <= width) {
+    footer.push(" " + style(left + " ".repeat(width - 2 - measure(left) - measure(context)) + context, DIM, color));
+  } else {
+    footer.push(" " + style(trimEnd(context, width - 1), DIM, color));
+    if (!compact && !compactFocus) footer.push(" " + style(trimEnd(left, width - 1), DIM, color));
+  }
+  if (view.origin && view.origin !== "https://vecteur.space") footer.push(" " + style(trimEnd(view.origin, width - 1), ACCENT, color));
+
+  // A breathing line between the scrollback and the live area when the window has room for it.
+  const lines = rows >= 18 && !compactFocus ? [""] : [];
+  const room = () => budget - footer.length - 3 - lines.length;
+  const line = (value, code, limit = 2) => {
+    const text = terminalText(value);
+    lines.push(...wrap(code ? style(text, code, color) : text, width).slice(0, Math.max(0, Math.min(limit, room()))));
+  };
+  // Activity: the one animated glyph, the current step and the server-anchored clock.
+  if (active && !compactFocus) {
+    const clock = view.run.elapsed ?? "Elapsed unavailable";
+    const doing = compactRun ? view.status : (view.run.progress || "Working").replace(/^Starting: (.+)$/, "$1") + "…";
+    const head = `${style(glyph, ACCENT, color)} ${terminalText(doing)}`, tail = style(terminalText(clock), DIM, color);
+    if (measure(`${glyph} ${terminalText(doing)} · ${terminalText(clock)}`) <= width) lines.push(`${head} ${style("·", DIM, color)} ${tail}`);
+    else if (compactRun) lines.push(wrap(head, width)[0], `  ${tail}`);
+    else lines.push(wrap(`${style(glyph, ACCENT, color)} ${tail} · ${terminalText(doing)}`, width)[0]);
+    if (!compactRun && view.status && view.status !== "Running") line(view.status, DIM, 1);
+  }
+  if (!compactFocus && !compactRun && view.run?.question) line(readOnly ? "Waiting for an editor to answer"
+    : signedOut ? "Question pending — reconnect to answer" : "Your answer is needed · /answer", `1;${ATTENTION}`, 1);
+  if (prompt) {
+    line(prompt.title, "1", compactFocus ? 1 : 3);
+    if (!prompt.typed) {
+      const choices = view.choices ?? prompt.options, selected = Math.min(view.selected ?? 0, Math.max(0, choices.length - 1));
+      const more = choices.length > 1 && !compactFocus ? 1 : 0;
+      const count = Math.max(1, Math.min(5, room() - more));
+      const offset = Math.max(0, selected - count + 1);
+      choices.slice(offset, offset + count).forEach((item, i) => {
+        const index = prompt.options.indexOf(item) + 1, current = i + offset === selected;
+        const checked = prompt.multiple ? `${composer.split(/[, ]+/).includes(String(index)) ? "[x]" : "[ ]"} ` : "";
+        lines.push(wrap(`${current ? style("›", ACCENT, color) : " "} ${index}. ${checked}${current ? style(terminalText(item.label), ACCENT, color) : terminalText(item.label)}`, width)[0]);
+      });
+      if (!choices.length) line("No matching choices; clear the filter", ATTENTION, 1);
+      if (choices.length > count && more) line(`${selected + 1}/${choices.length} · ↑↓ more choices`, DIM, 1);
+    }
+  } else if (view.login) {
+    line(`Approve code ${view.login.user_code} in your browser`, "1", 1);
+    if (!compactFocus) line(view.login.verification_uri_complete, ACCENT, 2);
+    const actions = ["Open browser", "Copy link", "Work offline"];
+    line(compactFocus ? `› ${actions[view.loginAction ?? 0]} (${(view.loginAction ?? 0) + 1}/3)`
+      : actions.map((text, i) => `${i === view.loginAction ? "› " : ""}${text}`).join(" · "), undefined, compactFocus ? 1 : 2);
+  } else if (view.palette?.length) {
+    const selected = Math.min(view.paletteSelected ?? 0, view.palette.length - 1);
+    const count = Math.max(1, Math.min(6, room()));
+    const offset = Math.max(0, selected - count + 1);
+    const name = Math.min(16, Math.max(...view.palette.map(row => row.name.length + 1)));
+    view.palette.slice(offset, offset + count).forEach((row, i) => {
+      const current = i + offset === selected, label = pad(`/${row.name}`, name);
+      lines.push(wrap(`${current ? style("›", ACCENT, color) : " "} ${current ? style(label, ACCENT, color) : label}  ${style(terminalText(row.disabled || row.description), DIM, color)}`, width)[0]);
+    });
+  }
+  const compactAttachments = rows < 24 && view.attachments?.length;
+  if (view.attachments?.length && !compactAttachments) line(`${view.attachments.length} file(s) selected · uploaded only on send`, DIM, 1);
+  if (view.issue && !prompt) line(view.issue.text + (view.issue.count > 1 ? ` (${view.issue.count} attempts)` : ""), ATTENTION, Math.max(1, Math.min(3, room())));
+  if (!active && !view.issue && !prompt && !view.login && !view.palette?.length) line(view.status, DIM, 1);
+  const maxDraft = Math.max(1, Math.min(6, budget - lines.length - footer.length - 2));
+  const draft = composerViewport(composer, cursor, width - 6, maxDraft);
+  const selection = compactAttachments ? `${view.attachments.length} file(s) · upload on send` : "";
+  const placeholder = prompt ? (prompt.typed ? "Type your answer…" : "Filter or type a choice number…")
+    : readOnly ? "Read-only Project — draft here…" : view.offline ? "Draft offline…"
+      : !view.account ? "Sign in to send — draft here…"
+        : active ? "Draft your next question…" : "Ask Laplace…";
+  lines.push(...box(draft.lines.map((value, index) => `${index ? "  " : style("›", ACCENT, color) + " "}${composer ? value : style("▌" + placeholder, DIM, color)}`),
+    width, color, { top: selection, bottom: draft.scrolling ? draft.position : "" }));
+  lines.push(...footer);
+  return lines.slice(-budget).join("\n");
+}
+
+const indent = (text, first, rest = "  ") => text.split("\n").map((line, i) => (i ? (line ? rest : "") : first) + line).join("\n");
+
+/** One scrollback block per message: the ask, the answer with its record, or a quiet notice. */
+export function richMessage(message, columns, color, { stepsShown = false } = {}) {
+  const width = Math.max(20, columns - 1);
+  if (message.kind === "user") {
+    return "\n" + indent(wrap(terminalText(message.text), width - 2).join("\n"), style("›", ACCENT, color) + " ") + "\n";
+  }
+  if (message.kind === "step") return style(trimEnd(`  ⎿ ${message.text}`, width), DIM, color);
+  if (message.kind === "cost") {
+    const display = message.value?.display ?? {};
+    const parts = [["Used", display.used], ["Limit", display.limit], ["Remaining", display.remaining]].filter(([, v]) => v !== null && v !== undefined);
+    return style(trimEnd(`  Usage this UTC month · ${parts.length ? parts.map(([k, v]) => `${k} ${v}`).join(" · ") : "no exact amount available"} · /usage`, width), DIM, color);
+  }
+  if (message.kind !== "answer") return wrap(terminalText(message.text), width - 2).map(line => "  " + line).join("\n");
+  const run = message.sections;
+  if (!run) return "\n" + indent(markdownView(message.text, width - 2, color), style("●", ACCENT, color) + " ") + "\n";
+  const out = [];
+  out.push(run.answer !== undefined ? indent(markdownView(run.answer, width - 2, color), style("●", ACCENT, color) + " ")
+    : style("●", ATTENTION, color) + " No answer was published for this Run.");
+  const section = (title, rows) => { if (rows.length) out.push("", "  " + style(title, DIM, color), ...rows); };
+  const one = text => text.split("\n").map(part => part.trim()).filter(Boolean).join(" · ");
+  section("Steps", run.tasks.slice(stepsShown).map(task => style(trimEnd(`  ⎿ ${one(task.replace(/^\s*[▸·]\s*/, ""))}`, width), DIM, color)));
+  // Evidence rows are never truncated: quantity, unit and origin wrap with a hanging indent.
+  const full = (row, code = DIM) => prose(terminalText(row.trim()), width - 4).map((part, i) => (i ? "    " : "  ") + style(part, code, color));
+  section("Inputs and origins", run.origins.flatMap(row => full(row)));
+  section("Assumptions", run.assumptions.flatMap(row => full(row)));
+  section("Transfer tables", run.tables.flatMap(rows => rows.flatMap(row => full(row))));
+  // Up to three files, readable names before digest-named ones; numbers stay the /download numbers.
+  const numbered = run.artifacts.map((row, i) => ({ ...row, number: i + 1 }));
+  const digest = row => /^[0-9a-f]{32,}\./.test(row.artifact.filename);
+  const shown = [...numbered.filter(row => !digest(row)), ...numbered.filter(digest)].slice(0, 3);
+  const more = run.artifacts.length - shown.length;
+  section("Files", shown.flatMap(({ artifact, number }) => prose(`${terminalText(artifact.filename)} ${style(`· ${artifact.kind} · /download ${number}`, DIM, color)}`, width - 4)
+    .map((part, i) => `  ${i ? " " : style("↓", ACCENT, color)} ${part}`))
+    .concat(more > 0 ? [style(`  … ${more} more · /files`, DIM, color)] : []));
+  out.push("", ...full(run.tail.map(terminalText).join(" · "), run.state === "ok" ? DIM : ATTENTION));
+  return "\n" + out.join("\n") + "\n";
+}

package/src/update.js

@@ -0,0 +1,313 @@
+import { constants, accessSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readdirSync, readlinkSync, symlinkSync, renameSync, unlinkSync, writeFileSync, openSync, closeSync, fsyncSync, statfsSync } from "node:fs";
+import { dirname, join, resolve, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash, randomUUID } from "node:crypto";
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { CliError, VecteurClient, resolveOrigin } from "./client.js";
+import { preferences, savePreferences } from "./preferences.js";
+import { terminalText } from "./format.js";
+import { credentialsPath } from "./credentials.js";
+import { writeStore, readStore } from "./store.js";
+
+const run = promisify(execFile), REGISTRY = "https://registry.npmjs.org", PACKAGE = "@vecteur/cli";
+const ownRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const manifest = root => JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+const fail = (code, text) => { throw new CliError(code, text); };
+const MAX_BYTES = 512 * 1024 * 1024;
+const official = origin => origin === "https://vecteur.space";
+const versionCompare = (a, b) => {
+  const aa = a.split(".").map(Number), bb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if (aa[i] !== bb[i]) return aa[i] - bb[i];
+  return 0;
+};
+function owned(path, directory = false) {
+  const stat = lstatSync(path);
+  return (!directory || stat.isDirectory()) && !stat.isSymbolicLink()
+    && (!process.getuid || stat.uid === process.getuid()) && !(stat.mode & 0o022);
+}
+function pathBinary(env) {
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
+    const file = resolve(dir, process.platform === "win32" ? "vecteur.cmd" : "vecteur");
+    try { accessSync(file, constants.X_OK); return file; } catch {}
+  }
+  return null;
+}
+/** Inspect paths only. Never execute the other PATH binary, even for its version. */
+export function installation({ entry = process.argv[1], env = process.env, root = ownRoot } = {}) {
+  const launcher = resolve(entry), realEntry = realpathSync(launcher), pkg = manifest(root);
+  const pointer = lstatSync(launcher);
+  const identity = [pointer.dev, pointer.ino, pointer.mtimeMs, pointer.size];
+  let path = pathBinary(env), pathVersion = null;
+  try { const other = manifest(resolve(dirname(realpathSync(path)), "..")); if (other.name === PACKAGE) pathVersion = other.version; } catch {}
+  const parent = dirname(launcher);
+  // The pointer is outside every immutable npm generation. A direct JS path is never replaced.
+  const prefix = parent.endsWith("/node_modules/.bin") ? resolve(parent, "../..")
+    : parent.endsWith("/bin") ? dirname(parent) : null;
+  let reason = "Direct script or unmanaged installation; use its package manager";
+  if (launcher.includes("/.vecteur-updates/generation-")) reason = "Launch this installation through its original launcher; retained generation files stay immutable";
+  else if (process.platform === "win32") reason = "Windows launcher recovery has not been qualified; use npm explicitly";
+  else if (process.env.NODE_OPTIONS || process.env.NODE_PATH || process.execArgv.length) reason = "Custom Node options/loaders: automatic replacement is unavailable";
+  else if (prefix && lstatSync(launcher).isSymbolicLink() && realEntry === join(realpathSync(root), "bin/vecteur.js")) {
+    try {
+      if (!owned(parent, true) || !owned(prefix, true) || !owned(realEntry) || !owned(root, true)) throw new Error();
+      accessSync(parent, constants.W_OK); accessSync(prefix, constants.W_OK);
+      reason = "";
+    } catch { reason = "Installation is not a writable, user-owned npm prefix"; }
+  }
+  const key = createHash("sha256").update(launcher).digest("hex");
+  return { launcher, realEntry, identity, root, prefix, version: pkg.version, channel: pkg.vecteur?.channel ?? "unknown", node: process.execPath,
+    path, pathVersion, reason, qualified: !reason, key };
+}
+export function installationText(info) {
+  return [`Running: ${info.launcher} (${info.version})`, `Resolved: ${info.realEntry}`, `Node: ${info.node}`,
+    info.path && info.path !== info.launcher ? `PATH: ${info.path} (${info.pathVersion ?? "version unknown"}); updating it does not change the running installation.` : "PATH selects this launcher.",
+    info.pathVersion && info.pathVersion !== info.version ? `To use the PATH installation: ${quote(info.path)}` : "",
+    info.reason || "Update layout: npm launcher with retained immutable generations"].filter(Boolean).join("\n");
+}
+function manualRecovery(plan) {
+  const { info, release } = plan;
+  if (info.pathVersion && info.pathVersion === (release.cli?.version ?? release.requiredVersion) && info.path !== info.launcher) return `Launch the matching installed CLI: ${quote(info.path)}`;
+  if (!release.cli) return "Use /offline to keep drafting; this older origin supplies no structured update pin.";
+  if (!info.prefix) return `Unmanaged checkout: use its build/package instructions. Offline launch: ${quote(info.launcher)} --offline`;
+  const global = dirname(info.launcher).endsWith("/bin");
+  return `Manual npm recovery for this prefix (close its clients first): npm install ${global ? "--global " : ""}--prefix ${quote(info.prefix)} --ignore-scripts --registry ${REGISTRY} ${PACKAGE}@${release.cli.version}`;
+}
+const prefKey = (info, origin) => `${info.key}:${origin}`;
+export async function updatePreference(session) {
+  const info = installation({ env: session.env });
+  const mode = await session.choose(`Updates for ${info.launcher} at ${session.origin}`, [
+    { label: "Ask before installing (default)", value: "ask" },
+    { label: "Automatically install verified upgrades when idle", value: "auto" },
+    { label: "Off — check only with /update", value: "off" },
+  ]);
+  const prefs = preferences(session.env);
+  savePreferences({ updates: { ...prefs.updates, [prefKey(info, session.origin)]: mode } }, session.env);
+  session.message(`Updates: ${mode}${mode === "auto" && info.reason ? `; deferred: ${info.reason}` : ""}.`);
+}
+export async function checkUpdate({ origin, env = process.env, release, force = false } = {}) {
+  const info = installation({ env });
+  origin = resolveOrigin(env, undefined, origin);
+  const cache = join(dirname(credentialsPath(env)), `release-${createHash("sha256").update(origin).digest("hex")}.json`);
+  if (!release && !force) {
+    const saved = readStore(cache);
+    if (saved?.origin === origin && saved.at <= Date.now() && Date.now() - saved.at < 86_400_000) release = saved.release;
+  }
+  release ??= await new VecteurClient({ origin, timeout: 5_000 }).readiness();
+  if (release.compatible) writeStore(cache, { origin, at: Date.now(), release });
+  else { try { unlinkSync(cache); } catch (error) { if (error.code !== "ENOENT") throw error; } }
+  const cli = release.cli;
+  const reason = !official(origin) ? "Custom origin: executable acquisition is disabled"
+    : !cli?.integrity || cli.channel !== "stable" ? "This origin has no published, integrity-pinned stable package"
+      : info.reason;
+  return { info, origin, release, reason, mode: preferences(env).updates[prefKey(info, origin)] ?? "ask",
+    needed: !!cli && (!release.compatible || cli.version !== info.version),
+    upgrade: !!cli && versionCompare(cli.version, info.version) > 0 };
+}
+function cleanEnvironment(directory) {
+  // npm sees no Vecteur token, npm token, user config, custom loader or proxy.
+  return { PATH: process.env.PATH, HOME: directory, TMPDIR: directory, SystemRoot: process.env.SystemRoot,
+    npm_config_registry: REGISTRY, npm_config_userconfig: join(directory, "empty.npmrc"),
+    npm_config_globalconfig: join(directory, "empty-global.npmrc"), npm_config_cache: join(directory, "cache"),
+    npm_config_ignore_scripts: "true", npm_config_umask: "077", npm_config_audit: "false", npm_config_fund: "false" };
+}
+function syncDirectory(path) { const fd = openSync(path, "r"); try { fsyncSync(fd); } finally { closeSync(fd); } }
+function unchanged(info) {
+  const stat = lstatSync(info.launcher);
+  return stat.isSymbolicLink() && JSON.stringify([stat.dev, stat.ino, stat.mtimeMs, stat.size]) === JSON.stringify(info.identity)
+    && realpathSync(info.launcher) === info.realEntry;
+}
+export function inspectGeneration(directory) {
+  const root = realpathSync(directory); let bytes = 0;
+  function visit(path) {
+    for (const name of readdirSync(path)) {
+      const file = join(path, name), stat = lstatSync(file);
+      if (stat.isSymbolicLink()) {
+        const target = realpathSync(file);
+        if (!target.startsWith(root + "/")) fail("update_closure", "A generation symlink escapes its dependency closure");
+      } else if (stat.isDirectory()) visit(file);
+      else if (!stat.isFile() || !owned(file)) fail("update_closure", "Unsafe package file ownership or type");
+      else bytes += stat.size;
+      if (bytes > MAX_BYTES) fail("update_storage", "Update generation exceeds 512 MiB; existing launchers are unchanged");
+    }
+  }
+  visit(root); return bytes;
+}
+export function activateLauncher(launcher, target) {
+  const temporary = `${launcher}.${randomUUID()}.tmp`;
+  try { symlinkSync(target, temporary); renameSync(temporary, launcher); syncDirectory(dirname(launcher)); }
+  finally { try { unlinkSync(temporary); } catch (error) { if (error.code !== "ENOENT") throw error; } }
+}
+/** The lock serializes pointer writers; readers retain their original real module paths forever. */
+export async function stageUpdate(plan, { signal, progress = () => {} } = {}) {
+  if (plan.reason) fail("update_unavailable", plan.reason);
+  const { info, release } = plan, cli = release.cli;
+  const directory = join(info.prefix, ".vecteur-updates");
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (!owned(directory, true)) fail("update_permissions", "Update directory must be private and owned by you");
+  const lock = join(directory, "install.lock");
+  let fd;
+  try { fd = openSync(lock, "wx", 0o600); }
+  catch { fail("update_locked", `Another updater owns ${lock}; inspect it after a crash before removing it`); }
+  writeFileSync(fd, JSON.stringify({ pid: process.pid, launcher: info.launcher })); fsyncSync(fd);
+  let stage;
+  try {
+    if (!unchanged(info)) fail("update_changed", "Another process changed this launcher; check again");
+    // Never delete a possibly-live generation to make room.
+    if (readdirSync(directory).filter(name => name.startsWith("generation-")).length >= 5) fail("update_storage", `Five generations retained in ${directory}; inspect inactive generations before another update`);
+    const retained = readdirSync(directory).filter(name => name.startsWith("generation-")).reduce((n, name) => n + inspectGeneration(join(directory, name)), 0);
+    const disk = statfsSync(directory);
+    if (retained > 2 * MAX_BYTES || disk.bavail * disk.bsize < MAX_BYTES) fail("update_storage", "Not enough space for a verified generation and rollback; old bytes retained");
+    stage = join(directory, `generation-${cli.version}-${randomUUID()}`);
+    mkdirSync(stage, { mode: 0o700 });
+    writeFileSync(join(stage, "empty.npmrc"), "", { mode: 0o600 }); writeFileSync(join(stage, "empty-global.npmrc"), "", { mode: 0o600 });
+    const env = cleanEnvironment(stage);
+    const npm = async args => (await run("npm", args, { cwd: stage, env, signal, timeout: 180_000, maxBuffer: 8 * 1024 * 1024 })).stdout;
+    const npmVersion = (await npm(["--version"])).trim();
+    if (!/^12\.\d+\.\d+$/.test(npmVersion) || (await npm(["config", "get", "include-attestations"])).trim() !== "false") fail("update_npm_unsupported", "This adapter requires npm 12 with verified attestation output; update npm explicitly through your Node manager");
+    const metadataSignal = AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(10_000)]);
+    const metadataResponse = await fetch(`${REGISTRY}/@vecteur%2fcli/${cli.version}`, { redirect: "error", signal: metadataSignal });
+    if (!metadataResponse.ok) fail("update_unpublished", "The required CLI package is not published");
+    let metadataBytes = 0; const chunks = [];
+    for await (const chunk of metadataResponse.body) {
+      metadataBytes += chunk.length;
+      if (metadataBytes > 2 * 1024 * 1024) fail("update_metadata", "Registry metadata exceeds the size limit");
+      chunks.push(chunk);
+    }
+    const metadata = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    if (metadata.name !== PACKAGE || metadata.version !== cli.version || metadata.dist?.integrity !== cli.integrity
+        || !metadata.dist.attestations || !metadata.dist.signatures?.length) fail("update_provenance", "Published package lacks matching integrity, signatures or provenance; installation kept");
+    writeFileSync(join(stage, "package.json"), JSON.stringify({ private: true, dependencies: { [PACKAGE]: cli.version } }), { mode: 0o600 });
+    progress("Resolving the signed npm dependency closure");
+    await npm(["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund", "--registry", REGISTRY]);
+    const lockfile = JSON.parse(readFileSync(join(stage, "package-lock.json"), "utf8"));
+    const packages = Object.entries(lockfile.packages ?? {}).filter(([path]) => path);
+    if (!packages.length || packages.length > 200) fail("update_closure", "Unexpected dependency closure");
+    for (const [path, item] of packages) {
+      if (!path.startsWith("node_modules/") || path.includes("..") || item.link || !/^https:\/\/registry\.npmjs\.org\//.test(item.resolved ?? "")
+          || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(item.integrity ?? "")) fail("update_closure", "Dependency closure contains an untrusted source or missing integrity");
+    }
+    if (lockfile.packages["node_modules/@vecteur/cli"]?.integrity !== cli.integrity) fail("update_integrity", "Resolved package differs from the origin pin");
+    progress("Downloading and verifying package signatures and provenance");
+    await npm(["ci", "--ignore-scripts", "--no-audit", "--no-fund", "--registry", REGISTRY]);
+    const audit = JSON.parse(await npm(["audit", "signatures", "--json", "--include-attestations", "--registry", REGISTRY]));
+    if (audit.invalid?.length || audit.missing?.length || !audit.verified?.some(row => row.name === PACKAGE && row.version === cli.version && row.registry?.replace(/\/$/, "") === REGISTRY && row.attestations)) fail("update_provenance", "npm did not verify this CLI's release provenance");
+    inspectGeneration(join(stage, "node_modules"));
+    const root = join(stage, "node_modules/@vecteur/cli"), pkg = manifest(root);
+    if (pkg.name !== PACKAGE || pkg.version !== cli.version || pkg.bin?.vecteur !== "bin/vecteur.js"
+        || pkg.vecteur?.updateProtocol !== 1 || pkg.vecteur?.channel !== cli.channel) fail("update_package", "Staged package has an unexpected entrypoint or release channel");
+    const source = readFileSync(join(root, "src/contract.js"), "utf8");
+    if (!source.includes(`export const OWNER_CONTRACT_IDENTITY = ${JSON.stringify(cli.contract)};`)) fail("update_contract", "Staged package does not match the origin contract");
+    const entry = join(root, "bin/vecteur.js");
+    // This is the first execution of newly acquired code, after npm's verification.
+    const probe = await run(process.execPath, [entry, "--version"], { cwd: stage, env, signal, timeout: 10_000 });
+    if (probe.stdout.trim() !== `vecteur ${cli.version}`) fail("update_version", "Staged CLI did not pass its version/Node check");
+    const ready = await new VecteurClient({ origin: plan.origin, timeout: 5_000 }).readiness(signal);
+    if (ready.contract !== cli.contract || ready.cli?.version !== cli.version || ready.cli?.integrity !== cli.integrity) fail("update_release_changed", "The origin changed its release during download; check again");
+    const receipt = { origin: plan.origin, launcher: info.launcher, previous: info.realEntry, target: entry, version: cli.version, contract: cli.contract };
+    // Recovery is self-contained and independent of the replacement or any npm dependency.
+    const recovery = join(directory, "recover.mjs");
+    receipt.recovery = recovery;
+    writeStore(join(directory, "activation.json"), receipt);
+    writeFileSync(recovery, `import {readFileSync,symlinkSync,renameSync,realpathSync,openSync,closeSync,writeFileSync,fsyncSync,unlinkSync} from 'node:fs';
+import {dirname,join} from 'node:path';
+import {randomUUID} from 'node:crypto';
+${syncDirectory.toString()}
+${activateLauncher.toString()}
+${rollbackLauncher.toString()}
+const r=JSON.parse(readFileSync(new URL('./activation.json',import.meta.url)));rollbackLauncher(r);console.log('Restored '+r.previous);
+`, { mode: 0o600 });
+    if (signal?.aborted) fail("update_cancelled", "Update cancelled before activation");
+    if (!unchanged(info)) fail("update_changed", "Launcher changed during staging; original bytes retained");
+    progress("Activating the verified CLI; previous package bytes remain available");
+    activateLauncher(info.launcher, entry);
+    return { ...receipt, recovery, directory };
+  } catch (error) {
+    // No node_modules tree is ever overwritten; failures before pointer activation are inert.
+    if (error instanceof CliError) throw error;
+    throw new CliError("update_failed", `Update did not complete; original package bytes retained. ${error.code ?? error.name}`);
+  } finally { closeSync(fd); unlinkSync(lock); }
+}
+export async function interactiveUpdate(session, { check = false, automatic = false } = {}) {
+  if (session.offline) { session.message("Offline: no update request was made. /resume reconnects."); return; }
+  if (session.busy || session.prompt || session.loginChallenge || session.run?.open || session.registry?.state().pendingRun || session.registry?.state().pendingCreate) {
+    if (!automatic) session.message("Update deferred until the Run, login or unresolved submission is finished; your draft stays here.");
+    return;
+  }
+  const plan = await checkUpdate({ origin: session.origin, env: session.env, release: automatic ? session.release : undefined, force: !automatic });
+  if (session.closed || session.offline) return;
+  if (automatic && plan.mode === "off") return;
+  if (check || !plan.needed || plan.reason) {
+    if (!automatic || plan.needed) session.message(`${installationText(plan.info)}\n${plan.release.cli || plan.release.requiredVersion ? `Origin requires ${plan.release.cli?.version ?? plan.release.requiredVersion}.` : "Origin does not publish update metadata."}\n${plan.reason || (plan.needed ? "Update available." : "This installation matches the origin.")}\n${plan.reason ? manualRecovery(plan) : ""}`);
+    return;
+  }
+  let action = automatic && plan.mode === "auto" && plan.upgrade && plan.release.compatible && plan.info.channel === plan.release.cli.channel ? "once" : await session.choose(
+    `${plan.upgrade ? "Update" : "Switch"} this installation ${plan.info.version} → ${plan.release.cli.version}? Draft saved; pending files must be reselected.`, [
+      { label: "Update and continue", value: "once" }, { label: "Keep this installation updated automatically", value: "auto" },
+      { label: "Keep drafting here", value: "later" },
+    ]);
+  if (action === "later") return;
+  if (action === "auto") {
+    const prefs = preferences(session.env);
+    savePreferences({ updates: { ...prefs.updates, [prefKey(plan.info, session.origin)]: "auto" } }, session.env);
+  }
+  await session.transition(async () => {
+    if (session.run?.open || session.offline || session.registry?.state().pendingRun || session.registry?.state().pendingCreate) fail("update_deferred", "Session changed; update deferred");
+    session.registry?.saveDraft(session.draft);
+    const receipt = await stageUpdate(plan, { signal: session.lifecycle.signal, progress: text => { session.status = text; session.change(); } });
+    session.restart = { receipt, args: ["--origin", session.origin, ...(session.noBrowser ? ["--no-browser"] : []), ...(session.terminalFlags ?? [])], env: session.env, cwd: session.cwd };
+    session.message(`Verified CLI ${receipt.version} activated. Restarting; no ask is sent. Recovery: ${quote(process.execPath)} ${quote(receipt.recovery)}`);
+    session.close();
+  });
+}
+export function rollbackLauncher(receipt) {
+  const lock = join(dirname(receipt.recovery), "install.lock");
+  let fd;
+  try { fd = openSync(lock, "wx", 0o600); }
+  catch { throw new Error(`Recovery deferred: another updater owns ${lock}`); }
+  try {
+    writeFileSync(fd, JSON.stringify({ pid: process.pid, launcher: receipt.launcher })); fsyncSync(fd);
+    if (realpathSync(receipt.launcher) !== receipt.target) throw new Error("Recovery refused: another process changed the launcher");
+    activateLauncher(receipt.launcher, receipt.previous);
+  } finally { closeSync(fd); unlinkSync(lock); }
+}
+export async function restartUpdate({ receipt, args, env, cwd }) {
+  const nonce = randomUUID();
+  const child = spawn(process.execPath, [receipt.launcher, ...args], { cwd,
+    env: { ...env, VECTEUR_UPDATE_SESSION: nonce }, stdio: ["inherit", "inherit", "inherit", "ipc"] });
+  return new Promise(resolveExit => {
+    let ready = false, finished = false, killTimer;
+    const timer = setTimeout(() => {
+      if (ready) return;
+      child.kill("SIGTERM");
+      killTimer = setTimeout(() => { child.kill("SIGKILL"); finish(1); }, 2_000);
+    }, 20_000);
+    child.on("message", value => {
+      if (!finished && !killTimer && value?.type === "vecteur-ready" && value.nonce === nonce && value.version === receipt.version
+          && value.contract === receipt.contract && value.origin === receipt.origin) {
+        ready = true; clearTimeout(timer); child.disconnect();
+        process.stderr.write(`Updated to Vecteur ${receipt.version}; origin compatibility confirmed.\n`);
+      }
+    });
+    const finish = code => {
+      if (finished) return; finished = true; clearTimeout(timer); clearTimeout(killTimer);
+      if (!ready) {
+        try { rollbackLauncher(receipt); process.stderr.write(`Restart was not verified; previous launcher restored. Run ${quote(receipt.launcher)} --offline to recover your draft.\n`); }
+        catch (error) { process.stderr.write(terminalText(`${error.message}; recovery: ${quote(process.execPath)} ${quote(receipt.recovery)}\n`)); }
+      }
+      resolveExit(ready ? code ?? 1 : 1);
+    };
+    child.once("error", () => finish(1)); child.once("exit", finish);
+  });
+}
+export async function updateCommand(options) {
+  const plan = await checkUpdate({ origin: options.origin, force: true });
+  process.stdout.write(terminalText(`${installationText(plan.info)}\n${plan.release.cli || plan.release.requiredVersion ? `Origin requires ${plan.release.cli?.version ?? plan.release.requiredVersion}.` : "No release metadata."}\n${plan.reason || "Verified update can be staged with --yes."}\n${plan.reason ? manualRecovery(plan) : ""}\n`));
+  if (options.check) return;
+  if (!options.yes) fail("update_confirmation", "Use vecteur update --check or explicitly pass --yes to change this launcher");
+  if (plan.needed) {
+    const receipt = await stageUpdate(plan);
+    process.stdout.write(terminalText(`Activated ${receipt.version}. Launch ${quote(receipt.launcher)}. Recovery: ${quote(process.execPath)} ${quote(receipt.recovery)}\n`));
+  }
+}