@peaske7/readit 0.1.6 → 0.1.8

package/src/App.tsx

@@ -13,6 +13,7 @@ import { TableOfContents } from "./components/TableOfContents";
 import { textVariants } from "./components/ui/Text";
 import { CommentContext, CommentProvider } from "./contexts/CommentContext";
 import { LayoutContext, LayoutProvider } from "./contexts/LayoutContext";
+import { useLocale } from "./contexts/LocaleContext";
 import { useClipboard } from "./hooks/useClipboard";
 import { useDocument } from "./hooks/useDocument";
 import { useHeadings } from "./hooks/useHeadings";
@@ -37,7 +38,13 @@ const TOASTER_OPTIONS = {
   },
 };
 
-function AppContent() {
+interface AppContentProps {
+  document: NonNullable<ReturnType<typeof useDocument>["document"]>;
+  reload: ReturnType<typeof useDocument>["reload"];
+}
+
+function AppContent({ document, reload }: AppContentProps) {
+  const { t } = useLocale();
   const {
     comments,
     sortedComments,
@@ -51,8 +58,6 @@ function AppContent() {
     navigateNext,
   } = use(CommentContext)!;
 
-  const { document, reload } = useDocument();
-
   const {
     selection,
     highlightPositions,
@@ -74,6 +79,7 @@ function AppContent() {
     document: document ?? undefined,
     selection: selection ?? undefined,
     clearSelection,
+    t,
   });
 
   const { shortcuts, isFullscreen } = use(LayoutContext)!;
@@ -137,11 +143,6 @@ function AppContent() {
     }
   }, []);
 
-  useEffect(() => {
-    const eventSource = new EventSource("/api/heartbeat");
-    return () => eventSource.close();
-  }, []);
-
   // Scroll save/restore for tab switching
   const setScrollY = useAppStore((s) => s.setScrollY);
   const savedScrollY = useAppStore(
@@ -275,6 +276,7 @@ function AppContent() {
                 />
               ) : (
                 <CommentInput
+                  key={selection.text}
                   selectedText={selection.text}
                   onSubmit={handleAddComment}
                   onCancel={clearSelection}
@@ -302,7 +304,7 @@ function AppContent() {
       <CommentNav />
 
       <footer className="py-4 text-center text-sm text-zinc-400 dark:text-zinc-500">
-        Made with ❤️ by Jay and Claude
+        {t("app.footer")}
       </footer>
     </div>
   );
@@ -333,11 +335,17 @@ function useTabKeyboardShortcuts() {
 }
 
 function App() {
-  const { document, error, isInitialized } = useDocument();
+  const { t } = useLocale();
+  const { document, error, isInitialized, reload } = useDocument();
   const documentOrder = useAppStore((s) => s.documentOrder);
 
   useTabKeyboardShortcuts();
 
+  useEffect(() => {
+    const eventSource = new EventSource("/api/heartbeat");
+    return () => eventSource.close();
+  }, []);
+
   if (error) {
     return (
       <div className="min-h-screen bg-white dark:bg-zinc-900 text-zinc-900 dark:text-zinc-100 flex items-center justify-center">
@@ -349,7 +357,9 @@ function App() {
   if (!isInitialized) {
     return (
       <div className="min-h-screen bg-white dark:bg-zinc-900 text-zinc-900 dark:text-zinc-100 flex items-center justify-center">
-        <div className="text-zinc-500 dark:text-zinc-400">Loading...</div>
+        <div className="text-zinc-500 dark:text-zinc-400">
+          {t("app.loading")}
+        </div>
       </div>
     );
   }
@@ -358,9 +368,17 @@ function App() {
     return (
       <div className="min-h-screen bg-white dark:bg-zinc-900 text-zinc-900 dark:text-zinc-100 flex flex-col">
         <TabBar />
-        <div className="flex-1 flex items-center justify-center">
+        <div className="flex-1 flex flex-col items-center justify-center gap-3">
           <p className="text-zinc-400 dark:text-zinc-500 text-sm">
-            No documents open.
+            {t("app.noDocuments")}
+          </p>
+          <p className="text-zinc-400 dark:text-zinc-500 text-xs">
+            {t("app.noDocumentsHintPrefix")}
+            {t("app.noDocumentsHintPrefix") && " "}
+            <code className="bg-zinc-100 dark:bg-zinc-800 px-1.5 py-0.5 rounded text-xs">
+              readit open &lt;file.md&gt;
+            </code>{" "}
+            {t("app.noDocumentsHintSuffix")}
           </p>
         </div>
       </div>
@@ -370,7 +388,9 @@ function App() {
   if (!document) {
     return (
       <div className="min-h-screen bg-white dark:bg-zinc-900 text-zinc-900 dark:text-zinc-100 flex items-center justify-center">
-        <div className="text-zinc-500 dark:text-zinc-400">Loading...</div>
+        <div className="text-zinc-500 dark:text-zinc-400">
+          {t("app.loading")}
+        </div>
       </div>
     );
   }
@@ -378,7 +398,7 @@ function App() {
   return (
     <>
       <TabBar />
-      <LayoutProvider filePath={document.filePath}>
+      <LayoutProvider>
         <CommentProvider
           filePath={document.filePath}
           clean={document.clean}
@@ -386,7 +406,7 @@ function App() {
           fileName={document.fileName}
           documentType={document.type}
         >
-          <AppContent />
+          <AppContent document={document} reload={reload} />
         </CommentProvider>
       </LayoutProvider>
     </>

package/src/cli/index.ts

@@ -5,6 +5,7 @@ import {
   lstatSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   statSync,
 } from "node:fs";
 import * as fs from "node:fs/promises";
@@ -33,17 +34,113 @@ interface ServerInfo {
   pid: number;
 }
 
-async function discoverServer(): Promise<ServerInfo | null> {
-  const serverInfoPath = join(os.homedir(), ".readit", "server.json");
+interface ServerTarget {
+  kind: "existing" | "started";
+  port: number;
+  url: string;
+  server?: { stop(): void };
+}
+
+const READIT_DIR = join(os.homedir(), ".readit");
+const SERVER_INFO_PATH = join(READIT_DIR, "server.json");
+const SERVER_LOCK_PATH = join(READIT_DIR, "server.lock");
+const SERVER_LOCK_MAX_AGE_MS = 30_000;
+const SERVER_LOCK_TIMEOUT_MS = 10_000;
+const SERVER_LOCK_WAIT_MS = 100;
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getErrnoCode(err: unknown): string | undefined {
+  return err instanceof Error && "code" in err
+    ? (err as NodeJS.ErrnoException).code
+    : undefined;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function clearStaleServerLock(): Promise<void> {
+  try {
+    const [stats, content] = await Promise.all([
+      fs.stat(SERVER_LOCK_PATH),
+      fs.readFile(SERVER_LOCK_PATH, "utf-8").catch(() => ""),
+    ]);
+
+    const age = Date.now() - stats.mtimeMs;
+    let pid: number | undefined;
+
+    if (content) {
+      try {
+        const lock = JSON.parse(content) as { pid?: number };
+        pid = lock.pid;
+      } catch {
+        // Ignore malformed lock files and fall back to age-based cleanup.
+      }
+    }
+
+    if (age > SERVER_LOCK_MAX_AGE_MS || (pid !== undefined && !isAlive(pid))) {
+      await fs.unlink(SERVER_LOCK_PATH).catch(() => {});
+    }
+  } catch (err) {
+    if (getErrnoCode(err) !== "ENOENT") throw err;
+  }
+}
+
+async function withServerLock<T>(run: () => Promise<T>): Promise<T> {
+  await fs.mkdir(READIT_DIR, { recursive: true });
+  const start = Date.now();
+
+  while (true) {
+    let handle: fs.FileHandle | undefined;
+
+    try {
+      handle = await fs.open(SERVER_LOCK_PATH, "wx");
+      await handle.writeFile(
+        JSON.stringify({ pid: process.pid, createdAt: Date.now() }),
+        "utf-8",
+      );
+
+      try {
+        return await run();
+      } finally {
+        await handle.close().catch(() => {});
+        await fs.unlink(SERVER_LOCK_PATH).catch(() => {});
+      }
+    } catch (err) {
+      if (handle) {
+        await handle.close().catch(() => {});
+      }
+
+      if (getErrnoCode(err) !== "EEXIST") {
+        throw err;
+      }
+
+      await clearStaleServerLock();
+
+      if (Date.now() - start >= SERVER_LOCK_TIMEOUT_MS) {
+        throw new Error("Timed out waiting for readit server lock");
+      }
+
+      await sleep(SERVER_LOCK_WAIT_MS);
+    }
+  }
+}
 
+async function discoverServer(): Promise<ServerInfo | null> {
   try {
-    const content = readFileSync(serverInfoPath, "utf-8");
+    const content = readFileSync(SERVER_INFO_PATH, "utf-8");
     const info: ServerInfo = JSON.parse(content);
 
     // Verify the process is alive
-    try {
-      process.kill(info.pid, 0);
-    } catch {
+    if (!isAlive(info.pid)) {
       return null;
     }
 
@@ -61,6 +158,65 @@ async function discoverServer(): Promise<ServerInfo | null> {
   }
 }
 
+async function attachFiles(
+  server: ServerInfo,
+  files: { path: string; type: DocumentType }[],
+): Promise<void> {
+  for (const file of files) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/documents`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ path: file.path }),
+      });
+
+      if (!res.ok) {
+        const data = await res.json();
+        console.error(`error: failed to add ${file.path}: ${data.error}`);
+        process.exit(1);
+      }
+
+      const data = await res.json();
+      if (data.status === "added") {
+        console.log(`Added: ${data.fileName} (${data.type})`);
+      } else {
+        console.log(`Present: ${data.fileName} (${data.type})`);
+      }
+    } catch (err) {
+      console.error(
+        "error: failed to connect to server:",
+        err instanceof Error ? err.message : err,
+      );
+      process.exit(1);
+    }
+  }
+}
+
+async function getServerTarget(
+  files: FileEntry[],
+  port: number,
+  host: string,
+): Promise<ServerTarget> {
+  return withServerLock(async () => {
+    const server = await discoverServer();
+    if (server) {
+      return {
+        kind: "existing",
+        port: server.port,
+        url: `http://127.0.0.1:${server.port}`,
+      };
+    }
+
+    const started = await startServer({ files, port, host });
+    return {
+      kind: "started",
+      port: started.port,
+      url: started.url,
+      server: started.server,
+    };
+  });
+}
+
 /**
  * Recursively find all .comments.md files in a directory.
  */
@@ -116,7 +272,6 @@ function findReviewableFiles(dir: string): FileEntry[] {
           const type = getFileType(entry);
           if (type) {
             results.push({
-              content: readFileSync(fullPath, "utf-8"),
               type,
               filePath: fullPath,
             });
@@ -145,13 +300,15 @@ function resolveFiles(args: string[]): FileEntry[] {
   const files: FileEntry[] = [];
 
   for (const arg of args) {
-    const filePath = resolve(process.cwd(), arg);
+    const inputPath = resolve(process.cwd(), arg);
 
-    if (!existsSync(filePath)) {
-      console.error(`error: not found: ${filePath}`);
+    if (!existsSync(inputPath)) {
+      console.error(`error: not found: ${inputPath}`);
       process.exit(1);
     }
 
+    const filePath = realpathSync(inputPath);
+
     const stat = statSync(filePath);
 
     if (stat.isDirectory()) {
@@ -175,7 +332,6 @@ function resolveFiles(args: string[]): FileEntry[] {
 
       seen.add(filePath);
       files.push({
-        content: readFileSync(filePath, "utf-8"),
         type,
         filePath,
       });
@@ -185,6 +341,114 @@ function resolveFiles(args: string[]): FileEntry[] {
   return files;
 }
 
+// ─── Onboarding ──────────────────────────────────────────────────────
+
+const SETTINGS_PATH = join(os.homedir(), ".readit", "settings.json");
+
+function isOnboarded(): boolean {
+  try {
+    const content = readFileSync(SETTINGS_PATH, "utf-8");
+    const settings = JSON.parse(content);
+    return settings.onboarded === true;
+  } catch {
+    return false;
+  }
+}
+
+async function markOnboarded(): Promise<void> {
+  let settings: Record<string, unknown> = {};
+  try {
+    const content = readFileSync(SETTINGS_PATH, "utf-8");
+    settings = JSON.parse(content);
+  } catch {
+    // No existing settings
+  }
+  settings.onboarded = true;
+  const dir = join(os.homedir(), ".readit");
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2), "utf-8");
+}
+
+const WELCOME_CONTENT = `# Welcome to readit
+
+A simple tool for reviewing markdown with inline comments.
+
+---
+
+## How It Works
+
+readit follows a simple loop: **read → comment → extract**.
+
+### 1. Read
+
+You're already doing this. Open any markdown file with \`readit <file.md>\` and it renders in your browser with a clean reading experience.
+
+### 2. Comment
+
+Select any text to add a comment. Try it now — **select this sentence** and type your first comment.
+
+Your comments appear as margin notes next to the highlighted text, just like reviewing a document in Google Docs. Add as many as you need.
+
+### 3. Extract
+
+When you're done reviewing, click the menu in the top-right and choose **Copy as Prompt**. This exports all your comments in a format ready for Claude, ChatGPT, or any AI assistant.
+
+You can also export as JSON if you prefer structured data.
+
+---
+
+## Everything is Plain Markdown
+
+Your comments are saved as \`.comments.md\` files in \`~/.readit/comments/\`. No database, no lock-in — just readable markdown files you can version control, search, or edit by hand.
+
+Each comment file looks something like this:
+
+\`\`\`markdown
+## Comment 1
+**Selected:** "select this sentence"
+**Comment:** This is my first comment!
+**Created:** 2024-01-15T10:30:00Z
+\`\`\`
+
+---
+
+## Navigating Comments
+
+Once you have multiple comments, use the navigation bar at the bottom of the screen to jump between them. You can also use keyboard shortcuts:
+
+| Shortcut | Action |
+|----------|--------|
+| \`Alt + ↑\` | Previous comment |
+| \`Alt + ↓\` | Next comment |
+| \`⌘ + C\` | Copy selected text (raw) |
+| \`⌘ + Shift + C\` | Copy selected text with context (for AI) |
+
+---
+
+## Quick Start
+
+\`\`\`bash
+# Review a markdown file
+readit document.md
+
+# Use a custom port
+readit document.md --port 3000
+
+# Start fresh (clear existing comments)
+readit document.md --clean
+\`\`\`
+
+---
+
+## Try It Now
+
+Go ahead and add a few comments to this document. When you're done, export them and see the output. That's the entire workflow — simple, transparent, and designed for reviewing AI-generated content.
+`;
+
+const WELCOME_PATH = join(os.homedir(), ".readit", "welcome.md");
+
+// ─── Program ─────────────────────────────────────────────────────────
+
 program
   .name("readit")
   .description("Review Markdown and HTML documents with inline comments")
@@ -273,9 +537,9 @@ program
     }
   });
 
-// Main review command (default) — accepts one or more files/directories
+// Main review command (default) — accepts zero or more files/directories
 program
-  .argument("<files...>", "Markdown or HTML files/directories to review")
+  .argument("[files...]", "Markdown or HTML files/directories to review")
   .option("-p, --port <number>", "Port to run server on", "4567")
   .option("--host <address>", "Host address to bind to", "127.0.0.1")
   .option("--no-open", "Don't automatically open browser")
@@ -290,11 +554,27 @@ program
         clean: boolean;
       },
     ) => {
-      const files = resolveFiles(fileArgs);
+      let files: FileEntry[];
 
-      if (files.length === 0) {
-        console.error("error: no reviewable files found");
-        process.exit(1);
+      if (fileArgs.length === 0) {
+        if (isOnboarded()) {
+          files = [];
+        } else {
+          files = [
+            {
+              content: WELCOME_CONTENT,
+              type: "markdown" as DocumentType,
+              filePath: WELCOME_PATH,
+            },
+          ];
+        }
+      } else {
+        files = resolveFiles(fileArgs);
+
+        if (files.length === 0) {
+          console.error("error: no reviewable files found");
+          process.exit(1);
+        }
       }
 
       const preferredPort = Number.parseInt(options.port, 10);
@@ -316,9 +596,21 @@ program
           clean: options.clean,
         });
 
-        const fileList = files.map((f) => `  ${f.filePath} (${f.type})`);
+        if (files.length === 0) {
+          console.log(`
+readit - Document Review Tool
 
-        console.log(`
+  URL:  ${url}
+
+  No files specified. Add files with:
+    readit open <file.md>
+
+  Server running. Press Ctrl+C to stop.
+`);
+        } else {
+          const fileList = files.map((f) => `  ${f.filePath} (${f.type})`);
+
+          console.log(`
 readit - Document Review Tool
 
   ${files.length === 1 ? "File:" : "Files:"}
@@ -328,11 +620,17 @@ ${fileList.join("\n")}
   Server running. Close browser tab to stop.
   Press Ctrl+C to force stop.
 `);
+        }
 
         if (options.open) {
           open(url);
         }
 
+        // Mark onboarding complete on first server start
+        if (fileArgs.length === 0) {
+          await markOnboarded();
+        }
+
         // Graceful shutdown on Ctrl+C
         process.on("SIGINT", async () => {
           console.log("\n\nShutting down...");
@@ -362,13 +660,15 @@ program
       // Resolve and validate files
       const resolvedFiles: { path: string; type: DocumentType }[] = [];
       for (const arg of fileArgs) {
-        const filePath = resolve(process.cwd(), arg);
+        const inputPath = resolve(process.cwd(), arg);
 
-        if (!existsSync(filePath)) {
-          console.error(`error: not found: ${filePath}`);
+        if (!existsSync(inputPath)) {
+          console.error(`error: not found: ${inputPath}`);
           process.exit(1);
         }
 
+        const filePath = realpathSync(inputPath);
+
         const type = getFileType(filePath);
         if (!type) {
           console.error(
@@ -380,59 +680,27 @@ program
         resolvedFiles.push({ path: filePath, type });
       }
 
-      // Try to find running server
-      const server = await discoverServer();
-
-      if (server) {
-        // Send files to running server
-        for (const file of resolvedFiles) {
-          try {
-            const res = await fetch(
-              `http://127.0.0.1:${server.port}/api/files`,
-              {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ path: file.path }),
-              },
-            );
-
-            if (!res.ok) {
-              const data = await res.json();
-              console.error(`error: failed to add ${file.path}: ${data.error}`);
-              process.exit(1);
-            }
-
-            const data = await res.json();
-            console.log(`Added: ${data.fileName} (${data.type})`);
-          } catch (err) {
-            console.error(
-              "error: failed to connect to server:",
-              err instanceof Error ? err.message : err,
-            );
-            process.exit(1);
-          }
-        }
-
-        console.log(`\nServer: http://127.0.0.1:${server.port}`);
-        return;
-      }
-
-      // No running server — start one
-      console.log("No running server found, starting new one...\n");
-
       const files = resolvedFiles.map((f) => ({
-        content: readFileSync(f.path, "utf-8"),
         type: f.type,
         filePath: f.path,
       }));
 
       const preferredPort = Number.parseInt(options.port, 10);
       try {
-        const { url, server: newServer } = await startServer({
+        const target = await getServerTarget(
           files,
-          port: preferredPort,
-          host: options.host,
-        });
+          preferredPort,
+          options.host,
+        );
+
+        if (target.kind === "existing") {
+          await attachFiles(
+            { port: target.port, pid: process.pid },
+            resolvedFiles,
+          );
+          console.log(`\nServer: ${target.url}`);
+          return;
+        }
 
         const fileList = files.map((f) => `  ${f.filePath} (${f.type})`);
         console.log(`
@@ -440,17 +708,17 @@ readit - Document Review Tool
 
   ${files.length === 1 ? "File:" : "Files:"}
 ${fileList.join("\n")}
-  URL:  ${url}
+  URL:  ${target.url}
 
   Server running. Close browser tab to stop.
   Press Ctrl+C to force stop.
 `);
 
-        open(url);
+        open(target.url);
 
         process.on("SIGINT", async () => {
           console.log("\n\nShutting down...");
-          newServer.stop();
+          target.server?.stop();
           await removeServerInfo();
           process.exit(0);
         });