@the-portland-company/devnotes 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @the-portland-company/devnotes
+
+Forge-backed DevNotes and bug reporting for server-capable React and Next.js apps.
+
+This package is Forge-only. It does not ship a local database, SQL schema, Supabase adapter, or migration path.
+
+## Install
+
+```bash
+npm install @the-portland-company/devnotes
+```
+
+Peer dependencies:
+
+- `react` `^18 || ^19`
+- `react-dom` `^18 || ^19`
+
+## Assumptions
+
+- The browser package never talks to Forge directly
+- The host app exposes a server-side proxy at `/api/devnotes`
+- The host app authenticates users and passes a bearer token to the proxy
+- Forge credentials are stored only on the server side
+
+## Quick start
+
+```bash
+npx devnotes-setup
+```
+
+Then wire the generated wrapper component to your auth token source and implement the generated proxy backend against Forge.
+
+## Package entrypoints
+
+- `@the-portland-company/devnotes`
+- `@the-portland-company/devnotes/next`
+- `@the-portland-company/devnotes/express`
+- `@the-portland-company/devnotes/styles.css`
+
+## What this package ships
+
+- React UI components for in-app bug reporting and DevNotes overlays
+- A browser client that talks to your host app at `/api/devnotes`
+- Next.js and Express proxy helpers for server-side routing
+- A `devnotes-setup` CLI that copies starter integration templates into a host app
+
+## Client usage
+
+```tsx
+import {
+  DevNotesButton,
+  DevNotesProvider,
+  createDevNotesClient,
+} from '@the-portland-company/devnotes';
+import '@the-portland-company/devnotes/styles.css';
+
+const client = createDevNotesClient({
+  getAuthToken: async () => session.accessToken,
+});
+
+export function AppDevNotes({ children }) {
+  return (
+    <DevNotesProvider adapter={client} user={{ id: session.user.id, email: session.user.email }}>
+      {children}
+      <DevNotesButton />
+    </DevNotesProvider>
+  );
+}
+```
+
+## Server helpers
+
+- `@the-portland-company/devnotes/next`
+- `@the-portland-company/devnotes/express`
+
+These provide request-routing helpers for a host proxy. They do not implement Forge access for you; your app backend remains responsible for the Forge integration.
+
+## Host app requirements
+
+- Expose a server-side proxy at `/api/devnotes`
+- Authenticate the current user in the host app
+- Return a bearer token from `getAuthToken()`
+- Keep Forge credentials server-side only
+- Translate DevNotes operations into real Forge API requests
+
+## Storage model
+
+- The browser package never talks to a database directly
+- The package does not persist to Supabase, Postgres, SQLite, or any local store
+- Your host proxy must translate DevNotes operations into real Focus Forge API calls
+- App-level Forge credentials must stay on the server side

package/bin/setup.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const BOLD = '\x1b[1m';
+const GREEN = '\x1b[32m';
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RESET = '\x1b[0m';
+
+function log(message) {
+  console.log(message);
+}
+
+function ok(message) {
+  log(`${GREEN}✓${RESET} ${message}`);
+}
+
+function warn(message) {
+  log(`${YELLOW}⚠${RESET} ${message}`);
+}
+
+function title(message) {
+  log(`\n${BOLD}${CYAN}${message}${RESET}`);
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function detectProject(projectRoot) {
+  const pkg = readJson(path.join(projectRoot, 'package.json')) || {};
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  if (deps.next) return 'next';
+  if (deps.express || deps.fastify || deps.koa || deps.hono) return 'server-react';
+  return 'unknown';
+}
+
+function resolveTemplate(projectRoot, fileName) {
+  try {
+    const pkgDir = path.dirname(
+      require.resolve('@the-portland-company/devnotes/package.json', { paths: [projectRoot] })
+    );
+    return path.join(pkgDir, 'templates', fileName);
+  } catch {
+    return path.join(__dirname, '..', 'templates', fileName);
+  }
+}
+
+function writeIfMissing(targetPath, content) {
+  if (fs.existsSync(targetPath)) {
+    warn(`Skipped existing file: ${path.relative(process.cwd(), targetPath)}`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, content);
+  ok(`Created ${path.relative(process.cwd(), targetPath)}`);
+}
+
+function copyTemplate(projectRoot, templateName, destination) {
+  const source = resolveTemplate(projectRoot, templateName);
+  const content = fs.readFileSync(source, 'utf8');
+  writeIfMissing(path.join(projectRoot, destination), content);
+}
+
+async function main() {
+  const projectRoot = process.cwd();
+  const projectType = detectProject(projectRoot);
+
+  title('@the-portland-company/devnotes setup');
+  log(`Detected project type: ${BOLD}${projectType}${RESET}`);
+
+  if (projectType === 'next') {
+    copyTemplate(projectRoot, 'NextDevNotesRoute.ts', 'app/api/devnotes/[...slug]/route.ts');
+    copyTemplate(projectRoot, 'DevNotesWrapper.tsx', 'src/components/DevNotesWrapper.tsx');
+  } else if (projectType === 'server-react') {
+    copyTemplate(projectRoot, 'ExpressDevNotesProxy.ts', 'src/server/devnotesProxy.ts');
+    copyTemplate(projectRoot, 'DevNotesWrapper.tsx', 'src/components/DevNotesWrapper.tsx');
+  } else {
+    warn('Could not detect Next.js or a server-capable React app.');
+    warn('Copy the templates manually from node_modules/@the-portland-company/devnotes/templates.');
+  }
+
+  title('Required configuration');
+  log('- Add a server-side Forge integration behind `/api/devnotes`.');
+  log('- Provide a host auth token via `getAuthToken()` in `DevNotesWrapper.tsx`.');
+  log('- Set server env vars like `FOCUS_FORGE_BASE_URL`, `FOCUS_FORGE_PAT`, and `FOCUS_FORGE_PROJECT_NAME`.');
+  log('- Import `@the-portland-company/devnotes/styles.css` once in your client bundle.');
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/index.d.mts

@@ -0,0 +1,261 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { D as DevNotesClientAdapter, a as DevNotesUser, b as DevNotesConfig, B as BugReport, c as BugReportType, T as TaskList, d as BugReportCreator, e as DevNotesCapabilities, f as DevNotesAppLinkStatus, N as NotifyEvent, A as AiProvider, g as DevNotesRole, h as DevNotesClientOptions, i as BugCaptureContext } from './types-xqGNcAbZ.mjs';
+export { j as AiAssistResult, k as AiConversationMessage, l as BugReportCreateData, m as BugReportMessage, n as DevNotesLinkAppInput } from './types-xqGNcAbZ.mjs';
+
+type DevNotesContextValue = {
+    isEnabled: boolean;
+    setIsEnabled: (enabled: boolean) => void;
+    showBugsAlways: boolean;
+    setShowBugsAlways: (show: boolean) => void;
+    hideResolvedClosed: boolean;
+    setHideResolvedClosed: (hide: boolean) => void;
+    bugReports: BugReport[];
+    bugReportTypes: BugReportType[];
+    taskLists: TaskList[];
+    userProfiles: Record<string, BugReportCreator>;
+    unreadCounts: Record<string, number>;
+    currentPageBugReports: BugReport[];
+    collaborators: BugReportCreator[];
+    loadBugReports: () => Promise<void>;
+    loadBugReportTypes: () => Promise<void>;
+    loadTaskLists: () => Promise<void>;
+    createBugReport: (report: Omit<BugReport, 'id' | 'created_at' | 'updated_at' | 'created_by' | 'resolved_at' | 'resolved_by'>) => Promise<BugReport | null>;
+    updateBugReport: (id: string, updates: Partial<BugReport>) => Promise<BugReport | null>;
+    deleteBugReport: (id: string) => Promise<boolean>;
+    createTaskList: (name: string) => Promise<TaskList | null>;
+    addBugReportType: (name: string) => Promise<BugReportType | null>;
+    deleteBugReportType: (id: string) => Promise<boolean>;
+    loadUnreadCounts: () => Promise<void>;
+    markMessagesAsRead: (reportId: string, messageIds: string[]) => Promise<void>;
+    user: DevNotesUser;
+    adapter: DevNotesClientAdapter;
+    capabilities: DevNotesCapabilities;
+    appLinkStatus: DevNotesAppLinkStatus | null;
+    refreshCapabilities: () => Promise<void>;
+    refreshAppLinkStatus: () => Promise<void>;
+    onNotify?: (event: NotifyEvent) => void;
+    aiProvider?: AiProvider;
+    requireAi: boolean;
+    role: DevNotesRole;
+    loading: boolean;
+    error: string | null;
+    dotContainer: HTMLDivElement | null;
+    compensate: (viewportX: number, viewportY: number) => {
+        x: number;
+        y: number;
+    };
+};
+type DevNotesProviderProps = {
+    adapter: DevNotesClientAdapter;
+    user: DevNotesUser;
+    config?: DevNotesConfig;
+    children: ReactNode;
+};
+declare function DevNotesProvider({ adapter, user, config, children }: DevNotesProviderProps): react_jsx_runtime.JSX.Element;
+declare function useDevNotes(): DevNotesContextValue;
+
+type DevNotesButtonProps = {
+    /** Position of the floating button */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Called when user clicks "View Tasks" in the menu. If omitted, a built-in task panel opens. */
+    onViewTasks?: () => void;
+    /** Called when user clicks "Settings" in the menu */
+    onSettings?: () => void;
+    /** Custom icon component for the menu trigger */
+    icon?: React.ComponentType<{
+        size?: number;
+        color?: string;
+    }>;
+    /** Optional: ID of a report to open immediately */
+    openReportId?: string | null;
+    /** Called when the opened report modal is closed */
+    onOpenReportClose?: () => void;
+    /** Called when user wants to navigate to a report's page (used by built-in task list) */
+    onNavigateToPage?: (pageUrl: string, reportId: string) => void;
+};
+declare function DevNotesButton({ position, onViewTasks, onSettings, icon, openReportId, onOpenReportClose, onNavigateToPage, }: DevNotesButtonProps): react_jsx_runtime.JSX.Element | null;
+
+type DevNotesOverlayProps = {
+    /** Optional: ID of a report to open immediately */
+    openReportId?: string | null;
+    /** Called when the opened report is closed */
+    onOpenReportClose?: () => void;
+};
+declare function DevNotesOverlay({ openReportId, onOpenReportClose, }?: DevNotesOverlayProps): react_jsx_runtime.JSX.Element | null;
+
+type DevNotesMenuProps = {
+    /** Called when user clicks "View Tasks" */
+    onViewTasks?: () => void;
+    /** Called when user clicks "Settings" */
+    onSettings?: () => void;
+    /** Custom icon component for the menu trigger */
+    icon?: React.ComponentType<{
+        size?: number;
+        color?: string;
+    }>;
+    /** Position of the parent button — controls dropdown alignment */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Direction the dropdown opens — default 'down' */
+    dropdownDirection?: 'up' | 'down';
+};
+declare function DevNotesMenu({ onViewTasks, onSettings, icon: IconComponent, position, dropdownDirection }: DevNotesMenuProps): react_jsx_runtime.JSX.Element | null;
+
+type DevNotesFormProps = {
+    pageUrl: string;
+    xPosition?: number;
+    yPosition?: number;
+    targetSelector?: string | null;
+    targetRelativeX?: number | null;
+    targetRelativeY?: number | null;
+    existingReport?: BugReport | null;
+    onSave: (report: BugReport) => void;
+    onCancel: () => void;
+    onDelete?: () => void;
+};
+declare function DevNotesForm({ pageUrl, xPosition, yPosition, targetSelector, targetRelativeX, targetRelativeY, existingReport, onSave, onCancel, onDelete, }: DevNotesFormProps): react_jsx_runtime.JSX.Element;
+
+type DevNotesDotProps = {
+    report: BugReport;
+};
+declare function DevNotesDot({ report }: DevNotesDotProps): react_jsx_runtime.JSX.Element | null;
+
+type DevNotesDiscussionProps = {
+    report: BugReport;
+};
+declare function DevNotesDiscussion({ report }: DevNotesDiscussionProps): react_jsx_runtime.JSX.Element;
+
+type DevNotesTaskListProps = {
+    /** Called when the user wants to navigate to the page where a report was filed */
+    onNavigateToPage?: (pageUrl: string, reportId: string) => void;
+    /** Called when the close/back button is clicked (if rendered as an overlay) */
+    onClose?: () => void;
+    /** Title shown at the top */
+    title?: string;
+};
+declare function DevNotesTaskList({ onNavigateToPage, onClose, title, }: DevNotesTaskListProps): react_jsx_runtime.JSX.Element;
+
+declare function createDevNotesClient(options: DevNotesClientOptions): DevNotesClientAdapter;
+
+type BugAnchorMetadata = {
+    targetSelector: string | null;
+    targetRelativeX: number | null;
+    targetRelativeY: number | null;
+};
+type BugPositionPayload = BugAnchorMetadata & {
+    x: number;
+    y: number;
+};
+/**
+ * Normalize a page URL for bug report storage.
+ * Strips hash fragments and trailing slashes. Preserves all query params.
+ */
+declare const normalizePageUrl: (value: string) => string;
+declare const calculateBugPositionFromPoint: ({ clientX, clientY, elementsToIgnore, }: {
+    clientX: number;
+    clientY: number;
+    elementsToIgnore?: Array<HTMLElement | null | undefined>;
+}) => BugPositionPayload;
+/**
+ * Resolve a bug report's position to viewport coordinates for `position: fixed` rendering.
+ *
+ * Priority 1: Find the anchored element by CSS selector and calculate viewport-relative
+ *             position from its current bounding rect. This makes the dot track the element.
+ * Priority 2: Fall back to stored page coordinates converted to viewport coordinates.
+ */
+declare const resolveBugReportCoordinates: (report: BugReport) => {
+    x: number;
+    y: number;
+} | null;
+
+declare function deriveRouteLabelFromUrl(rawUrl: string): string;
+declare function detectBrowserName(userAgent: string): string;
+declare function buildCaptureContext(pageUrl: string): BugCaptureContext | null;
+
+type AiFixPayload = {
+    source: string;
+    copied_at: string;
+    report: {
+        id: string | null;
+        title: string | null;
+        status: BugReport['status'];
+        severity: BugReport['severity'];
+        task_list_id: string | null;
+        types: string[];
+        type_names: string[];
+        approved: boolean;
+        ai_ready: boolean;
+    };
+    narrative: {
+        description: string | null;
+        expected_behavior: string | null;
+        actual_behavior: string | null;
+        ai_description: string | null;
+        response: string | null;
+    };
+    context: {
+        page_url: string;
+        route_label: string;
+        x_position: number;
+        y_position: number;
+        target_selector: string | null;
+        target_relative_x: number | null;
+        target_relative_y: number | null;
+        capture_context: BugCaptureContext | null;
+    };
+    workflow: {
+        assigned_to: string | null;
+        resolved_by: string | null;
+        created_by: string;
+        created_at: string | null;
+        updated_at: string | null;
+    };
+};
+type BuildAiFixPayloadParams = {
+    source?: string;
+    copiedAt?: string;
+    report: {
+        id?: string | null;
+        title?: string | null;
+        status: BugReport['status'];
+        severity: BugReport['severity'];
+        taskListId?: string | null;
+        types: string[];
+        typeNames: string[];
+        approved: boolean;
+        aiReady: boolean;
+    };
+    narrative: {
+        description?: string | null;
+        expectedBehavior?: string | null;
+        actualBehavior?: string | null;
+        aiDescription?: string | null;
+        response?: string | null;
+    };
+    context: {
+        pageUrl: string;
+        routeLabel: string;
+        xPosition: number;
+        yPosition: number;
+        targetSelector?: string | null;
+        targetRelativeX?: number | null;
+        targetRelativeY?: number | null;
+        captureContext?: BugCaptureContext | null;
+    };
+    workflow: {
+        assignedTo?: string | null;
+        resolvedBy?: string | null;
+        createdBy: string;
+        createdAt?: string | null;
+        updatedAt?: string | null;
+    };
+};
+declare function buildAiFixPayload(params: BuildAiFixPayloadParams): AiFixPayload;
+declare function formatAiFixPayloadForCopy(payload: AiFixPayload): string;
+
+declare const useBugReportPosition: (report: BugReport | null) => {
+    x: number;
+    y: number;
+} | null;
+
+export { type AiFixPayload, AiProvider, BugCaptureContext, BugReport, BugReportCreator, BugReportType, type BuildAiFixPayloadParams, DevNotesAppLinkStatus, DevNotesButton, DevNotesCapabilities, DevNotesClientOptions, DevNotesConfig, DevNotesDiscussion, DevNotesDot, DevNotesForm, DevNotesMenu, DevNotesOverlay, DevNotesProvider, DevNotesRole, DevNotesTaskList, DevNotesUser, NotifyEvent, TaskList, buildAiFixPayload, buildCaptureContext, calculateBugPositionFromPoint, createDevNotesClient, deriveRouteLabelFromUrl, detectBrowserName, formatAiFixPayloadForCopy, normalizePageUrl, resolveBugReportCoordinates, useBugReportPosition, useDevNotes };