instrlint 0.1.1 → 0.1.3

package/README.md

@@ -149,7 +149,7 @@ npx instrlint install --claude-code --project
 npx instrlint install --codex
 ```
 
-Then in your editor:
+Then **restart Claude Code** to activate the command. Then in your editor:
 
 ```
 /instrlint
@@ -157,6 +157,8 @@ Then in your editor:
 /instrlint ci --fail-on warning
 ```
 
+> **Note:** Claude Code only loads custom commands at startup. `/reload-plugins` does not pick up newly installed commands.
+
 ## Score and grade
 
 | Grade | Score | Meaning |

package/README.zh-TW.md

@@ -155,7 +155,7 @@ npx instrlint install --claude-code --project
 npx instrlint install --codex
 ```
 
-安裝後在編輯器中使用：
+安裝後**重新啟動 Claude Code** 以啟用指令，然後在編輯器中使用：
 
 ```
 /instrlint
@@ -163,6 +163,8 @@ npx instrlint install --codex
 /instrlint ci --fail-on warning
 ```
 
+> **注意：** Claude Code 只在啟動時載入 custom commands。`/reload-plugins` 無法載入新安裝的指令。
+
 ## 分數與等級
 
 | 等級 | 分數 | 說明 |

package/dist/cli.cjs

@@ -32,7 +32,8 @@ var import_commander = require("commander");
 
 // src/commands/run-command.ts
 var import_child_process = require("child_process");
-var import_path8 = require("path");
+var import_readline = require("readline");
+var import_path10 = require("path");
 var import_chalk4 = __toESM(require("chalk"), 1);
 
 // src/core/scanner.ts
@@ -1592,9 +1593,13 @@ var en_default = {
   "ci.writtenTo": "\u2192 written to {{file}}",
   "initCi.created": "\u2713 Created {{path}}",
   "initCi.alreadyExists": "{{path}} already exists. Use --force to overwrite.",
-  "install.installed": "\u2713 Installed to {{path}}",
+  "install.installed": "\u2713 Installed to {{path}}\n  \u2192 Restart Claude Code to activate /instrlint",
   "install.alreadyExists": "{{path}} already exists. Use --force to overwrite.",
   "install.unknownTarget": "Specify --claude-code or --codex",
+  "install.outdatedTitle": "instrlint skill is outdated",
+  "install.outdatedVersions": "installed: {{installed}} \u2192 current: {{current}}",
+  "install.updateCmd": "npx instrlint install {{flag}} --force",
+  "install.updatePrompt": "Update skill now?",
   "fix.manualActions": "MANUAL ACTIONS NEEDED",
   "fix.hookCreate": "Add to .claude/settings.json:",
   "fix.hookWarning": "\u26A0 Hook executes shell commands \u2014 review carefully before adding",
@@ -1693,9 +1698,13 @@ var zh_TW_default = {
   "ci.writtenTo": "\u2192 \u5DF2\u5BEB\u5165 {{file}}",
   "initCi.created": "\u2713 \u5DF2\u5EFA\u7ACB {{path}}",
   "initCi.alreadyExists": "{{path}} \u5DF2\u5B58\u5728\u3002\u4F7F\u7528 --force \u8986\u84CB\u3002",
-  "install.installed": "\u2713 \u5DF2\u5B89\u88DD\u81F3 {{path}}",
+  "install.installed": "\u2713 \u5DF2\u5B89\u88DD\u81F3 {{path}}\n  \u2192 \u91CD\u65B0\u555F\u52D5 Claude Code \u5F8C\u5373\u53EF\u4F7F\u7528 /instrlint",
   "install.alreadyExists": "{{path}} \u5DF2\u5B58\u5728\u3002\u4F7F\u7528 --force \u8986\u84CB\u3002",
   "install.unknownTarget": "\u8ACB\u6307\u5B9A --claude-code \u6216 --codex",
+  "install.outdatedTitle": "instrlint skill \u7248\u672C\u904E\u820A",
+  "install.outdatedVersions": "\u5DF2\u5B89\u88DD\uFF1A{{installed}} \u2192 \u6700\u65B0\uFF1A{{current}}",
+  "install.updateCmd": "npx instrlint install {{flag}} --force",
+  "install.updatePrompt": "\u662F\u5426\u7ACB\u5373\u66F4\u65B0\uFF1F",
   "fix.manualActions": "\u9700\u8981\u624B\u52D5\u64CD\u4F5C",
   "fix.hookCreate": "\u52A0\u5165 .claude/settings.json\uFF1A",
   "fix.hookWarning": "\u26A0 Hook \u6703\u57F7\u884C shell command\uFF0C\u8ACB\u4ED4\u7D30\u78BA\u8A8D\u5F8C\u518D\u52A0\u5165",
@@ -2290,6 +2299,136 @@ function markdownStructureSuggestions(suggestions, projectRoot) {
   return lines;
 }
 
+// src/utils/skill-version.ts
+var import_fs10 = require("fs");
+var import_path8 = require("path");
+var import_os = require("os");
+var CURRENT_VERSION = "0.1.3";
+var VERSION_RE = /^instrlint-version:\s*(.+)$/m;
+function extractVersion(content) {
+  const m = VERSION_RE.exec(content);
+  return m ? m[1].trim() : null;
+}
+function readInstalledVersion(path) {
+  if (!(0, import_fs10.existsSync)(path)) return null;
+  try {
+    return extractVersion((0, import_fs10.readFileSync)(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function checkSkillUpdate(projectRoot) {
+  const candidates = [
+    {
+      path: (0, import_path8.join)(projectRoot, ".claude", "commands", "instrlint.md"),
+      isProject: true
+    },
+    {
+      path: (0, import_path8.join)((0, import_os.homedir)(), ".claude", "commands", "instrlint.md"),
+      isProject: false
+    }
+  ];
+  for (const { path, isProject } of candidates) {
+    const installed = readInstalledVersion(path);
+    if (installed !== null && installed !== CURRENT_VERSION) {
+      return {
+        installedVersion: installed,
+        currentVersion: CURRENT_VERSION,
+        installPath: path,
+        isProject
+      };
+    }
+  }
+  return null;
+}
+function injectVersion(content, version) {
+  return content.replace(/^(---\n[\s\S]*?)(---)$/m, `$1instrlint-version: ${version}
+$2`);
+}
+
+// src/commands/install-command.ts
+var import_fs11 = require("fs");
+var import_path9 = require("path");
+var import_os2 = require("os");
+var import_url = require("url");
+function resolveSkillFile(target) {
+  const thisFile = (0, import_url.fileURLToPath)(importMetaUrl);
+  const subDir = target === "claude-code" ? "claude-code" : "codex";
+  for (const levels of [2, 3]) {
+    const parts = Array(levels).fill("..");
+    const candidate = (0, import_path9.join)(thisFile, ...parts, "skills", subDir, "SKILL.md");
+    if ((0, import_fs11.existsSync)(candidate)) return candidate;
+  }
+  return (0, import_path9.join)(thisFile, "..", "..", "skills", subDir, "SKILL.md");
+}
+function readSkillContent(target) {
+  const skillPath = resolveSkillFile(target);
+  try {
+    const raw = (0, import_fs11.readFileSync)(skillPath, "utf8");
+    return injectVersion(raw, CURRENT_VERSION);
+  } catch {
+    throw new Error(
+      `Could not read skill file at ${skillPath}. Make sure the package is properly installed.`
+    );
+  }
+}
+function installClaudeCode(content, projectRoot, isProject, force, output) {
+  const targetDir = isProject ? (0, import_path9.join)(projectRoot, ".claude", "commands") : (0, import_path9.join)((0, import_os2.homedir)(), ".claude", "commands");
+  const targetPath = (0, import_path9.join)(targetDir, "instrlint.md");
+  if ((0, import_fs11.existsSync)(targetPath) && !force) {
+    output.error(t("install.alreadyExists", { path: targetPath }));
+    return { exitCode: 1, errorMessage: "file already exists" };
+  }
+  (0, import_fs11.mkdirSync)(targetDir, { recursive: true });
+  (0, import_fs11.writeFileSync)(targetPath, content, "utf8");
+  output.log(t("install.installed", { path: targetPath }));
+  return { exitCode: 0 };
+}
+function installCodex(content, projectRoot, force, output) {
+  const targetDir = (0, import_path9.join)(projectRoot, ".agents", "skills", "instrlint");
+  const targetPath = (0, import_path9.join)(targetDir, "SKILL.md");
+  if ((0, import_fs11.existsSync)(targetPath) && !force) {
+    output.error(t("install.alreadyExists", { path: targetPath }));
+    return { exitCode: 1, errorMessage: "file already exists" };
+  }
+  (0, import_fs11.mkdirSync)(targetDir, { recursive: true });
+  (0, import_fs11.writeFileSync)(targetPath, content, "utf8");
+  output.log(t("install.installed", { path: targetPath }));
+  return { exitCode: 0 };
+}
+function runInstall(opts, output = console) {
+  const projectRoot = opts.projectRoot ?? process.cwd();
+  const force = opts.force ?? false;
+  if (opts.claudeCode) {
+    let content;
+    try {
+      content = readSkillContent("claude-code");
+    } catch (err) {
+      output.error(String(err));
+      return { exitCode: 1, errorMessage: String(err) };
+    }
+    return installClaudeCode(
+      content,
+      projectRoot,
+      opts.project ?? false,
+      force,
+      output
+    );
+  }
+  if (opts.codex) {
+    let content;
+    try {
+      content = readSkillContent("codex");
+    } catch (err) {
+      output.error(String(err));
+      return { exitCode: 1, errorMessage: String(err) };
+    }
+    return installCodex(content, projectRoot, force, output);
+  }
+  output.error(t("install.unknownTarget"));
+  return { exitCode: 1, errorMessage: "no target specified" };
+}
+
 // src/commands/run-command.ts
 function isGitClean(cwd) {
   try {
@@ -2334,7 +2473,7 @@ async function runAll(opts, output = console) {
   const { score, grade } = calculateScore(allFindings, summary);
   const actionPlan = buildActionPlan(allFindings);
   const report = {
-    project: (0, import_path8.basename)(projectRoot),
+    project: (0, import_path10.basename)(projectRoot),
     tool: instructions.tool,
     score,
     grade,
@@ -2379,6 +2518,7 @@ async function runAll(opts, output = console) {
     printStructureSuggestions(suggestions, projectRoot, output);
     return { exitCode: 0 };
   }
+  const skillUpdate = checkSkillUpdate(projectRoot);
   if (opts.format === "json") {
     output.log(reportJson(report));
     return { exitCode: 0 };
@@ -2386,12 +2526,52 @@ async function runAll(opts, output = console) {
   if (opts.format === "markdown") {
     const mdSuggestions = buildStructureSuggestions(allFindings);
     const mdExtra = markdownStructureSuggestions(mdSuggestions, projectRoot);
-    output.log(reportMarkdown(report, mdExtra));
+    const updateSection = skillUpdate ? [
+      "",
+      `> \u26A0\uFE0F **${t("install.outdatedTitle")}** (${t("install.outdatedVersions", { installed: skillUpdate.installedVersion, current: skillUpdate.currentVersion })})`,
+      `> \`${t("install.updateCmd", { flag: skillUpdate.isProject ? "--claude-code --project" : "--claude-code" })}\``
+    ] : [];
+    output.log(reportMarkdown(report, [...mdExtra, ...updateSection]));
     return { exitCode: 0 };
   }
   printCombinedTerminal(report, output);
+  if (skillUpdate && process.stdout.isTTY) {
+    output.log("");
+    output.log(
+      `  ${import_chalk4.default.yellow("\u26A0")}  ${import_chalk4.default.bold(t("install.outdatedTitle"))} (${t("install.outdatedVersions", { installed: skillUpdate.installedVersion, current: skillUpdate.currentVersion })})`
+    );
+    const confirmed = await promptYesNo(
+      `  ${t("install.updatePrompt")}`,
+      output
+    );
+    if (confirmed) {
+      runInstall(
+        {
+          claudeCode: true,
+          project: skillUpdate.isProject,
+          force: true,
+          projectRoot
+        },
+        output
+      );
+    }
+    output.log("");
+  }
   return { exitCode: 0 };
 }
+function promptYesNo(question, output) {
+  return new Promise((resolve) => {
+    const rl = (0, import_readline.createInterface)({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(`${question} ${import_chalk4.default.gray("[Y/n]")} `, (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      resolve(trimmed === "" || trimmed === "y");
+    });
+  });
+}
 
 // src/commands/deadrules-command.ts
 var import_chalk5 = __toESM(require("chalk"), 1);
@@ -2552,8 +2732,8 @@ async function runStructure(opts, output = console) {
 }
 
 // src/commands/ci-command.ts
-var import_fs10 = require("fs");
-var import_path9 = require("path");
+var import_fs12 = require("fs");
+var import_path11 = require("path");
 
 // src/reporters/sarif.ts
 function severityToLevel(severity) {
@@ -2659,7 +2839,7 @@ async function runCi(opts, output = console) {
   const { score, grade } = calculateScore(allFindings, summary);
   const actionPlan = buildActionPlan(allFindings);
   const report = {
-    project: (0, import_path9.basename)(projectRoot),
+    project: (0, import_path11.basename)(projectRoot),
     tool: instructions.tool,
     score,
     grade,
@@ -2680,7 +2860,7 @@ async function runCi(opts, output = console) {
     formatted = reportJson(report);
   }
   if (opts.output != null) {
-    (0, import_fs10.writeFileSync)(opts.output, formatted, "utf8");
+    (0, import_fs12.writeFileSync)(opts.output, formatted, "utf8");
     const pass = !shouldFail(allFindings, failOn);
     const statusKey = pass ? "ci.passed" : "ci.failed";
     output.error(
@@ -2694,8 +2874,8 @@ async function runCi(opts, output = console) {
 }
 
 // src/commands/init-ci-command.ts
-var import_fs11 = require("fs");
-var import_path10 = require("path");
+var import_fs13 = require("fs");
+var import_path12 = require("path");
 function githubWorkflow() {
   return `name: instrlint
 
@@ -2764,14 +2944,14 @@ instrlint:
 function runInitCi(opts, output = console) {
   const projectRoot = opts.projectRoot ?? process.cwd();
   if (opts.github) {
-    const workflowDir = (0, import_path10.join)(projectRoot, ".github", "workflows");
-    const workflowPath = (0, import_path10.join)(workflowDir, "instrlint.yml");
-    if ((0, import_fs11.existsSync)(workflowPath) && !opts.force) {
+    const workflowDir = (0, import_path12.join)(projectRoot, ".github", "workflows");
+    const workflowPath = (0, import_path12.join)(workflowDir, "instrlint.yml");
+    if ((0, import_fs13.existsSync)(workflowPath) && !opts.force) {
       output.error(t("initCi.alreadyExists", { path: workflowPath }));
       return { exitCode: 1, errorMessage: "file already exists" };
     }
-    (0, import_fs11.mkdirSync)(workflowDir, { recursive: true });
-    (0, import_fs11.writeFileSync)(workflowPath, githubWorkflow(), "utf8");
+    (0, import_fs13.mkdirSync)(workflowDir, { recursive: true });
+    (0, import_fs13.writeFileSync)(workflowPath, githubWorkflow(), "utf8");
     output.log(t("initCi.created", { path: workflowPath }));
     return { exitCode: 0 };
   }
@@ -2783,88 +2963,6 @@ function runInitCi(opts, output = console) {
   return { exitCode: 1, errorMessage: "no target specified" };
 }
 
-// src/commands/install-command.ts
-var import_fs12 = require("fs");
-var import_path11 = require("path");
-var import_os = require("os");
-var import_url = require("url");
-function resolveSkillFile(target) {
-  const thisFile = (0, import_url.fileURLToPath)(importMetaUrl);
-  const subDir = target === "claude-code" ? "claude-code" : "codex";
-  for (const levels of [2, 3]) {
-    const parts = Array(levels).fill("..");
-    const candidate = (0, import_path11.join)(thisFile, ...parts, "skills", subDir, "SKILL.md");
-    if ((0, import_fs12.existsSync)(candidate)) return candidate;
-  }
-  return (0, import_path11.join)(thisFile, "..", "..", "skills", subDir, "SKILL.md");
-}
-function readSkillContent(target) {
-  const skillPath = resolveSkillFile(target);
-  try {
-    return (0, import_fs12.readFileSync)(skillPath, "utf8");
-  } catch {
-    throw new Error(
-      `Could not read skill file at ${skillPath}. Make sure the package is properly installed.`
-    );
-  }
-}
-function installClaudeCode(content, projectRoot, isProject, force, output) {
-  const targetDir = isProject ? (0, import_path11.join)(projectRoot, ".claude", "skills", "instrlint") : (0, import_path11.join)((0, import_os.homedir)(), ".claude", "skills", "instrlint");
-  const targetPath = (0, import_path11.join)(targetDir, "SKILL.md");
-  if ((0, import_fs12.existsSync)(targetPath) && !force) {
-    output.error(t("install.alreadyExists", { path: targetPath }));
-    return { exitCode: 1, errorMessage: "file already exists" };
-  }
-  (0, import_fs12.mkdirSync)(targetDir, { recursive: true });
-  (0, import_fs12.writeFileSync)(targetPath, content, "utf8");
-  output.log(t("install.installed", { path: targetPath }));
-  return { exitCode: 0 };
-}
-function installCodex(content, projectRoot, force, output) {
-  const targetDir = (0, import_path11.join)(projectRoot, ".agents", "skills", "instrlint");
-  const targetPath = (0, import_path11.join)(targetDir, "SKILL.md");
-  if ((0, import_fs12.existsSync)(targetPath) && !force) {
-    output.error(t("install.alreadyExists", { path: targetPath }));
-    return { exitCode: 1, errorMessage: "file already exists" };
-  }
-  (0, import_fs12.mkdirSync)(targetDir, { recursive: true });
-  (0, import_fs12.writeFileSync)(targetPath, content, "utf8");
-  output.log(t("install.installed", { path: targetPath }));
-  return { exitCode: 0 };
-}
-function runInstall(opts, output = console) {
-  const projectRoot = opts.projectRoot ?? process.cwd();
-  const force = opts.force ?? false;
-  if (opts.claudeCode) {
-    let content;
-    try {
-      content = readSkillContent("claude-code");
-    } catch (err) {
-      output.error(String(err));
-      return { exitCode: 1, errorMessage: String(err) };
-    }
-    return installClaudeCode(
-      content,
-      projectRoot,
-      opts.project ?? false,
-      force,
-      output
-    );
-  }
-  if (opts.codex) {
-    let content;
-    try {
-      content = readSkillContent("codex");
-    } catch (err) {
-      output.error(String(err));
-      return { exitCode: 1, errorMessage: String(err) };
-    }
-    return installCodex(content, projectRoot, force, output);
-  }
-  output.error(t("install.unknownTarget"));
-  return { exitCode: 1, errorMessage: "no target specified" };
-}
-
 // src/cli.ts
 var program = new import_commander.Command();
 program.enablePositionalOptions().name("instrlint").description(
@@ -2882,27 +2980,27 @@ program.command("budget").description("Token budget analysis only").option(
   "--format <type>",
   "output format (terminal|json|markdown)",
   "terminal"
-).option("--tool <name>", "force tool detection (claude-code|codex|cursor)").action(async function() {
+).option("--lang <locale>", "output language (en|zh-TW)").option("--tool <name>", "force tool detection (claude-code|codex|cursor)").action(async function() {
   const opts = this.opts();
-  const lang = this.parent?.opts()?.lang;
+  const lang = opts.lang ?? this.parent?.opts()?.lang;
   const result = await runBudget({
     ...opts,
     ...lang !== void 0 && { lang }
   });
   if (result.exitCode !== 0) process.exit(result.exitCode);
 });
-program.command("deadrules").description("Dead rule detection only").option("--format <type>", "output format (terminal|json)", "terminal").option("--tool <name>", "force tool detection (claude-code|codex|cursor)").action(async function() {
+program.command("deadrules").description("Dead rule detection only").option("--format <type>", "output format (terminal|json)", "terminal").option("--lang <locale>", "output language (en|zh-TW)").option("--tool <name>", "force tool detection (claude-code|codex|cursor)").action(async function() {
   const opts = this.opts();
-  const lang = this.parent?.opts()?.lang;
+  const lang = opts.lang ?? this.parent?.opts()?.lang;
   const result = await runDeadRules({
     ...opts,
     ...lang !== void 0 && { lang }
   });
   if (result.exitCode !== 0) process.exit(result.exitCode);
 });
-program.command("structure").description("Structural analysis only").option("--format <type>", "output format (terminal|json)", "terminal").option("--tool <name>", "force tool detection (claude-code|codex|cursor)").action(async function() {
+program.command("structure").description("Structural analysis only").option("--format <type>", "output format (terminal|json)", "terminal").option("--lang <locale>", "output language (en|zh-TW)").option("--tool <name>", "force tool detection (claude-code|codex|cursor)").action(async function() {
   const opts = this.opts();
-  const lang = this.parent?.opts()?.lang;
+  const lang = opts.lang ?? this.parent?.opts()?.lang;
   const result = await runStructure({
     ...opts,
     ...lang !== void 0 && { lang }