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

package/src/login.ts

@@ -0,0 +1,109 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stderr as output } from "node:process";
+import { DEFAULT_INSTANCE_URL } from "./config.js";
+import { EXIT } from "./exit-codes.js";
+import { CliError } from "./output.js";
+
+export { DEFAULT_INSTANCE_URL };
+
+export interface LoginCommandOptions {
+  token?: string;
+  tokenStdin?: boolean;
+  url?: string;
+  instance?: string;
+  saveProfile: string;
+}
+
+export interface LoginGlobalOptions {
+  url?: string;
+  token?: string;
+}
+
+export function resolveLoginInstance(cmdOpts: Pick<LoginCommandOptions, "url" | "instance">, globalOpts: Pick<LoginGlobalOptions, "url">): string {
+  return cmdOpts.url ?? cmdOpts.instance ?? globalOpts.url ?? DEFAULT_INSTANCE_URL;
+}
+
+export async function resolveLoginInputs(
+  cmdOpts: LoginCommandOptions,
+  globalOpts: LoginGlobalOptions,
+): Promise<{ instance: string; token: string }> {
+  if ((cmdOpts.token !== undefined || globalOpts.token !== undefined) && cmdOpts.tokenStdin === true) {
+    throw new CliError(EXIT.USAGE, "use either --token/--token-stdin, not both");
+  }
+
+  const token = cmdOpts.token ?? globalOpts.token ?? (cmdOpts.tokenStdin === true ? await readTrimmedStdin("token") : undefined);
+  const instance = resolveLoginInstance(cmdOpts, globalOpts);
+  if (token !== undefined && token.length > 0) return { instance, token };
+
+  if (isInteractive()) {
+    const promptedInstance = await promptLine("Instance URL", instance);
+    const promptedToken = await promptSecret("API token");
+    if (promptedToken.length === 0) throw new CliError(EXIT.USAGE, "empty API token");
+    return { instance: promptedInstance || instance, token: promptedToken };
+  }
+
+  throw new CliError(
+    EXIT.USAGE,
+    "missing API token — pass --token-stdin, set TESSER_TOKEN, or run `tesser login` in an interactive terminal",
+  );
+}
+
+function isInteractive(): boolean {
+  return input.isTTY === true && output.isTTY === true;
+}
+
+async function readTrimmedStdin(label: string): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of input) chunks.push(chunk as Buffer);
+  const value = Buffer.concat(chunks).toString("utf8").trim();
+  if (value.length === 0) throw new CliError(EXIT.USAGE, `empty ${label} on stdin`);
+  return value;
+}
+
+async function promptLine(label: string, defaultValue: string): Promise<string> {
+  const rl = createInterface({ input, output });
+  try {
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
+    return (await rl.question(`${label}${suffix}: `)).trim() || defaultValue;
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptSecret(label: string): Promise<string> {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== "function") {
+    throw new CliError(EXIT.USAGE, "cannot prompt for a token without an interactive terminal; use --token-stdin");
+  }
+
+  output.write(`${label}: `);
+  input.setRawMode(true);
+  input.resume();
+  input.setEncoding("utf8");
+
+  return await new Promise<string>((resolve, reject) => {
+    let value = "";
+    const cleanup = () => {
+      input.off("data", onData);
+      input.setRawMode(false);
+      output.write("\n");
+    };
+    const onData = (char: string) => {
+      if (char === "\u0003") {
+        cleanup();
+        reject(new CliError(EXIT.USAGE, "login cancelled"));
+        return;
+      }
+      if (char === "\r" || char === "\n") {
+        cleanup();
+        resolve(value.trim());
+        return;
+      }
+      if (char === "\u007f" || char === "\b") {
+        value = value.slice(0, -1);
+        return;
+      }
+      value += char;
+    };
+    input.on("data", onData);
+  });
+}

package/src/output.ts

@@ -3,13 +3,24 @@
 
 import { EXIT, type ExitCode } from "./exit-codes.js";
 
+export type OutputFormat = "text" | "json" | "ndjson";
+
 export class Output {
-  constructor(readonly json: boolean) {}
+  readonly format: OutputFormat;
+
+  constructor(formatOrJson: OutputFormat | boolean) {
+    this.format = typeof formatOrJson === "boolean" ? (formatOrJson ? "json" : "text") : formatOrJson;
+  }
+
+  get json(): boolean {
+    return this.format !== "text";
+  }
 
   /** Emit the command's data result. `human` renders the no-JSON form. */
   data(value: unknown, human?: (v: never) => string): void {
     if (this.json) {
-      process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+      const pretty = this.format === "json";
+      process.stdout.write(JSON.stringify(value, null, pretty ? 2 : 0) + "\n");
     } else {
       process.stdout.write((human ? human(value as never) : JSON.stringify(value, null, 2)) + "\n");
     }
@@ -22,7 +33,8 @@ export class Output {
 
   fail(code: ExitCode, message: string, extra?: Record<string, unknown>): never {
     if (this.json) {
-      process.stdout.write(JSON.stringify({ error: { code, message, ...extra } }, null, 2) + "\n");
+      const pretty = this.format === "json";
+      process.stdout.write(JSON.stringify({ error: { code, message, ...extra } }, null, pretty ? 2 : 0) + "\n");
     } else {
       process.stderr.write(`error: ${message}\n`);
       if (extra) process.stderr.write(JSON.stringify(extra, null, 2) + "\n");

package/src/schema.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "vitest";
+import { cliSchema } from "./schema.js";
+
+
+describe("CLI schema", () => {
+  test("is available without runtime inputs and includes agent-critical contracts", () => {
+    const schema = cliSchema("0.0.0") as {
+      clispec: string;
+      global_args: Array<{ name: string }>;
+      commands: Array<{ name: string; mutating: boolean }>;
+      errors: Array<{ kind: string; exit_code: number }>;
+    };
+
+    expect(schema.clispec).toBe("0.2");
+    expect(schema.global_args.map((arg) => arg.name)).toContain("--output");
+    expect(schema.commands.find((command) => command.name === "runs list")?.mutating).toBe(false);
+    expect(schema.commands.find((command) => command.name === "secrets set")?.mutating).toBe(true);
+    expect(schema.errors.find((error) => error.kind === "halted_credentials")?.exit_code).toBe(4);
+  });
+
+  test("can be narrowed to a command subtree", () => {
+    const schema = cliSchema("0.0.0", "runs") as { commands: Array<{ name: string }> };
+    expect(schema.commands.length).toBeGreaterThan(1);
+    expect(schema.commands.every((command) => command.name.startsWith("runs"))).toBe(true);
+  });
+});

package/src/schema.ts

@@ -0,0 +1,289 @@
+import { EXIT } from "./exit-codes.js";
+
+const errorRows = [
+  ["error", EXIT.ERROR, true, "Unexpected internal error"],
+  ["usage", EXIT.USAGE, false, "Bad arguments or missing Project context"],
+  ["tests_failed", EXIT.TESTS_FAILED, false, "Local validation failed"],
+  ["halted_credentials", EXIT.HALTED_CREDENTIALS, false, "Deploy/connect halted on missing credentials"],
+  ["auth", EXIT.AUTH, false, "Cannot reach or authenticate against the Instance"],
+  ["not_found", EXIT.NOT_FOUND, false, "Requested resource does not exist"],
+  ["conflict", EXIT.CONFLICT, false, "Operation conflicts with current state"],
+  ["deploy_failed", EXIT.DEPLOY_FAILED, false, "Build, test gate, or deploy failed"],
+] as const;
+
+const commands = [
+  {
+    name: "schema",
+    description: "Emit the machine-readable CLI contract without auth, config, or network",
+    mutating: false,
+    args: [{ name: "command", type: "string[]", required: false }],
+    output_fields: ["clispec", "name", "version", "global_args", "commands", "errors", "outcomes"],
+  },
+  {
+    name: "completion",
+    description: "Print a shell completion script",
+    mutating: false,
+    args: [{ name: "shell", type: "string", enum: ["bash", "zsh"], required: true }],
+    output_fields: [],
+  },
+  {
+    name: "doctor",
+    description: "Agent preflight for local Project, auth, pins, and optional Instance health",
+    mutating: false,
+    args: [{ name: "--no-network", type: "boolean", required: false, default: false }],
+    output_fields: ["ok", "cliVersion", "node", "cwd", "project", "projectRoot", "instance", "auth", "checks", "network"],
+  },
+  {
+    name: "init",
+    description: "Scaffold a new Project",
+    mutating: true,
+    args: [
+      { name: "name", type: "string", required: true },
+      { name: "--dir", type: "string", required: false },
+      { name: "--instance", type: "string", required: false },
+      { name: "--force", type: "boolean", required: false, default: false },
+    ],
+    output_fields: ["created", "tesserVersion", "docs", "next"],
+  },
+  {
+    name: "upgrade",
+    description: "Pin Tesser packages to this CLI version and refresh generated Project docs",
+    mutating: true,
+    args: [],
+    output_fields: ["upgraded", "tesserVersion", "docs", "next"],
+  },
+  {
+    name: "login",
+    description: "Verify and store Instance API credentials in a local profile",
+    mutating: true,
+    args: [
+      { name: "--url", type: "string", required: false, default: "http://localhost:8377" },
+      { name: "--token-stdin", type: "boolean", required: false, default: false },
+      { name: "--token", type: "string", required: false, secret: true, deprecated: "Prefer --token-stdin" },
+      { name: "--save-profile", type: "string", required: false, default: "default" },
+    ],
+    output_fields: ["profile", "url"],
+  },
+  {
+    name: "link",
+    description: "Register this Project on the Instance and wire git-sync",
+    mutating: true,
+    args: [{ name: "--repo", type: "string", required: false }],
+    output_fields: ["id", "name", "repoUrl", "deployKeyPublic", "webhookSetupUrl"],
+  },
+  {
+    name: "status",
+    description: "Instance and Project deploy status",
+    mutating: false,
+    args: [],
+    output_fields: ["instance", "health", "status", "project", "deploy"],
+  },
+  {
+    name: "test",
+    description: "Run colocated tests plus generated smoke tests",
+    mutating: false,
+    args: [
+      { name: "--smoke-only", type: "boolean", required: false, default: false },
+      { name: "--automation", type: "string", required: false },
+    ],
+    output_fields: ["passed", "colocated", "smoke", "failures"],
+  },
+  {
+    name: "build",
+    description: "Build and statically extract automation manifests locally",
+    mutating: false,
+    args: [],
+    output_fields: ["automations"],
+  },
+  {
+    name: "dev",
+    description: "Run a local Instance with embedded Postgres and deploy-on-change",
+    mutating: true,
+    args: [
+      { name: "--port", type: "integer", required: false, default: 8377 },
+      { name: "--no-watch", type: "boolean", required: false, default: false },
+    ],
+    output_fields: [],
+  },
+  {
+    name: "deploy",
+    description: "Sync git or a local tree to the Instance and promote on green",
+    mutating: true,
+    args: [
+      { name: "--ref", type: "string", required: false },
+      { name: "--local", type: "boolean", required: false, default: false },
+      { name: "--no-wait", type: "boolean", required: false, default: false },
+    ],
+    output_fields: ["status", "report", "live"],
+  },
+  {
+    name: "harness connect claude-code",
+    description: "Connect Claude Code as a brokered Harness (alias of auth claude-code)",
+    mutating: true,
+    args: [
+      { name: "--connect", type: "string", required: true },
+      { name: "--mode", type: "string", enum: ["subscription", "apiKey"], required: false, default: "subscription" },
+      { name: "--token-stdin", type: "boolean", required: false, default: false, secret: true },
+      { name: "--from-env", type: "string", required: false, secret: true },
+      { name: "--scope", type: "string", enum: ["workspace", "per_user"], required: false, default: "workspace" },
+      { name: "--end-user-id", type: "string", required: false },
+      { name: "--bin", type: "string", required: false, default: "claude" },
+    ],
+    output_fields: ["connector", "mode", "connected"],
+  },
+  {
+    name: "harness connect pi",
+    description: "Connect Pi as a brokered Harness (alias of auth pi)",
+    mutating: true,
+    args: [
+      { name: "--connect", type: "string", required: true },
+      { name: "--mode", type: "string", enum: ["anthropicOAuth", "anthropicApiKey"], required: false, default: "anthropicOAuth" },
+      { name: "--token-stdin", type: "boolean", required: false, default: false, secret: true },
+      { name: "--from-env", type: "string", required: false, secret: true },
+      { name: "--scope", type: "string", enum: ["workspace", "per_user"], required: false, default: "workspace" },
+      { name: "--end-user-id", type: "string", required: false },
+    ],
+    output_fields: ["connector", "mode", "connected"],
+  },
+  {
+    name: "connect",
+    description: "Mint or poll the human connect link for missing credentials",
+    mutating: true,
+    args: [
+      { name: "--wait", type: "boolean", required: false, default: false },
+      { name: "--status", type: "string", required: false },
+    ],
+    output_fields: ["url", "token", "requirements", "status"],
+  },
+  {
+    name: "secrets list",
+    description: "List Secret names only",
+    mutating: false,
+    args: [],
+    output_fields: ["secrets"],
+  },
+  {
+    name: "secrets set",
+    description: "Set a Secret from stdin; never accepts the value on argv",
+    mutating: true,
+    args: [
+      { name: "name", type: "string", required: true },
+      { name: "--value-stdin", type: "boolean", required: true, secret: true },
+    ],
+    output_fields: ["set", "changed"],
+  },
+  {
+    name: "secrets rm",
+    description: "Delete a Secret by name",
+    mutating: true,
+    args: [{ name: "name", type: "string", required: true }],
+    output_fields: ["deleted", "changed"],
+  },
+  {
+    name: "runs list",
+    description: "List runs with bounded output",
+    mutating: false,
+    args: [
+      { name: "--automation", type: "string", required: false },
+      { name: "--status", type: "string", required: false },
+      { name: "--limit", type: "integer", required: false, default: 25 },
+      { name: "--offset", type: "integer", required: false, default: 0 },
+      { name: "--fields", type: "string", required: false },
+    ],
+    output_fields: ["runs", "total", "limit", "offset", "truncated"],
+  },
+  {
+    name: "runs show",
+    description: "Show a run with bounded log output",
+    mutating: false,
+    args: [
+      { name: "runId", type: "string", required: true },
+      { name: "--log-limit", type: "integer", required: false, default: 100 },
+      { name: "--log-offset", type: "integer", required: false, default: 0 },
+    ],
+    output_fields: ["run", "steps", "logs", "logsTotal", "logsLimit", "logsOffset", "logsTruncated"],
+  },
+  {
+    name: "runs trigger",
+    description: "Manually trigger an Automation",
+    mutating: true,
+    args: [
+      { name: "automation", type: "string", required: true },
+      { name: "--input", type: "json", required: false },
+      { name: "--input-file", type: "path|-", required: false },
+      { name: "--env", type: "string", required: false, default: "production" },
+    ],
+    output_fields: ["runId"],
+  },
+  {
+    name: "runs signal",
+    description: "Deliver a Signal to a suspended run",
+    mutating: true,
+    args: [
+      { name: "runId", type: "string", required: true },
+      { name: "name", type: "string", required: true },
+      { name: "--payload", type: "json", required: false },
+      { name: "--payload-file", type: "path|-", required: false },
+    ],
+    output_fields: ["delivered"],
+  },
+  {
+    name: "runs cancel",
+    description: "Cancel a queued or suspended run",
+    mutating: true,
+    args: [{ name: "runId", type: "string", required: true }],
+    output_fields: ["cancelled", "changed"],
+  },
+  {
+    name: "logs",
+    description: "Print bounded run logs or follow until settle",
+    mutating: false,
+    args: [
+      { name: "runId", type: "string", required: true },
+      { name: "--follow", type: "boolean", required: false, default: false },
+      { name: "--limit", type: "integer", required: false, default: 100 },
+      { name: "--offset", type: "integer", required: false, default: 0 },
+    ],
+    output_fields: ["run", "logs", "logsTotal", "logsLimit", "logsOffset", "logsTruncated"],
+  },
+  {
+    name: "replay",
+    description: "Freeze a real run as a regression fixture and test",
+    mutating: true,
+    args: [{ name: "runId", type: "string", required: true }],
+    output_fields: ["runId", "fixture", "test"],
+  },
+  {
+    name: "rollback",
+    description: "Re-point an Automation alias to a prior immutable version",
+    mutating: true,
+    args: [
+      { name: "automation", type: "string", required: true },
+      { name: "--to", type: "integer", required: true },
+      { name: "--env", type: "string", required: false, default: "production" },
+    ],
+    output_fields: ["rolledBack", "automation", "env", "toVersion", "changed"],
+  },
+] as const;
+
+export function cliSchema(version: string, commandPrefix?: string | undefined): Record<string, unknown> {
+  const filtered = commandPrefix
+    ? commands.filter((command) => command.name === commandPrefix || command.name.startsWith(`${commandPrefix} `))
+    : commands;
+  return {
+    clispec: "0.2",
+    name: "tesser",
+    version,
+    description: "Code-first, agent-native automation CLI",
+    global_args: [
+      { name: "--json", type: "boolean", default: false, description: "Alias for --output json" },
+      { name: "--output", short: "-o", type: "string", enum: ["auto", "text", "json", "ndjson"], default: "auto" },
+      { name: "--url", type: "string", required: false },
+      { name: "--token", type: "string", required: false, secret: true },
+      { name: "--profile", type: "string", required: false },
+    ],
+    commands: filtered,
+    errors: errorRows.map(([kind, exitCode, retryable, description]) => ({ kind, exit_code: exitCode, retryable, description })),
+    outcomes: [],
+  };
+}