@rose42/t3-feedback 0.1.0

package/dist/bridge/sendFeedback.js

@@ -0,0 +1,417 @@
+import { spawnSync } from "node:child_process";
+import WebSocket from "ws";
+import { dataUrlSizeBytes, envelopeImageAttachments } from "./attachments.js";
+import { buildPairOpenUrl, buildThreadOpenUrl, deriveThreadTitle, formatFeedbackMessage, normalizeOrigin, resolveOpenOrigin, } from "./format.js";
+import { isShellThreadArchived, listItemStateFromShellThread } from "./probeThreads.js";
+const environmentCache = new Map();
+/** Clear cached environment descriptors (tests). */
+export function clearT3EnvironmentIdCache() {
+    environmentCache.clear();
+}
+/**
+ * Read this server's environment descriptor from the public well-known document.
+ * Cached per API origin for the process lifetime. Always use the bridge `origin`
+ * (same server that owns the thread) — never a browser-only openOrigin.
+ */
+export async function resolveT3Environment(apiOrigin) {
+    const key = normalizeOrigin(apiOrigin);
+    const cached = environmentCache.get(key);
+    if (cached)
+        return cached;
+    const res = await fetch(`${key}/.well-known/t3/environment`, {
+        headers: { Accept: "application/json" },
+    });
+    const body = (await res.json().catch(() => null));
+    const environmentId = body?.environmentId?.trim() ?? "";
+    if (!res.ok || !environmentId) {
+        throw new Error(`Failed to read T3 environment id from ${key}/.well-known/t3/environment: ${JSON.stringify(body)}`);
+    }
+    const label = body?.label?.trim() || environmentId;
+    const resolved = { environmentId, label };
+    environmentCache.set(key, resolved);
+    console.info(`[t3-feedback] T3 environment ${environmentId} (${label}) via ${key}`);
+    return resolved;
+}
+/** @deprecated Prefer {@link resolveT3Environment}. */
+export async function resolveT3EnvironmentId(apiOrigin) {
+    return (await resolveT3Environment(apiOrigin)).environmentId;
+}
+function issueToken() {
+    const result = spawnSync("t3", ["auth", "session", "issue", "--ttl", "8h", "--label", "t3-feedback-bridge", "--token-only"], { encoding: "utf8" });
+    if (result.status !== 0) {
+        throw new Error(`Failed to issue T3 session token: ${result.stderr || result.stdout || result.error}`);
+    }
+    const token = result.stdout.trim().split("\n").at(-1)?.trim();
+    if (!token)
+        throw new Error("t3 auth session issue returned an empty token");
+    return token;
+}
+/**
+ * Parse JSON from a `t3 … --json` stdout blob.
+ * Newer CLIs pretty-print; older ones emit a single line (sometimes after log lines).
+ */
+export function parseT3JsonStdout(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        throw new Error("t3 returned empty output");
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // Fall through — may be logs + trailing JSON, or a single compact line.
+    }
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start >= 0 && end > start) {
+        try {
+            return JSON.parse(trimmed.slice(start, end + 1));
+        }
+        catch {
+            // Fall through to last-line attempt.
+        }
+    }
+    const lastLine = trimmed.split("\n").at(-1)?.trim() ?? "";
+    try {
+        return JSON.parse(lastLine);
+    }
+    catch {
+        throw new Error(`t3 returned non-JSON: ${lastLine || trimmed.slice(0, 120)}`);
+    }
+}
+/** Mint a one-time browser pairing credential (`t3 auth pairing create`). */
+export function issuePairingCredential(openOrigin) {
+    const baseUrl = normalizeOrigin(openOrigin);
+    const result = spawnSync("t3", [
+        "auth",
+        "pairing",
+        "create",
+        "--ttl",
+        "5m",
+        "--label",
+        "t3-feedback-open",
+        "--base-url",
+        baseUrl,
+        "--json",
+    ], { encoding: "utf8" });
+    if (result.status !== 0) {
+        throw new Error(`Failed to mint T3 pairing token: ${result.stderr || result.stdout || result.error}`);
+    }
+    let parsed;
+    try {
+        parsed = parseT3JsonStdout(result.stdout);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`t3 auth pairing create ${detail}`);
+    }
+    const credential = parsed.credential?.trim() ?? "";
+    if (!credential)
+        throw new Error("t3 auth pairing create returned no credential");
+    // Always build from `openOrigin` so T3's server-runtime origin (often
+    // http://127.0.0.1:port) cannot override the browser-facing host.
+    return { credential, pairUrl: buildPairOpenUrl(baseUrl, credential) };
+}
+/**
+ * Build a seamless Open-in-T3 handoff: pair URL (auto-submits) + thread deep link.
+ * Call on click so the one-time pairing token is fresh.
+ *
+ * Environment id is always read from the bridge `origin` (the server that owns
+ * the thread). Client-supplied ids are ignored — they can be stale when multiple
+ * apps share a Vite origin / sessionStorage.
+ */
+export async function createOpenHandoff(threadId, options) {
+    const browserOrigin = resolveOpenOrigin(options.origin, options.openOrigin);
+    const { environmentId } = await resolveT3Environment(options.origin);
+    const threadUrl = buildThreadOpenUrl(browserOrigin, threadId, environmentId);
+    const { pairUrl } = issuePairingCredential(browserOrigin);
+    return { pairUrl, threadUrl, environmentId };
+}
+async function getWsTicket(origin, token) {
+    const res = await fetch(`${origin}/api/auth/websocket-ticket`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+        },
+        body: "{}",
+    });
+    const body = (await res.json());
+    if (!res.ok || !body.ticket) {
+        throw new Error(`websocket-ticket failed: ${JSON.stringify(body)}`);
+    }
+    return body.ticket;
+}
+class T3RpcClient {
+    #ws;
+    #pending = new Map();
+    #streams = new Map();
+    constructor(ws) {
+        this.#ws = ws;
+        ws.on("message", (raw) => this.#onMessage(String(raw)));
+    }
+    static connect(wsUrl) {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(wsUrl);
+            ws.once("open", () => resolve(new T3RpcClient(ws)));
+            ws.once("error", reject);
+            ws.once("unexpected-response", (_req, res) => {
+                let body = "";
+                res.on("data", (chunk) => {
+                    body += chunk;
+                });
+                res.on("end", () => {
+                    reject(new Error(`WS upgrade ${res.statusCode}: ${body}`));
+                });
+            });
+        });
+    }
+    #onMessage(raw) {
+        const msg = JSON.parse(raw);
+        if (msg._tag === "Chunk" && msg.requestId) {
+            const stream = this.#streams.get(msg.requestId);
+            if (stream) {
+                for (const value of msg.values ?? [])
+                    stream.onChunk(value);
+            }
+            this.#ws.send(JSON.stringify({ _tag: "Ack", requestId: msg.requestId }));
+            return;
+        }
+        if (msg._tag === "Exit" && msg.requestId && msg.exit) {
+            const pending = this.#pending.get(msg.requestId);
+            if (!pending)
+                return;
+            this.#pending.delete(msg.requestId);
+            clearTimeout(pending.timer);
+            if (msg.exit._tag === "Success")
+                pending.resolve(msg.exit.value);
+            else
+                pending.reject(new Error(JSON.stringify(msg.exit)));
+            return;
+        }
+        if (msg._tag === "Defect") {
+            console.warn("[t3-feedback] RPC defect", msg.defect);
+        }
+    }
+    request(tag, payload, timeoutMs = 20_000) {
+        const id = crypto.randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new Error(`RPC timeout: ${tag}`));
+            }, timeoutMs);
+            this.#pending.set(id, { resolve, reject, timer });
+            this.#ws.send(JSON.stringify({ _tag: "Request", id, tag, payload, headers: [] }));
+        });
+    }
+    subscribeOnce(tag, payload, predicate, timeoutMs = 20_000) {
+        const id = crypto.randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#streams.delete(id);
+                reject(new Error(`subscribe timeout: ${tag}`));
+            }, timeoutMs);
+            this.#streams.set(id, {
+                onChunk: (value) => {
+                    if (!predicate(value))
+                        return;
+                    clearTimeout(timer);
+                    this.#streams.delete(id);
+                    resolve(value);
+                },
+            });
+            this.#ws.send(JSON.stringify({ _tag: "Request", id, tag, payload, headers: [] }));
+        });
+    }
+    close() {
+        this.#ws.close();
+    }
+}
+async function withShellClient(options, fn) {
+    const token = options.token?.trim() || issueToken();
+    const ticket = await getWsTicket(options.origin, token);
+    const wsUrl = `${options.origin.replace(/^http/, "ws")}/ws?wsTicket=${encodeURIComponent(ticket)}`;
+    const client = await T3RpcClient.connect(wsUrl);
+    try {
+        const shellEvent = (await client.subscribeOnce("orchestration.subscribeShell", { requestCompletionMarker: true }, (value) => typeof value === "object" &&
+            value !== null &&
+            value.kind === "snapshot"));
+        return await fn(client, shellEvent.snapshot);
+    }
+    finally {
+        client.close();
+    }
+}
+export function pickProject(projects, hints) {
+    for (const hint of hints) {
+        const match = projects.find((p) => p.workspaceRoot.includes(hint));
+        if (match)
+            return match;
+    }
+    if (projects[0])
+        return projects[0];
+    throw new Error("No T3 projects available");
+}
+/** Authenticate to T3 and start a turn with the feedback envelope. */
+export async function sendFeedbackToT3(envelope, options) {
+    return withShellClient(options, async (client, snapshot) => {
+        const project = pickProject(snapshot.projects, options.workspaceRootHints);
+        const modelSelection = snapshot.threads.find((t) => t.projectId === project.id)
+            ?.modelSelection ??
+            snapshot.threads[0]?.modelSelection ?? {
+            instanceId: "cursor",
+            model: "default",
+        };
+        const branch = snapshot.threads.find((t) => t.projectId === project.id)?.branch ?? null;
+        const existing = options.threadId
+            ? snapshot.threads.find((t) => t.id === options.threadId && t.projectId === project.id)
+            : undefined;
+        let threadId;
+        let threadTitle;
+        if (existing) {
+            threadId = existing.id;
+            threadTitle = existing.title;
+        }
+        else {
+            threadId = crypto.randomUUID();
+            threadTitle = deriveThreadTitle(envelope, options.threadTitlePrefix, options.reportTypeGlyph ?? "icon");
+            await client.request("orchestration.dispatchCommand", {
+                type: "thread.create",
+                commandId: crypto.randomUUID(),
+                threadId,
+                projectId: project.id,
+                title: threadTitle,
+                modelSelection,
+                runtimeMode: "full-access",
+                interactionMode: "default",
+                branch,
+                worktreePath: null,
+                createdAt: new Date().toISOString(),
+            });
+        }
+        const imageAttachments = envelopeImageAttachments(envelope);
+        const attachments = imageAttachments.map((item, index) => {
+            const mimeType = item.mimeType ?? "image/png";
+            const defaultName = imageAttachments.length === 1 ? "feedback.png" : `feedback-${index + 1}.png`;
+            return {
+                type: "image",
+                name: item.name ?? defaultName,
+                mimeType,
+                sizeBytes: dataUrlSizeBytes(item.dataUrl),
+                dataUrl: item.dataUrl,
+            };
+        });
+        const result = (await client.request("orchestration.dispatchCommand", {
+            type: "thread.turn.start",
+            commandId: crypto.randomUUID(),
+            threadId,
+            message: {
+                messageId: crypto.randomUUID(),
+                role: "user",
+                text: formatFeedbackMessage(envelope),
+                attachments,
+            },
+            runtimeMode: "full-access",
+            interactionMode: "default",
+            createdAt: new Date().toISOString(),
+        }));
+        const browserOrigin = resolveOpenOrigin(options.origin, options.openOrigin);
+        const { environmentId, label: environmentLabel } = await resolveT3Environment(options.origin);
+        return {
+            threadId,
+            threadTitle,
+            projectId: project.id,
+            environmentId,
+            environmentLabel,
+            sequence: result.sequence,
+            openUrl: buildThreadOpenUrl(browserOrigin, threadId, environmentId),
+        };
+    });
+}
+/** List non-archived threads for the matched T3 project (continue picker). */
+export async function listThreadsInT3(options) {
+    return withShellClient(options, async (_client, snapshot) => {
+        const project = pickProject(snapshot.projects, options.workspaceRootHints);
+        const items = [];
+        for (const thread of snapshot.threads) {
+            if (thread.projectId !== project.id)
+                continue;
+            if (isShellThreadArchived(thread))
+                continue;
+            const threadId = typeof thread.id === "string" ? thread.id.trim() : "";
+            const title = typeof thread.title === "string" ? thread.title.trim() : "";
+            if (!threadId || !title)
+                continue;
+            const updatedAt = typeof thread.updatedAt === "string" && thread.updatedAt.trim()
+                ? thread.updatedAt.trim()
+                : undefined;
+            items.push({
+                threadId,
+                title,
+                state: listItemStateFromShellThread(thread),
+                ...(updatedAt ? { updatedAt } : {}),
+            });
+        }
+        items.sort((a, b) => {
+            const aAt = a.updatedAt ?? "";
+            const bAt = b.updatedAt ?? "";
+            if (aAt !== bAt)
+                return bAt.localeCompare(aAt);
+            return a.title.localeCompare(b.title);
+        });
+        return items;
+    });
+}
+/** Probe working/settled state for feedback threads in the T3 shell snapshot. */
+export async function probeThreadsInT3(threadIds, options) {
+    const ids = [...new Set(threadIds.map((id) => id.trim()).filter(Boolean))];
+    if (ids.length === 0)
+        return [];
+    return withShellClient(options, async (_client, snapshot) => {
+        const project = pickProject(snapshot.projects, options.workspaceRootHints);
+        return ids.map((threadId) => {
+            const thread = snapshot.threads.find((t) => t.id === threadId && t.projectId === project.id);
+            if (!thread) {
+                const any = snapshot.threads.find((t) => t.id === threadId);
+                if (!any)
+                    return { threadId, state: "settled" };
+                return { threadId, state: listItemStateFromShellThread(any) };
+            }
+            return { threadId, state: listItemStateFromShellThread(thread) };
+        });
+    });
+}
+/**
+ * Settle feedback threads in T3 (`thread.settle`). Missing threads are reported
+ * as `{ ok: true, skipped: true }` so dismiss can clear the local activity list.
+ */
+export async function settleThreadsInT3(threadIds, options) {
+    const ids = [...new Set(threadIds.map((id) => id.trim()).filter(Boolean))];
+    if (ids.length === 0)
+        return [];
+    return withShellClient(options, async (client, snapshot) => {
+        const results = [];
+        for (const threadId of ids) {
+            const exists = snapshot.threads.some((t) => t.id === threadId);
+            if (!exists) {
+                results.push({ threadId, ok: true, skipped: true });
+                continue;
+            }
+            try {
+                await client.request("orchestration.dispatchCommand", {
+                    type: "thread.settle",
+                    commandId: crypto.randomUUID(),
+                    threadId,
+                });
+                results.push({ threadId, ok: true });
+            }
+            catch (error) {
+                results.push({
+                    threadId,
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return results;
+    });
+}

package/dist/cli/bin.d.ts

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

package/dist/cli/bin.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { CLI_NAME } from "./constants.js";
+import { parseInitArgs, printInitHelp, runInit } from "./init.js";
+async function main() {
+    const argv = process.argv.slice(2);
+    const [command, ...rest] = argv;
+    if (!command || command === "--help" || command === "-h") {
+        console.log(`Usage: ${CLI_NAME} <command>
+
+Commands:
+  init    Detect project, confirm, install if needed, wire connector files
+
+Run \`${CLI_NAME} init --help\` for init options.
+`);
+        process.exit(command ? 0 : 1);
+    }
+    if (command === "init") {
+        try {
+            if (rest.includes("--help") || rest.includes("-h")) {
+                printInitHelp();
+                process.exit(0);
+            }
+            const options = parseInitArgs(rest);
+            const code = await runInit(options);
+            process.exit(code);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === "help") {
+                printInitHelp();
+                process.exit(0);
+            }
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    }
+    console.error(`Unknown command: ${command}`);
+    console.error(`Try \`${CLI_NAME} init\``);
+    process.exit(1);
+}
+void main();

package/dist/cli/constants.d.ts

@@ -0,0 +1,4 @@
+/** Published package name (update when renaming off *). */
+export declare const PACKAGE_NAME = "@rose42/t3-feedback";
+/** CLI binary name. */
+export declare const CLI_NAME = "t3-feedback";

package/dist/cli/constants.js

@@ -0,0 +1,4 @@
+/** Published package name (update when renaming off *). */
+export const PACKAGE_NAME = "@rose42/t3-feedback";
+/** CLI binary name. */
+export const CLI_NAME = "t3-feedback";

package/dist/cli/detect.d.ts

@@ -0,0 +1,17 @@
+export type HostKind = "next" | "vite" | "node";
+export type ProjectDetection = {
+    root: string;
+    host: HostKind;
+    reasons: string[];
+    packageJsonPath: string | null;
+    viteConfigPath: string | null;
+    nextConfigPath: string | null;
+    hasAppDir: boolean;
+    alreadyInstalled: boolean;
+    alreadyWiredHint: boolean;
+};
+/**
+ * Detect the best host connector for `root`.
+ * Priority: Next (app/pages) > Vite config > generic Node.
+ */
+export declare function detectProject(root: string): ProjectDetection;

package/dist/cli/detect.js

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PACKAGE_NAME } from "./constants.js";
+const VITE_CONFIG_NAMES = [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "vite.config.cjs",
+];
+const NEXT_CONFIG_NAMES = [
+    "next.config.ts",
+    "next.config.mjs",
+    "next.config.js",
+    "next.config.cjs",
+];
+function readPackageJson(root) {
+    const pkgPath = path.join(root, "package.json");
+    if (!fs.existsSync(pkgPath))
+        return null;
+    try {
+        const data = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        return { path: pkgPath, data };
+    }
+    catch {
+        return null;
+    }
+}
+function depMap(data) {
+    const deps = {
+        ...(typeof data.dependencies === "object" && data.dependencies
+            ? data.dependencies
+            : {}),
+        ...(typeof data.devDependencies === "object" && data.devDependencies
+            ? data.devDependencies
+            : {}),
+        ...(typeof data.optionalDependencies === "object" && data.optionalDependencies
+            ? data.optionalDependencies
+            : {}),
+    };
+    return deps;
+}
+function firstExisting(root, names) {
+    for (const name of names) {
+        const full = path.join(root, name);
+        if (fs.existsSync(full))
+            return full;
+    }
+    return null;
+}
+function contentMentionsPackage(filePath) {
+    if (!filePath || !fs.existsSync(filePath))
+        return false;
+    try {
+        const text = fs.readFileSync(filePath, "utf8");
+        return text.includes(PACKAGE_NAME) || text.includes("t3FeedbackPlugin");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detect the best host connector for `root`.
+ * Priority: Next (app/pages) > Vite config > generic Node.
+ */
+export function detectProject(root) {
+    const abs = path.resolve(root);
+    const pkg = readPackageJson(abs);
+    const deps = pkg ? depMap(pkg.data) : {};
+    const reasons = [];
+    const viteConfigPath = firstExisting(abs, VITE_CONFIG_NAMES);
+    const nextConfigPath = firstExisting(abs, NEXT_CONFIG_NAMES);
+    const hasNextDep = Boolean(deps.next);
+    const hasViteDep = Boolean(deps.vite);
+    const hasAppDir = fs.existsSync(path.join(abs, "app"));
+    const hasPagesDir = fs.existsSync(path.join(abs, "pages"));
+    const alreadyInstalled = Boolean(deps[PACKAGE_NAME]);
+    let host = "node";
+    if (hasNextDep || nextConfigPath || hasAppDir || hasPagesDir) {
+        host = "next";
+        if (hasNextDep)
+            reasons.push("package.json lists next");
+        if (nextConfigPath)
+            reasons.push(`found ${path.basename(nextConfigPath)}`);
+        if (hasAppDir)
+            reasons.push("found app/");
+        if (hasPagesDir)
+            reasons.push("found pages/");
+    }
+    else if (viteConfigPath || hasViteDep) {
+        host = "vite";
+        if (viteConfigPath)
+            reasons.push(`found ${path.basename(viteConfigPath)}`);
+        if (hasViteDep)
+            reasons.push("package.json lists vite");
+    }
+    else {
+        reasons.push("no Next/Vite markers — generic Node bridge stub");
+    }
+    const nextRoute = path.join(abs, "app", "api", "t3-feedback", "[[...path]]", "route.ts");
+    const alreadyWiredHint = host === "vite"
+        ? contentMentionsPackage(viteConfigPath)
+        : host === "next"
+            ? fs.existsSync(nextRoute) || contentMentionsPackage(nextConfigPath)
+            : fs.existsSync(path.join(abs, "t3-feedback-bridge.mjs")) ||
+                fs.existsSync(path.join(abs, "t3-feedback-bridge.ts"));
+    return {
+        root: abs,
+        host,
+        reasons,
+        packageJsonPath: pkg?.path ?? null,
+        viteConfigPath,
+        nextConfigPath,
+        hasAppDir,
+        alreadyInstalled,
+        alreadyWiredHint,
+    };
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,4 @@
+export { PACKAGE_NAME, CLI_NAME } from "./constants.js";
+export { detectProject, type HostKind, type ProjectDetection } from "./detect.js";
+export { detectPackageManager, installDevDependency, type PackageManager } from "./pm.js";
+export { runInit, parseInitArgs, printInitHelp, type InitOptions } from "./init.js";

package/dist/cli/index.js

@@ -0,0 +1,4 @@
+export { PACKAGE_NAME, CLI_NAME } from "./constants.js";
+export { detectProject } from "./detect.js";
+export { detectPackageManager, installDevDependency } from "./pm.js";
+export { runInit, parseInitArgs, printInitHelp } from "./init.js";

package/dist/cli/init.d.ts

@@ -0,0 +1,18 @@
+import { type HostKind } from "./detect.js";
+export type InitOptions = {
+    cwd?: string;
+    /** Skip prompts (assume yes). */
+    yes?: boolean;
+    /** Print the plan only. */
+    dryRun?: boolean;
+    /** Never run package install. */
+    noInstall?: boolean;
+    /** Force host instead of detection. */
+    host?: HostKind;
+};
+/**
+ * Hybrid init: detect host → confirm → install if missing → wire files.
+ */
+export declare function runInit(options?: InitOptions): Promise<number>;
+export declare function parseInitArgs(argv: string[]): InitOptions;
+export declare function printInitHelp(): void;