@pixelhop/dit 0.1.0 → 0.3.0

package/README.md

@@ -7,32 +7,102 @@ PR-ready Markdown, and later reads the humans' annotations as structured JSON.
 Node 22+. No runtime dependencies.
 
 ```bash
-npx @pixelhop/dit --help
-# or install it once
 npm install -g @pixelhop/dit
+dit login
+dit project create --name "Marketing site"
+dit upload --project marketing-site --review pr-1234 --file shot.png
 ```
 
-## Configuration
+`dit login` on its own prints a link. Open it, approve, and the CLI has its own key —
+nothing to copy, and no account needed beforehand. `--url` defaults to
+`https://diditthough.app` and the token is remembered, so neither is repeated.
 
-Two values, from flags or the environment:
+## Signing in
 
-| Flag            | Environment | Meaning                                                     |
-| --------------- | ----------- | ----------------------------------------------------------- |
-| `--url <url>`   | `DIT_URL`   | API base URL — `https://diditthough.app` for the hosted app |
-| `--token <tok>` | `DIT_TOKEN` | Agent token (`dit_…`), created per project in the web UI    |
+Sign in once; after that every command is just the command.
 
-Set `DIT_DEBUG=1` to print stack traces instead of one-line errors.
+```bash
+dit login
+```
+
+With no arguments this runs a browser approval. The CLI prints a link and a short code and
+waits; a person opens the link, signs in or signs up, and clicks approve. The CLI is then
+issued its own agent token scoped to that person's workspace. Nothing is ever copied
+between windows, and the person's session is discarded immediately — it is a courier for
+the approval, not the credential the agent keeps.
+
+You can still pass a token directly, which is what CI does:
 
 ```bash
-export DIT_URL=https://diditthough.app
-export DIT_TOKEN=dit_…
+dit login --token dit_…
 ```
 
-The token is scoped to one project and one workspace. Agents cannot create projects — a
-human makes the project and mints the token first.
+Either way the token is checked against the API before being stored — a token saved
+without checking turns one clear failure here into a puzzling one on the next upload — and
+written to `~/.config/dit/config.json` with `0600` permissions. `$XDG_CONFIG_HOME` is
+respected, and `DIT_CONFIG` overrides the path outright. `dit logout` removes it.
+
+### Where each value comes from
+
+`--url` defaults to the hosted service, so you only pass it to point at a local
+`wrangler dev`. Tokens are saved per URL, so signing in locally cannot quietly overwrite
+the production one.
+
+| Value | Resolution order                                                          |
+| ----- | ------------------------------------------------------------------------- |
+| URL   | `--url`, then `DIT_URL`, then `https://diditthough.app`                   |
+| Token | `--token`, then `DIT_TOKEN`, then whatever `dit login` saved for that URL |
+
+The saved token comes last on purpose: a one-off `--token`, or `DIT_TOKEN` in CI, wins
+without anyone having to sign out first. Set `DIT_DEBUG=1` to print stack traces instead
+of one-line errors.
 
 ## Commands
 
+### `dit login` and `dit logout`
+
+```bash
+dit login                                            # browser approval
+dit login --token dit_…                              # a token you already have
+dit login --token dit_… --url http://localhost:3000  # a local server
+dit logout
+```
+
+`login` also accepts the token from `DIT_TOKEN`, which keeps it out of your shell history.
+
+### Uploading with no account at all
+
+If nothing is signed in, `dit upload` does not fail. It creates a temporary workspace that
+nobody owns yet, uploads into that, and prints a claim link alongside the usual Markdown:
+
+```
+This workspace has not been claimed. Everything uploaded here is deleted in 5 days unless
+somebody claims it.
+Claim it: https://diditthough.app/claim/…
+```
+
+Pass that link on. Whoever follows it and signs in becomes the owner, and the workspace
+moves to the Free plan with everything in it intact — including evidence that has already
+stopped displaying, because the visible window is derived from the current plan rather than
+frozen at upload time. Unclaimed workspaces are small on purpose: one project, three
+reviews, media visible for five days and recoverable for seven more.
+
+Deployments can switch this off, in which case `dit upload` asks you to run `dit login`
+instead.
+
+### `dit project create`
+
+A project is where reviews live, one per repository or site. An agent can make its own,
+provided its token is workspace-scoped rather than pinned to a single project — a token
+tied to one project cannot create another, because widening your own reach is not
+something a credential should be able to do.
+
+```bash
+dit project create --name "Marketing site"
+```
+
+It prints the slug to pass to `--project` afterwards.
+
 ### `dit upload`
 
 Uploads one or more files to a review, creating the review if it does not exist yet.

package/dist/args.d.ts

@@ -41,13 +41,24 @@ export type CliArgs = ({
 } & RuntimeFlags & JsonFlag) | ({
     command: "markdown";
     review: string;
-} & RuntimeFlags) | {
+} & RuntimeFlags) | ({
+    command: "project:create";
+    name: string;
+} & RuntimeFlags & JsonFlag) | ({
+    command: "login";
+} & RuntimeFlags) | ({
+    command: "logout";
+} & Pick<RuntimeFlags, "url">) | {
     command: "help";
     topic?: string;
 } | {
     command: "version";
 };
 export type FeedbackStatus = "open" | "addressed" | "resolved" | "all";
+/** The commands that talk to the API, so need a resolved URL and token. */
+export type ApiCommandArgs = Exclude<CliArgs, {
+    command: "help" | "version" | "login" | "logout";
+}>;
 export declare function parseCliArgs(argv: string[]): CliArgs;
 export declare function parseViewport(value: string): Viewport;
 export {};

package/dist/args.js

@@ -45,11 +45,25 @@ const commandOptions = {
         ...runtimeOptions,
         review: { type: "string" },
     },
+    "project:create": {
+        ...runtimeOptions,
+        name: { type: "string" },
+        json: { type: "boolean" },
+    },
+    login: runtimeOptions,
+    logout: {
+        url: { type: "string" },
+        help: { type: "boolean", short: "h" },
+    },
 };
 export function parseCliArgs(argv) {
-    const command = argv[0];
+    // `project create` is the only two-word command. Joining it into the same
+    // `project:create` key the rest of the table uses keeps one lookup rather than
+    // a special case threaded through everything below.
+    const argv_ = argv[0] === "project" && argv[1] ? [`project:${argv[1]}`, ...argv.slice(2)] : argv;
+    const command = argv_[0];
     if (!command || command === "help" || command === "--help" || command === "-h") {
-        return { command: "help", ...(argv[1] ? { topic: argv[1] } : {}) };
+        return { command: "help", ...(argv_[1] ? { topic: argv_[1] } : {}) };
     }
     if (command === "--version" || command === "-v" || command === "version") {
         return { command: "version" };
@@ -61,7 +75,7 @@ export function parseCliArgs(argv) {
     let values;
     try {
         ({ values } = parseArgs({
-            args: argv.slice(1),
+            args: argv_.slice(1),
             options: commandOptions[name],
             strict: true,
             allowPositionals: false,
@@ -123,6 +137,20 @@ export function parseCliArgs(argv) {
             ...runtime,
         };
     }
+    if (name === "project:create") {
+        return {
+            command: name,
+            name: required(values, "name", "project create"),
+            ...(values.json ? { json: true } : {}),
+            ...runtime,
+        };
+    }
+    if (name === "login") {
+        return { command: name, ...runtime };
+    }
+    if (name === "logout") {
+        return { command: name, ...(runtime.url ? { url: runtime.url } : {}) };
+    }
     if (name === "revision") {
         return {
             command: name,

package/dist/auth.d.ts

@@ -0,0 +1,12 @@
+import type { CliArgs } from "./args.js";
+import { ApiClient, type ApiClientOptions } from "./client.js";
+import { type DeviceLoginDeps } from "./device.js";
+import type { Output } from "./output.js";
+type CreateClient = (options: ApiClientOptions) => ApiClient;
+export declare function login(args: Extract<CliArgs, {
+    command: "login";
+}>, environment: NodeJS.ProcessEnv, output: Output, createClient?: CreateClient, device?: DeviceLoginDeps): Promise<void>;
+export declare function logout(args: Extract<CliArgs, {
+    command: "logout";
+}>, environment: NodeJS.ProcessEnv, output: Output): Promise<void>;
+export {};

package/dist/auth.js

@@ -0,0 +1,35 @@
+import { getCatalog } from "./catalog.js";
+import { ApiClient } from "./client.js";
+import { clearStoredToken, configPath, writeStoredToken } from "./config.js";
+import { deviceLogin } from "./device.js";
+import { ApiError } from "./errors.js";
+import { resolveUrl } from "./runtime.js";
+export async function login(args, environment, output, createClient = (options) => new ApiClient(options), device = {}) {
+    const url = resolveUrl(args.url, environment);
+    // No token given? Ask a human to approve one in a browser instead. This is the
+    // whole point: an agent can get itself signed in without anyone copying a
+    // secret between two windows.
+    const token = args.token ?? environment.DIT_TOKEN ?? (await deviceLogin(url, output, device));
+    // Check the token before writing it. Storing a dead token turns one clear
+    // failure here into a confusing one on the next upload. A token that has just
+    // come back from the device flow is checked too — it costs one request, and it
+    // means "signed in" is never printed over something that does not work.
+    try {
+        await getCatalog(createClient({ url, token }));
+    }
+    catch (error) {
+        if (error instanceof ApiError && (error.status === 401 || error.status === 403)) {
+            throw new ApiError(`That token was rejected by ${url}`, error.status, error.code);
+        }
+        throw error;
+    }
+    const path = await writeStoredToken(url, token, environment);
+    output.out(`Signed in to ${url}. Token saved to ${path}.\n`);
+}
+export async function logout(args, environment, output) {
+    const url = resolveUrl(args.url, environment);
+    const removed = await clearStoredToken(url, environment);
+    output.out(removed
+        ? `Signed out of ${url}.\n`
+        : `No saved token for ${url} in ${configPath(environment)}.\n`);
+}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+/** The hosted service. Overridable, but nobody self-hosts this yet. */
+export declare const DEFAULT_URL = "https://diditthough.app";
+/**
+ * Tokens are stored per base URL rather than as one global value, so signing in
+ * against a local `wrangler dev` cannot silently overwrite the production token
+ * an agent is relying on.
+ */
+export declare function configPath(environment: NodeJS.ProcessEnv): string;
+export declare function readStoredToken(url: string, environment: NodeJS.ProcessEnv): Promise<string | undefined>;
+export declare function writeStoredToken(url: string, token: string, environment: NodeJS.ProcessEnv): Promise<string>;
+/** Resolves to false when there was nothing stored for that URL. */
+export declare function clearStoredToken(url: string, environment: NodeJS.ProcessEnv): Promise<boolean>;

package/dist/config.js

@@ -0,0 +1,94 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { CliError } from "./errors.js";
+/** The hosted service. Overridable, but nobody self-hosts this yet. */
+export const DEFAULT_URL = "https://diditthough.app";
+/**
+ * Tokens are stored per base URL rather than as one global value, so signing in
+ * against a local `wrangler dev` cannot silently overwrite the production token
+ * an agent is relying on.
+ */
+export function configPath(environment) {
+    const override = environment.DIT_CONFIG?.trim();
+    if (override)
+        return override;
+    const base = environment.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+    return join(base, "dit", "config.json");
+}
+export async function readStoredToken(url, environment) {
+    const config = await readConfig(configPath(environment));
+    return config?.hosts[url]?.token;
+}
+export async function writeStoredToken(url, token, environment) {
+    const path = configPath(environment);
+    const config = (await readConfig(path)) ?? { version: 1, hosts: {} };
+    config.hosts[url] = { token };
+    await writeConfig(path, config);
+    return path;
+}
+/** Resolves to false when there was nothing stored for that URL. */
+export async function clearStoredToken(url, environment) {
+    const path = configPath(environment);
+    const config = await readConfig(path);
+    if (!config?.hosts[url])
+        return false;
+    delete config.hosts[url];
+    if (Object.keys(config.hosts).length === 0) {
+        await rm(path, { force: true });
+    }
+    else {
+        await writeConfig(path, config);
+    }
+    return true;
+}
+async function readConfig(path) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw new CliError(`Could not read ${path}: ${messageOf(error)}`, 1);
+    }
+    // A corrupt credential file is worth saying out loud. Falling back to "not
+    // signed in" would send someone hunting for a token that is right there.
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new CliError(`${path} is not valid JSON; delete it and run \`dit login\` again`, 1);
+    }
+    if (!isStoredConfig(parsed)) {
+        throw new CliError(`${path} is not a dit config; delete it and run \`dit login\` again`, 1);
+    }
+    return parsed;
+}
+async function writeConfig(path, config) {
+    // 0700/0600, and written through a temp file so an interrupted write cannot
+    // leave a half-JSON credential store behind.
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, path);
+}
+function isStoredConfig(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    if (candidate.version !== 1)
+        return false;
+    if (typeof candidate.hosts !== "object" || candidate.hosts === null)
+        return false;
+    return Object.values(candidate.hosts).every((host) => typeof host === "object" &&
+        host !== null &&
+        typeof host.token === "string");
+}
+function isMissing(error) {
+    return error?.code === "ENOENT";
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/device.d.ts

@@ -0,0 +1,25 @@
+import type { Output } from "./output.js";
+export type DeviceLoginDeps = {
+    fetch?: typeof fetch;
+    sleep?: (milliseconds: number) => Promise<void>;
+    now?: () => number;
+};
+export declare function deviceLogin(url: string, output: Output, deps?: DeviceLoginDeps): Promise<string>;
+export type Bootstrapped = {
+    token: string;
+    project: {
+        slug: string;
+    };
+    claimUrl: string;
+    warning: string;
+};
+/**
+ * Make somewhere to upload to for an agent with no credentials at all.
+ *
+ * This is what lets an agent show its human the product rather than describe it:
+ * it uploads the evidence first and hands over a link, and the human claims the
+ * result if they want to keep it. The warning and the claim URL are returned by
+ * the server rather than composed here, so the retention number a person reads
+ * always comes from the plan catalogue and cannot drift.
+ */
+export declare function bootstrapUnclaimed(url: string, projectName: string, doFetch?: typeof fetch): Promise<Bootstrapped>;

package/dist/device.js

@@ -0,0 +1,160 @@
+import { ApiError, CliError } from "./errors.js";
+/**
+ * Signing in without a token to paste.
+ *
+ * The CLI asks the server for a pair of codes, shows the person a URL and a
+ * short code, and polls until they have approved it in a browser. What comes
+ * back is a *session* token, which is not what an agent should hold: it belongs
+ * to the person, expires on their schedule, and carries their full authority.
+ * So the last step trades it immediately for a workspace-scoped `dit_` agent
+ * token and forgets the session. The session is a courier.
+ *
+ * The shape of the exchange is OAuth 2.0 device authorization (RFC 8628), which
+ * is the same flow `gh auth login` uses, so the polling error codes below are
+ * that specification's rather than this product's.
+ */
+const CLIENT_ID = "dit-cli";
+const GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/**
+ * Every capability an agent needs to do the whole loop.
+ *
+ * `project:create` is in here because `dit project create` is the very next
+ * thing an agent runs after signing in, and a token without it gets a 403 on
+ * the step the documentation tells it to take.
+ */
+const AGENT_CAPABILITIES = [
+    "artifact:write",
+    "artifact:read",
+    "feedback:read",
+    "thread:reply",
+    "project:create",
+];
+export async function deviceLogin(url, output, deps = {}) {
+    const doFetch = deps.fetch ?? globalThis.fetch;
+    const sleep = deps.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    const now = deps.now ?? (() => Date.now());
+    const start = await requestCode(url, doFetch);
+    const link = start.verification_uri_complete ?? start.verification_uri;
+    output.out(`To finish signing in, open this and approve:\n\n  ${link}\n\n` +
+        `If it asks for a code, it is: ${start.user_code}\n\nWaiting…\n`);
+    const accessToken = await poll(url, start, { doFetch, sleep, now });
+    return exchangeForAgentToken(url, accessToken, doFetch);
+}
+async function requestCode(url, doFetch) {
+    const response = await doFetch(`${url}/api/auth/device/code`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ client_id: CLIENT_ID }),
+    });
+    if (!response.ok) {
+        throw new ApiError(`Could not start sign-in at ${url} (HTTP ${response.status})`, response.status);
+    }
+    return (await response.json());
+}
+async function poll(url, start, runtime) {
+    // The server states how often it wants to be asked and how long the code is
+    // good for. Both are honoured rather than guessed: polling faster than asked
+    // earns a `slow_down`, and polling past the expiry just annoys the server.
+    let intervalMs = (start.interval ?? 5) * 1000;
+    const deadline = runtime.now() + start.expires_in * 1000;
+    while (runtime.now() < deadline) {
+        await runtime.sleep(intervalMs);
+        const response = await runtime.doFetch(`${url}/api/auth/device/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                grant_type: GRANT_TYPE,
+                device_code: start.device_code,
+                client_id: CLIENT_ID,
+            }),
+        });
+        const payload = (await response.json().catch(() => ({})));
+        if (payload.access_token)
+            return payload.access_token;
+        switch (payload.error) {
+            case "authorization_pending":
+                break;
+            case "slow_down":
+                intervalMs += 5000;
+                break;
+            case "access_denied":
+                throw new CliError("Sign-in was denied in the browser.", 1);
+            case "expired_token":
+                throw new CliError("The sign-in code expired. Run `dit login` again.", 1);
+            default:
+                throw new ApiError(payload.error_description ?? payload.error ?? "Sign-in failed", response.status, payload.error);
+        }
+    }
+    throw new CliError("Timed out waiting for approval. Run `dit login` again.", 1);
+}
+/**
+ * Swap the person's session for an agent token belonging to their workspace.
+ *
+ * Deliberately workspace-scoped rather than tied to one project, because an
+ * agent that cannot create a project would still need a human to make one.
+ */
+async function exchangeForAgentToken(url, accessToken, doFetch) {
+    // Which workspace is asked for explicitly. The server refuses to guess when
+    // somebody belongs to more than one, and belonging to two is ordinary — it is
+    // what happens the moment they claim a workspace an agent made for them, so
+    // leaving this out breaks sign-in for exactly the people this feature creates.
+    const workspaceId = await currentWorkspaceId(url, accessToken, doFetch);
+    const response = await doFetch(`${url}/api/tokens`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${accessToken}`,
+        },
+        body: JSON.stringify({
+            name: agentTokenName(),
+            capabilities: [...AGENT_CAPABILITIES],
+            ...(workspaceId ? { workspaceId } : {}),
+        }),
+    });
+    if (!response.ok) {
+        const detail = (await response.json().catch(() => ({})));
+        throw new ApiError(detail.message ?? `Could not create an agent token (HTTP ${response.status})`, response.status);
+    }
+    const created = (await response.json());
+    if (!created.token) {
+        throw new ApiError("The server did not return an agent token", response.status);
+    }
+    return created.token;
+}
+/** The workspace `/api/me` reports for this person, if it will say. */
+async function currentWorkspaceId(url, accessToken, doFetch) {
+    const response = await doFetch(`${url}/api/me`, {
+        headers: { authorization: `Bearer ${accessToken}` },
+    });
+    if (!response.ok)
+        return undefined;
+    const payload = (await response.json().catch(() => ({})));
+    return payload.workspace?.id;
+}
+function agentTokenName() {
+    const host = process.env.HOSTNAME?.trim();
+    return host ? `dit CLI on ${host}` : "dit CLI";
+}
+/**
+ * Make somewhere to upload to for an agent with no credentials at all.
+ *
+ * This is what lets an agent show its human the product rather than describe it:
+ * it uploads the evidence first and hands over a link, and the human claims the
+ * result if they want to keep it. The warning and the claim URL are returned by
+ * the server rather than composed here, so the retention number a person reads
+ * always comes from the plan catalogue and cannot drift.
+ */
+export async function bootstrapUnclaimed(url, projectName, doFetch = globalThis.fetch) {
+    const response = await doFetch(`${url}/v1/bootstrap`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ project: projectName }),
+    });
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok || !payload.token) {
+        throw new ApiError(payload.data?.message ??
+            payload.message ??
+            `Could not create a workspace at ${url} (HTTP ${response.status})`, response.status);
+    }
+    return payload;
+}

package/dist/index.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { parseCliArgs } from "./args.js";
+import { login, logout } from "./auth.js";
 import { ApiClient } from "./client.js";
+import { DEFAULT_URL, writeStoredToken } from "./config.js";
+import { bootstrapUnclaimed } from "./device.js";
 import { CliError } from "./errors.js";
 import { executeCommand } from "./operations.js";
-import { resolveRuntime } from "./runtime.js";
+import { findToken, resolveRuntime, resolveUrl } from "./runtime.js";
 // Read from the manifest rather than a second copy of the number here: the
 // published version is set by the release tag, and a hard-coded constant is
 // guaranteed to start lying the first time one is cut. `../package.json` from
@@ -13,16 +16,19 @@ const { version: VERSION } = createRequire(import.meta.url)("../package.json");
 const HELP = `Usage: dit <command> [options]
 
 Commands:
+  login     [--token <token>] [--url <url>]  Sign in; opens a browser approval
+  logout    [--url <url>]
   upload    --project <slug|id> --review <ref|id> --file <path> [--file <path> ...]
   feedback  --review <ref|id> [--status open|addressed|resolved|all] [--json]
   reply     --thread <id> --message <text>
   address   --thread <id> [--message <text>]
   revision  --artifact <id> --file <path> [--json]
   markdown  --review <ref|id>
+  project create --name <name> [--json]
 
 Global options:
-  --url <url>      API base URL (or DIT_URL)
-  --token <token>  Agent token (or DIT_TOKEN)
+  --url <url>      API base URL (default ${DEFAULT_URL}, or DIT_URL)
+  --token <token>  Agent token (or DIT_TOKEN, or saved by \`dit login\`)
   -h, --help       Show help
   -v, --version    Show version
 
@@ -40,12 +46,37 @@ async function main() {
         process.stdout.write(`${VERSION}\n`);
         return;
     }
-    const runtime = resolveRuntime(args, process.env);
-    const client = new ApiClient(runtime);
-    await executeCommand(args, client, {
+    const output = {
         out: (value) => process.stdout.write(value),
         warn: (value) => process.stderr.write(`warning: ${value}\n`),
-    });
+    };
+    if (args.command === "login")
+        return login(args, process.env, output);
+    if (args.command === "logout")
+        return logout(args, process.env, output);
+    // An upload with no credentials anywhere does not fail. It creates a temporary
+    // workspace nobody owns yet, uploads into that, and hands back a link the
+    // human can claim — which is the whole point: an agent can show this product
+    // working on its human's own change before that human has an account.
+    if (args.command === "upload") {
+        const url = resolveUrl(args.url, process.env);
+        const existing = await findToken(args, url, process.env);
+        if (!existing) {
+            const created = await bootstrapUnclaimed(url, args.project);
+            // Saved, not held for the one command. Without this the agent cannot come
+            // back for the notes: `dit feedback` would find no token and bootstrap a
+            // second workspace, so the review it asked about would be one nobody had
+            // looked at. Saving it also means a later claim simply makes the token's
+            // workspace somebody's, and the agent carries on unaware.
+            await writeStoredToken(url, created.token, process.env);
+            output.out(`${created.warning}\nClaim it: ${created.claimUrl}\n\n`);
+            await executeCommand({ ...args, project: created.project.slug }, new ApiClient({ url, token: created.token }), output);
+            output.out(`\nThis review is not claimed yet. Claim it: ${created.claimUrl}\n`);
+            return;
+        }
+    }
+    const runtime = await resolveRuntime(args, process.env);
+    await executeCommand(args, new ApiClient(runtime), output);
 }
 main().catch((error) => {
     if (process.env.DIT_DEBUG === "1" && error instanceof Error && error.stack) {

package/dist/operations.d.ts

@@ -1,6 +1,4 @@
-import type { CliArgs } from "./args.js";
+import type { ApiCommandArgs } from "./args.js";
 import { ApiClient } from "./client.js";
 import { type Output } from "./output.js";
-export declare function executeCommand(args: Exclude<CliArgs, {
-    command: "help" | "version";
-}>, client: ApiClient, output: Output): Promise<void>;
+export declare function executeCommand(args: ApiCommandArgs, client: ApiClient, output: Output): Promise<void>;

package/dist/operations.js

@@ -29,6 +29,13 @@ export async function executeCommand(args, client, output) {
         output.out(`Addressed ${args.thread}.\n`);
         return;
     }
+    if (args.command === "project:create") {
+        const created = await client.requestJson("/v1/projects", { method: "POST", idempotent: true, body: { name: args.name } });
+        output.out(args.json
+            ? printJson(created)
+            : `Created project ${created.project.name}.\nUse --project ${created.project.slug} when uploading.\n`);
+        return;
+    }
     const review = resolveReview(await getCatalog(client), args.review);
     output.out(await client.requestText(`/v1/reviews/${encodeURIComponent(review.id)}/markdown?format=text`));
 }

package/dist/runtime.d.ts

@@ -1,9 +1,16 @@
-import type { CliArgs } from "./args.js";
-type RuntimeArgs = Exclude<CliArgs, {
-    command: "help" | "version";
-}>;
-export declare function resolveRuntime(args: RuntimeArgs, environment: NodeJS.ProcessEnv): {
+import type { ApiCommandArgs } from "./args.js";
+export declare function resolveUrl(url: string | undefined, environment: NodeJS.ProcessEnv): string;
+/**
+ * Flag, then environment, then whatever `dit login` saved. The saved token is
+ * last so a one-off `--token` or a CI `DIT_TOKEN` still wins without anyone
+ * having to sign out first.
+ */
+export declare function resolveRuntime(args: ApiCommandArgs, environment: NodeJS.ProcessEnv): Promise<{
     url: string;
     token: string;
-};
-export {};
+}>;
+/** The same resolution, without insisting there be an answer. */
+export declare function findToken(args: {
+    token?: string;
+    url?: string;
+}, url: string, environment: NodeJS.ProcessEnv): Promise<string | undefined>;

package/dist/runtime.js

@@ -1,14 +1,10 @@
+import { DEFAULT_URL, readStoredToken } from "./config.js";
 import { UsageError } from "./errors.js";
-export function resolveRuntime(args, environment) {
-    const url = args.url ?? environment.DIT_URL;
-    const token = args.token ?? environment.DIT_TOKEN;
-    if (!url)
-        throw new UsageError("Missing base URL: pass --url or set DIT_URL");
-    if (!token)
-        throw new UsageError("Missing auth token: pass --token or set DIT_TOKEN");
+export function resolveUrl(url, environment) {
+    const value = url ?? environment.DIT_URL ?? DEFAULT_URL;
     let parsed;
     try {
-        parsed = new URL(url);
+        parsed = new URL(value);
     }
     catch {
         throw new UsageError("DIT_URL/--url must be an absolute HTTP(S) URL");
@@ -16,5 +12,22 @@ export function resolveRuntime(args, environment) {
     if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
         throw new UsageError("DIT_URL/--url must be an absolute HTTP(S) URL");
     }
-    return { url: parsed.toString().replace(/\/+$/, ""), token };
+    return parsed.toString().replace(/\/+$/, "");
+}
+/**
+ * Flag, then environment, then whatever `dit login` saved. The saved token is
+ * last so a one-off `--token` or a CI `DIT_TOKEN` still wins without anyone
+ * having to sign out first.
+ */
+export async function resolveRuntime(args, environment) {
+    const url = resolveUrl(args.url, environment);
+    const token = await findToken(args, url, environment);
+    if (!token) {
+        throw new UsageError(`No agent token for ${url}: run \`dit login\`, pass --token, or set DIT_TOKEN`);
+    }
+    return { url, token };
+}
+/** The same resolution, without insisting there be an answer. */
+export async function findToken(args, url, environment) {
+    return args.token ?? environment.DIT_TOKEN ?? (await readStoredToken(url, environment));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelhop/dit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Did It Though? CLI for coding agents — upload PR screenshots and videos, pull structured feedback back",
   "keywords": [
     "agents",