@devosurf/tesser 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/index.ts

@@ -5,20 +5,25 @@
 import { execFile } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { promisify } from "node:util";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { extractAutomationManifest } from "@devosurf/tesser-sdk/internal";
 import { ApiClient } from "./client.js";
 import { readConfig, readLinkManifest, resolveTarget, writeConfig } from "./config.js";
 import { EXIT } from "./exit-codes.js";
-import { CliError, Output, toExit } from "./output.js";
+import { DEFAULT_INSTANCE_URL, resolveLoginInputs, type LoginCommandOptions } from "./login.js";
+import { completionScript } from "./completion.js";
+import { parseIntOption, projectFields, resolveJsonInput } from "./inputs.js";
+import { CliError, Output, toExit, type OutputFormat } from "./output.js";
 import { discoverLocalAutomations, loadAutomationDef } from "./project.js";
 import { authClaudeCode, authPi } from "./commands/auth.js";
 import { deploy } from "./commands/deploy.js";
+import { doctor } from "./commands/doctor.js";
 import { dev } from "./commands/dev.js";
 import { init } from "./commands/init.js";
 import { upgradeProject } from "./commands/project-docs.js";
 import { replay } from "./commands/replay.js";
 import { runTests } from "./commands/test.js";
+import { cliSchema } from "./schema.js";
 
 const exec = promisify(execFile);
 const program = new Command();
@@ -26,6 +31,7 @@ const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.u
 
 interface GlobalOpts {
   json?: boolean;
+  output?: "auto" | OutputFormat;
   url?: string;
   token?: string;
   profile?: string;
@@ -33,7 +39,20 @@ interface GlobalOpts {
 
 function setup(): { out: Output; opts: GlobalOpts } {
   const opts = program.opts<GlobalOpts>();
-  return { out: new Output(opts.json ?? false), opts };
+  return { out: new Output(resolveOutputFormat(opts)), opts };
+}
+
+function resolveOutputFormat(opts: GlobalOpts): OutputFormat {
+  if (opts.json) return "json";
+  const requested = opts.output ?? "auto";
+  if (requested === "auto") return process.stdout.isTTY ? "text" : "json";
+  return requested;
+}
+
+function isJsonRequestedFromArgv(): boolean {
+  const idx = process.argv.findIndex((arg) => arg === "--output" || arg === "-o");
+  const explicitOutput = idx >= 0 ? process.argv[idx + 1] : undefined;
+  return process.argv.includes("--json") || explicitOutput === "json" || explicitOutput === "ndjson";
 }
 
 function target(opts: GlobalOpts): ReturnType<typeof resolveTarget> {
@@ -61,18 +80,54 @@ program
   .name("tesser")
   .version(VERSION)
   .description("Code-first, agent-native automation. stdout = data, stderr = logs; --json everywhere.")
-  .option("--json", "machine output: one JSON document on stdout")
+  .option("--json", "machine output: one JSON document on stdout (alias for --output json)")
+  .addOption(new Option("-o, --output <format>", "output format").choices(["auto", "text", "json", "ndjson"]).default("auto"))
   .option("--url <url>", "instance URL (overrides tesser.json / profile)")
   .option("--token <token>", "API token (overrides TESSER_TOKEN / profile)")
-  .option("--profile <name>", "config profile");
+  .option("--profile <name>", "config profile")
+  .exitOverride()
+  .configureOutput({ outputError: () => {} })
+  .action(() => {
+    const out = new Output(resolveOutputFormat(program.opts<GlobalOpts>()));
+    if (out.json) out.fail(EXIT.USAGE, "missing command");
+    program.outputHelp({ error: true });
+    process.exit(EXIT.USAGE);
+  });
+
+program
+  .command("completion")
+  .argument("<shell>", "bash or zsh")
+  .description("print shell completion script")
+  .action((shell: string) => {
+    const { out } = setup();
+    try {
+      out.data(completionScript(shell), (script: string) => script.replace(/\n$/, ""));
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("schema")
+  .argument("[command...]", "optional command subtree, e.g. runs list")
+  .description("emit the machine-readable CLI contract (no auth, config, or network needed)")
+  .action((parts: string[]) => {
+    const { out } = setup();
+    try {
+      out.data(cliSchema(VERSION, parts.length > 0 ? parts.join(" ") : undefined));
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
 
 program
   .command("init")
   .argument("<name>", "project name (kebab-case)")
   .option("--dir <dir>", "parent directory")
   .option("--instance <url>", "instance URL to write into tesser.json")
+  .option("--force", "write into an existing non-empty directory")
   .description("scaffold a new Project (one repo of automations)")
-  .action((name: string, cmdOpts: { dir?: string; instance?: string }) => {
+  .action((name: string, cmdOpts: { dir?: string; instance?: string; force?: boolean }) => {
     const { out } = setup();
     try {
       init(out, name, cmdOpts, VERSION);
@@ -95,22 +150,23 @@ program
 
 program
   .command("login")
-  .option("--token <token>", "API token from the instance (printed at first boot)")
-  .option("--instance <url>", "instance URL", "http://localhost:8377")
+  .option("--token <token>", "API token from the instance (discouraged: argv can leak; prefer --token-stdin)")
+  .option("--token-stdin", "read the API token from stdin")
+  .option("--url <url>", `instance URL (defaults to ${DEFAULT_INSTANCE_URL})`)
+  .option("--instance <url>", "deprecated alias for --url")
   .option("--save-profile <name>", "profile name", "default")
   .description("store instance credentials in ~/.config/tesser (or use env TESSER_TOKEN)")
-  .action(async (cmdOpts: { token?: string; instance: string; saveProfile: string }) => {
+  .action(async (cmdOpts: LoginCommandOptions) => {
     const { out, opts } = setup();
     try {
-      const token = cmdOpts.token ?? opts.token;
-      if (!token) throw new CliError(EXIT.USAGE, "missing required option '--token <token>'");
-      const client = new ApiClient(cmdOpts.instance, token);
+      const { instance, token } = await resolveLoginInputs(cmdOpts, opts);
+      const client = new ApiClient(instance, token);
       await client.get("/health"); // verify before storing
       const config = readConfig();
-      config.profiles = { ...config.profiles, [cmdOpts.saveProfile]: { url: cmdOpts.instance, token } };
+      config.profiles = { ...config.profiles, [cmdOpts.saveProfile]: { url: instance, token } };
       config.current = cmdOpts.saveProfile;
       writeConfig(config);
-      out.data({ profile: cmdOpts.saveProfile, url: cmdOpts.instance }, () => `logged in to ${cmdOpts.instance} (profile "${cmdOpts.saveProfile}")`);
+      out.data({ profile: cmdOpts.saveProfile, url: instance }, () => `logged in to ${instance} (profile "${cmdOpts.saveProfile}")`);
     } catch (err) {
       toExit(err, out);
     }
@@ -220,7 +276,8 @@ program
     const { out, opts } = setup();
     try {
       const { name, root } = requireProject(opts);
-      await dev(out, root, name, { port: Number(cmdOpts.port), ...(cmdOpts.watch === false ? { watch: false } : {}) });
+      const port = parseIntOption(cmdOpts.port, "--port", { min: 1, max: 65535 });
+      await dev(out, root, name, { port, ...(cmdOpts.watch === false ? { watch: false } : {}) });
     } catch (err) {
       toExit(err, out);
     }
@@ -263,6 +320,43 @@ auth
     }
   });
 
+const harnessConnect = program.command("harness").description("brokered Harness helpers").command("connect").description("connect a Harness credential through a Tesser connect link");
+harnessConnect
+  .command("claude-code")
+  .requiredOption("--connect <urlOrToken>", "Tesser /connect/<token> URL or token")
+  .option("--mode <mode>", "subscription or apiKey", "subscription")
+  .option("--token-stdin", "read token from stdin instead of running claude setup-token")
+  .option("--from-env <name>", "read token from an environment variable")
+  .option("--scope <scope>", "workspace or per_user", "workspace")
+  .option("--end-user-id <id>", "end-user id for per_user connections")
+  .option("--bin <path>", "claude binary", "claude")
+  .description("connect Claude Code as a brokered Harness; alias of `tesser auth claude-code`")
+  .action(async (cmdOpts: { connect: string; mode?: string; tokenStdin?: boolean; fromEnv?: string; scope?: string; endUserId?: string; bin?: string }) => {
+    const { out, opts } = setup();
+    try {
+      await authClaudeCode(out, target(opts).url, cmdOpts);
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+harnessConnect
+  .command("pi")
+  .requiredOption("--connect <urlOrToken>", "Tesser /connect/<token> URL or token")
+  .option("--mode <mode>", "anthropicOAuth or anthropicApiKey", "anthropicOAuth")
+  .option("--token-stdin", "read token from stdin")
+  .option("--from-env <name>", "read token from an environment variable")
+  .option("--scope <scope>", "workspace or per_user", "workspace")
+  .option("--end-user-id <id>", "end-user id for per_user connections")
+  .description("connect Pi as a brokered Harness; alias of `tesser auth pi`")
+  .action(async (cmdOpts: { connect: string; mode?: string; tokenStdin?: boolean; fromEnv?: string; scope?: string; endUserId?: string }) => {
+    const { out, opts } = setup();
+    try {
+      await authPi(out, target(opts).url, cmdOpts);
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
 program
   .command("connect")
   .option("--wait", "poll until the human completes the link")
@@ -285,19 +379,20 @@ program
         out.data({ url: null, requirements: [] }, () => "nothing missing — all requirements are satisfied");
         return;
       }
-      out.data(minted, () => `open in a browser to connect:\n  ${minted.url}`);
-      if (cmdOpts.wait) {
-        for (;;) {
-          await new Promise((r) => setTimeout(r, 2000));
-          const status = await client.get<{ status: string }>(`/connect-links/${minted.token}/status`);
-          if (status.status === "completed") {
-            out.log("connect link completed ✓");
-            return;
-          }
-          if (status.status === "expired") throw new CliError(EXIT.HALTED_CREDENTIALS, "connect link expired");
+      if (!cmdOpts.wait) {
+        out.data(minted, () => `open in a browser to connect:\n  ${minted.url}`);
+        process.exit(EXIT.HALTED_CREDENTIALS);
+      }
+      out.log(`open in a browser to connect:\n  ${minted.url}`);
+      for (;;) {
+        await new Promise((r) => setTimeout(r, 2000));
+        const status = await client.get<{ status: string }>(`/connect-links/${minted.token}/status`);
+        if (status.status === "completed") {
+          out.data({ ...minted, status: "completed" }, () => "connect link completed ✓");
+          return;
         }
+        if (status.status === "expired") throw new CliError(EXIT.HALTED_CREDENTIALS, "connect link expired");
       }
-      process.exit(EXIT.HALTED_CREDENTIALS);
     } catch (err) {
       toExit(err, out);
     }
@@ -333,7 +428,7 @@ secrets
       const value = Buffer.concat(chunks).toString("utf8").replace(/\n$/, "");
       if (value.length === 0) throw new CliError(EXIT.USAGE, "empty value on stdin");
       await api(opts).put(`/secrets/${encodeURIComponent(name)}`, { value });
-      out.data({ set: name }, () => `secret "${name}" set ✓`);
+      out.data({ set: name, changed: true }, () => `secret "${name}" set ✓`);
     } catch (err) {
       toExit(err, out);
     }
@@ -344,7 +439,8 @@ secrets
   .action(async (name: string) => {
     const { out, opts } = setup();
     try {
-      out.data(await api(opts).delete(`/secrets/${encodeURIComponent(name)}`));
+      const result = await api(opts).delete<{ deleted: boolean }>(`/secrets/${encodeURIComponent(name)}`);
+      out.data({ ...result, changed: result.deleted });
     } catch (err) {
       toExit(err, out);
     }
@@ -356,17 +452,23 @@ runs
   .option("--automation <id>")
   .option("--status <status>")
   .option("--limit <n>", "max rows", "25")
-  .action(async (cmdOpts: { automation?: string; status?: string; limit: string }) => {
+  .option("--offset <n>", "rows to skip", "0")
+  .option("--fields <csv>", "comma-separated fields to include in each run")
+  .action(async (cmdOpts: { automation?: string; status?: string; limit: string; offset: string; fields?: string }) => {
     const { out, opts } = setup();
     try {
       const { name } = requireProject(opts);
-      const params = new URLSearchParams({ project: name, limit: cmdOpts.limit });
+      const limit = parseIntOption(cmdOpts.limit, "--limit", { min: 1, max: 200 });
+      const offset = parseIntOption(cmdOpts.offset, "--offset", { min: 0 });
+      const params = new URLSearchParams({ project: name, limit: String(limit), offset: String(offset) });
       if (cmdOpts.automation) params.set("automation", cmdOpts.automation);
       if (cmdOpts.status) params.set("status", cmdOpts.status);
-      const data = await api(opts).get<{ runs: Array<Record<string, unknown>> }>(`/runs?${params}`);
-      out.data(data, (d: { runs: Array<{ id: string; automation_id: string; status: string; trigger_kind: string; created_at: string }> }) =>
-        d.runs.map((r) => `${r.id}  ${r.automation_id}  ${r.status}  (${r.trigger_kind})  ${r.created_at}`).join("\n") || "(no runs)",
-      );
+      const data = await api(opts).get<{ runs: Array<Record<string, unknown>>; total?: number; limit?: number; offset?: number; truncated?: boolean }>(`/runs?${params}`);
+      const projected = { ...data, runs: projectFields(data.runs, cmdOpts.fields) };
+      out.data(projected, (d: { runs: Array<{ id?: string; automation_id?: string; status?: string; trigger_kind?: string; created_at?: string }>; total?: number; truncated?: boolean }) => {
+        const rows = d.runs.map((r) => `${r.id ?? "?"}  ${r.automation_id ?? "?"}  ${r.status ?? "?"}  (${r.trigger_kind ?? "?"})  ${r.created_at ?? "?"}`).join("\n") || "(no runs)";
+        return d.truncated ? `${rows}\n(showing ${d.runs.length} of ${d.total ?? "?"}; use --offset for more)` : rows;
+      });
     } catch (err) {
       toExit(err, out);
     }
@@ -374,10 +476,14 @@ runs
 runs
   .command("show")
   .argument("<runId>")
-  .action(async (runId: string) => {
+  .option("--log-limit <n>", "max log rows", "100")
+  .option("--log-offset <n>", "log rows to skip", "0")
+  .action(async (runId: string, cmdOpts: { logLimit: string; logOffset: string }) => {
     const { out, opts } = setup();
     try {
-      out.data(await api(opts).get(`/runs/${runId}`));
+      const logLimit = parseIntOption(cmdOpts.logLimit, "--log-limit", { min: 1, max: 500 });
+      const logOffset = parseIntOption(cmdOpts.logOffset, "--log-offset", { min: 0 });
+      out.data(await api(opts).get(`/runs/${runId}?${new URLSearchParams({ logLimit: String(logLimit), logOffset: String(logOffset) })}`));
     } catch (err) {
       toExit(err, out);
     }
@@ -386,13 +492,15 @@ runs
   .command("trigger")
   .argument("<automation>")
   .option("--input <json>", "input payload as JSON")
+  .option("--input-file <path>", "read input JSON from a file, or '-' for stdin")
   .option("--env <env>", "environment", "production")
-  .action(async (automation: string, cmdOpts: { input?: string; env: string }) => {
+  .action(async (automation: string, cmdOpts: { input?: string; inputFile?: string; env: string }) => {
     const { out, opts } = setup();
     try {
       const { name } = requireProject(opts);
       const body: Record<string, unknown> = { project: name, automation, env: cmdOpts.env };
-      if (cmdOpts.input !== undefined) body["input"] = JSON.parse(cmdOpts.input);
+      const input = await resolveJsonInput({ literal: cmdOpts.input, file: cmdOpts.inputFile, label: "input" });
+      if (input !== undefined) body["input"] = input;
       out.data(await api(opts).post("/runs", body));
     } catch (err) {
       toExit(err, out);
@@ -403,12 +511,14 @@ runs
   .argument("<runId>")
   .argument("<name>")
   .option("--payload <json>", "signal payload as JSON")
-  .action(async (runId: string, name: string, cmdOpts: { payload?: string }) => {
+  .option("--payload-file <path>", "read signal payload JSON from a file, or '-' for stdin")
+  .action(async (runId: string, name: string, cmdOpts: { payload?: string; payloadFile?: string }) => {
     const { out, opts } = setup();
     try {
+      const payload = await resolveJsonInput({ literal: cmdOpts.payload, file: cmdOpts.payloadFile, label: "payload" });
       out.data(
         await api(opts).post(`/runs/${runId}/signals/${encodeURIComponent(name)}`, {
-          ...(cmdOpts.payload !== undefined ? { payload: JSON.parse(cmdOpts.payload) } : {}),
+          ...(payload !== undefined ? { payload } : {}),
         }),
       );
     } catch (err) {
@@ -421,7 +531,8 @@ runs
   .action(async (runId: string) => {
     const { out, opts } = setup();
     try {
-      out.data(await api(opts).post(`/runs/${runId}/cancel`));
+      const result = await api(opts).post<{ cancelled: boolean }>(`/runs/${runId}/cancel`);
+      out.data({ ...result, changed: result.cancelled });
     } catch (err) {
       toExit(err, out);
     }
@@ -431,27 +542,49 @@ program
   .command("logs")
   .argument("<runId>")
   .option("--follow", "poll until the run settles")
+  .option("--limit <n>", "max log rows per page", "100")
+  .option("--offset <n>", "log rows to skip", "0")
   .description("step logs for one run")
-  .action(async (runId: string, cmdOpts: { follow?: boolean }) => {
+  .action(async (runId: string, cmdOpts: { follow?: boolean; limit: string; offset: string }) => {
     const { out, opts } = setup();
     try {
       const client = api(opts);
-      let printed = 0;
+      const limit = parseIntOption(cmdOpts.limit, "--limit", { min: 1, max: 500 });
+      let offset = parseIntOption(cmdOpts.offset, "--offset", { min: 0 });
+      let finalDetail: {
+        run: { status: string };
+        logs: Array<{ step: string | null; level: string; msg: string; created_at: string }>;
+        logsTruncated?: boolean;
+      } | null = null;
       for (;;) {
         const detail = await client.get<{
           run: { status: string };
           logs: Array<{ step: string | null; level: string; msg: string; created_at: string }>;
-        }>(`/runs/${runId}`);
-        const fresh = detail.logs.slice(printed);
-        printed = detail.logs.length;
-        if (out.json && !cmdOpts.follow) {
-          out.data(detail);
+          logsTotal?: number;
+          logsLimit?: number;
+          logsOffset?: number;
+          logsTruncated?: boolean;
+        }>(`/runs/${runId}?${new URLSearchParams({ logLimit: String(limit), logOffset: String(offset) })}`);
+        finalDetail = detail;
+        if (!cmdOpts.follow) {
+          if (out.json) out.data(detail);
+          else {
+            for (const l of detail.logs) process.stdout.write(`[${l.level}]${l.step ? ` (${l.step})` : ""} ${l.msg}\n`);
+            if (detail.logsTruncated) out.log(`showing ${detail.logs.length} of ${detail.logsTotal ?? "?"}; use --offset for more`);
+          }
           return;
         }
-        for (const l of fresh) out.log(`[${l.level}]${l.step ? ` (${l.step})` : ""} ${l.msg}`);
-        if (!cmdOpts.follow || ["completed", "failed", "cancelled"].includes(detail.run.status)) {
-          if (!out.json) out.log(`run ${detail.run.status}`);
-          else out.data(detail);
+        if (out.format === "ndjson") {
+          for (const l of detail.logs) process.stdout.write(JSON.stringify({ log: l }) + "\n");
+        } else if (!out.json) {
+          for (const l of detail.logs) process.stdout.write(`[${l.level}]${l.step ? ` (${l.step})` : ""} ${l.msg}\n`);
+        }
+        offset += detail.logs.length;
+        if (detail.logsTruncated) continue;
+        if (["completed", "failed", "cancelled"].includes(detail.run.status)) {
+          if (out.format === "ndjson") process.stdout.write(JSON.stringify({ run: detail.run }) + "\n");
+          else if (out.json) out.data(finalDetail);
+          else out.log(`run ${detail.run.status}`);
           return;
         }
         await new Promise((r) => setTimeout(r, 1000));
@@ -485,13 +618,27 @@ program
     const { out, opts } = setup();
     try {
       const { name } = requireProject(opts);
-      out.data(
-        await api(opts).post(`/projects/${name}/rollback`, {
-          automation,
-          toVersion: Number(cmdOpts.to),
-          env: cmdOpts.env,
-        }),
-      );
+      const toVersion = parseIntOption(cmdOpts.to, "--to", { min: 1 });
+      const result = await api(opts).post<Record<string, unknown>>(`/projects/${name}/rollback`, {
+        automation,
+        toVersion,
+        env: cmdOpts.env,
+      });
+      out.data({ ...result, changed: true });
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("doctor")
+  .option("--no-network", "skip Instance health checks")
+  .description("agent preflight: local Project, auth, pins, and optional Instance health")
+  .action(async (cmdOpts: { network?: boolean }) => {
+    const { out, opts } = setup();
+    try {
+      const resolved = target(opts);
+      await doctor(out, { version: VERSION, target: resolved, client: new ApiClient(resolved.url, resolved.token), network: cmdOpts.network !== false });
     } catch (err) {
       toExit(err, out);
     }
@@ -516,6 +663,25 @@ program
   });
 
 program.parseAsync().catch((err) => {
-  const out = new Output(process.argv.includes("--json"));
+  if (isCommanderHelp(err)) process.exit(err.exitCode ?? EXIT.OK);
+  const out = new Output(isJsonRequestedFromArgv() ? "json" : process.stdout.isTTY ? "text" : "json");
+  if (isCommanderUsageError(err)) {
+    out.fail(EXIT.USAGE, err.message.replace(/^error: /, ""));
+  }
   toExit(err, out);
 });
+
+function isCommanderHelp(err: unknown): err is { code: string; exitCode?: number } {
+  return typeof err === "object" && err !== null && (err as { code?: unknown }).code === "commander.helpDisplayed";
+}
+
+function isCommanderUsageError(err: unknown): err is { code: string; message: string } {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    typeof (err as { code?: unknown }).code === "string" &&
+    (err as { code: string }).code.startsWith("commander.") &&
+    typeof (err as { message?: unknown }).message === "string"
+  );
+}
+

package/src/inputs.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "vitest";
+import { parseIntOption, parseJsonLiteral, projectFields } from "./inputs.js";
+
+
+describe("CLI input helpers", () => {
+  test("turns malformed JSON into a usage error", () => {
+    expect(() => parseJsonLiteral("{bad}", "--input")).toThrow("invalid JSON for --input");
+  });
+
+  test("validates integer options", () => {
+    expect(parseIntOption("25", "--limit", { min: 1, max: 200 })).toBe(25);
+    expect(() => parseIntOption("0", "--limit", { min: 1 })).toThrow("--limit must be >= 1");
+    expect(() => parseIntOption("abc", "--limit")).toThrow("--limit must be an integer");
+  });
+
+  test("projects list fields without mutating the source rows", () => {
+    const rows = [{ id: "r1", status: "completed", secret: "hidden" }];
+    expect(projectFields(rows, "id,status")).toEqual([{ id: "r1", status: "completed" }]);
+    expect(rows[0]?.secret).toBe("hidden");
+  });
+});

package/src/inputs.ts

@@ -0,0 +1,64 @@
+import { readFile } from "node:fs/promises";
+import { EXIT } from "./exit-codes.js";
+import { CliError } from "./output.js";
+
+export function parseJsonLiteral(value: string, label: string): unknown {
+  try {
+    return JSON.parse(value) as unknown;
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new CliError(EXIT.USAGE, `invalid JSON for ${label}: ${detail}`);
+  }
+}
+
+export async function readTextInput(pathOrDash: string, label: string): Promise<string> {
+  if (pathOrDash === "-") {
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+    return Buffer.concat(chunks).toString("utf8");
+  }
+  try {
+    return await readFile(pathOrDash, "utf8");
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new CliError(EXIT.USAGE, `cannot read ${label} file ${pathOrDash}: ${detail}`);
+  }
+}
+
+export async function resolveJsonInput(opts: {
+  literal?: string | undefined;
+  file?: string | undefined;
+  label: string;
+}): Promise<unknown | undefined> {
+  if (opts.literal !== undefined && opts.file !== undefined) {
+    throw new CliError(EXIT.USAGE, `use either --${opts.label} or --${opts.label}-file, not both`);
+  }
+  if (opts.literal !== undefined) return parseJsonLiteral(opts.literal, `--${opts.label}`);
+  if (opts.file !== undefined) return parseJsonLiteral(await readTextInput(opts.file, `--${opts.label}`), `--${opts.label}-file`);
+  return undefined;
+}
+
+export function parseIntOption(value: string, label: string, opts: { min?: number; max?: number } = {}): number {
+  if (!/^\d+$/.test(value)) throw new CliError(EXIT.USAGE, `${label} must be an integer`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) throw new CliError(EXIT.USAGE, `${label} is too large`);
+  if (opts.min !== undefined && parsed < opts.min) throw new CliError(EXIT.USAGE, `${label} must be >= ${opts.min}`);
+  if (opts.max !== undefined && parsed > opts.max) throw new CliError(EXIT.USAGE, `${label} must be <= ${opts.max}`);
+  return parsed;
+}
+
+export function projectFields<T extends Record<string, unknown>>(items: T[], fieldsCsv?: string | undefined): Array<Record<string, unknown>> {
+  if (fieldsCsv === undefined || fieldsCsv.trim() === "") return items;
+  const fields = fieldsCsv
+    .split(",")
+    .map((field) => field.trim())
+    .filter(Boolean);
+  if (fields.length === 0) return items;
+  return items.map((item) => {
+    const out: Record<string, unknown> = {};
+    for (const field of fields) {
+      if (field in item) out[field] = item[field];
+    }
+    return out;
+  });
+}

package/src/login.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "vitest";
+import { DEFAULT_INSTANCE_URL, resolveLoginInputs, resolveLoginInstance } from "./login.js";
+
+describe("tesser login target resolution", () => {
+  test("accepts --url on the login command", () => {
+    expect(resolveLoginInstance({ url: "https://inst.example" }, {})).toBe("https://inst.example");
+  });
+
+  test("accepts the global --url before login", () => {
+    expect(resolveLoginInstance({}, { url: "https://global.example" })).toBe("https://global.example");
+  });
+
+  test("keeps --instance as a backwards-compatible alias", () => {
+    expect(resolveLoginInstance({ instance: "https://old.example" }, { url: "https://global.example" })).toBe("https://old.example");
+  });
+
+  test("defaults to the local dev instance", () => {
+    expect(resolveLoginInstance({}, {})).toBe(DEFAULT_INSTANCE_URL);
+  });
+
+  test("rejects ambiguous token sources before prompting", async () => {
+    await expect(
+      resolveLoginInputs(
+        { token: "cmd-token", tokenStdin: true, saveProfile: "default" },
+        { url: "https://inst.example" },
+      ),
+    ).rejects.toThrow("use either --token/--token-stdin");
+  });
+
+  test("accepts a command token without prompting", async () => {
+    await expect(
+      resolveLoginInputs(
+        { token: "cmd-token", saveProfile: "default", url: "https://inst.example" },
+        {},
+      ),
+    ).resolves.toEqual({ instance: "https://inst.example", token: "cmd-token" });
+  });
+});