paperlint 10.4.0 → 11.0.0

package/src/submission.ts

@@ -17,11 +17,16 @@
  */
 import { basename, join, resolve } from "node:path";
 import { absolutePath } from "./domain/paths.ts";
+import { messageOf } from "./domain/text.ts";
 import { err, ok, type Result } from "./domain/result.ts";
 import { sha256Hex, type Sha256 } from "./domain/sha256.ts";
 import {
   supportedPortal,
+  withSubmissionId,
   wordCount,
+  type Author,
+  type CreateOutcome,
+  type NewSubmission,
   type PortalFailure,
   type PortalMessage,
   type SubmissionView,
@@ -29,7 +34,10 @@ import {
   type UpdateOutcome,
 } from "./domain/submission.ts";
 import type { Files } from "./ports/files.ts";
-import type { SubmissionPortal } from "./ports/submission-portal.ts";
+import type {
+  PortalSite,
+  SubmissionPortal,
+} from "./ports/submission-portal.ts";
 import {
   paperPreset,
   unusablePresetLine,
@@ -40,23 +48,70 @@ import type { PaperSettings } from "./paper-settings.ts";
 import { currentDeadlines } from "./domain/cycle.ts";
 import {
   deadlinesInForce,
+  readingText,
   type InForce,
-  type Observation,
 } from "./domain/deadline.ts";
 import { CONFIG_FILE } from "#lib/paper-config";
+import {
+  hostOf,
+  lookUpToken,
+  type TokenProblem,
+} from "./domain/portal-token.ts";
+import { LINE_BREAK, OPAQUE, runText } from "./domain/tex-document.ts";
+import type { LatexReader } from "./ports/latex.ts";
+import { factsPath, parseFactsText } from "./facts-file.ts";
+import { lineColumn, readPaper } from "./tex-paper.ts";
+import { originOf, type PaperSource } from "./domain/paper-source.ts";
+import type { SourcesCodec } from "./ports/sources-codec.ts";
+import { MAIN } from "./build.ts";
 
-/** The environment variable each portal kind's token is read from. */
-export const TOKEN_ENV: Readonly<Record<SupportedPortal["kind"], string>> = {
-  hotcrp: "HOTCRP_TOKEN",
-};
+/** How to make and set the site's token: the page, the scopes, the variable. Pure. */
+export function tokenSteps(
+  portal: SupportedPortal,
+  site: PortalSite,
+  variable: string,
+): readonly string[] {
+  const c = site.credentials;
+  return [
+    `  1. create a token on this site: ${c.page} (${c.where}), with the scopes ${c.scopes}`,
+    `  2. set it in your environment — never paste it into a chat: export ${variable}=<the token>`,
+    `  tokens are per ${portal.kind} site: ${variable} is read for ${hostOf(portal.url)} alone, so two venues take two variables`,
+  ];
+}
 
-/** Where each portal kind lets an author create a token. */
-const TOKEN_HELP: Readonly<Record<SupportedPortal["kind"], string>> = {
-  hotcrp:
-    "create one on the HotCRP site under Account settings → Developer, with the scopes submeta:read and document:read (show) and submeta:write and document:write (update)",
-};
+/** Why there is no token, as the complete instruction the author follows. Pure. */
+export function tokenProblemLines(
+  portal: SupportedPortal,
+  site: PortalSite,
+  p: TokenProblem,
+): readonly string[] {
+  const head =
+    p.kind === "missing"
+      ? `no ${portal.kind} token for ${portal.url}: ${p.variable} is not set`
+      : `${p.siteLess} is no longer read: tokens are per ${portal.kind} site. If it was made on ${hostOf(portal.url)}, rename it to ${p.variable}; if it was made on another site, rename it to that site's variable (${site.variablePattern}) and create a token here:`;
+  return [head, ...tokenSteps(portal, site, p.variable)];
+}
+
+/**
+ * What to do when the portal turned the token away: 401 is "this site does not know the token", 403
+ * a token without the scope — both answered with the site's token page. Empty for anything else. Pure.
+ */
+export function tokenRefusedLines(
+  portal: SupportedPortal,
+  site: PortalSite,
+  f: PortalFailure,
+): readonly string[] {
+  if (f.kind !== "refused" || (f.httpStatus !== 401 && f.httpStatus !== 403))
+    return [];
+  const variable = site.tokenVariable;
+  const why =
+    f.httpStatus === 401
+      ? `${variable} was used; it may belong to another ${portal.kind} site (tokens are per site), or be revoked or expired`
+      : `${variable} was used; the site turned the request away — the token may lack a scope this subcommand needs`;
+  return [why, ...tokenSteps(portal, site, variable)];
+}
 
-export const SUBCOMMANDS = ["show", "update"] as const;
+export const SUBCOMMANDS = ["new", "show", "update"] as const;
 export type Subcommand = (typeof SUBCOMMANDS)[number];
 const isSubcommand = (s: string | undefined): s is Subcommand =>
   SUBCOMMANDS.some((x) => x === s);
@@ -69,7 +124,10 @@ export interface SubmissionArgs {
   readonly extra: readonly string[];
   /** `--pdf <file>`, relative to `cwd`; null: the paper's own PDF. */
   readonly pdf: string | null;
-  /** `--abstract <file>`, relative to `cwd`; null: leave the abstract as it is. */
+  /**
+   * `--abstract <file>`, relative to `cwd`; null: `update` leaves the abstract as it is, `new` reads
+   * it from the build.
+   */
   readonly abstract: string | null;
   readonly submit: boolean;
   readonly save: boolean;
@@ -81,7 +139,12 @@ export interface SubmissionDeps {
   readonly cwd: string;
   /** The value of an environment variable; the root reads the environment. */
   readonly env: (name: string) => string | undefined;
-  readonly portalFor: (p: SupportedPortal, token: string) => SubmissionPortal;
+  /** The portal site of a supported kind: its token variable and help, and its API once there is a token. */
+  readonly site: (p: SupportedPortal) => PortalSite;
+  /** Reads the paper's `\title` and its abstract, its includes spliced in (`new`). */
+  readonly latex: LatexReader;
+  /** Reads the build's record of the files TeX read, for the includes (`new`). */
+  readonly codec: SourcesCodec;
   readonly log: (line: string) => void;
   readonly err: (line: string) => void;
 }
@@ -89,7 +152,14 @@ export interface SubmissionDeps {
 /** A paper's portal, its submission there, and the PDF the paper builds. */
 export interface SubmissionTarget {
   readonly portal: SupportedPortal;
-  readonly id: number;
+  /** The paper's submission on the portal; null before `new` created one. */
+  readonly id: number | null;
+  /** The paper's `paperlint.json`, absolute. */
+  readonly config: string;
+  /** The authors the paper declares for the portal; null when it declares none. */
+  readonly authors: readonly Author[] | null;
+  /** The cycle attempt is accepted: a new submission belongs to a new cycle. */
+  readonly accepted: boolean;
   /** The paper's built PDF, absolute. */
   readonly pdf: string;
   /** The venue's call for papers (the preset's `url`); null when the preset names no venue. */
@@ -122,11 +192,6 @@ function targetOf(
     return err(
       `the venue preset declares no "portal" (read: ${p.preset.chain.join(", ")}) — add "portal": { "kind": "hotcrp", "url": "<the site>" } to the venue's preset, or upload by hand`,
     );
-  const sub = p.settings.submission;
-  if (sub === null)
-    return err(
-      `${configOf(paperDir)}: no "submission" — add "submission": { "id": <the submission number on ${declared.url}> }`,
-    );
   const portal = supportedPortal(declared);
   if (!portal.ok) return portal;
   const pdf = join(paperDir, p.settings.pdf ?? "paper.pdf");
@@ -137,7 +202,16 @@ function targetOf(
       ? []
       : currentDeadlines(p.settings.cycles.current);
   const deadlines = deadlinesInForce(own, p.preset.deadlines);
-  return ok({ portal: portal.value, id: sub.id, pdf, call, deadlines });
+  return ok({
+    portal: portal.value,
+    id: p.settings.submission?.id ?? null,
+    config: configOf(paperDir),
+    authors: p.settings.authors,
+    accepted: p.settings.cycles?.current.kind === "accepted",
+    pdf,
+    call,
+    deadlines,
+  });
 }
 
 /** The paper directory → its portal and submission, or the line naming the file and key to set. */
@@ -157,20 +231,6 @@ export function submissionTarget(
   }
 }
 
-/** The token from the environment, or the line naming the variable and where to get one. */
-export function tokenFor(
-  portal: SupportedPortal,
-  env: (name: string) => string | undefined,
-): Result<string, string> {
-  const name = TOKEN_ENV[portal.kind];
-  const v = env(name)?.trim();
-  return v
-    ? ok(v)
-    : err(
-        `${name} is not set — the ${portal.kind} API needs a token: ${TOKEN_HELP[portal.kind]}. Then: export ${name}=…`,
-      );
-}
-
 const iso = (seconds: number | null): string =>
   seconds === null ? "—" : new Date(seconds * 1000).toISOString();
 
@@ -207,23 +267,20 @@ const pdfLine = (view: SubmissionView): string =>
     ? "portal PDF    none"
     : `portal PDF    ${view.pdf.hash}, ${view.pdf.size === null ? "?" : String(view.pdf.size)} bytes, uploaded ${iso(view.pdf.uploadedAt)}`;
 
-const readingText = (o: Observation): string =>
-  `${o.source} ${o.at}, read ${o.read}`;
-
 /** One deadline in force, what set it, and the other readings of it. Pure. */
 export function deadlineLine(d: InForce): string {
   const by = d.by;
-  const why =
+  const set =
     by.kind === "override"
-      ? `override: ${by.override.reason} (${by.override.evidence})`
-      : `${by.reading.source}, read ${by.reading.read}`;
+      ? `${d.at} — override: ${by.override.reason} (${by.override.evidence})`
+      : readingText(by.reading);
   const others = d.readings.filter(
     (r) => by.kind === "override" || r !== by.reading,
   );
   const also = others.length
     ? `; also ${others.map(readingText).join("; ")}`
     : "";
-  return `deadline      ${d.what} ${d.at} — ${why}${also}`;
+  return `deadline      ${d.what} ${set}${also}`;
 }
 
 /** `show`'s report. Pure. */
@@ -283,15 +340,37 @@ const shownPath = (cwd: string, p: string): string =>
 const bytesAt = (files: Files, p: string): Uint8Array | null =>
   files.readBytes(absolutePath(p));
 
+/** The deps a subcommand runs with: the command's, and what to say when the portal turns the token away. */
+type RunDeps = SubmissionDeps & {
+  readonly portalSite: PortalSite;
+  readonly refused: (f: PortalFailure) => readonly string[];
+};
+
+/** A failure printed — the portal's words, then what to do about the token if it was the token — exit 1. */
+function failed(f: PortalFailure, deps: RunDeps): number {
+  [failureText(f), ...deps.refused(f)].forEach((l) => {
+    deps.err(l);
+  });
+  return 1;
+}
+
+/** The submission's id, or the line naming the key to set — `show` and `update` need one. */
+const idOf = (t: SubmissionTarget): Result<number, string> =>
+  t.id === null
+    ? err(
+        `${t.config}: no "submission" — add "submission": { "id": <the submission number on ${t.portal.url}> }, or create the submission with \`paperlint submission new\``,
+      )
+    : ok(t.id);
+
 /** `show`: read the submission and compare its PDF with the local one. */
 async function runShow(
-  t: SubmissionTarget,
+  t: SubmissionTarget & { readonly id: number },
   portal: SubmissionPortal,
   pdfPath: string,
-  deps: SubmissionDeps,
+  deps: RunDeps,
 ): Promise<number> {
   const view = await portal.show(t.id);
-  if (!view.ok) return (deps.err(failureText(view.error)), 1);
+  if (!view.ok) return failed(view.error, deps);
   const bytes = bytesAt(deps.files, pdfPath);
   const local = {
     shown: shownPath(deps.cwd, pdfPath),
@@ -329,10 +408,10 @@ const changeOf = (
 
 /** `update`: send the PDF (and the abstract, and "submitted" when asked); a dry run unless saving. */
 async function runUpdate(
-  t: SubmissionTarget,
+  t: SubmissionTarget & { readonly id: number },
   portal: SubmissionPortal,
   a: SubmissionArgs & { readonly pdfPath: string },
-  deps: SubmissionDeps,
+  deps: RunDeps,
 ): Promise<number> {
   const bytes = bytesAt(deps.files, a.pdfPath);
   const shown = shownPath(deps.cwd, a.pdfPath);
@@ -347,7 +426,7 @@ async function runUpdate(
   const r = await portal.update(t.id, changeOf(a, bytes, abstract.value), {
     save: a.save,
   });
-  if (!r.ok) return (deps.err(failureText(r.error)), 1);
+  if (!r.ok) return failed(r.error, deps);
   const local = { shown, sha256: sha256Hex(bytes) };
   updateLines(r.value, local, a.save).forEach((l) => {
     deps.log(l);
@@ -357,23 +436,366 @@ async function runUpdate(
   return fine ? 0 : 1;
 }
 
+// ── new ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The metadata of the PDF that is sent, from the build's facts — the title's fallback; null when
+ * there are no facts, or they describe another PDF.
+ */
+function pdfMetadata(
+  paperDir: string,
+  pdf: Uint8Array,
+  deps: SubmissionDeps,
+): Readonly<Record<string, string>> | null {
+  const bytes = bytesAt(deps.files, factsPath(paperDir));
+  const facts =
+    bytes === null ? null : parseFactsText(new TextDecoder().decode(bytes));
+  return facts?.ok === true && facts.value.sha === sha256Hex(pdf)
+    ? facts.value.text.metadata
+    : null;
+}
+
+/** Where an offset of the assembled paper stands in its own file: `file:line:column`. */
+function placeIn(paper: PaperSource, offset: number): string {
+  const o = originOf(paper, { start: offset, end: offset });
+  return o === null ? MAIN : `${o.file}:${lineColumn(o.source, o.span.start)}`;
+}
+
+/**
+ * The abstract from the paper's source: its `abstract` environment, with the files it includes
+ * spliced in as the build recorded them, as plain text — or why it cannot be read without guessing.
+ */
+function sourceAbstract(
+  paper: PaperSource | null,
+  deps: SubmissionDeps,
+): Result<string, string> {
+  const instead = "give the abstract with --abstract <file>, a plain-text file";
+  if (paper === null)
+    return err(`no ${MAIN} to read the abstract from — ${instead}`);
+  const r = deps.latex.abstractText(paper.text);
+  if (r.ok) return r;
+  const guess = "paperlint sends no text it would have to guess";
+  switch (r.error.kind) {
+    case "none":
+      return err(
+        `${MAIN} has no \\begin{abstract}…\\end{abstract} — ${instead}`,
+      );
+    case "unreadable":
+      return err(
+        `the abstract, ${placeIn(paper, r.error.at)}: ${r.error.what} — ${guess}; ${instead}`,
+      );
+    case "redefined":
+      return err(
+        `the abstract uses \\${r.error.name}, which the paper defines ${String(r.error.at.length)} times (${r.error.at.map((o) => placeIn(paper, o)).join(", ")}) — which one TeX uses there is not guessed; ${instead}`,
+      );
+  }
+}
+
+/**
+ * The title as the paper sets it: its `\title`, as text — or, when the title holds a command
+ * paperlint cannot read (a macro of the author's own), the PDF's own Title (`pdftitle`). Pure.
+ */
+export function titleOf(
+  source: {
+    readonly text: string;
+    /** Where an offset of `text` stands, as a message names it (file:line:column). */
+    readonly where: (offset: number) => string;
+  } | null,
+  latex: Pick<LatexReader, "headings">,
+  metadata: Readonly<Record<string, string>> | null,
+): Result<string, string> {
+  const titles = (source === null ? [] : latex.headings(source.text)).filter(
+    (h) => h.command.kind === "title" && h.argument === "title",
+  );
+  // One \title is read; several are not chosen between — the PDF's own Title stands in, or the fix.
+  const [heading] = titles.length === 1 ? titles : [];
+  const text =
+    heading === undefined
+      ? ""
+      : runText(heading.title)
+          .replaceAll(LINE_BREAK, " ")
+          .replace(/\s+/g, " ")
+          .trim();
+  if (text !== "" && !text.includes(OPAQUE)) return ok(text);
+  const pdfTitle = pdfTitleOf(metadata);
+  if (pdfTitle !== "") return ok(pdfTitle);
+  return err(
+    titles.length > 1
+      ? `the paper sets \\title ${String(titles.length)} times (${titles.map((h) => source?.where(h.title.segments[0].at)).join(", ")}), and the PDF names no Title — which one to send is not guessed: keep one \\title, or set \\hypersetup{pdftitle={<the title as plain text>}} and rebuild`
+      : noReadableTitle(text),
+  );
+}
+
+/** The Info dictionary's Title, else the XMP packet's dc:title (pdf-content.ts keeps both); "" for none. */
+const pdfTitleOf = (
+  metadata: Readonly<Record<string, string>> | null,
+): string =>
+  [metadata?.["Title"], metadata?.["dc:title"]]
+    .map((t) => t?.trim() ?? "")
+    .find((t) => t !== "") ?? "";
+
+/** The fix when the one \\title is missing (`text` "") or holds a command paperlint does not read. */
+const noReadableTitle = (text: string): string =>
+  text === ""
+    ? `no \\title in ${MAIN}, and the PDF names no Title — add \\title{…}, or \\hypersetup{pdftitle={…}}, and rebuild`
+    : `the \\title in ${MAIN} uses a command paperlint does not read («${text.replaceAll(OPAQUE, "…")}»), and the PDF names no Title — set \\hypersetup{pdftitle={<the title as plain text>}} and rebuild`;
+
+/** What `new` will send, as the author reads it before saying yes. Pure. */
+export function newLines(
+  title: string,
+  abstract: string,
+  authors: readonly Author[],
+): readonly string[] {
+  return [
+    `title         ${title}`,
+    ...authors.map(
+      (a, i) =>
+        `author ${String(i + 1).padEnd(6)} ${a.name} <${a.email}>${a.affiliation === null ? "" : `, ${a.affiliation}`}`,
+    ),
+    `abstract      ${String(wordCount(abstract))} words:`,
+    `  ${abstract}`,
+  ];
+}
+
+/** What the author does on the site after `new`: what paperlint does not send. Pure. */
+export function onTheSiteLines(
+  site: PortalSite,
+  id: number | null,
+  paperArg: string,
+): readonly string[] {
+  return [
+    `do on the site, ${site.submissionPage(id)} — paperlint sends only the title, the abstract, the authors and the PDF:`,
+    ...site.siteOnly.map((f) => `  - ${f}`),
+    `  - then mark it submitted: npx paperlint submission update ${paperArg} --submit (a dry run; --save after your yes)`,
+  ];
+}
+
+/** `new`'s report of the portal's answer. Pure. */
+export function createLines(
+  o: CreateOutcome,
+  save: boolean,
+): readonly string[] {
+  const mode = save
+    ? o.id === null
+      ? "NOTHING CREATED — the portal did not save it"
+      : `created submission ${String(o.id)}`
+    : "dry run — the portal checked the new submission and kept nothing; --save creates it for real";
+  return [
+    mode,
+    `HTTP          ${String(o.httpStatus)}`,
+    `valid         ${o.valid ? "yes" : "NO"}`,
+    `changes       ${o.changes.length ? o.changes.join(", ") : "—"}`,
+    ...o.messages.map(messageLine),
+  ];
+}
+
+/** A file's JSON, or why there is none: gone, or not JSON. */
+function jsonAt(files: Files, path: string): Result<unknown, string> {
+  const bytes = bytesAt(files, path);
+  if (bytes === null) return err("the file is gone");
+  try {
+    return ok(JSON.parse(new TextDecoder().decode(bytes)));
+  } catch (e) {
+    return err(`not JSON: ${messageOf(e)}`);
+  }
+}
+
+/** `paperlint.json` with the new id recorded in it, written; or why it was not. */
+function recordId(
+  config: string,
+  id: number,
+  deps: SubmissionDeps,
+): Result<null, string> {
+  const json = jsonAt(deps.files, config);
+  if (!json.ok) return json;
+  const next = withSubmissionId(json.value, id);
+  if (!next.ok) return next;
+  // A write that fails (read-only, disk full) must not lose the id the portal just gave.
+  try {
+    deps.files.writeAtomic(
+      absolutePath(config),
+      new TextEncoder().encode(`${JSON.stringify(next.value, null, 2)}\n`),
+    );
+    return ok(null);
+  } catch (e) {
+    return err(messageOf(e));
+  }
+}
+
+//** Why `new` cannot run for this paper, or the authors it sends: checked before anything is read. */
+function readyForNew(t: SubmissionTarget): Result<readonly Author[], string> {
+  if (t.id !== null)
+    return err(
+      `${t.config}: the paper already has submission ${String(t.id)} on ${t.portal.url} — \`paperlint submission show\` reads it, \`paperlint submission update\` changes it`,
+    );
+  if (t.accepted)
+    return err(
+      `${t.config}: the current attempt is accepted — a new submission belongs to a new cycle`,
+    );
+  return t.authors === null
+    ? err(
+        `${t.config}: no "authors" — add "authors": [{ "name": "…", "email": "…", "affiliation": "…" }], every author in the paper's order, as ${hostOf(t.portal.url)} should record them; paperlint never guesses them`,
+      )
+    : ok(t.authors);
+}
+
+/** The paper as the build read it: paper.tex with the files it includes spliced in; null without one. */
+function assembledPaper(
+  paperDir: string,
+  deps: SubmissionDeps,
+): PaperSource | null {
+  const bytes = bytesAt(deps.files, join(paperDir, MAIN));
+  return bytes === null
+    ? null
+    : readPaper(join(paperDir, MAIN), new TextDecoder().decode(bytes), deps);
+}
+
+/** The title and the abstract: the paper's `\title`, and `--abstract`'s file or the source's abstract. */
+function titleAndAbstract(
+  a: SubmissionArgs & { readonly paperDir: string },
+  pdf: Uint8Array,
+  deps: SubmissionDeps,
+): Result<{ readonly title: string; readonly abstract: string }, string> {
+  const own = abstractOf(a, deps);
+  if (!own.ok) return own;
+  const paper = assembledPaper(a.paperDir, deps);
+  const metadata = pdfMetadata(a.paperDir, pdf, deps);
+  const title = titleOf(
+    paper === null
+      ? null
+      : { text: paper.text, where: (o: number) => placeIn(paper, o) },
+    deps.latex,
+    metadata,
+  );
+  if (!title.ok) return title;
+  const abstract =
+    own.value === null
+      ? sourceAbstract(paper, deps)
+      : ok(own.value.replace(/\s+/g, " "));
+  return abstract.ok
+    ? ok({ title: title.value, abstract: abstract.value })
+    : abstract;
+}
+
+/** What `new` sends, or the first line saying what is missing. */
+function newSubmissionOf(
+  t: SubmissionTarget,
+  a: SubmissionArgs & { readonly pdfPath: string; readonly paperDir: string },
+  deps: SubmissionDeps,
+): Result<{ readonly paper: NewSubmission; readonly shown: string }, string> {
+  const authors = readyForNew(t);
+  if (!authors.ok) return authors;
+  const shown = shownPath(deps.cwd, a.pdfPath);
+  const pdf = bytesAt(deps.files, a.pdfPath);
+  if (pdf === null)
+    return err(`no PDF at ${shown} — build the paper, or name one with --pdf`);
+  const text = titleAndAbstract(a, pdf, deps);
+  if (!text.ok) return text;
+  const paper = {
+    ...text.value,
+    authors: authors.value,
+    pdf: { name: basename(a.pdfPath), bytes: pdf },
+  };
+  return ok({ paper, shown });
+}
+
+//** After a save that created one: the id written into `paperlint.json`, and the next command. */
+function recordCreated(
+  t: SubmissionTarget,
+  id: number,
+  paperArg: string,
+  deps: RunDeps,
+): number {
+  const config = shownPath(deps.cwd, t.config);
+  const recorded = recordId(t.config, id, deps);
+  if (!recorded.ok) {
+    deps.err(
+      `submission ${String(id)} was created (${deps.portalSite.submissionPage(id)}), but ${config} was not changed (${recorded.error}) — add "submission": { "id": ${String(id)} } to the current attempt by hand`,
+    );
+    return 1;
+  }
+  deps.log(`recorded      "submission": { "id": ${String(id)} } in ${config}`);
+  deps.log(
+    `next          npx paperlint submission show ${paperArg} — it should say "match yes"`,
+  );
+  return 0;
+}
+
+const logAll = (lines: readonly string[], deps: RunDeps): void => {
+  lines.forEach((l) => {
+    deps.log(l);
+  });
+};
+
+/**
+ * `new`: create the paper's submission — title and abstract from the build, the authors the paper
+ * declares, the PDF. A dry run unless `--save`; after a save, the id goes into `paperlint.json`.
+ */
+async function runNew(
+  t: SubmissionTarget,
+  portal: SubmissionPortal,
+  a: SubmissionArgs & { readonly pdfPath: string; readonly paperDir: string },
+  deps: RunDeps,
+): Promise<number> {
+  const n = newSubmissionOf(t, a, deps);
+  if (!n.ok) return (deps.err(n.error), 2);
+  const { paper, shown } = n.value;
+  deps.log(checkPdfLine(shown, t.call));
+  logAll(newLines(paper.title, paper.abstract, paper.authors), deps);
+  const r = await portal.create(paper, { save: a.save });
+  if (!r.ok) return failed(r.error, deps);
+  logAll(createLines(r.value, a.save), deps);
+  const fine =
+    r.value.valid && r.value.httpStatus >= 200 && r.value.httpStatus < 300;
+  if (!fine || (a.save && r.value.id === null)) return 1;
+  const paperArg =
+    a.paperDir === deps.cwd ? "." : shownPath(deps.cwd, a.paperDir);
+  logAll(onTheSiteLines(deps.portalSite, r.value.id, paperArg), deps);
+  return r.value.id === null ? 0 : recordCreated(t, r.value.id, paperArg, deps);
+}
+
+//** The flags that change something, as given. */
+const writingFlags = (a: SubmissionArgs): readonly string[] =>
+  [
+    a.abstract === null ? null : "--abstract",
+    a.submit ? "--submit" : null,
+    a.save ? "--save" : null,
+  ].filter((f) => f !== null);
+
 /** Why the command line cannot be run as asked; null when it can. Pure. */
 export function usageProblem(a: SubmissionArgs): string | null {
   if (!isSubcommand(a.sub))
     return `\`submission\` needs a subcommand: ${SUBCOMMANDS.join(" or ")} — got \`${a.sub ?? ""}\``;
   if (a.extra.length > 0)
     return `\`submission ${a.sub}\` takes one paper folder — got also \`${a.extra.join(" ")}\``;
-  const updateOnly = [
-    a.abstract === null ? null : "--abstract",
-    a.submit ? "--submit" : null,
-    a.save ? "--save" : null,
-  ].filter((f) => f !== null);
-  return a.sub === "show" && updateOnly.length > 0
-    ? `${updateOnly.join(", ")}: only \`submission update\` changes anything; \`show\` reads`
+  const writing = writingFlags(a);
+  if (a.sub === "show" && writing.length > 0)
+    return `${writing.join(", ")}: only \`submission new\` and \`submission update\` change anything; \`show\` reads`;
+  return a.sub === "new" && a.submit
+    ? "--submit: `submission new` creates the submission; mark it submitted with `submission update --submit` once `show` says the portal holds this build"
     : null;
 }
 
-/** `paperlint submission <show|update> [paper-dir]` — exit 0, 1 (the portal said no), or 2 (usage). */
+/** The variables a site's token lookup reads. */
+const tokenNames = (site: PortalSite) => ({
+  variable: site.tokenVariable,
+  siteLess: site.siteLessVariable,
+});
+
+/** No token to use: the complete instruction, exit 2 — nothing is sent. */
+function tokenMissing(
+  portal: SupportedPortal,
+  site: PortalSite,
+  p: TokenProblem,
+  deps: SubmissionDeps,
+): number {
+  tokenProblemLines(portal, site, p).forEach((l) => {
+    deps.err(l);
+  });
+  return 2;
+}
+
+/** `paperlint submission <new|show|update> [paper-dir]` — exit 0, 1 (the portal said no), or 2 (usage). */
 export async function runSubmission(
   a: SubmissionArgs,
   deps: SubmissionDeps,
@@ -383,11 +805,22 @@ export async function runSubmission(
   const paperDir = resolve(deps.cwd, a.paperDir);
   const t = submissionTarget(paperDir, deps.presets);
   if (!t.ok) return (deps.err(t.error), 2);
-  const token = tokenFor(t.value.portal, deps.env);
-  if (!token.ok) return (deps.err(token.error), 2);
-  const portal = deps.portalFor(t.value.portal, token.value);
+  const id = a.sub === "new" ? ok(null) : idOf(t.value);
+  if (!id.ok) return (deps.err(id.error), 2);
+  const site = deps.site(t.value.portal);
+  const found = lookUpToken(tokenNames(site), deps.env);
+  if (!found.ok) return tokenMissing(t.value.portal, site, found.error, deps);
+  const portal = site.connect(found.value.token);
   const pdfPath = a.pdf === null ? t.value.pdf : resolve(deps.cwd, a.pdf);
+  const withToken: RunDeps = {
+    ...deps,
+    portalSite: site,
+    refused: (f) => tokenRefusedLines(t.value.portal, site, f),
+  };
+  if (id.value === null)
+    return runNew(t.value, portal, { ...a, pdfPath, paperDir }, withToken);
+  const target = { ...t.value, id: id.value };
   return a.sub === "show"
-    ? runShow(t.value, portal, pdfPath, deps)
-    : runUpdate(t.value, portal, { ...a, pdfPath }, deps);
+    ? runShow(target, portal, pdfPath, withToken)
+    : runUpdate(target, portal, { ...a, pdfPath }, withToken);
 }