@takara-ai/miru-code 1.5.3 → 1.7.2

package/src/help.ts

@@ -37,24 +37,23 @@ export function printMainHelp(): void {
   commandRow("locate", "Exact substring location in the index");
   commandRow("expand", "Adjacent chunks in the same file as a hit");
   commandRow("find-related", "Find chunks related to a file:line");
-  commandRow("setup", "Save your Takara API key locally");
+  commandRow("setup", "Authenticate with Takara");
   commandRow("install", "Configure miru across coding agents");
   commandRow("uninstall", "Remove miru agent configuration");
   commandRow("benchmark", "Turn MCP benchmark mode on or off");
   commandRow("init", "Write a project-local sub-agent file");
   commandRow("clear", "Remove cached index for a path");
-  commandRow("help", "Show help for a command");
   divider();
 
   section("Quick start");
   writeStdout("  miru setup && miru install");
   writeStdout('  miru search "auth middleware" ./src');
   writeStdout("");
-  hint("miru help <command>  ·  miru -h for environment variables  ·  miru -v for version");
+  hint("miru <command> -h  ·  miru -v for version");
   writeStdout("");
 }
 
-export function printEnvHelp(): void {
+export function printEnvironmentHelp(): void {
   section("Environment");
   writeStdout(`  ${TAKARA_API_KEY_ENV}`);
   writeStdout("      Takara bearer token for embeddings");
@@ -67,6 +66,9 @@ export function printEnvHelp(): void {
   writeStdout("  MIRU_TOKENIZER_JSON");
   writeStdout("      Path to tokenizer.json (default: <package>/tokenizer/tokenizer.json)");
   writeStdout("");
+}
+
+export function printSageMakerHelp(): void {
   section("Self-hosted (AWS SageMaker)");
   writeStdout("  MIRU_SAGEMAKER_ENDPOINT_ARN");
   writeStdout("      arn:aws:sagemaker:<region>:<account-id>:endpoint/<name> — set this to");
@@ -90,13 +92,17 @@ export function printEnvHelp(): void {
   writeStdout("");
 }
 
-export function printFullHelp(): void {
-  printMainHelp();
-  printEnvHelp();
+export function printEnvHelp(): void {
+  printEnvironmentHelp();
+  printSageMakerHelp();
 }
 
 export function printCommandHelp(command: string): void {
   switch (command) {
+    case "env":
+    case "environment":
+      printEnvironmentHelp();
+      return;
     case "search":
       commandHeader("search", "Hybrid semantic + keyword search.");
       section("Usage");
@@ -147,13 +153,14 @@ export function printCommandHelp(command: string): void {
       writeStdout("");
       return;
     case "setup":
-      commandHeader("setup", "Store and validate Takara or self-hosted SageMaker credentials.");
+      commandHeader("setup", "Authenticate with Takara or self-hosted SageMaker credentials.");
       section("Usage");
-      writeStdout("  miru setup [--key TOKEN] [--force] [--clear]");
+      writeStdout("  miru setup [--device] [--key TOKEN] [--force] [--clear]");
       writeStdout("  miru setup --sagemaker --arn ENDPOINT_ARN --profile NAME");
       section("Options (Takara)");
-      writeStdout("  --key, -k TOKEN     Non-interactive key entry");
-      writeStdout("  --force             Replace an existing stored key");
+      writeStdout("  --device            Start device-code login (default when interactive)");
+      writeStdout("  --key, -k TOKEN     Non-interactive: store a bearer token directly");
+      writeStdout("  --force             Replace existing stored credentials");
       writeStdout("  --clear             Remove stored credentials");
       section("Options (SageMaker)");
       writeStdout("  --sagemaker         Switch setup to self-hosted SageMaker mode");
@@ -170,15 +177,24 @@ export function printCommandHelp(command: string): void {
       return;
     case "install":
       commandHeader("install", "Interactive global agent setup.");
-      writeStdout("Configures MCP server, instructions, and sub-agent files under");
+      writeStdout("Configures MCP server, instructions, sub-agent files, and optional");
+      writeStdout("experimental integrations (search hooks, Caveman, STE writing) under");
       writeStdout("your user config (~/.claude, ~/.cursor, etc.).");
       writeStdout("");
+      writeStdout(
+        "Caveman = chat compression (/caveman). STE = clear docs (/ste). Off by default.",
+      );
+      writeStdout("Caveman is supported on all Miru installer IDEs (shared path for most IDEs).");
+      writeStdout(
+        "STE is supported on all Miru installer IDEs (same shared-path ownership model).",
+      );
       writeStdout("Run miru setup first, or set TAKARA_API_KEY for MCP env expansion.");
       writeStdout("");
       return;
     case "uninstall":
       commandHeader("uninstall", "Remove miru configuration from agents.");
-      writeStdout("Removes MCP entries, marked instruction blocks, and global sub-agents.");
+      writeStdout("Removes MCP entries, marked instruction blocks, global sub-agents,");
+      writeStdout("and selected optional integrations (hooks, Caveman, STE skills).");
       writeStdout("Also deletes the global benchmark report from Miru's state directory.");
       writeStdout("");
       return;

package/src/installer/agents.ts

@@ -9,6 +9,52 @@ function copilotHooksPath(home: string): string {
   return join(home, ".copilot", "hooks", "miru-search.json");
 }
 
+/** Shared Copilot / VS Code / Visual Studio config root (MCP, hooks, agents). */
+export function copilotHomeDir(home: string): string {
+  return join(home, ".copilot");
+}
+
+/**
+ * Vendors that do not scan `~/.agents/skills/` and need a native skill dir
+ * (Caveman + STE).
+ */
+export type NativeSkillVendor = "claude" | "kiro";
+
+/** @deprecated Use NativeSkillVendor. */
+export type NativeCavemanVendor = NativeSkillVendor;
+
+function skillMd(home: string, rootDir: string, skillName: string): string {
+  return join(home, rootDir, "skills", skillName, "SKILL.md");
+}
+
+function skillDir(home: string, rootDir: string, skillName: string): string {
+  return join(home, rootDir, "skills", skillName);
+}
+
+/**
+ * Cross-agent Agent Skills root (`~/.agents/skills/…`).
+ * Used by Cursor, Gemini, OpenCode, Codex, Windsurf, and Copilot-family IDEs.
+ * Claude Code and Kiro still use vendor-native skill dirs.
+ */
+export function agentsCavemanSkillPath(home: string): string {
+  return skillMd(home, ".agents", "caveman");
+}
+
+/** Claude Code / Kiro native Caveman skill path. */
+export function nativeCavemanSkillPath(home: string, vendor: NativeSkillVendor): string {
+  return skillMd(home, `.${vendor}`, "caveman");
+}
+
+/** Shared STE skill directory under `~/.agents/skills/ste`. */
+export function agentsSteSkillDir(home: string): string {
+  return skillDir(home, ".agents", "ste");
+}
+
+/** Claude Code / Kiro native STE skill directory. */
+export function nativeSteSkillDir(home: string, vendor: NativeSkillVendor): string {
+  return skillDir(home, `.${vendor}`, "ste");
+}
+
 function kiroHooksPath(home: string): string {
   return join(home, ".kiro", "settings", "hooks.json");
 }
@@ -17,10 +63,14 @@ function windsurfHooksPath(home: string): string {
   return join(home, ".codeium", "windsurf", "hooks.json");
 }
 
-function opencodePluginPath(home: string): string {
+/** OpenCode config root (`$XDG_CONFIG_HOME/opencode` or `~/.config/opencode`). */
+export function opencodeConfigDir(home: string): string {
   const xdg = process.env.XDG_CONFIG_HOME;
-  const base = xdg ? join(xdg, "opencode") : join(home, ".config", "opencode");
-  return join(base, "plugins", "miru-search-guard.ts");
+  return xdg ? join(xdg, "opencode") : join(home, ".config", "opencode");
+}
+
+function opencodePluginPath(home: string): string {
+  return join(opencodeConfigDir(home), "plugins", "miru-search-guard.ts");
 }
 
 export type InstallAction =
@@ -92,11 +142,19 @@ export interface AgentTarget {
   hooksFormat: HooksFormat | null;
   subagentPath: string | null;
   subagentId: AgentId | null;
+  /**
+   * On-demand Caveman Agent Skill (`…/skills/caveman/SKILL.md`), or null if
+   * unsupported.
+   */
+  cavemanSkillPath: string | null;
+  /**
+   * On-demand STE skill directory (`…/skills/ste/`), or null if unsupported.
+   */
+  steSkillDir: string | null;
 }
 
 export function opencodeMcpPath(): string {
-  const xdg = process.env.XDG_CONFIG_HOME;
-  const base = xdg ? join(xdg, "opencode") : join(HOME, ".config", "opencode");
+  const base = opencodeConfigDir(HOME);
   const jsonc = join(base, "opencode.jsonc");
   const json = join(base, "opencode.json");
   if (existsSync(jsonc)) {
@@ -163,6 +221,9 @@ function jsonMcp(path: string, key: string, entry: Record<string, unknown>): Mcp
   return { path, key, memberKey: "miru", entry, format: "json" };
 }
 
+const SHARED_CAVEMAN_SKILL = agentsCavemanSkillPath(HOME);
+const SHARED_STE_SKILL_DIR = agentsSteSkillDir(HOME);
+
 export const AGENT_TARGETS: AgentTarget[] = [
   {
     id: "claude",
@@ -176,6 +237,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     hooksFormat: "claude",
     subagentPath: join(HOME, ".claude", "agents", "miru-code.md"),
     subagentId: "claude",
+    cavemanSkillPath: nativeCavemanSkillPath(HOME, "claude"),
+    steSkillDir: nativeSteSkillDir(HOME, "claude"),
   },
   {
     id: "cursor",
@@ -189,6 +252,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     hooksFormat: "cursor",
     subagentPath: join(HOME, ".cursor", "agents", "miru-code.md"),
     subagentId: "cursor",
+    cavemanSkillPath: SHARED_CAVEMAN_SKILL,
+    steSkillDir: SHARED_STE_SKILL_DIR,
   },
   {
     id: "gemini",
@@ -202,50 +267,57 @@ export const AGENT_TARGETS: AgentTarget[] = [
     hooksFormat: "gemini",
     subagentPath: join(HOME, ".gemini", "agents", "miru-code.md"),
     subagentId: "gemini",
+    cavemanSkillPath: SHARED_CAVEMAN_SKILL,
+    steSkillDir: SHARED_STE_SKILL_DIR,
   },
   {
     id: "kiro",
     displayName: "Kiro",
     binary: "kiro",
     configDir: join(HOME, ".kiro"),
-    mcp: jsonMcp(join(HOME, ".kiro", "settings", "mcp.json"), "mcpServers", {
-      ...STDIO_SERVER_CONFIG,
-      env: {
-        PATH: "/usr/local/bin:/usr/bin:/bin",
-      },
-    }),
+    mcp: jsonMcp(join(HOME, ".kiro", "settings", "mcp.json"), "mcpServers", STDIO_SERVER_CONFIG),
     instructionsPath: join(HOME, ".kiro", "steering", "miru.md"),
     cursorRulesPath: null,
     hooksPath: kiroHooksPath(HOME),
     hooksFormat: "kiro",
     subagentPath: join(HOME, ".kiro", "agents", "miru-code.md"),
     subagentId: "kiro",
+    cavemanSkillPath: nativeCavemanSkillPath(HOME, "kiro"),
+    steSkillDir: nativeSteSkillDir(HOME, "kiro"),
   },
   {
     id: "opencode",
     displayName: "OpenCode",
     binary: "opencode",
-    configDir: join(HOME, ".config", "opencode"),
+    configDir: opencodeConfigDir(HOME),
     mcp: jsonMcp(opencodeMcpPath(), "mcp", OPENCODE_SERVER_CONFIG),
-    instructionsPath: join(HOME, ".config", "opencode", "AGENTS.md"),
+    instructionsPath: join(opencodeConfigDir(HOME), "AGENTS.md"),
     cursorRulesPath: null,
     hooksPath: opencodePluginPath(HOME),
     hooksFormat: "opencode",
-    subagentPath: join(HOME, ".config", "opencode", "agents", "miru-code.md"),
+    subagentPath: join(opencodeConfigDir(HOME), "agents", "miru-code.md"),
     subagentId: "opencode",
+    cavemanSkillPath: SHARED_CAVEMAN_SKILL,
+    steSkillDir: SHARED_STE_SKILL_DIR,
   },
   {
     id: "copilot",
     displayName: "GitHub Copilot",
     binary: null,
     configDir: join(HOME, ".config", "github-copilot"),
-    mcp: jsonMcp(join(HOME, ".copilot", "mcp-config.json"), "mcpServers", BARE_STDIO_SERVER_CONFIG),
+    mcp: jsonMcp(
+      join(copilotHomeDir(HOME), "mcp-config.json"),
+      "mcpServers",
+      BARE_STDIO_SERVER_CONFIG,
+    ),
     instructionsPath: null,
     cursorRulesPath: null,
     hooksPath: copilotHooksPath(HOME),
     hooksFormat: "vscode",
-    subagentPath: join(HOME, ".copilot", "agents", "miru-code.agent.md"),
+    subagentPath: join(copilotHomeDir(HOME), "agents", "miru-code.agent.md"),
     subagentId: "copilot",
+    cavemanSkillPath: SHARED_CAVEMAN_SKILL,
+    steSkillDir: SHARED_STE_SKILL_DIR,
   },
   {
     id: "codex",
@@ -265,6 +337,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     hooksFormat: "claude",
     subagentPath: null,
     subagentId: null,
+    cavemanSkillPath: SHARED_CAVEMAN_SKILL,
+    steSkillDir: SHARED_STE_SKILL_DIR,
   },
   {
     id: "vscode",
@@ -278,6 +352,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     hooksFormat: "vscode",
     subagentPath: null,
     subagentId: null,
+    cavemanSkillPath: SHARED_CAVEMAN_SKILL,
+    steSkillDir: SHARED_STE_SKILL_DIR,
   },
   {
     id: "windsurf",
@@ -291,6 +367,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     hooksFormat: "windsurf",
     subagentPath: null,
     subagentId: null,
+    cavemanSkillPath: SHARED_CAVEMAN_SKILL,
+    steSkillDir: SHARED_STE_SKILL_DIR,
   },
   {
     id: "visualstudio",
@@ -304,6 +382,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     hooksFormat: "vscode",
     subagentPath: null,
     subagentId: null,
+    cavemanSkillPath: SHARED_CAVEMAN_SKILL,
+    steSkillDir: SHARED_STE_SKILL_DIR,
   },
 ];
 
@@ -330,6 +410,10 @@ export async function isAgentDetected(agent: AgentTarget): Promise<boolean> {
     }
     return false;
   }
+  // Copilot-specific artifacts only — ~/.copilot alone is shared with VS Code / VS.
+  if (agent.id === "copilot") {
+    return isCopilotInstalled(HOME);
+  }
   if (agent.binary && (await commandOnPath(agent.binary))) {
     return true;
   }
@@ -338,3 +422,21 @@ export async function isAgentDetected(agent: AgentTarget): Promise<boolean> {
   }
   return false;
 }
+
+/**
+ * True when Copilot-specific config exists. Does not treat shared
+ * `~/.copilot` hooks (also used by VS Code / Visual Studio) as enough.
+ */
+export function isCopilotInstalled(home: string = HOME): boolean {
+  if (existsSync(join(home, ".config", "github-copilot"))) {
+    return true;
+  }
+  const copilot = copilotHomeDir(home);
+  if (existsSync(join(copilot, "mcp-config.json"))) {
+    return true;
+  }
+  if (existsSync(join(copilot, "agents"))) {
+    return true;
+  }
+  return false;
+}

package/src/installer/caveman-shared.ts

@@ -0,0 +1,51 @@
+import type { AgentTarget, InstallAction } from "./agents.ts";
+import {
+  ensureSharedSkillOwnersOnInstall,
+  isSharedSkillPath,
+  removeSkillMdAndOwners,
+  resolveSharedSkillUninstall,
+  type SharedSkillCtx,
+  type SharedSkillUninstallDecision,
+  SKILL_OWNERS_FILE,
+  type SkillPathOf,
+} from "./shared-skill.ts";
+
+/** @deprecated Prefer SKILL_OWNERS_FILE — same sidecar name for all shared skills. */
+export const CAVEMAN_OWNERS_FILE = SKILL_OWNERS_FILE;
+
+/** Context for shared `~/.agents/skills` Caveman install/uninstall. */
+export type CavemanSharedCtx = SharedSkillCtx;
+
+export type SharedCavemanUninstallDecision = SharedSkillUninstallDecision;
+
+const cavemanPathOf: SkillPathOf = (agent) => agent.cavemanSkillPath;
+
+export function isSharedCavemanPath(path: string, allAgents: AgentTarget[]): boolean {
+  return isSharedSkillPath(path, allAgents, cavemanPathOf);
+}
+
+export async function ensureSharedCavemanOwnersOnInstall(
+  skillDir: string,
+  skillPath: string,
+  agent: AgentTarget,
+  ctx: CavemanSharedCtx,
+): Promise<void> {
+  return ensureSharedSkillOwnersOnInstall(skillDir, skillPath, agent, ctx, cavemanPathOf);
+}
+
+export async function resolveSharedCavemanUninstall(
+  path: string,
+  skillDir: string,
+  agent: AgentTarget,
+  ctx: CavemanSharedCtx,
+): Promise<SharedCavemanUninstallDecision> {
+  return resolveSharedSkillUninstall(path, skillDir, agent, ctx, cavemanPathOf);
+}
+
+/** Remove SKILL.md and owners sidecar; leave sibling skill folders untouched. */
+export async function removeCavemanSkillFiles(
+  path: string,
+  skillDir: string,
+): Promise<Extract<InstallAction, "removed" | "not-found">> {
+  return removeSkillMdAndOwners(path, skillDir);
+}

package/src/installer/config.ts

@@ -616,3 +616,76 @@ export async function removeTomlBlock(path: string): Promise<InstallAction> {
   await Bun.write(path, `${remaining}\n`);
   return "removed";
 }
+
+/**
+ * Ensure Codex loads Agent Skills: `[features] skills = true` in config.toml.
+ * Does not disable the flag on uninstall (other skills may still need it).
+ */
+export function codexSkillsFeatureEnabled(text: string): boolean {
+  const lines = text.split("\n");
+  let inFeatures = false;
+  for (const line of lines) {
+    const tableKey = line.split("#")[0]?.trim() ?? "";
+    if (tableKey.startsWith("[") && tableKey.endsWith("]")) {
+      inFeatures = tableKey === "[features]";
+      continue;
+    }
+    if (!inFeatures) {
+      continue;
+    }
+    const value = line.split("#")[0]?.match(/^\s*skills\s*=\s*(true|false)\s*$/i)?.[1];
+    if (value?.toLowerCase() === "true") {
+      return true;
+    }
+  }
+  return false;
+}
+
+export async function ensureCodexSkillsFeature(path: string): Promise<InstallAction> {
+  const existed = await Bun.file(path).exists();
+  const existing = existed ? await Bun.file(path).text() : "";
+  if (codexSkillsFeatureEnabled(existing)) {
+    return "unchanged";
+  }
+  const lines = existing.length > 0 ? existing.split("\n") : [];
+
+  let featuresIdx = -1;
+  let skillsIdx = -1;
+  let inFeatures = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const tableKey = (lines[i] ?? "").split("#")[0]?.trim() ?? "";
+    if (tableKey.startsWith("[") && tableKey.endsWith("]")) {
+      if (tableKey === "[features]") {
+        inFeatures = true;
+        featuresIdx = i;
+        continue;
+      }
+      inFeatures = false;
+      continue;
+    }
+    if (inFeatures && /^\s*skills\s*=/.test(lines[i] ?? "")) {
+      skillsIdx = i;
+    }
+  }
+
+  if (featuresIdx >= 0 && skillsIdx >= 0) {
+    lines[skillsIdx] = "skills = true";
+    const next = `${lines.join("\n").replace(/\n+$/, "")}\n`;
+    await Bun.write(path, next);
+    return "updated";
+  }
+
+  if (featuresIdx >= 0) {
+    lines.splice(featuresIdx + 1, 0, "skills = true");
+    const next = `${lines.join("\n").replace(/\n+$/, "")}\n`;
+    await Bun.write(path, next);
+    return "updated";
+  }
+
+  const block = "[features]\nskills = true\n";
+  const base = existing.replace(/\n+$/, "");
+  const next = base.length > 0 ? `${base}\n\n${block}` : block;
+  await Bun.write(path, next.endsWith("\n") ? next : `${next}\n`);
+  return existed ? "updated" : "created";
+}

package/src/installer/copilot-family.ts

@@ -0,0 +1,8 @@
+/** Agents that share `~/.copilot` hooks. Caveman uses `~/.agents/skills`. */
+export const COPILOT_FAMILY_IDS = ["copilot", "vscode", "visualstudio"] as const;
+
+export type CopilotFamilyId = (typeof COPILOT_FAMILY_IDS)[number];
+
+export function isCopilotFamilyId(id: string): id is CopilotFamilyId {
+  return (COPILOT_FAMILY_IDS as readonly string[]).includes(id);
+}

package/src/installer/hooks/install.ts

@@ -2,11 +2,11 @@ import { unlink } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import type { HooksFormat, InstallAction } from "../agents.ts";
 import { stripJsonComments } from "../config.ts";
+import { isCopilotFamilyId } from "../copilot-family.ts";
 
 const HOOK_GUARD_MARKER = "hook-guard";
 const MIRU_HOOK_MARKER = "miru-search";
 const VSCODE_OWNERS_KEY = "miruOwners";
-const SHARED_VSCODE_HOOK_OWNERS = ["copilot", "vscode", "visualstudio"] as const;
 
 const MATCHERS = {
   cursor: "Grep|Glob|Shell|SemanticSearch",
@@ -346,22 +346,11 @@ export async function mergeVscodeHooks(path: string, owner?: string): Promise<In
 
   const currentOwners = Array.isArray(parsed[VSCODE_OWNERS_KEY])
     ? (parsed[VSCODE_OWNERS_KEY] as unknown[]).filter(
-        (item): item is string =>
-          typeof item === "string" &&
-          SHARED_VSCODE_HOOK_OWNERS.includes(item as (typeof SHARED_VSCODE_HOOK_OWNERS)[number]),
+        (item): item is string => typeof item === "string" && isCopilotFamilyId(item),
       )
     : [];
   const nextOwners = owner
-    ? Array.from(
-        new Set([
-          ...currentOwners,
-          ...(SHARED_VSCODE_HOOK_OWNERS.includes(
-            owner as (typeof SHARED_VSCODE_HOOK_OWNERS)[number],
-          )
-            ? [owner]
-            : []),
-        ]),
-      )
+    ? Array.from(new Set([...currentOwners, ...(isCopilotFamilyId(owner) ? [owner] : [])]))
     : currentOwners;
 
   const next = {