@pixelhop/dit 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# @pixelhop/dit
+
+The `dit` CLI for [Did It Though?](https://diditthough.app) — visual proof for agent-built
+software. An agent uploads the screenshots and screen recordings it produced, gets back
+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
+```
+
+## Configuration
+
+Two values, from flags or the environment:
+
+| 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.
+
+```bash
+export DIT_URL=https://diditthough.app
+export DIT_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.
+
+## Commands
+
+### `dit upload`
+
+Uploads one or more files to a review, creating the review if it does not exist yet.
+
+```bash
+dit upload --project marketing-site --review pr-1234 \
+  --title "Fix the mobile action bar" \
+  --commit "$(git rev-parse HEAD)" --branch "$(git branch --show-current)" \
+  --file shots/action-bar-mobile.png --file shots/action-bar-desktop.png
+```
+
+`--review` takes either an existing `rev_…` id or your own reference — a PR number, a run
+id, anything stable. A reference that has been seen before reuses that review, so a job
+that runs twice on the same PR adds revisions instead of a second review. `--project`
+takes the project slug or its `prj_…` id.
+
+Per-capture context, all optional: `--route /checkout`, `--viewport 390x844@3`,
+`--scenario "logged out"`, `--title`. Pass `--json` for the machine-readable form; the
+default prints the review URL and the Markdown block to paste into a PR.
+
+Images are sniffed by magic bytes (PNG, JPEG, WebP, GIF) and their dimensions read from
+the file, so a mislabelled extension does not matter. For MP4 and WebM the CLI shells out
+to `ffprobe` for duration and dimensions, and to `ffmpeg` for a poster frame — both are
+optional. Without them the upload still succeeds, with a warning, minus the poster.
+
+### `dit feedback`
+
+```bash
+dit feedback --review pr-1234                    # open threads, human-readable
+dit feedback --review pr-1234 --status all --json
+```
+
+Threads come back with normalised 0–1 geometry and `timestampMs` for video notes, so an
+agent can map a comment to the place it points at without knowing the render size.
+`--status` is `open` (default), `addressed`, `resolved` or `all`.
+
+### `dit reply` and `dit address`
+
+```bash
+dit reply   --thread thr_… --message "Fixed the padding, re-shot below."
+dit address --thread thr_… --message "Done in 4a1c9f2."
+```
+
+`reply` adds a comment. `address` marks the thread as handled and leaves the resolve
+decision to the human who raised it.
+
+### `dit revision`
+
+Uploads a new take of one artifact, keeping it linked to the original and to any notes on
+it.
+
+```bash
+dit revision --artifact art_… --file shots/action-bar-mobile.png
+```
+
+### `dit markdown`
+
+Reprints the PR Markdown for a whole review — every artifact, current revision, as image
+links that GitHub will render inline.
+
+```bash
+dit markdown --review pr-1234 >> pr-body.md
+```
+
+## Exit codes
+
+`0` success, `2` usage error (a bad or missing flag), `1` everything else, including API
+errors. Errors go to stderr as a single line.
+
+## Development
+
+From the repository root:
+
+```bash
+pnpm --filter @pixelhop/dit build      # tsc → dist/
+pnpm --filter @pixelhop/dit test       # vitest
+pnpm --filter @pixelhop/dit typecheck
+```
+
+Releases are cut by tagging `cli-v<version>`, which runs `.github/workflows/publish-cli.yml`.
+See that file for the publish path and the repository README for the service itself.

package/dist/args.d.ts

@@ -0,0 +1,53 @@
+export type Viewport = {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+};
+type RuntimeFlags = {
+    url?: string;
+    token?: string;
+};
+type JsonFlag = {
+    json?: true;
+};
+export type CliArgs = ({
+    command: "upload";
+    project: string;
+    review: string;
+    files: string[];
+} & RuntimeFlags & JsonFlag & {
+    title?: string;
+    commit?: string;
+    branch?: string;
+    route?: string;
+    viewport?: Viewport;
+    scenario?: string;
+}) | ({
+    command: "feedback";
+    review: string;
+    status: FeedbackStatus;
+} & RuntimeFlags & JsonFlag) | ({
+    command: "reply";
+    thread: string;
+    message: string;
+} & RuntimeFlags) | ({
+    command: "address";
+    thread: string;
+    message?: string;
+} & RuntimeFlags) | ({
+    command: "revision";
+    artifact: string;
+    file: string;
+} & RuntimeFlags & JsonFlag) | ({
+    command: "markdown";
+    review: string;
+} & RuntimeFlags) | {
+    command: "help";
+    topic?: string;
+} | {
+    command: "version";
+};
+export type FeedbackStatus = "open" | "addressed" | "resolved" | "all";
+export declare function parseCliArgs(argv: string[]): CliArgs;
+export declare function parseViewport(value: string): Viewport;
+export {};

package/dist/args.js

@@ -0,0 +1,182 @@
+import { parseArgs } from "node:util";
+import { UsageError } from "./errors.js";
+const runtimeOptions = {
+    url: { type: "string" },
+    token: { type: "string" },
+    help: { type: "boolean", short: "h" },
+};
+const commandOptions = {
+    upload: {
+        ...runtimeOptions,
+        project: { type: "string" },
+        review: { type: "string" },
+        file: { type: "string", multiple: true },
+        title: { type: "string" },
+        commit: { type: "string" },
+        branch: { type: "string" },
+        route: { type: "string" },
+        viewport: { type: "string" },
+        scenario: { type: "string" },
+        json: { type: "boolean" },
+    },
+    feedback: {
+        ...runtimeOptions,
+        review: { type: "string" },
+        status: { type: "string" },
+        json: { type: "boolean" },
+    },
+    reply: {
+        ...runtimeOptions,
+        thread: { type: "string" },
+        message: { type: "string" },
+    },
+    address: {
+        ...runtimeOptions,
+        thread: { type: "string" },
+        message: { type: "string" },
+    },
+    revision: {
+        ...runtimeOptions,
+        artifact: { type: "string" },
+        file: { type: "string" },
+        json: { type: "boolean" },
+    },
+    markdown: {
+        ...runtimeOptions,
+        review: { type: "string" },
+    },
+};
+export function parseCliArgs(argv) {
+    const command = argv[0];
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        return { command: "help", ...(argv[1] ? { topic: argv[1] } : {}) };
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+        return { command: "version" };
+    }
+    if (!(command in commandOptions)) {
+        throw new UsageError(`Unknown command: ${command}`);
+    }
+    const name = command;
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: argv.slice(1),
+            options: commandOptions[name],
+            strict: true,
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        throw new UsageError(error instanceof Error ? error.message : "Invalid arguments");
+    }
+    if (values.help) {
+        return { command: "help", topic: name };
+    }
+    const runtime = runtimeFlags(values);
+    if (name === "upload") {
+        const files = Array.isArray(values.file) ? values.file : [];
+        if (files.length === 0) {
+            throw new UsageError("upload requires at least one --file");
+        }
+        return {
+            command: name,
+            project: required(values, "project", name),
+            review: required(values, "review", name),
+            files,
+            ...optional(values, "title"),
+            ...optional(values, "commit"),
+            ...optional(values, "branch"),
+            ...optional(values, "route"),
+            ...(typeof values.viewport === "string" ? { viewport: parseViewport(values.viewport) } : {}),
+            ...optional(values, "scenario"),
+            ...(values.json ? { json: true } : {}),
+            ...runtime,
+        };
+    }
+    if (name === "feedback") {
+        const status = (values.status ?? "open");
+        if (!["open", "addressed", "resolved", "all"].includes(status)) {
+            throw new UsageError("--status must be open, addressed, resolved, or all");
+        }
+        return {
+            command: name,
+            review: required(values, "review", name),
+            status: status,
+            ...(values.json ? { json: true } : {}),
+            ...runtime,
+        };
+    }
+    if (name === "reply") {
+        return {
+            command: name,
+            thread: required(values, "thread", name),
+            message: required(values, "message", name),
+            ...runtime,
+        };
+    }
+    if (name === "address") {
+        return {
+            command: name,
+            thread: required(values, "thread", name),
+            ...optional(values, "message"),
+            ...runtime,
+        };
+    }
+    if (name === "revision") {
+        return {
+            command: name,
+            artifact: required(values, "artifact", name),
+            file: required(values, "file", name),
+            ...(values.json ? { json: true } : {}),
+            ...runtime,
+        };
+    }
+    return {
+        command: name,
+        review: required(values, "review", name),
+        ...runtime,
+    };
+}
+function required(values, key, command) {
+    const value = values[key];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new UsageError(`${command} requires --${key}`);
+    }
+    return value;
+}
+function optional(values, key) {
+    const value = values[key];
+    return typeof value === "string" ? { [key]: value } : {};
+}
+function runtimeFlags(values) {
+    const url = typeof values.url === "string" ? normalizeUrl(values.url) : undefined;
+    const token = typeof values.token === "string" ? values.token : undefined;
+    return { ...(url ? { url } : {}), ...(token ? { token } : {}) };
+}
+function normalizeUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new UsageError("--url must be an absolute HTTP(S) URL");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new UsageError("--url must be an absolute HTTP(S) URL");
+    }
+    return url.toString().replace(/\/+$/, "");
+}
+export function parseViewport(value) {
+    const match = /^(\d+)x(\d+)(?:@(\d+(?:\.\d+)?))?$/.exec(value);
+    if (!match) {
+        throw new UsageError("--viewport must use WIDTHxHEIGHT or WIDTHxHEIGHT@SCALE");
+    }
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    const scale = match[3] ? Number(match[3]) : undefined;
+    if (width < 1 || height < 1 || width > 100_000 || height > 100_000 || scale === 0) {
+        throw new UsageError("--viewport contains an out-of-range value");
+    }
+    return { width, height, ...(scale === undefined ? {} : { deviceScaleFactor: scale }) };
+}

package/dist/catalog.d.ts

@@ -0,0 +1,21 @@
+import { ApiClient } from "./client.js";
+export type CatalogReview = {
+    id: string;
+    title: string;
+    externalRef: string | null;
+    status: string;
+    url: string;
+};
+export type CatalogProject = {
+    id: string;
+    name: string;
+    slug: string;
+    workspaceId: string;
+    reviews: CatalogReview[];
+};
+export type ProjectCatalog = {
+    projects: CatalogProject[];
+};
+export declare function getCatalog(client: ApiClient): Promise<ProjectCatalog>;
+export declare function resolveProject(catalog: ProjectCatalog, reference: string): CatalogProject;
+export declare function resolveReview(catalog: ProjectCatalog, reference: string): CatalogReview;

package/dist/catalog.js

@@ -0,0 +1,29 @@
+import { ApiError } from "./errors.js";
+export async function getCatalog(client) {
+    return client.requestJson("/v1/projects");
+}
+export function resolveProject(catalog, reference) {
+    const idMatch = catalog.projects.find(({ id }) => id === reference);
+    if (idMatch)
+        return idMatch;
+    const matches = catalog.projects.filter(({ slug }) => slug === reference);
+    if (matches.length === 0)
+        throw new ApiError(`Project not found: ${reference}`, 404, "not_found");
+    if (matches.length > 1) {
+        throw new ApiError(`Project reference is ambiguous: ${reference}; use a project id`, 422, "invalid_request");
+    }
+    return matches[0];
+}
+export function resolveReview(catalog, reference) {
+    const reviews = catalog.projects.flatMap(({ reviews }) => reviews);
+    const idMatch = reviews.find(({ id }) => id === reference);
+    if (idMatch)
+        return idMatch;
+    const matches = reviews.filter(({ externalRef }) => externalRef === reference);
+    if (matches.length === 0)
+        throw new ApiError(`Review not found: ${reference}`, 404, "not_found");
+    if (matches.length > 1) {
+        throw new ApiError(`Review reference is ambiguous: ${reference}; use a review id`, 422, "invalid_request");
+    }
+    return matches[0];
+}

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+type Fetch = typeof fetch;
+export type ApiClientOptions = {
+    url: string;
+    token: string;
+    fetch?: Fetch;
+    sleep?: (milliseconds: number) => Promise<void>;
+    createIdempotencyKey?: () => string;
+    retries?: number;
+};
+export type JsonRequest = {
+    method?: string;
+    body?: unknown;
+    idempotent?: boolean;
+    authenticated?: boolean;
+    headers?: HeadersInit;
+};
+export declare class ApiClient {
+    readonly url: string;
+    private readonly token;
+    private readonly fetch;
+    private readonly sleep;
+    private readonly createIdempotencyKey;
+    private readonly retries;
+    constructor(options: ApiClientOptions);
+    requestJson<T = unknown>(path: string, request?: JsonRequest): Promise<T>;
+    requestText(path: string): Promise<string>;
+    /** Stream a file to a one-time upload URL without buffering it in the CLI. */
+    uploadFile(uploadUrl: string, filePath: string): Promise<void>;
+    private absoluteUrl;
+    private withRetries;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { ApiError } from "./errors.js";
+export class ApiClient {
+    url;
+    token;
+    fetch;
+    sleep;
+    createIdempotencyKey;
+    retries;
+    constructor(options) {
+        this.url = options.url.replace(/\/+$/, "");
+        this.token = options.token;
+        this.fetch = options.fetch ?? globalThis.fetch;
+        this.sleep =
+            options.sleep ??
+                ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+        this.createIdempotencyKey = options.createIdempotencyKey ?? (() => randomUUID());
+        this.retries = options.retries ?? 2;
+    }
+    async requestJson(path, request = {}) {
+        const idempotencyKey = request.idempotent ? this.createIdempotencyKey() : undefined;
+        const headers = new Headers(request.headers);
+        if (request.authenticated !== false) {
+            headers.set("authorization", `Bearer ${this.token}`);
+        }
+        if (request.body !== undefined) {
+            headers.set("content-type", "application/json");
+        }
+        if (idempotencyKey) {
+            headers.set("idempotency-key", idempotencyKey);
+        }
+        return this.withRetries(async () => {
+            const response = await this.fetch(this.absoluteUrl(path), {
+                method: request.method ?? "GET",
+                headers,
+                body: request.body === undefined ? undefined : JSON.stringify(request.body),
+            });
+            if (isTransient(response.status)) {
+                throw new TransientResponse(response);
+            }
+            if (!response.ok) {
+                throw await apiErrorFrom(response);
+            }
+            return (await readPayload(response));
+        });
+    }
+    async requestText(path) {
+        const headers = new Headers({ authorization: `Bearer ${this.token}` });
+        return this.withRetries(async () => {
+            const response = await this.fetch(this.absoluteUrl(path), { headers });
+            if (isTransient(response.status)) {
+                throw new TransientResponse(response);
+            }
+            if (!response.ok) {
+                throw await apiErrorFrom(response);
+            }
+            return response.text();
+        });
+    }
+    /** Stream a file to a one-time upload URL without buffering it in the CLI. */
+    async uploadFile(uploadUrl, filePath) {
+        const file = await stat(filePath);
+        let uncertainPreviousAttempt = false;
+        for (let attempt = 0; attempt <= this.retries; attempt += 1) {
+            try {
+                const response = await this.fetch(this.absoluteUrl(uploadUrl), {
+                    method: "PUT",
+                    headers: { "content-length": String(file.size) },
+                    body: Readable.toWeb(createReadStream(filePath)),
+                    duplex: "half",
+                });
+                if (response.ok) {
+                    await response.body?.cancel().catch(() => undefined);
+                    return;
+                }
+                if (isTransient(response.status) && attempt < this.retries) {
+                    uncertainPreviousAttempt = true;
+                    await response.body?.cancel().catch(() => undefined);
+                    await this.sleep(100 * 2 ** attempt);
+                    continue;
+                }
+                const error = await apiErrorFrom(response);
+                // If a response was lost after the server consumed this one-time URL, retrying
+                // correctly reports already_used. In that narrow case completion is the proof.
+                if (uncertainPreviousAttempt && error.status === 409 && error.code === "already_used") {
+                    return;
+                }
+                throw error;
+            }
+            catch (error) {
+                if (error instanceof ApiError)
+                    throw error;
+                if (!(error instanceof TypeError) || attempt === this.retries) {
+                    const message = error instanceof Error ? error.message : "Network request failed";
+                    throw new ApiError(`Network request failed: ${oneLine(message)}`);
+                }
+                uncertainPreviousAttempt = true;
+                await this.sleep(100 * 2 ** attempt);
+            }
+        }
+    }
+    absoluteUrl(path) {
+        return /^https?:\/\//.test(path)
+            ? path
+            : `${this.url}${path.startsWith("/") ? "" : "/"}${path}`;
+    }
+    async withRetries(operation) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.retries; attempt += 1) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                if (error instanceof ApiError) {
+                    throw error;
+                }
+                lastError = error;
+                if (attempt === this.retries) {
+                    break;
+                }
+                if (error instanceof TransientResponse) {
+                    await error.response.body?.cancel().catch(() => undefined);
+                }
+                else if (!(error instanceof TypeError)) {
+                    throw error;
+                }
+                await this.sleep(100 * 2 ** attempt);
+            }
+        }
+        if (lastError instanceof TransientResponse) {
+            throw await apiErrorFrom(lastError.response);
+        }
+        const message = lastError instanceof Error ? lastError.message : "Network request failed";
+        throw new ApiError(`Network request failed: ${oneLine(message)}`);
+    }
+}
+class TransientResponse extends Error {
+    response;
+    constructor(response) {
+        super(`HTTP ${response.status}`);
+        this.response = response;
+    }
+}
+function isTransient(status) {
+    return status >= 500 && status <= 599;
+}
+async function apiErrorFrom(response) {
+    const payload = await readPayload(response);
+    const record = isRecord(payload) ? payload : {};
+    const data = isRecord(record.data) ? record.data : {};
+    const message = stringValue(data.message) ??
+        stringValue(record.statusMessage) ??
+        stringValue(record.message) ??
+        `${response.status} ${response.statusText || "API request failed"}`;
+    const code = stringValue(data.error);
+    return new ApiError(oneLine(message), response.status, code);
+}
+async function readPayload(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+function oneLine(value) {
+    return value.replace(/\s+/g, " ").trim();
+}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class CliError extends Error {
+    readonly exitCode: 1 | 2;
+    constructor(message: string, exitCode: 1 | 2);
+}
+export declare class UsageError extends CliError {
+    constructor(message: string);
+}
+export declare class ApiError extends CliError {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,22 @@
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = new.target.name;
+    }
+}
+export class UsageError extends CliError {
+    constructor(message) {
+        super(message, 2);
+    }
+}
+export class ApiError extends CliError {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message, 1);
+        this.status = status;
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { parseCliArgs } from "./args.js";
+import { ApiClient } from "./client.js";
+import { CliError } from "./errors.js";
+import { executeCommand } from "./operations.js";
+import { resolveRuntime } 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
+// both `src/` and `dist/` is the package root, and npm always ships it.
+const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+const HELP = `Usage: dit <command> [options]
+
+Commands:
+  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>
+
+Global options:
+  --url <url>      API base URL (or DIT_URL)
+  --token <token>  Agent token (or DIT_TOKEN)
+  -h, --help       Show help
+  -v, --version    Show version
+
+Upload options:
+  --title <text> --commit <sha> --branch <name> --route <path>
+  --viewport <WIDTHxHEIGHT[@SCALE]> --scenario <name> --json
+`;
+async function main() {
+    const args = parseCliArgs(process.argv.slice(2));
+    if (args.command === "help") {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (args.command === "version") {
+        process.stdout.write(`${VERSION}\n`);
+        return;
+    }
+    const runtime = resolveRuntime(args, process.env);
+    const client = new ApiClient(runtime);
+    await executeCommand(args, client, {
+        out: (value) => process.stdout.write(value),
+        warn: (value) => process.stderr.write(`warning: ${value}\n`),
+    });
+}
+main().catch((error) => {
+    if (process.env.DIT_DEBUG === "1" && error instanceof Error && error.stack) {
+        process.stderr.write(`${error.stack}\n`);
+    }
+    else {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`error: ${message.replace(/\s+/g, " ").trim()}\n`);
+    }
+    process.exitCode = error instanceof CliError ? error.exitCode : 1;
+});

package/dist/media.d.ts

@@ -0,0 +1,25 @@
+export type SupportedMime = "image/png" | "image/jpeg" | "image/webp" | "image/gif" | "video/mp4" | "video/webm";
+export type Dimensions = {
+    width: number;
+    height: number;
+};
+export type PreparedMedia = {
+    path: string;
+    name: string;
+    kind: "image" | "video";
+    mime: SupportedMime;
+    bytes: number;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    poster?: {
+        path: string;
+        mime: "image/jpeg";
+        bytes: number;
+    };
+    cleanup: () => Promise<void>;
+};
+export declare function sniffMediaType(buffer: Uint8Array): SupportedMime | undefined;
+export declare function sniffImageDimensions(buffer: Uint8Array, mime: SupportedMime): Dimensions | undefined;
+export declare function readMediaHeader(path: string, maxBytes?: number): Promise<Buffer>;
+export declare function prepareMedia(path: string, warn: (message: string) => void): Promise<PreparedMedia>;

package/dist/media.js

@@ -0,0 +1,238 @@
+import { execFile } from "node:child_process";
+import { basename, join } from "node:path";
+import { open, mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { promisify } from "node:util";
+import { CliError } from "./errors.js";
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const MP4_BRANDS = new Set([
+    "isom",
+    "iso2",
+    "iso4",
+    "iso5",
+    "iso6",
+    "mp41",
+    "mp42",
+    "avc1",
+    "M4V ",
+    "dash",
+]);
+export function sniffMediaType(buffer) {
+    const bytes = Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(PNG_SIGNATURE))
+        return "image/png";
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return "image/jpeg";
+    }
+    if (bytes.length >= 6 &&
+        (bytes.toString("ascii", 0, 6) === "GIF87a" || bytes.toString("ascii", 0, 6) === "GIF89a")) {
+        return "image/gif";
+    }
+    if (bytes.length >= 12 &&
+        bytes.toString("ascii", 0, 4) === "RIFF" &&
+        bytes.toString("ascii", 8, 12) === "WEBP") {
+        return "image/webp";
+    }
+    if (bytes.length >= 12 && bytes.toString("ascii", 4, 8) === "ftyp") {
+        const brand = bytes.toString("ascii", 8, 12);
+        if (MP4_BRANDS.has(brand) || brand.startsWith("mp4"))
+            return "video/mp4";
+    }
+    if (bytes.length >= 4 &&
+        bytes[0] === 0x1a &&
+        bytes[1] === 0x45 &&
+        bytes[2] === 0xdf &&
+        bytes[3] === 0xa3) {
+        return "video/webm";
+    }
+    return undefined;
+}
+export function sniffImageDimensions(buffer, mime) {
+    const bytes = Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    if (mime === "image/png" && bytes.length >= 24) {
+        return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+    }
+    if (mime === "image/gif" && bytes.length >= 10) {
+        return { width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) };
+    }
+    if (mime === "image/jpeg")
+        return jpegDimensions(bytes);
+    if (mime === "image/webp")
+        return webpDimensions(bytes);
+    return undefined;
+}
+export async function readMediaHeader(path, maxBytes = 1024 * 1024) {
+    const handle = await open(path, "r");
+    try {
+        const stats = await handle.stat();
+        const length = Math.min(stats.size, maxBytes);
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buffer, 0, length, 0);
+        return buffer.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
+const execFileAsync = promisify(execFile);
+export async function prepareMedia(path, warn) {
+    let file;
+    try {
+        file = await stat(path);
+    }
+    catch {
+        throw new CliError(`File not found: ${path}`, 1);
+    }
+    if (!file.isFile())
+        throw new CliError(`Not a file: ${path}`, 1);
+    if (file.size === 0)
+        throw new CliError(`File is empty: ${path}`, 1);
+    const header = await readMediaHeader(path);
+    const mime = sniffMediaType(header);
+    if (!mime)
+        throw new CliError(`Unsupported media type: ${path}`, 1);
+    const kind = mime.startsWith("image/") ? "image" : "video";
+    const common = { path, name: basename(path), kind, mime, bytes: file.size };
+    if (kind === "image") {
+        const dimensions = sniffImageDimensions(header, mime);
+        if (!dimensions)
+            throw new CliError(`Could not read image dimensions: ${path}`, 1);
+        return { ...common, ...dimensions, cleanup: async () => undefined };
+    }
+    const video = await probeVideo(path, warn);
+    const poster = await createPoster(path, warn);
+    return {
+        ...common,
+        ...video,
+        ...(poster ? { poster } : {}),
+        cleanup: poster?.cleanup ?? (async () => undefined),
+    };
+}
+async function probeVideo(path, warn) {
+    try {
+        const { stdout } = await execFileAsync("ffprobe", [
+            "-v",
+            "error",
+            "-select_streams",
+            "v:0",
+            "-show_entries",
+            "stream=width,height:format=duration",
+            "-of",
+            "json",
+            path,
+        ]);
+        const payload = JSON.parse(stdout);
+        const stream = payload.streams?.[0];
+        const duration = Number(payload.format?.duration);
+        return {
+            ...(Number.isInteger(stream?.width) && stream.width > 0 ? { width: stream.width } : {}),
+            ...(Number.isInteger(stream?.height) && stream.height > 0
+                ? { height: stream.height }
+                : {}),
+            ...(Number.isFinite(duration) && duration >= 0
+                ? { durationMs: Math.round(duration * 1000) }
+                : {}),
+        };
+    }
+    catch (error) {
+        warn(toolWarning("ffprobe", "video duration and dimensions skipped", error));
+        return {};
+    }
+}
+async function createPoster(path, warn) {
+    const directory = await mkdtemp(join(tmpdir(), "dit-poster-"));
+    const posterPath = join(directory, "poster.jpg");
+    try {
+        await execFileAsync("ffmpeg", [
+            "-v",
+            "error",
+            "-y",
+            "-i",
+            path,
+            "-frames:v",
+            "1",
+            "-q:v",
+            "3",
+            posterPath,
+        ]);
+        const poster = await stat(posterPath);
+        if (poster.size === 0)
+            throw new Error("generated an empty poster");
+        return {
+            path: posterPath,
+            mime: "image/jpeg",
+            bytes: poster.size,
+            cleanup: () => rm(directory, { recursive: true, force: true }),
+        };
+    }
+    catch (error) {
+        await rm(directory, { recursive: true, force: true });
+        warn(toolWarning("ffmpeg", "video poster skipped", error));
+        return undefined;
+    }
+}
+function toolWarning(tool, consequence, error) {
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    if (code === "ENOENT")
+        return `${tool} not found; ${consequence}`;
+    const detail = error instanceof Error ? error.message.replace(/\s+/g, " ").trim() : "failed";
+    return `${tool} failed; ${consequence}: ${detail}`;
+}
+function jpegDimensions(bytes) {
+    let offset = 2;
+    const startOfFrame = new Set([
+        0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+    ]);
+    while (offset + 3 < bytes.length) {
+        if (bytes[offset] !== 0xff) {
+            offset += 1;
+            continue;
+        }
+        while (bytes[offset] === 0xff)
+            offset += 1;
+        const marker = bytes[offset];
+        offset += 1;
+        if (marker === undefined || marker === 0xd9 || marker === 0xda)
+            break;
+        if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7) || marker === 0x01)
+            continue;
+        if (offset + 2 > bytes.length)
+            break;
+        const length = bytes.readUInt16BE(offset);
+        if (length < 2 || offset + length > bytes.length)
+            break;
+        if (startOfFrame.has(marker) && length >= 7) {
+            return { height: bytes.readUInt16BE(offset + 3), width: bytes.readUInt16BE(offset + 5) };
+        }
+        offset += length;
+    }
+    return undefined;
+}
+function webpDimensions(bytes) {
+    if (bytes.length < 25)
+        return undefined;
+    const kind = bytes.toString("ascii", 12, 16);
+    const data = 20;
+    if (kind === "VP8X" && bytes.length >= data + 10) {
+        return {
+            width: readUInt24LE(bytes, data + 4) + 1,
+            height: readUInt24LE(bytes, data + 7) + 1,
+        };
+    }
+    if (kind === "VP8 " &&
+        bytes.length >= data + 10 &&
+        bytes.subarray(data + 3, data + 6).equals(Buffer.from([0x9d, 0x01, 0x2a]))) {
+        return {
+            width: bytes.readUInt16LE(data + 6) & 0x3fff,
+            height: bytes.readUInt16LE(data + 8) & 0x3fff,
+        };
+    }
+    if (kind === "VP8L" && bytes.length >= data + 5 && bytes[data] === 0x2f) {
+        const bits = bytes.readUInt32LE(data + 1);
+        return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+    }
+    return undefined;
+}
+function readUInt24LE(buffer, offset) {
+    return buffer[offset] | (buffer[offset + 1] << 8) | (buffer[offset + 2] << 16);
+}

package/dist/operations.d.ts

@@ -0,0 +1,6 @@
+import type { CliArgs } 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>;

package/dist/operations.js

@@ -0,0 +1,144 @@
+import { getCatalog, resolveProject, resolveReview } from "./catalog.js";
+import { ApiError } from "./errors.js";
+import { prepareMedia } from "./media.js";
+import { formatFeedback, printJson } from "./output.js";
+export async function executeCommand(args, client, output) {
+    if (args.command === "upload")
+        return upload(args, client, output);
+    if (args.command === "revision")
+        return revision(args, client, output);
+    if (args.command === "feedback") {
+        const review = resolveReview(await getCatalog(client), args.review);
+        const payload = await client.requestJson(`/v1/reviews/${encodeURIComponent(review.id)}/threads?status=${args.status}`);
+        output.out(args.json ? printJson(payload) : formatFeedback(payload));
+        return;
+    }
+    if (args.command === "reply") {
+        await client.requestJson(`/v1/threads/${encodeURIComponent(args.thread)}/replies`, {
+            method: "POST",
+            body: { body: args.message },
+        });
+        output.out(`Replied to ${args.thread}.\n`);
+        return;
+    }
+    if (args.command === "address") {
+        await client.requestJson(`/v1/threads/${encodeURIComponent(args.thread)}/address`, {
+            method: "POST",
+            body: args.message ? { body: args.message } : {},
+        });
+        output.out(`Addressed ${args.thread}.\n`);
+        return;
+    }
+    const review = resolveReview(await getCatalog(client), args.review);
+    output.out(await client.requestText(`/v1/reviews/${encodeURIComponent(review.id)}/markdown?format=text`));
+}
+async function upload(args, client, output) {
+    const catalog = await getCatalog(client);
+    const project = resolveProject(catalog, args.project);
+    let reviewPayload;
+    if (args.review.startsWith("rev_")) {
+        const review = project.reviews.find(({ id }) => id === args.review);
+        if (!review)
+            throw new ApiError(`Review not found in project ${project.id}: ${args.review}`, 404, "not_found");
+        reviewPayload = { reused: true, review };
+    }
+    else {
+        reviewPayload = await client.requestJson("/v1/reviews", {
+            method: "POST",
+            idempotent: true,
+            body: {
+                projectId: project.id,
+                title: args.title ?? args.review,
+                externalRef: args.review,
+                ...(args.branch ? { branch: args.branch } : {}),
+                ...(args.commit ? { commit: args.commit } : {}),
+            },
+        });
+    }
+    const completions = [];
+    for (const file of args.files) {
+        const prepared = await prepareMedia(file, output.warn);
+        try {
+            completions.push(await declareUploadComplete(client, prepared, {
+                path: "/v1/artifacts/uploads",
+                declaration: {
+                    reviewId: reviewPayload.review.id,
+                    kind: prepared.kind,
+                    title: args.title ?? stripExtension(prepared.name),
+                    ...(args.route ? { route: args.route } : {}),
+                    ...(args.viewport ? { viewport: args.viewport } : {}),
+                    ...(args.commit ? { commit: args.commit } : {}),
+                    ...(args.scenario ? { scenario: args.scenario } : {}),
+                },
+            }));
+        }
+        finally {
+            await prepared.cleanup();
+        }
+    }
+    const markdown = await client.requestText(`/v1/reviews/${encodeURIComponent(reviewPayload.review.id)}/markdown?format=text`);
+    if (args.json) {
+        output.out(printJson({
+            review: { ...reviewPayload.review, reused: reviewPayload.reused },
+            artifacts: completions,
+            markdown,
+        }));
+    }
+    else {
+        output.out(`Uploaded ${completions.length} artifact${completions.length === 1 ? "" : "s"}.\nReview: ${reviewPayload.review.url}\n\nMarkdown:\n${ensureNewline(markdown)}`);
+    }
+}
+async function revision(args, client, output) {
+    const prepared = await prepareMedia(args.file, output.warn);
+    try {
+        const completion = await declareUploadComplete(client, prepared, {
+            path: `/v1/artifacts/${encodeURIComponent(args.artifact)}/revisions`,
+            declaration: {},
+        });
+        if (args.json) {
+            output.out(printJson(completion));
+        }
+        else {
+            output.out(`Revision ${completion.revisionIndex} ready.\nReview: ${completion.review.url}\n\nMarkdown:\n${ensureNewline(completion.markdown)}`);
+        }
+    }
+    finally {
+        await prepared.cleanup();
+    }
+}
+async function declareUploadComplete(client, media, options) {
+    const declaration = await client.requestJson(options.path, {
+        method: "POST",
+        idempotent: true,
+        body: {
+            ...options.declaration,
+            mime: media.mime,
+            bytes: media.bytes,
+            ...(media.poster ? { poster: { mime: media.poster.mime, bytes: media.poster.bytes } } : {}),
+        },
+    });
+    await client.uploadFile(declaration.uploadUrl, media.path);
+    if (media.poster && declaration.poster) {
+        await client.uploadFile(declaration.poster.uploadUrl, media.poster.path);
+    }
+    return client.requestJson(`/v1/artifacts/${encodeURIComponent(declaration.artifactId)}/complete`, {
+        method: "POST",
+        idempotent: true,
+        body: {
+            revisionId: declaration.revisionId,
+            ...(media.width ? { width: media.width } : {}),
+            ...(media.height ? { height: media.height } : {}),
+            ...(media.durationMs === undefined ? {} : { durationMs: media.durationMs }),
+            ...(media.poster && declaration.poster
+                ? { posterUploadToken: declaration.poster.uploadToken }
+                : {}),
+        },
+    });
+}
+function stripExtension(name) {
+    const stripped = name.replace(/\.[^.]+$/, "");
+    return stripped || name;
+}
+function ensureNewline(value) {
+    return value.endsWith("\n") ? value : `${value}\n`;
+}

package/dist/output.d.ts

@@ -0,0 +1,10 @@
+export type Output = {
+    out: (value: string) => void;
+    warn: (value: string) => void;
+};
+export declare function printJson(value: unknown): string;
+export declare function formatFeedback(payload: {
+    count: number;
+    status: string;
+    threads: Array<Record<string, unknown>>;
+}): string;

package/dist/output.js

@@ -0,0 +1,41 @@
+export function printJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function formatFeedback(payload) {
+    if (payload.count === 0)
+        return `No ${payload.status} feedback.\n`;
+    const rows = payload.threads.map((thread) => {
+        const artifact = record(thread.artifact);
+        return [
+            text(thread.threadId),
+            text(thread.status),
+            text(artifact.title) || "(review)",
+            text(thread.revision) || "-",
+            text(thread.kind),
+            oneLine(text(thread.comment)),
+        ];
+    });
+    const headings = ["THREAD", "STATUS", "ARTIFACT", "REV", "KIND", "COMMENT"];
+    const widths = headings.map((heading, column) => Math.max(heading.length, ...rows.map((row) => row[column].length)));
+    const line = (row) => row
+        .map((value, column) => value.padEnd(widths[column]))
+        .join("  ")
+        .trimEnd();
+    return `${line(headings)}\n${rows.map(line).join("\n")}\n`;
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function text(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return String(value);
+    }
+    return "";
+}
+function oneLine(value) {
+    return value.replace(/\s+/g, " ").trim();
+}

package/dist/runtime.d.ts

@@ -0,0 +1,9 @@
+import type { CliArgs } from "./args.js";
+type RuntimeArgs = Exclude<CliArgs, {
+    command: "help" | "version";
+}>;
+export declare function resolveRuntime(args: RuntimeArgs, environment: NodeJS.ProcessEnv): {
+    url: string;
+    token: string;
+};
+export {};

package/dist/runtime.js

@@ -0,0 +1,20 @@
+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");
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new UsageError("DIT_URL/--url must be an absolute HTTP(S) URL");
+    }
+    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 };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pixelhop/dit",
+  "version": "0.1.0",
+  "description": "Did It Though? CLI for coding agents — upload PR screenshots and videos, pull structured feedback back",
+  "keywords": [
+    "agents",
+    "cli",
+    "code-review",
+    "diditthough",
+    "screenshots",
+    "visual-review"
+  ],
+  "homepage": "https://diditthough.app",
+  "bugs": {
+    "url": "https://github.com/pixelhop/diditthough/issues"
+  },
+  "license": "ISC",
+  "author": "Pixelhop <hello@pixelhop.io> (https://pixelhop.io)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pixelhop/diditthough.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "dit": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.0",
+    "typescript": "^5.9.2",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}