@youtyan/code-viewer 0.1.37 → 0.1.39

package/README.md

@@ -149,6 +149,21 @@ 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://agentskills.io) (the SKILL.md
+open standard) that teaches AI coding agents when and how to use
+`annotate`. Install it into the current project:
+
+```sh
+npx -y @youtyan/code-viewer skill install                       # Claude Code (.claude/skills/)
+npx -y @youtyan/code-viewer skill install --agent codex,gemini  # other agents
+npx -y @youtyan/code-viewer skill install --agent all           # claude, codex, gemini, cursor, .agents
+```
+
+Or install it once for all projects with `--global` (`~/.claude/skills/`
+etc). Running the same command again updates an existing installation.
+
 ## Development
 
 ```sh

package/dist/code-viewer.js

@@ -1624,6 +1624,176 @@ 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,
+  AGENT_SKILL_DIRS: () => AGENT_SKILL_DIRS
+});
+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 parseAgentList(value) {
+  if (value === "all")
+    return [...AGENT_NAMES];
+  const names = value.split(",").map((name) => name.trim()).filter(Boolean);
+  if (names.length === 0)
+    return null;
+  const result = [];
+  for (const name of names) {
+    if (!(name in AGENT_SKILL_DIRS))
+      return null;
+    const agent = name;
+    if (!result.includes(agent))
+      result.push(agent);
+  }
+  return result;
+}
+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;
+  let agents = ["claude"];
+  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 if (arg === "--agent") {
+      const value = rest[++i];
+      if (!value)
+        return { ok: false, error: "--agent requires a list" };
+      const parsed = parseAgentList(value);
+      if (!parsed) {
+        return {
+          ok: false,
+          error: `unknown agent in "${value}" (valid: ${AGENT_NAMES.join(", ")}, all)`
+        };
+      }
+      agents = parsed;
+    } else {
+      return { ok: false, error: `unknown option: ${arg}` };
+    }
+  }
+  return { ok: true, args: { kind: "install", agents, 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 results = [];
+  for (const agent of args.agents) {
+    const target = join5(base, AGENT_SKILL_DIRS[agent], "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) };
+    }
+    results.push({ agent, action, target });
+  }
+  return { ok: true, results };
+}
+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);
+  }
+  for (const entry of result.results) {
+    console.log(`${entry.action} (${entry.agent}): ${entry.target}`);
+  }
+  if (result.results.some((entry) => entry.action === "installed")) {
+    console.log("Re-run the same command anytime to update the skill.");
+  }
+}
+var SKILL_NAME = "code-viewer-annotate", AGENT_SKILL_DIRS, AGENT_NAMES, SKILL_HELP;
+var init_skill_cli = __esm(() => {
+  init_root();
+  AGENT_SKILL_DIRS = {
+    claude: ".claude",
+    codex: ".codex",
+    gemini: ".gemini",
+    cursor: ".cursor",
+    agents: ".agents"
+  };
+  AGENT_NAMES = Object.keys(AGENT_SKILL_DIRS);
+  SKILL_HELP = `code-viewer skill — manage the bundled agent skill
+
+Usage:
+  code-viewer skill install [--agent <list>] [--global] [--cwd <dir>]
+
+Installs the ${SKILL_NAME} skill (SKILL.md for AI coding agents) into the
+skills directory of each selected agent in the current project, or into the
+home directory equivalents with --global. Running install again overwrites
+the files, so the same command also updates an existing installation.
+
+Options:
+  --agent <list>  comma separated agents: ${AGENT_NAMES.join(", ")}, or all
+                  (default: claude)
+  --global        install into the home directory (~/.claude/skills/ etc)
+  --cwd <dir>     project directory to install into (ignored with --global)
+
+Examples:
+  code-viewer skill install
+  code-viewer skill install --agent claude,codex,gemini
+  code-viewer skill install --agent all --global
+`;
+});
+
 // web-src/core/directory-name.ts
 function normalizeNewDirectoryName(name) {
   if (typeof name !== "string")
@@ -1650,7 +1820,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 +1835,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 +2091,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 +2217,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 +2300,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 +2329,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 +2391,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 +2403,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 +2543,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 +2777,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 +2842,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 +2861,7 @@ function safeWorktreePath(path) {
   return realFull;
 }
 function worktreePath(path) {
-  return join7(cwd, path);
+  return join8(cwd, path);
 }
 function safeOpenWorktreePath(path) {
   if (path === "") {
@@ -3476,10 +3624,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 +3745,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 +3781,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 +3939,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 +4121,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 +4320,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.37",
+  "version": "0.1.39",
   "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

@@ -246,6 +246,8 @@
       allowPaletteOpen: true
     },
     { action: "focus-file-filter", key: "/" },
+    { action: "annotation-next", key: "]" },
+    { action: "annotation-previous", key: "[" },
     { action: "focus-sidebar", key: "h", ctrl: true },
     { action: "focus-main", key: "l", ctrl: true },
     {
@@ -7339,6 +7341,13 @@ ${frontmatter.yaml}
         sessionEl.className = "annotation-session";
         sessionEl.dataset.sessionId = session.id;
         sessionEl.classList.toggle("active", session.id === activeSessionId);
+        sessionEl.addEventListener("click", (event) => {
+          const target = event.target;
+          if (target.closest("button, a, input"))
+            return;
+          if (session.id !== activeSessionId)
+            setActiveSession(session.id);
+        });
         const head = document.createElement("div");
         head.className = "annotation-session-head";
         const title = document.createElement("button");
@@ -7572,14 +7581,18 @@ ${frontmatter.yaml}
         deps.scrollDiffElementIntoView(inlineRow, "center");
     }
     function stepAnnotation(direction) {
-      if (!activeAnnotationId)
+      const found = activeAnnotationId ? findAnnotation(activeAnnotationId) : null;
+      if (found && (!activeSessionId || found.session.id === activeSessionId)) {
+        const next = found.session.entries[found.index + direction];
+        if (next)
+          openAnnotationEntry(next.id);
         return;
-      const found = findAnnotation(activeAnnotationId);
-      if (!found)
-        return;
-      const next = found.session.entries[found.index + direction];
-      if (next)
-        openAnnotationEntry(next.id);
+      }
+      const session = ANNOTATIONS.sessions.find((s2) => s2.id === activeSessionId) ?? ANNOTATIONS.sessions[0];
+      const entries = session?.entries ?? [];
+      const entry = direction === 1 ? entries[0] : entries[entries.length - 1];
+      if (entry)
+        openAnnotationEntry(entry.id);
     }
     function handleSse(raw) {
       let event = null;
@@ -7650,7 +7663,8 @@ ${frontmatter.yaml}
       },
       getActiveAnnotationId() {
         return activeAnnotationId;
-      }
+      },
+      stepAnnotation
     };
   }
 
@@ -8794,7 +8808,8 @@ ${frontmatter.yaml}
                 ["Ctrl+K", "Open file palette"],
                 ["Ctrl+G", "Open grep palette"],
                 ["/", "Focus file filter"],
-                ["t", "Toggle theme"]
+                ["t", "Toggle theme"],
+                ["[ / ]", "Previous / next annotation"]
               ]
             },
             {
@@ -8842,7 +8857,8 @@ ${frontmatter.yaml}
                 ["Ctrl+K", "ファイルパレットを開く"],
                 ["Ctrl+G", "grep パレットを開く"],
                 ["/", "ファイルフィルターへフォーカス"],
-                ["t", "テーマ切り替え"]
+                ["t", "テーマ切り替え"],
+                ["[ / ]", "前 / 次の注釈へ移動"]
               ]
             },
             {
@@ -15631,6 +15647,10 @@ ${frontmatter.yaml}
       if (action === "tab-preview" || action === "tab-code") {
         return switchSourceTab(action === "tab-preview" ? "preview" : "code");
       }
+      if (action === "annotation-next" || action === "annotation-previous") {
+        ANNOTATIONS_UI?.stepAnnotation(action === "annotation-next" ? 1 : -1);
+        return true;
+      }
       if (action === "start-g-sequence") {
         PENDING_G_SCOPE = scope;
         PENDING_G_UNTIL = performance.now() + 900;

package/web/style.css

@@ -1132,7 +1132,8 @@ body.gdp-resizing * { user-select: none !important; }
   top: calc(var(--global-header-h) + 8px);
   width: min(460px, calc(100vw - 32px));
   max-width: calc(100vw - 32px);
-  z-index: 40;
+  /* Transient popover: must sit above the annotation panel (45). */
+  z-index: 70;
   padding: 12px;
   border: 1px solid var(--border);
   border-radius: 8px;