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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devosurf/tesser",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Tesser CLI — the machine-first interface for agents and humans.",
   "license": "Apache-2.0",
   "type": "module",
@@ -19,8 +19,8 @@
   "dependencies": {
     "commander": "^15.0.0",
     "esbuild": "^0.28.1",
-    "@devosurf/tesser-sdk": "0.1.0-alpha.2",
-    "@devosurf/tesser-testing": "0.1.0-alpha.2"
+    "@devosurf/tesser-testing": "0.1.0-alpha.4",
+    "@devosurf/tesser-sdk": "0.1.0-alpha.4"
   },
   "main": "./dist/index.js",
   "types": "./src/index.ts",

package/src/commands/doctor.test.ts

@@ -0,0 +1,39 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import type { ApiClient } from "../client.js";
+import type { Output } from "../output.js";
+import { doctor } from "./doctor.js";
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function out(): Output & { data: ReturnType<typeof vi.fn> } {
+  return { data: vi.fn(), log: vi.fn(), fail: vi.fn(), json: true, format: "json" } as unknown as Output & { data: ReturnType<typeof vi.fn> };
+}
+
+describe("tesser doctor", () => {
+  test("reports local project checks without requiring network", async () => {
+    const root = mkdtempSync(join(tmpdir(), "tesser-doctor-"));
+    roots.push(root);
+    writeFileSync(join(root, "package.json"), JSON.stringify({ dependencies: { "@devosurf/tesser-sdk": "0.1.0" } }));
+    writeFileSync(join(root, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+    const output = out();
+
+    await doctor(output, {
+      version: "0.1.0",
+      target: { url: "https://inst.example", token: undefined, project: "demo", projectRoot: root },
+      client: { get: vi.fn() } as unknown as ApiClient,
+      network: false,
+    });
+
+    const report = output.data.mock.calls[0]?.[0] as { project: string; checks: Array<{ name: string; ok: boolean }> };
+    expect(report.project).toBe("demo");
+    expect(report.checks.find((check) => check.name === "pnpm-lock")?.ok).toBe(true);
+    expect(report.checks.find((check) => check.name === "auth-token")?.ok).toBe(false);
+  });
+});

package/src/commands/doctor.ts

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ApiClient } from "../client.js";
+import type { ResolvedTarget } from "../config.js";
+import type { Output } from "../output.js";
+
+export interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  severity: "info" | "warning" | "error";
+  message: string;
+  hint?: string;
+}
+
+export interface DoctorReport {
+  ok: boolean;
+  cliVersion: string;
+  node: string;
+  cwd: string;
+  project: string | null;
+  projectRoot: string | null;
+  instance: string;
+  auth: { tokenPresent: boolean };
+  checks: DoctorCheck[];
+  network?: { ok: boolean; health?: unknown; error?: string };
+}
+
+export async function doctor(
+  out: Output,
+  opts: { version: string; target: ResolvedTarget; client: ApiClient; network: boolean },
+): Promise<void> {
+  const checks: DoctorCheck[] = [];
+  checks.push({
+    name: "project",
+    ok: opts.target.projectRoot !== null,
+    severity: opts.target.projectRoot ? "info" : "warning",
+    message: opts.target.projectRoot ? `Project ${opts.target.project ?? "(unnamed)"} found` : "No tesser.json found from this directory",
+    ...(opts.target.projectRoot ? {} : { hint: "Run inside a Tesser Project, or create one with `tesser init <name>`." }),
+  });
+  checks.push({
+    name: "auth-token",
+    ok: opts.target.token !== undefined,
+    severity: opts.target.token ? "info" : "warning",
+    message: opts.target.token ? "API token is configured" : "No API token configured",
+    ...(opts.target.token ? {} : { hint: "Run `tesser login` or set TESSER_TOKEN." }),
+  });
+
+  if (opts.target.projectRoot) {
+    const pkgPath = join(opts.target.projectRoot, "package.json");
+    const lockPath = join(opts.target.projectRoot, "pnpm-lock.yaml");
+    checks.push({
+      name: "package-json",
+      ok: existsSync(pkgPath),
+      severity: existsSync(pkgPath) ? "info" : "warning",
+      message: existsSync(pkgPath) ? "package.json exists" : "package.json missing",
+    });
+    checks.push({
+      name: "pnpm-lock",
+      ok: existsSync(lockPath),
+      severity: existsSync(lockPath) ? "info" : "warning",
+      message: existsSync(lockPath) ? "pnpm-lock.yaml exists" : "pnpm-lock.yaml missing",
+      ...(existsSync(lockPath) ? {} : { hint: "Run `pnpm install` and commit pnpm-lock.yaml for reproducible Instance builds." }),
+    });
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+        const pinned = pkg.dependencies?.["@devosurf/tesser-sdk"] ?? pkg.devDependencies?.["@devosurf/tesser"];
+        checks.push({
+          name: "tesser-pins",
+          ok: typeof pinned === "string" && pinned.length > 0 && pinned !== "latest",
+          severity: typeof pinned === "string" && pinned.length > 0 && pinned !== "latest" ? "info" : "warning",
+          message: pinned ? `Tesser package pin detected (${pinned})` : "No Tesser package pin detected",
+          ...(pinned && pinned !== "latest" ? {} : { hint: "Run `tesser upgrade` with the target CLI version." }),
+        });
+      } catch (cause) {
+        checks.push({ name: "package-json-parse", ok: false, severity: "warning", message: `package.json is not valid JSON: ${String(cause)}` });
+      }
+    }
+  }
+
+  let network: DoctorReport["network"];
+  if (opts.network && opts.target.token) {
+    try {
+      network = { ok: true, health: await opts.client.get("/health") };
+      checks.push({ name: "instance-health", ok: true, severity: "info", message: `Instance reachable at ${opts.target.url}` });
+    } catch (cause) {
+      const error = cause instanceof Error ? cause.message : String(cause);
+      network = { ok: false, error };
+      checks.push({
+        name: "instance-health",
+        ok: false,
+        severity: "error",
+        message: error,
+        hint: "Check --url/TESSER_URL and the API token, or rerun with --no-network for local checks only.",
+      });
+    }
+  }
+
+  const report: DoctorReport = {
+    ok: checks.every((check) => check.severity !== "error" && check.ok),
+    cliVersion: opts.version,
+    node: process.version,
+    cwd: process.cwd(),
+    project: opts.target.project ?? null,
+    projectRoot: opts.target.projectRoot,
+    instance: opts.target.url,
+    auth: { tokenPresent: opts.target.token !== undefined },
+    checks,
+    ...(network !== undefined ? { network } : {}),
+  };
+
+  out.data(report, (r: DoctorReport) => {
+    const lines = [`Tesser CLI ${r.cliVersion}`, `instance: ${r.instance}`, `project: ${r.project ?? "(none)"}`];
+    for (const check of r.checks) lines.push(`${check.ok ? "ok" : check.severity}: ${check.name} — ${check.message}${check.hint ? ` (${check.hint})` : ""}`);
+    return lines.join("\n");
+  });
+}

package/src/commands/init.test.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, test, vi } from "vitest";
@@ -27,6 +27,15 @@ afterEach(() => {
 });
 
 describe("tesser init", () => {
+  test("refuses to overwrite a non-empty directory without --force", () => {
+    const parent = tempRoot();
+    const root = join(parent, "occupied");
+    mkdirSync(root);
+    writeFileSync(join(root, "package.json"), "{}\n");
+
+    expect(() => init(out(), "occupied", { dir: parent }, "0.2.0-beta.1")).toThrow("is not empty");
+  });
+
   test("pins Tesser packages and writes committed agent docs", () => {
     const parent = tempRoot();
     init(out(), "agent-docs", { dir: parent, instance: "https://tesser.example.com" }, "0.2.0-beta.1");
@@ -47,6 +56,10 @@ describe("tesser init", () => {
     expect(readFileSync(join(root, "AGENTS.md"), "utf8")).toContain("./.tesser/docs/README.md");
     expect(readFileSync(join(root, ".tesser", "docs", "sdk.md"), "utf8")).toContain("ctx.step");
     expect(readFileSync(join(root, ".tesser", "docs", "cli.md"), "utf8")).toContain("pnpm-lock.yaml");
+    const connectorsDoc = readFileSync(join(root, ".tesser", "docs", "connectors.md"), "utf8");
+    expect(connectorsDoc).toContain("node_modules/@devosurf/tesser-connectors/manifest.json");
+    expect(connectorsDoc).toContain("Do not guess Connector APIs");
+    expect(connectorsDoc).not.toContain("## Common Actions");
 
     const manifest = readJson<{ tesserVersion: string; project: string }>(join(root, ".tesser", "docs", "manifest.json"));
     expect(manifest).toMatchObject({ tesserVersion: "0.2.0-beta.1", project: "agent-docs" });

package/src/commands/init.ts

@@ -1,7 +1,7 @@
 // `tesser init <name>`: scaffold a Project — the linked repo unit (ADR-0006). One
 // automation per directory; colocated tests; git is the source of truth.
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { EXIT } from "../exit-codes.js";
 import { CliError, Output } from "../output.js";
@@ -33,13 +33,19 @@ test("greets by name", async () => {
 });
 `;
 
-export function init(out: Output, name: string, opts: { dir?: string | undefined; instance?: string | undefined }, version: string): void {
+export function init(out: Output, name: string, opts: { dir?: string | undefined; instance?: string | undefined; force?: boolean | undefined }, version: string): void {
   if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) {
     throw new CliError(EXIT.USAGE, "project name must be kebab-case");
   }
   const root = join(opts.dir ?? process.cwd(), name);
-  if (existsSync(join(root, "tesser.json"))) {
-    throw new CliError(EXIT.CONFLICT, `${root} is already a Tesser project`);
+  if (existsSync(root) && !opts.force) {
+    if (existsSync(join(root, "tesser.json"))) {
+      throw new CliError(EXIT.CONFLICT, `${root} is already a Tesser project`);
+    }
+    const entries = readdirSync(root).filter((entry) => entry !== ".DS_Store");
+    if (entries.length > 0) {
+      throw new CliError(EXIT.CONFLICT, `${root} is not empty — choose a new name or pass --force to write into it`);
+    }
   }
   mkdirSync(join(root, "automations", "hello"), { recursive: true });
 

package/src/commands/project-docs.ts

@@ -143,7 +143,11 @@ function docsReadmeMd(projectName: string, version: string): string {
 }
 
 function cliReferenceMd(version: string): string {
-  return `# Tesser CLI reference\n\nGenerated for \`@devosurf/tesser@${version}\`. The CLI is the agent interface: prefer \`--json\` when output will drive follow-up actions. stdout is data; stderr is logs/progress.\n\n## Install and invoke\n\n\`\`\`bash\nnpm install -g @devosurf/tesser@${version}\ntesser --version\n\n# Or run an exact version without global install:\nnpx @devosurf/tesser@${version} --version\n\`\`\`\n\n## Common flow\n\n\`\`\`bash\ntesser init my-project --instance https://tesser.example.com\ncd my-project\npnpm install                    # creates pnpm-lock.yaml; commit it\ngit init && git add -A && git commit -m init\ntesser login --instance https://tesser.example.com --token "$TESSER_TOKEN"\ntesser link --json              # registers this Project on the Instance\ntesser test --json\ntesser build --json\ntesser deploy --json\n\`\`\`\n\n## Commands agents commonly use\n\n- \`tesser init <name> [--dir DIR] [--instance URL]\` — scaffold a Project.\n- \`tesser upgrade\` — pin Tesser packages to this CLI version and refresh \`.tesser/docs/\`. To target a version: \`npx @devosurf/tesser@<version> upgrade\`.\n- \`tesser login --instance URL --token TOKEN\` — verify and store a profile. Prefer \`TESSER_TOKEN\` over pasting tokens into chat.\n- \`tesser link [--repo URL] --json\` — register the Project and print deploy-key/webhook setup data. CLI output must not include private keys or webhook secrets.\n- \`tesser status --json\` — instance health and deploy state.\n- \`tesser test [--smoke-only] [--automation ID] --json\` — fast local tests plus generated smoke tests.\n- \`tesser build --json\` — bundle and statically extract manifests. Use before deploy when changing requirements.\n- \`tesser dev [--port N] [--no-watch]\` — local Instance with embedded Postgres under ignored \`.tesser/*\` state.\n- \`tesser deploy [--ref REF] [--local] [--no-wait] --json\` — server-side build/test/promotion. Exit code 4 means halted on missing credentials; run \`tesser connect\`.\n- \`tesser connect [--wait] [--status TOKEN] --json\` — mint or poll the human connect link. The human supplies credentials in the browser; the agent only sees readiness.\n- \`tesser secrets list --json\`, \`tesser secrets rm <name> --json\`, \`printenv MY_SECRET | tesser secrets set <name> --value-stdin --json\`. Never put secret values in argv.\n- \`tesser runs list|show|trigger|signal|cancel --json\`; \`tesser logs <runId> [--follow]\`; \`tesser replay <runId>\`.\n- \`tesser rollback <automation> --to <version> --json\` — alias re-point; no rebuild.\n\n## Credential safety\n\n- Do not ask the user to paste secrets into chat. Use masked secret prompts where your harness supports them, or ask the human to run a command locally.\n- Never pass raw secret values as CLI arguments. Use environment variables, profiles, connect links, OAuth, or \`--value-stdin\`.\n- Treat connect links and status tokens as sensitive operational material.\n\n## Deploy hygiene\n\n- Run \`pnpm install\` after init/upgrade and commit \`pnpm-lock.yaml\`; the Instance installs from lockfiles for reproducible builds.\n- Do not commit \`node_modules/\`, \`.env\`, or local runtime state in \`.tesser/*\` outside \`.tesser/docs/\`.\n- Git is the source of truth. Commit and push before expecting a normal Instance deploy to see changes.\n`;
+  return `# Tesser CLI reference\n\nGenerated for \`@devosurf/tesser@${version}\`. The CLI is the agent interface: prefer \`--output json\` (or \`--json\`) when output will drive follow-up actions. stdout is data; stderr is logs/progress. \`tesser schema\` prints the machine-readable command contract without auth or network.\n\n## Install and invoke\n\n\`\`\`bash\nnpm install -g @devosurf/tesser@${version}\ntesser --version\n\n# Or run an exact version without global install:\nnpx @devosurf/tesser@${version} --version\n\`\`\`\n\n## Common flow\n\n\`\`\`bash\ntesser init my-project --instance https://tesser.example.com\ncd my-project\npnpm install                    # creates pnpm-lock.yaml; commit it\ngit init && git add -A && git commit -m init\nprintf '%s' "$TESSER_TOKEN" | tesser login --url https://tesser.example.com --token-stdin\ntesser link --json              # registers this Project on the Instance\ntesser test --json\ntesser build --json\ntesser deploy --json\n\`\`\`\n\n## Commands agents commonly use\n\n- \`tesser init <name> [--dir DIR] [--instance URL] [--force]\` — scaffold a Project; refuses non-empty directories unless forced.\n- \`tesser upgrade\` — pin Tesser packages to this CLI version and refresh \`.tesser/docs/\`. To target a version: \`npx @devosurf/tesser@<version> upgrade\`.\n- \`printf '%s' "$TESSER_TOKEN" | tesser login --url URL --token-stdin\` — verify and store a profile. Humans may run \`tesser login\` and use masked prompts; avoid \`--token\` because argv can leak.\n- \`tesser link [--repo URL] --json\` — register the Project and print deploy-key/webhook setup data. CLI output must not include private keys or webhook secrets.\n- \`tesser status --json\` — instance health and deploy state.\n- \`tesser test [--smoke-only] [--automation ID] --json\` — fast local tests plus generated smoke tests.\n- \`tesser build --json\` — bundle and statically extract manifests. Use before deploy when changing requirements.\n- \`tesser dev [--port N] [--no-watch]\` — local Instance with embedded Postgres under ignored \`.tesser/*\` state.\n- \`tesser deploy [--ref REF] [--local] [--no-wait] --json\` — server-side build/test/promotion. Exit code 4 means halted on missing credentials; run \`tesser connect\`.\n- \`tesser connect [--wait] [--status TOKEN] --json\` — mint or poll the human connect link. The human supplies credentials in the browser; the agent only sees readiness.\n- \`tesser secrets list --json\`, \`tesser secrets rm <name> --json\`, \`printenv MY_SECRET | tesser secrets set <name> --value-stdin --json\`. Never put secret values in argv.\n- \`tesser schema --json\` — inspect commands, arguments, outputs, exit codes, and mutation markers.
+- \`tesser doctor --json\` — local Project/auth/package preflight; use \`--no-network\` for offline checks.
+- \`tesser completion bash|zsh\` — print shell completion scripts.
+- \`tesser runs list [--limit N] [--offset N] [--fields id,status] --json\`; \`tesser runs trigger <automation> --input-file - --json\`; \`tesser runs signal <runId> <name> --payload-file - --json\`; \`tesser runs show|cancel --json\`; \`tesser logs <runId> [--follow] [--limit N] [--offset N] [-o ndjson]\`; \`tesser replay <runId>\`.
+- \`tesser harness connect claude-code --connect CONNECT_URL\` and \`tesser harness connect pi --connect CONNECT_URL\` — preferred Harness credential namespace; legacy \`tesser auth ...\` aliases remain.\n- \`tesser rollback <automation> --to <version> --json\` — alias re-point; no rebuild.\n\n## Credential safety\n\n- Do not ask the user to paste secrets into chat. Use masked secret prompts where your harness supports them, or ask the human to run a command locally.\n- Never pass raw secret values as CLI arguments. Use masked prompts, environment variables, profiles, connect links, OAuth, \`--token-stdin\`, \`--value-stdin\`, or \`--*-file -\` stdin lanes.\n- Treat connect links and status tokens as sensitive operational material.\n\n## Deploy hygiene\n\n- Run \`pnpm install\` after init/upgrade and commit \`pnpm-lock.yaml\`; the Instance installs from lockfiles for reproducible builds.\n- Do not commit \`node_modules/\`, \`.env\`, or local runtime state in \`.tesser/*\` outside \`.tesser/docs/\`.\n- Git is the source of truth. Commit and push before expecting a normal Instance deploy to see changes.\n`;
 }
 
 function sdkReferenceMd(version: string): string {
@@ -151,5 +155,5 @@ function sdkReferenceMd(version: string): string {
 }
 
 function connectorsReferenceMd(version: string): string {
-  return `# Tesser Connector reference\n\nGenerated for \`@devosurf/tesser-connectors@${version}\`. A Connector is a typed integration; a Connection is an authed runtime instance injected by the Credential broker.\n\n## Available connector imports\n\n\`\`\`ts\nimport {\n  anthropic,\n  claudeCode,\n  github,\n  gmail,\n  googleCalendar,\n  googleDocs,\n  googleDrive,\n  googleSheets,\n  http,\n  outlookMail,\n  pi,\n  resend,\n  slack,\n} from "@devosurf/tesser-connectors";\n\`\`\`\n\nOnly import Connectors that the Automation declares in \`connections: { ... }\`.\n\n## Pattern\n\n\`\`\`ts\nimport { defineAutomation, onSchedule } from "@devosurf/tesser-sdk";\nimport { github, slack } from "@devosurf/tesser-connectors";\nimport { z } from "zod";\n\nexport default defineAutomation({\n  id: "digest",\n  trigger: onSchedule({ cron: "0 9 * * *", tz: "UTC" }),\n  connections: { github, slack },\n  output: z.object({ posted: z.boolean(), count: z.number() }),\n\n  run: async (_input, ctx) => {\n    const issues = await ctx.step("fetch-open-issues", () =>\n      ctx.connections.github.issues.list({ state: "open", labels: ["bug"] }),\n    );\n\n    if (issues.length === 0) return { posted: false, count: 0 };\n\n    await ctx.step("post-to-slack", () =>\n      ctx.connections.slack.chat.postMessage({ channel: "#ops", text: \`\${issues.length} bugs\` }),\n    );\n\n    return { posted: true, count: issues.length };\n  },\n});\n\`\`\`\n\n## Common Actions\n\n- \`ctx.connections.http.get({ url, headers?, query? })\` and \`ctx.connections.http.request({ method, url, headers?, query?, body?, bodyText? })\`. Generic writes are not retry-safe; still wrap them in a Step.\n- \`ctx.connections.github.issues.list({ repo?, state?, labels?, limit? })\`, \`issues.create({ repo, title, body?, labels? })\`, \`issues.comment({ repo, number, body })\`, \`repos.get({ repo })\`.\n- \`ctx.connections.slack.chat.postMessage({ channel, text, threadTs? })\` and related Slack chat/conversation/user Actions.\n- \`ctx.connections.resend.emails.send(...)\`, Gmail/Outlook Mail and Google Calendar/Docs/Drive/Sheets Actions, Anthropic model Actions, Claude Code/Pi Harness-related Connectors: inspect package types or examples before using.\n\n## Connector triggers\n\nSome Connectors expose typed triggers, e.g. GitHub issue triggers, Slack event triggers, Gmail/Outlook mailbox poll triggers. Use the Connector's \`triggers\` constructors; do not hand-roll webhook delivery unless no Connector exists.\n\n\`\`\`ts\ntrigger: github.triggers.issueOpened({ repo: "owner/repo" })\n\`\`\`\n\n## Safety rules\n\n- Connector Actions are not automatically durable. The Automation author must wrap every Action call in \`ctx.step\`.\n- The imported Connector is not a token-bearing client. The authed client exists only at \`ctx.connections.<name>\` inside \`run\`.\n- For bespoke APIs, combine \`http\` with declared \`secrets: { ... }\`; do not put API keys in source, tests, logs, CLI args, or committed env files.\n- If deploy halts on a missing Connection, surface \`tesser connect\` output to the human. The agent must not complete OAuth or paste raw secrets itself.\n`;
+  return "# Tesser Connector reference\n\nGenerated for `@devosurf/tesser-connectors@__VERSION__`. This file is intentionally a source map, not a duplicated API reference. The installed Connector package is the authoritative version-pinned reference. Do not rely on training data, memory, or hand-written summaries.\n\n## Hard rule\n\nDo not guess Connector APIs from memory, training data, old examples, or web search. After `pnpm install`, inspect the installed package in `node_modules/@devosurf/tesser-connectors`.\n\n## Source-of-truth order\n\n1. Project policy: `AGENTS.md` and `.tesser/docs/connectors.md`.\n2. Connector inventory: `node_modules/@devosurf/tesser-connectors/manifest.json`.\n3. Import names: `node_modules/@devosurf/tesser-connectors/index.ts`.\n4. Exact input/output schemas, samples, triggers, provider quirks: `node_modules/@devosurf/tesser-connectors/<connector-id>/index.ts`.\n5. Provider OAuth facts: `node_modules/@devosurf/tesser-connectors/providers/*.ts` and `catalog/index.ts`.\n\nNever edit `node_modules`. Read it, then edit the Automation under `automations/<id>/` and validate with `tesser test --json` / `tesser build --json`.\n\n## Quick inspection commands\n\nRun `pnpm install` first if `node_modules` is absent.\n\n```bash\n# Barrel export names: use these names in `import { ... } from \"@devosurf/tesser-connectors\"`.\nsed -n '1,180p' node_modules/@devosurf/tesser-connectors/index.ts\n\n# Installed connector inventory with actions/triggers.\nnode - <<'NODE'\nconst fs = require('node:fs');\nconst manifest = JSON.parse(fs.readFileSync('node_modules/@devosurf/tesser-connectors/manifest.json', 'utf8'));\nfor (const c of manifest.connectors) {\n  console.log(\"\");\n  console.log(`${c.id}: ${c.describe}`);\n  const auth = Object.keys(c.auth ?? {});\n  if (auth.length) console.log(`  auth: ${auth.join(', ')}`);\n  if (c.actions?.length) console.log(`  actions: ${c.actions.map((a) => `${a.path} [${a.safety}${a.retrySafe ? ', retry-safe' : ''}]`).join(', ')}`);\n  if (c.triggers?.length) console.log(`  triggers: ${c.triggers.map((t) => `${t.id} [${t.strategy}]`).join(', ')}`);\n}\nNODE\n\n# Exact schemas for one Connector, including Zod input/output objects.\nsed -n '1,260p' node_modules/@devosurf/tesser-connectors/outlook-mail/index.ts\n```\n\n## Authoring pattern\n\n```ts\nimport { defineAutomation, onSchedule } from \"@devosurf/tesser-sdk\";\nimport { github, slack } from \"@devosurf/tesser-connectors\";\nimport { z } from \"zod\";\n\nexport default defineAutomation({\n  id: \"digest\",\n  trigger: onSchedule({ cron: \"0 9 * * *\", tz: \"UTC\" }),\n  connections: { github, slack },\n  output: z.object({ posted: z.boolean(), count: z.number() }),\n\n  run: async (_input, ctx) => {\n    const issues = await ctx.step(\"fetch-open-issues\", () =>\n      ctx.connections.github.issues.list({ state: \"open\", labels: [\"bug\"] }),\n    );\n\n    if (issues.length === 0) return { posted: false, count: 0 };\n\n    await ctx.step(\"post-to-slack\", () =>\n      ctx.connections.slack.chat.postMessage({ channel: \"#ops\", text: `${issues.length} bugs` }),\n    );\n\n    return { posted: true, count: issues.length };\n  },\n});\n```\n\n## Rules that matter more than the Connector API\n\n- A Connector import is not an authed client. It is a typed requirement declaration.\n- Runtime calls go through `ctx.connections.<connection-key>` inside `run`.\n- Every Connector Action call must be inside `ctx.step(...)`.\n- Declare raw credentials separately with `secrets: { name: secret({ describe: \"...\" }) }`.\n- The Credential broker injects values at runtime; agents must never read or print tokens/secrets.\n- Deploy halts on missing Connections or Secrets; a human completes the connect link.\n\n## Connector ids currently shipped in this package\n\nRead `manifest.json` for the authoritative list. Current ids include core HTTP/email/repo/chat/calendar/document/spreadsheet/model/harness Connectors such as `http`, `github`, `slack`, `resend`, `gmail`, `outlook-mail`, Google Connectors, and Harness/model Connectors. Do not hardcode this list in Automations or docs; inspect the installed manifest.\n".replaceAll("__VERSION__", version);
 }

package/src/completion.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "vitest";
+import { completionScript } from "./completion.js";
+
+
+describe("completion scripts", () => {
+  test("prints bash and zsh scripts", () => {
+    expect(completionScript("bash")).toContain("complete -F _tesser_completion tesser");
+    expect(completionScript("zsh")).toContain("#compdef tesser");
+  });
+
+  test("rejects unknown shells", () => {
+    expect(() => completionScript("fish")).toThrow("completion shell must be bash or zsh");
+  });
+});

package/src/completion.ts

@@ -0,0 +1,92 @@
+import { EXIT } from "./exit-codes.js";
+import { CliError } from "./output.js";
+
+const COMMANDS = [
+  "schema",
+  "init",
+  "upgrade",
+  "login",
+  "link",
+  "status",
+  "test",
+  "build",
+  "dev",
+  "deploy",
+  "connect",
+  "auth",
+  "harness",
+  "secrets",
+  "runs",
+  "logs",
+  "replay",
+  "rollback",
+  "doctor",
+  "completion",
+];
+
+const CHILDREN: Record<string, string[]> = {
+  auth: ["claude-code", "pi"],
+  harness: ["connect"],
+  "harness connect": ["claude-code", "pi"],
+  secrets: ["list", "set", "rm"],
+  runs: ["list", "show", "trigger", "signal", "cancel"],
+};
+
+export function completionScript(shell: string): string {
+  if (shell === "bash") return bashCompletion();
+  if (shell === "zsh") return zshCompletion();
+  throw new CliError(EXIT.USAGE, "completion shell must be bash or zsh");
+}
+
+function bashCompletion(): string {
+  const commands = COMMANDS.join(" ");
+  const cases = Object.entries(CHILDREN)
+    .map(([parent, children]) => `    "${parent}") COMPREPLY=( $(compgen -W "${children.join(" ")}" -- "$cur") ) ;;`)
+    .join("\n");
+  return `# bash completion for tesser
+_tesser_completion() {
+  local cur prev words cword
+  _init_completion -n : || return
+  if [[ $cword -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "${commands}" -- "$cur") )
+    return
+  fi
+  local parent="\${COMP_WORDS[1]}"
+  if [[ $cword -ge 3 ]]; then parent="\${COMP_WORDS[1]} \${COMP_WORDS[2]}"; fi
+  case "$parent" in
+${cases}
+  esac
+}
+complete -F _tesser_completion tesser
+`;
+}
+
+function zshCompletion(): string {
+  const commandLines = COMMANDS.map((command) => `    '${command}: :->${command.replace(/ /g, "-")}'`).join(" \\\n");
+  return `#compdef tesser
+_tesser() {
+  local -a commands
+  _arguments -C \
+    '(-h --help)'{-h,--help}'[display help]' \
+    '--json[machine output]' \
+    '(-o --output)'{-o,--output}'[output format]:format:(auto text json ndjson)' \
+    '1:command:->cmds' \
+    '*::arg:->args'
+  case $state in
+    cmds)
+      _values 'tesser commands' \
+${commandLines}
+      ;;
+    args)
+      case $words[1] in
+        secrets) _values 'secrets commands' list set rm ;;
+        runs) _values 'runs commands' list show trigger signal cancel ;;
+        auth) _values 'auth commands' claude-code pi ;;
+        harness) _values 'harness commands' connect ;;
+      esac
+      ;;
+  esac
+}
+_tesser
+`;
+}

package/src/config.ts

@@ -20,6 +20,8 @@ export interface LinkManifest {
   instance?: string;
 }
 
+export const DEFAULT_INSTANCE_URL = "http://localhost:8377";
+
 const CONFIG_PATH = join(
   process.env["TESSER_CONFIG_DIR"] ?? join(homedir(), ".config", "tesser"),
   "config.json",
@@ -79,7 +81,7 @@ export function resolveTarget(opts: { url?: string; token?: string; profile?: st
       manifest?.instance ??
       process.env["TESSER_URL"] ??
       profile.url ??
-      "http://localhost:8377",
+      DEFAULT_INSTANCE_URL,
     token: opts.token ?? process.env["TESSER_TOKEN"] ?? profile.token,
     project: manifest?.project,
     projectRoot,