@youtyan/code-viewer 0.1.34 → 0.1.36

package/README.md

@@ -122,7 +122,9 @@ code-viewer annotate add --file web-src/app.ts --line 9650 \
 
 The body is Markdown. Long bodies can be passed with `--body-file <path>` or
 piped through stdin. `code-viewer annotate --help` shows all commands,
-including `list`, `delete <id>`, and `clear`.
+including `list`, `delete <id>`, and `clear`. For AI agents,
+`code-viewer annotate agent-help` prints a skill-style guide covering the
+workflow, conventions, and pitfalls for writing good walkthroughs.
 
 Annotations are grouped into sessions and persisted in
 `.code-viewer/annotations.json` at the repository root, so the walkthrough
@@ -138,11 +140,14 @@ location, and entries and sessions can be deleted there too. The "follow"
 checkbox controls whether the tab jumps automatically when an agent adds a
 new annotation.
 
-The `annotate` subcommand reuses the running server for the repository when
-one exists (discovered via `~/.cache/code-viewer/servers/`) and starts one
-automatically otherwise, printing its URL to stderr. Pass `--cwd <repo>` when
-annotating a repository other than the current directory, or `--server <url>`
-to target a specific server.
+The `annotate` subcommand talks to the running server for the repository
+(discovered via `~/.cache/code-viewer/servers/`); start one with
+`code-viewer` first. Pass `--cwd <repo>` when annotating a repository other
+than the current directory, or `--server <url>` to target a specific server.
+
+`add` appends to the most recent session (creating one when none exists);
+run `annotate start` again to begin a new session, or pass `--session <id>`
+to target a specific one.
 
 ## Development
 

package/dist/code-viewer.js

@@ -197,6 +197,47 @@ function addAnnotationEntry(state, input, now, makeId = makeAnnotationId) {
     created_session: createdSession
   };
 }
+function renameAnnotationSession(state, id, title) {
+  const session = state.sessions.find((s) => s.id === id);
+  if (!session)
+    return { state, renamed: false };
+  const next = title.trim().slice(0, ANNOTATION_TITLE_MAX_CHARS) || "Untitled session";
+  return {
+    state: {
+      version: 1,
+      sessions: state.sessions.map((s) => s.id === id ? { ...s, title: next } : s)
+    },
+    renamed: true
+  };
+}
+function updateAnnotationEntry(state, id, patch) {
+  const session = state.sessions.find((s) => s.entries.some((e) => e.id === id));
+  if (!session)
+    return { ok: false, error: "annotation not found" };
+  if (patch.body !== undefined) {
+    if (!patch.body.trim())
+      return { ok: false, error: "body is required" };
+    if (Buffer.byteLength(patch.body, "utf8") > ANNOTATION_BODY_MAX_BYTES)
+      return { ok: false, error: "body is too large" };
+  }
+  let updated = null;
+  const sessions = state.sessions.map((s) => s.id === session.id ? {
+    ...s,
+    entries: s.entries.map((e) => {
+      if (e.id !== id)
+        return e;
+      updated = {
+        ...e,
+        ...patch.title !== undefined ? { title: patch.title.trim() || undefined } : {},
+        ...patch.body !== undefined ? { body: patch.body } : {}
+      };
+      return updated;
+    })
+  } : s);
+  if (!updated)
+    return { ok: false, error: "annotation not found" };
+  return { ok: true, state: { version: 1, sessions }, entry: updated };
+}
 function deleteAnnotationById(state, id) {
   for (const session of state.sessions) {
     if (session.id === id) {
@@ -1106,7 +1147,8 @@ var exports_annotate_cli = {};
 __export(exports_annotate_cli, {
   runAnnotateCli: () => runAnnotateCli,
   parseAnnotateArgs: () => parseAnnotateArgs,
-  ANNOTATE_HELP: () => ANNOTATE_HELP
+  ANNOTATE_HELP: () => ANNOTATE_HELP,
+  ANNOTATE_AGENT_HELP: () => ANNOTATE_AGENT_HELP
 });
 import { readFileSync as readFileSync4, realpathSync } from "node:fs";
 function takeValue(argv, index, flag) {
@@ -1162,6 +1204,9 @@ function parseAnnotateArgs(argv) {
   const subcommand = rest[0];
   if (!subcommand)
     return { ok: true, args: { command: { kind: "help" } } };
+  if (subcommand === "agent-help") {
+    return { ok: true, args: { command: { kind: "agent-help" } } };
+  }
   if (subcommand === "start") {
     return {
       ok: true,
@@ -1207,6 +1252,41 @@ function parseAnnotateArgs(argv) {
       }
     };
   }
+  if (subcommand === "rename") {
+    const id = rest[1];
+    if (!id)
+      return { ok: false, error: "rename requires a session id" };
+    const title = options.get("--title");
+    if (!title)
+      return { ok: false, error: "rename requires --title <text>" };
+    return {
+      ok: true,
+      args: { command: { kind: "rename", id, title }, cwd, server }
+    };
+  }
+  if (subcommand === "edit") {
+    const id = rest[1];
+    if (!id)
+      return { ok: false, error: "edit requires an annotation id" };
+    const body = options.get("--body");
+    const bodyFile = options.get("--body-file");
+    if (body !== undefined && bodyFile !== undefined)
+      return { ok: false, error: "use either --body or --body-file" };
+    return {
+      ok: true,
+      args: {
+        command: {
+          kind: "edit",
+          id,
+          title: options.get("--title"),
+          body,
+          bodyFile
+        },
+        cwd,
+        server
+      }
+    };
+  }
   if (subcommand === "list") {
     return {
       ok: true,
@@ -1331,6 +1411,10 @@ async function runAnnotateCli(argv) {
     console.log(ANNOTATE_HELP);
     return;
   }
+  if (command.kind === "agent-help") {
+    console.log(ANNOTATE_AGENT_HELP);
+    return;
+  }
   const root = resolveRepoRoot(cwd);
   const serverUrl = await ensureServerUrl(root, server);
   if (command.kind === "start") {
@@ -1383,6 +1467,37 @@ async function runAnnotateCli(argv) {
       printList(state);
     return;
   }
+  if (command.kind === "rename") {
+    await request(serverUrl, "POST", {
+      action: "rename",
+      id: command.id,
+      title: command.title
+    });
+    console.log(`renamed session ${command.id} to "${command.title}"`);
+    return;
+  }
+  if (command.kind === "edit") {
+    let bodyText = command.body;
+    if (command.bodyFile !== undefined)
+      bodyText = readFileSync4(command.bodyFile, "utf8");
+    if (bodyText === undefined) {
+      const stdin = await readStdin();
+      if (stdin.trim())
+        bodyText = stdin;
+    }
+    if (bodyText === undefined && command.title === undefined) {
+      console.error("edit requires --title, --body, --body-file, or stdin");
+      process.exit(1);
+    }
+    const result = await request(serverUrl, "POST", {
+      action: "update",
+      id: command.id,
+      title: command.title,
+      body: bodyText
+    });
+    console.log(`updated annotation ${result.entry.id} (${result.entry.path}${formatLine(result.entry.line)})`);
+    return;
+  }
   if (command.kind === "delete") {
     const result = await request(serverUrl, "POST", {
       action: "delete",
@@ -1405,11 +1520,17 @@ in <repo>/.code-viewer/annotations.json. A running code-viewer server for
 the repository is required: start one with "code-viewer" before using
 annotate (or point at one explicitly with --server).
 
+Run "code-viewer annotate agent-help" for an AI-agent oriented guide
+(workflow, conventions, and pitfalls for writing good walkthroughs).
+
 Usage:
   code-viewer annotate start [--title <text>]
   code-viewer annotate add --file <path> [--line <n>|<n>-<m>]
       [--from <ref>] [--to <ref>] [--title <text>] [--session <id>]
       [--body <markdown> | --body-file <path>]   (or pipe body via stdin)
+  code-viewer annotate rename <session-id> --title <text>
+  code-viewer annotate edit <id> [--title <text>]
+      [--body <markdown> | --body-file <path>]   (or pipe body via stdin)
   code-viewer annotate list [--json]
   code-viewer annotate delete <id>
   code-viewer annotate clear
@@ -1424,6 +1545,78 @@ Examples:
       --body "This endpoint keeps one SSE stream per browser tab."
   git diff HEAD~1 | code-viewer annotate add --file src/app.ts --line 10 \\
       --from HEAD~1 --to worktree --body "The fix moves the guard up here."
+`, ANNOTATE_AGENT_HELP = `code-viewer annotate — agent guide
+
+You are an AI coding agent. Use this tool to walk a human through code in
+their browser: each annotation jumps every open code-viewer tab to a file
+location and renders your explanation directly under the annotated lines.
+
+## When to use
+
+- Explaining a change you just made (per-file, per-hunk commentary)
+- Guiding a code review: point at the risky lines, in reading order
+- Onboarding walkthroughs: "how does feature X flow through the code"
+
+## Requirements
+
+- A code-viewer server must already be running for the repository
+  (the human starts it with: code-viewer). This command never starts one.
+- Run from inside the repository, or pass --cwd <repo>.
+- If "code-viewer" is not on PATH (e.g. the human runs it via npx), invoke
+  every command below as: npx -y @youtyan/code-viewer annotate ...
+
+## Workflow
+
+1. Start a session per walkthrough topic. The title is shown to the human:
+     code-viewer annotate start --title "How the cache invalidation works"
+2. Add annotations in READING ORDER (the order you want the human to
+   follow). Each add without --session appends to the most recent session:
+     code-viewer annotate add --file src/cache.ts --line 120-145 \\
+         --title "Entry point" --body "Writes land here first. ..."
+3. Verify what you posted:
+     code-viewer annotate list
+
+## Conventions for good walkthroughs
+
+- One idea per annotation. Prefer 5-10 focused annotations over 2 huge ones.
+- Always pass --line. Use the smallest range that covers the idea; the
+  body is rendered inline directly under the LAST line of the range.
+- Line numbers must match the "to" side of the range (default: the current
+  worktree state of the file). When annotating a diff against another ref,
+  pass --from/--to and use NEW-side line numbers.
+- The body is Markdown. Code spans, fenced blocks, and links work. Long
+  bodies: use --body-file <path> or pipe via stdin instead of --body.
+- Give every annotation a short --title; it becomes the inline heading.
+- Annotating unchanged code is fine: the viewer auto-expands diff context
+  or falls back to the full source view.
+
+## Sessions
+
+- add (no --session) → appends to the most recent session.
+- annotate start      → begins a NEW session; later adds go there.
+- add --session <id>  → targets a specific session (ids: annotate list).
+- The human can share a walkthrough as a URL; one session = one shareable
+  walkthrough. Do not mix unrelated topics in one session.
+
+## Fixing mistakes and follow-ups
+
+- The human may paste a reference block copied from the viewer that starts
+  with "code-viewer のコード注釈について依頼があります" and lists the
+  annotation id, location, and session, followed by their question.
+  Read the current body first: code-viewer annotate list --json
+- Revise a wrong annotation IN PLACE (do not delete + re-add; the id and
+  its position in the walkthrough are preserved):
+    code-viewer annotate edit <id> --body "<corrected markdown>"
+    (long bodies: --body-file <path> or pipe via stdin; --title also works)
+- Post a follow-up answer next to the original instead of replacing it:
+    code-viewer annotate add --session <session-id> --file <path> --line <n>         --title "回答: ..." --body "<markdown>"
+- Rename a session: code-viewer annotate rename <session-id> --title <text>
+
+## Cleanup
+
+- delete <id> removes one annotation or a whole session by its id.
+- clear removes everything. Ask the human before clearing state you did
+  not create.
 `;
 var init_annotate_cli = __esm(() => {
   init_annotations();
@@ -1431,7 +1624,7 @@ var init_annotate_cli = __esm(() => {
   init_server_registry();
 });
 
-// web-src/directory-name.ts
+// web-src/core/directory-name.ts
 function normalizeNewDirectoryName(name) {
   if (typeof name !== "string")
     return null;
@@ -1448,7 +1641,7 @@ function normalizeNewDirectoryName(name) {
   return trimmed;
 }
 
-// web-src/routes.ts
+// web-src/core/routes.ts
 var SPA_PATHS, APP_ENTRY_PATHS;
 var init_routes = __esm(() => {
   SPA_PATHS = ["/todif", "/todiff", "/file", "/help"];
@@ -3715,6 +3908,32 @@ async function handleAnnotations(req) {
     }
     return json({ ok: true, removed: result.removed });
   }
+  if (action === "rename") {
+    const id = typeof body.id === "string" ? body.id : "";
+    const title = typeof body.title === "string" ? body.title : "";
+    if (!id)
+      return text("invalid id", 400);
+    const result = renameAnnotationSession(loadAnnotationsState(cwd), id, title);
+    if (!result.renamed)
+      return text("session not found", 404);
+    saveAnnotationsState(cwd, result.state);
+    annotationSse("update", id);
+    return json({ ok: true });
+  }
+  if (action === "update") {
+    const id = typeof body.id === "string" ? body.id : "";
+    if (!id)
+      return text("invalid id", 400);
+    const result = updateAnnotationEntry(loadAnnotationsState(cwd), id, {
+      title: typeof body.title === "string" ? body.title : undefined,
+      body: typeof body.body === "string" ? body.body : undefined
+    });
+    if (result.ok === false)
+      return text(result.error, 400);
+    saveAnnotationsState(cwd, result.state);
+    annotationSse("update", undefined, id);
+    return json({ ok: true, entry: result.entry });
+  }
   if (action === "clear") {
     saveAnnotationsState(cwd, emptyAnnotationsState());
     annotationSse("clear");
@@ -3908,12 +4127,24 @@ data: ok
     started_at: new Date().toISOString()
   });
   process.on("exit", () => removeServerRegistry(cwd, process.pid));
-  for (const signal of ["SIGINT", "SIGTERM"]) {
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
     process.on(signal, () => {
       removeServerRegistry(cwd, process.pid);
       process.exit(0);
     });
   }
+  if (process.env.CODE_VIEWER_DEV === "1") {
+    const parentPid = process.ppid;
+    setInterval(() => {
+      try {
+        process.kill(parentPid, 0);
+      } catch {
+        console.log("dev wrapper exited; shutting down preview server");
+        removeServerRegistry(cwd, process.pid);
+        process.exit(0);
+      }
+    }, 1000).unref();
+  }
   startDevAssetReload({
     enabled: process.env.CODE_VIEWER_DEV === "1",
     webRoot: WEB_ROOT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youtyan/code-viewer",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "Local browser-based code and git diff viewer",
   "type": "module",
   "bin": {
@@ -65,6 +65,5 @@
   },
   "engines": {
     "node": ">=20.0.0"
-  },
-  "dependencies": {}
+  }
 }