@readwise/cli 0.3.1 → 0.5.1

package/dist/tui/term.js

@@ -17,11 +17,15 @@ export const style = {
 // --- Screen control ---
 export function enterFullScreen() {
     process.stdout.write(`${ESC}[?1049h`); // alternate screen buffer
+    process.stdout.write(`${ESC}[?2004h`); // enable bracketed paste mode
+    process.stdout.write(`${ESC}[>1u`); // enable kitty keyboard protocol (disambiguate mode)
     process.stdout.write(`${ESC}[?25l`); // hide cursor
     process.stdout.write(`${ESC}[H`); // cursor home
 }
 export function exitFullScreen() {
     process.stdout.write(`${ESC}[?25h`); // show cursor
+    process.stdout.write(`${ESC}[<u`); // disable kitty keyboard protocol
+    process.stdout.write(`${ESC}[?2004l`); // disable bracketed paste mode
     process.stdout.write(`${ESC}[?1049l`); // restore screen buffer
 }
 /** Paint lines to terminal without flicker: cursor home → overwrite each line → clear remainder */
@@ -30,11 +34,13 @@ export function paint(lines) {
     let out = `${ESC}[H`; // cursor home
     const count = Math.min(lines.length, rows);
     for (let i = 0; i < count; i++) {
-        out += lines[i] + `${ESC}[K\n`; // line content + clear to end of line
+        out += lines[i] + `${ESC}[K`; // line content + clear to end of line
+        if (i < count - 1)
+            out += "\n";
     }
     // Clear any remaining lines below content
     if (count < rows) {
-        out += `${ESC}[J`; // clear from cursor to end of screen
+        out += `\n${ESC}[J`; // clear from cursor to end of screen
     }
     process.stdout.write(out);
 }
@@ -43,6 +49,24 @@ export function screenSize() {
 }
 export function parseKey(data) {
     const s = data.toString("utf-8");
+    // Bracketed paste: \x1b[200~ ... \x1b[201~
+    if (s.startsWith(`${ESC}[200~`)) {
+        const content = s.replace(/\x1b\[200~/g, "").replace(/\x1b\[201~/g, "");
+        const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+        return { raw: normalized, name: "paste", shift: false, ctrl: false };
+    }
+    // Alt+Enter (ESC + CR/LF) — reliable newline insertion across all terminals
+    if (s === `${ESC}\r` || s === `${ESC}\n`) {
+        return { raw: s, name: "return", shift: true, ctrl: false };
+    }
+    // Alt+Arrow (word navigation)
+    if (s === `${ESC}[1;3D` || s === `${ESC}b`)
+        return { raw: s, name: "wordLeft", shift: false, ctrl: false };
+    if (s === `${ESC}[1;3C` || s === `${ESC}f`)
+        return { raw: s, name: "wordRight", shift: false, ctrl: false };
+    // Alt+Backspace (word delete)
+    if (s === `${ESC}\x7f`)
+        return { raw: s, name: "wordBackspace", shift: false, ctrl: false };
     const ctrl = s.length === 1 && s.charCodeAt(0) < 32;
     // Escape sequences
     if (s === `${ESC}[A`)
@@ -61,13 +85,23 @@ export function parseKey(data) {
         return { raw: s, name: "tab", shift: true, ctrl: false };
     if (s === ESC || s === `${ESC}${ESC}`)
         return { raw: s, name: "escape", shift: false, ctrl: false };
-    // Shift+Enter sequences
+    // Kitty keyboard protocol CSI-u encodings (when disambiguate mode is active)
     if (s === `${ESC}[13;2u`)
-        return { raw: s, name: "return", shift: true, ctrl: false }; // CSI u / kitty
+        return { raw: s, name: "return", shift: true, ctrl: false }; // Shift+Enter
     if (s === `${ESC}[27;2;13~`)
-        return { raw: s, name: "return", shift: true, ctrl: false }; // xterm
+        return { raw: s, name: "return", shift: true, ctrl: false }; // Shift+Enter (xterm)
     if (s === `${ESC}OM`)
-        return { raw: s, name: "return", shift: true, ctrl: false }; // misc terminals
+        return { raw: s, name: "return", shift: true, ctrl: false }; // Shift+Enter (misc)
+    if (s === `${ESC}[27u`)
+        return { raw: s, name: "escape", shift: false, ctrl: false };
+    if (s === `${ESC}[13u`)
+        return { raw: s, name: "return", shift: false, ctrl: false };
+    if (s === `${ESC}[9u`)
+        return { raw: s, name: "tab", shift: false, ctrl: false };
+    if (s === `${ESC}[9;2u`)
+        return { raw: s, name: "tab", shift: true, ctrl: false };
+    if (s === `${ESC}[127u`)
+        return { raw: s, name: "backspace", shift: false, ctrl: false };
     // Single characters
     if (s === "\r" || s === "\n")
         return { raw: s, name: "return", shift: false, ctrl: false };
@@ -82,6 +116,11 @@ export function parseKey(data) {
     if (ctrl) {
         return { raw: s, name: String.fromCharCode(s.charCodeAt(0) + 96), shift: false, ctrl: true };
     }
+    // Multi-character non-escape input = paste (terminal without bracketed paste support)
+    if (s.length > 1 && !s.startsWith(ESC)) {
+        const normalized = s.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+        return { raw: normalized, name: "paste", shift: false, ctrl: false };
+    }
     return { raw: s, name: s, shift: false, ctrl: false };
 }
 /** Strip ANSI escape codes to get visible character count */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readwise/cli",
-  "version": "0.3.1",
+  "version": "0.5.1",
   "description": "Command-line interface for Readwise and Reader",
   "type": "module",
   "bin": {
@@ -23,8 +23,8 @@
     "open": "^10"
   },
   "devDependencies": {
-    "typescript": "^5",
     "@types/node": "^22",
-    "tsx": "^4"
+    "tsx": "^4",
+    "typescript": "^5"
   }
 }

package/src/config.ts

@@ -20,6 +20,7 @@ export interface SchemaProperty {
   enum?: string[];
   items?: SchemaProperty;
   default?: unknown;
+  examples?: unknown[];
   anyOf?: SchemaProperty[];
   $ref?: string;
   properties?: Record<string, SchemaProperty>;

package/src/index.ts

@@ -6,6 +6,7 @@ import { getTools } from "./mcp.js";
 import { registerTools } from "./commands.js";
 import { loadConfig } from "./config.js";
 import { VERSION } from "./version.js";
+import { registerSkillsCommands } from "./skills.js";
 
 function readHiddenInput(prompt: string): Promise<string> {
   return new Promise((resolve, reject) => {
@@ -93,9 +94,10 @@ async function main() {
   const forceRefresh = process.argv.includes("--refresh");
   const positionalArgs = process.argv.slice(2).filter((a) => !a.startsWith("--"));
   const hasSubcommand = positionalArgs.length > 0;
+  const wantsHelp = process.argv.includes("--help") || process.argv.includes("-h");
 
-  // If no subcommand, TTY, and authenticated → launch TUI
-  if (!hasSubcommand && process.stdout.isTTY && config.access_token) {
+  // If no subcommand, TTY, and authenticated → launch TUI (unless --help)
+  if (!hasSubcommand && !wantsHelp && process.stdout.isTTY && config.access_token) {
     try {
       const { token, authType } = await ensureValidToken();
       const tools = await getTools(token, authType, forceRefresh);
@@ -115,6 +117,16 @@ async function main() {
     return;
   }
 
+  // Register skills commands (works without auth)
+  registerSkillsCommands(program);
+
+  // If not authenticated and trying a non-login command, tell user to log in
+  if (!config.access_token && hasSubcommand && positionalArgs[0] !== "login" && positionalArgs[0] !== "login-with-token" && positionalArgs[0] !== "skills") {
+    process.stderr.write("\x1b[31mNot logged in.\x1b[0m Run `readwise login` or `readwise login-with-token` to authenticate.\n");
+    process.exitCode = 1;
+    return;
+  }
+
   // Try to load tools if we have a token (for subcommand mode)
   if (config.access_token) {
     try {
@@ -123,7 +135,6 @@ async function main() {
       registerTools(program, tools);
     } catch (err) {
       // Don't fail — login command should still work
-      // Only warn if user is trying to run a non-login command
       if (hasSubcommand && positionalArgs[0] !== "login" && positionalArgs[0] !== "login-with-token") {
         process.stderr.write(`\x1b[33mWarning: Could not fetch tools: ${(err as Error).message}\x1b[0m\n`);
       }

package/src/skills.ts

@@ -0,0 +1,260 @@
+import { Command } from "commander";
+import { readdir, readFile, writeFile, mkdir, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+const REPO_OWNER = "readwiseio";
+const REPO_NAME = "readwise-skills";
+const SKILLS_SUBDIR = "skills";
+const GITHUB_API = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}`;
+const GITHUB_RAW = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/master`;
+
+/** Local cache directory for fetched skills */
+function cacheDir(): string {
+  return join(homedir(), ".readwise", "skills-cache");
+}
+
+/** Staleness threshold — refetch if cache is older than this */
+const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+function cacheMetaPath(): string {
+  return join(cacheDir(), ".fetched_at");
+}
+
+async function isCacheFresh(): Promise<boolean> {
+  const metaPath = cacheMetaPath();
+  if (!existsSync(metaPath)) return false;
+  try {
+    const ts = Number(await readFile(metaPath, "utf-8"));
+    return Date.now() - ts < CACHE_MAX_AGE_MS;
+  } catch {
+    return false;
+  }
+}
+
+async function touchCache(): Promise<void> {
+  await writeFile(cacheMetaPath(), String(Date.now()));
+}
+
+/** Fetch the list of skill directory names from GitHub API */
+async function fetchSkillNames(): Promise<string[]> {
+  const res = await fetch(`${GITHUB_API}/contents/${SKILLS_SUBDIR}`, {
+    headers: { Accept: "application/vnd.github.v3+json", "User-Agent": "readwise-cli" },
+  });
+  if (!res.ok) throw new Error(`GitHub API error: ${res.status} ${res.statusText}`);
+  const entries = (await res.json()) as { name: string; type: string }[];
+  return entries.filter((e) => e.type === "dir").map((e) => e.name);
+}
+
+/** Fetch a single SKILL.md from GitHub */
+async function fetchSkillFile(skillName: string): Promise<string> {
+  const url = `${GITHUB_RAW}/${SKILLS_SUBDIR}/${skillName}/SKILL.md`;
+  const res = await fetch(url, { headers: { "User-Agent": "readwise-cli" } });
+  if (!res.ok) throw new Error(`Failed to fetch ${skillName}: ${res.status}`);
+  return res.text();
+}
+
+/** Fetch all skills from GitHub and write to cache */
+async function refreshCache(): Promise<string[]> {
+  const names = await fetchSkillNames();
+  const cache = cacheDir();
+
+  // Clear old cache
+  if (existsSync(cache)) await rm(cache, { recursive: true });
+  await mkdir(cache, { recursive: true });
+
+  // Fetch all in parallel
+  const results = await Promise.allSettled(
+    names.map(async (name) => {
+      const content = await fetchSkillFile(name);
+      const dir = join(cache, name);
+      await mkdir(dir, { recursive: true });
+      await writeFile(join(dir, "SKILL.md"), content);
+      return name;
+    })
+  );
+
+  const fetched = results
+    .filter((r): r is PromiseFulfilledResult<string> => r.status === "fulfilled")
+    .map((r) => r.value);
+
+  await touchCache();
+  return fetched;
+}
+
+/** Get cached skill names, refreshing if stale */
+async function getSkillNames(forceRefresh: boolean): Promise<string[]> {
+  if (!forceRefresh && (await isCacheFresh())) {
+    return listCachedSkills();
+  }
+  try {
+    return await refreshCache();
+  } catch (err) {
+    // Fall back to cache if network fails
+    const cached = await listCachedSkills();
+    if (cached.length > 0) {
+      console.error(`\x1b[33mWarning: Could not fetch from GitHub (${(err as Error).message}), using cached skills.\x1b[0m`);
+      return cached;
+    }
+    throw err;
+  }
+}
+
+async function listCachedSkills(): Promise<string[]> {
+  const cache = cacheDir();
+  if (!existsSync(cache)) return [];
+  const entries = await readdir(cache, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isDirectory() && existsSync(join(cache, e.name, "SKILL.md")))
+    .map((e) => e.name);
+}
+
+async function readSkillFrontmatter(skillName: string): Promise<{ name?: string; description?: string }> {
+  const content = await readFile(join(cacheDir(), skillName, "SKILL.md"), "utf-8");
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const fm: Record<string, string> = {};
+  for (const line of match[1]!.split("\n")) {
+    const [key, ...rest] = line.split(":");
+    if (key && rest.length) fm[key.trim()] = rest.join(":").trim();
+  }
+  return fm;
+}
+
+/** Known agent platforms and their skills directories */
+const PLATFORMS: Record<string, { name: string; path: string }> = {
+  claude: { name: "Claude Code", path: join(homedir(), ".claude", "skills") },
+  codex: { name: "Codex CLI", path: join(homedir(), ".codex", "skills") },
+  opencode: { name: "OpenCode", path: join(homedir(), ".opencode", "skills") },
+};
+
+export function registerSkillsCommands(program: Command): void {
+  const skills = program.command("skills").description("Manage Readwise skills for AI agents");
+
+  skills
+    .command("list")
+    .description("List available skills (fetched from github.com/readwiseio/readwise-skills)")
+    .option("--refresh", "Force refresh from GitHub")
+    .action(async (opts: { refresh?: boolean }) => {
+      try {
+        const names = await getSkillNames(!!opts.refresh);
+        if (names.length === 0) {
+          console.log("No skills found.");
+          return;
+        }
+        console.log("Available skills:\n");
+        for (const name of names) {
+          const fm = await readSkillFrontmatter(name);
+          const desc = fm.description || "";
+          console.log(`  ${name.padEnd(22)} ${desc}`);
+        }
+        console.log(`\nRun \`readwise skills install <platform>\` to install. Platforms: ${Object.keys(PLATFORMS).join(", ")}`);
+      } catch (err) {
+        console.error(`\x1b[31mFailed to list skills: ${(err as Error).message}\x1b[0m`);
+        process.exitCode = 1;
+      }
+    });
+
+  skills
+    .command("install [platform]")
+    .description("Install skills to an agent platform (claude, codex, opencode)")
+    .option("--all", "Detect installed agents and install to all")
+    .option("--refresh", "Force refresh from GitHub before installing")
+    .action(async (platform?: string, opts?: { all?: boolean; refresh?: boolean }) => {
+      try {
+        const names = await getSkillNames(!!opts?.refresh);
+        if (names.length === 0) {
+          console.error("No skills found.");
+          process.exitCode = 1;
+          return;
+        }
+
+        let targets: { key: string; name: string; path: string }[] = [];
+
+        if (opts?.all) {
+          for (const [key, info] of Object.entries(PLATFORMS)) {
+            const parentDir = dirname(info.path);
+            if (existsSync(parentDir)) {
+              targets.push({ key, ...info });
+            }
+          }
+          if (targets.length === 0) {
+            console.log("No supported agents detected. Supported platforms: " + Object.keys(PLATFORMS).join(", "));
+            return;
+          }
+        } else if (platform) {
+          const info = PLATFORMS[platform.toLowerCase()];
+          if (!info) {
+            console.error(`Unknown platform: ${platform}`);
+            console.error(`Supported platforms: ${Object.keys(PLATFORMS).join(", ")}`);
+            process.exitCode = 1;
+            return;
+          }
+          targets = [{ key: platform.toLowerCase(), ...info }];
+        } else {
+          console.error("Specify a platform or use --all.");
+          console.error(`Supported platforms: ${Object.keys(PLATFORMS).join(", ")}`);
+          process.exitCode = 1;
+          return;
+        }
+
+        const cache = cacheDir();
+        for (const target of targets) {
+          console.log(`\nInstalling to ${target.name} (${target.path})...`);
+          await mkdir(target.path, { recursive: true });
+
+          for (const skillName of names) {
+            const srcFile = join(cache, skillName, "SKILL.md");
+            const destDir = join(target.path, skillName);
+            await mkdir(destDir, { recursive: true });
+            const content = await readFile(srcFile, "utf-8");
+            await writeFile(join(destDir, "SKILL.md"), content);
+            console.log(`  \u2713 ${skillName}`);
+          }
+        }
+
+        console.log("\nDone!");
+      } catch (err) {
+        console.error(`\x1b[31mFailed to install skills: ${(err as Error).message}\x1b[0m`);
+        process.exitCode = 1;
+      }
+    });
+
+  skills
+    .command("show <name>")
+    .description("Print the raw SKILL.md for a skill")
+    .option("--refresh", "Force refresh from GitHub")
+    .action(async (name: string, opts: { refresh?: boolean }) => {
+      try {
+        await getSkillNames(!!opts.refresh);
+        const skillPath = join(cacheDir(), name, "SKILL.md");
+        if (!existsSync(skillPath)) {
+          console.error(`Skill not found: ${name}`);
+          const available = await listCachedSkills();
+          if (available.length) console.error(`Available: ${available.join(", ")}`);
+          process.exitCode = 1;
+          return;
+        }
+        const content = await readFile(skillPath, "utf-8");
+        process.stdout.write(content);
+      } catch (err) {
+        console.error(`\x1b[31mFailed: ${(err as Error).message}\x1b[0m`);
+        process.exitCode = 1;
+      }
+    });
+
+  skills
+    .command("update")
+    .description("Force refresh skills from GitHub")
+    .action(async () => {
+      try {
+        console.log("Fetching skills from github.com/readwiseio/readwise-skills...");
+        const names = await refreshCache();
+        console.log(`Updated ${names.length} skills: ${names.join(", ")}`);
+      } catch (err) {
+        console.error(`\x1b[31mFailed to update: ${(err as Error).message}\x1b[0m`);
+        process.exitCode = 1;
+      }
+    });
+}