@vecteur/cli 0.8.0 → 0.9.0

package/README.md

@@ -6,6 +6,16 @@ calls the OPE, engine or database directly.
 
 ```bash
 npm install -g @vecteur/cli
+vecteur
+```
+
+`vecteur` opens the session, signs in through your browser when needed, and finds the Project
+linked to this folder. A new folder creates its Project only when you send your first ask.
+No `init` command or file in the working directory is required.
+
+For scripts and explicit one-shot commands:
+
+```bash
 vecteur login
 vecteur whoami
 vecteur project list
@@ -57,3 +67,118 @@ SHA-256, and refuse to overwrite a local path. Use `--project ID` when no Projec
 `vecteur mcp` serves MCP over stdio using the same credentials and public client. It exposes
 `vecteur_project_get`, `vecteur_run_submit`, `vecteur_run_get` and `vecteur_run_events`.
 An MCP host supplies tool arguments; stdout carries only MCP protocol.
+
+`vecteur mcp setup claude` (or `codex`) runs that vendor's own `mcp add` once so your Claude Code
+or Codex can call Vecteur. `vecteur handoff claude` (or `codex`, or `/handoff` in a session) opens
+your own Claude Code/Codex in this terminal with Vecteur attached for that session only, and
+returns when it exits. The vendor keeps its own login and billing; Vecteur never reads its
+credentials and the handoff changes no vendor configuration. This is a handoff, not the integrated
+mode in which the vendor session appears inside Vecteur's TUI and web.
+
+`vecteur run export <run-id> [--output <dir>]` (or `/export [dir]`) writes a completed Run into a
+new folder: `answer.md` (exact answer bytes), `run.json` (the canonical record) and every artifact,
+each verified against its SHA-256 CAS id. Nothing is overwritten.
+
+## Interactive session
+
+Enter sends; Ctrl+J or Alt+Enter inserts a line. Bracketed paste is one edit and never sends.
+The rich view uses normal terminal scrollback. `vecteur --plain` gives a linear view;
+`NO_COLOR=1 vecteur` or `--no-color` removes styling. `TERM=dumb` selects the linear view.
+Bare invocation in a pipe or CI keeps the previous status output; `vecteur status` always prints it.
+
+- `/project` chooses a Project for this session; `/link` saves the folder association.
+  `/unlink` removes that association for this subtree and preserves the draft. `/name` renames
+  the current Project or names the one created on first send. `/history` loads older Runs on demand.
+- `/model` selects the next Run's model or route from the matched server catalogue. `/mode`
+  explains leadership, execution location and payer. Stage 1 runs in Vecteur cloud.
+- `/attach <path>` previews a selected file and asks before uploading on send. Up to eight
+  files, 8 MiB each and 32 MiB total; all available extracts are selected. `/clear-files` removes
+  pending attachments. Nothing scans your directory or uploads unrelated files.
+- `/answer` handles clarification, including multiple choices and custom text. `/steer <text>`
+  and `/answer-now` submit instructions; acceptance is distinct from execution.
+- `/cancel` or double Esc requests cloud Run cancellation. Ctrl+D on an empty composer or
+  `/quit` detaches; the cloud Run continues. Ctrl+C clears a nonempty composer.
+- `/files` lists outputs; `/download <number> [path]` verifies bytes and refuses overwrite.
+  `/copy [path]` preserves the exact answer: terminal clipboard when supported, otherwise a file.
+- `/resume` reconciles an interrupted submission using its original identity, or follows the
+  same Run from its validated event cursor. A moved head requires an explicit new send.
+  Unknown admission remains pending if authority or transport prevents reconciliation.
+- `/details [number]`, `/web`, `/doctor` and `/help` expose details, browser access, diagnostics
+  and commands. Updates are manual; an incompatible origin supplies its required install command.
+
+Folder links are scoped by origin, authenticated account and canonical directory identity.
+An explicit parent link applies to descendants; a nearer link or unlink overrides it. Linking
+home, a filesystem root or a detected mount root requires typing its full path. A replaced directory or inaccessible Project asks for recovery.
+A link is metadata and never a filesystem grant. Viewer access permits reads and downloads.
+
+`folders.json` beside the credential store holds bindings, drafts and unresolved request identities.
+POSIX directories/files use 0700/0600; writes are atomic and protected by a short writer lock.
+A crashed writer leaves an explicit lock recovery message. Drafts are bounded to 256 KiB and
+expire after 30 days on next registry access/write. Up to 20 revisions from concurrent editors remain
+recoverable through `/drafts`; `/clear` removes the selected draft. Unchanged terminals never
+overwrite another editor, and admission consumes only its exact draft revision. Unresolved
+request evidence stays until resolved. Account draft recovery requires the same credential fingerprint
+previously bound by a successful account read. Never-signed-in drafts occupy a separate unsigned
+namespace with no Project authority; only explicit login transfers them into an account. Neither
+recovery path grants server access. Attachments are held in
+memory until send and must be selected again after restart. A newer store version is refused without
+rewriting it. Previous CLI versions ignore the separate folder registry.
+
+## Maintainer boundaries and later stages
+
+One package, one session owner, two views; stage 1 has no daemon or second application.
+
+| Owner | Responsibility |
+|---|---|
+| `bin/vecteur.js` | TTY dispatch and preserved script/MCP commands; lazy terminal loading |
+| `session.js`, `commands.js` | Cloud actions, prompts, recovery and view facts |
+| `client.js` | Public API, auth transport, validated records, sources, controls and cursor replay |
+| `credentials.js`, `folders.js`, `store.js` | Existing login, account/folder metadata and atomic persistence |
+| `input.js`, `terminal.js` | Grapheme-aware composer, paste, signals and the single stdout writer |
+| `tui/view.js`, `blocks.js` | Rich layout and Run presentation; plain view uses the same session facts |
+| `markdown.js`, `contract.js` | Generated parser/contracts; no runtime web or SDK import |
+| `download.js`, `diagnostics.js` | Verified downloader, Run export and shared read-only diagnostics |
+| `vendors.js` | Claude Code/Codex MCP setup and native-terminal handoff argv; no vendor credentials |
+
+The renderer uses exact `wrap-ansi`/`string-width` pins and a common display-width implementation.
+Ink failed the frozen startup budget. Completed output is appended; resize abandons old live
+geometry so it never guesses how many reflowed scrollback lines to erase. Neither view authorizes
+operations or issues requests itself.
+
+Later computer-use work adds separate device credentials, grants, IPC/relay and cancellation
+subjects. Native Claude/Codex sessions need their own identity and lifecycle; they are not cloud
+Runs. A folder link must never become a local execution grant. External tool results enter existing
+custody with tool/version/hash/trust metadata. No companion/native/driver stubs, vendor credential
+discovery or local execution capability ships in this package.
+
+The intended platform matrix includes Linux, macOS and Windows Terminal, plus screen-reader
+qualification. Current evidence and unresolved cases belong in the stage-1 WBS/backlog; Linux
+tests alone do not qualify other platforms. Standalone binaries are a later packaging option using
+the same session owner. This candidate is unpublished until release acceptance. Its package-owned
+`vecteur.channel` is `preview`, visible even offline; release preparation must promote it to
+`stable` before freezing the published bytes. Updates across channels always ask explicitly.
+
+## Drafting, recovery and updates
+
+`vecteur --offline` opens a saved local draft without a network request or browser. Use `/login`
+when ready; signing in restores the draft for editing and never sends it automatically. `/help`
+searches every command and `/shortcuts` lists editing, choice and Run-control keys. `/settings`
+saves plain/screen-reader display, reduced motion and update preferences separately from tokens.
+
+`/update check` (or `vecteur update --check`) identifies the actual launcher, Node, PATH mismatch
+and origin's required version. Default installation asks first. Opted-in automatic upgrades defer
+while a Run, login or unresolved submission is active. Only a user-owned npm symlink launcher with
+verified release integrity and npm provenance qualifies. Existing module trees stay intact; the
+launcher switches to a separately installed npm generation. Recovery instructions name the retained
+previous target. Windows wrappers, custom Node loaders, direct source scripts and packages without
+provenance receive a refusal and exact manual guidance. No elevation, shell setup edits or automatic
+old-generation deletion occurs. Scripts, JSON, MCP, help and version never install an update.
+
+For an **unpublished preview**, use its exact installed path with `--offline`, or pass `--origin`
+for the matching ready acceptance backend. Installing a global release does not update an absolute
+preview path. Production's exact contract pin may reject a preview before browser sign-in.
+
+```bash
+/path/to/preview/bin/vecteur --offline
+/path/to/preview/bin/vecteur --origin http://127.0.0.1:PORT --no-browser
+```

package/bin/vecteur.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 
 import {
@@ -9,9 +8,10 @@ import {
 import {
   clearCredentials, credentialsPath, readCredentials, setCurrentOrigin, writeCredentials, selectProject,
 } from "../src/credentials.js";
-import { downloadArtifact, downloadProjection } from "../src/download.js";
+import { downloadArtifact, downloadProjection, exportRun } from "../src/download.js";
 import { humanProjects, resolveNamed, resolveRunProject, resolveWorkspace } from "../src/projects.js";
 import { canonicalJson, currentTransferTables, human, humanCost, progress } from "../src/format.js";
+import { openBrowser } from "../src/browser.js";
 
 function manifest() {
   return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -43,8 +43,11 @@ function refuseOldNode() {
 
 function helpText(version) {
   return `vecteur ${version}
-  login | logout | whoami | project list | project create <name> [--workspace <name-or-id>] | project use <name-or-id> | project get <id> | run submit [-p <id>] -a <ask> [--parent <state-hash>] | run get <id> | run events <id> | artifact get <id> [--output <path>] [-p <id>] | projection get <run-id> <projection-id> [--output <path>] [-p <id>] | mcp
-  --help  --version  --json  --origin <url>  --no-browser  --local  -p/--project  -a/--ask  --output <path>
+  login | logout | whoami | project list | project create <name> [--workspace <name-or-id>] | project use <name-or-id> | project get <id> | run submit [-p <id>] -a <ask> [--parent <state-hash>] | run get <id> | run events <id> | run export <id> [--output <dir>] [-p <id>] | artifact get <id> [--output <path>] [-p <id>] | projection get <run-id> <projection-id> [--output <path>] [-p <id>] | mcp
+  mcp setup claude|codex adds Vecteur to your Claude Code/Codex · handoff claude|codex opens it in this terminal with Vecteur attached
+  status | doctor | (bare vecteur opens an interactive session)
+  --help  --version  --json  --origin <url>  --no-browser  --offline  --plain  --no-color  --local  -p/--project  -a/--ask  --output <path>
+  update [--check] [--yes] [--origin <url>] updates the executing installation
   run submit continues the Project's current head; --parent <state-hash> admits it only if that is still the head
 `;
 }
@@ -58,19 +61,6 @@ function writeStatus(env = process.env) {
   }
 }
 
-function openBrowser(url) {
-  const command = process.platform === "darwin" ? "open"
-    : process.platform === "win32" ? "cmd" : "xdg-open";
-  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
-  try {
-    const child = spawn(command, args, { detached: true, stdio: "ignore" });
-    child.on("error", () => {});
-    child.unref();
-  } catch {
-    // The address is already on screen; failing to spawn a browser is not a failed login.
-  }
-}
-
 function parseCommand(argv) {
   let args = [...argv];
   const value = (candidate) => typeof candidate === "string" && candidate.length > 0 &&
@@ -97,6 +87,10 @@ function parseCommand(argv) {
   const json = takeFlag("--json");
   const origin = takeOption("--origin");
   const noBrowser = takeFlag("--no-browser");
+  const offline = takeFlag("--offline");
+  const checkUpdate = takeFlag("--check"), yesUpdate = takeFlag("--yes");
+  const plain = takeFlag("--plain");
+  const noColor = takeFlag("--no-color");
   const local = takeFlag("--local");
   const projectId = takeOption("--project", "-p");
   const ask = takeOption("--ask", "-a");
@@ -111,10 +105,24 @@ function parseCommand(argv) {
   }
   if (version) return { kind: "version" };
   if (help) return { kind: "help" };
+  if (args.length === 1 && args[0] === "update" && !json && !local && !offline && !plain && !noColor
+      && !noBrowser && projectId === undefined && ask === undefined && workspace === undefined && output === undefined && parent === undefined) {
+    return { kind: "update", origin, check: checkUpdate, yes: yesUpdate };
+  }
+  if (checkUpdate || yesUpdate) throw new CliError("usage_invalid", "--check and --yes apply only to update");
+  if (!args.length && !json && !local && projectId === undefined && ask === undefined
+      && workspace === undefined && output === undefined && parent === undefined) {
+    return { kind: "session", origin, noBrowser, plain, noColor, offline };
+  }
+  if (offline) throw new CliError("usage_invalid", "--offline applies only to an interactive session");
+  if (plain || noColor) throw new CliError("usage_invalid", "--plain and --no-color apply to an interactive session");
   const extra = json || origin !== undefined || noBrowser || local
     || projectId !== undefined || ask !== undefined || workspace !== undefined || output !== undefined;
-  if (args.length === 0 && !extra) return { kind: "status" };
+  if (args.length === 1 && ["status", "doctor"].includes(args[0]) && !extra) return { kind: args[0] };
   if (args.length === 1 && args[0] === "mcp" && !extra) return { kind: "mcp" };
+  if (!extra && ((args.length === 3 && args[0] === "mcp" && args[1] === "setup") || (args.length === 2 && args[0] === "handoff"))) {
+    return { kind: "vendor", mode: args[0] === "mcp" ? "setup" : "handoff", vendor: args.at(-1) };
+  }
   if (args[0] === "project" && projectId === undefined && ask === undefined && output === undefined
       && !noBrowser && !local) {
     if (args.length === 3 && args[1] === "create" && value(args[2])) {
@@ -157,6 +165,9 @@ function parseCommand(argv) {
       && projectId === undefined && ask === undefined && output === undefined) {
     return { kind: "run_events", id: args[2], origin, json };
   }
+  if (args.length === 3 && args[0] === "run" && args[1] === "export" && value(args[2]) && ask === undefined) {
+    return { kind: "run_export", id: args[2], projectId, output, origin, json };
+  }
   if (args.length === 3 && args[0] === "artifact" && args[1] === "get" && value(args[2])
       && ask === undefined) {
     return { kind: "artifact_get", id: args[2], projectId, output, origin, json };
@@ -203,7 +214,7 @@ async function login(command, env = process.env) {
     try {
       await new VecteurClient({ origin, token: previous, timeout }).credentialSelfRevoke();
     } catch (error) {
-      if (!(error instanceof CliError && error.code === "pat_revoked")) throw error;
+      if (!(error instanceof CliError && ["pat_revoked", "pat_expired", "pat_invalid"].includes(error.code))) throw error;
     }
   }
   const path = writeCredentials({ origin, token: created.token }, env);
@@ -277,6 +288,39 @@ async function main() {
     writeStatus();
     return;
   }
+  if (command.kind === "doctor") {
+    const { diagnose } = await import("../src/diagnostics.js");
+    const result = await diagnose();
+    process.stdout.write(result.text + "\n");
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (command.kind === "session") {
+    if (!process.stdin.isTTY || !process.stdout.isTTY || process.env.CI !== undefined) {
+      if (command.plain || command.noColor || command.origin || command.noBrowser || command.offline) {
+        throw new CliError("terminal_required", "Interactive options need a terminal; use existing subcommands for scripts");
+      }
+      writeStatus(); return;
+    }
+    const { startTerminal } = await import("../src/terminal.js");
+    await startTerminal(command);
+    return;
+  }
+  if (command.kind === "update") {
+    const { updateCommand } = await import("../src/update.js");
+    await updateCommand(command);
+    return;
+  }
+  if (command.kind === "vendor") {
+    const { VENDORS, executingServer, runVendor, shellLine, vendorArgv } = await import("../src/vendors.js");
+    const argv = vendorArgv(command.vendor, command.mode, command.mode === "handoff" ? executingServer() : undefined);
+    process.stderr.write(command.mode === "setup"
+      ? `Adding Vecteur to ${VENDORS[command.vendor]} with its own command:\n  ${shellLine(argv)}\n`
+      : `Opening your ${VENDORS[command.vendor]} terminal with Vecteur attached for this session only.\n`
+        + `${VENDORS[command.vendor]} keeps its own login and billing; exit it to return here.\n`);
+    process.exitCode = await runVendor(argv);
+    return;
+  }
   if (command.kind === "mcp") {
     const { serveVecteurMcp } = await import("../src/mcp.js");
     serveVecteurMcp();
@@ -328,6 +372,14 @@ async function main() {
       : `Downloaded ${value.bytes} bytes to ${value.path} (${value.content_type})\n`);
     return;
   }
+  else if (command.kind === "run_export") {
+    const projectId = await resolveRunProject(client, command.projectId);
+    value = await exportRun(client, await client.runGet(command.id), projectId,
+      command.output ?? `vecteur-run-${command.id.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 12)}`);
+    process.stdout.write(command.json ? canonicalJson(value) : `Exported Run ${value.run_id} (${value.terminal}) to ${value.directory}\n`
+      + value.files.map(file => `  ${file.path} · ${file.bytes} bytes${file.cas_ref ? " · verified" : ""}\n`).join(""));
+    return;
+  }
   else if (command.kind === "projection_get") {
     const projectId = await resolveRunProject(client, command.projectId);
     const run = await client.runGet(command.runId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vecteur/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "bin": {
     "vecteur": "bin/vecteur.js"
@@ -15,7 +15,21 @@
     "src/errors.js",
     "src/format.js",
     "src/mcp.js",
-    "src/projects.js"
+    "src/projects.js",
+    "src/store.js",
+    "src/folders.js",
+    "src/browser.js",
+    "src/blocks.js",
+    "src/session.js",
+    "src/input.js",
+    "src/commands.js",
+    "src/terminal.js",
+    "src/markdown.js",
+    "src/tui/view.js",
+    "src/diagnostics.js",
+    "src/preferences.js",
+    "src/update.js",
+    "src/vendors.js"
   ],
   "scripts": {
     "test": "node --test tests/*.test.js",
@@ -28,14 +42,20 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
+    "string-width": "7.2.0",
+    "wrap-ansi": "9.0.2",
     "zod": "4.4.3"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.0.0"
   },
-  "description": "The Vecteur command line — one login, the same product as the web app, from any directory.",
+  "description": "The Vecteur command line \u2014 one login, the same product as the web app, from any directory.",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
+  },
+  "vecteur": {
+    "updateProtocol": 1,
+    "channel": "stable"
   }
 }

package/src/blocks.js

@@ -0,0 +1,40 @@
+import { humanRun, progress } from "./format.js";
+
+function elapsed(run, now) {
+  if (!run) return null;
+  const accepted = run.accepted_at;
+  // Both owner duration and live age start at admission, never at local follow/restart.
+  // Live age uses the client wall clock; invalid/future anchors are unavailable.
+  const seconds = run.terminal ? run.duration_seconds
+    : Number.isSafeInteger(accepted) && accepted >= 0 && accepted <= now / 1000
+      ? Math.floor(now / 1000 - accepted) : null;
+  if (!Number.isSafeInteger(seconds) || seconds < 0) return "Elapsed unavailable";
+  const pad = value => String(value).padStart(2, "0");
+  return "Elapsed " + (seconds >= 3600 ? `${Math.floor(seconds / 3600)}:` : "")
+    + `${pad(Math.floor(seconds / 60) % 60)}:${pad(seconds % 60)}`;
+}
+
+/** RunWire owns the facts. Optional session cache projects only newly appended events. */
+export function runView(run, cache, now = Date.now()) {
+  const events = run?.events ?? [];
+  const same = cache && cache.run === run && cache.count <= events.length && cache.view;
+  if (same && cache.count === events.length && cache.terminal === run?.terminal) return { ...cache.view, elapsed: elapsed(run, now) };
+  const view = same ? cache.view : {
+    subject: run ? { kind: "vecteur_run", id: run.run_id } : null,
+    answer: "", question: null, artifacts: [], steps: [], progress: "Waiting for Vecteur",
+    terminal: "", transcript: "",
+  };
+  for (let index = same ? cache.count : 0; index < events.length; index++) {
+    const event = events[index];
+    if (event.kind === "synthesis") view.answer = event.payload.answer ?? "";
+    if (event.kind === "clarification") view.question = event.payload.state === "requested" ? event.payload : null;
+    if (event.kind === "artifact") view.artifacts.push(event.payload);
+    if (["step_started", "step_finished", "task"].includes(event.kind)) view.steps.push(event);
+    const line = progress(event);
+    if (line) view.progress = line.trim();
+  }
+  view.terminal = run?.terminal ?? "";
+  view.transcript = run?.terminal ? humanRun(run) : "";
+  if (cache) Object.assign(cache, { run, count: events.length, terminal: run?.terminal, view });
+  return { ...view, elapsed: elapsed(run, now) };
+}

package/src/browser.js

@@ -0,0 +1,18 @@
+import { spawn } from "node:child_process";
+
+/** Only an explicit user action calls this; the visible URL always remains usable. */
+export async function openBrowser(url) {
+  try {
+    const parsed = new URL(url);
+    if (!["https:", "http:"].includes(parsed.protocol)) return false;
+    const command = process.platform === "darwin" ? "open"
+      : process.platform === "win32" ? "rundll32.exe" : "xdg-open";
+    const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", parsed.href] : [parsed.href];
+    return await new Promise(resolve => {
+      const child = spawn(command, args, { detached: true, stdio: "ignore" });
+      const timer = setTimeout(() => { child.unref(); resolve(true); }, 1_500);
+      child.once("error", () => { clearTimeout(timer); resolve(false); });
+      child.once("exit", code => { clearTimeout(timer); resolve(code === 0); });
+    });
+  } catch { return false; }
+}