@skilly-hand/skilly-hand 0.23.0 → 0.23.1

package/CHANGELOG.md

@@ -16,6 +16,26 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.23.1] - 2026-04-13
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.23.1)
+
+### Added
+- Added an Inquirer-powered guided home launcher with searchable command discovery and a built-in Command Guide.
+- Added shared CLI command metadata in `packages/cli/src/command-registry.js` and wired help/interactive flows to consume it.
+- Added `scripts/review-rangers-check.mjs` plus `npm run review:rangers`, and integrated it into `verify:publish`.
+
+### Changed
+- Updated CLI help output to include a dedicated Commands section sourced from the shared command registry.
+- Updated docs to describe the new interactive launcher and mark `--classic` as a deprecated compatibility flag.
+- Updated dependency policy and script contract tests for the new release gates and runtime dependency set.
+
+### Fixed
+- Added guard tests to prevent reintroducing `react`/`ink` runtime dependencies after the interactive stack migration.
+
+### Removed
+- Removed the legacy Ink full-screen UI implementation (`packages/cli/src/ink-ui.js`) and related tests.
+- Removed runtime dependencies on `ink` and `react` in favor of `inquirer`.
+
 ## [0.23.0] - 2026-04-12
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.23.0)
 

package/README.md

@@ -36,7 +36,8 @@
 npx skilly-hand
 ```
 
-`npx skilly-hand` opens a full-screen skilly-hand terminal UI when running in a TTY.
+`npx skilly-hand` opens an interactive prompt workflow when running in a TTY.
+The guided home supports type-to-filter command discovery and includes a built-in Command Guide.
 
 ---
 
@@ -55,7 +56,7 @@ npx skilly-hand
 | Flag | Description |
 | ---- | ----------- |
 | `--json` | Emit machine-readable output and disable interactive prompts |
-| `--classic` | Force plain text command mode and skip full-screen TUI |
+| `--classic` | Deprecated compatibility flag that keeps plain command mode (launcher disabled) |
 | `--yes`, `-y` | Skip confirmation prompts for mutating commands (`install`, `uninstall`) |
 | `--dry-run` | Preview install plan without writing files |
 | `--agent`, `-a <name>` | Target a specific assistant (repeatable; e.g. `--agent claude --agent cursor`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {
@@ -35,7 +35,8 @@
     "security:check": "node ./scripts/security-check.mjs --strict-deps",
     "verify:packlist": "node ./scripts/verify-packlist.mjs",
     "verify:versions": "node ./scripts/verify-versions.mjs",
-    "verify:publish": "npm run verify:versions && npm run deps:policy:check && npm run security:check && npm run catalog:check && npm test && npm run verify:packlist",
+    "review:rangers": "node ./scripts/review-rangers-check.mjs",
+    "verify:publish": "npm run verify:versions && npm run deps:policy:check && npm run security:check && npm run catalog:check && npm test && npm run review:rangers && npm run verify:packlist",
     "publish:prepare": "npm run verify:publish && npm pack --dry-run --json",
     "publish:otp": "node ./scripts/publish-with-otp.mjs",
     "publish:next": "node ./scripts/publish-with-otp.mjs --tag next",
@@ -49,7 +50,6 @@
     "doctor": "node ./packages/cli/src/bin.js doctor"
   },
   "dependencies": {
-    "ink": "7.0.0",
-    "react": "19.2.5"
+    "inquirer": "13.4.1"
   }
 }

package/packages/catalog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/catalog",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "private": true,
   "type": "module"
 }

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/cli",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "private": true,
   "type": "module",
   "bin": {

package/packages/cli/src/bin.js

@@ -14,7 +14,8 @@ import {
 } from "../../core/src/index.js";
 import { createTerminalRenderer } from "../../core/src/terminal.js";
 import { detectProject } from "../../detectors/src/index.js";
-import { confirmWithInk, launchInkApp } from "./ink-ui.js";
+import { createInquirerInteractiveUi } from "./inquirer-ui.js";
+import { formatHelpUsageLines, getCliCommands, getInteractiveCommands } from "./command-registry.js";
 import {
   createResultDoc,
   kvBlock,
@@ -90,20 +91,17 @@ export function parseArgs(argv) {
 }
 
 function buildHelpText(renderer, appVersion) {
-  const usage = renderer.section("Usage", renderer.list([
-    "npx skilly-hand                  # interactive launcher when running in a TTY",
-    "npx skilly-hand install",
-    "npx skilly-hand native setup",
-    "npx skilly-hand detect",
-    "npx skilly-hand list",
-    "npx skilly-hand doctor",
-    "npx skilly-hand uninstall"
-  ], { bullet: "-" }));
+  const usage = renderer.section("Usage", renderer.list(formatHelpUsageLines(), { bullet: "-" }));
+
+  const commands = renderer.section("Commands", renderer.list(
+    getCliCommands().map((command) => `${command.usage}  # ${command.description}`),
+    { bullet: "-" }
+  ));
 
   const flags = renderer.section("Flags", renderer.list([
     "--dry-run                     Show install plan without writing files",
     "--json                        Emit stable JSON output for automation",
-    "--classic                     Force plain text command mode (skip full-screen TUI)",
+    "--classic                     Deprecated alias for plain command mode (launcher disabled)",
     "--yes, -y                     Skip install/uninstall confirmations",
     "--verbose, -v                 Reserved for future debug detail",
     "--agent, -a <name>            standard|codex|claude|cursor|gemini|copilot|antigravity|windsurf|trae (repeatable)",
@@ -125,6 +123,7 @@ function buildHelpText(renderer, appVersion) {
   return renderer.joinBlocks([
     renderer.banner(appVersion),
     usage,
+    commands,
     flags,
     examples
   ]);
@@ -474,8 +473,11 @@ async function runInteractiveSession({
   appVersion,
   interactiveUi
 }) {
+  const interactiveCommands = getInteractiveCommands();
+
   await interactiveUi.launch({
     appVersion,
+    commands: interactiveCommands,
     actions: {
       async runCommandBundle(command) {
         if (command === "native-setup") {
@@ -738,10 +740,7 @@ export async function runCli({
   env = process.env,
   platform = process.platform,
   services: providedServices = {},
-  interactiveUi = {
-    launch: ({ appVersion, actions }) => launchInkApp({ appVersion, actions }),
-    confirm: ({ message, defaultValue }) => confirmWithInk({ message, defaultValue })
-  },
+  interactiveUi = createInquirerInteractiveUi(),
   appVersion = version,
   cwdResolver = process.cwd
 } = {}) {
@@ -754,15 +753,7 @@ export async function runCli({
       renderer.writeJson({
         command: command || "install",
         help: true,
-        usage: [
-          "npx skilly-hand",
-          "npx skilly-hand install",
-          "npx skilly-hand native setup",
-          "npx skilly-hand detect",
-          "npx skilly-hand list",
-          "npx skilly-hand doctor",
-          "npx skilly-hand uninstall"
-        ]
+        usage: formatHelpUsageLines().map((line) => line.split("#")[0].trim())
       });
       return;
     }
@@ -773,6 +764,10 @@ export async function runCli({
 
   const cwd = path.resolve(flags.cwd || cwdResolver());
 
+  if (flags.classic && !flags.json) {
+    renderer.write(renderer.status("info", "`--classic` is deprecated and kept only for backwards compatibility."));
+  }
+
   if (isInteractiveLauncherMode({ command, flags, stdout, stdin })) {
     try {
       await runInteractiveSession({

package/packages/cli/src/command-registry.js

@@ -0,0 +1,108 @@
+const CLI_COMMANDS = [
+  {
+    value: "install",
+    label: "Install",
+    description: "Install portable skills into the current project.",
+    bestFor: "First-time setup and skill refresh",
+    aliases: ["setup", "init", "apply"],
+    usage: "npx skilly-hand install"
+  },
+  {
+    value: "native-setup",
+    label: "Native Setup",
+    description: "Sync native assistant adapters and instruction files.",
+    bestFor: "After install or when assistant targets change",
+    aliases: ["native", "adapters"],
+    usage: "npx skilly-hand native setup"
+  },
+  {
+    value: "detect",
+    label: "Detect",
+    description: "Scan project technologies and show detected signals.",
+    bestFor: "Preview auto-detection before installation",
+    aliases: ["scan", "inspect"],
+    usage: "npx skilly-hand detect"
+  },
+  {
+    value: "list",
+    label: "List",
+    description: "List all skills available in the catalog.",
+    bestFor: "Browse skills and tags",
+    aliases: ["catalog", "skills"],
+    usage: "npx skilly-hand list"
+  },
+  {
+    value: "doctor",
+    label: "Doctor",
+    description: "Diagnose install health, probes, and native coverage.",
+    bestFor: "Troubleshooting and pre-release checks",
+    aliases: ["health", "check"],
+    usage: "npx skilly-hand doctor"
+  },
+  {
+    value: "uninstall",
+    label: "Uninstall",
+    description: "Remove managed skilly-hand installation files.",
+    bestFor: "Restore project to pre-install state",
+    aliases: ["remove", "cleanup"],
+    usage: "npx skilly-hand uninstall"
+  }
+];
+
+const INTERACTIVE_ONLY_COMMANDS = [
+  {
+    value: "command-guide",
+    label: "Command Guide",
+    description: "Show command explanations, aliases, and examples.",
+    bestFor: "Learning what to run",
+    aliases: ["help", "guide"],
+    usage: "npx skilly-hand --help"
+  },
+  {
+    value: "exit",
+    label: "Exit",
+    description: "Close the guided launcher.",
+    bestFor: "Leave interactive mode",
+    aliases: ["quit"],
+    usage: "npx skilly-hand"
+  }
+];
+
+function normalizeText(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+function buildSearchText(command) {
+  return [
+    command.value,
+    command.label,
+    command.description,
+    command.bestFor,
+    ...(command.aliases || [])
+  ]
+    .map(normalizeText)
+    .join(" ");
+}
+
+export function getCliCommands() {
+  return CLI_COMMANDS.map((command) => ({ ...command, aliases: [...command.aliases] }));
+}
+
+export function getInteractiveCommands() {
+  const merged = [...CLI_COMMANDS, ...INTERACTIVE_ONLY_COMMANDS];
+  return merged.map((command) => ({ ...command, aliases: [...command.aliases] }));
+}
+
+export function filterCommands(commands, term) {
+  const normalizedTerm = normalizeText(term);
+  if (!normalizedTerm) return [...commands];
+  return commands.filter((command) => buildSearchText(command).includes(normalizedTerm));
+}
+
+export function formatHelpUsageLines() {
+  return [
+    "npx skilly-hand                  # interactive launcher when running in a TTY",
+    ...CLI_COMMANDS.map((command) => command.usage)
+  ];
+}
+

package/packages/cli/src/inquirer-ui.js

@@ -0,0 +1,201 @@
+import inquirer from "inquirer";
+import { filterCommands, getInteractiveCommands } from "./command-registry.js";
+
+function writeBlock(write, title, body) {
+  const lines = [];
+  if (title) {
+    lines.push(`\n${title}`);
+    lines.push("=".repeat(Math.max(12, title.length)));
+  }
+  if (body) {
+    lines.push(String(body).trimEnd());
+  }
+  lines.push("");
+  write(`${lines.join("\n")}\n`);
+}
+
+function formatSkillChoiceLabel(skill) {
+  const tags = (skill.tags || []).join(", ") || "none";
+  const agents = (skill.agentSupport || []).join(", ") || "none";
+  return `${skill.id} | ${skill.title} | tags: ${tags} | agents: ${agents}`;
+}
+
+function toCheckboxChoices(items, valueKey, labelFn) {
+  return items.map((item) => ({
+    name: labelFn(item),
+    value: item[valueKey],
+    checked: Boolean(item.checked)
+  }));
+}
+
+function commandChoiceName(command) {
+  return `${command.label} - ${command.description}`;
+}
+
+function buildCommandGuide(commands) {
+  const rows = commands.filter((command) => command.value !== "exit").map((command) => {
+    const aliases = (command.aliases || []).join(", ") || "none";
+    return [
+      `${command.label} (${command.value})`,
+      `Best for: ${command.bestFor}`,
+      `Aliases: ${aliases}`,
+      `Run: ${command.usage}`
+    ].join("\n");
+  });
+  return rows.join("\n\n");
+}
+
+function buildGuidedHomeIntro() {
+  return [
+    "Type to filter commands, then press Enter to run.",
+    "Tips: arrow keys to navigate, Esc to clear search, Ctrl+C to exit."
+  ].join("\n");
+}
+
+function installTipsBlock() {
+  return [
+    "Recommended skills are preselected using stack detection.",
+    "Use space to toggle, a to toggle all, i to invert selection."
+  ].join("\n");
+}
+
+function agentTipsBlock() {
+  return [
+    "Pick assistant targets that should receive installed skills.",
+    "Use space to toggle and Enter to continue."
+  ].join("\n");
+}
+
+const COMMAND_HINTS = {
+  "native-setup": "Tip: run `npx skilly-hand doctor` next to verify native coverage.",
+  detect: "Tip: run `npx skilly-hand install` to apply detected recommendations.",
+  list: "Tip: use `npx skilly-hand install --include <tag>` to narrow installation.",
+  doctor: "Tip: resolve any warnings, then rerun doctor before release.",
+  uninstall: "Tip: run `npx skilly-hand install` anytime to restore managed files."
+};
+
+export function createInquirerInteractiveUi({
+  prompt = (questions) => inquirer.prompt(questions),
+  write = (value) => process.stdout.write(value)
+} = {}) {
+  async function confirm({ message, defaultValue = false }) {
+    try {
+      const response = await prompt([
+        {
+          type: "confirm",
+          name: "confirmed",
+          message: String(message),
+          default: defaultValue
+        }
+      ]);
+      return Boolean(response.confirmed);
+    } catch (error) {
+      if (error?.name === "ExitPromptError") return false;
+      throw error;
+    }
+  }
+
+  async function launch({ appVersion, actions, commands = getInteractiveCommands() }) {
+    const header = appVersion ? `skilly-hand v${appVersion}` : "skilly-hand";
+    writeBlock(write, "Guided Home", buildGuidedHomeIntro());
+
+    while (true) {
+      const { command } = await prompt([
+        {
+          type: "search",
+          name: "command",
+          message: `${header}: choose a command`,
+          source: async (term) =>
+            filterCommands(commands, term).map((item) => ({
+              name: commandChoiceName(item),
+              value: item.value,
+              description: `${item.bestFor} | aliases: ${(item.aliases || []).join(", ") || "none"}`
+            })),
+          default: "install",
+          pageSize: 10
+        }
+      ]);
+
+      if (command === "exit") return;
+      if (command === "command-guide") {
+        writeBlock(write, "Command Guide", buildCommandGuide(commands));
+        continue;
+      }
+
+      if (command === "install") {
+        const context = await actions.prepareInstall();
+        const skillChoices = toCheckboxChoices(context.skills || [], "id", formatSkillChoiceLabel);
+        const agentChoices = toCheckboxChoices(context.agents || [], "value", (agent) => agent.value);
+
+        writeBlock(write, "Install Tips", installTipsBlock());
+
+        const { selectedSkillIds } = await prompt([
+          {
+            type: "checkbox",
+            name: "selectedSkillIds",
+            message: "Select skills to install",
+            choices: skillChoices,
+            pageSize: 16
+          }
+        ]);
+
+        writeBlock(write, "Assistant Target Tips", agentTipsBlock());
+
+        const { selectedAgents } = await prompt([
+          {
+            type: "checkbox",
+            name: "selectedAgents",
+            message: "Select assistant targets",
+            choices: agentChoices,
+            pageSize: 12
+          }
+        ]);
+
+        const previewBundle = await actions.previewInstallBundle({
+          selectedSkillIds,
+          selectedAgents
+        });
+        writeBlock(write, "Install Preview", previewBundle?.text || "");
+
+        const { installDecision } = await prompt([
+          {
+            type: "list",
+            name: "installDecision",
+            message: "Next action",
+            choices: [
+              { name: "Apply installation", value: "apply" },
+              { name: "Back to command menu", value: "menu" }
+            ]
+          }
+        ]);
+
+        if (installDecision === "apply") {
+          const applyBundle = await actions.applyInstallBundle({
+            selectedSkillIds,
+            selectedAgents
+          });
+          writeBlock(write, "Install Result", applyBundle?.text || "");
+          writeBlock(write, "Next Hint", "Run `npx skilly-hand doctor` to verify installation health.");
+        }
+        continue;
+      }
+
+      if (command === "uninstall") {
+        const accepted = await confirm({
+          message: "Remove the skilly-hand installation from this project?",
+          defaultValue: false
+        });
+        if (!accepted) {
+          writeBlock(write, "Uninstall", "Uninstall cancelled.");
+          continue;
+        }
+      }
+
+      const bundle = await actions.runCommandBundle(command);
+      writeBlock(write, "Command Result", bundle?.text || "");
+      if (COMMAND_HINTS[command]) writeBlock(write, "Next Hint", COMMAND_HINTS[command]);
+    }
+  }
+
+  return { launch, confirm };
+}

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "private": true,
   "type": "module"
 }

package/packages/detectors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/detectors",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "private": true,
   "type": "module"
 }