@youtyan/code-viewer 0.1.36 → 0.1.38

package/README.md

@@ -149,6 +149,20 @@ than the current directory, or `--server <url>` to target a specific server.
 run `annotate start` again to begin a new session, or pass `--session <id>`
 to target a specific one.
 
+### Agent Skill
+
+The package bundles an [Agent Skill](https://code.claude.com/docs/en/skills)
+that teaches AI coding agents when and how to use `annotate`. Install it
+into the current project (`.claude/skills/`):
+
+```sh
+npx -y @youtyan/code-viewer skill install
+```
+
+Or install it once for all projects with `--global`
+(`~/.claude/skills/`). Running the same command again updates an existing
+installation.
+
 ## Development
 
 ```sh

package/dist/code-viewer.js

@@ -1624,6 +1624,125 @@ var init_annotate_cli = __esm(() => {
   init_server_registry();
 });
 
+// web-src/server/root.ts
+import { existsSync as existsSync4 } from "node:fs";
+import { dirname, join as join4, normalize } from "node:path";
+import { fileURLToPath } from "node:url";
+function findRoot(start) {
+  let current = start;
+  for (let i = 0;i < 5; i++) {
+    if (existsSync4(join4(current, "package.json")) && existsSync4(join4(current, "web"))) {
+      return normalize(current);
+    }
+    const parent = dirname(current);
+    if (parent === current)
+      break;
+    current = parent;
+  }
+  return normalize(join4(start, "..", ".."));
+}
+var ROOT;
+var init_root = __esm(() => {
+  ROOT = findRoot(dirname(fileURLToPath(import.meta.url)));
+});
+
+// web-src/server/skill-cli.ts
+var exports_skill_cli = {};
+__export(exports_skill_cli, {
+  runSkillCli: () => runSkillCli,
+  parseSkillArgs: () => parseSkillArgs,
+  installSkill: () => installSkill,
+  SKILL_HELP: () => SKILL_HELP
+});
+import { cpSync, existsSync as existsSync5, mkdirSync as mkdirSync3 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join5, resolve } from "node:path";
+function parseSkillArgs(argv) {
+  if (argv.length === 0 || argv.includes("--help") || argv[0] === "help") {
+    return { ok: true, args: { kind: "help" } };
+  }
+  const [command, ...rest] = argv;
+  if (command !== "install") {
+    return { ok: false, error: `unknown skill command: ${command}` };
+  }
+  let global = false;
+  let cwd;
+  for (let i = 0;i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--global") {
+      global = true;
+    } else if (arg === "--cwd") {
+      cwd = rest[++i];
+      if (!cwd)
+        return { ok: false, error: "--cwd requires a directory" };
+    } else {
+      return { ok: false, error: `unknown option: ${arg}` };
+    }
+  }
+  return { ok: true, args: { kind: "install", global, cwd } };
+}
+function installSkill(args, deps) {
+  if (!existsSync5(join5(deps.sourceDir, "SKILL.md"))) {
+    return {
+      ok: false,
+      error: `bundled skill not found at ${deps.sourceDir}`
+    };
+  }
+  const base = args.global ? deps.homeDir : resolve(args.cwd ?? deps.projectDir);
+  const target = join5(base, ".claude", "skills", SKILL_NAME);
+  const action = existsSync5(target) ? "updated" : "installed";
+  try {
+    mkdirSync3(target, { recursive: true });
+    cpSync(deps.sourceDir, target, { recursive: true });
+  } catch (error) {
+    return { ok: false, error: String(error) };
+  }
+  return { ok: true, action, target };
+}
+function runSkillCli(argv) {
+  const parsed = parseSkillArgs(argv);
+  if (parsed.ok === false) {
+    console.error(parsed.error);
+    console.error('Run "code-viewer skill --help" for usage.');
+    process.exit(1);
+  }
+  if (parsed.args.kind === "help") {
+    console.log(SKILL_HELP);
+    return;
+  }
+  const result = installSkill(parsed.args, {
+    sourceDir: join5(ROOT, "skills", SKILL_NAME),
+    homeDir: homedir2(),
+    projectDir: process.cwd()
+  });
+  if (result.ok === false) {
+    console.error(result.error);
+    process.exit(1);
+  }
+  console.log(`${result.action}: ${result.target}`);
+  if (result.action === "installed") {
+    console.log("Re-run the same command anytime to update the skill.");
+  }
+}
+var SKILL_NAME = "code-viewer-annotate", SKILL_HELP;
+var init_skill_cli = __esm(() => {
+  init_root();
+  SKILL_HELP = `code-viewer skill — manage the bundled agent skill
+
+Usage:
+  code-viewer skill install [--global] [--cwd <dir>]
+
+Installs the ${SKILL_NAME} skill (SKILL.md for AI coding agents) into
+.claude/skills/ of the current project, or into ~/.claude/skills/ with
+--global. Running install again overwrites the files, so the same command
+also updates an existing installation.
+
+Options:
+  --global      install into ~/.claude/skills/ instead of the project
+  --cwd <dir>   project directory to install into (ignored with --global)
+`;
+});
+
 // web-src/core/directory-name.ts
 function normalizeNewDirectoryName(name) {
   if (typeof name !== "string")
@@ -1650,7 +1769,7 @@ var init_routes = __esm(() => {
 
 // web-src/server/cache.ts
 import { lstatSync as lstatSync2 } from "node:fs";
-import { join as join4 } from "node:path";
+import { join as join6 } from "node:path";
 function cacheFresh(cached, now = Date.now(), ttlMs = CACHE_TTL_MS) {
   return !!cached && now - cached.storedAt <= ttlMs;
 }
@@ -1665,7 +1784,7 @@ function setTimedCacheEntry(cache, key, value, now = Date.now(), maxEntries = MA
 }
 function worktreeFileSignature(path, cwd) {
   try {
-    const stats = lstatSync2(join4(cwd, path));
+    const stats = lstatSync2(join6(cwd, path));
     const inode = "ino" in stats ? stats.ino : 0;
     return `state:file|size:${stats.size}|mtime:${stats.mtimeMs}|ctime:${stats.ctimeMs}|ino:${inode}`;
   } catch {
@@ -1921,28 +2040,6 @@ function collectLineRangeFromIndexedText(text, index, start, end) {
   return { lines, total: index.total, complete: end >= index.total };
 }
 
-// web-src/server/root.ts
-import { existsSync as existsSync4 } from "node:fs";
-import { dirname, join as join5, normalize } from "node:path";
-import { fileURLToPath } from "node:url";
-function findRoot(start) {
-  let current = start;
-  for (let i = 0;i < 5; i++) {
-    if (existsSync4(join5(current, "package.json")) && existsSync4(join5(current, "web"))) {
-      return normalize(current);
-    }
-    const parent = dirname(current);
-    if (parent === current)
-      break;
-    current = parent;
-  }
-  return normalize(join5(start, "..", ".."));
-}
-var ROOT;
-var init_root = __esm(() => {
-  ROOT = findRoot(dirname(fileURLToPath(import.meta.url)));
-});
-
 // web-src/server/search.ts
 function normalizeGrepMax(value) {
   const parsed = Number(value || "");
@@ -2069,7 +2166,7 @@ import {
   readdirSync as nodeReaddirSync,
   watch as nodeWatch
 } from "node:fs";
-import { join as join6, relative } from "node:path";
+import { join as join7, relative } from "node:path";
 function normalizeRelativePath(path) {
   return path.replace(/\\/g, "/").replace(/^\/+/, "");
 }
@@ -2152,7 +2249,7 @@ function startWorktreeUpdateWatch(options) {
     for (const entry of entries) {
       if (!entry.isDirectory())
         continue;
-      children.push(join6(dir, entry.name));
+      children.push(join7(dir, entry.name));
     }
     return children;
   };
@@ -2181,10 +2278,10 @@ function startWorktreeUpdateWatch(options) {
           scheduleUpdate();
           return;
         }
-        const changed = normalizeRelativePath(join6(rel, filename.toString()));
+        const changed = normalizeRelativePath(join7(rel, filename.toString()));
         if (ignored(changed))
           return;
-        const fullChangedPath = join6(options.root, changed);
+        const fullChangedPath = join7(options.root, changed);
         if (!isInsideRoot(options.root, fullChangedPath))
           return;
         const known = watchers.has(fullChangedPath);
@@ -2243,9 +2340,9 @@ var exports_preview = {};
 import {
   closeSync,
   constants,
-  existsSync as existsSync5,
+  existsSync as existsSync6,
   lstatSync as lstatSync4,
-  mkdirSync as mkdirSync3,
+  mkdirSync as mkdirSync4,
   openSync,
   readFileSync as readFileSync5,
   realpathSync as realpathSync2,
@@ -2255,8 +2352,8 @@ import {
   watch,
   writeFileSync as writeFileSync3
 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { basename as basename2, dirname as dirname2, extname, join as join7, relative as relative2 } from "node:path";
+import { homedir as homedir3 } from "node:os";
+import { basename as basename2, dirname as dirname2, extname, join as join8, relative as relative2 } from "node:path";
 function parseCli() {
   const rest = [];
   for (let i = 2;i < process.argv.length; i++) {
@@ -2395,8 +2492,8 @@ function staticFile(pathname) {
   const spec = map[pathname];
   if (!spec)
     return null;
-  const full = join7(WEB_ROOT, spec[0]);
-  if (!existsSync5(full))
+  const full = join8(WEB_ROOT, spec[0]);
+  if (!existsSync6(full))
     return text("not found", 404);
   return new Response(readFileSync5(full), {
     headers: { "Content-Type": spec[1], "Cache-Control": "no-store" }
@@ -2629,8 +2726,8 @@ function parseScopeExcludeNamesQuery(value) {
   return normalizeScopeExcludeNames(names);
 }
 function loadProjectConfig() {
-  const full = join7(cwd, ".code-viewer.json");
-  if (!existsSync5(full))
+  const full = join8(cwd, ".code-viewer.json");
+  if (!existsSync6(full))
     return null;
   let realCwd;
   let realConfig;
@@ -2694,8 +2791,8 @@ function safeWorktreePath(path) {
     return null;
   if (isGitInternalPath(path))
     return null;
-  const full = join7(cwd, path);
-  if (!existsSync5(full))
+  const full = join8(cwd, path);
+  if (!existsSync6(full))
     return null;
   let realCwd;
   let realFull;
@@ -2713,7 +2810,7 @@ function safeWorktreePath(path) {
   return realFull;
 }
 function worktreePath(path) {
-  return join7(cwd, path);
+  return join8(cwd, path);
 }
 function safeOpenWorktreePath(path) {
   if (path === "") {
@@ -3476,10 +3573,10 @@ async function handleUploadFiles(req) {
     total += file.size;
     if (total > MAX_UPLOAD_TOTAL_BYTES)
       return text("upload too large", 413);
-    const target = join7(realDir, safeName);
+    const target = join8(realDir, safeName);
     if (relative2(realDir, dirname2(target)) !== "")
       return text("invalid filename", 400);
-    if (existsSync5(target))
+    if (existsSync6(target))
       return text("file exists", 409);
     uploads.push({ file, name: safeName, target });
   }
@@ -3597,11 +3694,11 @@ function triggerUpdate() {
   sendSse("update");
 }
 function moveMacPathIntoTrash(path) {
-  const trashDir = join7(homedir2(), ".Trash");
+  const trashDir = join8(homedir3(), ".Trash");
   const base = basename2(path) || "code-viewer-trash-item";
-  const target = join7(trashDir, `${base}-${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+  const target = join8(trashDir, `${base}-${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
   try {
-    mkdirSync3(trashDir, { recursive: true });
+    mkdirSync4(trashDir, { recursive: true });
     renameSync2(path, target);
     return { ok: true, trashPath: target };
   } catch (error) {
@@ -3633,19 +3730,19 @@ function restoreTrashPath(originalPath, trashPath) {
   if (!parentFullPath)
     return { ok: false, error: "invalid restore target" };
   const original = worktreePath(originalPath);
-  if (existsSync5(original))
+  if (existsSync6(original))
     return { ok: false, error: "restore target exists" };
   if (trashPath) {
     if (process.platform !== "darwin")
       return { ok: false, error: "invalid trash handle" };
-    if (!existsSync5(trashPath))
+    if (!existsSync6(trashPath))
       return { ok: false, error: "trash item not found" };
     try {
-      const trashRoot = join7(homedir2(), ".Trash");
+      const trashRoot = join8(homedir3(), ".Trash");
       const trashRelative = relative2(trashRoot, trashPath);
       if (trashRelative === "" || trashRelative.startsWith("..") || trashRelative.startsWith("/") || trashRelative.startsWith("\\"))
         return { ok: false, error: "invalid trash handle" };
-      mkdirSync3(dirname2(original), { recursive: true });
+      mkdirSync4(dirname2(original), { recursive: true });
       renameSync2(trashPath, original);
       return { ok: true };
     } catch (error) {
@@ -3791,11 +3888,11 @@ async function handleCreateDirectory(req) {
   const targetPath = dir ? `${dir}/${name}` : name;
   if (!safeRepoPath(targetPath) || isGitInternalPath(targetPath))
     return text("invalid target", 400);
-  const target = join7(parent, name);
-  if (existsSync5(target))
+  const target = join8(parent, name);
+  if (existsSync6(target))
     return text("already exists", 409);
   try {
-    mkdirSync3(target, { recursive: false });
+    mkdirSync4(target, { recursive: false });
   } catch (error) {
     if (error.code === "EEXIST")
       return text("already exists", 409);
@@ -3973,8 +4070,8 @@ var init_preview = __esm(async () => {
   init_search();
   init_server_registry();
   init_worktree_watcher();
-  WEB_ROOT = join7(ROOT, "web");
-  VERSION = JSON.parse(readFileSync5(join7(ROOT, "package.json"), "utf8")).version;
+  WEB_ROOT = join8(ROOT, "web");
+  VERSION = JSON.parse(readFileSync5(join8(ROOT, "package.json"), "utf8")).version;
   DEFAULT_ARGS = ["HEAD"];
   WATCHED_ASSET_FILES = ["index.html", "style.css", "app.js"];
   LINE_INDEX_MAX_FILE_BYTES = 256 * 1024 * 1024;
@@ -4172,6 +4269,9 @@ data: ok
 if (process.argv[2] === "annotate") {
   const { runAnnotateCli: runAnnotateCli2 } = await Promise.resolve().then(() => (init_annotate_cli(), exports_annotate_cli));
   await runAnnotateCli2(process.argv.slice(3));
+} else if (process.argv[2] === "skill") {
+  const { runSkillCli: runSkillCli2 } = await Promise.resolve().then(() => (init_skill_cli(), exports_skill_cli));
+  runSkillCli2(process.argv.slice(3));
 } else {
   await init_preview().then(() => exports_preview);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youtyan/code-viewer",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Local browser-based code and git diff viewer",
   "type": "module",
   "bin": {
@@ -23,7 +23,8 @@
     "dist",
     "web",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "skills"
   ],
   "scripts": {
     "build": "bun run build:web && bun run build:server",

package/skills/code-viewer-annotate/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: code-viewer-annotate
+description: Use when walking a human through code in their browser with code-viewer annotations - explaining changes you just made, guiding a code review in reading order, or onboarding walkthroughs. Triggers on "annotate", "ウォークスルー", "コードを説明して", "変更を解説して", "レビューを案内して", "walkthrough", "explain this change in the browser".
+---
+
+# code-viewer annotate
+
+Create browser walkthroughs for a human: each annotation jumps every open
+code-viewer tab to a file location and renders your explanation directly
+under the annotated lines. The human can also replay a session with
+text-to-speech playback.
+
+## 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`). The CLI never starts one.
+- Run from inside the repository, or pass `--cwd <repo>`.
+- If `code-viewer` is not on PATH, prefix every command with
+  `npx -y @youtyan/code-viewer`.
+
+## Workflow
+
+1. Start a session per walkthrough topic (the title is shown to the human):
+
+   ```sh
+   code-viewer annotate start --title "How the cache invalidation works"
+   ```
+
+2. Add annotations in READING ORDER (the order the human should follow):
+
+   ```sh
+   code-viewer annotate add --file src/cache.ts --line 42-58 --body "..."
+   ```
+
+## Full reference
+
+Before composing annotations, read the complete agent guide (all commands,
+options, body formatting rules):
+
+```sh
+code-viewer annotate agent-help
+```

package/web/app.js

@@ -532,16 +532,16 @@
       };
       deps.jump(item.entryId).then(proceed, proceed);
     }
-    function play() {
+    function play(fromIndex) {
       if (status === "playing")
         return;
       if (status === "paused") {
-        startEntry(index);
+        startEntry(fromIndex ?? index);
         return;
       }
       if (deps.items().length === 0)
         return;
-      startEntry(0);
+      startEntry(fromIndex ?? 0);
     }
     function pause() {
       if (status !== "playing")
@@ -574,6 +574,11 @@
           deps.jump(item.entryId).catch(() => {});
       }
     }
+    function jumpTo(at) {
+      if (status === "idle")
+        return;
+      moveTo(at);
+    }
     function next() {
       if (status === "idle")
         return;
@@ -603,7 +608,17 @@
       rate = value;
       restartCurrentIfPlaying();
     }
-    return { play, pause, stop, next, prev, setMuted, setRate, getState };
+    return {
+      play,
+      pause,
+      stop,
+      next,
+      prev,
+      jumpTo,
+      setMuted,
+      setRate,
+      getState
+    };
   }
 
   // web-src/core/annotation-speech.ts
@@ -616,6 +631,7 @@
     text = text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
     text = text.replace(/`([^`]*)`/g, "$1");
     text = text.replace(/https?:\/\/\S+/g, "URL");
+    text = text.replace(/<([^<>]*)>/g, " $1 ");
     text = text.replace(/^[ \t]*(?:#{1,6}|>|[-*+]|\d+\.)[ \t]+/gm, "");
     text = text.replace(/(\*\*|__|\*|_)/g, "");
     return text.replace(/\s+/g, " ").trim();
@@ -689,9 +705,17 @@
       prevBtn.disabled = state.status === "idle";
       nextBtn.disabled = state.status === "idle";
     }
+    let selfJumping = false;
     const core = createAnnotationPlayerCore({
       items,
-      jump: (entryId) => deps.openAnnotationEntry(entryId),
+      jump: async (entryId) => {
+        selfJumping = true;
+        try {
+          await deps.openAnnotationEntry(entryId);
+        } finally {
+          selfJumping = false;
+        }
+      },
       speak,
       schedule: (ms, cb) => {
         const id = window.setTimeout(cb, ms);
@@ -713,13 +737,23 @@
       rateSel.disabled = true;
       core.setMuted(true);
     }
+    function entryIndexOf(entryId) {
+      if (!entryId)
+        return -1;
+      return deps.getActiveSessionEntries().findIndex((entry) => entry.id === entryId);
+    }
     toggleBtn.addEventListener("click", () => {
       const state = core.getState();
       if (state.status === "playing") {
         core.pause();
       } else {
         deps.setAnnotationPanelOpen(true);
-        core.play();
+        if (state.status === "idle") {
+          const activeIndex = entryIndexOf(deps.getActiveAnnotationId());
+          core.play(activeIndex >= 0 ? activeIndex : 0);
+        } else {
+          core.play();
+        }
       }
     });
     prevBtn.addEventListener("click", () => core.prev());
@@ -743,6 +777,15 @@
       core.stop();
       syncVisibility();
     });
+    deps.onAnnotationOpened((entryId) => {
+      if (selfJumping)
+        return;
+      if (core.getState().status === "idle")
+        return;
+      const index = entryIndexOf(entryId);
+      if (index >= 0)
+        core.jumpTo(index);
+    });
     syncVisibility();
     render(core.getState());
     return { stop: () => core.stop(), syncVisibility };
@@ -6970,6 +7013,11 @@ ${frontmatter.yaml}
       for (const cb of annotationsChangedCallbacks)
         cb();
     }
+    const annotationOpenedCallbacks = [];
+    function notifyAnnotationOpened(entryId) {
+      for (const cb of annotationOpenedCallbacks)
+        cb(entryId);
+    }
     let mdHighlighter = null;
     let mdHighlighterRequested = false;
     function ensureMarkdownHighlighter() {
@@ -7475,6 +7523,7 @@ ${frontmatter.yaml}
       activeSessionId = session.id;
       if (sessionChanged)
         notifyAnnotationsChanged();
+      notifyAnnotationOpened(entry.id);
       showAnnotationDetail(session, entry, index);
       const from = entry.range.from || "HEAD";
       const to = entry.range.to || "worktree";
@@ -7595,6 +7644,12 @@ ${frontmatter.yaml}
       },
       onAnnotationsChanged(cb) {
         annotationsChangedCallbacks.push(cb);
+      },
+      onAnnotationOpened(cb) {
+        annotationOpenedCallbacks.push(cb);
+      },
+      getActiveAnnotationId() {
+        return activeAnnotationId;
       }
     };
   }
@@ -15874,7 +15929,9 @@ ${frontmatter.yaml}
       getActiveSessionEntries: () => ANNOTATIONS_UI?.getActiveSessionEntries() ?? [],
       openAnnotationEntry: (id) => ANNOTATIONS_UI ? ANNOTATIONS_UI.openAnnotationEntry(id) : Promise.resolve(),
       setAnnotationPanelOpen: (open) => ANNOTATIONS_UI?.setAnnotationPanelOpen(open),
-      onAnnotationsChanged: (cb) => ANNOTATIONS_UI?.onAnnotationsChanged(cb)
+      onAnnotationsChanged: (cb) => ANNOTATIONS_UI?.onAnnotationsChanged(cb),
+      onAnnotationOpened: (cb) => ANNOTATIONS_UI?.onAnnotationOpened(cb),
+      getActiveAnnotationId: () => ANNOTATIONS_UI ? ANNOTATIONS_UI.getActiveAnnotationId() : null
     });
     let sseTimer = null;
     function scheduleSseLoad() {