@skilly-hand/skilly-hand 0.1.1 → 0.2.0

package/README.md

@@ -58,7 +58,8 @@ npx skilly-hand
 4. Run publish gate: `npm run verify:publish`.
 5. Inspect package payload: `npm pack --dry-run --json`.
 6. Bump version intentionally: `npm version patch|minor|major` (this auto-rotates `CHANGELOG.md`, creates a dated release section, and inserts a version-specific npm link).
-7. Publish the root package: `npm publish` (or `npm publish --tag next` for prereleases).
+7. Publish with assisted 2FA flow: `npm run publish:otp` (or `npm run publish:next` for prereleases).
+   - The script runs the publish gate, asks for OTP with hidden input, and if left blank lets npm trigger your default security method.
 8. Smoke test after publish: `npx @skilly-hand/skilly-hand@<version> --help`.
 9. Verify npm metadata (README render, changelog, license, executable bin).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {
@@ -30,6 +30,9 @@
     "test": "node --test tests/*.test.js",
     "verify:packlist": "node ./scripts/verify-packlist.mjs",
     "verify:publish": "npm run catalog:check && npm test && 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",
     "prepublishOnly": "npm run verify:publish",
     "version": "node ./scripts/release-changelog.mjs",
     "changelog:release": "node ./scripts/release-changelog.mjs",

package/packages/cli/src/bin.js

@@ -2,8 +2,11 @@
 import path from "node:path";
 import { loadAllSkills } from "../../catalog/src/index.js";
 import { installProject, runDoctor, uninstallProject } from "../../core/src/index.js";
+import { createTerminalRenderer } from "../../core/src/terminal.js";
 import { detectProject } from "../../detectors/src/index.js";
 
+const renderer = createTerminalRenderer();
+
 function parseArgs(argv) {
   const args = [...argv];
   const positional = [];
@@ -11,11 +14,20 @@ function parseArgs(argv) {
     dryRun: false,
     yes: false,
     verbose: false,
+    json: false,
     agents: [],
     include: [],
     exclude: []
   };
 
+  function takeFlagValue(flagName) {
+    const value = args.shift();
+    if (!value || value.startsWith("-")) {
+      throw new Error(`Missing value for ${flagName}`);
+    }
+    return value;
+  }
+
   while (args.length > 0) {
     const token = args.shift();
     if (!token.startsWith("-")) {
@@ -26,10 +38,11 @@ function parseArgs(argv) {
     if (token === "--dry-run") flags.dryRun = true;
     else if (token === "--yes" || token === "-y") flags.yes = true;
     else if (token === "--verbose" || token === "-v") flags.verbose = true;
-    else if (token === "--agent" || token === "-a") flags.agents.push(args.shift());
-    else if (token === "--cwd") flags.cwd = args.shift();
-    else if (token === "--include") flags.include.push(args.shift());
-    else if (token === "--exclude") flags.exclude.push(args.shift());
+    else if (token === "--json") flags.json = true;
+    else if (token === "--agent" || token === "-a") flags.agents.push(takeFlagValue(token));
+    else if (token === "--cwd") flags.cwd = takeFlagValue(token);
+    else if (token === "--include") flags.include.push(takeFlagValue(token));
+    else if (token === "--exclude") flags.exclude.push(takeFlagValue(token));
     else if (token === "--help" || token === "-h") flags.help = true;
     else throw new Error(`Unknown flag: ${token}`);
   }
@@ -37,57 +50,251 @@ function parseArgs(argv) {
   return { command: positional[0], flags };
 }
 
-function printHelp() {
-  console.log(`skilly-hand
-
-Usage:
-  npx skilly-hand [install]
-  npx skilly-hand detect
-  npx skilly-hand list
-  npx skilly-hand doctor
-  npx skilly-hand uninstall
-
-Flags:
-  --dry-run
-  --yes
-  --verbose
-  --agent <codex|claude|cursor|gemini|copilot>
-  --cwd <path>
-  --include <tag>
-  --exclude <tag>
-`);
+function buildHelpText() {
+  const usage = renderer.section("Usage", renderer.list([
+    "npx skilly-hand [install]",
+    "npx skilly-hand detect",
+    "npx skilly-hand list",
+    "npx skilly-hand doctor",
+    "npx skilly-hand uninstall"
+  ], { bullet: "-" }));
+
+  const flags = renderer.section("Flags", renderer.list([
+    "--dry-run                     Show install plan without writing files",
+    "--json                        Emit stable JSON output for automation",
+    "--yes, -y                     Reserved for future non-interactive confirmations",
+    "--verbose, -v                 Reserved for future debug detail",
+    "--agent, -a <name>            codex|claude|cursor|gemini|copilot (repeatable)",
+    "--cwd <path>                  Project root (defaults to current directory)",
+    "--include <tag>               Include only skills matching all tags",
+    "--exclude <tag>               Exclude skills matching any tag",
+    "--help, -h                    Show help"
+  ], { bullet: "-" }));
+
+  const examples = renderer.section("Examples", renderer.list([
+    "npx skilly-hand install --dry-run",
+    "npx skilly-hand detect --json",
+    "npx skilly-hand install --agent codex --agent claude",
+    "npx skilly-hand list --include workflow"
+  ], { bullet: "-" }));
+
+  return renderer.joinBlocks([
+    renderer.status("info", "skilly-hand", "Portable AI skill orchestration for coding assistants."),
+    usage,
+    flags,
+    examples
+  ]);
+}
+
+function detectionRows(detections) {
+  return detections.map((item) => ({
+    technology: item.technology,
+    confidence: item.confidence.toFixed(2),
+    reasons: item.reasons.join("; "),
+    recommended: item.recommendedSkillIds.join(", ")
+  }));
 }
 
-function printDetections(detections) {
+function renderDetections(detections) {
   if (detections.length === 0) {
-    console.log("No technology signals were detected.");
-    return;
+    return renderer.status("warn", "No technology signals were detected.", "Only core skills will be selected.");
   }
 
-  for (const item of detections) {
-    console.log(`- ${item.technology} (${item.confidence})`);
-    console.log(`  reasons: ${item.reasons.join("; ")}`);
-    console.log(`  recommended skills: ${item.recommendedSkillIds.join(", ")}`);
+  return renderer.table(
+    [
+      { key: "technology", header: "Technology" },
+      { key: "confidence", header: "Confidence" },
+      { key: "reasons", header: "Reasons" },
+      { key: "recommended", header: "Recommended Skills" }
+    ],
+    detectionRows(detections)
+  );
+}
+
+function renderSkillTable(skills) {
+  if (skills.length === 0) {
+    return renderer.status("warn", "No skills selected.");
   }
+
+  return renderer.table(
+    [
+      { key: "id", header: "Skill ID" },
+      { key: "title", header: "Title" },
+      { key: "tags", header: "Tags" }
+    ],
+    skills.map((skill) => ({
+      id: skill.id,
+      title: skill.title,
+      tags: skill.tags.join(", ")
+    }))
+  );
+}
+
+function printInstallResult(result, flags) {
+  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]
+    ])
+  );
+
+  const detections = renderer.section("Detected Technologies", renderDetections(result.plan.detections));
+  const skills = renderer.section("Skill Plan", renderSkillTable(result.plan.skills));
+
+  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.");
+
+  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."
+    ]);
+
+  renderer.write(renderer.joinBlocks([preflight, detections, skills, status, nextSteps]));
+}
+
+function printDetectResult(cwd, detections) {
+  const summary = renderer.section(
+    "Detection Summary",
+    renderer.kv([
+      ["Project", cwd],
+      ["Signals found", String(detections.length)]
+    ])
+  );
+
+  const details = renderer.section("Findings", renderDetections(detections));
+  renderer.write(renderer.joinBlocks([summary, details]));
+}
+
+function printListResult(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(", ")
+      }))
+    )
+  );
+
+  renderer.write(renderer.joinBlocks([summary, table]));
+}
+
+function printDoctorResult(result) {
+  const health = result.installed
+    ? renderer.status("success", "Installation detected.")
+    : renderer.status("warn", "No installation detected.");
+
+  const summary = renderer.section(
+    "Doctor Summary",
+    renderer.kv([
+      ["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(", ")]
+        ])
+      )
+    : "";
+
+  const issues = result.catalogIssues.length
+    ? renderer.section("Catalog Issues", renderer.list(result.catalogIssues))
+    : renderer.section("Catalog Issues", renderer.status("success", "No catalog issues found."));
+
+  const probes = renderer.section(
+    "Project Probes",
+    renderer.table(
+      [
+        { key: "path", header: "Path" },
+        { key: "exists", header: "Exists" },
+        { key: "type", header: "Type" }
+      ],
+      result.fileStatus.map((item) => ({
+        path: item.path,
+        exists: item.exists ? "yes" : "no",
+        type: item.type || "-"
+      }))
+    )
+  );
+
+  renderer.write(renderer.joinBlocks([health, summary, lock, issues, probes]));
 }
 
-function printPlan(plan) {
-  console.log(`Project: ${plan.cwd}`);
-  console.log(`Install root: ${plan.installRoot}`);
-  console.log(`Agents: ${plan.agents.join(", ")}`);
-  console.log("Detected technologies:");
-  printDetections(plan.detections);
-  console.log("Skills to install:");
-  for (const skill of plan.skills) {
-    console.log(`- ${skill.id}: ${skill.title} [${skill.tags.join(", ")}]`);
+function printUninstallResult(result) {
+  if (result.removed) {
+    renderer.write(
+      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;
   }
+
+  renderer.write(
+    renderer.joinBlocks([
+      renderer.status("warn", "Nothing to uninstall.", result.reason),
+      renderer.nextSteps(["Run `npx skilly-hand install` to create a managed installation first."])
+    ])
+  );
 }
 
 async function main() {
   const { command, flags } = parseArgs(process.argv.slice(2));
 
   if (flags.help) {
-    printHelp();
+    if (flags.json) {
+      renderer.writeJson({
+        command: command || "install",
+        help: true,
+        usage: [
+          "npx skilly-hand [install]",
+          "npx skilly-hand detect",
+          "npx skilly-hand list",
+          "npx skilly-hand doctor",
+          "npx skilly-hand uninstall"
+        ]
+      });
+      return;
+    }
+
+    renderer.write(buildHelpText());
     return;
   }
 
@@ -95,29 +302,57 @@ async function main() {
   const effectiveCommand = command || "install";
 
   if (effectiveCommand === "detect") {
-    printDetections(await detectProject(cwd));
+    const detections = await detectProject(cwd);
+    if (flags.json) {
+      renderer.writeJson({
+        command: "detect",
+        cwd,
+        count: detections.length,
+        detections
+      });
+      return;
+    }
+    printDetectResult(cwd, detections);
     return;
   }
 
   if (effectiveCommand === "list") {
     const skills = await loadAllSkills();
-    for (const skill of skills) {
-      console.log(`- ${skill.id}: ${skill.title}`);
-      console.log(`  tags: ${skill.tags.join(", ")}`);
-      console.log(`  agents: ${skill.agentSupport.join(", ")}`);
+    if (flags.json) {
+      renderer.writeJson({
+        command: "list",
+        count: skills.length,
+        skills
+      });
+      return;
     }
+    printListResult(skills);
     return;
   }
 
   if (effectiveCommand === "doctor") {
     const result = await runDoctor(cwd);
-    console.log(JSON.stringify(result, null, 2));
+    if (flags.json) {
+      renderer.writeJson({
+        command: "doctor",
+        ...result
+      });
+      return;
+    }
+    printDoctorResult(result);
     return;
   }
 
   if (effectiveCommand === "uninstall") {
     const result = await uninstallProject(cwd);
-    console.log(result.removed ? "skilly-hand installation removed." : result.reason);
+    if (flags.json) {
+      renderer.writeJson({
+        command: "uninstall",
+        ...result
+      });
+      return;
+    }
+    printUninstallResult(result);
     return;
   }
 
@@ -130,15 +365,53 @@ async function main() {
       excludeTags: flags.exclude
     });
 
-    printPlan(result.plan);
-    console.log(result.applied ? "Installation completed." : "Dry run only; nothing was written.");
+    if (flags.json) {
+      renderer.writeJson({
+        command: "install",
+        applied: result.applied,
+        plan: result.plan,
+        lockPath: result.lockPath || null
+      });
+      return;
+    }
+
+    printInstallResult(result, flags);
     return;
   }
 
   throw new Error(`Unknown command: ${effectiveCommand}`);
 }
 
+const jsonRequested = process.argv.includes("--json");
+
 main().catch((error) => {
-  console.error(error.message);
+  const hint =
+    error.message.startsWith("Unknown command:")
+      ? "Run `npx skilly-hand --help` to see available commands."
+      : error.message.startsWith("Unknown flag:") || error.message.startsWith("Missing value")
+      ? "Check command flags with `npx skilly-hand --help`."
+      : "Retry with `--verbose` for expanded context if needed.";
+
+  if (jsonRequested) {
+    renderer.writeErrorJson({
+      ok: false,
+      error: {
+        what: "skilly-hand command failed",
+        why: error.message,
+        hint
+      }
+    });
+    process.exitCode = 1;
+    return;
+  }
+
+  renderer.writeError(
+    renderer.error({
+      what: "skilly-hand command failed",
+      why: error.message,
+      hint,
+      exitCode: 1
+    })
+  );
   process.exitCode = 1;
 });

package/packages/core/src/terminal.js

@@ -0,0 +1,196 @@
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
+
+function asString(value) {
+  if (value === null || value === undefined) return "";
+  return String(value);
+}
+
+function stripAnsi(value) {
+  return asString(value).replace(ANSI_PATTERN, "");
+}
+
+function padEndAnsi(value, width) {
+  const clean = stripAnsi(value);
+  if (clean.length >= width) return value;
+  return value + " ".repeat(width - clean.length);
+}
+
+function normalizeBooleanEnv(value) {
+  if (value === undefined || value === null) return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (normalized === "" || normalized === "0" || normalized === "false" || normalized === "no") return false;
+  return true;
+}
+
+export function detectColorSupport({ env = process.env, stream = process.stdout } = {}) {
+  const noColor = normalizeBooleanEnv(env.NO_COLOR);
+  if (noColor) return false;
+
+  const forceColor = normalizeBooleanEnv(env.FORCE_COLOR);
+  if (forceColor === true) return true;
+  if (forceColor === false) return false;
+
+  if (!stream?.isTTY) return false;
+  if (env.CI) return false;
+  return true;
+}
+
+export function detectUnicodeSupport({ env = process.env, stream = process.stdout, platform = process.platform } = {}) {
+  if (!stream?.isTTY) return false;
+  if (env.TERM === "dumb") return false;
+  if (env.NO_UNICODE) return false;
+  if (platform === "win32") {
+    return Boolean(env.WT_SESSION || env.TERM_PROGRAM || env.ConEmuTask || env.ANSICON);
+  }
+  return true;
+}
+
+function createStyler(enabled) {
+  if (!enabled) {
+    const passthrough = (value) => asString(value);
+    return {
+      reset: passthrough,
+      bold: passthrough,
+      dim: passthrough,
+      cyan: passthrough,
+      green: passthrough,
+      yellow: passthrough,
+      red: passthrough,
+      magenta: passthrough
+    };
+  }
+
+  const wrap = (code) => (value) => `\u001b[${code}m${asString(value)}\u001b[0m`;
+  return {
+    reset: wrap("0"),
+    bold: wrap("1"),
+    dim: wrap("2"),
+    cyan: wrap("36"),
+    green: wrap("32"),
+    yellow: wrap("33"),
+    red: wrap("31"),
+    magenta: wrap("35")
+  };
+}
+
+function renderKeyValue(entries, style) {
+  if (!entries || entries.length === 0) return "";
+  const normalized = entries.map(([key, value]) => [asString(key), asString(value)]);
+  const width = normalized.reduce((max, [key]) => Math.max(max, key.length), 0);
+  return normalized
+    .map(([key, value]) => `${style.dim(padEndAnsi(key, width))} : ${value}`)
+    .join("\n");
+}
+
+function renderList(items, { bullet }) {
+  if (!items || items.length === 0) return "";
+  return items.map((item) => `${bullet} ${asString(item)}`).join("\n");
+}
+
+function renderTable(columns, rows) {
+  if (!columns || columns.length === 0) return "";
+  const header = columns.map((column) => column.header);
+  const matrix = [header, ...rows.map((row) => columns.map((column) => asString(row[column.key] ?? "")))];
+  const widths = header.map((_, index) =>
+    matrix.reduce((max, line) => Math.max(max, stripAnsi(line[index]).length), 0)
+  );
+
+  const headerLine = header.map((value, index) => padEndAnsi(value, widths[index])).join("  ");
+  const separatorLine = widths.map((width) => "-".repeat(Math.max(3, width))).join("  ");
+  const body = rows.map((row) =>
+    columns.map((column, index) => padEndAnsi(asString(row[column.key] ?? ""), widths[index])).join("  ")
+  );
+
+  return [headerLine, separatorLine, ...body].join("\n");
+}
+
+function joinBlocks(blocks) {
+  const filtered = blocks.map((block) => asString(block).trimEnd()).filter(Boolean);
+  if (filtered.length === 0) return "";
+  return filtered.join("\n\n");
+}
+
+export function createTerminalRenderer({
+  stdout = process.stdout,
+  stderr = process.stderr,
+  env = process.env,
+  platform = process.platform
+} = {}) {
+  const colorEnabled = detectColorSupport({ env, stream: stdout });
+  const unicodeEnabled = detectUnicodeSupport({ env, stream: stdout, platform });
+  const style = createStyler(colorEnabled);
+  const symbols = unicodeEnabled
+    ? { info: "i", success: "✓", warn: "!", error: "x", bullet: "•", section: "■" }
+    : { info: "i", success: "+", warn: "!", error: "x", bullet: "-", section: "#" };
+
+  const statusStyles = {
+    info: style.cyan,
+    success: style.green,
+    warn: style.yellow,
+    error: style.red
+  };
+
+  const renderer = {
+    colorEnabled,
+    unicodeEnabled,
+    symbols,
+    style,
+    json(value) {
+      return JSON.stringify(value, null, 2);
+    },
+    section(title, body = "") {
+      const heading = `${style.cyan(symbols.section)} ${style.bold(asString(title))}`;
+      const bodyText = asString(body).trimEnd();
+      return bodyText ? `${heading}\n${bodyText}` : heading;
+    },
+    kv(entries) {
+      return renderKeyValue(entries, style);
+    },
+    list(items, options = {}) {
+      return renderList(items, { bullet: options.bullet || symbols.bullet });
+    },
+    table(columns, rows) {
+      return renderTable(columns, rows);
+    },
+    status(level, message, detail = "") {
+      const applied = statusStyles[level] || ((value) => value);
+      const icon = symbols[level] || symbols.info;
+      const main = `${applied(icon)} ${asString(message)}`;
+      if (!detail) return main;
+      return `${main}\n${style.dim("  " + asString(detail))}`;
+    },
+    summary(title, items = []) {
+      return renderer.section(title, renderer.list(items));
+    },
+    nextSteps(steps = []) {
+      if (!steps.length) return "";
+      return renderer.section("Next Steps", renderer.list(steps));
+    },
+    error({ what = "Command failed", why = "", hint = "", exitCode = 1 } = {}) {
+      const blocks = [
+        renderer.status("error", what),
+        why ? renderer.kv([["Why", why]]) : "",
+        hint ? renderer.kv([["How to recover", hint]]) : "",
+        renderer.kv([["Exit code", asString(exitCode)]])
+      ];
+      return joinBlocks(blocks);
+    },
+    joinBlocks
+  };
+
+  return {
+    ...renderer,
+    write(block = "") {
+      if (block) stdout.write(`${block}\n`);
+    },
+    writeError(block = "") {
+      if (block) stderr.write(`${block}\n`);
+    },
+    writeJson(value) {
+      stdout.write(`${renderer.json(value)}\n`);
+    },
+    writeErrorJson(value) {
+      stderr.write(`${renderer.json(value)}\n`);
+    }
+  };
+}