@devosurf/tesser 0.1.0-alpha.0 → 0.1.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devosurf/tesser",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "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.0",
-    "@devosurf/tesser-testing": "0.1.0-alpha.0"
+    "@devosurf/tesser-sdk": "0.1.0-alpha.1",
+    "@devosurf/tesser-testing": "0.1.0-alpha.1"
   },
   "main": "./dist/index.js",
   "types": "./src/index.ts",

package/src/commands/init.test.ts

@@ -0,0 +1,87 @@
+import { 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";
+import type { Output } from "../output.js";
+import { init } from "./init.js";
+import { upgradeProject } from "./project-docs.js";
+
+const roots: string[] = [];
+
+function tempRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), "tesser-cli-init-"));
+  roots.push(root);
+  return root;
+}
+
+function out(): Output {
+  return { data: vi.fn(), log: vi.fn(), fail: vi.fn() } as unknown as Output;
+}
+
+function readJson<T>(path: string): T {
+  return JSON.parse(readFileSync(path, "utf8")) as T;
+}
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("tesser init", () => {
+  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");
+
+    const root = join(parent, "agent-docs");
+    const pkg = readJson<{
+      dependencies: Record<string, string>;
+      devDependencies: Record<string, string>;
+    }>(join(root, "package.json"));
+
+    expect(pkg.dependencies["@devosurf/tesser-sdk"]).toBe("0.2.0-beta.1");
+    expect(pkg.dependencies["@devosurf/tesser-connectors"]).toBe("0.2.0-beta.1");
+    expect(pkg.devDependencies["@devosurf/tesser"]).toBe("0.2.0-beta.1");
+    expect(pkg.devDependencies["@devosurf/tesser-server"]).toBe("0.2.0-beta.1");
+    expect(pkg.devDependencies["@devosurf/tesser-testing"]).toBe("0.2.0-beta.1");
+
+    expect(readFileSync(join(root, ".gitignore"), "utf8")).toContain("!.tesser/docs/**");
+    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 manifest = readJson<{ tesserVersion: string; project: string }>(join(root, ".tesser", "docs", "manifest.json"));
+    expect(manifest).toMatchObject({ tesserVersion: "0.2.0-beta.1", project: "agent-docs" });
+  });
+});
+
+describe("tesser upgrade", () => {
+  test("updates pins and generated docs without overwriting AGENTS.md", () => {
+    const parent = tempRoot();
+    init(out(), "upgrade-me", { dir: parent }, "0.1.0-alpha.0");
+    const root = join(parent, "upgrade-me");
+    writeFileSync(join(root, "AGENTS.md"), "# Custom project policy\n");
+
+    const pkg = readJson<{
+      dependencies: Record<string, string>;
+      devDependencies: Record<string, string>;
+    }>(join(root, "package.json"));
+    pkg.dependencies["@devosurf/tesser-sdk"] = "latest";
+    pkg.devDependencies["@devosurf/tesser"] = "latest";
+    writeFileSync(join(root, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+
+    upgradeProject(out(), { name: "upgrade-me", root }, "0.2.0-beta.1");
+
+    const upgraded = readJson<{
+      dependencies: Record<string, string>;
+      devDependencies: Record<string, string>;
+    }>(join(root, "package.json"));
+    expect(upgraded.dependencies["@devosurf/tesser-sdk"]).toBe("0.2.0-beta.1");
+    expect(upgraded.dependencies["@devosurf/tesser-connectors"]).toBe("0.2.0-beta.1");
+    expect(upgraded.devDependencies["@devosurf/tesser"]).toBe("0.2.0-beta.1");
+    expect(upgraded.devDependencies["@devosurf/tesser-server"]).toBe("0.2.0-beta.1");
+    expect(upgraded.devDependencies["@devosurf/tesser-testing"]).toBe("0.2.0-beta.1");
+
+    expect(readFileSync(join(root, "AGENTS.md"), "utf8")).toBe("# Custom project policy\n");
+    const manifest = readJson<{ tesserVersion: string }>(join(root, ".tesser", "docs", "manifest.json"));
+    expect(manifest.tesserVersion).toBe("0.2.0-beta.1");
+  });
+});

package/src/commands/init.ts

@@ -5,6 +5,7 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { EXIT } from "../exit-codes.js";
 import { CliError, Output } from "../output.js";
+import { projectPackageJson, tesserGitignore, writeProjectAgentInstructions, writeTesserGeneratedDocs } from "./project-docs.js";
 
 const EXAMPLE_AUTOMATION = `import { defineAutomation, onWebhook } from "@devosurf/tesser-sdk";
 import { z } from "zod";
@@ -32,7 +33,7 @@ test("greets by name", async () => {
 });
 `;
 
-export function init(out: Output, name: string, opts: { dir?: string | undefined; instance?: string | undefined }): void {
+export function init(out: Output, name: string, opts: { dir?: string | undefined; instance?: string | 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");
   }
@@ -49,20 +50,7 @@ export function init(out: Output, name: string, opts: { dir?: string | undefined
   writeFileSync(
     join(root, "package.json"),
     JSON.stringify(
-      {
-        name,
-        private: true,
-        type: "module",
-        packageManager: "pnpm@9.12.0",
-        scripts: { test: "tesser test", deploy: "tesser deploy", dev: "tesser dev" },
-        dependencies: { "@devosurf/tesser-sdk": "latest", "@devosurf/tesser-connectors": "latest", zod: "^4" },
-        devDependencies: {
-          "@devosurf/tesser": "latest",
-          "@devosurf/tesser-server": "latest",
-          "@devosurf/tesser-testing": "latest",
-          vitest: "^4",
-        },
-      },
+      projectPackageJson(name, version),
       null,
       2,
     ) + "\n",
@@ -89,13 +77,22 @@ export function init(out: Output, name: string, opts: { dir?: string | undefined
     join(root, "vitest.config.ts"),
     `import { defineConfig } from "vitest/config";\nexport default defineConfig({ test: { globals: true, include: ["automations/**/*.test.ts"] } });\n`,
   );
-  writeFileSync(join(root, ".gitignore"), "node_modules/\n.tesser/\n.env\n");
+  writeFileSync(join(root, ".gitignore"), tesserGitignore());
+  writeProjectAgentInstructions(root, name, version, { overwrite: true });
+  const docs = writeTesserGeneratedDocs(root, name, version);
   writeFileSync(join(root, "automations", "hello", "index.ts"), EXAMPLE_AUTOMATION);
   writeFileSync(join(root, "automations", "hello", "index.test.ts"), EXAMPLE_TEST);
 
+  const next = [
+    "cd " + name,
+    "pnpm install",
+    "git init && git add -A && git commit -m init",
+    "tesser link",
+    "tesser test",
+  ];
   out.data(
-    { created: root, next: ["cd " + name, "git init && git add -A && git commit -m init", "npm install (or pnpm)", "tesser link", "tesser test"] },
+    { created: root, tesserVersion: version, docs, next },
     () =>
-      `created ${root}\nnext:\n  cd ${name}\n  git init && git add -A && git commit -m init\n  pnpm install\n  tesser link    # register on your instance\n  tesser test    # green in milliseconds`,
+      `created ${root}\nnext:\n  cd ${name}\n  pnpm install       # creates pnpm-lock.yaml; commit it\n  git init && git add -A && git commit -m init\n  tesser link       # register on your instance\n  tesser test       # green in milliseconds`,
   );
 }

package/src/commands/project-docs.ts

@@ -0,0 +1,155 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { EXIT } from "../exit-codes.js";
+import { CliError, Output } from "../output.js";
+
+export const TESSER_DEPENDENCIES = ["@devosurf/tesser-sdk", "@devosurf/tesser-connectors"] as const;
+export const TESSER_DEV_DEPENDENCIES = ["@devosurf/tesser", "@devosurf/tesser-server", "@devosurf/tesser-testing"] as const;
+
+export const GENERATED_DOC_PATHS = [
+  ".tesser/docs/manifest.json",
+  ".tesser/docs/README.md",
+  ".tesser/docs/cli.md",
+  ".tesser/docs/sdk.md",
+  ".tesser/docs/connectors.md",
+] as const;
+
+interface JsonObject {
+  [key: string]: unknown;
+}
+
+export function projectPackageJson(name: string, version: string): JsonObject {
+  return {
+    name,
+    private: true,
+    type: "module",
+    packageManager: "pnpm@9.12.0",
+    scripts: { test: "tesser test", deploy: "tesser deploy", dev: "tesser dev" },
+    dependencies: {
+      "@devosurf/tesser-sdk": version,
+      "@devosurf/tesser-connectors": version,
+      zod: "^4",
+    },
+    devDependencies: {
+      "@devosurf/tesser": version,
+      "@devosurf/tesser-server": version,
+      "@devosurf/tesser-testing": version,
+      vitest: "^4",
+    },
+  };
+}
+
+export function writeProjectAgentInstructions(root: string, projectName: string, version: string, opts: { overwrite: boolean }): boolean {
+  const path = join(root, "AGENTS.md");
+  if (!opts.overwrite && existsSync(path)) return false;
+  writeFileSync(path, projectAgentsMd(projectName, version));
+  return true;
+}
+
+export function writeTesserGeneratedDocs(root: string, projectName: string, version: string): string[] {
+  const docsDir = join(root, ".tesser", "docs");
+  mkdirSync(docsDir, { recursive: true });
+  const docs: Record<string, string> = {
+    "manifest.json": JSON.stringify(
+      {
+        kind: "tesser-agent-docs",
+        schemaVersion: 1,
+        generatedBy: "@devosurf/tesser",
+        tesserVersion: version,
+        project: projectName,
+        generatedFiles: GENERATED_DOC_PATHS.filter((path) => path !== ".tesser/docs/manifest.json"),
+      },
+      null,
+      2,
+    ) + "\n",
+    "README.md": docsReadmeMd(projectName, version),
+    "cli.md": cliReferenceMd(version),
+    "sdk.md": sdkReferenceMd(version),
+    "connectors.md": connectorsReferenceMd(version),
+  };
+  for (const [file, content] of Object.entries(docs)) {
+    writeFileSync(join(docsDir, file), content);
+  }
+  return [...GENERATED_DOC_PATHS];
+}
+
+export function tesserGitignore(): string {
+  return `node_modules/\n.env\n\n# Tesser local runtime state from \`tesser dev\`; keep generated agent docs committed.\n.tesser/*\n!.tesser/\n!.tesser/docs/\n!.tesser/docs/**\n`;
+}
+
+export function ensureTesserDocsGitignore(root: string): boolean {
+  const path = join(root, ".gitignore");
+  const block = `\n# Tesser local runtime state from \`tesser dev\`; keep generated agent docs committed.\n.tesser/*\n!.tesser/\n!.tesser/docs/\n!.tesser/docs/**\n`;
+  if (!existsSync(path)) {
+    writeFileSync(path, tesserGitignore());
+    return true;
+  }
+  const existing = readFileSync(path, "utf8");
+  if (existing.includes("!.tesser/docs/**")) return false;
+  writeFileSync(path, existing.replace(/\s*$/, "\n") + block);
+  return true;
+}
+
+export function upgradeProject(
+  out: Output,
+  project: { name: string; root: string },
+  version: string,
+): void {
+  const packagePath = join(project.root, "package.json");
+  if (!existsSync(packagePath)) {
+    throw new CliError(EXIT.USAGE, "not inside a package-backed Tesser project (missing package.json)");
+  }
+  const pkg = JSON.parse(readFileSync(packagePath, "utf8")) as JsonObject;
+  pinTesserPackages(pkg, version);
+  writeFileSync(packagePath, JSON.stringify(pkg, null, 2) + "\n");
+
+  const docs = writeTesserGeneratedDocs(project.root, project.name, version);
+  const gitignoreUpdated = ensureTesserDocsGitignore(project.root);
+  const agentInstructionsCreated = writeProjectAgentInstructions(project.root, project.name, version, { overwrite: false });
+  const next = [
+    "pnpm install",
+    "tesser test --json",
+    "git add package.json pnpm-lock.yaml .gitignore AGENTS.md .tesser/docs && git commit -m \"upgrade tesser\"",
+  ];
+
+  out.data(
+    { upgraded: project.root, tesserVersion: version, docs, packageJson: "package.json", gitignoreUpdated, agentInstructionsCreated, next },
+    () =>
+      `upgraded ${project.root} to Tesser ${version}\nnext:\n  pnpm install\n  tesser test --json\n  git add package.json pnpm-lock.yaml .gitignore AGENTS.md .tesser/docs && git commit -m "upgrade tesser"`,
+  );
+}
+
+function pinTesserPackages(pkg: JsonObject, version: string): void {
+  const dependencies = objectField(pkg, "dependencies");
+  for (const name of TESSER_DEPENDENCIES) dependencies[name] = version;
+  const devDependencies = objectField(pkg, "devDependencies");
+  for (const name of TESSER_DEV_DEPENDENCIES) devDependencies[name] = version;
+}
+
+function objectField(pkg: JsonObject, key: string): JsonObject {
+  const existing = pkg[key];
+  if (existing && typeof existing === "object" && !Array.isArray(existing)) return existing as JsonObject;
+  const next: JsonObject = {};
+  pkg[key] = next;
+  return next;
+}
+
+function projectAgentsMd(projectName: string, version: string): string {
+  return `# Working in this Tesser Project\n\nThis repository is a Tesser **Project**: one git repo of automations deployed to a Tesser **Instance**.\n\n## Read first\n- [Generated Tesser reference](./.tesser/docs/README.md) — generated for Tesser ${version}.\n- [CLI reference](./.tesser/docs/cli.md) — use \`--json\` for machine-readable output.\n- [SDK reference](./.tesser/docs/sdk.md) — authoring pattern, \`ctx.step\`, tests.\n- [Connector reference](./.tesser/docs/connectors.md) — safe Connection and Secret usage.\n\n## Project rules\n- Use Tesser terms: **Automation**, **Trigger**, **Step**, **Project**, **Instance**, **Connector**, **Connection**, **Secret**, **Credential broker**, **Replay**.\n- One Automation per directory under \`automations/\`; colocate \`*.test.ts\` with each Automation.\n- Every side effect and external call must be inside \`ctx.step("stable-name", async () => ...)\`.\n- Declare credentials statically with \`connections: { ... }\` and \`secrets: { ... }\`; never read or print secret values.\n- Run \`pnpm install\` after init/upgrade, commit \`pnpm-lock.yaml\`, and never commit \`node_modules/\`.\n- Before deploy, run \`tesser test --json\` (and usually \`tesser build --json\`).\n- Deploy from git. Commit generated Tesser docs under \`.tesser/docs/\`; local runtime state in other \`.tesser/*\` paths stays ignored.\n\n## Upgrade rule\nTo update this Project's pinned Tesser packages and generated references, run the target CLI version explicitly:\n\n\`\`\`bash\nnpx @devosurf/tesser@<version> upgrade\npnpm install\ntesser test --json\n\`\`\`\n\nProject name: \`${projectName}\`.\n`;
+}
+
+function docsReadmeMd(projectName: string, version: string): string {
+  return `# Tesser agent reference\n\nGenerated for Project \`${projectName}\` by \`@devosurf/tesser@${version}\`. Treat this directory as generated/vendor reference: do not hand-edit files under \`.tesser/docs/\`; customize local policy in \`AGENTS.md\`.\n\n## Start here\n1. Read \`AGENTS.md\` for project-specific policy.\n2. Use [cli.md](./cli.md) for command sequences and safe secret handling.\n3. Use [sdk.md](./sdk.md) before editing an Automation.\n4. Use [connectors.md](./connectors.md) before adding a Connection or Secret.\n\n## Version contract\nTesser packages in \`package.json\` should be pinned exactly to \`${version}\`:\n\n- \`@devosurf/tesser\`\n- \`@devosurf/tesser-sdk\`\n- \`@devosurf/tesser-connectors\`\n- \`@devosurf/tesser-testing\`\n- \`@devosurf/tesser-server\`\n\nTo upgrade, run the target CLI version so docs and packages move together:\n\n\`\`\`bash\nnpx @devosurf/tesser@<version> upgrade\npnpm install\ntesser test --json\n\`\`\`\n\nCommit \`package.json\`, \`pnpm-lock.yaml\`, \`.tesser/docs/\`, and any Automation/test changes together. Do not commit \`node_modules/\` or local runtime files such as \`.tesser/master.key\`.\n`;
+}
+
+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`;
+}
+
+function sdkReferenceMd(version: string): string {
+  return `# Tesser SDK reference\n\nGenerated for \`@devosurf/tesser-sdk@${version}\`. Author ordinary async TypeScript; Tesser durability comes only from Steps.\n\n## Minimal Automation\n\n\`\`\`ts\nimport { defineAutomation, onWebhook } from "@devosurf/tesser-sdk";\nimport { z } from "zod";\n\nexport default defineAutomation({\n  id: "hello",\n  trigger: onWebhook({ input: z.object({ name: z.string().default("world") }) }),\n  output: z.object({ greeting: z.string() }),\n\n  run: async (input, ctx) => {\n    const greeting = await ctx.step("compose", async () => \`hello, \${input.name}!\`);\n    return { greeting };\n  },\n});\n\`\`\`\n\n## Non-negotiable rules\n\n- Use **Step**, not node/task/action, for durable checkpoints.\n- Every side effect, external I/O call, Connector Action, bespoke HTTP request, file/network operation, or secret-dependent operation must happen inside \`ctx.step(name, fn)\`.\n- Step names are stable API for the journal. Use short, descriptive names such as \`fetch-customer\`, \`post-to-slack\`, \`charge-card\`.\n- Step outputs are journaled and must be serializable. Return plain data, not functions, class instances, streams, sockets, or live handles.\n- An Automation declares credentials statically at the top level. Do not hide requirements inside \`run\`.\n- Do not access provider tokens directly. Runtime-injected \`ctx.connections.*\` and \`ctx.secrets.*\` are the only runtime credential surfaces.\n\n## Triggers\n\n\`\`\`ts\nimport { onWebhook, onSchedule, onEvent } from "@devosurf/tesser-sdk";\n\nconst webhook = onWebhook({ input: schema, respond: "sync" });\nconst schedule = onSchedule({ cron: "0 9 * * *", tz: "UTC" });\nconst event = onEvent(myEvent);\n\`\`\`\n\nConnector triggers are reached from the Connector import, for example \`github.triggers.issueOpened({ repo: "owner/repo" })\` when supported.\n\n## Connections and Secrets\n\n\`\`\`ts\nimport { defineAutomation, onWebhook, secret } from "@devosurf/tesser-sdk";\nimport { slack } from "@devosurf/tesser-connectors";\nimport { z } from "zod";\n\nexport default defineAutomation({\n  id: "notify",\n  trigger: onWebhook({ input: z.object({ text: z.string() }) }),\n  connections: { slack },\n  secrets: { signingKey: secret({ describe: "Shared HMAC signing key" }) },\n  output: z.object({ ok: z.boolean() }),\n\n  run: async (input, ctx) => {\n    await ctx.step("post-message", () =>\n      ctx.connections.slack.chat.postMessage({ channel: "#ops", text: input.text }),\n    );\n    return { ok: true };\n  },\n});\n\`\`\`\n\nDeploy halts if required Connections or Secrets are missing. The agent should surface the connect link to a human and poll status; it must not collect the secret value itself.\n\n## Tests\n\nColocate tests beside each Automation.\n\n\`\`\`ts\nimport { createTest } from "@devosurf/tesser-testing";\nimport automation from "./index";\n\ntest("greets by name", async () => {\n  const t = createTest({ automation });\n  const { result } = await t.run({ input: { name: "tesser" } });\n  expect(result).toEqual({ greeting: "hello, tesser!" });\n});\n\`\`\`\n\nFor Connector calls, mock the Step result by Step name. Replay fixtures produced by \`tesser replay <runId>\` should become permanent regression tests.\n`;
+}
+
+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  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/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 and Slack event 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`;
+}

package/src/index.ts

@@ -16,6 +16,7 @@ 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 { upgradeProject } from "./commands/project-docs.js";
 import { replay } from "./commands/replay.js";
 import { runTests } from "./commands/test.js";
 
@@ -74,7 +75,19 @@ program
   .action((name: string, cmdOpts: { dir?: string; instance?: string }) => {
     const { out } = setup();
     try {
-      init(out, name, cmdOpts);
+      init(out, name, cmdOpts, VERSION);
+    } catch (err) {
+      toExit(err, out);
+    }
+  });
+
+program
+  .command("upgrade")
+  .description("pin Tesser packages to this CLI version and refresh generated Project docs")
+  .action(() => {
+    const { out, opts } = setup();
+    try {
+      upgradeProject(out, requireProject(opts), VERSION);
     } catch (err) {
       toExit(err, out);
     }