@devosurf/tesser 0.1.0-alpha.0

package/src/index.ts

@@ -0,0 +1,508 @@
+// tesser — the machine-first CLI (ADR-0007). Every command: --json (stdout = one JSON
+// document, stderr = logs), deterministic exit codes (src/exit-codes.ts), thin shell
+// over the control-plane API.
+
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { promisify } from "node:util";
+import { Command } 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 { discoverLocalAutomations, loadAutomationDef } from "./project.js";
+import { authClaudeCode, authPi } from "./commands/auth.js";
+import { deploy } from "./commands/deploy.js";
+import { dev } from "./commands/dev.js";
+import { init } from "./commands/init.js";
+import { replay } from "./commands/replay.js";
+import { runTests } from "./commands/test.js";
+
+const exec = promisify(execFile);
+const program = new Command();
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version as string;
+
+interface GlobalOpts {
+  json?: boolean;
+  url?: string;
+  token?: string;
+  profile?: string;
+}
+
+function setup(): { out: Output; opts: GlobalOpts } {
+  const opts = program.opts<GlobalOpts>();
+  return { out: new Output(opts.json ?? false), opts };
+}
+
+function target(opts: GlobalOpts): ReturnType<typeof resolveTarget> {
+  return resolveTarget({
+    ...(opts.url !== undefined ? { url: opts.url } : {}),
+    ...(opts.token !== undefined ? { token: opts.token } : {}),
+    ...(opts.profile !== undefined ? { profile: opts.profile } : {}),
+  });
+}
+
+function api(opts: GlobalOpts): ApiClient {
+  const t = target(opts);
+  return new ApiClient(t.url, t.token);
+}
+
+function requireProject(opts: GlobalOpts): { name: string; root: string } {
+  const t = target(opts);
+  if (!t.projectRoot || !t.project) {
+    throw new CliError(EXIT.USAGE, "not inside a Tesser project (no tesser.json) — run `tesser init <name>` or `tesser link`");
+  }
+  return { name: t.project, root: t.projectRoot };
+}
+
+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("--url <url>", "instance URL (overrides tesser.json / profile)")
+  .option("--token <token>", "API token (overrides TESSER_TOKEN / profile)")
+  .option("--profile <name>", "config profile");
+
+program
+  .command("init")
+  .argument("<name>", "project name (kebab-case)")
+  .option("--dir <dir>", "parent directory")
+  .option("--instance <url>", "instance URL to write into tesser.json")
+  .description("scaffold a new Project (one repo of automations)")
+  .action((name: string, cmdOpts: { dir?: string; instance?: string }) => {
+    const { out } = setup();
+    try {
+      init(out, name, cmdOpts);
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("login")
+  .option("--token <token>", "API token from the instance (printed at first boot)")
+  .option("--instance <url>", "instance URL", "http://localhost:8377")
+  .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 }) => {
+    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);
+      await client.get("/health"); // verify before storing
+      const config = readConfig();
+      config.profiles = { ...config.profiles, [cmdOpts.saveProfile]: { url: cmdOpts.instance, token } };
+      config.current = cmdOpts.saveProfile;
+      writeConfig(config);
+      out.data({ profile: cmdOpts.saveProfile, url: cmdOpts.instance }, () => `logged in to ${cmdOpts.instance} (profile "${cmdOpts.saveProfile}")`);
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("link")
+  .option("--repo <url>", "git remote the instance should pull (defaults to origin)")
+  .description("register this Project on the instance and wire git-sync")
+  .action(async (cmdOpts: { repo?: string }) => {
+    const { out, opts } = setup();
+    try {
+      const { name } = requireProject(opts);
+      let repoUrl = cmdOpts.repo;
+      if (repoUrl === undefined) {
+        repoUrl = await exec("git", ["remote", "get-url", "origin"]).then(
+          (r) => r.stdout.trim(),
+          () => undefined,
+        );
+      }
+      const result = await api(opts).post<{
+        id: string;
+        name: string;
+        deployKeyPublic: string;
+        webhookSetupUrl: string;
+      }>("/projects", {
+        name,
+        ...(repoUrl !== undefined ? { repoUrl } : {}),
+      });
+      out.data(
+        { ...result, repoUrl: repoUrl ?? null },
+        () =>
+          `linked project "${name}"${repoUrl ? ` ← ${repoUrl}` : " (no git remote yet — deploy with --local or set --repo)"}\n` +
+          `deploy key: ${result.deployKeyPublic}\n` +
+          `webhook setup: ${result.webhookSetupUrl}`,
+      );
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("test")
+  .option("--smoke-only", "run only the auto-generated smoke tests")
+  .option("--automation <id>", "limit to one automation")
+  .description("fast in-process validation: colocated tests + auto smoke (ADR-0008)")
+  .action(async (cmdOpts: { smokeOnly?: boolean; automation?: string }) => {
+    const { out, opts } = setup();
+    try {
+      const t = target(opts);
+      const root = t.projectRoot ?? process.cwd();
+      await runTests(out, root, { ...(cmdOpts.smokeOnly !== undefined ? { smokeOnly: cmdOpts.smokeOnly } : {}), filter: cmdOpts.automation });
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("build")
+  .description("build + statically extract every automation's manifest locally (CI check)")
+  .action(async () => {
+    const { out, opts } = setup();
+    try {
+      const t = target(opts);
+      const root = t.projectRoot ?? process.cwd();
+      const autos = discoverLocalAutomations(root);
+      if (autos.length === 0) throw new CliError(EXIT.USAGE, "no automations found");
+      const manifests: Array<ReturnType<typeof extractAutomationManifest>> = [];
+      for (const a of autos) {
+        const def = await loadAutomationDef(a.entry);
+        manifests.push(extractAutomationManifest(def));
+      }
+      out.data({ automations: manifests }, () =>
+        manifests.map((m) => `${m.id}: trigger=${m.trigger.kind} connections=${Object.keys(m.connections).join(",") || "-"} secrets=${Object.keys(m.secrets).join(",") || "-"}`).join("\n"),
+      );
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("deploy")
+  .option("--ref <ref>", "git ref to deploy (default: the project's production branch)")
+  .option("--local", "deploy the local working tree (dev/dogfood lane, skips git)")
+  .option("--no-wait", "queue the sync and return immediately")
+  .description("git → instance: build changed, gate on tests, promote on green (ADR-0006)")
+  .action(async (cmdOpts: { ref?: string; local?: boolean; wait?: boolean }) => {
+    const { out, opts } = setup();
+    try {
+      const { name, root } = requireProject(opts);
+      await deploy(out, api(opts), name, {
+        ref: cmdOpts.ref,
+        local: cmdOpts.local ? root : undefined,
+        ...(cmdOpts.wait === false ? { wait: false } : {}),
+      });
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("dev")
+  .option("--port <port>", "port for the local instance", "8377")
+  .option("--no-watch", "deploy once and keep serving without watching")
+  .description("zero-setup local instance (embedded postgres) + deploy-on-change")
+  .action(async (cmdOpts: { port: string; watch?: boolean }) => {
+    const { out, opts } = setup();
+    try {
+      const { name, root } = requireProject(opts);
+      await dev(out, root, name, { port: Number(cmdOpts.port), ...(cmdOpts.watch === false ? { watch: false } : {}) });
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+const auth = program.command("auth").description("agent-assisted Harness credential setup; values post directly to connect links");
+auth
+  .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; subscription mode runs claude setup-token")
+  .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);
+    }
+  });
+auth
+  .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")
+  .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")
+  .option("--status <token>", "check an existing connect link")
+  .description("mint a connect link for missing credentials; the human completes it in a browser (ADR-0005)")
+  .action(async (cmdOpts: { wait?: boolean; status?: string }) => {
+    const { out, opts } = setup();
+    try {
+      const client = api(opts);
+      if (cmdOpts.status) {
+        out.data(await client.get(`/connect-links/${cmdOpts.status}/status`));
+        return;
+      }
+      const { name } = requireProject(opts);
+      const minted = await client.post<{ url: string | null; token?: string; requirements: unknown[] }>(
+        "/connect-links",
+        { project: name },
+      );
+      if (!minted.url) {
+        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");
+        }
+      }
+      process.exit(EXIT.HALTED_CREDENTIALS);
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+const secrets = program.command("secrets").description("workspace secrets — names only; values never echo");
+secrets
+  .command("list")
+  .action(async () => {
+    const { out, opts } = setup();
+    try {
+      out.data(await api(opts).get("/secrets"));
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+secrets
+  .command("set")
+  .argument("<name>")
+  .option("--value-stdin", "read the value from stdin (pipe it; value never appears in argv)")
+  .description("set a secret value (human/CI lane: pipe via --value-stdin; agents mint connect links instead)")
+  .action(async (name: string, cmdOpts: { valueStdin?: boolean }) => {
+    const { out, opts } = setup();
+    try {
+      if (!cmdOpts.valueStdin) {
+        throw new CliError(
+          EXIT.USAGE,
+          "refusing a value on argv — pipe it: `printenv MY_SECRET | tesser secrets set " + name + " --value-stdin` (or use a connect link)",
+        );
+      }
+      const chunks: Buffer[] = [];
+      for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+      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 ✓`);
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+secrets
+  .command("rm")
+  .argument("<name>")
+  .action(async (name: string) => {
+    const { out, opts } = setup();
+    try {
+      out.data(await api(opts).delete(`/secrets/${encodeURIComponent(name)}`));
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+const runs = program.command("runs").description("inspect and drive runs");
+runs
+  .command("list")
+  .option("--automation <id>")
+  .option("--status <status>")
+  .option("--limit <n>", "max rows", "25")
+  .action(async (cmdOpts: { automation?: string; status?: string; limit: string }) => {
+    const { out, opts } = setup();
+    try {
+      const { name } = requireProject(opts);
+      const params = new URLSearchParams({ project: name, limit: cmdOpts.limit });
+      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)",
+      );
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+runs
+  .command("show")
+  .argument("<runId>")
+  .action(async (runId: string) => {
+    const { out, opts } = setup();
+    try {
+      out.data(await api(opts).get(`/runs/${runId}`));
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+runs
+  .command("trigger")
+  .argument("<automation>")
+  .option("--input <json>", "input payload as JSON")
+  .option("--env <env>", "environment", "production")
+  .action(async (automation: string, cmdOpts: { input?: 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);
+      out.data(await api(opts).post("/runs", body));
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+runs
+  .command("signal")
+  .argument("<runId>")
+  .argument("<name>")
+  .option("--payload <json>", "signal payload as JSON")
+  .action(async (runId: string, name: string, cmdOpts: { payload?: string }) => {
+    const { out, opts } = setup();
+    try {
+      out.data(
+        await api(opts).post(`/runs/${runId}/signals/${encodeURIComponent(name)}`, {
+          ...(cmdOpts.payload !== undefined ? { payload: JSON.parse(cmdOpts.payload) } : {}),
+        }),
+      );
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+runs
+  .command("cancel")
+  .argument("<runId>")
+  .action(async (runId: string) => {
+    const { out, opts } = setup();
+    try {
+      out.data(await api(opts).post(`/runs/${runId}/cancel`));
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("logs")
+  .argument("<runId>")
+  .option("--follow", "poll until the run settles")
+  .description("step logs for one run")
+  .action(async (runId: string, cmdOpts: { follow?: boolean }) => {
+    const { out, opts } = setup();
+    try {
+      const client = api(opts);
+      let printed = 0;
+      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);
+          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);
+          return;
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+      }
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("replay")
+  .argument("<runId>")
+  .description("freeze a real run as a committed regression fixture + test (ADR-0008)")
+  .action(async (runId: string) => {
+    const { out, opts } = setup();
+    try {
+      const { root } = requireProject(opts);
+      await replay(out, api(opts), root, runId);
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("rollback")
+  .argument("<automation>")
+  .requiredOption("--to <version>", "version number to re-point the alias at")
+  .option("--env <env>", "environment", "production")
+  .description("instant alias re-point to a prior immutable version (no rebuild)")
+  .action(async (automation: string, cmdOpts: { to: string; env: string }) => {
+    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,
+        }),
+      );
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("status")
+  .description("instance + project deploy status")
+  .action(async () => {
+    const { out, opts } = setup();
+    try {
+      const t = target(opts);
+      const client = api(opts);
+      const health = await client.get("/health");
+      const status = await client.get("/status");
+      const manifest = t.projectRoot ? readLinkManifest(t.projectRoot) : null;
+      const projectStatus = manifest ? await client.get(`/projects/${manifest.project}/deploys/latest`).catch(() => null) : null;
+      out.data({ instance: t.url, health, status, project: manifest?.project ?? null, deploy: projectStatus });
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program.parseAsync().catch((err) => {
+  const out = new Output(process.argv.includes("--json"));
+  toExit(err, out);
+});

package/src/output.ts

@@ -0,0 +1,47 @@
+// Machine-first I/O contract (ADR-0007): stdout = data (one JSON document with --json),
+// stderr = logs/progress, deterministic exit codes.
+
+import { EXIT, type ExitCode } from "./exit-codes.js";
+
+export class Output {
+  constructor(readonly json: boolean) {}
+
+  /** 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");
+    } else {
+      process.stdout.write((human ? human(value as never) : JSON.stringify(value, null, 2)) + "\n");
+    }
+  }
+
+  /** Progress/notes → stderr, never stdout. */
+  log(msg: string): void {
+    process.stderr.write(msg + "\n");
+  }
+
+  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");
+    } else {
+      process.stderr.write(`error: ${message}\n`);
+      if (extra) process.stderr.write(JSON.stringify(extra, null, 2) + "\n");
+    }
+    process.exit(code);
+  }
+}
+
+export class CliError extends Error {
+  constructor(
+    readonly code: ExitCode,
+    message: string,
+    readonly extra?: Record<string, unknown>,
+  ) {
+    super(message);
+  }
+}
+
+export function toExit(err: unknown, out: Output): never {
+  if (err instanceof CliError) out.fail(err.code, err.message, err.extra);
+  out.fail(EXIT.ERROR, err instanceof Error ? err.message : String(err));
+}

package/src/project.ts

@@ -0,0 +1,51 @@
+// Local project introspection: discover automations, bundle one (esbuild), load its def
+// for smoke/build checks. (Apache-side implementation — the CLI never links the server.)
+
+import { mkdtempSync, existsSync, readdirSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { build } from "esbuild";
+import type { AutomationDef } from "@devosurf/tesser-sdk";
+
+export interface LocalAutomation {
+  automationId: string;
+  dir: string;
+  entry: string;
+  hasTests: boolean;
+}
+
+export function discoverLocalAutomations(projectRoot: string): LocalAutomation[] {
+  const root = join(projectRoot, "automations");
+  if (!existsSync(root)) return [];
+  const out: LocalAutomation[] = [];
+  for (const name of readdirSync(root).sort()) {
+    const dir = join(root, name);
+    if (!statSync(dir).isDirectory()) continue;
+    const entry = join(dir, "index.ts");
+    if (!existsSync(entry)) continue;
+    const hasTests = readdirSync(dir).some((f) => /\.test\.(ts|js|mts|mjs)$/.test(f));
+    out.push({ automationId: name, dir, entry, hasTests });
+  }
+  return out;
+}
+
+export async function loadAutomationDef(entry: string): Promise<AutomationDef<any, any, any, any, any, any, any>> {
+  const outDir = mkdtempSync(join(tmpdir(), "tesser-cli-"));
+  const outFile = join(outDir, "bundle.mjs");
+  await build({
+    entryPoints: [entry],
+    outfile: outFile,
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    target: "node20",
+    packages: "bundle",
+    logLevel: "silent",
+  });
+  const mod = (await import(pathToFileURL(outFile).href)) as { default?: AutomationDef<any, any, any, any, any, any, any> };
+  if (!mod.default || typeof mod.default.run !== "function") {
+    throw new Error(`${entry}: no default export from defineAutomation`);
+  }
+  return mod.default;
+}