@vecteur/cli 0.3.1 → 0.4.1

package/README.md

@@ -0,0 +1,49 @@
+# Vecteur CLI
+
+One command line for Vecteur's public API. Sign in through your browser, then use the same
+Projects and run records as the web app. The client stores your credential locally; it never
+calls the OPE, engine or database directly.
+
+```bash
+npm install -g @vecteur/cli
+vecteur login
+vecteur whoami
+vecteur project list
+vecteur project create 'Transfer study'
+vecteur project use 'Transfer study'
+vecteur project get PROJECT_ID --json
+vecteur run submit --ask 'GTO to GEO transfer'
+vecteur run get RUN_ID --json
+vecteur run events RUN_ID --json
+vecteur artifact get sha256:ARTIFACT_DIGEST --output report.docx
+vecteur logout
+```
+
+Use `vecteur login --origin URL` for another deployment. For automation, supply a Project PAT
+through `VECTEUR_TOKEN` and its origin through `VECTEUR_BASE_URL`; never pass a token on argv.
+`--help` and `--version` work without signing in.
+
+`project list` shows authorized Projects and the server's Organization-wide active Project
+allowance. `project create NAME --workspace NAME_OR_ID` chooses among multiple Workspaces; one
+Workspace is implicit. Names must match exactly and uniquely, or use an id. Quota refusals show
+the server's reason and recovery links.
+
+`project use NAME_OR_ID` saves the selected id beside the login for that origin. `run submit`
+checks this selection against the live authorized list each time; `--project ID` overrides it.
+With `VECTEUR_TOKEN`, runs require `--project ID` and `project use` requires a persistent login.
+Project PATs retain their server-defined scope; listing and creating Projects require an account
+login. `project list --json` preserves `{projects, active_projects, selected_project_id}`.
+
+`run events` validates dense SSE sequence and returns the canonical direct record only when its
+embedded events match the stream. Redirects, secret-shaped responses, malformed responses and
+timeouts fail nonzero. `--json` sorts object keys for deterministic machine output.
+
+Human run output shows the sealed synthesis, input origins, artifact download commands, the typed
+terminal cause/recovery, and—after `run submit`—the selected Project's UTC-month customer cost using
+the server's display strings. Machine run output remains the unchanged canonical record. Artifact
+downloads use the Project-scoped admitted CAS route, verify the declared length, media type and
+SHA-256, and refuse to overwrite a local path. Use `--project ID` when no Project is selected.
+
+`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.

package/bin/vecteur.js

@@ -1,106 +1,347 @@
 #!/usr/bin/env node
-import { CliError, VecteurClient, configuration, redact } from "../src/client.js";
-import { clearCredentials, credentialsPath, readCredentials, writeCredentials } from "../src/credentials.js";
-import { canonicalJson, human, progress } from "../src/format.js";
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
 
-/**
- * Read one line from stdin, with no echo concerns: the token is PIPED, never typed into argv.
- *
- * `--token vct_…` would put a live credential in `ps`, in `/proc/<pid>/cmdline` for every local
- * user, and in the shell history file afterwards. That exposure is not hypothetical here —
- * `SHIP-007` on this project's own backlog exists to rotate production credentials that reached
- * a command line. A door must not ship a convenient way to repeat it.
- */
-async function readTokenFromStdin() {
-  if (process.stdin.isTTY) {
-    throw new CliError("token_required",
-      "pipe the personal access token in: `vecteur login --url <origin> < token.txt`");
-  }
-  const chunks = [];
-  for await (const chunk of process.stdin) chunks.push(chunk);
-  const token = Buffer.concat(chunks).toString("utf8").trim();
-  if (!token) throw new CliError("token_required", "stdin held no personal access token");
-  return token;
+import {
+  CliError, VecteurClient, configuration, isTokenShaped, redact, requestTimeout, resolveOrigin,
+  shouldOpenBrowser, waitForDeviceAuthorization,
+} from "../src/client.js";
+import {
+  clearCredentials, credentialsPath, readCredentials, setCurrentOrigin, writeCredentials, selectProject,
+} from "../src/credentials.js";
+import { downloadArtifact } from "../src/download.js";
+import { humanProjects, resolveNamed, resolveRunProject, resolveWorkspace } from "../src/projects.js";
+import { canonicalJson, human, humanCost, progress } from "../src/format.js";
+
+function manifest() {
+  return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+}
+
+function versionParts(raw) {
+  const match = String(raw).match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
+  return match ? [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)] : null;
+}
+
+function refuseOldNode() {
+  const declared = manifest().engines?.node;
+  if (typeof declared !== "string" || !declared.startsWith(">=")) {
+    throw new CliError("engines_invalid", "package engines.node must be a >= floor");
+  }
+  const floor = versionParts(declared.slice(2));
+  const current = versionParts(process.versions.node);
+  if (!floor || !current) {
+    throw new CliError("engines_invalid", "package engines.node must be a >= floor");
+  }
+  const below = current[0] < floor[0]
+    || (current[0] === floor[0] && current[1] < floor[1])
+    || (current[0] === floor[0] && current[1] === floor[1] && current[2] < floor[2]);
+  if (below) {
+    throw new CliError("node_version_unsupported",
+      `Node ${process.versions.node} is below engines.node ${declared}`);
+  }
+}
+
+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> | run get <id> | run events <id> | artifact get <id> [--output <path>] [-p <id>] | mcp
+  --help  --version  --json  --origin <url>  --no-browser  --local  -p/--project  -a/--ask  --output <path>
+`;
+}
+
+function writeStatus(env = process.env) {
+  const saved = readCredentials(env);
+  if (saved?.current) {
+    process.stdout.write(`${saved.current}\nnext: vecteur whoami\n`);
+  } else {
+    process.stdout.write("not logged in\nnext: vecteur login\n");
+  }
+}
+
+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) {
-  const json = argv.at(-1) === "--json";
-  const args = json ? argv.slice(0, -1) : [...argv];
+  let args = [...argv];
   const value = (candidate) => typeof candidate === "string" && candidate.length > 0 &&
     !candidate.startsWith("-");
-  if (args.length === 3 && args[0] === "login" && args[1] === "--url" && value(args[2])) {
-    return { kind: "login", origin: args[2], json };
+  const takeFlag = (...names) => {
+    const indexes = args.flatMap((arg, i) => names.includes(arg) ? [i] : []);
+    if (indexes.length > 1) throw new CliError("usage_invalid", "Invalid command grammar");
+    if (indexes.length === 0) return false;
+    args = args.filter((_, i) => i !== indexes[0]);
+    return true;
+  };
+  const takeOption = (...names) => {
+    const indexes = args.flatMap((arg, i) => names.includes(arg) ? [i] : []);
+    if (indexes.length > 1) throw new CliError("usage_invalid", "Invalid command grammar");
+    if (indexes.length === 0) return undefined;
+    const index = indexes[0];
+    if (!value(args[index + 1])) throw new CliError("usage_invalid", "Invalid command grammar");
+    const option = args[index + 1];
+    args = args.filter((_, i) => i !== index && i !== index + 1);
+    return option;
+  };
+  const version = takeFlag("--version");
+  const help = takeFlag("--help");
+  const json = takeFlag("--json");
+  const origin = takeOption("--origin");
+  const noBrowser = takeFlag("--no-browser");
+  const local = takeFlag("--local");
+  const projectId = takeOption("--project", "-p");
+  const ask = takeOption("--ask", "-a");
+  const workspace = takeOption("--workspace");
+  const output = takeOption("--output");
+  if (args.some((arg) => typeof arg === "string" && arg.startsWith("-"))) {
+    throw new CliError("usage_invalid", "Invalid command grammar");
+  }
+  if (version) return { kind: "version" };
+  if (help) return { kind: "help" };
+  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 && args[0] === "mcp" && !extra) return { kind: "mcp" };
+  if (args[0] === "project" && projectId === undefined && ask === undefined && output === undefined
+      && !noBrowser && !local) {
+    if (args.length === 3 && args[1] === "create" && value(args[2])) {
+      return { kind: "project_create", name: args[2], workspace, origin, json };
+    }
+    if (workspace === undefined && args.length === 2 && args[1] === "list") {
+      return { kind: "project_list", origin, json };
+    }
+    if (workspace === undefined && args.length === 3 && args[1] === "use" && value(args[2])) {
+      return { kind: "project_use", name: args[2], origin, json };
+    }
+  }
+  if (workspace !== undefined) throw new CliError("usage_invalid", "Invalid command grammar");
+  if (args.length === 1 && args[0] === "login" && !local
+      && projectId === undefined && ask === undefined && output === undefined) {
+    return { kind: "login", origin, noBrowser, json };
+  }
+  if (args.length === 1 && args[0] === "logout" && !noBrowser
+      && projectId === undefined && ask === undefined && output === undefined) {
+    return { kind: "logout", origin, local, json };
   }
-  if (args.length === 1 && args[0] === "logout") return { kind: "logout", json };
-  if (args.length === 1 && args[0] === "whoami") return { kind: "whoami", json };
-  if (args.length === 3 && args[0] === "project" && args[1] === "get" && value(args[2])) {
-    return { kind: "project_get", id: args[2], json };
+  if (args.length === 1 && args[0] === "whoami" && !noBrowser && !local
+      && projectId === undefined && ask === undefined && output === undefined) {
+    return { kind: "whoami", origin, json };
   }
-  if (args.length === 6 && args[0] === "run" && args[1] === "submit" &&
-      args[2] === "--project" && value(args[3]) && args[4] === "--ask" && value(args[5])) {
-    return { kind: "run_submit", projectId: args[3], ask: args[5], json };
+  if (noBrowser || local) throw new CliError("usage_invalid", "Invalid command grammar");
+  if (args.length === 3 && args[0] === "project" && args[1] === "get" && value(args[2])
+      && projectId === undefined && ask === undefined && output === undefined) {
+    return { kind: "project_get", id: args[2], origin, json };
   }
-  if (args.length === 3 && args[0] === "run" && args[1] === "get" && value(args[2])) {
-    return { kind: "run_get", id: args[2], json };
+  if (args.length === 2 && args[0] === "run" && args[1] === "submit"
+      && (projectId === undefined || value(projectId)) && value(ask) && output === undefined) {
+    return { kind: "run_submit", projectId, ask, origin, json };
   }
-  if (args.length === 3 && args[0] === "run" && args[1] === "events" && value(args[2])) {
-    return { kind: "run_events", id: args[2], json };
+  if (args.length === 3 && args[0] === "run" && args[1] === "get" && value(args[2])
+      && projectId === undefined && ask === undefined && output === undefined) {
+    return { kind: "run_get", id: args[2], origin, json };
+  }
+  if (args.length === 3 && args[0] === "run" && args[1] === "events" && value(args[2])
+      && projectId === undefined && ask === undefined && output === undefined) {
+    return { kind: "run_events", id: args[2], 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 };
   }
   throw new CliError("usage_invalid", "Invalid command grammar");
 }
 
+/**
+ * `--origin` moves the STORE's current origin, and only the store path may do it.
+ *
+ * When the credential came from the environment there is no stored login for the named origin
+ * to become current, writing to the store is the one thing the CI path must not do, and reading
+ * it is how an unreadable file broke a run that never needed one. Both callers ask here rather
+ * than each remembering the rule, because one of them already forgot it.
+ */
+function rememberOrigin(flagOrigin, origin, env) {
+  if (flagOrigin && !env.VECTEUR_TOKEN) setCurrentOrigin(origin, env);
+}
+
+function writeLoggedOut(json, path) {
+  process.stdout.write(json
+    ? canonicalJson({ logged_in: false, credentials: path })
+    : `logged out\ncredentials removed: ${path}\n`);
+}
+
+async function login(command, env = process.env) {
+  const origin = resolveOrigin(env, undefined, command.origin);
+  const timeout = requestTimeout(env);
+  const client = new VecteurClient({ origin, token: "", timeout });
+  const grant = await client.deviceMint();
+  const prompt = `Visit ${grant.verification_uri_complete}\nUser code: ${grant.user_code}\n`;
+  (command.json ? process.stderr : process.stdout).write(prompt);
+  if (shouldOpenBrowser(command.noBrowser, env)) openBrowser(grant.verification_uri_complete);
+  const created = await waitForDeviceAuthorization(client, grant);
+  if (!isTokenShaped(created.token)) {
+    throw new CliError("pat_created_invalid", "Server returned malformed owner data");
+  }
+  const previous = readCredentials(env)?.logins?.[origin]?.token;
+  if (previous) {
+    try {
+      await new VecteurClient({ origin, token: previous, timeout }).credentialSelfRevoke();
+    } catch (error) {
+      if (!(error instanceof CliError && error.code === "pat_revoked")) throw error;
+    }
+  }
+  const path = writeCredentials({ origin, token: created.token }, env);
+  const account = await new VecteurClient({ origin, token: created.token, timeout }).accountMe();
+  process.stdout.write(command.json
+    ? canonicalJson({ logged_in: true, origin, credentials: path, account })
+    : `logged in to ${origin}\n${renderAccount(account, origin)}credentials: ${path}\n`);
+}
+
+async function logout(command, env = process.env) {
+  const path = credentialsPath(env);
+  let saved;
+  try {
+    saved = readCredentials(env);
+  } catch (error) {
+    if (!command.local) throw error;
+    clearCredentials(env);
+    writeLoggedOut(command.json, path);
+    return;
+  }
+  if (!saved) {
+    writeLoggedOut(command.json, path);
+    return;
+  }
+  const origin = resolveOrigin(env, saved, command.origin);
+  const token = saved.logins[origin]?.token;
+  if (!token) {
+    throw new CliError("origin_mismatch",
+      `the stored login is for ${saved.current} and ${command.origin !== undefined ? "--origin" : "VECTEUR_BASE_URL"} names `
+      + `${origin} — set VECTEUR_TOKEN for that origin, or log in to it`);
+  }
+  if (!command.local) {
+    try {
+      await new VecteurClient({ origin, token, timeout: requestTimeout(env) }).credentialSelfRevoke();
+    } catch (error) {
+      if (error instanceof CliError && (error.code === "request_failed" || error.code === "request_timeout")) {
+        throw new CliError("logout_offline",
+          "logout requires the origin; pass --local to delete only this machine's store");
+      }
+      throw error;
+    }
+  }
+  writeLoggedOut(command.json, clearCredentials(env, origin));
+}
+
+function renderAccount(account, origin) {
+  return `${account.display_name} <${account.email}> (${account.id}) at ${origin}\n`;
+}
+
+async function whoami(command, env = process.env) {
+  const config = configuration(env, undefined, command.origin);
+  rememberOrigin(command.origin, config.origin, env);
+  const account = await new VecteurClient(config).accountMe();
+  process.stdout.write(command.json
+    ? canonicalJson(account)
+    : renderAccount(account, config.origin));
+}
+
 async function main() {
+  refuseOldNode();
   const command = parseCommand(process.argv.slice(2));
+  if (command.kind === "version") {
+    process.stdout.write(`vecteur ${manifest().version}\n`);
+    return;
+  }
+  if (command.kind === "help") {
+    process.stdout.write(helpText(manifest().version));
+    return;
+  }
+  if (command.kind === "status") {
+    writeStatus();
+    return;
+  }
+  if (command.kind === "mcp") {
+    const { serveVecteurMcp } = await import("../src/mcp.js");
+    serveVecteurMcp();
+    return;
+  }
 
-  // The login commands run BEFORE a client is constructed. Constructing one resolves a
-  // configuration, and requiring a valid login in order to log in is the shape of bug that
-  // makes a first run impossible.
+  // Login and logout run BEFORE a client is constructed from configuration(): requiring a
+  // valid login in order to log in (or to delete a corrupt store locally) is the shape of
+  // bug that makes a first run or a recovery impossible. VECTEUR_TOKEN is the CI path and
+  // is never written or revoked here.
   if (command.kind === "login") {
-    const token = await readTokenFromStdin();
-    // Shape-check HERE so the refusal names what is wrong with what was just piped in. Falling
-    // straight through to `configuration` reported "no login found: run `vecteur login`" to a
-    // user in the middle of running exactly that.
-    if (!/^vct_[A-Za-z0-9_-]{43}$/.test(token)) {
-      throw new CliError("token_invalid",
-        `stdin held ${token.length} characters; a personal access token is \`vct_\` and 43 more`);
-    }
-    // Then through the SAME function every command resolves through, so an origin this CLI
-    // would later refuse is refused now, while the user is still holding the token — not on
-    // their next command with the credential already on disk.
-    const checked = configuration({ VECTEUR_TOKEN: token, VECTEUR_BASE_URL: command.origin }, null);
-    const path = writeCredentials({ origin: checked.origin, token }, process.env);
-    process.stdout.write(command.json
-      ? canonicalJson({ logged_in: true, origin: checked.origin, credentials: path })
-      : `logged in to ${checked.origin}\ncredentials: ${path}\n`);
+    await login(command);
     return;
   }
   if (command.kind === "logout") {
-    const path = clearCredentials(process.env);
-    process.stdout.write(command.json
-      ? canonicalJson({ logged_in: false, credentials: path })
-      : `logged out\ncredentials removed: ${path}\n`);
+    await logout(command);
     return;
   }
   if (command.kind === "whoami") {
-    const saved = readCredentials(process.env);
-    // NEVER the token, not even a prefix. A door that prints part of a credential teaches the
-    // habit of pasting it somewhere, and a prefix is enough to confirm a guess.
-    process.stdout.write(command.json
-      ? canonicalJson({ logged_in: Boolean(saved), origin: saved?.origin ?? null })
-      : saved ? `logged in to ${saved.origin}\n` : "not logged in\n");
-    process.exitCode = saved ? 0 : 1;
+    await whoami(command);
     return;
   }
 
-  const client = new VecteurClient();
+  const config = configuration(process.env, undefined, command.origin);
+  rememberOrigin(command.origin, config.origin, process.env);
+  const client = new VecteurClient(config);
   const onEvent = command.json ? null : (event) => process.stderr.write(progress(event));
   let value;
-  if (command.kind === "project_get") value = await client.projectGet(command.id);
+  let renderOptions = {};
+  if (command.kind === "project_list") {
+    const [account, projects] = await Promise.all([client.accountMe(), client.projectList()]);
+    value = { projects, active_projects: account.entitlements.active_projects,
+      selected_project_id: config.projectId ?? null };
+    process.stdout.write(command.json ? canonicalJson(value) : humanProjects(value));
+    return;
+  } else if (command.kind === "project_create") {
+    const account = await client.accountMe();
+    value = await client.projectCreate(command.name, resolveWorkspace(account, command.workspace));
+  } else if (command.kind === "project_use") {
+    if (process.env.VECTEUR_TOKEN) throw new CliError("persistent_login_required",
+      "project use requires a persistent login; unset VECTEUR_TOKEN and run `vecteur login`");
+    value = resolveNamed(await client.projectList(), command.name, "project");
+    selectProject(config.origin, value.id);
+  } else if (command.kind === "project_get") value = await client.projectGet(command.id);
+  else if (command.kind === "artifact_get") {
+    const projectId = await resolveRunProject(client, command.projectId);
+    value = await downloadArtifact(client, command.id, projectId, command.output);
+    process.stdout.write(command.json ? canonicalJson(value)
+      : `Downloaded ${value.bytes} bytes to ${value.path} (${value.content_type})\n`);
+    return;
+  }
   else if (command.kind === "run_submit") {
-    value = await client.runSubmit(command.projectId, command.ask, onEvent);
+    const projectId = await resolveRunProject(client, command.projectId);
+    value = await client.runSubmit(projectId, command.ask, onEvent);
+    if (!command.json) {
+      process.stdout.write(human(value, { projectId }));
+      try {
+        const cost = await client.customerCost(projectId);
+        process.stdout.write(`\n${humanCost(cost)}`);
+      } catch (error) {
+        if (error instanceof CliError && error.code === "pat_expired") {
+          throw new CliError("pat_expired",
+            `credential expired after Run ${value.run_id} was admitted; next: vecteur login; then: vecteur run get ${value.run_id}`);
+        }
+        throw error;
+      }
+      return;
+    }
   } else if (command.kind === "run_get") value = await client.runGet(command.id);
   else value = await client.runEvents(command.id, onEvent);
-  process.stdout.write(command.json ? canonicalJson(value) : human(value));
+  if (!command.json && !renderOptions.projectId && config.projectId) {
+    renderOptions = { projectId: config.projectId };
+  }
+  process.stdout.write(command.json ? canonicalJson(value) : human(value, renderOptions));
 }
 
 main().catch((error) => {

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@vecteur/cli",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "type": "module",
   "bin": {
-    "cli": "bin/vecteur.js",
-    "vecteur": "bin/vecteur.js",
-    "vecteur-mcp": "bin/vecteur-mcp.js"
+    "vecteur": "bin/vecteur.js"
   },
   "files": [
-    "bin/vecteur-mcp.js",
+    "README.md",
     "bin/vecteur.js",
     "src/client.js",
     "src/contract.js",
     "src/credentials.js",
+    "src/download.js",
     "src/errors.js",
     "src/format.js",
-    "src/mcp.js"
+    "src/mcp.js",
+    "src/projects.js"
   ],
   "scripts": {
     "test": "node --test tests/*.test.js",