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

package/package.json

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

package/src/commands/project-docs.ts

@@ -143,7 +143,7 @@ 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 \`--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 --url 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 --url 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 {
@@ -151,5 +151,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  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`;
+  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 and Outlook Mail Actions (Outlook accepts optional \`mailbox\` for shared mailbox \`/users/{userPrincipalName}\` access), 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`;
 }

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,

package/src/index.ts

@@ -10,6 +10,7 @@ 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 { DEFAULT_INSTANCE_URL, resolveLoginInstance, type LoginCommandOptions } from "./login.js";
 import { CliError, Output, toExit } from "./output.js";
 import { discoverLocalAutomations, loadAutomationDef } from "./project.js";
 import { authClaudeCode, authPi } from "./commands/auth.js";
@@ -96,21 +97,23 @@ program
 program
   .command("login")
   .option("--token <token>", "API token from the instance (printed at first boot)")
-  .option("--instance <url>", "instance URL", "http://localhost:8377")
+  .option("--url <url>", `instance URL (defaults to ${DEFAULT_INSTANCE_URL})`)
+  .option("--instance <url>", "deprecated alias for --url")
   .option("--save-profile <name>", "profile name", "default")
   .description("store instance credentials in ~/.config/tesser (or use env TESSER_TOKEN)")
-  .action(async (cmdOpts: { token?: string; instance: string; saveProfile: string }) => {
+  .action(async (cmdOpts: LoginCommandOptions) => {
     const { out, opts } = setup();
     try {
       const token = cmdOpts.token ?? opts.token;
       if (!token) throw new CliError(EXIT.USAGE, "missing required option '--token <token>'");
-      const client = new ApiClient(cmdOpts.instance, token);
+      const instance = resolveLoginInstance(cmdOpts, opts);
+      const client = new ApiClient(instance, token);
       await client.get("/health"); // verify before storing
       const config = readConfig();
-      config.profiles = { ...config.profiles, [cmdOpts.saveProfile]: { url: cmdOpts.instance, token } };
+      config.profiles = { ...config.profiles, [cmdOpts.saveProfile]: { url: instance, token } };
       config.current = cmdOpts.saveProfile;
       writeConfig(config);
-      out.data({ profile: cmdOpts.saveProfile, url: cmdOpts.instance }, () => `logged in to ${cmdOpts.instance} (profile "${cmdOpts.saveProfile}")`);
+      out.data({ profile: cmdOpts.saveProfile, url: instance }, () => `logged in to ${instance} (profile "${cmdOpts.saveProfile}")`);
     } catch (err) {
       toExit(err, out);
     }

package/src/login.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "vitest";
+import { DEFAULT_INSTANCE_URL, resolveLoginInstance } from "./login.js";
+
+describe("tesser login target resolution", () => {
+  test("accepts --url on the login command", () => {
+    expect(resolveLoginInstance({ url: "https://inst.example" }, {})).toBe("https://inst.example");
+  });
+
+  test("accepts the global --url before login", () => {
+    expect(resolveLoginInstance({}, { url: "https://global.example" })).toBe("https://global.example");
+  });
+
+  test("keeps --instance as a backwards-compatible alias", () => {
+    expect(resolveLoginInstance({ instance: "https://old.example" }, { url: "https://global.example" })).toBe("https://old.example");
+  });
+
+  test("defaults to the local dev instance", () => {
+    expect(resolveLoginInstance({}, {})).toBe(DEFAULT_INSTANCE_URL);
+  });
+});

package/src/login.ts

@@ -0,0 +1,18 @@
+import { DEFAULT_INSTANCE_URL } from "./config.js";
+
+export { DEFAULT_INSTANCE_URL };
+
+export interface LoginCommandOptions {
+  token?: string;
+  url?: string;
+  instance?: string;
+  saveProfile: string;
+}
+
+export interface LoginGlobalOptions {
+  url?: string;
+}
+
+export function resolveLoginInstance(cmdOpts: Pick<LoginCommandOptions, "url" | "instance">, globalOpts: LoginGlobalOptions): string {
+  return cmdOpts.url ?? cmdOpts.instance ?? globalOpts.url ?? DEFAULT_INSTANCE_URL;
+}