@rose42/t3-feedback 0.1.0

package/dist/bridge/parse.js

@@ -0,0 +1,82 @@
+function isFeedbackEnvelope(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+/** POST body: raw envelope, or `{ envelope, threadId? }` for session reuse. */
+export function parseFeedbackPost(body) {
+    if (!isFeedbackEnvelope(body))
+        return null;
+    const record = body;
+    if ("envelope" in record) {
+        if (!isFeedbackEnvelope(record.envelope))
+            return null;
+        const threadId = typeof record.threadId === "string" && record.threadId.trim()
+            ? record.threadId.trim()
+            : undefined;
+        return threadId ? { envelope: record.envelope, threadId } : { envelope: record.envelope };
+    }
+    return { envelope: body };
+}
+/** Parse `?ids=a,b` from the threads probe URL. */
+export function parseThreadProbeIds(url) {
+    try {
+        const parsed = new URL(url, "http://t3-feedback.local");
+        const raw = parsed.searchParams.get("ids") ?? "";
+        return [
+            ...new Set(raw
+                .split(",")
+                .map((id) => id.trim())
+                .filter(Boolean)),
+        ];
+    }
+    catch {
+        return [];
+    }
+}
+/** POST body: `{ threadIds: string[] }` (also accepts singular `threadId`). */
+export function parseSettlePost(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return null;
+    const record = body;
+    if (typeof record.threadId === "string" && record.threadId.trim()) {
+        return [record.threadId.trim()];
+    }
+    if (!Array.isArray(record.threadIds))
+        return null;
+    const ids = [
+        ...new Set(record.threadIds
+            .filter((id) => typeof id === "string")
+            .map((id) => id.trim())
+            .filter(Boolean)),
+    ];
+    return ids;
+}
+/** Parse `{ threadId, environmentId?, projectId? }` from open query string or JSON body. */
+export function parseOpenHandoffRequest(url, body) {
+    const fromParts = (threadIdRaw, environmentIdRaw, projectIdRaw) => {
+        const threadId = typeof threadIdRaw === "string" ? threadIdRaw.trim() : "";
+        if (!threadId)
+            return null;
+        const environmentId = typeof environmentIdRaw === "string" && environmentIdRaw.trim()
+            ? environmentIdRaw.trim()
+            : undefined;
+        const projectId = typeof projectIdRaw === "string" && projectIdRaw.trim() ? projectIdRaw.trim() : undefined;
+        return {
+            threadId,
+            ...(environmentId ? { environmentId } : {}),
+            ...(projectId ? { projectId } : {}),
+        };
+    };
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+        const record = body;
+        const parsed = fromParts(record.threadId, record.environmentId, record.projectId);
+        if (parsed)
+            return parsed;
+    }
+    try {
+        const parsedUrl = new URL(url, "http://t3-feedback.local");
+        return fromParts(parsedUrl.searchParams.get("threadId"), parsedUrl.searchParams.get("environmentId"), parsedUrl.searchParams.get("projectId"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/bridge/paths.d.ts

@@ -0,0 +1,10 @@
+/** Default Vite middleware base path (also used when `basePath` is omitted). */
+export declare const T3_FEEDBACK_API_PATH = "/__t3-feedback";
+export declare const T3_FEEDBACK_THREADS_PATH = "/__t3-feedback/threads";
+export declare const T3_FEEDBACK_SETTLE_PATH = "/__t3-feedback/settle";
+export declare const T3_FEEDBACK_OPEN_PATH = "/__t3-feedback/open";
+/** Suffixes under a host-chosen base path (e.g. `/api/t3-feedback`). */
+export declare const T3_FEEDBACK_THREADS_SUFFIX = "/threads";
+export declare const T3_FEEDBACK_SETTLE_SUFFIX = "/settle";
+export declare const T3_FEEDBACK_OPEN_SUFFIX = "/open";
+export declare const T3_FEEDBACK_SOURCE_SUFFIX = "/source";

package/dist/bridge/paths.js

@@ -0,0 +1,10 @@
+/** Default Vite middleware base path (also used when `basePath` is omitted). */
+export const T3_FEEDBACK_API_PATH = "/__t3-feedback";
+export const T3_FEEDBACK_THREADS_PATH = "/__t3-feedback/threads";
+export const T3_FEEDBACK_SETTLE_PATH = "/__t3-feedback/settle";
+export const T3_FEEDBACK_OPEN_PATH = "/__t3-feedback/open";
+/** Suffixes under a host-chosen base path (e.g. `/api/t3-feedback`). */
+export const T3_FEEDBACK_THREADS_SUFFIX = "/threads";
+export const T3_FEEDBACK_SETTLE_SUFFIX = "/settle";
+export const T3_FEEDBACK_OPEN_SUFFIX = "/open";
+export const T3_FEEDBACK_SOURCE_SUFFIX = "/source";

package/dist/bridge/probeThreads.d.ts

@@ -0,0 +1,13 @@
+import type { ThreadProbeState } from "../types.js";
+/**
+ * Best-effort mapping from a shell thread object to working/settled.
+ * Unknown fields leave state as `"unknown"` so the client can fall back to TTL / dismiss.
+ */
+export declare function inferThreadProbeState(thread: unknown): ThreadProbeState;
+/** True when the shell thread is archived (excluded from continue pickers). */
+export declare function isShellThreadArchived(thread: unknown): boolean;
+/**
+ * Prefer explicit shell settle / liveness fields, then fall back to
+ * {@link inferThreadProbeState}.
+ */
+export declare function listItemStateFromShellThread(thread: unknown): ThreadProbeState;

package/dist/bridge/probeThreads.js

@@ -0,0 +1,66 @@
+/**
+ * Best-effort mapping from a shell thread object to working/settled.
+ * Unknown fields leave state as `"unknown"` so the client can fall back to TTL / dismiss.
+ */
+export function inferThreadProbeState(thread) {
+    if (!thread || typeof thread !== "object" || Array.isArray(thread))
+        return "unknown";
+    const record = thread;
+    const boolBusyKeys = ["busy", "isRunning", "running", "isGenerating"];
+    for (const key of boolBusyKeys) {
+        if (typeof record[key] === "boolean") {
+            return record[key] ? "working" : "settled";
+        }
+    }
+    const statusKeys = ["status", "agentStatus", "turnStatus", "runStatus", "state"];
+    for (const key of statusKeys) {
+        const raw = record[key];
+        if (typeof raw !== "string")
+            continue;
+        const value = raw.toLowerCase();
+        if (/^(idle|done|complete|completed|settled|finished|stopped|cancelled|canceled|error|failed)$/.test(value)) {
+            return "settled";
+        }
+        if (/^(running|working|active|busy|streaming|generating|in_progress|in-progress)$/.test(value)) {
+            return "working";
+        }
+    }
+    const nested = record.agent ?? record.turn ?? record.run;
+    if (nested && nested !== thread) {
+        const nestedState = inferThreadProbeState(nested);
+        if (nestedState !== "unknown")
+            return nestedState;
+    }
+    return "unknown";
+}
+/** True when the shell thread is archived (excluded from continue pickers). */
+export function isShellThreadArchived(thread) {
+    if (!thread || typeof thread !== "object" || Array.isArray(thread))
+        return false;
+    const archivedAt = thread.archivedAt;
+    return typeof archivedAt === "string" && archivedAt.trim().length > 0;
+}
+/**
+ * Prefer explicit shell settle / liveness fields, then fall back to
+ * {@link inferThreadProbeState}.
+ */
+export function listItemStateFromShellThread(thread) {
+    if (!thread || typeof thread !== "object" || Array.isArray(thread))
+        return "unknown";
+    const record = thread;
+    if (record.settledOverride === "settled")
+        return "settled";
+    if (record.backgroundLiveness === "working")
+        return "working";
+    if (record.settledOverride !== "active" &&
+        typeof record.settledAt === "string" &&
+        record.settledAt.trim().length > 0) {
+        return "settled";
+    }
+    const inferred = inferThreadProbeState(thread);
+    if (inferred !== "unknown")
+        return inferred;
+    if (record.backgroundLiveness === "monitoring")
+        return "working";
+    return "unknown";
+}

package/dist/bridge/readSource.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolve an app-relative source path (e.g. `app/[locale]/page.tsx`) under one
+ * of the workspace roots. Rejects path traversal and non-source extensions.
+ */
+export declare function readWorkspaceSourceFile(fileParam: string, workspaceRootHints: readonly string[]): Promise<{
+    absolutePath: string;
+    content: string;
+} | null>;

package/dist/bridge/readSource.js

@@ -0,0 +1,64 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const ALLOWED_EXT = new Set([".tsx", ".ts", ".jsx", ".js", ".mjs", ".cjs"]);
+/**
+ * Resolve an app-relative source path (e.g. `app/[locale]/page.tsx`) under one
+ * of the workspace roots. Rejects path traversal and non-source extensions.
+ */
+export async function readWorkspaceSourceFile(fileParam, workspaceRootHints) {
+    const cleaned = fileParam.replace(/\\/g, "/").replace(/^\/+/, "").trim();
+    if (!cleaned || cleaned.includes("\0") || cleaned.includes(".."))
+        return null;
+    if (path.isAbsolute(cleaned))
+        return null;
+    const ext = path.extname(cleaned);
+    if (!ALLOWED_EXT.has(ext))
+        return null;
+    // Prefer app/package sources; allow either apps/<pkg>/… or app/… (Next app cwd).
+    if (!cleaned.startsWith("app/") &&
+        !cleaned.startsWith("apps/") &&
+        !cleaned.startsWith("packages/") &&
+        !cleaned.startsWith("src/")) {
+        return null;
+    }
+    for (const root of workspaceRootHints) {
+        const absolutePath = path.resolve(root, cleaned);
+        const rootResolved = path.resolve(root);
+        if (absolutePath !== rootResolved && !absolutePath.startsWith(rootResolved + path.sep)) {
+            continue;
+        }
+        try {
+            const content = await fs.readFile(absolutePath, "utf8");
+            return { absolutePath, content };
+        }
+        catch {
+            // try next root (e.g. monorepo root vs apps/b2b cwd)
+        }
+    }
+    // When hint is a monorepo root and the file is `app/…`, try `apps/<pkg>/app/…`.
+    if (cleaned.startsWith("app/")) {
+        for (const root of workspaceRootHints) {
+            const appsDir = path.resolve(root, "apps");
+            let entries = [];
+            try {
+                entries = await fs.readdir(appsDir);
+            }
+            catch {
+                continue;
+            }
+            for (const appName of entries) {
+                if (appName.startsWith("."))
+                    continue;
+                const absolutePath = path.resolve(appsDir, appName, cleaned);
+                try {
+                    const content = await fs.readFile(absolutePath, "utf8");
+                    return { absolutePath, content };
+                }
+                catch {
+                    // continue
+                }
+            }
+        }
+    }
+    return null;
+}

package/dist/bridge/sendFeedback.d.ts

@@ -0,0 +1,99 @@
+import type { FeedbackEnvelope } from "@rose42/feedback-capture";
+import type { FeedbackSendResult, T3FeedbackReportTypeGlyphResolved, ThreadListItem, ThreadProbeResult, ThreadSettleResult } from "../types.js";
+import type { T3FeedbackOpenHandoff } from "../types.js";
+export type ShellSnapshot = {
+    snapshotSequence: number;
+    projects: Array<{
+        id: string;
+        title: string;
+        workspaceRoot: string;
+    }>;
+    threads: Array<{
+        id: string;
+        projectId: string;
+        title: string;
+        modelSelection: {
+            instanceId: string;
+            model: string;
+        };
+        branch: string | null;
+        [key: string]: unknown;
+    }>;
+};
+export type T3BridgeOptions = {
+    origin: string;
+    /**
+     * Browser-facing origin for Open-in-T3 links (may differ from `origin` when
+     * the API talks to an in-container host but the browser uses localhost).
+     */
+    openOrigin?: string;
+    /** Optional display-title prefix for newly created threads. */
+    threadTitlePrefix?: string;
+    /**
+     * When `"emoji"` or a custom map, new thread titles use emoji type prefixes
+     * instead of `Bug` / `Feedback` / `Suggestion`.
+     */
+    reportTypeGlyph?: T3FeedbackReportTypeGlyphResolved;
+    /**
+     * Reuse this thread when it still exists in the project snapshot.
+     * Stale / missing ids create a new thread instead.
+     */
+    threadId?: string;
+    workspaceRootHints: string[];
+    /** Optional pre-issued bearer token; otherwise `t3 auth session issue` */
+    token?: string;
+};
+export type ProbeThreadsOptions = Pick<T3BridgeOptions, "origin" | "workspaceRootHints" | "token">;
+/** Clear cached environment descriptors (tests). */
+export declare function clearT3EnvironmentIdCache(): void;
+export type T3EnvironmentDescriptor = {
+    environmentId: string;
+    label: string;
+};
+/**
+ * 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 declare function resolveT3Environment(apiOrigin: string): Promise<T3EnvironmentDescriptor>;
+/** @deprecated Prefer {@link resolveT3Environment}. */
+export declare function resolveT3EnvironmentId(apiOrigin: string): Promise<string>;
+/**
+ * Parse JSON from a `t3 … --json` stdout blob.
+ * Newer CLIs pretty-print; older ones emit a single line (sometimes after log lines).
+ */
+export declare function parseT3JsonStdout(stdout: string): unknown;
+/** Mint a one-time browser pairing credential (`t3 auth pairing create`). */
+export declare function issuePairingCredential(openOrigin: string): {
+    credential: string;
+    pairUrl: string;
+};
+/**
+ * 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 declare function createOpenHandoff(threadId: string, options: Pick<T3BridgeOptions, "origin" | "openOrigin">): Promise<T3FeedbackOpenHandoff>;
+export declare function pickProject(projects: Array<{
+    id: string;
+    title: string;
+    workspaceRoot: string;
+}>, hints: string[]): {
+    id: string;
+    title: string;
+    workspaceRoot: string;
+};
+/** Authenticate to T3 and start a turn with the feedback envelope. */
+export declare function sendFeedbackToT3(envelope: FeedbackEnvelope, options: T3BridgeOptions): Promise<FeedbackSendResult>;
+/** List non-archived threads for the matched T3 project (continue picker). */
+export declare function listThreadsInT3(options: ProbeThreadsOptions): Promise<ThreadListItem[]>;
+/** Probe working/settled state for feedback threads in the T3 shell snapshot. */
+export declare function probeThreadsInT3(threadIds: string[], options: ProbeThreadsOptions): Promise<ThreadProbeResult[]>;
+/**
+ * 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 declare function settleThreadsInT3(threadIds: string[], options: ProbeThreadsOptions): Promise<ThreadSettleResult[]>;