paperlint 10.4.1 → 11.0.0

package/skills/submission-portal/SKILL.md.spec.ts

@@ -4,68 +4,87 @@ import { experimental_skill } from "vigiles/spec";
 export default experimental_skill({
   name: "submission-portal",
   description:
-    "Read or change a paper's submission on the venue's HotCRP portal via `paperlint submission show|update`: replace the PDF or abstract, mark it submitted, check it is really \"Submitted\", and verify by sha256 that the portal holds the latest build. Use when the PDF or abstract on HotCRP needs replacing, when asked whether the paper is truly submitted or which PDF reviewers see, or before a deadline. Composes with submit-paper (what to submit); this gets it onto the portal and proves it landed.",
+    "Create, read or change a paper's submission on the venue's HotCRP portal via `paperlint submission new|show|update`: register the paper, replace the PDF or abstract, mark it submitted, and verify by sha256 that the portal holds the latest build. Use when the paper is not yet on HotCRP, when its PDF or abstract there needs replacing, when asked whether it is truly submitted, or before a deadline. Composes with submit-paper (what to submit).",
   tools: ["Read", "Grep", "Glob", "Bash"],
+  // The `npx paperlint submission …` commands in the body are not verified at compile time until
+  // zernie/vigiles#395 (cmd() for the package's own CLI): keep them in step with src/cli.ts by hand.
+  // Do not re-add a test that re-parses the compiled SKILL.md — that check belongs in vigiles.
   body: `
-# submission-portal — read and update the submission on the portal, then prove it landed
+# submission-portal — create, read and update the submission on the portal, then prove it landed
 
-\`paperlint submission\` talks to the venue's submission portal through its API. Only HotCRP is
-supported; for any other portal the command says so and the upload is done by hand.
+\`paperlint submission\` creates, reads and updates the paper's submission on the venue's portal.
+Only HotCRP is supported; for any other portal the command says so and the upload is done by hand.
+
+## What the command does, and what stays on the site
+
+\`submission new\` creates the submission with the title, the abstract, the authors and the PDF.
+Everything else — conflicts, topics, the venue's own fields — is done on the site by the author: the
+command prints that list, with the submission's page, after every run.
+
+## Token
+
+One variable per site: \`HOTCRP_TOKEN_MSR2027\` for \`msr2027.hotcrp.com\`; for a site not on
+hotcrp.com, its whole host (with a port other than the default) and path. A plain \`HOTCRP_TOKEN\` is not read. When the command reports
+a missing, misnamed or refused token, **relay its message to the author verbatim and stop**: it
+already says where on the site to make one, which permissions to tick, and which variable to set.
+🔴 Never ask for the token in chat, never print it, never write it to a file — the author sets it in
+their own environment.
 
 ## What must be in place
 
 - **The venue preset declares the portal**: \`"portal": { "kind": "hotcrp", "url": "<the site>" }\`
-  (\`paperlint:aidc\` and \`paperlint:msr\` have it). For your own venue preset, add it there.
-- **The paper's \`paperlint.json\` names its submission**: \`"submission": { "id": <number> }\` — the
-  number HotCRP shows for the paper.
-- **A token in \`HOTCRP_TOKEN\`**, created by the author on the HotCRP site under Account settings →
-  Developer (scopes \`submeta:read\` and \`document:read\` to read; \`submeta:write\` and
-  \`document:write\` to update). Never ask for it in chat, never print it, never write it to a file:
-  the command reads it from the environment and sends it only as the \`Authorization\` header.
+  (\`paperlint:aidc\` and \`paperlint:msr\` have it).
+- **For \`new\`: \`"authors"\` in the paper's \`paperlint.json\`** — \`[{ "name", "email",
+  "affiliation" }]\`, every author in the paper's order. The author writes this list; never fill it
+  in from the paper, a profile or memory.
+- **For \`show\` and \`update\`: \`"submission": { "id": <number> }\`** — \`new --save\` writes it.
 
-A missing key or token stops the command with exit 2 and a line naming the file and key, or the
-variable — fix exactly that and run again.
+A missing key or token stops the command with exit 2 and a line naming what to set — fix exactly that.
 
 ## The procedure — always in this order
 
-1. **Read it.** \`npx paperlint submission show papers/<paper>\` — status, title, type, topics,
-   abstract length, the PDF the portal holds, and \`match\`: whether that PDF's sha256 equals the
-   local \`paper.pdf\`. Rebuild first (\`npx paperlint build papers/<paper>\`) if the local PDF is stale.
-2. **Dry run.** \`npx paperlint submission update papers/<paper>\` — sends the PDF (add
-   \`--abstract <file>\` for a plain-text abstract, \`--submit\` to mark it submitted) with HotCRP's
-   \`dry_run=1\`: the portal checks the change and **keeps nothing**. Read \`valid\`, \`changes\` and every
-   \`portal says:\` line. Exit 1 means the portal would refuse it — report why, do not go on.
-3. **Ask the author.** Show the dry run's output and ask for an explicit yes to change the real
-   submission.
-4. **Save — only after that yes.** \`npx paperlint submission update papers/<paper> --save\` (same
-   flags as the dry run). 🔴 \`--save\` CHANGES A REAL SUBMISSION that reviewers will see. Never run it
-   without the author's explicit yes in this conversation, never "to test", and never because a
-   dry run was valid.
-5. **Prove it landed.** \`npx paperlint submission show papers/<paper>\` again: \`match\` must read
-   \`yes — the portal holds this build\`, and the status must be what was intended (\`submitted\` if
-   \`--submit\` was sent). Anything else is not done — say so.
-
-The same five steps as commands, in order (\`<paper>\` is the paper's folder):
+\`papers/my-paper\` stands for the paper's folder.
+
+0. **Create it, once — only while the paper has no \`submission\` id.**
+   \`npx paperlint submission new papers/my-paper\` is a dry run: the portal checks it and keeps
+   nothing. It prints the title, the authors and the whole abstract (read from the source's
+   \`\\begin{abstract}\`). Read them with the author; an abstract the command cannot read, or one
+   that reads wrong, is given as a plain-text file with \`--abstract <file>\`.
+1. **Ask the author** for an explicit yes, then \`npx paperlint submission new papers/my-paper --save\`,
+   and do the printed "on the site" list with the author.
+2. **Read it.** \`npx paperlint submission show papers/my-paper\` — status, the PDF the portal holds,
+   and \`match\`: whether it is the local build. Rebuild first if the local PDF is stale.
+3. **Dry run the change.** \`npx paperlint submission update papers/my-paper\` (\`--abstract <file>\`,
+   \`--submit\` to mark it submitted). Exit 1 means the portal would refuse it — report why, stop.
+4. **Ask the author** for an explicit yes, then the same command with \`--save\`.
+5. **Prove it landed.** \`show\` again: \`match\` must read \`yes — the portal holds this build\`, and
+   the status must be what was intended. Anything else is not done — say so.
+
+🔴 \`--save\` creates or changes a real submission that reviewers will see: never without the
+author's yes in this conversation, never "to test", never because a dry run passed.
 
 \`\`\`bash
-npx paperlint submission show papers/<paper>
-npx paperlint submission update papers/<paper>
+npx paperlint build papers/my-paper
+# only while the paper has no submission id:
+npx paperlint submission new papers/my-paper
+# … the author reads the dry run and says yes …
+npx paperlint submission new papers/my-paper --save
+npx paperlint submission show papers/my-paper
+npx paperlint submission update papers/my-paper --submit
 # … the author reads the dry run and says yes …
-npx paperlint submission update papers/<paper> --save
-npx paperlint submission show papers/<paper>
+npx paperlint submission update papers/my-paper --submit --save
+npx paperlint submission show papers/my-paper
 \`\`\`
 
 ## Reading the answers
 
-- \`match yes\` is the only proof the reviewers get the local build; a status of \`submitted\` alone
-  says nothing about WHICH PDF.
-- \`the portal refused (HTTP 401): …\` — the token is missing, wrong or expired; \`403\` — the token
-  lacks the scope, or the deadline has passed for this change. The text after the colon is
-  HotCRP's own; quote it.
-- \`SAVE WITHHELD by the portal\` — HotCRP did not save; nothing changed.
+- \`match yes\` is the only proof the reviewers get the local build; \`submitted\` alone says nothing
+  about WHICH PDF.
+- \`portal says: …\` lines are the portal's own words; quote them.
+- \`SAVE WITHHELD\` or \`NOTHING CREATED\` — the portal saved nothing.
 
 ## What this skill does not do
 
-It does not decide whether the paper is ready (that is \`harden-paper\`), anonymize it, or fill the
-submission form's other fields (authors, conflicts) — see \`submit-paper\`.`,
+It does not decide whether the paper is ready (\`harden-paper\`), anonymize it, or set the portal's
+other fields — see \`submit-paper\`.`,
 });

package/skills/submission-portal/submission-portal.test.ts

@@ -1,80 +1,11 @@
 /**
- * submission-portal — the free tier: the skill's commands are commands the CLI accepts, in the
- * order the skill promises, and the skill passes the shared per-skill checks. No model, no network,
- * no portal.
- *
- * 🔴 WHY THE COMMANDS ARE PARSED, NOT GREPPED: a skill that tells the agent to run a flag the CLI
- * refuses fails at the worst moment — before a deadline, on a real submission. So every
- * `paperlint submission …` the skill writes goes through the CLI's own argument parser and its
- * usage check, and must come out runnable.
+ * submission-portal — the shared per-skill checks (frontmatter, tool contract, pipeline wiring, own
+ * identity). Not checked here: that the skill's `npx paperlint submission …` commands are ones the
+ * CLI runs — that belongs in vigiles (zernie/vigiles#395) — nor that the skill fires
+ * (`submission-portal.eval.mjs`).
  */
-import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { test } from "vitest";
-import { commandsIn } from "vigiles";
 import { checkSkill } from "../../lib/skill-checks.mjs";
-import { parseArgs } from "../../src/cli.ts";
-import { usageProblem } from "../../src/submission.ts";
-
-const SKILL = readFileSync(
-  join(dirname(fileURLToPath(import.meta.url)), "SKILL.md"),
-  "utf8",
-);
-const commands = commandsIn(
-  SKILL,
-  /(^|[|;&]\s*)npx paperlint submission\b/,
-).map((c) => c.text);
-
-/** A command as the CLI receives it: the words after `npx paperlint`. */
-const argvOf = (command: string): string[] =>
-  command
-    .replace(/^.*?npx paperlint /, "")
-    .split(/\s+/)
-    .filter(Boolean);
-
-test("the skill names show, a dry run and a save — and nothing else", () => {
-  const kinds = commands.map((c) => {
-    const a = parseArgs(argvOf(c));
-    return `${String(a.paths[0])}${a.save ? " --save" : ""}`;
-  });
-  assert.deepEqual([...new Set(kinds)], ["show", "update", "update --save"]);
-});
-
-test("every `paperlint submission` command in the skill is one the CLI runs", () => {
-  assert.ok(
-    commands.length > 0,
-    "the skill names no `paperlint submission` command",
-  );
-  for (const c of commands) {
-    const a = parseArgs(argvOf(c));
-    assert.equal(a.cmd, "submission", c);
-    assert.equal(a.unknownFlag, undefined, c);
-    assert.equal(a.missingValue, undefined, c);
-    const problem = usageProblem({
-      sub: a.paths[0],
-      paperDir: a.paths[1] ?? ".",
-      extra: a.paths.slice(2),
-      pdf: a.pdf,
-      abstract: a.abstract,
-      submit: a.submit,
-      save: a.save,
-    });
-    assert.equal(problem, null, c);
-  }
-});
-
-test("🔴 the procedure reads, dry-runs, then saves, then reads again — never saves first", () => {
-  const order = commands.map((c) => {
-    const a = parseArgs(argvOf(c));
-    return a.paths[0] === "show" ? "show" : a.save ? "save" : "dry";
-  });
-  const firstSave = order.indexOf("save");
-  assert.ok(firstSave > order.indexOf("dry"), order.join(" → "));
-  assert.ok(order.indexOf("dry") > order.indexOf("show"), order.join(" → "));
-  assert.ok(order.lastIndexOf("show") > firstSave, order.join(" → "));
-});
 
 test("the shared per-skill checks pass", async () => {
   await checkSkill("submission-portal");

package/src/adapters/hotcrp/cassette/README.md

@@ -19,19 +19,19 @@ verbatim.
 | `post-ok.json`    | the same with the part and `content_file` named `paperlint_pdf`                                                                                           |  200 |
 
 To re-record: run the same four requests with `curl` against a HotCRP site where you have a
-submission and a token (`Authorization: bearer $HOTCRP_TOKEN`), always with `dry_run=1` on a `POST`,
+submission and a token (`Authorization: bearer $HOTCRP_TOKEN_<SITE>`), always with `dry_run=1` on a `POST`,
 save each body, then replace every identifying value with a fake of the same type before committing.
 These files ship in the npm package with the rest of `src/`, like the tests beside them.
 
 ## The deadlines pages
 
 `deadlines-<site>.html` are five live sites' `GET /deadlines` pages and one site that does not exist,
-recorded whole on 2026-10-05 (`curl`, no account): the page is public and carries no personal data,
+recorded whole on 2026-10-05 (`curl`, no account; `deadlines-msr2027.html` re-recorded 2026-10-19 18:27 UTC, when the portal had moved both its deadlines — #235): the page is public and carries no personal data,
 so nothing is replaced. `deadlines.test.ts` parses each through the adapter's real parser; the
 expected values were read off the pages' text by hand first. `/api/deadlines` on the same sites
 answers 401 «Missing credentials», so the HTML page is the source.
-`scripts/refresh-deadlines.test.ts` replays the MSR and AIDC pages through the scheduled refresh of
-the presets' `deadlines` (`.github/workflows/deadlines.yml`). Re-read live through the adapter at
+`scripts/refresh-deadlines/main.test.ts` replays the MSR page through `npm run refresh-deadlines`, the
+scheduled refresh of the presets' `deadlines` (`.github/workflows/deadlines.yml`). Re-read live through the adapter at
 14:38 UTC the same day, both pages differed from these files only in the script nonces and `now`.
 
 | file                      | site                  | HTTP | what it shows                                                      |

package/src/adapters/hotcrp/cassette/deadlines-msr2027.html

@@ -5,7 +5,7 @@
 <meta name="google" content="notranslate">
 <meta name="theme-color" content="#ffb7ca">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<link href="https://static.hotcrp.com/@1790985506/stylesheets/style.css" rel="stylesheet">
+<link href="https://static.hotcrp.com/@1792005925/stylesheets/style.css" rel="stylesheet">
 <link href="https://static.hotcrp.com/@1786633883/stylesheets/mobile.css" media="screen and (max-width: 1100px)" rel="stylesheet">
 <link href="https://static.hotcrp.com/@1788721683/stylesheets/plugin.css" rel="stylesheet">
 <link rel="icon" type="image/svg+xml" href="https://static.hotcrp.com/images/review48.svg">
@@ -14,12 +14,12 @@
 <body id="m-deadlines" data-upload-limit="104857600" data-document-max-size="600000000"><div id="p-page" class="need-banner-offset"><header id="p-header"><hr class="c"><div id="h-site" class="header-site-page"><a class="q" href="/"><span class="header-site-name">MSR 2027</span></a></div><div id="h-right"></div><div id="h-page"><h1 id="h-title">Deadlines</h1></div><nav id="p-quicklinks" aria-label="Submission search"></nav><hr class="c">
 <div id="h-messages" class="want-mx-auto"></div></header>
 <main id="p-body">
-<h3>Upcoming</h3><dl class="bsp"><dt><strong>Submission deadline</strong>: <span class="need-usertime" data-ts="1792468800">Tuesday Oct 20, 2026, 12 AM EDT</span></dt><dd>Submissions must be completed by this deadline to be reviewed.</dd>
-<dt><strong>Resubmission deadline</strong>: <span class="need-usertime" data-ts="1792728000">Friday Oct 23, 2026, 12 AM EDT</span></dt><dd>Completed submissions may be updated until this deadline.</dd></dl>
-<hr class="c"></main></div><footer id="p-footer" class="need-banner-offset banner-bottom"><a class="noq" href="https://hotcrp.com/">HotCRP</a><!-- Version 3.4 --></footer><!--[if lt IE 9]><script nonce="8XgRxNPYP5XebPvVSL6MyA==" src="https://static.hotcrp.com/@1749780400/scripts/jquery-1.12.4.min.js" crossorigin="anonymous" integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ="></script><![endif]-->
-<![if !IE|gte IE 9]><script nonce="8XgRxNPYP5XebPvVSL6MyA==" src="https://static.hotcrp.com/@1749780400/scripts/jquery-3.7.1.min.js" crossorigin="anonymous" integrity="sha256-/JqT3SQfawRcv/BIHPThkBvs0OEvtFFmqPF/lYI/Cxo="></script><![endif]>
-<script nonce="8XgRxNPYP5XebPvVSL6MyA==">window.siteinfo={"site_relative":"","base":"\/","suffix":"","assets":"https:\/\/static.hotcrp.com\/","icons_url":"@1787797517\/images\/icons.svg","cookie_params":"; Domain=.hotcrp.com; Secure; SameSite=Lax","postvalue":".empty","download_prefix":"msr2027-","snouns":["submission","submissions","Submission","Submissions"],"user":[]}</script><script nonce="8XgRxNPYP5XebPvVSL6MyA==" src="https://static.hotcrp.com/@1790985505/scripts/script.js" crossorigin="anonymous"></script>
-<script nonce="8XgRxNPYP5XebPvVSL6MyA==" src="https://static.hotcrp.com/@1777496734/scripts/markdown-it.min.js" crossorigin="anonymous"></script>
-<script nonce="8XgRxNPYP5XebPvVSL6MyA==" src="https://static.hotcrp.com/@1787955704/scripts/plugin.js" crossorigin="anonymous"></script>
-<script nonce="8XgRxNPYP5XebPvVSL6MyA==">hotcrp.onload.time(240,0);hotcrp.init_deadlines({"now":1791194488.329003,"email":null,"sub":{"open":true,"sub":1792468800,"blind":true}})</script></body>
+<h3>Upcoming</h3><dl class="bsp"><dt><strong>Submission deadline</strong>: <span class="need-usertime" data-ts="1792583999">Wednesday Oct 21, 2026, 7:59:59 AM EDT</span></dt><dd>Submissions must be completed by this deadline to be reviewed.</dd>
+<dt><strong>Resubmission deadline</strong>: <span class="need-usertime" data-ts="1792843199">Saturday Oct 24, 2026, 7:59:59 AM EDT</span></dt><dd>Completed submissions may be updated until this deadline.</dd></dl>
+<hr class="c"></main></div><footer id="p-footer" class="need-banner-offset banner-bottom"><a class="noq" href="https://hotcrp.com/">HotCRP</a><!-- Version 3.4 --></footer><!--[if lt IE 9]><script nonce="ecy+ctcGvxeRVeuZdgbMbA==" src="https://static.hotcrp.com/@1749780400/scripts/jquery-1.12.4.min.js" crossorigin="anonymous" integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ="></script><![endif]-->
+<![if !IE|gte IE 9]><script nonce="ecy+ctcGvxeRVeuZdgbMbA==" src="https://static.hotcrp.com/@1749780400/scripts/jquery-3.7.1.min.js" crossorigin="anonymous" integrity="sha256-/JqT3SQfawRcv/BIHPThkBvs0OEvtFFmqPF/lYI/Cxo="></script><![endif]>
+<script nonce="ecy+ctcGvxeRVeuZdgbMbA==">window.siteinfo={"site_relative":"","base":"\/","suffix":"","assets":"https:\/\/static.hotcrp.com\/","icons_url":"@1787797517\/images\/icons.svg","cookie_params":"; Domain=.hotcrp.com; Secure; SameSite=Lax","postvalue":".empty","download_prefix":"msr2027-","snouns":["submission","submissions","Submission","Submissions"],"user":[]}</script><script nonce="ecy+ctcGvxeRVeuZdgbMbA==" src="https://static.hotcrp.com/@1792005925/scripts/script.js" crossorigin="anonymous"></script>
+<script nonce="ecy+ctcGvxeRVeuZdgbMbA==" src="https://static.hotcrp.com/@1777496734/scripts/markdown-it.min.js" crossorigin="anonymous"></script>
+<script nonce="ecy+ctcGvxeRVeuZdgbMbA==" src="https://static.hotcrp.com/@1787955704/scripts/plugin.js" crossorigin="anonymous"></script>
+<script nonce="ecy+ctcGvxeRVeuZdgbMbA==">hotcrp.onload.time(240,0);hotcrp.init_deadlines({"now":1792434476.311902,"email":null,"sub":{"open":true,"sub":1792583999,"blind":true}})</script></body>
 </html>

package/src/adapters/hotcrp/deadlines.io.test.ts

@@ -61,8 +61,8 @@ test("GET <site>/deadlines, no credential; the page parses to the venue's deadli
   assert.deepEqual(
     r.value.deadlines.map((d) => [d.what, d.at]),
     [
-      ["submission", "2026-10-20T04:00:00Z"],
-      ["resubmission", "2026-10-23T04:00:00Z"],
+      ["submission", "2026-10-21T11:59:59Z"],
+      ["resubmission", "2026-10-24T11:59:59Z"],
     ],
   );
 });

package/src/adapters/hotcrp/deadlines.test.ts

@@ -23,19 +23,19 @@ const read = (site: Site, status = 200) => {
 describe("parseDeadlinesPage", () => {
   it("a conference with a resubmission deadline: the list carries it, the status object does not", () => {
     expect(read("msr2027")).toEqual({
-      now: 1791194488.329003,
+      now: 1792434476.311902,
       open: true,
       blind: true,
       deadlines: [
         {
           what: "submission",
           label: "Submission deadline",
-          at: "2026-10-20T04:00:00Z",
+          at: "2026-10-21T11:59:59Z",
         },
         {
           what: "resubmission",
           label: "Resubmission deadline",
-          at: "2026-10-23T04:00:00Z",
+          at: "2026-10-24T11:59:59Z",
         },
       ],
     });

package/src/adapters/hotcrp/index.ts

@@ -1,13 +1,25 @@
 /**
- * HotCRP, as the `SubmissionPortal` port: its REST API read and written over `fetch`, its answers
- * parsed here. Everything that changes if HotCRP's API does lives in this folder.
+ * HotCRP, as the `PortalSite` and `SubmissionPortal` ports: its token variables and token page, its
+ * REST API read and written over `fetch`, its answers parsed here. Everything that changes if HotCRP's API does lives in this folder.
  */
 export {
   CONTENT_FIELD,
   changeObject,
+  createObject,
   hotcrpPortal,
   type HotcrpOptions,
 } from "./portal.io.ts";
-export { parseShow, parseUpdate, sha256OfHash } from "./response.ts";
+export {
+  parseCreate,
+  parseShow,
+  parseUpdate,
+  sha256OfHash,
+} from "./response.ts";
 export { hotcrpDeadlines } from "./deadlines.io.ts";
+export { hotcrpSite } from "./site.ts";
+export {
+  SITE_LESS_VARIABLE,
+  VARIABLE_PATTERN,
+  tokenVariable,
+} from "./token.ts";
 export { parseDeadlinesPage, whatOf } from "./deadlines.ts";

package/src/adapters/hotcrp/portal.io.ts

@@ -9,17 +9,24 @@
  * (the documented form: `curl -F "json=<data.json" -F paper.pdf=@paper.pdf SITEURL/api/paper`).
  * Without `save` the request carries `dry_run=1`: HotCRP checks the change and keeps nothing.
  *
+ * Create: the same `POST`, with `p=new` and `"pid": "new"` in the object — «Setting `p=new` will
+ * create a new submission; the response will contain the chosen submission ID»
+ * (`devel/apidoc/submissions.md`, `post /paper`, in kohler/hotcrp). The object carries the title, the
+ * abstract, the authors and the PDF; nothing else is sent.
+ *
  * 🔴 THE TOKEN goes in the `Authorization` header and nowhere else: not into a URL, a message, or an
  * error. A failure is described by HTTP status, HotCRP's own messages, or the network error's text.
  */
 import { messageOf } from "../../domain/text.ts";
 import { err, type Result } from "../../domain/result.ts";
 import type {
+  Author,
+  NewSubmission,
   PortalFailure,
   SubmissionChange,
 } from "../../domain/submission.ts";
 import type { SubmissionPortal } from "../../ports/submission-portal.ts";
-import { parseShow, parseUpdate } from "./response.ts";
+import { parseCreate, parseShow, parseUpdate } from "./response.ts";
 
 /**
  * The form field the PDF travels in, and the name the `json` object's `content_file` refers to it
@@ -87,14 +94,38 @@ export function changeObject(
   };
 }
 
-function formOf(id: number, c: SubmissionChange): Readonly<FormData> {
+/** An author as HotCRP's submission object spells one (`Author::make_keyed` reads `name`). */
+const authorObject = (a: Author): Readonly<Record<string, string>> => ({
+  name: a.name,
+  email: a.email,
+  ...(a.affiliation === null ? {} : { affiliation: a.affiliation }),
+});
+
+/** The submission object a creation sends: title, abstract, authors and the PDF's field. */
+export function createObject(
+  p: NewSubmission,
+): Readonly<Record<string, unknown>> {
+  return {
+    object: "paper",
+    pid: "new",
+    title: p.title,
+    abstract: p.abstract,
+    authors: p.authors.map(authorObject),
+    submission: { content_file: CONTENT_FIELD },
+  };
+}
+
+function formOf(
+  object: Readonly<Record<string, unknown>>,
+  pdf: { readonly name: string; readonly bytes: Uint8Array } | null,
+): Readonly<FormData> {
   const form = new FormData();
-  form.append("json", JSON.stringify(changeObject(id, c)));
-  if (c.pdf !== null)
+  form.append("json", JSON.stringify(object));
+  if (pdf !== null)
     form.append(
       CONTENT_FIELD,
-      new Blob([new Uint8Array(c.pdf.bytes)], { type: "application/pdf" }),
-      c.pdf.name,
+      new Blob([new Uint8Array(pdf.bytes)], { type: "application/pdf" }),
+      pdf.name,
     );
   return form;
 }
@@ -104,6 +135,23 @@ const endpoint = (
   params: Readonly<Record<string, string>>,
 ): string => `${base}/api/paper?${new URLSearchParams(params).toString()}`;
 
+/** What one `POST /api/paper` sends: which submission, its object, the PDF, and whether to save. */
+interface Post {
+  readonly p: string;
+  readonly object: Readonly<Record<string, unknown>>;
+  readonly pdf: { readonly name: string; readonly bytes: Uint8Array } | null;
+  readonly save: boolean;
+}
+
+/** A `POST /api/paper` carrying the object and the PDF, a dry run unless saving. */
+const post = (o: HotcrpOptions, w: Post): Promise<Answer> =>
+  call(
+    endpoint(o.url, { p: w.p, ...(w.save ? {} : { dry_run: "1" }) }),
+    { method: "POST", body: formOf(w.object, w.pdf) },
+    o.token,
+    WRITE_TIMEOUT_MS,
+  );
+
 /** HotCRP at `o.url`, read and changed with `o.token`. */
 export function hotcrpPortal(o: HotcrpOptions): SubmissionPortal {
   return {
@@ -113,18 +161,14 @@ export function hotcrpPortal(o: HotcrpOptions): SubmissionPortal {
       return a.ok ? parseShow(a.value.status, a.value.body) : a;
     },
     async update(id, change, { save }) {
-      const url = endpoint(o.url, {
-        p: String(id),
-        ...(save ? {} : { dry_run: "1" }),
-      });
-      const body = formOf(id, change);
-      const a = await call(
-        url,
-        { method: "POST", body },
-        o.token,
-        WRITE_TIMEOUT_MS,
-      );
+      const object = changeObject(id, change);
+      const a = await post(o, { p: String(id), object, pdf: change.pdf, save });
       return a.ok ? parseUpdate(a.value.status, a.value.body) : a;
     },
+    async create(paper, { save }) {
+      const object = createObject(paper);
+      const a = await post(o, { p: "new", object, pdf: paper.pdf, save });
+      return a.ok ? parseCreate(a.value.status, a.value.body) : a;
+    },
   };
 }

package/src/adapters/hotcrp/portal.test.ts

@@ -14,11 +14,16 @@ import {
 import { afterAll, beforeAll, test } from "vitest";
 import { fieldOf } from "../../domain/record.ts";
 import { sha256Hex } from "../../domain/sha256.ts";
-import type { SubmissionChange } from "../../domain/submission.ts";
+import type {
+  NewSubmission,
+  SubmissionChange,
+} from "../../domain/submission.ts";
 import {
   CONTENT_FIELD,
   changeObject,
+  createObject,
   hotcrpPortal,
+  parseCreate,
   parseShow,
   parseUpdate,
   sha256OfHash,
@@ -342,6 +347,104 @@ test("update with save: no dry_run parameter at all", async () => {
   });
 });
 
+const NEW: NewSubmission = {
+  title: "Agents That Lie",
+  abstract: "One paragraph.",
+  authors: [
+    {
+      name: "Ada Lovelace",
+      email: "ada@example.org",
+      affiliation: "Analytical",
+    },
+    { name: "Bob", email: "bob@example.org", affiliation: null },
+  ],
+  pdf: { name: "paper.pdf", bytes: PDF },
+};
+
+test("create: a dry run by default — p=new, dry_run=1, title/abstract/authors and the PDF; no id", async () => {
+  // HotCRP's dry-run answer: `Paper_API_Status` sends `"pid": "new"` until a save chose one
+  // (src/api/api_paper.php, kohler/hotcrp 9a01097).
+  answer(200, {
+    ok: true,
+    valid: true,
+    change_list: ["new", "title", "abstract", "authors", "submission"],
+    pid: "new",
+    dry_run: true,
+    message_list: [],
+  });
+  const r = await portal().create(NEW, { save: false });
+  const s = last();
+  assert.equal(s.method, "POST");
+  assert.equal(s.url.pathname, "/api/paper");
+  assert.deepEqual(Object.fromEntries(s.url.searchParams), {
+    p: "new",
+    dry_run: "1",
+  });
+  assert.equal(s.headers.authorization, `bearer ${TOKEN}`);
+  const parts = partsOf(s);
+  assert.deepEqual([...parts.keys()], ["json", CONTENT_FIELD]);
+  assert.deepEqual(JSON.parse(parts.get("json")?.body.toString("utf8") ?? ""), {
+    object: "paper",
+    pid: "new",
+    title: "Agents That Lie",
+    abstract: "One paragraph.",
+    authors: [
+      {
+        name: "Ada Lovelace",
+        email: "ada@example.org",
+        affiliation: "Analytical",
+      },
+      { name: "Bob", email: "bob@example.org" },
+    ],
+    submission: { content_file: CONTENT_FIELD },
+  });
+  assert.deepEqual(new Uint8Array(parts.get(CONTENT_FIELD)?.body ?? []), PDF);
+  assert.deepEqual(r, {
+    ok: true,
+    value: {
+      httpStatus: 200,
+      valid: true,
+      changes: ["new", "title", "abstract", "authors", "submission"],
+      messages: [],
+      dryRun: true,
+      id: null,
+    },
+  });
+});
+
+test("create with save: no dry_run, and the id HotCRP chose", async () => {
+  answer(200, { ok: true, valid: true, change_list: ["new"], pid: 42 });
+  const r = await portal().create(NEW, { save: true });
+  assert.deepEqual(Object.fromEntries(last().url.searchParams), { p: "new" });
+  assert.deepEqual(r.ok ? r.value.id : r, 42);
+});
+
+test("🔴 parseCreate: an id only for a valid, saved creation", () => {
+  assert.deepEqual(
+    [
+      parseCreate(200, { ok: false, valid: false, pid: 42 }),
+      parseCreate(200, { ok: true, valid: true, pid: "new", dry_run: true }),
+      parseCreate(200, { ok: true, valid: true, pid: "new" }),
+    ].map((r) => (r.ok ? r.value.id : r)),
+    [null, null, null],
+  );
+  assert.deepEqual(parseCreate(401, { ok: false, status_code: 401 }), {
+    ok: false,
+    error: { kind: "refused", httpStatus: 401, messages: [] },
+  });
+});
+
+test("createObject: an author without an affiliation sends none", () => {
+  assert.deepEqual(fieldOf(createObject(NEW), "authors"), [
+    {
+      name: "Ada Lovelace",
+      email: "ada@example.org",
+      affiliation: "Analytical",
+    },
+    { name: "Bob", email: "bob@example.org" },
+  ]);
+});
+
 test("update: valid:false is an outcome with HotCRP's messages, at any HTTP status", async () => {
   answer(400, {
     ok: false,
@@ -441,6 +544,7 @@ test("a portal that does not answer is unreachable, with the network's words", a
   for (const r of [
     await down.show(7),
     await down.update(7, CHANGE, { save: false }),
+    await down.create(NEW, { save: false }),
   ]) {
     assert.equal(!r.ok && r.error.kind, "unreachable");
     assert.ok(!r.ok && r.error.kind === "unreachable" && r.error.detail !== "");

package/src/adapters/hotcrp/response.ts

@@ -11,6 +11,7 @@ import { z } from "zod";
 import { err, ok, type Result } from "../../domain/result.ts";
 import { parseSha256, type Sha256 } from "../../domain/sha256.ts";
 import type {
+  CreateOutcome,
   PortalDocument,
   PortalFailure,
   PortalMessage,
@@ -55,6 +56,8 @@ const UpdateBody = z.object({
   change_list: z.array(z.string()).optional(),
   message_list: Messages,
   dry_run: z.boolean().optional(),
+  // The submission's id: a number once saved, `"new"` for a creation that was not.
+  pid: z.union([z.number(), z.string()]).optional(),
 });
 
 const Envelope = z.object({ message_list: Messages });
@@ -179,3 +182,21 @@ export function parseUpdate(
     dryRun: b.data.dry_run ?? false,
   });
 }
+
+/**
+ * `POST /api/paper?p=new` → the outcome, with the id HotCRP chose: its `pid`, a number only when the
+ * submission was saved (a dry run answers `"pid": "new"`).
+ */
+export function parseCreate(
+  httpStatus: number,
+  body: unknown,
+): Result<CreateOutcome, PortalFailure> {
+  const u = parseUpdate(httpStatus, body);
+  if (!u.ok) return u;
+  const pid = UpdateBody.safeParse(body).data?.pid;
+  const saved = u.value.valid && !u.value.dryRun;
+  return ok({
+    ...u.value,
+    id: saved && typeof pid === "number" ? pid : null,
+  });
+}