@pixelhop/dit 0.1.0 → 0.2.0

package/README.md

@@ -7,32 +7,57 @@ 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 --token dit_…
+dit upload --project marketing-site --review pr-1234 --file shot.png
 ```
 
-## Configuration
+`--url` defaults to `https://diditthough.app` and `login` remembers the token, so neither
+has to be 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    |
-
-Set `DIT_DEBUG=1` to print stack traces instead of one-line errors.
+Sign in once; after that every command is just the command.
 
 ```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.
+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.
+
+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.
+
+### 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 --token dit_…                              # the hosted service
+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.
+
 ### `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,21 @@ export type CliArgs = ({
 } & RuntimeFlags & JsonFlag) | ({
     command: "markdown";
     review: string;
-} & RuntimeFlags) | {
+} & RuntimeFlags) | ({
+    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,6 +45,11 @@ const commandOptions = {
         ...runtimeOptions,
         review: { type: "string" },
     },
+    login: runtimeOptions,
+    logout: {
+        url: { type: "string" },
+        help: { type: "boolean", short: "h" },
+    },
 };
 export function parseCliArgs(argv) {
     const command = argv[0];
@@ -123,6 +128,12 @@ export function parseCliArgs(argv) {
             ...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,11 @@
+import type { CliArgs } from "./args.js";
+import { ApiClient, type ApiClientOptions } from "./client.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>;
+export declare function logout(args: Extract<CliArgs, {
+    command: "logout";
+}>, environment: NodeJS.ProcessEnv, output: Output): Promise<void>;
+export {};

package/dist/auth.js

@@ -0,0 +1,32 @@
+import { getCatalog } from "./catalog.js";
+import { ApiClient } from "./client.js";
+import { clearStoredToken, configPath, writeStoredToken } from "./config.js";
+import { ApiError, UsageError } from "./errors.js";
+import { resolveUrl } from "./runtime.js";
+export async function login(args, environment, output, createClient = (options) => new ApiClient(options)) {
+    const url = resolveUrl(args.url, environment);
+    const token = args.token ?? environment.DIT_TOKEN;
+    if (!token) {
+        throw new UsageError("login requires --token (or DIT_TOKEN)");
+    }
+    // Check the token before writing it. Storing a dead token turns one clear
+    // failure here into a confusing one on the next upload.
+    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/index.js

@@ -1,7 +1,9 @@
 #!/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 } from "./config.js";
 import { CliError } from "./errors.js";
 import { executeCommand } from "./operations.js";
 import { resolveRuntime } from "./runtime.js";
@@ -13,6 +15,8 @@ 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
+  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>
@@ -21,8 +25,8 @@ Commands:
   markdown  --review <ref|id>
 
 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 +44,16 @@ 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);
+    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/runtime.d.ts

@@ -1,9 +1,11 @@
-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 {};
+}>;

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,18 @@ 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 = args.token ?? environment.DIT_TOKEN ?? (await readStoredToken(url, environment));
+    if (!token) {
+        throw new UsageError(`No agent token for ${url}: run \`dit login --token dit_…\`, pass --token, or set DIT_TOKEN`);
+    }
+    return { url, token };
 }

package/package.json

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