@pipod/cli 0.1.4 → 0.1.6

package/README.md

@@ -4,15 +4,16 @@ Run [pi](https://github.com/earendil-works/pi) coding-agent sessions in server-m
 
 ```bash
 npm install -g @pipod/cli    # or from a checkout of this directory: npm ci && npm run build && npm install -g .
-pipod login --server <url>   # sign in to a pi pod server (the hosted one without --server)
+pipod login --server <url>   # sign in to your pi pod server
 pipod                        # launch a pod for the current directory and attach
 pipod --help                 # every command and launch option
 pipod update                 # upgrade the way it was installed
 ```
 
 Running your own server: [docs/self-host.md](https://github.com/pi-pod/pipod/blob/main/docs/self-host.md).
-A self-hosted server is deployed from a checkout; install the CLI from the same checkout so the
-two match.
+The npm release works with any server at least as new as it; a CLI newer than its server is
+refused, so upgrade the server first. Building the CLI from the server's own checkout always
+matches.
 
 ## Secrets
 
@@ -53,12 +54,12 @@ Details, limits and a manual test checklist: [docs/workspace-seeding.md](docs/wo
 Local images named in a prompt (clipboard pastes, `@shot.png`, file paths) are
 attached inline for the pod agent: [docs/image-attachments.md](docs/image-attachments.md).
 
-## Personal workstations (SaaS)
+## Personal workstations (hosted service)
 
-On the hosted service each user gets a whole machine of their own, which sleeps when idle. The
-first command after it sleeps waits for it to come back — measured at 243 to 708 seconds in
-production, so the CLI shows elapsed progress and says "several minutes" rather than promising
-a number. Nothing is lost while it sleeps: every workspace stays on the workstation's disk.
+This section does not apply to a self-hosted server. On the hosted service (coming soon) each
+user gets a whole machine of their own, which sleeps when idle. The first command after it
+sleeps waits for it to come back — measured at 243 to 708 seconds in production, so the CLI
+shows elapsed progress and says "several minutes" rather than promising a number. Nothing is lost while it sleeps: every workspace stays on the workstation's disk.
 
 The hosted service also reports the account's plan, active hours and spend cap, which `pipod
 list` prints under the pods. A self-hosted server reports none of that, and the client then

package/dist/cli.js

@@ -256,6 +256,7 @@ async function discover(issuer) {
     authorization_endpoint: body.authorization_endpoint,
     token_endpoint: body.token_endpoint,
     jwks_uri: body.jwks_uri,
+    device_authorization_endpoint: body.device_authorization_endpoint,
     end_session_endpoint: body.end_session_endpoint,
     revocation_endpoint: body.revocation_endpoint
   })) {
@@ -270,6 +271,7 @@ async function discover(issuer) {
     authorization_endpoint: body.authorization_endpoint,
     token_endpoint: body.token_endpoint,
     jwks_uri: body.jwks_uri,
+    ...body.device_authorization_endpoint ? { device_authorization_endpoint: body.device_authorization_endpoint } : {},
     ...body.end_session_endpoint ? { end_session_endpoint: body.end_session_endpoint } : {},
     ...body.revocation_endpoint ? { revocation_endpoint: body.revocation_endpoint } : {}
   };
@@ -293,15 +295,18 @@ function organizationScope(alias) {
   }
   return `urn:zitadel:iam:org:domain:primary:${alias}`;
 }
+function loginScopes(orgAlias) {
+  const scopes = ["openid", "profile", "email", OFFLINE_ACCESS_SCOPE, RESOURCE_OWNER_SCOPE, PROJECT_ROLES_SCOPE];
+  const orgScope = organizationScope(orgAlias);
+  if (orgScope) scopes.push(orgScope);
+  return scopes.join(" ");
+}
 function authorizeUrl(meta, args) {
   const url = new URL(meta.authorization_endpoint);
   url.searchParams.set("response_type", "code");
   url.searchParams.set("client_id", args.clientId);
   url.searchParams.set("redirect_uri", args.redirectUri);
-  const scopes = ["openid", "profile", "email", OFFLINE_ACCESS_SCOPE, RESOURCE_OWNER_SCOPE, PROJECT_ROLES_SCOPE];
-  const orgScope = organizationScope(args.orgAlias);
-  if (orgScope) scopes.push(orgScope);
-  url.searchParams.set("scope", scopes.join(" "));
+  url.searchParams.set("scope", loginScopes(args.orgAlias));
   url.searchParams.set("code_challenge", args.challenge);
   url.searchParams.set("code_challenge_method", "S256");
   url.searchParams.set("state", args.state);
@@ -345,11 +350,105 @@ async function exchangeCode(meta, args) {
       hint: String(e instanceof Error ? e.message : e)
     });
   });
-  const tokens = await readTokenResponse(res);
+  return verifiedLoginTokens(meta, await readTokenResponse(res), args.clientId, args.nonce);
+}
+async function verifiedLoginTokens(meta, tokens, clientId, nonce) {
   if (!tokens.idToken) throw new PiPodError("the identity provider returned no ID token");
-  await verifyIdToken(meta, tokens.idToken, args.clientId, tokens.accessToken, args.nonce);
+  await verifyIdToken(meta, tokens.idToken, clientId, tokens.accessToken, nonce);
   return tokens;
 }
+var DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+var DEVICE_POLL_SECONDS = 5;
+async function startDeviceAuthorization(meta, args) {
+  if (!meta.device_authorization_endpoint) return null;
+  const res = await fetch(meta.device_authorization_endpoint, {
+    method: "POST",
+    redirect: "error",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ client_id: args.clientId, scope: loginScopes(args.orgAlias) }),
+    signal: AbortSignal.timeout(OIDC_NETWORK_TIMEOUT_MS)
+  }).catch((e) => {
+    throw new PiPodError("cannot reach the identity provider device endpoint", {
+      hint: String(e instanceof Error ? e.message : e)
+    });
+  });
+  if (!res.ok) {
+    if (await oauthError(res) === "unauthorized_client") return null;
+    throw new PiPodError("the identity provider refused to start a device sign-in", {
+      hint: `HTTP ${res.status} \u2014 run \`pipod login\` again`
+    });
+  }
+  const body = await res.json().catch(() => null);
+  const deviceCode = body?.["device_code"];
+  const userCode = body?.["user_code"];
+  const verificationUri = body?.["verification_uri"];
+  const verificationUriComplete = body?.["verification_uri_complete"];
+  const expiresIn = body?.["expires_in"];
+  const interval = body?.["interval"];
+  if (typeof deviceCode !== "string" || typeof userCode !== "string" || typeof verificationUri !== "string" || typeof expiresIn !== "number") {
+    throw new PiPodError("the identity provider returned an invalid device sign-in");
+  }
+  parseSecureOidcUrl(verificationUri, "verification_uri");
+  if (typeof verificationUriComplete === "string") {
+    parseSecureOidcUrl(verificationUriComplete, "verification_uri_complete");
+  }
+  const authorization = {
+    userCode,
+    verificationUri,
+    ...typeof verificationUriComplete === "string" ? { verificationUriComplete } : {},
+    deviceCode,
+    intervalSeconds: typeof interval === "number" && interval > 0 ? interval : DEVICE_POLL_SECONDS,
+    expiresAt: Date.now() + expiresIn * 1e3
+  };
+  const probe = await pollDeviceToken(meta, args.clientId, deviceCode);
+  if ("error" in probe && probe.error === "unauthorized_client") return null;
+  if ("error" in probe && probe.error === "slow_down") authorization.intervalSeconds += DEVICE_POLL_SECONDS;
+  return authorization;
+}
+async function awaitDeviceTokens(meta, args) {
+  let intervalSeconds = args.authorization.intervalSeconds;
+  while (true) {
+    await new Promise((resolve14) => setTimeout(resolve14, intervalSeconds * 1e3));
+    if (Date.now() >= args.authorization.expiresAt) throw deviceCodeExpired();
+    const poll = await pollDeviceToken(meta, args.clientId, args.authorization.deviceCode);
+    if ("tokens" in poll) return verifiedLoginTokens(meta, poll.tokens, args.clientId);
+    switch (poll.error) {
+      case "authorization_pending":
+      case "unreachable":
+        continue;
+      case "slow_down":
+        intervalSeconds += DEVICE_POLL_SECONDS;
+        continue;
+      case "access_denied":
+        throw new PiPodError("the sign-in was declined", { hint: "run `pipod login` again" });
+      case "expired_token":
+        throw deviceCodeExpired();
+      default:
+        throw new PiPodError(`the identity provider refused the device sign-in (${poll.error})`, {
+          hint: "run `pipod login` again"
+        });
+    }
+  }
+}
+function deviceCodeExpired() {
+  return new PiPodError("the sign-in code expired before it was used", { hint: "run `pipod login` again" });
+}
+async function pollDeviceToken(meta, clientId, deviceCode) {
+  const res = await fetch(meta.token_endpoint, {
+    method: "POST",
+    redirect: "error",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ grant_type: DEVICE_CODE_GRANT, client_id: clientId, device_code: deviceCode }),
+    signal: AbortSignal.timeout(OIDC_NETWORK_TIMEOUT_MS)
+  }).catch(() => null);
+  if (!res) return { error: "unreachable" };
+  if (res.ok) return { tokens: await readTokenResponse(res) };
+  return { error: await oauthError(res) ?? `HTTP ${res.status}` };
+}
+async function oauthError(res) {
+  const body = await res.json().catch(() => null);
+  return typeof body?.error === "string" ? body.error : null;
+}
 async function verifyIdToken(meta, token, clientId, accessToken, expectedNonce) {
   let jwks = idTokenJwksCache.get(meta.jwks_uri);
   if (!jwks) {
@@ -7507,7 +7606,7 @@ function unattestedPackageNotice(podPackages, specs) {
   const remainder = mismatches.length - shown.length;
   const examples = `${shown.join(", ")}${remainder > 0 ? `, and ${remainder} more` : ""}`;
   const noun = mismatches.length === 1 ? "package" : "packages";
-  return `pod reports ${mismatches.length} configured ${noun} outside its exact launch-attested set: ${examples}; extension rendering from ${mismatches.length === 1 ? "that package is" : "those packages is"} unavailable locally \u2014 land intentional top-level Pi packages in your bundle's settings.json "packages" (pipod push, or a settings proposal); do not add transitive dependencies`;
+  return `pod reports ${mismatches.length} configured ${noun} outside its exact launch-attested set: ${examples}; extension rendering from ${mismatches.length === 1 ? "that package is" : "those packages is"} unavailable locally \u2014 land intentional top-level Pi packages in your bundle's settings.json "packages" (pipod push); do not add transitive dependencies`;
 }
 
 // src/client/runtime/pod-command-overrides.ts
@@ -17020,7 +17119,7 @@ async function runLogin(flags) {
   if (flags.token) {
     accessToken = flags.token;
   } else {
-    const pair = await browserLogin({ issuer, clientId, orgAlias: flags.org });
+    const pair = await interactiveLogin({ issuer, clientId, orgAlias: flags.org, device: flags.device === true });
     accessToken = pair.accessToken;
     refreshToken = pair.refreshToken;
     idToken = pair.idToken;
@@ -17162,8 +17261,36 @@ async function openConsole(flags, which) {
   openBrowser2(url);
   return 0;
 }
-async function browserLogin(args) {
+async function interactiveLogin(args) {
   const meta = await discover(args.issuer);
+  const browserHere = canOpenBrowserHere();
+  if (args.device || !browserHere) {
+    const authorization = await startDeviceAuthorization(meta, { clientId: args.clientId, orgAlias: args.orgAlias });
+    if (authorization) {
+      const page = authorization.verificationUriComplete ?? authorization.verificationUri;
+      const verb = authorization.verificationUriComplete ? "confirm" : "enter";
+      info(`to sign in, open this page on any device and ${verb} the code ${authorization.userCode}:
+  ${page}`);
+      info("waiting for you to finish signing in\u2026");
+      return awaitDeviceTokens(meta, { clientId: args.clientId, authorization });
+    }
+    if (args.device) {
+      throw new PiPodError(`${args.issuer} does not allow this CLI to sign in with a code`, {
+        hint: "on a self-hosted server the operator enables it with `selfhost/upgrade --apply-zitadel`; until then run `pipod login` without --device"
+      });
+    }
+    info("this identity provider does not offer sign-in with a code; using the browser flow");
+  }
+  return browserLogin(meta, { clientId: args.clientId, orgAlias: args.orgAlias, browserHere });
+}
+function canOpenBrowserHere() {
+  const env = process.env;
+  if (process.platform === "darwin" || process.platform === "win32") {
+    return !env["SSH_CONNECTION"] && !env["SSH_TTY"];
+  }
+  return Boolean(env["DISPLAY"] || env["WAYLAND_DISPLAY"] || env["BROWSER"]);
+}
+async function browserLogin(meta, args) {
   const pkce = createPkce();
   const state = createState();
   const nonce = createNonce();
@@ -17178,10 +17305,16 @@ async function browserLogin(args) {
       nonce,
       orgAlias: args.orgAlias
     });
-    info("opening your browser to sign in\u2026");
-    info(`if nothing opens, visit:
+    if (args.browserHere) {
+      info("opening your browser to sign in\u2026");
+      info(`if nothing opens, visit:
   ${url}`);
-    openBrowser2(url);
+      openBrowser2(url);
+    } else {
+      info(`to sign in, open this page in a browser that reaches port ${port} on this machine:
+  ${url}`);
+      hint(`over SSH, forward it first: ssh -L ${port}:127.0.0.1:${port} <this host>`);
+    }
     const code = await waitForCallback(server, state);
     return exchangeCode(meta, {
       clientId: args.clientId,
@@ -18400,6 +18533,11 @@ async function showCmd(client, args) {
     info("bake script:");
     out(t.bakeScript);
   }
+  if (t.agentInstructions) {
+    out("");
+    info("agent instructions:");
+    out(t.agentInstructions);
+  }
   if (t.piSettings && Object.keys(t.piSettings).length > 0) {
     info(`Pi settings ${describePiSettings(flatPiSettings(t.piSettings))}`);
   }
@@ -18478,6 +18616,12 @@ function parseOpts(args) {
         opts.bakeScript = fs30.readFileSync(file, "utf8");
         break;
       }
+      case "--agent-instructions": {
+        const file = next();
+        if (!fs30.existsSync(file)) throw new PiPodError(`no such agent instructions file: ${file}`);
+        opts.agentInstructions = fs30.readFileSync(file, "utf8");
+        break;
+      }
       default:
         rest.push(arg);
     }
@@ -18531,6 +18675,7 @@ async function createCmd(client, args, flags) {
     ...opts.description ? { description: opts.description } : {},
     ...initScript ? { initScript } : {},
     ...bakeScript ? { bakeScript } : {},
+    ...opts.agentInstructions ? { agentInstructions: opts.agentInstructions } : {},
     // An explicit refresh is replacement, not merge: an empty project file set clears stale custody.
     ...opts.fromHere ? { piSettings: piSettings ?? {} } : {}
   });
@@ -18637,9 +18782,9 @@ async function editCmd(client, args) {
     });
   }
   const t = await findTemplate(client, rest[0]);
-  if (opts.name === void 0 && opts.description === void 0 && !opts.config && opts.initScript === void 0 && opts.bakeScript === void 0) {
+  if (opts.name === void 0 && opts.description === void 0 && !opts.config && opts.initScript === void 0 && opts.bakeScript === void 0 && opts.agentInstructions === void 0) {
     throw new PiPodError("nothing to change", {
-      hint: "pass --name, --description, --config <file>, --init-script <file> or --bake-script <file>"
+      hint: "pass --name, --description, --config <file>, --init-script <file>, --bake-script <file> or --agent-instructions <file>"
     });
   }
   const updated = await client.updateTemplate(t.id, {
@@ -18650,7 +18795,8 @@ async function editCmd(client, args) {
     ...opts.description !== void 0 ? { description: opts.description } : {},
     ...opts.config ? { config: opts.config } : {},
     ...opts.initScript !== void 0 ? { initScript: opts.initScript } : {},
-    ...opts.bakeScript !== void 0 ? { bakeScript: opts.bakeScript } : {}
+    ...opts.bakeScript !== void 0 ? { bakeScript: opts.bakeScript } : {},
+    ...opts.agentInstructions !== void 0 ? { agentInstructions: opts.agentInstructions } : {}
   });
   info(`updated template ${updated.name}`);
   await hintMissingCredentials(client);
@@ -19429,10 +19575,12 @@ reused pods, \`--on\` co-location and \`--no-seed\` never seed.
 Run \`pipod <command> --help\` for command-specific usage.
 `;
 var SUBCOMMAND_HELP = {
-  login: `Usage: pipod login [--server <url>] [--issuer <url>] [--org <alias>] [--token <jwt>]
+  login: `Usage: pipod login [--server <url>] [--issuer <url>] [--org <alias>] [--device] [--token <jwt>]
 
 Sign this machine in to a pi pod server via Zitadel (authorization code + PKCE,
-in your browser). The session is stored in ~/.pi-pod/auth.json.
+in your browser). Where no browser can open here (over SSH, on a headless
+server), it prints a page and a code to confirm on any other device instead.
+The session is stored in ~/.pi-pod/auth.json.
 
 Options:
   --server <url>   Server to sign in to (default: the previous session's server,
@@ -19442,6 +19590,8 @@ Options:
                    publish its own
   --org <alias>    Only sign in to the organization with this primary domain;
                    omit it to sign in to your own organization
+  --device         Sign in with a code on another device even if a browser
+                   could open here
   --token <jwt>    Use an existing access token instead of the browser flow (dev/CI)
 `,
   account: `Usage: pipod account
@@ -19689,15 +19839,23 @@ are never stored on the server.
   templates: `Usage: pipod templates [action]
 
 Manage pod templates on the pi pod server. A template stores config, init and
-bake scripts, Pi settings files, and named secrets. Templates are personal by
-default: only their owner sees and launches them. --org at creation or
-\`templates share\` makes one org-wide.
+bake scripts, Pi settings files, named secrets, and agent instructions.
+Templates are personal by default: only their owner sees and launches them.
+--org at creation or \`templates share\` makes one org-wide.
+
+Agent instructions are added to the agent's system prompt in every pod launched
+from the template, with the hosts and secrets the pod actually has: say what
+access the template is meant to have. They guide the agent and enforce nothing;
+the template's secrets and egress decide what a pod can reach. A pod's child
+pods and the jobs it schedules launch from the pod's own template.
 
 Actions:
   list             List templates with scope and key counts (default)
-  show <name|id>   Show config, scripts, Pi settings, and secret names
+  show <name|id>   Show config, scripts, agent instructions, Pi settings, and
+                   secret names
   create <name>    Create a template
-  edit <name|id>   Update a template's name, description, config, or scripts
+  edit <name|id>   Update a template's name, description, config, scripts, or
+                   agent instructions
   share <name|id>  Make a personal template org-wide (cannot be undone)
   rm <name|id>     Delete a template (alias: delete)
 
@@ -19709,6 +19867,9 @@ create/edit options:
                         scripts, and sanitized Pi files (contradicts --config)
   --init-script <file>  Store this init script
   --bake-script <file>  Store this bake script
+  --agent-instructions <file>
+                        Store this file as the agent instructions (an empty
+                        file removes them); \`pipod push\` leaves them alone
   --org                 create only: make the template org-wide from the start
   --with-secrets        With --from-here: also upload project env values as
                         template secrets
@@ -19815,7 +19976,8 @@ var FLAG_SCOPE = {
   "--server": /* @__PURE__ */ new Set(["login"]),
   "--org": /* @__PURE__ */ new Set(["login", "jobs"]),
   "--token": /* @__PURE__ */ new Set(["login"]),
-  "--issuer": /* @__PURE__ */ new Set(["login"])
+  "--issuer": /* @__PURE__ */ new Set(["login"]),
+  "--device": /* @__PURE__ */ new Set(["login"])
 };
 function resolveSubcommand(positional) {
   if (positional === void 0) return null;
@@ -19959,6 +20121,9 @@ function parseArgs(argv) {
       case "--issuer":
         flags.issuer = takeValue();
         break;
+      case "--device":
+        flags.device = true;
+        break;
       default:
         throw new PiPodError(`unknown pi pod option "${name}"`, {
           hint: "pass Pi options after `--`, for example: pipod -- --model claude-opus",
@@ -20025,7 +20190,7 @@ async function main(argv) {
     case "init":
       return runInit(flags);
     case "login":
-      return runLogin({ server: flags.server, org: flags.org, token: flags.token, issuer: flags.issuer });
+      return runLogin({ server: flags.server, org: flags.org, token: flags.token, issuer: flags.issuer, device: flags.device });
     case "whoami":
       return runWhoami({});
     case "logout":