@specific.dev/cli 0.1.214 → 0.1.216

package/dist/cli.js

@@ -367991,6 +367991,39 @@ var ApiClient = class {
     }
     return response.json();
   }
+  async getAgentRegistration() {
+    const url = `${this.baseUrl}/agent-registration`;
+    writeLog("api", `GET ${url}`);
+    const response = await fetch(url, {
+      headers: await this.authHeaders()
+    });
+    writeLog("api", `Response: ${response.status} ${response.statusText}`);
+    if (!response.ok) {
+      throw await readApiError(
+        response,
+        "Failed to get agent registration",
+        `GET ${url}`
+      );
+    }
+    return response.json();
+  }
+  async claimAgentRegistration() {
+    const url = `${this.baseUrl}/agent-registration/claim`;
+    writeLog("api", `POST ${url}`);
+    const response = await fetch(url, {
+      method: "POST",
+      headers: await this.authHeaders()
+    });
+    writeLog("api", `Response: ${response.status} ${response.statusText}`);
+    if (!response.ok) {
+      throw await readApiError(
+        response,
+        "Failed to claim agent registration",
+        `POST ${url}`
+      );
+    }
+    return response.json();
+  }
   async submitFeedback(args) {
     const url = `${this.baseUrl}/feedback`;
     writeLog("api", `POST ${url}`);
@@ -368081,6 +368114,13 @@ var SpecificClient = class {
   async getMe() {
     return await this.client.getMe();
   }
+  // --- Agent registration (WorkOS auth.md) ---
+  async getAgentRegistration() {
+    return await this.client.getAgentRegistration();
+  }
+  async claimAgentRegistration() {
+    return await this.client.claimAgentRegistration();
+  }
   // --- Deployments ---
   async createDeployment(projectId, environment, options2) {
     return toDeployment(
@@ -374758,6 +374798,93 @@ async function refreshAccessToken(refreshToken) {
   }
   return response.json();
 }
+var WORKOS_AUTHKIT_DOMAIN = "auth.specific.dev";
+function authkitUrl(path28) {
+  return `https://${WORKOS_AUTHKIT_DOMAIN}${path28}`;
+}
+var AgentAuthError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AgentAuthError";
+  }
+};
+async function postAuthkitJson(path28, body, operation) {
+  const response = await fetch(authkitUrl(path28), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const text = await response.text();
+  let json = null;
+  try {
+    json = JSON.parse(text);
+  } catch {
+  }
+  if (!response.ok) {
+    const code = json?.code ?? json?.error ?? `http_${response.status}`;
+    const message = json?.message ?? json?.error_description ?? text.slice(0, 200);
+    throw new AgentAuthError(String(code), `${operation}: ${message}`);
+  }
+  return json;
+}
+async function registerAgentIdentity() {
+  return postAuthkitJson("/agent/identity", { type: "anonymous" }, "Agent registration failed");
+}
+async function refreshAgentIdentity(refreshToken) {
+  return postAuthkitJson(
+    "/agent/identity",
+    { type: "refresh", refresh_token: refreshToken },
+    "Agent identity refresh failed"
+  );
+}
+async function startAgentClaim(claimToken, email) {
+  const res = await postAuthkitJson(
+    "/agent/identity/claim",
+    { type: "service_auth", claim_token: claimToken, login_hint: email },
+    "Starting the claim failed"
+  );
+  const verificationUri = res.attempt?.verification_uri ?? res.claim?.attempt?.verification_uri;
+  if (!verificationUri) {
+    throw new AgentAuthError("invalid_response", "Claim attempt response had no verification_uri");
+  }
+  return { verificationUri };
+}
+async function completeAgentClaim(claimToken, userCode) {
+  const res = await postAuthkitJson(
+    "/agent/identity/claim/complete",
+    { claim_token: claimToken, user_code: userCode },
+    "Completing the claim failed"
+  );
+  if (!res.identity?.assertion) {
+    throw new AgentAuthError("invalid_response", "Claim completion returned no identity");
+  }
+  return res;
+}
+async function exchangeAgentAssertion(assertion) {
+  const response = await fetch(authkitUrl("/oauth2/token"), {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion
+    })
+  });
+  const text = await response.text();
+  let json = null;
+  try {
+    json = JSON.parse(text);
+  } catch {
+  }
+  if (!response.ok || !json?.access_token) {
+    const code = json?.error ?? `http_${response.status}`;
+    throw new AgentAuthError(
+      String(code),
+      `Agent token exchange failed: ${json?.error_description ?? text.slice(0, 200)}`
+    );
+  }
+  return { access_token: json.access_token, expires_in: Number(json.expires_in ?? 300) };
+}
 
 // src/lib/auth/login.tsx
 import React from "react";
@@ -374997,13 +375124,16 @@ async function fetchGithubActionsIdToken() {
 }
 
 // src/lib/auth/credentials.ts
+function isAgentCredentials(credentials) {
+  return credentials?.kind === "agent";
+}
 function getUserCredentialsDir() {
   return path18.join(os5.homedir(), ".specific");
 }
 function getCredentialsPath() {
   return path18.join(getUserCredentialsDir(), "credentials.json");
 }
-function readUserCredentials() {
+function readStoredCredentials() {
   const credentialsPath = getCredentialsPath();
   if (!fs20.existsSync(credentialsPath)) {
     return null;
@@ -375015,6 +375145,15 @@ function readUserCredentials() {
     return null;
   }
 }
+function readUserCredentials() {
+  const credentials = readStoredCredentials();
+  if (!credentials || isAgentCredentials(credentials)) return null;
+  return credentials;
+}
+function readAgentCredentials() {
+  const credentials = readStoredCredentials();
+  return isAgentCredentials(credentials) ? credentials : null;
+}
 function writeUserCredentials(credentials) {
   const dir = getUserCredentialsDir();
   if (!fs20.existsSync(dir)) {
@@ -375035,12 +375174,72 @@ function getEnvApiKey() {
   return process.env.SPECIFIC_API_KEY || null;
 }
 function isLoggedIn() {
-  return getEnvApiKey() !== null || readUserCredentials() !== null;
+  return getEnvApiKey() !== null || readStoredCredentials() !== null;
 }
 function getUserId() {
-  const credentials = readUserCredentials();
+  const credentials = readStoredCredentials();
   return credentials?.userId ?? null;
 }
+var ACCESS_TOKEN_REFRESH_BUFFER_MS = 30 * 1e3;
+var AgentRegistrationExpiredError = class extends Error {
+  constructor() {
+    super(
+      "This agent registration has expired. Run 'specific login --agent' to register again."
+    );
+    this.name = "AgentRegistrationExpiredError";
+  }
+};
+function applyAgentIdentity(credentials, identity, extra = {}) {
+  const updated = {
+    ...credentials,
+    ...extra,
+    assertion: identity.assertion,
+    assertionExpiresAt: Date.parse(identity.expires_at) || Date.now() + 60 * 60 * 1e3,
+    refreshToken: identity.refresh_token?.value ?? credentials.refreshToken,
+    accessToken: void 0,
+    accessTokenExpiresAt: void 0
+  };
+  writeUserCredentials(updated);
+  return updated;
+}
+async function getAgentAccessToken(credentials) {
+  const now = Date.now();
+  if (credentials.accessToken && credentials.accessTokenExpiresAt && credentials.accessTokenExpiresAt - ACCESS_TOKEN_REFRESH_BUFFER_MS > now) {
+    return credentials.accessToken;
+  }
+  let current = credentials;
+  const mint = async () => {
+    const token = await exchangeAgentAssertion(current.assertion);
+    const expiresAt = getTokenExpiresAt(token.access_token) ?? Date.now() + token.expires_in * 1e3;
+    current = { ...current, accessToken: token.access_token, accessTokenExpiresAt: expiresAt };
+    writeUserCredentials(current);
+    return token.access_token;
+  };
+  const refresh = async () => {
+    if (!current.refreshToken) {
+      throw new AgentRegistrationExpiredError();
+    }
+    try {
+      const refreshed = await refreshAgentIdentity(current.refreshToken);
+      current = applyAgentIdentity(current, refreshed.identity);
+    } catch (err) {
+      if (err instanceof AgentAuthError) throw new AgentRegistrationExpiredError();
+      throw err;
+    }
+  };
+  if (current.assertionExpiresAt - ACCESS_TOKEN_REFRESH_BUFFER_MS <= now) {
+    await refresh();
+  }
+  try {
+    return await mint();
+  } catch (err) {
+    if (err instanceof AgentAuthError && err.code === "invalid_grant") {
+      await refresh();
+      return await mint();
+    }
+    throw err;
+  }
+}
 async function saveCredentialsFromToken(token) {
   const client2 = new ApiClient({ token: token.access_token });
   const user = await client2.getMe();
@@ -375060,10 +375259,16 @@ async function getValidAccessToken() {
   if (isGithubActions()) {
     return await fetchGithubActionsIdToken();
   }
-  const credentials = readUserCredentials();
-  if (!credentials) {
-    throw new Error("Not logged in. Run 'specific login' first.");
+  const stored = readStoredCredentials();
+  if (!stored) {
+    throw new Error(
+      "Not logged in. Run 'specific login' (or 'specific login --agent' for an unattended agent) first."
+    );
+  }
+  if (isAgentCredentials(stored)) {
+    return await getAgentAccessToken(stored);
   }
+  const credentials = stored;
   if (!credentials.userId) {
     const result = await performLogin({ isReauthentication: true });
     if (!result.success) {
@@ -375164,7 +375369,7 @@ function trackEvent(event, properties) {
     event,
     properties: {
       ...properties,
-      cli_version: "0.1.214",
+      cli_version: "0.1.216",
       platform: process.platform,
       node_version: process.version,
       project_id: getProjectId()
@@ -379730,6 +379935,119 @@ function cleanCommand(instanceKey) {
   }
 }
 
+// src/lib/auth/agent-login.ts
+function formatDeadline(date) {
+  return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+async function performAgentLogin() {
+  writeLog("auth", "Registering anonymous agent identity with AuthKit");
+  const registration = await registerAgentIdentity();
+  writeLog("auth", `Agent registration received: ${registration.id}`);
+  const base = {
+    kind: "agent",
+    registrationId: registration.id,
+    assertion: registration.identity.assertion,
+    assertionExpiresAt: Date.parse(registration.identity.expires_at) || Date.now() + 36e5,
+    refreshToken: registration.identity.refresh_token?.value,
+    claimToken: registration.claim?.token,
+    claimTokenExpiresAt: registration.claim ? Date.parse(registration.claim.expires_at) : void 0,
+    claimed: false,
+    userId: ""
+  };
+  const accessToken = await getAgentAccessToken(base);
+  const client2 = new SpecificClient({ accessToken });
+  const me = await client2.getMe();
+  const info = await client2.getAgentRegistration();
+  writeUserCredentials({ ...readAgentCredentials() ?? base, userId: me.id });
+  writeLog("auth", `Agent credentials written for user ${me.id}`);
+  return { registrationId: registration.id, claimDeadlineAt: new Date(info.claimDeadlineAt) };
+}
+function printAgentLoginSummary(result) {
+  console.log("Registered this CLI as an agent. No login needed to deploy.");
+  console.log("");
+  console.log("This account is UNCLAIMED:");
+  console.log("  - it can hold one project on the free tier");
+  console.log(`  - it and everything deployed to it are deleted at ${formatDeadline(result.claimDeadlineAt)}`);
+  console.log("    unless a person claims it before then");
+  console.log("");
+  console.log("To hand the account to its owner, run (with their email):");
+  console.log("  specific claim --email <email>");
+}
+function requireAgentCredentials() {
+  const stored = readStoredCredentials();
+  if (!stored) {
+    throw new Error("Not registered as an agent. Run 'specific login --agent' first.");
+  }
+  if (stored.kind !== "agent") {
+    throw new Error(
+      "Claiming only applies to agent registrations. This CLI is logged in as a person already."
+    );
+  }
+  return stored;
+}
+async function startClaim(email) {
+  const credentials = requireAgentCredentials();
+  if (credentials.claimed) {
+    const client2 = new SpecificClient({ tokenProvider: getValidAccessToken });
+    const me = await client2.getMe();
+    return { phase: "completed", email: me.email, alreadyClaimed: true };
+  }
+  if (credentials.claimVerified) {
+    return await handOverToPlatform(credentials);
+  }
+  if (!credentials.claimToken) {
+    throw new Error("This registration has no claim token; run 'specific login --agent' again.");
+  }
+  writeLog("auth", `Starting agent claim for ${email}`);
+  const { verificationUri } = await startAgentClaim(credentials.claimToken, email);
+  return { phase: "started", verificationUri };
+}
+async function completeClaim(userCode) {
+  let credentials = requireAgentCredentials();
+  if (credentials.claimed) {
+    const client2 = new SpecificClient({ tokenProvider: getValidAccessToken });
+    const me = await client2.getMe();
+    return { phase: "completed", email: me.email, alreadyClaimed: true };
+  }
+  if (credentials.claimVerified) {
+    return await handOverToPlatform(credentials);
+  }
+  if (!credentials.claimToken) {
+    throw new Error("This registration has no claim token; run 'specific login --agent' again.");
+  }
+  writeLog("auth", "Completing agent claim");
+  const verified = await completeAgentClaim(credentials.claimToken, userCode.trim());
+  credentials = applyAgentIdentity(credentials, verified.identity, { claimVerified: true });
+  return await handOverToPlatform(credentials);
+}
+async function handOverToPlatform(credentials) {
+  const client2 = new SpecificClient({ tokenProvider: getValidAccessToken });
+  const result = await client2.claimAgentRegistration();
+  writeUserCredentials({ ...credentials, claimVerified: void 0, claimed: true, userId: result.user.id });
+  writeLog("auth", `Agent registration claimed by ${result.user.email}`);
+  return { phase: "completed", email: result.user.email, alreadyClaimed: false };
+}
+function describeClaimError(err) {
+  if (err instanceof AgentAuthError) {
+    switch (err.code) {
+      case "claim_not_confirmed":
+        return "The user hasn't finished on the claim page yet. Ask them to complete it, then retry.";
+      case "invalid_user_code":
+        return "That code was not accepted. Ask the user to read it again from the claim page.";
+      case "user_code_expired":
+        return "The code expired. Run 'specific claim --email <email>' again for a fresh link.";
+      case "claim_expired":
+      case "claim_revoked":
+      case "already_claimed":
+      case "invalid_claim_token":
+        return `${err.message}. Run 'specific login --agent' to register again.`;
+      default:
+        return err.message;
+    }
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+
 // src/commands/login.tsx
 async function loginCommand(options2 = {}) {
   if (getEnvApiKey()) {
@@ -379740,6 +380058,16 @@ async function loginCommand(options2 = {}) {
     console.log("Already logged in.");
     return;
   }
+  if (options2.agent) {
+    try {
+      const result2 = await performAgentLogin();
+      printAgentLoginSummary(result2);
+    } catch (err) {
+      console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
   if (options2.deviceCode) {
     const result2 = await performDeviceCodeLogin(options2.deviceCode);
     if (!result2.success) {
@@ -379795,6 +380123,64 @@ function logoutCommand() {
   render7(/* @__PURE__ */ React9.createElement(LogoutUI, null));
 }
 
+// src/commands/claim.ts
+import { createInterface } from "readline";
+function printCompleted(outcome) {
+  if (outcome.alreadyClaimed) {
+    console.log(`This agent account is already claimed by ${outcome.email}.`);
+    return;
+  }
+  console.log(`Claimed. This account and its projects now belong to ${outcome.email}.`);
+  console.log("They can manage everything at https://dashboard.specific.dev.");
+  console.log("This CLI keeps working as their agent.");
+}
+async function askForCode() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await new Promise((resolve10) => {
+      rl.question("Enter the code shown on the claim page: ", (answer) => resolve10(answer));
+    });
+  } finally {
+    rl.close();
+  }
+}
+async function claimCommand(options2) {
+  try {
+    if (options2.code) {
+      const outcome = await completeClaim(options2.code);
+      if (outcome.phase === "completed") printCompleted(outcome);
+      return;
+    }
+    if (!options2.email) {
+      console.error(
+        "Usage: specific claim --email <email>   (start: prints a link for the user)\n       specific claim --code <code>     (finish: the code the user read off that page)"
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const started = await startClaim(options2.email);
+    if (started.phase === "completed") {
+      printCompleted(started);
+      return;
+    }
+    console.log("Claim started. Give the user this link:");
+    console.log(`  ${started.verificationUri}`);
+    console.log("");
+    console.log("They sign in there and are shown a short code.");
+    if (isInteractive()) {
+      const code = await askForCode();
+      const outcome = await completeClaim(code);
+      if (outcome.phase === "completed") printCompleted(outcome);
+      return;
+    }
+    console.log("Once they give you the code, run:");
+    console.log("  specific claim --code <code>");
+  } catch (err) {
+    console.error(`Error: ${describeClaimError(err)}`);
+    process.exitCode = 1;
+  }
+}
+
 // src/commands/beta.tsx
 import React10, { useState as useState9, useEffect as useEffect9 } from "react";
 import { render as render8, Text as Text10, Box as Box9, useInput as useInput5, useApp as useApp5 } from "ink";
@@ -379892,7 +380278,7 @@ function compareVersions(a, b) {
   return 0;
 }
 async function checkForUpdate() {
-  const currentVersion = "0.1.214";
+  const currentVersion = "0.1.216";
   const response = await fetch(`${BINARIES_BASE_URL}/latest?t=${Date.now()}`);
   if (!response.ok) {
     throw new Error(`Failed to check for updates: HTTP ${response.status}`);
@@ -380926,7 +381312,7 @@ async function feedbackCommand(message) {
     await client2.submitFeedback({
       message: trimmed,
       projectId,
-      cliVersion: "0.1.214"
+      cliVersion: "0.1.216"
     });
     trackEvent("feedback_submitted", { hasProject: !!projectId });
     console.log("Thanks! We will take a look at your feedback shortly.");
@@ -380945,7 +381331,7 @@ async function feedbackCommand(message) {
 var program = new Command();
 var env = "production";
 var envLabel = env !== "production" ? `[${env.toUpperCase()}] ` : "";
-program.name("specific").description(`${envLabel}Infrastructure-as-code for coding agents`).version("0.1.214").enablePositionalOptions();
+program.name("specific").description(`${envLabel}Infrastructure-as-code for coding agents`).version("0.1.216").enablePositionalOptions();
 program.command("init").description("Initialize project for use with a coding agent").option("--agent <name...>", "Agents to configure (cursor, claude, codex, other)").addHelpText("after", `
 Examples:
   $ specific init
@@ -381098,7 +381484,14 @@ Examples:
   $ specific feedback "specific query has no way to export results to CSV"`).action((message) => feedbackCommand(message));
 program.command("beta").description("Manage beta feature flags").action(betaCommand);
 program.command("update").description("Update Specific CLI to the latest version").action(updateCommand);
-program.command("login").description("Log in to Specific").option("--device-code <code>", "Complete login using a device code from a previous non-interactive login").action((options2) => loginCommand(options2));
+program.command("login").description("Log in to Specific").option("--device-code <code>", "Complete login using a device code from a previous non-interactive login").option("--agent", "Register this CLI as an agent (WorkOS agent registration) \u2014 no browser or human needed").addHelpText("after", `
+Examples:
+  $ specific login
+  $ specific login --agent      # unattended: registers an agent account the user can claim later`).action((options2) => loginCommand(options2));
+program.command("claim").description("Hand an agent-registered account to its owner (WorkOS claim ceremony)").option("--email <email>", "The owner's email: starts the claim and prints a link for them").option("--code <code>", "The code the owner read off the claim page: completes the claim").addHelpText("after", `
+Examples:
+  $ specific claim --email jane@example.com
+  $ specific claim --code 123456`).action((options2) => claimCommand(options2));
 program.command("logout").description("Log out of Specific").action(logoutCommand);
 var commandName = process.argv[2] || "help";
 trackEvent("cli_command_invoked", { command: commandName });

package/dist/docs/index.md

@@ -20,7 +20,7 @@ After deploying, the user can manage their project from the Specific Dashboard a
 
 ## Authentication
 
-Commands that talk to Specific Cloud — deploying, `specific status`, `specific deployment show`, `specific query`, and other project and environment commands — require the user to be signed in. Interactively, run `specific login`; it opens a browser (or prints a device-authorization link) for the user to approve.
+Commands that talk to Specific Cloud — deploying, `specific status`, `specific deployment show`, `specific query`, and other project and environment commands — require the user to be signed in. Interactively, run `specific login`; it opens a browser (or prints a device-authorization link) for the user to approve. With no user available, run `specific login --agent`: it registers the CLI as an agent with no human involved, giving it an unclaimed account that holds one free-tier project and is deleted after 48 hours unless claimed. Hand it over with `specific claim --email <email>` (prints a link for the user) followed by `specific claim --code <code>` (the code they see after signing in).
 
 In headless environments where nobody can complete the browser flow (CI, cloud coding agents), set the `SPECIFIC_API_KEY` environment variable instead. The user creates an API key in the dashboard at https://dashboard.specific.dev/user-settings under **API keys**; when the variable is set, every command authenticates with it directly and no login is needed. If a command reports you are not logged in and an interactive login is not possible, ask the user to create an API key there and add it to this environment as `SPECIFIC_API_KEY`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/cli",
-  "version": "0.1.214",
+  "version": "0.1.216",
   "description": "CLI for Specific infrastructure-as-code",
   "type": "module",
   "main": "dist/cli.js",