@skilly-hand/skilly-hand 0.21.0 → 0.22.0

package/packages/cli/src/bin.js

@@ -9,11 +9,22 @@ import {
   installProject,
   resolveSkillSelection,
   runDoctor,
+  setupNativeProject,
   uninstallProject
 } 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 {
+  createResultDoc,
+  kvBlock,
+  listBlock,
+  renderResultDocText,
+  section,
+  statusBlock,
+  tableBlock,
+  textBlock
+} from "./result-doc.js";
 
 const require = createRequire(import.meta.url);
 const { version } = require("../../../package.json");
@@ -75,13 +86,14 @@ export function parseArgs(argv) {
     else throw new Error(`Unknown flag: ${token}`);
   }
 
-  return { command: positional[0], flags };
+  return { command: positional[0], subcommand: positional[1], flags };
 }
 
 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",
@@ -104,6 +116,7 @@ function buildHelpText(renderer, appVersion) {
   const examples = renderer.section("Examples", renderer.list([
     "npx skilly-hand",
     "npx skilly-hand install --dry-run",
+    "npx skilly-hand native setup --agent codex",
     "npx skilly-hand detect --json",
     "npx skilly-hand install --agent antigravity --agent windsurf",
     "npx skilly-hand uninstall --yes"
@@ -117,151 +130,216 @@ function buildHelpText(renderer, appVersion) {
   ]);
 }
 
-function buildInstallResultBlock(renderer, appVersion, result, flags) {
+function buildInstallResultDoc(result, flags, detectionGridText = "") {
   const mode = flags.dryRun ? "dry-run" : "apply";
-  const preflight = renderer.section(
-    "Install Preflight",
-    renderer.kv([
-      ["Project", result.plan.cwd],
-      ["Install root", result.plan.installRoot],
-      ["Agents", result.plan.agents.join(", ") || "none"],
-      ["Include tags", flags.include.join(", ") || "none"],
-      ["Exclude tags", flags.exclude.join(", ") || "none"],
-      ["Mode", mode]
+  return createResultDoc("Install", [
+    section("Install Preflight", [
+      kvBlock([
+        ["Project", result.plan.cwd],
+        ["Install root", result.plan.installRoot],
+        ["Agents", result.plan.agents.join(", ") || "none"],
+        ["Include tags", flags.include.join(", ") || "none"],
+        ["Exclude tags", flags.exclude.join(", ") || "none"],
+        ["Mode", mode]
+      ])
+    ]),
+    section("Detected Technologies", [
+      result.plan.detections.length > 0
+        ? textBlock(detectionGridText)
+        : statusBlock("warn", "No technology signals were detected.", "Only core skills will be selected.")
+    ]),
+    section("Skill Plan", [
+      result.plan.skills.length > 0
+        ? tableBlock(
+            [
+              { key: "id", header: "Skill ID" },
+              { key: "title", header: "Title" },
+              { key: "tags", header: "Tags" }
+            ],
+            result.plan.skills.map((skill) => ({
+              id: skill.id,
+              title: skill.title,
+              tags: skill.tags.join(", ")
+            }))
+          )
+        : statusBlock("warn", "No skills selected.")
+    ]),
+    section("Status", [
+      result.applied
+        ? statusBlock("success", "Installation completed.", "Managed files and symlinks are in place.")
+        : statusBlock("info", "Dry run complete.", "No files were written.")
+    ]),
+    section("Next Steps", [
+      listBlock(
+        result.applied
+          ? [
+              "Review generated AGENTS and assistant instruction files.",
+              "Run `npx skilly-hand native setup` to scaffold native instruction/rule adapters.",
+              "Run `npx skilly-hand doctor` to validate installation health.",
+              "Use `npx skilly-hand uninstall` to restore backed-up files if needed."
+            ]
+          : [
+              "Run `npx skilly-hand install` to apply this plan.",
+              "Adjust `--include` and `--exclude` tags to tune skill selection."
+            ]
+      )
     ])
-  );
+  ]);
+}
 
-  const detections = renderer.section(
-    "Detected Technologies",
-    result.plan.detections.length > 0
-      ? renderer.detectionGrid(result.plan.detections)
-      : renderer.status("warn", "No technology signals were detected.", "Only core skills will be selected.")
-  );
+function buildNativeSetupResultDoc(result, flags) {
+  const mode = flags.dryRun ? "dry-run" : "apply";
+  return createResultDoc("Native Setup", [
+    section("Native Setup Preflight", [
+      kvBlock([
+        ["Project", result.plan.cwd],
+        ["Install root", result.plan.installRoot],
+        ["Agents", result.plan.agents.join(", ") || "none"],
+        ["Mode", mode]
+      ])
+    ]),
+    section("Native Coverage", [
+      tableBlock(
+        [
+          { key: "agent", header: "Agent" },
+          { key: "status", header: "Status" },
+          { key: "target", header: "Target" },
+          { key: "remediation", header: "Remediation" }
+        ],
+        (result.nativeStatus || result.plan.nativeStatus || []).map((row) => ({
+          agent: row.agent,
+          status: row.status,
+          target: row.target || "-",
+          remediation: row.remediation
+        }))
+      )
+    ]),
+    section("Status", [
+      result.applied
+        ? statusBlock("success", "Native setup completed.", "Native rule/instruction files are synchronized.")
+        : statusBlock("info", "Native setup dry run complete.", "No files were written.")
+    ]),
+    section("Next Steps", [
+      listBlock(
+        result.applied
+          ? [
+              "Run `npx skilly-hand doctor` to verify native coverage.",
+              "Re-run `npx skilly-hand native setup` after changing agent targets."
+            ]
+          : [
+              "Run `npx skilly-hand native setup` to apply these native adapter changes."
+            ]
+      )
+    ])
+  ]);
+}
 
-  const skills = renderer.section(
-    "Skill Plan",
-    result.plan.skills.length > 0
-      ? renderer.table(
-          [
-            { key: "id", header: "Skill ID" },
-            { key: "title", header: "Title" },
-            { key: "tags", header: "Tags" }
-          ],
-          result.plan.skills.map((skill) => ({
-            id: skill.id,
-            title: skill.title,
-            tags: skill.tags.join(", ")
-          }))
-        )
-      : renderer.status("warn", "No skills selected.")
-  );
+function renderResultDoc(renderer, appVersion, doc, options = {}) {
+  return renderResultDocText(renderer, appVersion, doc, options);
+}
 
-  const status = result.applied
-    ? renderer.status("success", "Installation completed.", "Managed files and symlinks are in place.")
-    : renderer.status("info", "Dry run complete.", "No files were written.");
+function buildInstallResultBlock(renderer, appVersion, result, flags, options = {}) {
+  const doc = buildInstallResultDoc(result, flags, renderer.detectionGrid(result.plan.detections));
+  return renderResultDoc(renderer, appVersion, doc, options);
+}
 
-  const nextSteps = result.applied
-    ? renderer.nextSteps([
-        "Review generated AGENTS and assistant instruction files.",
-        "Run `npx skilly-hand doctor` to validate installation health.",
-        "Use `npx skilly-hand uninstall` to restore backed-up files if needed."
-      ])
-    : renderer.nextSteps([
-        "Run `npx skilly-hand install` to apply this plan.",
-        "Adjust `--include` and `--exclude` tags to tune skill selection."
-      ]);
+function buildNativeSetupResultBlock(renderer, appVersion, result, flags, options = {}) {
+  return renderResultDoc(renderer, appVersion, buildNativeSetupResultDoc(result, flags), options);
+}
 
-  return renderer.joinBlocks([renderer.banner(appVersion), preflight, detections, skills, status, nextSteps]);
+function printNativeSetupResult(renderer, appVersion, result, flags) {
+  renderer.write(buildNativeSetupResultBlock(renderer, appVersion, result, flags, { includeBanner: true }));
 }
 
 function printInstallResult(renderer, appVersion, result, flags) {
-  renderer.write(buildInstallResultBlock(renderer, appVersion, result, flags));
+  renderer.write(buildInstallResultBlock(renderer, appVersion, result, flags, { includeBanner: true }));
 }
 
-function buildDetectResultBlock(renderer, cwd, detections) {
-  const summary = renderer.section(
-    "Detection Summary",
-    renderer.kv([
-      ["Project", cwd],
-      ["Signals found", String(detections.length)]
+function buildDetectResultDoc(cwd, detections, detectionGridText = "") {
+  return createResultDoc("Detect", [
+    section("Detection Summary", [
+      kvBlock([
+        ["Project", cwd],
+        ["Signals found", String(detections.length)]
+      ])
+    ]),
+    section("Findings", [
+      detections.length > 0
+        ? textBlock(detectionGridText)
+        : statusBlock("warn", "No technology signals were detected.", "Only core skills will be selected.")
     ])
-  );
-
-  const findings = renderer.section(
-    "Findings",
-    detections.length > 0
-      ? renderer.detectionGrid(detections)
-      : renderer.status("warn", "No technology signals were detected.", "Only core skills will be selected.")
-  );
+  ]);
+}
 
-  return renderer.joinBlocks([summary, findings]);
+function buildDetectResultBlock(renderer, cwd, detections) {
+  const doc = buildDetectResultDoc(cwd, detections, renderer.detectionGrid(detections));
+  return renderResultDoc(renderer, "", doc, { includeBanner: false });
 }
 
 function printDetectResult(renderer, cwd, detections) {
   renderer.write(buildDetectResultBlock(renderer, cwd, detections));
 }
 
-function buildListResultBlock(renderer, skills) {
-  const summary = renderer.section(
-    "Catalog Summary",
-    renderer.kv([["Skills available", String(skills.length)]])
-  );
-
-  const table = renderer.section(
-    "Skills",
-    renderer.table(
-      [
-        { key: "id", header: "Skill ID" },
-        { key: "title", header: "Title" },
-        { key: "tags", header: "Tags" },
-        { key: "agents", header: "Agents" }
-      ],
-      skills.map((skill) => ({
-        id: skill.id,
-        title: skill.title,
-        tags: skill.tags.join(", "),
-        agents: skill.agentSupport.join(", ")
-      }))
-    )
-  );
+function buildListResultDoc(skills) {
+  return createResultDoc("List", [
+    section("Catalog Summary", [kvBlock([["Skills available", String(skills.length)]])]),
+    section("Skills", [
+      tableBlock(
+        [
+          { key: "id", header: "Skill ID" },
+          { key: "title", header: "Title" },
+          { key: "tags", header: "Tags" },
+          { key: "agents", header: "Agents" }
+        ],
+        skills.map((skill) => ({
+          id: skill.id,
+          title: skill.title,
+          tags: skill.tags.join(", "),
+          agents: skill.agentSupport.join(", ")
+        }))
+      )
+    ])
+  ]);
+}
 
-  return renderer.joinBlocks([summary, table]);
+function buildListResultBlock(renderer, skills) {
+  return renderResultDoc(renderer, "", buildListResultDoc(skills), { includeBanner: false });
 }
 
 function printListResult(renderer, skills) {
   renderer.write(buildListResultBlock(renderer, skills));
 }
 
-function buildDoctorResultBlock(renderer, result) {
-  const badge = renderer.healthBadge(result.installed);
-
-  const summary = renderer.section(
-    "Doctor Summary",
-    renderer.kv([
-      ["Project", result.cwd],
-      ["Installed", result.installed ? "yes" : "no"],
-      ["Catalog issues", String(result.catalogIssues.length)]
+function buildDoctorResultDoc(result, healthBadgeText = "") {
+  const sections = [
+    section("Health", [textBlock(healthBadgeText)]),
+    section("Doctor Summary", [
+      kvBlock([
+        ["Project", result.cwd],
+        ["Installed", result.installed ? "yes" : "no"],
+        ["Catalog issues", String(result.catalogIssues.length)]
+      ])
     ])
-  );
-
-  const lock = result.lock
-    ? renderer.section(
-        "Lock Metadata",
-        renderer.kv([
-          ["Generated at", result.lock.generatedAt],
-          ["Agents", result.lock.agents.join(", ")],
-          ["Skills", result.lock.skills.join(", ")]
-        ])
-      )
-    : "";
+  ];
+
+  if (result.lock) {
+    sections.push(section("Lock Metadata", [
+      kvBlock([
+        ["Generated at", result.lock.generatedAt],
+        ["Agents", result.lock.agents.join(", ")],
+        ["Skills", result.lock.skills.join(", ")]
+      ])
+    ]));
+  }
 
-  const issues = result.catalogIssues.length
-    ? renderer.section("Catalog Issues", renderer.list(result.catalogIssues))
-    : renderer.section("Catalog Issues", renderer.status("success", "No catalog issues found."));
+  sections.push(section("Catalog Issues", [
+    result.catalogIssues.length
+      ? listBlock(result.catalogIssues)
+      : statusBlock("success", "No catalog issues found.")
+  ]));
 
-  const probes = renderer.section(
-    "Project Probes",
-    renderer.table(
+  sections.push(section("Project Probes", [
+    tableBlock(
       [
         { key: "path", header: "Path" },
         { key: "exists", header: "Exists" },
@@ -273,32 +351,60 @@ function buildDoctorResultBlock(renderer, result) {
         type: item.type || "-"
       }))
     )
-  );
+  ]));
 
-  return renderer.joinBlocks([badge, summary, lock, issues, probes]);
+  sections.push(section("Native Coverage", [
+    tableBlock(
+      [
+        { key: "agent", header: "Agent" },
+        { key: "status", header: "Status" },
+        { key: "target", header: "Target" },
+        { key: "remediation", header: "Remediation" }
+      ],
+      (result.nativeStatus || []).map((row) => ({
+        agent: row.agent,
+        status: row.status,
+        target: row.target || "-",
+        remediation: row.remediation
+      }))
+    )
+  ]));
+
+  return createResultDoc("Doctor", sections);
+}
+
+function buildDoctorResultBlock(renderer, result) {
+  const doc = buildDoctorResultDoc(result, renderer.healthBadge(result.installed));
+  return renderResultDoc(renderer, "", doc, { includeBanner: false });
 }
 
 function printDoctorResult(renderer, result) {
   renderer.write(buildDoctorResultBlock(renderer, result));
 }
 
-function buildUninstallResultBlock(renderer, result) {
+function buildUninstallResultDoc(result) {
   if (result.removed) {
-    return renderer.joinBlocks([
-      renderer.status("success", "skilly-hand installation removed."),
-      renderer.nextSteps([
-        "Run `npx skilly-hand install` if you want to reinstall managed files.",
-        "Run `npx skilly-hand doctor` to confirm the project state."
+    return createResultDoc("Uninstall", [
+      section("Status", [statusBlock("success", "skilly-hand installation removed.")]),
+      section("Next Steps", [
+        listBlock([
+          "Run `npx skilly-hand install` if you want to reinstall managed files.",
+          "Run `npx skilly-hand doctor` to confirm the project state."
+        ])
       ])
     ]);
   }
 
-  return renderer.joinBlocks([
-    renderer.status("warn", "Nothing to uninstall.", result.reason),
-    renderer.nextSteps(["Run `npx skilly-hand install` to create a managed installation first."])
+  return createResultDoc("Uninstall", [
+    section("Status", [statusBlock("warn", "Nothing to uninstall.", result.reason)]),
+    section("Next Steps", [listBlock(["Run `npx skilly-hand install` to create a managed installation first."])])
   ]);
 }
 
+function buildUninstallResultBlock(renderer, result) {
+  return renderResultDoc(renderer, "", buildUninstallResultDoc(result), { includeBanner: false });
+}
+
 function printUninstallResult(renderer, result) {
   renderer.write(buildUninstallResultBlock(renderer, result));
 }
@@ -307,6 +413,9 @@ export function buildErrorHint(message) {
   if (message.startsWith("Unknown command:")) {
     return "Run `npx skilly-hand --help` to see available commands.";
   }
+  if (message.startsWith("Unknown native subcommand:")) {
+    return "Use `npx skilly-hand native setup`.";
+  }
   if (message.startsWith("Unknown flag:") || message.startsWith("Missing value")) {
     return "Check command flags with `npx skilly-hand --help`.";
   }
@@ -319,6 +428,7 @@ function createServices(overrides = {}) {
     installProject,
     resolveSkillSelection,
     runDoctor,
+    setupNativeProject,
     uninstallProject,
     detectProject,
     defaultAgents: DEFAULT_AGENTS,
@@ -367,53 +477,113 @@ async function runInteractiveSession({
   await interactiveUi.launch({
     appVersion,
     actions: {
-      async runCommand(command) {
+      async runCommandBundle(command) {
+        if (command === "native-setup") {
+          const result = await services.setupNativeProject({ cwd, dryRun: false });
+          const doc = buildNativeSetupResultDoc(result, { dryRun: false });
+          return {
+            doc,
+            text: renderResultDoc(renderer, appVersion, doc, { includeBanner: false })
+          };
+        }
         if (command === "detect") {
           const detections = await services.detectProject(cwd);
-          return buildDetectResultBlock(renderer, cwd, detections);
+          const doc = buildDetectResultDoc(cwd, detections, renderer.detectionGrid(detections));
+          return {
+            doc,
+            text: renderResultDoc(renderer, "", doc, { includeBanner: false })
+          };
         }
         if (command === "list") {
           const skills = await services.loadAllSkills();
-          return buildListResultBlock(renderer, skills);
+          const doc = buildListResultDoc(skills);
+          return {
+            doc,
+            text: renderResultDoc(renderer, "", doc, { includeBanner: false })
+          };
         }
         if (command === "doctor") {
           const result = await services.runDoctor(cwd);
-          return buildDoctorResultBlock(renderer, result);
+          const doc = buildDoctorResultDoc(result, renderer.healthBadge(result.installed));
+          return {
+            doc,
+            text: renderResultDoc(renderer, "", doc, { includeBanner: false })
+          };
         }
         if (command === "uninstall") {
           const result = await services.uninstallProject(cwd);
-          return buildUninstallResultBlock(renderer, result);
+          const doc = buildUninstallResultDoc(result);
+          return {
+            doc,
+            text: renderResultDoc(renderer, "", doc, { includeBanner: false })
+          };
         }
-        return renderer.status("warn", `Unknown command: ${command}`);
+        const doc = createResultDoc("Result", [section("Status", [statusBlock("warn", `Unknown command: ${command}`)])]);
+        return {
+          doc,
+          text: renderResultDoc(renderer, "", doc, { includeBanner: false })
+        };
+      },
+      async runCommandDoc(command) {
+        const bundle = await this.runCommandBundle(command);
+        return bundle.doc;
+      },
+      async runCommand(command) {
+        const bundle = await this.runCommandBundle(command);
+        return bundle.text;
       },
       async prepareInstall() {
         return getInteractiveInstallContext({ cwd, services });
       },
-      async previewInstall({ selectedSkillIds, selectedAgents }) {
+      async previewInstallBundle({ selectedSkillIds, selectedAgents }) {
         const preview = await services.installProject({
           cwd,
           agents: selectedAgents,
           dryRun: true,
           selectedSkillIds
         });
-        return buildInstallResultBlock(renderer, appVersion, preview, {
+        const doc = buildInstallResultDoc(preview, {
           dryRun: true,
           include: [],
           exclude: []
-        });
+        }, renderer.detectionGrid(preview.plan.detections));
+        return {
+          doc,
+          text: renderResultDoc(renderer, appVersion, doc, { includeBanner: false })
+        };
       },
-      async applyInstall({ selectedSkillIds, selectedAgents }) {
+      async previewInstall({ selectedSkillIds, selectedAgents }) {
+        const bundle = await this.previewInstallBundle({ selectedSkillIds, selectedAgents });
+        return bundle.text;
+      },
+      async previewInstallDoc({ selectedSkillIds, selectedAgents }) {
+        const bundle = await this.previewInstallBundle({ selectedSkillIds, selectedAgents });
+        return bundle.doc;
+      },
+      async applyInstallBundle({ selectedSkillIds, selectedAgents }) {
         const applied = await services.installProject({
           cwd,
           agents: selectedAgents,
           dryRun: false,
           selectedSkillIds
         });
-        return buildInstallResultBlock(renderer, appVersion, applied, {
+        const doc = buildInstallResultDoc(applied, {
           dryRun: false,
           include: [],
           exclude: []
-        });
+        }, renderer.detectionGrid(applied.plan.detections));
+        return {
+          doc,
+          text: renderResultDoc(renderer, appVersion, doc, { includeBanner: false })
+        };
+      },
+      async applyInstall({ selectedSkillIds, selectedAgents }) {
+        const bundle = await this.applyInstallBundle({ selectedSkillIds, selectedAgents });
+        return bundle.text;
+      },
+      async applyInstallDoc({ selectedSkillIds, selectedAgents }) {
+        const bundle = await this.applyInstallBundle({ selectedSkillIds, selectedAgents });
+        return bundle.doc;
       }
     }
   });
@@ -421,6 +591,7 @@ async function runInteractiveSession({
 
 async function runCommand({
   command,
+  subcommand,
   flags,
   cwd,
   stdin,
@@ -530,6 +701,32 @@ async function runCommand({
     return;
   }
 
+  if (command === "native") {
+    if (subcommand && subcommand !== "setup") {
+      throw new Error(`Unknown native subcommand: ${subcommand}`);
+    }
+
+    const result = await services.setupNativeProject({
+      cwd,
+      agents: flags.agents,
+      dryRun: flags.dryRun
+    });
+
+    if (flags.json) {
+      renderer.writeJson({
+        command: "native setup",
+        applied: result.applied,
+        plan: result.plan,
+        nativeStatus: result.nativeStatus || result.plan.nativeStatus || [],
+        lockPath: result.lockPath || null
+      });
+      return;
+    }
+
+    printNativeSetupResult(renderer, appVersion, result, flags);
+    return;
+  }
+
   throw new Error(`Unknown command: ${command}`);
 }
 
@@ -550,7 +747,7 @@ export async function runCli({
 } = {}) {
   const renderer = createTerminalRenderer({ stdout, stderr, env, platform });
   const services = createServices(providedServices);
-  const { command, flags } = parseArgs(argv);
+  const { command, subcommand, flags } = parseArgs(argv);
 
   if (flags.help) {
     if (flags.json) {
@@ -560,6 +757,7 @@ export async function runCli({
         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",
@@ -597,6 +795,7 @@ export async function runCli({
   const effectiveCommand = command || "install";
   await runCommand({
     command: effectiveCommand,
+    subcommand,
     flags,
     cwd,
     stdin,