@pixelhop/dit 0.2.0 → 0.3.0

package/README.md

@@ -8,28 +8,39 @@ Node 22+. No runtime dependencies.
 
 ```bash
 npm install -g @pixelhop/dit
-dit login --token dit_…
+dit login
+dit project create --name "Marketing site"
 dit upload --project marketing-site --review pr-1234 --file shot.png
 ```
 
-`--url` defaults to `https://diditthough.app` and `login` remembers the token, so neither
-has to be repeated.
+`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.
 
 ## Signing in
 
 Sign in once; after that every command is just the command.
 
 ```bash
-dit login --token dit_…
+dit login
 ```
 
-That checks the token against the API before storing it — a token saved without checking
-turns one clear failure here into a puzzling one on the next upload — and writes it to
-`~/.config/dit/config.json` with `0600` permissions. `$XDG_CONFIG_HOME` is respected, and
-`DIT_CONFIG` overrides the path outright. `dit logout` removes it.
+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
+dit login --token dit_…
+```
 
-The token is scoped to one project and one workspace, and a human has to create the
-project and mint the token first: agents cannot create projects.
+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
 
@@ -51,13 +62,47 @@ of one-line errors.
 ### `dit login` and `dit logout`
 
 ```bash
-dit login --token dit_…                              # the hosted service
+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

@@ -42,6 +42,9 @@ export type CliArgs = ({
     command: "markdown";
     review: string;
 } & RuntimeFlags) | ({
+    command: "project:create";
+    name: string;
+} & RuntimeFlags & JsonFlag) | ({
     command: "login";
 } & RuntimeFlags) | ({
     command: "logout";

package/dist/args.js

@@ -45,6 +45,11 @@ const commandOptions = {
         ...runtimeOptions,
         review: { type: "string" },
     },
+    "project:create": {
+        ...runtimeOptions,
+        name: { type: "string" },
+        json: { type: "boolean" },
+    },
     login: runtimeOptions,
     logout: {
         url: { type: "string" },
@@ -52,9 +57,13 @@ const commandOptions = {
     },
 };
 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" };
@@ -66,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,
@@ -128,6 +137,14 @@ 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 };
     }

package/dist/auth.d.ts

@@ -1,10 +1,11 @@
 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): Promise<void>;
+}>, 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>;

package/dist/auth.js

@@ -1,16 +1,19 @@
 import { getCatalog } from "./catalog.js";
 import { ApiClient } from "./client.js";
 import { clearStoredToken, configPath, writeStoredToken } from "./config.js";
-import { ApiError, UsageError } from "./errors.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)) {
+export async function login(args, environment, output, createClient = (options) => new ApiClient(options), device = {}) {
     const url = resolveUrl(args.url, environment);
-    const token = args.token ?? environment.DIT_TOKEN;
-    if (!token) {
-        throw new UsageError("login requires --token (or DIT_TOKEN)");
-    }
+    // 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.
+    // 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 }));
     }

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

@@ -3,10 +3,11 @@ import { createRequire } from "node:module";
 import { parseCliArgs } from "./args.js";
 import { login, logout } from "./auth.js";
 import { ApiClient } from "./client.js";
-import { DEFAULT_URL } from "./config.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
@@ -15,7 +16,7 @@ const { version: VERSION } = createRequire(import.meta.url)("../package.json");
 const HELP = `Usage: dit <command> [options]
 
 Commands:
-  login     --token <token> [--url <url>]   Save the token for later 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]
@@ -23,6 +24,7 @@ Commands:
   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 (default ${DEFAULT_URL}, or DIT_URL)
@@ -52,6 +54,27 @@ async function main() {
         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);
 }

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

@@ -9,3 +9,8 @@ export declare function resolveRuntime(args: ApiCommandArgs, environment: NodeJS
     url: string;
     token: string;
 }>;
+/** 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

@@ -21,9 +21,13 @@ export function resolveUrl(url, environment) {
  */
 export async function resolveRuntime(args, environment) {
     const url = resolveUrl(args.url, environment);
-    const token = args.token ?? environment.DIT_TOKEN ?? (await readStoredToken(url, environment));
+    const token = await findToken(args, url, environment);
     if (!token) {
-        throw new UsageError(`No agent token for ${url}: run \`dit login --token dit_…\`, pass --token, or set DIT_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.2.0",
+  "version": "0.3.0",
   "description": "Did It Though? CLI for coding agents — upload PR screenshots and videos, pull structured feedback back",
   "keywords": [
     "agents",