turnzero 0.23.0-next.1 → 0.24.0-next.1

package/README.md

@@ -25,6 +25,7 @@ Install it once with `npm install -g turnzero`, then run `turnzero login` once i
 - `login` logs this computer in through your browser, `whoami` names the account its token acts as, and `logout` revokes its token.
 - `authorize` gives this computer a token through your signed-in tool, which then tells you it did.
 - `token request` and `token claim` get a token for another computer or for an unattended run.
+- `session` signs a test end user of your application in and writes the session's cookie into a file that curl reads.
 
 Every subcommand's options, statuses, and output are on the reference page: https://turnzero.ai/cloud/reference/turnzero-command/
 

package/dist/turnzero-cloud.mjs

@@ -258,6 +258,15 @@ var AUTHORIZED_COMPUTER_MEMBER = "authorized_computer";
 var AUTHORIZE_SUBCOMMAND = "authorize";
 var LOGOUT_SUBCOMMAND = "logout";
 var WHOAMI_SUBCOMMAND = "whoami";
+var SESSION_SUBCOMMAND = "session";
+var SESSION_OPTION = {
+  application: "--application",
+  environment: "--environment",
+  endUser: "--end-user",
+  out: "--out",
+  origin: "--origin",
+  force: "--force"
+};
 var TOKEN_SUBCOMMAND = "token";
 var TOKEN_REQUEST_ACT = "request";
 var TOKEN_CLAIM_ACT = "claim";
@@ -767,9 +776,9 @@ var readMovingCredentialFile = (io2, place, say) => {
 // src/turnzero_cloud_command/grant.ts
 var GRANT_READ_BOUND_MS = 1e4;
 var GRANT_INPUT_BYTES_MAX = 4096;
-var readStandardInputEnded = (input, boundMs = GRANT_READ_BOUND_MS) => new Promise((resolve12) => {
+var readStandardInputEnded = (input, boundMs = GRANT_READ_BOUND_MS) => new Promise((resolve13) => {
   if (input.isTTY) {
-    resolve12({ text: "", bytes: 0, ending: "terminal" });
+    resolve13({ text: "", bytes: 0, ending: "terminal" });
     return;
   }
   const chunks = [];
@@ -791,7 +800,7 @@ var readStandardInputEnded = (input, boundMs = GRANT_READ_BOUND_MS) => new Promi
     input.removeListener("close", onEnd);
     input.pause();
     input.destroy?.();
-    resolve12({ text: Buffer.concat(chunks).toString("utf8"), bytes, ending });
+    resolve13({ text: Buffer.concat(chunks).toString("utf8"), bytes, ending });
   };
   const onEnd = () => finish("end");
   const onError = () => finish("error");
@@ -3233,7 +3242,7 @@ var headCommitOf = (folder, reads = FILE_SYSTEM_READS) => {
 
 // src/turnzero_cloud_command/options.ts
 var afterOwnErrorOf = (row, call, io2) => typeof row.afterOwnError === "function" ? row.afterOwnError(call, io2) : row.afterOwnError;
-var PATH_OPTION_NAMES = Object.freeze([DEPLOY_OPTION.path, SECRET_OPTION.valueFile, PROVISION_OPTION.envFile]);
+var PATH_OPTION_NAMES = Object.freeze([DEPLOY_OPTION.path, SECRET_OPTION.valueFile, PROVISION_OPTION.envFile, SESSION_OPTION.out]);
 var DEPLOY_OPTIONS = Object.freeze([
   {
     name: DEPLOY_OPTION.application,
@@ -4303,7 +4312,7 @@ var noTerminalSentence = (option, call) => `${option} reads the value from a ter
 var readPromptedValue = (io2, option, fileOption, call) => {
   const terminal = io2.terminal();
   if (terminal === null) return Promise.resolve({ refusal: noTerminalSentence(option, call) });
-  return new Promise((resolve12) => {
+  return new Promise((resolve13) => {
     let typed = "";
     let done = false;
     let cancel = () => void 0;
@@ -4313,7 +4322,7 @@ var readPromptedValue = (io2, option, fileOption, call) => {
       cancel();
       terminal.write("\n");
       terminal.close();
-      resolve12(read2);
+      resolve13(read2);
     };
     cancel = io2.schedule(
       PROMPT_BOUND_SECONDS * 1e3,
@@ -5650,8 +5659,8 @@ var openerRunOf = (io2, address) => {
 };
 var openBrowser = async (io2, address) => {
   let cancel = () => void 0;
-  const waited = new Promise((resolve12) => {
-    cancel = io2.schedule(OPENER_WAIT_MS, () => resolve12("waiting"));
+  const waited = new Promise((resolve13) => {
+    cancel = io2.schedule(OPENER_WAIT_MS, () => resolve13("waiting"));
   });
   const ended = await Promise.race([io2.child(openerRunOf(io2, address)), waited]);
   cancel();
@@ -5731,13 +5740,13 @@ async function login(call, io2) {
   const endMs = Math.max(1e3, Date.parse(pending.expires_at) - io2.clock().getTime());
   const minutes = minutesLeftOf(pending.expires_at, io2.clock());
   let settle = () => void 0;
-  const arrived = new Promise((resolve12) => {
-    settle = resolve12;
+  const arrived = new Promise((resolve13) => {
+    settle = resolve13;
   });
   let taken = false;
   let outcome = () => void 0;
-  const outcomeKnown = new Promise((resolve12) => {
-    outcome = resolve12;
+  const outcomeKnown = new Promise((resolve13) => {
+    outcome = resolve13;
   });
   const take = (arrival2) => {
     if (taken) return false;
@@ -8973,6 +8982,326 @@ var SCAFFOLD_ROW = Object.freeze({
   run: scaffold
 });
 
+// src/turnzero_cloud_command/session.ts
+import { dirname as dirname7, isAbsolute as isAbsolute6, join as join11, relative as relative7, resolve as resolve12, sep as sep4 } from "node:path";
+var SIGN_IN_TEST_END_USER_ACTION = "sign_in_test_end_user";
+var SESSION_DELIVERY = "command";
+var NOTHING_SENT_OR_WRITTEN = "Nothing was sent and nothing was written.";
+var SESSION_ACT = "sign-in";
+var SESSION_CALL_BOUND_SECONDS = 60;
+var REDACTED_SESSION_COOKIE = "<session cookie>";
+var COOKIE_JAR_HEADER = "# Netscape HTTP Cookie File";
+var HTTP_ONLY_PREFIX = "#HttpOnly_";
+var SUGGESTED_JAR_NAME = "turnzero-session-cookies.txt";
+var SESSION_LINE_HEAD = "session: ";
+var SESSION_UNKNOWN_AGAIN = "Whether the end user was signed in is unknown, and nothing was written: run the line again.";
+var SESSION_RATE_CAPPED = "Nothing was written. Run the line again after the wait the answer names.";
+var SESSION_SIGNAL_ENDED = "The run was ended before the cookie jar was written, so nothing was written: run the line again.";
+var SESSION_AFTER_LOGIN = `Once login has printed authorized:, run this session line again. ${NOTHING_SENT_OR_WRITTEN}`;
+var SESSION_OPTIONS = Object.freeze([
+  {
+    name: SESSION_OPTION.application,
+    value: "<application id>",
+    required: true,
+    description: `The application whose test end user signs in, by its id, as the line a ${SIGN_IN_TEST_END_USER_ACTION} call from your tool names it.`
+  },
+  {
+    name: SESSION_OPTION.environment,
+    value: "<environment>",
+    required: true,
+    description: `The environment the end user signs in to, ${COMMAND_ENVIRONMENTS.join(" or ")}.`
+  },
+  {
+    name: SESSION_OPTION.endUser,
+    value: "<end user id or label>",
+    required: true,
+    description: "The test end user, by the id or the label create_test_end_users answered."
+  },
+  {
+    name: SESSION_OPTION.out,
+    value: "<path>",
+    required: true,
+    description: `The cookie jar file the session's cookie is written into, which curl -b reads. Its folder must stand. A file that stands there is refused unless the line names ${SESSION_OPTION.force}, and a path inside the folder the command runs in is refused where that folder holds package.json, since a deploy from it would upload the jar.`
+  },
+  {
+    name: SESSION_OPTION.origin,
+    value: "<origin>",
+    required: false,
+    description: `The platform's address. Where absent, the address ${ORIGIN_VARIABLE} holds, or ${DEFAULT_COMMAND_ORIGIN} where it is unset. Under ${MINTED_TOKEN_VARIABLE} the token is sent only to the address ${ORIGIN_VARIABLE} holds, or to ${DEFAULT_COMMAND_ORIGIN} where it is unset. Otherwise it names the address whose token the command reads from this computer's credential file, and that token is sent to that address alone.`
+  },
+  {
+    name: SESSION_OPTION.force,
+    value: "",
+    required: false,
+    flag: true,
+    description: `Replaces the file ${SESSION_OPTION.out} names where one stands.`
+  }
+]);
+var SESSION_CREDENTIAL = Object.freeze({
+  grant: "minted token",
+  aGrant: "a minted token",
+  call: `the ${SIGN_IN_TEST_END_USER_ACTION} call`,
+  mintedToken: true,
+  piped: false,
+  places: `the command reads no standard input: it reads a minted token from ${MINTED_TOKEN_VARIABLE} where it is set, as a tool connected by a minted token sets it from where its token is kept, or a job with no tool from its secret store, and otherwise this computer's token for the platform's address from its credential file, which ${LOGIN_SUBCOMMAND} and ${AUTHORIZE_SUBCOMMAND} write.`
+});
+var SESSION_READS = `no standard input: a minted token from ${MINTED_TOKEN_VARIABLE} where it is set, and otherwise this computer's token for the platform's address from its credential file, which ${LOGIN_SUBCOMMAND} and ${AUTHORIZE_SUBCOMMAND} write, sent only to that address; with neither, it prints the variable route first and then, where the address is admitted, the login route`;
+var missingOptionSentence = (option) => `${SESSION_SUBCOMMAND} needs ${option.name} ${option.value}, as the line a ${SIGN_IN_TEST_END_USER_ACTION} call answers names it. ${NOTHING_SENT_OR_WRITTEN}`;
+var ENVIRONMENT_REFUSAL = `${SESSION_OPTION.environment} names the environment the end user signs in to, ${COMMAND_ENVIRONMENTS.join(" or ")}. ${NOTHING_SENT_OR_WRITTEN}`;
+var OUT_STANDS_REFUSAL = `A file stands where ${SESSION_OPTION.out} names the cookie jar, and ${SESSION_SUBCOMMAND} replaces one only where the line names ${SESSION_OPTION.force}. Name a new file, or add ${SESSION_OPTION.force} to replace it. ${NOTHING_SENT_OR_WRITTEN}`;
+var OUT_FOLDER_REFUSAL = `${SESSION_OPTION.out} names a folder: name a file for the cookie jar, in that folder or another. ${NOTHING_SENT_OR_WRITTEN}`;
+var OUT_PARENT_REFUSAL = `The folder ${SESSION_OPTION.out} names the cookie jar in does not stand: make it, or name a file in a folder that stands. ${NOTHING_SENT_OR_WRITTEN}`;
+var outInsideApplicationRefusal = (outside2) => `${SESSION_OPTION.out} names a file inside the folder the command runs in, which holds package.json, so a ${DEPLOY_SUBCOMMAND} from that folder would upload the session's cookie with the application. Name a file outside that folder${outside2 !== null ? `, such as ${outside2}` : ""}. ${NOTHING_SENT_OR_WRITTEN}`;
+var jarUntriedRefusal = (code) => `The cookie jar could not be written (${code}): the folder ${SESSION_OPTION.out} names a file in must admit a write. ${NOTHING_SENT_OR_WRITTEN}`;
+var jarUnwrittenSentence = (code) => `The end user was signed in, and the cookie jar could not be written (${code}), so the session's cookie was not kept: run the line again.`;
+var SESSION_NO_ANSWER = "The sign-in call drew no answer.";
+var sessionRedirected = (status) => {
+  const how = answeredHow(status);
+  return `The sign-in call was answered ${status >= 100 ? `${how}, a redirect` : how}, which the command never follows, so the credential was sent to no second address.`;
+};
+var sessionAnswerUnusable = (status) => `The sign-in call was answered HTTP ${status} with no answer the command can use: status signed_in, hostname, end_user, expires_at, and cookie, each in its form. Nothing of the answer was printed or written.`;
+var insideFolder = (folder, path) => {
+  const between = relative7(folder, path);
+  return between === "" || between !== ".." && !between.startsWith(`..${sep4}`) && !isAbsolute6(between);
+};
+var sessionOptionsOf = (call, cwd) => {
+  for (const option of SESSION_OPTIONS) {
+    if (option.required && (call.named[option.name] ?? "").trim() === "") return { refusal: missingOptionSentence(option) };
+  }
+  const environment = call.named[SESSION_OPTION.environment];
+  if (!COMMAND_ENVIRONMENTS.includes(environment)) return { refusal: ENVIRONMENT_REFUSAL };
+  const origin = commandOriginOf(call.named[SESSION_OPTION.origin] ?? DEFAULT_COMMAND_ORIGIN);
+  if ("refusal" in origin) return origin;
+  const outGiven = call.named[SESSION_OPTION.out];
+  return {
+    application: call.named[SESSION_OPTION.application],
+    environment,
+    endUser: call.named[SESSION_OPTION.endUser],
+    outGiven,
+    out: resolve12(cwd, outGiven),
+    force: call.flags.has(SESSION_OPTION.force),
+    origin: origin.origin
+  };
+};
+var outRefusalOf = (io2, options) => {
+  const standing = io2.stat(options.out);
+  if (standing !== null && standing.folder) return OUT_FOLDER_REFUSAL;
+  if (standing !== null && !options.force) return OUT_STANDS_REFUSAL;
+  const cwd = resolve12(io2.cwd);
+  const manifest = io2.stat(join11(cwd, "package.json"));
+  if (manifest !== null && !manifest.folder && insideFolder(cwd, options.out)) {
+    const above = dirname7(cwd);
+    return outInsideApplicationRefusal(above !== cwd ? join11(above, SUGGESTED_JAR_NAME) : null);
+  }
+  const folder = io2.stat(dirname7(options.out));
+  if (folder === null || !folder.folder) return OUT_PARENT_REFUSAL;
+  return null;
+};
+var HOSTNAME_FORM = /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?$/;
+var COOKIE_NAME_FORM = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+var COOKIE_VALUE_FORM = /^[\x21\x23-\x2b\x2d-\x3a\x3c-\x5b\x5d-\x7e]+$/;
+var COOKIE_PATH_FORM = /^\/[\x21-\x3a\x3c-\x7e]*$/;
+var UTC_INSTANT_FORM = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
+var shownText = (value) => typeof value === "string" && value !== "" && value.length <= 256 && oneLine(value) === value;
+var sessionAnswerOf = (answer) => {
+  const { status, hostname: hostname3, end_user: endUser, expires_at: expiresAt, cookie } = answer;
+  if (status !== "signed_in") return null;
+  if (typeof hostname3 !== "string" || !HOSTNAME_FORM.test(hostname3)) return null;
+  if (endUser === null || typeof endUser !== "object" || Array.isArray(endUser)) return null;
+  const { id, label } = endUser;
+  if (!shownText(id) || label !== null && label !== void 0 && !shownText(label)) return null;
+  if (typeof expiresAt !== "string" || !UTC_INSTANT_FORM.test(expiresAt) || !Number.isFinite(Date.parse(expiresAt))) return null;
+  if (cookie === null || typeof cookie !== "object" || Array.isArray(cookie)) return null;
+  const { name, value, path, secure, http_only: httpOnly } = cookie;
+  if (typeof name !== "string" || !COOKIE_NAME_FORM.test(name)) return null;
+  if (typeof value !== "string" || !COOKIE_VALUE_FORM.test(value)) return null;
+  if (typeof path !== "string" || !COOKIE_PATH_FORM.test(path)) return null;
+  if (typeof secure !== "boolean" || typeof httpOnly !== "boolean") return null;
+  return { hostname: hostname3, endUser: { id, label: typeof label === "string" ? label : null }, expiresAt, cookie: { name, value, path, secure, httpOnly } };
+};
+var cookieJarTextOf = (session2) => `${COOKIE_JAR_HEADER}
+${[
+  `${session2.cookie.httpOnly ? HTTP_ONLY_PREFIX : ""}${session2.hostname}`,
+  "FALSE",
+  session2.cookie.path,
+  session2.cookie.secure ? "TRUE" : "FALSE",
+  String(Math.floor(Date.parse(session2.expiresAt) / 1e3)),
+  session2.cookie.name,
+  session2.cookie.value
+].join("	")}
+`;
+var sessionLineOf = (session2, outGiven) => `${SESSION_LINE_HEAD}${session2.hostname} for ${oneLine(session2.endUser.label ?? session2.endUser.id)} until ${session2.expiresAt}; cookie ${session2.cookie.name} written to ${outGiven} (curl -b ${outGiven})`;
+var hideCookieOf = (io2, answer) => {
+  const cookie = answer?.cookie;
+  if (cookie === null || typeof cookie !== "object" || Array.isArray(cookie)) return;
+  const value = cookie.value;
+  if (typeof value === "string" && value !== "") io2.hide(value, REDACTED_SESSION_COOKIE);
+};
+var postSignIn = async (io2, origin, bearer, userAgent, body) => {
+  const controller = new AbortController();
+  const cancel = io2.schedule(SESSION_CALL_BOUND_SECONDS * 1e3, () => controller.abort());
+  try {
+    const response = await io2.fetch(`${origin}${actionPathOf(SIGN_IN_TEST_END_USER_ACTION)}`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${bearer}`, "user-agent": userAgent, "content-type": "application/json" },
+      body: JSON.stringify(body),
+      redirect: "manual",
+      signal: controller.signal
+    });
+    return { status: response.status, redirected: redirected(response), text: await response.text() };
+  } catch {
+    return null;
+  } finally {
+    cancel();
+  }
+};
+async function callSignIn(io2, options, origin, bearer, userAgent, refused) {
+  const unknown = { status: COMMAND_STATUS.unknown };
+  const answered = await postSignIn(io2, origin, bearer, userAgent, {
+    application: options.application,
+    environment: options.environment,
+    end_user: options.endUser,
+    delivery: SESSION_DELIVERY
+  });
+  if (answered === null) {
+    io2.print(SESSION_NO_ANSWER);
+    io2.print(SESSION_UNKNOWN_AGAIN);
+    return unknown;
+  }
+  const parsed = planeObjectOf(answered.text);
+  hideCookieOf(io2, parsed);
+  if (answered.redirected) {
+    io2.print(sessionRedirected(answered.status));
+    io2.print(SESSION_UNKNOWN_AGAIN);
+    return unknown;
+  }
+  if (answered.status >= PLATFORM_FAILURE_STATUS) {
+    for (const line of failureLines(SESSION_ACT, answered.status, planeRefusalOf(answered.text))) io2.print(line);
+    io2.print(SESSION_UNKNOWN_AGAIN);
+    return unknown;
+  }
+  if (answered.status < 200 || answered.status > 299) {
+    const refusal = markedRefusalOf(answered.status, answered.text);
+    if (refusal === null) {
+      io2.print(notThePlatformLine("sign-in call", answered.status));
+      io2.print(SESSION_UNKNOWN_AGAIN);
+      return unknown;
+    }
+    for (const line of refusalLines(SESSION_ACT, answered.status, refusal)) io2.print(line);
+    if (answered.status === 429 && refusal.error === RATE_CAPPED) {
+      io2.print(SESSION_RATE_CAPPED);
+    } else {
+      const sentence = refused();
+      if (sentence !== null) io2.print(sentence);
+    }
+    return { status: COMMAND_STATUS.failed };
+  }
+  const usable = parsed === null ? null : sessionAnswerOf(parsed);
+  if (usable === null) {
+    io2.print(sessionAnswerUnusable(answered.status));
+    io2.print(SESSION_UNKNOWN_AGAIN);
+    return unknown;
+  }
+  return usable;
+}
+async function session(call, io2) {
+  const options = sessionOptionsOf(call, io2.cwd);
+  if ("refusal" in options) {
+    io2.print(options.refusal);
+    return COMMAND_STATUS.nothing_started;
+  }
+  const agent = userAgentOf(io2.env);
+  if ("refusal" in agent) {
+    io2.print(agent.refusal);
+    return COMMAND_STATUS.nothing_started;
+  }
+  const out = outRefusalOf(io2, options);
+  if (out !== null) {
+    io2.print(out);
+    return COMMAND_STATUS.nothing_started;
+  }
+  const named = call.named[SESSION_OPTION.origin];
+  const credential = await readCredential(io2, SESSION_CREDENTIAL, "", { named, closing: NOTHING_SENT_OR_WRITTEN });
+  if ("unauthorized" in credential) {
+    io2.print(noTokenSentence(credential.unauthorized.origin, credential.unauthorized.expiredAt));
+    io2.print(VARIABLE_ROUTE_SENTENCES);
+    const reached = authorizationOriginOf(io2.env, named, NOTHING_SENT_OR_WRITTEN);
+    if ("refusal" in reached) {
+      io2.print(reached.refusal);
+      return COMMAND_STATUS.nothing_started;
+    }
+    const unwritable = loginRouteRefusalOf(io2, NOTHING_SENT_OR_WRITTEN);
+    if (unwritable !== null) {
+      io2.print(unwritable);
+      return COMMAND_STATUS.nothing_started;
+    }
+    for (const line of loginRouteLines(io2, reached.origin, false)) io2.print(line);
+    io2.print(SESSION_AFTER_LOGIN);
+    return COMMAND_STATUS.nothing_started;
+  }
+  if ("refusal" in credential) {
+    io2.print(credential.refusal);
+    return COMMAND_STATUS.nothing_started;
+  }
+  io2.hide(credential.credential, REDACTED_TOKEN);
+  const sent = credentialOriginOf(io2.env, credential, { named, closing: NOTHING_SENT_OR_WRITTEN });
+  if ("refusal" in sent) {
+    io2.print(sent.refusal);
+    return COMMAND_STATUS.nothing_started;
+  }
+  const origin = sent.origin;
+  const refused = () => credential.source === "credential_file" ? fileReadSentence(origin) : variableReadSentence(origin, fileStandingOf(io2, origin, io2.print));
+  const tag = runTagOf();
+  const tried = tryWritingFile(io2, options.out, "owner only", tag);
+  if ("unwritten" in tried) {
+    dropWritingFile(io2, options.out, tag);
+    io2.print(jarUntriedRefusal(tried.unwritten));
+    return COMMAND_STATUS.nothing_started;
+  }
+  const release = io2.whenEnded(() => {
+    io2.print(SESSION_SIGNAL_ENDED);
+    dropWritingFile(io2, options.out, tag);
+  });
+  try {
+    const older = await planeWireRefusal(io2, origin);
+    if (older !== null) {
+      io2.print(older);
+      return COMMAND_STATUS.nothing_started;
+    }
+    const answer = await callSignIn(io2, options, origin, credential.credential, agent.userAgent, refused);
+    if ("status" in answer) return answer.status;
+    const written = writeThenRename(io2, options.out, cookieJarTextOf(answer), "owner only", tag);
+    if ("unwritten" in written) {
+      io2.print(jarUnwrittenSentence(written.unwritten));
+      return COMMAND_STATUS.failed;
+    }
+    io2.print(sessionLineOf(answer, options.outGiven));
+    return COMMAND_STATUS.done;
+  } finally {
+    dropWritingFile(io2, options.out, tag);
+    release();
+  }
+}
+var SESSION_ROW = Object.freeze({
+  name: SESSION_SUBCOMMAND,
+  summary: `Signs a test end user in and writes the session's cookie into a file curl -b reads, through one ${SIGN_IN_TEST_END_USER_ACTION} call under the credential ${DEPLOY_SUBCOMMAND} reads. It prints one line naming the hostname, the end user, the expiry, and the file, never the cookie's value. With no credential, it sends nothing and prints the two routes to one.`,
+  options: SESSION_OPTIONS,
+  credential: SESSION_CREDENTIAL,
+  reads: SESSION_READS,
+  statuses: {
+    done: `the end user was signed in and the session's cookie written to the file ${SESSION_OPTION.out} names`,
+    failed: "the platform refused the sign-in, the printed lines naming the platform's error and detail, or the end user was signed in and the cookie jar could not be written, so the session's cookie was not kept",
+    unknown: "the sign-in call drew no answer, was redirected, failed, or drew an answer that is neither a refusal nor a session, and nothing was written",
+    nothing_started: `nothing was sent, or nothing was written: an option, the file ${SESSION_OPTION.out} names, or the credential was refused, no credential was read and the two routes to one were printed, the platform was too old, or the jar's folder admitted no write`
+  },
+  note: [
+    `A session line is the one your tool's ${SIGN_IN_TEST_END_USER_ACTION} call answers where the platform serves that action, and it carries no credential. Run it once: it signs the test end user in and writes the session's cookie into the file ${SESSION_OPTION.out} names, in the cookie file form curl -b reads, so the session's value never passes through your tool. Requests then carry the cookie with curl -b and that path.`,
+    `${SESSION_SUBCOMMAND} writes the cookie jar under another name beside it, owner-only, and renames it into place, and it removes that file where the run ends before the rename. It writes over a file that stands only where the line names ${SESSION_OPTION.force}. It refuses a path inside the folder the command runs in where that folder holds package.json, since a deploy from it would upload the jar.`
+  ],
+  afterOwnError: `whether the end user was signed in is unknown, and a file ${SESSION_OPTION.out} names may now stand, so run the line again, adding ${SESSION_OPTION.force} where it does`,
+  run: session
+});
+
 // src/turnzero_cloud_command/token.ts
 var TOKEN_OPTIONS = Object.freeze([
   {
@@ -9050,9 +9379,9 @@ import { chmodSync, closeSync, openSync, readFileSync as readFileSync5, realpath
 import { mkdirSync, readdirSync as readdirSync2, renameSync, rmSync, statSync as statSync4, write as writeAt } from "node:fs";
 import { createServer } from "node:http";
 import { constants as constants2 } from "node:os";
-import { sep as sep4 } from "node:path";
+import { sep as sep5 } from "node:path";
 import { ReadStream, isatty } from "node:tty";
-var listenLoopback = (answer) => new Promise((resolve12) => {
+var listenLoopback = (answer) => new Promise((resolve13) => {
   const server = createServer((request, response) => {
     const url = new URL(request.url ?? "/", "http://127.0.0.1");
     const query = {};
@@ -9069,16 +9398,16 @@ var listenLoopback = (answer) => new Promise((resolve12) => {
       }
     );
   });
-  server.once("error", () => resolve12(null));
+  server.once("error", () => resolve13(null));
   server.listen(0, "127.0.0.1", () => {
     const address = server.address();
     if (address === null || typeof address === "string") {
       server.close();
-      resolve12(null);
+      resolve13(null);
       return;
     }
     let closed = false;
-    resolve12({
+    resolve13({
       port: address.port,
       close: () => {
         if (closed) return;
@@ -9090,7 +9419,7 @@ var listenLoopback = (answer) => new Promise((resolve12) => {
     });
   });
 });
-var ranThroughNpxOf = (entry) => entry !== void 0 && entry.includes(`${sep4}_npx${sep4}`);
+var ranThroughNpxOf = (entry) => entry !== void 0 && entry.includes(`${sep5}_npx${sep5}`);
 var TERMINAL = process.platform === "win32" ? { input: "\\\\.\\CONIN$", output: "\\\\.\\CONOUT$", inputFlags: "r+" } : { input: "/dev/tty", output: "/dev/tty", inputFlags: "r" };
 var terminalFor = (outputIsTerminal, open) => outputIsTerminal ? open() : null;
 var openTerminal = () => {
@@ -9171,7 +9500,7 @@ var holdSignals = (signals, inputIsTerminal, passesOn, passOn, onInterrupt) => {
     for (const [signal, handler] of held) signals.off(signal, handler);
   };
 };
-var childRunnerOf = (signals, inputIsTerminal, passesOn = SIGNALS_PASS_ON, groups = CHILD_GROUPS) => (run) => new Promise((resolve12) => {
+var childRunnerOf = (signals, inputIsTerminal, passesOn = SIGNALS_PASS_ON, groups = CHILD_GROUPS) => (run) => new Promise((resolve13) => {
   const output = run.output;
   let interrupted = false;
   const group = run.foreground === true && passesOn && groups;
@@ -9188,8 +9517,8 @@ var childRunnerOf = (signals, inputIsTerminal, passesOn = SIGNALS_PASS_ON, group
       child.stdout?.setEncoding("utf8").on("data", (chunk) => output(chunk, "stdout"));
       child.stderr?.setEncoding("utf8").on("data", (chunk) => output(chunk, "stderr"));
     }
-    child.once("error", (error) => resolve12({ status: null, signal: null, error: startErrorOf(error) }));
-    child.once("close", (status, signal) => resolve12({ status, signal, error: null, ...interrupted ? { interrupted: true } : {} }));
+    child.once("error", (error) => resolve13({ status: null, signal: null, error: startErrorOf(error) }));
+    child.once("close", (status, signal) => resolve13({ status, signal, error: null, ...interrupted ? { interrupted: true } : {} }));
     if (run.foreground) {
       const release = holdSignals(
         signals,
@@ -9214,7 +9543,7 @@ var childRunnerOf = (signals, inputIsTerminal, passesOn = SIGNALS_PASS_ON, group
       child.once("close", release);
     }
   } catch (error) {
-    resolve12({ status: null, signal: null, error: startErrorOf(error) });
+    resolve13({ status: null, signal: null, error: startErrorOf(error) });
   }
 });
 var runChild = childRunnerOf(process, () => isatty(0));
@@ -9259,7 +9588,7 @@ var processIo = () => ({
   // hold a subcommand lets go after a pause has seen it (scaffold.ts;
   // PLD-L0-103). A bare timer of no length ends before the loop polls, and
   // the signal would be dropped with the hold.
-  sleep: (ms) => new Promise((resolve12) => setTimeout(() => setImmediate(resolve12), ms)),
+  sleep: (ms) => new Promise((resolve13) => setTimeout(() => setImmediate(resolve13), ms)),
   schedule: (ms, fire) => {
     const timer = setTimeout(fire, ms);
     return () => clearTimeout(timer);
@@ -9291,10 +9620,10 @@ var processIo = () => ({
 `);
   }
 });
-var writeWhole = (fd2, chunk) => new Promise((resolve12, reject) => {
+var writeWhole = (fd2, chunk) => new Promise((resolve13, reject) => {
   const from = (offset) => {
     if (offset >= chunk.length) {
-      resolve12();
+      resolve13();
       return;
     }
     writeAt(fd2, chunk, offset, chunk.length - offset, null, (error, written) => error ? reject(error) : from(offset + written));
@@ -9374,7 +9703,8 @@ var SUBCOMMANDS = Object.freeze([
   LOGOUT_ROW,
   TOKEN_ROW,
   LOGIN_ROW,
-  WHOAMI_ROW
+  WHOAMI_ROW,
+  SESSION_ROW
 ]);
 var SERVED = LINE_RUNNER;
 var NPX_FORM_SENTENCE = `Where the command is not installed, install it with ${installLineOf(DEFAULT_COMMAND_ORIGIN)}. A person or a job may instead run the same line through npx: write ${commandRunnerOf("latest")} for ${LINE_RUNNER}. A tool where the command is not installed uses deploy_files within its caps, or the deploy skill's setup steps, never the npx line.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turnzero",
-  "version": "0.23.0-next.1",
+  "version": "0.24.0-next.1",
   "type": "module",
   "description": "The Turn Zero Cloud command, which an AI coding tool runs on your machine to deploy an application, store a secret, upload a file, download an export, take a library entry, write a local run's settings, start the application locally, and scaffold a new service from a template.",
   "license": "Apache-2.0",