@vecteur/cli 0.2.4 → 0.3.0

package/src/credentials.js

@@ -0,0 +1,75 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { CliError } from "./errors.js";
+
+/**
+ * ONE PERSISTENT LOGIN — SRD 06's release bar for this door, beside "the same product from any
+ * working directory".
+ *
+ * Before this, `configuration()` read `VECTEUR_TOKEN` from the environment and nothing else, so
+ * "logged in" lasted exactly as long as one shell. Every new terminal, every cron line and every
+ * `cd` into a project began by pasting a credential again — which is not a login, and it is the
+ * habit that puts secrets in shell history.
+ *
+ * THE TOKEN IS NEVER AN ARGUMENT. `vecteur login` reads it from stdin. A credential passed as
+ * `--token vct_…` is visible in `ps`, in `/proc/<pid>/cmdline` to every local user, and in the
+ * shell history file afterwards — the exact exposure `SHIP-007` exists to rotate away in this
+ * same product. A door that ships a convenient way to make that mistake has shipped the mistake.
+ *
+ * The store lives OUTSIDE every git tree, one file, 0600 — the same shape `scripts/with-secrets.py`
+ * holds the fleet's own store in, for the same reason.
+ */
+const FILE_MODE = 0o600;
+const DIRECTORY_MODE = 0o700;
+
+/** `$XDG_CONFIG_HOME/vecteur/credentials.json`, or `~/.config/vecteur/credentials.json`. */
+export function credentialsPath(env = process.env) {
+  const base = env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME.startsWith("/")
+    ? env.XDG_CONFIG_HOME
+    : join(env.HOME || homedir(), ".config");
+  return join(base, "vecteur", "credentials.json");
+}
+
+/** `{ origin, token }` as stored, or `null` when nobody has logged in on this machine. */
+export function readCredentials(env = process.env) {
+  let raw;
+  try {
+    raw = readFileSync(credentialsPath(env), "utf8");
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // A corrupt store is a typed refusal, not a silent fall back to "not logged in": the second
+    // reads as "run login again" and loses the fact that a credential IS there and unreadable.
+    throw new CliError("credentials_unreadable",
+      `${credentialsPath(env)} is not readable JSON — run \`vecteur logout\` and log in again`);
+  }
+  if (!parsed || typeof parsed !== "object" ||
+      typeof parsed.origin !== "string" || typeof parsed.token !== "string") {
+    throw new CliError("credentials_unreadable",
+      `${credentialsPath(env)} does not hold an origin and a token`);
+  }
+  return { origin: parsed.origin, token: parsed.token };
+}
+
+export function writeCredentials({ origin, token }, env = process.env) {
+  const path = credentialsPath(env);
+  mkdirSync(dirname(path), { recursive: true, mode: DIRECTORY_MODE });
+  // Written 0600 AT CREATION, not chmod'ed after: between an 0644 create and a chmod there is a
+  // window in which any local user can read the token, and on a shared machine that window is
+  // the whole exposure.
+  writeFileSync(path, `${JSON.stringify({ origin, token }, null, 2)}\n`, { mode: FILE_MODE });
+  chmodSync(path, FILE_MODE);   // an existing file keeps its old mode through writeFileSync
+  return path;
+}
+
+export function clearCredentials(env = process.env) {
+  const path = credentialsPath(env);
+  rmSync(path, { force: true });
+  return path;
+}

package/src/errors.js

@@ -0,0 +1,14 @@
+/**
+ * The CLI's one typed error, in its own module.
+ *
+ * It used to live in `client.js`, which `credentials.js` had to import for it while `client.js`
+ * needed `credentials.js` to resolve a stored login — a cycle whose first workaround was a
+ * function reached through `globalThis`. An error type is not part of either concern; it is
+ * shared vocabulary, so it owns a file and neither side reaches through the other.
+ */
+export class CliError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}

package/src/format.js

@@ -0,0 +1,91 @@
+import { ORIGIN_KINDS, ORIGIN_WORD } from "./contract.js";
+
+export function canonicalJson(value) {
+  validateNumbers(value);
+  return `${JSON.stringify(sortValue(value))}\n`;
+}
+
+function keyOrder(left, right) {
+  const a = Array.from(left, (character) => character.codePointAt(0));
+  const b = Array.from(right, (character) => character.codePointAt(0));
+  for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return a.length - b.length;
+}
+
+function validateNumbers(value) {
+  if (typeof value === "number" && (!Number.isFinite(value) ||
+      (Number.isInteger(value) && !Number.isSafeInteger(value)))) {
+    throw new TypeError("canonical JSON contains an unsafe number");
+  }
+  if (Array.isArray(value)) value.forEach(validateNumbers);
+  else if (value && typeof value === "object") Object.values(value).forEach(validateNumbers);
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort(keyOrder).map((key) => [key, sortValue(value[key])]),
+    );
+  }
+  return value;
+}
+
+/**
+ * ONE CLASSIFICATION OF THE EVIDENCE A RUN USED, SPOKEN BY THIS DOOR TOO.
+ *
+ * PRD-UX-16: every load-bearing value in a step's inputs shows its origin — your brief, assumed,
+ * derived, your file, catalogue, default — and a value the program attributed to nothing renders
+ * an explicit marker, NEVER a blank. PRD-CLI-9: every door sees the same state. The web has said
+ * this for a while; this door printed `[3] step_finished` and nothing else, so the same run
+ * answered "where did this number come from?" on one surface and stayed silent on the other.
+ *
+ * The words come from `contract.js`, generated from `frontend/src/run/provenance.ts` — the
+ * web's own owner — so the two doors cannot drift into different vocabularies without the
+ * contract gate going red.
+ */
+export function originWord(origin) {
+  if (!origin || typeof origin !== "object" || typeof origin.kind !== "string") {
+    return ORIGIN_WORD.unattributed;
+  }
+  // A kind the engine invented and this build does not know is NOT silently "unstated": that
+  // would report an attribution failure where there is a version skew, and the two read
+  // completely differently to whoever is trying to trust the number.
+  if (!ORIGIN_KINDS.includes(origin.kind)) return `unknown origin \`${origin.kind}\``;
+  return ORIGIN_WORD[origin.kind];
+}
+
+/** `name = value unit  (origin word, ref)` — one line per input, in wire order. */
+export function inputLines(inputs) {
+  if (!Array.isArray(inputs)) return [];
+  return inputs.map((row) => {
+    const unit = typeof row?.unit === "string" && row.unit ? ` ${row.unit}` : "";
+    const word = originWord(row?.origin);
+    // The REF is what makes the word actionable — "your file" is a category, "your file
+    // (orbit.csv)" is an answer. It is omitted only when the origin does not carry one.
+    const ref = typeof row?.origin?.ref === "string" && row.origin.ref
+      ? ` ${row.origin.ref}` : "";
+    return `    ${row?.name ?? "?"} = ${JSON.stringify(row?.value)}${unit}  (${word}${ref})`;
+  });
+}
+
+export function human(value) {
+  if (value && typeof value === "object" && typeof value.run_id === "string") {
+    return `Run ${value.run_id}: ${value.terminal ?? value.state_hash ?? "accepted"}\n`;
+  }
+  if (value && typeof value === "object" && typeof value.name === "string") {
+    return `${value.name} (${value.id})\n`;
+  }
+  return canonicalJson(value);
+}
+
+export function progress(event) {
+  const head = `[${event.seq}] ${event.kind}\n`;
+  // A finished step is where a run's evidence becomes visible: its inputs each carry an
+  // origin. Every other kind keeps the one-line shape.
+  if (event?.kind !== "step_finished") return head;
+  const lines = inputLines(event?.payload?.step?.inputs ?? event?.payload?.inputs);
+  return lines.length ? `${head}${lines.join("\n")}\n` : head;
+}

package/src/mcp.js

@@ -0,0 +1,98 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+
+import { CliError, VecteurClient } from "./client.js";
+import { EVENT_KINDS } from "./contract.js";
+import { canonicalJson } from "./format.js";
+
+const projectInput = z.object({ project_id: z.string().min(1) }).strict();
+const submitInput = z.object({
+  project_id: z.string().min(1),
+  ask: z.string().min(1),
+}).strict();
+const runInput = z.object({ run_id: z.string().min(1) }).strict();
+const eventKind = z.enum(EVENT_KINDS);
+const eventOutput = z.object({
+  run_id: z.string().min(1), seq: z.number().int().safe().nonnegative(),
+  kind: eventKind,
+  payload: z.record(z.string(), z.json()),
+}).strict();
+const memberOutput = z.object({
+  user_id: z.string().min(1), email: z.string().min(1), display_name: z.string().min(1),
+  role: z.enum(["OWNER", "ADMIN", "EDITOR", "VIEWER"]),
+}).strict();
+const projectOutput = z.object({
+  id: z.string().min(1), name: z.string().min(1), org_id: z.string().min(1),
+  workspace_id: z.string().min(1), role: z.enum(["OWNER", "ADMIN", "EDITOR", "VIEWER"]),
+  role_source: z.enum(["workspace", "project"]), members: z.array(memberOutput),
+  created_at: z.number().int().safe(), updated_at: z.number().int().safe(),
+}).strict();
+const admittedOutput = z.object({
+  run_id: z.string().min(1), state_hash: z.string().min(1), result_hash: z.string().min(1),
+  profile: z.string().min(1),
+  terminal: z.enum(["ok", "partial", "blocked", "refused", "infeasible_physics", "capability_gap"]),
+  usage: z.object({
+    state: z.enum(["recorded", "usage_unavailable"]), provider: z.string().min(1),
+    model_id: z.string().min(1), input_tokens: z.number().int().safe().nonnegative().nullable(),
+    output_tokens: z.number().int().safe().nonnegative().nullable(),
+    cost_usd: z.number().finite().nonnegative().nullable(),
+  }).strict(),
+  events: z.array(eventOutput),
+}).strict();
+
+function success(value) {
+  return {
+    content: [{ type: "text", text: canonicalJson(value) }],
+    structuredContent: value,
+  };
+}
+
+function failure(error) {
+  const code = error instanceof CliError && /^[a-z][a-z0-9_]{0,63}$/.test(error.code)
+    ? error.code : "internal_error";
+  return {
+    isError: true,
+    content: [{ type: "text", text: canonicalJson({ error: { code } }) }],
+  };
+}
+
+function tool(server, name, description, inputSchema, outputSchema, call) {
+  server.registerTool(name, { description, inputSchema, outputSchema }, async (input, context) => {
+    try {
+      return success(await call(input, context));
+    } catch (error) {
+      return failure(error);
+    }
+  });
+}
+
+export function createVecteurMcpServer(client = new VecteurClient(), shutdownSignal = undefined) {
+  const server = new McpServer({ name: "vecteur", version: "0.1.0" });
+  const signal = (context) => shutdownSignal
+    ? AbortSignal.any([context.mcpReq.signal, shutdownSignal]) : context.mcpReq.signal;
+
+  tool(server, "vecteur_project_get", "Get one PAT-bound Vecteur project.", projectInput, projectOutput,
+    ({ project_id: projectId }, context) => client.projectGet(projectId, signal(context)));
+
+  tool(server, "vecteur_run_submit", "Submit one project turn and return its terminal record.",
+    submitInput, admittedOutput, async ({ project_id: projectId, ask }, context) => {
+      const progressToken = context.mcpReq._meta?.progressToken;
+      const onEvent = progressToken === undefined ? null : (event) => context.mcpReq.notify({
+          method: "notifications/progress",
+          params: {
+            progressToken,
+            progress: event.seq + 1,
+            message: event.kind,
+          },
+        });
+      return client.runSubmit(projectId, ask, onEvent, signal(context));
+    });
+
+  tool(server, "vecteur_run_get", "Get one terminal Vecteur run record.", runInput, admittedOutput,
+    ({ run_id: runId }, context) => client.runGet(runId, signal(context)));
+
+  tool(server, "vecteur_run_events", "Validate run events against its direct record.", runInput,
+    admittedOutput, ({ run_id: runId }, context) => client.runEvents(runId, null, signal(context)));
+
+  return server;
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Vecteur
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,70 +0,0 @@
-# Vecteur CLI
-
-Run space-mission-engineering queries from your terminal — an interactive agent that works on
-your local files. The `vecteur` CLI is a **thin, open-source client**: the agent, physics
-libraries, and models run on Vecteur's servers, so nothing proprietary ships in this package.
-
-![Vecteur CLI](https://raw.githubusercontent.com/vecteurspace/vecteur-cli/main/assets/screenshot.png)
-
-```
-npm install -g @vecteur/cli
-vecteur login          # opens your browser to approve this device
-cd my-mission/         # this directory becomes your workspace
-vecteur                # start an interactive session
-```
-
-## Install
-
-```bash
-npm install -g @vecteur/cli
-```
-
-Standalone binaries (no Node needed) and `brew` / `winget` / `curl` installers are published with
-each release — see the [releases page](https://github.com/vecteurspace/vecteur-cli/releases).
-
-## Use
-
-```bash
-vecteur                       # interactive session; the current directory is your workspace
-vecteur ask "period at 550 km circular" --project <id>
-vecteur ask "explain this" --file ./mission.md   # attach local files as context
-vecteur projects              # your projects (same as the web app at vecteur.space)
-vecteur whoami                # who you're signed in as
-```
-
-Inside the interactive session: type naturally, use `@path` to attach a local file, and
-`/help` for commands (`/files`, `/new`, `/open`, `/exit`).
-
-## Use it from an AI assistant (MCP)
-
-No install needed — connect Vecteur to Claude, Cursor, or any MCP-capable assistant:
-
-```bash
-claude mcp add --transport http vecteur https://api.vecteur.space/mcp
-```
-
-## Configuration
-
-- `VECTEUR_API_URL` — point at a different Vecteur instance (default `https://api.vecteur.space`).
-- `VECTEUR_TOKEN` — supply an access key non-interactively (CI).
-
-Credentials are stored at `~/.config/vecteur/config.json` (owner-only).
-
-## What this package contains (and doesn't)
-
-This is a client. It sends your queries (and any files you explicitly attach) to the Vecteur API
-and streams results back. It contains **no** agent logic, physics code, prompts, or API keys — a
-CI gate (`.github/workflows/ci.yml`) scans every change and the published tarball ships only
-compiled client code + LICENSE + README.
-
-## Development
-
-```bash
-npm install
-npm run build      # tsc typecheck + emit to dist/
-npm run typecheck
-```
-
-## License
-
-MIT — see [LICENSE](./LICENSE).

package/dist/api.js

@@ -1,89 +0,0 @@
-/**
- * Thin HTTP client for the Vecteur backend. Bearer auth (PAT or JWT — the CLI is
- * auth-method-agnostic so it works with whatever credential the platform issues).
- * Structured errors so commands can print actionable messages and set exit codes.
- */
-import { loadConfig } from "./config.js";
-import { VERSION } from "./version.js";
-export class ApiError extends Error {
-    status;
-    body;
-    retryAfter;
-    constructor(status, message, body, retryAfter) {
-        super(message);
-        this.status = status;
-        this.body = body;
-        this.retryAfter = retryAfter;
-        this.name = "ApiError";
-    }
-    /** A human, actionable line for the terminal. */
-    hint() {
-        switch (this.status) {
-            case 401:
-                return "Not authenticated. Run `vecteur login` (or set VECTEUR_TOKEN).";
-            case 403:
-                // Prefer the server's actual reason (e.g. "Project limit reached…", a plan gate);
-                // fall back to the scope hint only when the server gave no detail (bare status text).
-                return this.message && this.message.toLowerCase() !== "forbidden"
-                    ? this.message
-                    : "Forbidden — your token may lack the required scope for this action.";
-            case 429:
-                return `Rate limit / quota exceeded${this.retryAfter ? ` — retry in ${this.retryAfter}s` : ""}.`;
-            case 426:
-                return "This CLI is out of date. Run `vecteur update`.";
-            default:
-                return this.message;
-        }
-    }
-}
-export function apiBase() {
-    return loadConfig().apiUrl.replace(/\/+$/, "");
-}
-export async function api(path, opts = {}) {
-    const cfg = loadConfig();
-    const token = opts.token ?? cfg.token;
-    const url = new URL(apiBase() + path);
-    if (opts.query) {
-        for (const [k, v] of Object.entries(opts.query)) {
-            if (v !== undefined)
-                url.searchParams.set(k, String(v));
-        }
-    }
-    const headers = {
-        Accept: "application/json",
-        "User-Agent": `vecteur-cli/${VERSION}`, // lets the server 426-gate clients below a min version
-    };
-    if (token)
-        headers["Authorization"] = `Bearer ${token}`;
-    if (opts.body !== undefined)
-        headers["Content-Type"] = "application/json";
-    let res;
-    try {
-        res = await fetch(url, {
-            method: opts.method ?? "GET",
-            headers,
-            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
-        });
-    }
-    catch (e) {
-        throw new ApiError(0, `Network error reaching ${apiBase()} — is the API URL correct and are you online? (${e.message})`);
-    }
-    const text = await res.text();
-    let parsed = undefined;
-    if (text) {
-        try {
-            parsed = JSON.parse(text);
-        }
-        catch {
-            parsed = text;
-        }
-    }
-    if (!res.ok) {
-        const retryAfter = Number(res.headers.get("retry-after")) || undefined;
-        const detail = (parsed && typeof parsed === "object" && "detail" in parsed
-            ? String(parsed.detail)
-            : undefined) ?? res.statusText;
-        throw new ApiError(res.status, detail, parsed, retryAfter);
-    }
-    return parsed;
-}

package/dist/commands/ask.js

@@ -1,44 +0,0 @@
-/**
- * ask: one-shot — run an engineering query and stream the answer. A thin wrapper over the
- * shared runner (same streaming path the interactive `chat` REPL uses).
- */
-import { loadConfig } from "../config.js";
-import { buildLocalContextQuery, openBrowser, streamTurn, webBase } from "../runner.js";
-export async function ask(query, opts) {
-    const cfg = loadConfig();
-    if (!cfg.token) {
-        console.error("Not logged in. Run `vecteur login` first.");
-        process.exitCode = 1;
-        return;
-    }
-    if (!opts.project) {
-        console.error('A project is required: `vecteur ask "…" --project <id>` (or use `vecteur` for an interactive session).');
-        process.exitCode = 1;
-        return;
-    }
-    const effectiveQuery = buildLocalContextQuery(query, opts.file);
-    if (!opts.json)
-        console.error("▸ running…");
-    const res = await streamTurn({
-        project: opts.project,
-        query: effectiveQuery,
-        followUp: opts.followUp,
-        agent: opts.agent,
-        json: opts.json,
-        onStep: opts.json ? undefined : (s) => process.stderr.write(`  · ${s}\n`),
-    });
-    if (opts.json)
-        return;
-    if (res.failed) {
-        console.error(`✗ ${res.failed}`);
-        process.exitCode = 1;
-        return;
-    }
-    console.log("\n" + (res.answer ?? "(no answer)"));
-    const link = `${webBase()}/projects/${opts.project}`;
-    console.log(`\nView the full run (globe, tables, provenance): ${link}`);
-    if (res.sawVisual)
-        console.log("(this run produced visual artifacts best seen in the web view)");
-    if (opts.open)
-        void openBrowser(link);
-}

package/dist/commands/auth.js

@@ -1,76 +0,0 @@
-/** login / logout / whoami. */
-import { api, ApiError } from "../api.js";
-import { clearToken, loadConfig, saveToken } from "../config.js";
-import { openBrowser } from "../runner.js";
-export async function login(opts) {
-    if (opts.token) {
-        // Verify the token works before persisting.
-        await api("/api/v1/auth/me", { token: opts.token });
-        saveToken(opts.token, opts.apiUrl);
-        console.log("Logged in (token stored).");
-        return;
-    }
-    if (opts.email && opts.password) {
-        const res = await api("/api/v1/auth/login", {
-            method: "POST",
-            body: { email: opts.email, password: opts.password },
-        });
-        saveToken(res.access_token, opts.apiUrl);
-        console.log(`Logged in as ${res.user?.email ?? opts.email}.`);
-        return;
-    }
-    // Default: browser device flow (RFC 8628). No password touches the terminal.
-    await deviceLogin(opts.apiUrl, opts.noBrowser);
-}
-export function formatDeviceInstructions(verification_uri, user_code) {
-    return `To authorize this device, open:
-  ${verification_uri}?code=${user_code}
-or go to ${verification_uri} and enter the code:  ${user_code}`;
-}
-async function deviceLogin(apiUrl, noBrowser = false) {
-    const dc = await api("/api/v1/auth/device/code", { method: "POST", body: {} });
-    console.log(`\n${formatDeviceInstructions(dc.verification_uri, dc.user_code)}\n`);
-    if (!noBrowser) {
-        await openBrowser(`${dc.verification_uri}?code=${dc.user_code}`);
-    }
-    console.log(`Waiting for approval (expires in ${Math.round(dc.expires_in / 60)} min)…`);
-    const deadline = Date.now() + dc.expires_in * 1000;
-    const intervalMs = Math.max(2, dc.interval ?? 3) * 1000;
-    while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, intervalMs));
-        try {
-            const res = await api("/api/v1/auth/device/token", {
-                method: "POST",
-                body: { device_code: dc.device_code },
-            });
-            saveToken(res.token, apiUrl);
-            console.log("Approved — logged in.");
-            return;
-        }
-        catch (e) {
-            if (e instanceof ApiError && e.status === 428)
-                continue; // authorization_pending
-            throw e;
-        }
-    }
-    throw new ApiError(408, "Device authorization timed out. Run `vecteur login` again.");
-}
-export function logout() {
-    clearToken();
-    console.log("Logged out (local token cleared).");
-}
-export async function whoami() {
-    const cfg = loadConfig();
-    if (!cfg.token) {
-        console.log("Not logged in. Run `vecteur login`.");
-        process.exitCode = 1;
-        return;
-    }
-    const me = await api("/api/v1/auth/me");
-    console.log(`user:    ${me.email ?? me.username ?? me.id}`);
-    if (me.role)
-        console.log(`role:    ${me.role}`);
-    console.log(`token:   ${cfg.tokenPrefix ?? "(hidden)"}…`);
-    console.log(`api:     ${cfg.apiUrl}`);
-    // Quota is shown here once the platform exposes a per-credential quota endpoint (M-U3).
-}