feat: a project is made before it is filled, so a typo cannot invent one

`upload` took two flags — --name to make a project, --to to add to one — which
meant a child's second upload was typed differently from their first and learned
so by failing. Those collapsed into one flag that found the project or made it.
The cost was that a mistyped --project Snak stopped being a question and became
a second project called "Snak" holding one file.

So the flag stays one flag and stops making anything. --project names a project
that has to be there already, and `projects create` is where one begins. Two
commands for a first upload, on purpose: the moment a name is invented is now a
moment somebody chose, rather than a side effect of putting a file somewhere.

The API had no way to make an empty project. Create refuses a request carrying
neither files nor a link, because at a screen that means the files were never
attached — relaxing it would have swallowed that mistake, so the new way through
is opt-in. Only a caller that sends AllowEmpty gets one, and the panel a child
uploads from sends nothing of the sort and still hears about an empty selection.

`projects create` refuses a name the locker already has. The API would take a
second "Snake" without complaint, and that is precisely the ambiguity `upload`
cannot resolve afterwards — better said while it is still one keystroke to pick
another name. Upload's own guard is unchanged: a reference matching two projects
is refused, listing both, and the id says which.

With upload never creating, half of performUpload was unreachable and the dry
run still carried a line about "a new project" that could no longer happen. Both
are gone, and UploadTarget and the outcome's `added` with them — one endpoint,
no branch. That also bought a plainer sentence for a pasted link, which used to
report "Added 0 files" about something that had plainly worked.

--to means what it always meant. --name is kept as a hidden spelling of
--project, so a script written against the published version is told which
command makes a project rather than that the flag does not exist.

Author: JKamsker

README.md

@@ -20,7 +20,8 @@ Then:
 
 ```bash
 locker auth login
-locker upload ./my-game --name "Snake"
+locker projects create "Snake"
+locker upload ./my-game --project Snake
 ```
 
 It is not on the npm registry yet, so `npx @coderdojo-linz/locker` does not work
@@ -33,41 +34,53 @@ From a clone, it runs straight out of the tree:
 npm ci && npm run build && node dist/index.js --help
 ```
 
-## The four things you will actually do
+## The things you will actually do
 
 ```bash
-locker auth login                 # enter the code from your card
-locker status                     # what is in your locker, and how full it is
-locker upload ./my-project        # save work into a new project
-locker download Snake             # get work back out
+locker auth login                        # enter the code from your card
+locker status                            # what is in your locker, and how full it is
+locker projects create Snake             # start a project
+locker upload ./my-game --project Snake  # put work into it
+locker download Snake                    # get work back out
 ```
 
 `locker --help` lists everything. `locker <command> --help` explains one thing.
 
 ## Uploading
 
-Always say where the files go — `--name` makes a new project, `--to` adds to one
-that is already there. Neither is guessed, because a project name is not unique
-and a coincidence is a poor way to decide where your work lands.
-
-A folder keeps its shape, so this arrives as a `game` folder with `img/` still
-inside it:
+A project is made first, and then uploaded into. Two steps, one flag each time:
 
 ```bash
-locker upload ./game --name "Snake"
+locker projects create "Snake"
+locker upload ./game --project Snake
 ```
 
+`--project` takes a name or an id and never invents one. A name you have not
+made yet is refused, naming the command that would make it — so a mistyped
+`--project Snak` is a question rather than a second project called "Snak" with
+one file in it. Every upload after the first is typed exactly like this one:
+
 ```bash
-locker upload extra-level.py --to Snake
+locker upload extra-level.py --project Snake
 ```
 
+A folder keeps its shape, so `./game` arrives as a `game` folder with `img/`
+still inside it.
+
+One thing is still never guessed for you: a name matching two projects is
+refused, listing both, because nothing stops you calling two of them "Game". Use
+the id from `locker projects list` to say which.
+
 Look before you leap. `--dry-run` lists every file, the total, and how much room
 is left, without uploading anything:
 
 ```bash
-locker upload ./game --name "Snake" --dry-run
+locker upload ./game --project "Snake" --dry-run
 ```
 
+`--name` and `--to` are still accepted and both mean `--project`. `--to` behaves
+exactly as it always did; `--name` no longer makes a project, and says so.
+
 `.git`, `node_modules` and similar are skipped, and the CLI tells you it skipped
 them. `--all` includes them.
 

src/commands/projectsCreate.ts

@@ -0,0 +1,79 @@
+import { requirePositional } from '../runtime/args.js';
+import type { ProjectDetails } from '../api/types.js';
+import type { Command, CommandResult } from '../runtime/command.js';
+import { usageError } from '../runtime/exit.js';
+import { shortId } from '../runtime/format.js';
+import { fetchLocker, findProject } from '../domain/locker.js';
+
+const MAXIMUM_NAME_LENGTH = 120;
+
+/**
+ * Makes a project with nothing in it yet.
+ *
+ * `upload` only ever adds to a project that is already there, so this is where
+ * one begins. Two commands rather than one for a first upload, on purpose: it
+ * means a mistyped `--project` is a refusal rather than a second project named
+ * after the typo, and the moment a name is invented is a moment somebody chose
+ * rather than a side effect of putting a file somewhere.
+ */
+export const projectsCreateCommand: Command = {
+  path: ['projects', 'create'],
+  summary: 'Make an empty project to upload into',
+  description:
+    'Makes a project with nothing in it. Put files in it with\n' +
+    '"locker upload <paths...> --project <name>".',
+  usage: 'locker projects create <name>',
+  examples: [
+    'locker projects create "Snake"',
+    'locker projects create "Snake" && locker upload ./game --project Snake',
+  ],
+  async run(context, input): Promise<CommandResult> {
+    const code = context.requireCode();
+    const name = requirePositional(
+      input,
+      0,
+      'a name',
+      'locker projects create "My project"',
+    ).trim();
+
+    if (name.length === 0 || name.length > MAXIMUM_NAME_LENGTH) {
+      throw usageError(`A project name is between 1 and ${MAXIMUM_NAME_LENGTH} characters.`);
+    }
+
+    // Names are not unique and the API would take a second "Snake" without
+    // complaint, which is precisely the ambiguity `upload` then cannot resolve.
+    // Said here, where it is still one keystroke to pick another name.
+    const locker = await fetchLocker(context);
+    if (findProject(locker, name)) {
+      throw usageError(
+        `This locker already has a project called "${name}".`,
+        `locker upload ./files --project ${JSON.stringify(name)}`,
+      );
+    }
+
+    if (context.dryRun) {
+      return {
+        human: `Would make an empty project called "${name}".`,
+        data: { dryRun: true, name },
+      };
+    }
+
+    const project = await context.api.request<ProjectDetails>(
+      `/api/lockers/${encodeURIComponent(code)}/projects`,
+      {
+        method: 'POST',
+        // Said outright: the API refuses a project with nothing in it unless the
+        // caller asked for one, so that a screen which forgot to attach the
+        // files still hears about it.
+        body: { name, link: null, ticket: null, allowEmpty: true },
+        notFound: { kind: 'credential' },
+      },
+    );
+
+    context.reporter.success(`Made "${project.name}" — empty for now.`);
+    return {
+      human: `${shortId(project.id)}  ${project.name}`,
+      data: project,
+    };
+  },
+};

src/commands/registry.ts

@@ -11,6 +11,7 @@ import { filesDeleteCommand } from './filesDelete.js';
 import { filesListCommand } from './filesList.js';
 import { filesRenameCommand } from './filesRename.js';
 import { filesReplaceCommand } from './filesReplace.js';
+import { projectsCreateCommand } from './projectsCreate.js';
 import { projectsDeleteCommand } from './projectsDelete.js';
 import { projectsListCommand } from './projectsList.js';
 import { projectsRenameCommand } from './projectsRename.js';
@@ -40,6 +41,7 @@ export const COMMANDS: Command[] = [
   authLogoutCommand,
   authStatusCommand,
 
+  projectsCreateCommand,
   projectsListCommand,
   projectsShowCommand,
   projectsRenameCommand,
@@ -66,7 +68,8 @@ export const COMMANDS: Command[] = [
 export const COMMON_TASKS: { command: string; blurb: string }[] = [
   { command: 'locker auth login', blurb: 'Enter the code from your card' },
   { command: 'locker status', blurb: 'See what is in your locker' },
-  { command: 'locker upload ./my-project', blurb: 'Save work into a new project' },
+  { command: 'locker projects create Snake', blurb: 'Start a project' },
+  { command: 'locker upload ./game --project Snake', blurb: 'Put work into it' },
   { command: 'locker download <project>', blurb: 'Get work back out' },
 ];