@inspecto-dev/cli 0.2.0-alpha.5 → 0.3.0-alpha.1

package/dist/bin.js

@@ -1,65 +1,546 @@
 import {
+  apply,
+  detect,
   doctor,
+  exists,
   init,
   log,
-  teardown
-} from "./chunk-MIHQGC3L.js";
+  onboard,
+  plan,
+  reportCommandError,
+  teardown,
+  writeFile
+} from "./chunk-FZS2TLXQ.js";
 
 // src/bin.ts
 import { cac } from "cac";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { createRequire } from "module";
-var require2 = createRequire(import.meta.url);
-var { version } = require2("../package.json");
-var cli = cac("inspecto");
-cli.command("init", "Set up Inspecto in your project").option("--shared", "Share .inspecto/settings.json with your team via Git", { default: false }).option("--skip-install", "Skip npm dependency installation", { default: false }).option("--dry-run", "Preview changes without modifying files", { default: false }).option("--provider <provider>", "Set default provider (e.g. copilot, claude-code)").option("--no-extension", "Skip VS Code extension installation", { default: false }).option("--packages <names>", "(Monorepo) Comma-separated list of packages to inject").option("--force", "Force initialization even if environment is unsupported", { default: false }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
-  try {
-    await init({
-      shared: options.shared ?? false,
-      skipInstall: options.skipInstall ?? false,
-      dryRun: options.dryRun ?? false,
-      ...options.provider && { provider: options.provider },
-      // Changed from prefer to provider
-      noExtension: options.noExtension ?? false,
-      ...options.packages && {
-        packages: options.packages.split(",").map((s) => s.trim())
+
+// src/commands/integration-install.ts
+import fs from "fs/promises";
+import { homedir } from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+var REPO_RAW_BASE = "https://raw.githubusercontent.com/inspecto-dev/inspecto/main";
+var INTEGRATION_MANIFESTS = [
+  {
+    assistant: "codex",
+    type: "native-skill",
+    installTarget: "~/.codex/skills/",
+    preferredInstall: "npx @inspecto-dev/cli integrations install codex",
+    cliSupported: true
+  },
+  {
+    assistant: "claude-code",
+    type: "native-skill",
+    installTarget: ".claude/skills/ or ~/.claude/skills/",
+    preferredInstall: "npx @inspecto-dev/cli integrations install claude-code --scope project",
+    cliSupported: true
+  },
+  {
+    assistant: "copilot",
+    type: "instruction-template",
+    installTarget: ".github/copilot-instructions.md or AGENTS.md",
+    preferredInstall: "npx @inspecto-dev/cli integrations install copilot",
+    cliSupported: true
+  },
+  {
+    assistant: "cursor",
+    type: "rule-template",
+    installTarget: ".cursor/rules/inspecto-onboarding.mdc or AGENTS.md",
+    preferredInstall: "npx @inspecto-dev/cli integrations install cursor --mode rules",
+    cliSupported: true
+  },
+  {
+    assistant: "gemini",
+    type: "context-template",
+    installTarget: "GEMINI.md",
+    preferredInstall: "npx @inspecto-dev/cli integrations install gemini",
+    cliSupported: true
+  },
+  {
+    assistant: "trae",
+    type: "compatibility-template",
+    installTarget: "AGENTS.md",
+    preferredInstall: "npx @inspecto-dev/cli integrations install trae",
+    cliSupported: true
+  },
+  {
+    assistant: "coco",
+    type: "compatibility-template",
+    installTarget: "AGENTS.md",
+    preferredInstall: "npx @inspecto-dev/cli integrations install coco",
+    cliSupported: true
+  }
+];
+async function installIntegration(assistant, options = {}) {
+  const plan2 = resolveInstallPlan(assistant, options);
+  log.header("Inspecto Integration Install");
+  for (const asset of plan2.assets) {
+    if (await exists(asset.target) && !options.force) {
+      throw new Error(
+        `Refusing to overwrite existing file: ${asset.target}. Re-run with --force if you want to replace it.`
+      );
+    }
+  }
+  const downloadedAssets = [];
+  for (const asset of plan2.assets) {
+    const content = await loadAsset(asset);
+    downloadedAssets.push({ asset, content });
+  }
+  for (const { asset, content } of downloadedAssets) {
+    await writeFile(asset.target, content);
+    if (asset.executable) {
+      await fs.chmod(asset.target, 493);
+    }
+  }
+  log.success(plan2.successMessage);
+  log.hint(plan2.nextStep);
+}
+function describeIntegration(assistant, options = {}) {
+  const manifest = getIntegrationManifest(assistant);
+  const targets = manifest.cliSupported ? resolveInstallPlan(assistant, options).assets.map((asset) => asset.target) : [manifest.installTarget];
+  return {
+    assistant: manifest.assistant,
+    type: manifest.type,
+    targets,
+    preferredInstall: manifest.preferredInstall,
+    cliSupported: manifest.cliSupported
+  };
+}
+function printIntegrationList() {
+  log.header("Inspecto Integrations");
+  for (const manifest of INTEGRATION_MANIFESTS) {
+    const support = manifest.cliSupported ? "CLI" : "native installer";
+    log.info(`${manifest.assistant} \u2014 ${manifest.type} \u2014 ${manifest.installTarget} \u2014 ${support}`);
+  }
+}
+function printIntegrationPath(assistant, options = {}) {
+  const description = describeIntegration(assistant, options);
+  log.header(`Inspecto Integration Paths: ${description.assistant}`);
+  for (const target of description.targets) {
+    log.info(target);
+  }
+  if (description.cliSupported) {
+    log.hint(`Preferred install: ${description.preferredInstall}`);
+  } else {
+    log.hint(`Native install required: ${description.preferredInstall}`);
+  }
+}
+function resolveInstallPlan(assistant, options) {
+  switch (assistant) {
+    case "codex":
+      return resolveCodexPlan(options);
+    case "claude-code":
+      return resolveClaudeCodePlan(options);
+    case "copilot":
+      return resolveCopilotPlan(options);
+    case "cursor":
+      return resolveCursorPlan(options);
+    case "gemini":
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/gemini/GEMINI.md`,
+            target: "GEMINI.md",
+            localSource: "assistant-integrations/gemini/GEMINI.md"
+          }
+        ],
+        successMessage: "Installed Gemini context to GEMINI.md",
+        nextStep: "Start a new Gemini CLI session."
+      };
+    case "trae":
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/trae/AGENTS.md`,
+            target: "AGENTS.md",
+            localSource: "assistant-integrations/trae/AGENTS.md"
+          }
+        ],
+        successMessage: "Installed Trae compatibility instructions to AGENTS.md",
+        nextStep: "Open a new Trae chat."
+      };
+    case "coco":
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/coco/AGENTS.md`,
+            target: "AGENTS.md",
+            localSource: "assistant-integrations/coco/AGENTS.md"
+          }
+        ],
+        successMessage: "Installed Coco compatibility instructions to AGENTS.md",
+        nextStep: "Start a new Coco session."
+      };
+    default:
+      throw new Error(`Unknown assistant: ${assistant}`);
+  }
+}
+function getIntegrationManifest(assistant) {
+  const manifest = INTEGRATION_MANIFESTS.find((item) => item.assistant === assistant);
+  if (!manifest) {
+    throw new Error(
+      `Unknown assistant: ${assistant}. Run 'inspecto integrations list' to see available targets.`
+    );
+  }
+  return manifest;
+}
+function resolveCodexPlan(options) {
+  if (options.scope !== void 0) {
+    throw new Error("`--scope` is not supported for codex.");
+  }
+  if (options.mode !== void 0) {
+    throw new Error("`--mode` is not supported for codex.");
+  }
+  const baseDir = path.join(homedir(), ".codex/skills/inspecto-onboarding-codex");
+  return {
+    assets: [
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-codex/SKILL.md`,
+        target: path.join(baseDir, "SKILL.md"),
+        localSource: "skills/inspecto-onboarding-codex/SKILL.md"
+      },
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-codex/agents/openai.yaml`,
+        target: path.join(baseDir, "agents/openai.yaml"),
+        localSource: "skills/inspecto-onboarding-codex/agents/openai.yaml"
       },
-      force: options.force ?? false
-    });
-  } catch (err) {
-    log.error(err instanceof Error ? err.message : String(err));
-    if (options.debug && err instanceof Error && err.stack) {
-      console.error(err.stack);
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh`,
+        target: path.join(baseDir, "scripts/run-inspecto.sh"),
+        executable: true,
+        localSource: "skills/inspecto-onboarding-codex/scripts/run-inspecto.sh"
+      }
+    ],
+    successMessage: `Installed Codex skill to ${baseDir}`,
+    nextStep: "Restart Codex or start a new Codex session to load the skill."
+  };
+}
+function resolveClaudeCodePlan(options) {
+  const scope = options.scope ?? "project";
+  const unsupportedMode = options.mode !== void 0;
+  if (unsupportedMode) {
+    throw new Error(
+      "`--mode` is not supported for claude-code. Use `--scope project|user` instead."
+    );
+  }
+  if (scope !== "project" && scope !== "user") {
+    throw new Error(`Unknown Claude Code scope: ${scope}`);
+  }
+  const baseDir = scope === "user" ? path.join(homedir(), ".claude/skills/inspecto-onboarding-claude-code") : ".claude/skills/inspecto-onboarding-claude-code";
+  return {
+    assets: [
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-claude-code/SKILL.md`,
+        target: path.join(baseDir, "SKILL.md"),
+        localSource: "skills/inspecto-onboarding-claude-code/SKILL.md"
+      },
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-claude-code/agents/openai.yaml`,
+        target: path.join(baseDir, "agents/openai.yaml"),
+        localSource: "skills/inspecto-onboarding-claude-code/agents/openai.yaml"
+      },
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh`,
+        target: path.join(baseDir, "scripts/run-inspecto.sh"),
+        executable: true,
+        localSource: "skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh"
+      }
+    ],
+    successMessage: `Installed Claude Code skill to ${baseDir}`,
+    nextStep: "Restart Claude Code to load the new skill."
+  };
+}
+function resolveCopilotPlan(options) {
+  const mode = options.mode ?? "instructions";
+  if (options.scope !== void 0) {
+    throw new Error(
+      "`--scope` is not supported for copilot. Use `--mode instructions|agents` instead."
+    );
+  }
+  switch (mode) {
+    case "instructions":
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/copilot/.github/copilot-instructions.md`,
+            target: ".github/copilot-instructions.md",
+            localSource: "assistant-integrations/copilot/.github/copilot-instructions.md"
+          }
+        ],
+        successMessage: "Installed Copilot instructions to .github/copilot-instructions.md",
+        nextStep: "Open a new Copilot chat or agent session."
+      };
+    case "agents":
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/copilot/AGENTS.md`,
+            target: "AGENTS.md",
+            localSource: "assistant-integrations/copilot/AGENTS.md"
+          }
+        ],
+        successMessage: "Installed Copilot compatibility instructions to AGENTS.md",
+        nextStep: "Open a new Copilot chat or agent session."
+      };
+    default:
+      throw new Error(`Unknown Copilot mode: ${mode}`);
+  }
+}
+function resolveCursorPlan(options) {
+  const mode = options.mode ?? "rules";
+  if (options.scope !== void 0) {
+    throw new Error("`--scope` is not supported for cursor. Use `--mode rules|agents` instead.");
+  }
+  switch (mode) {
+    case "rules":
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/cursor/.cursor/rules/inspecto-onboarding.mdc`,
+            target: ".cursor/rules/inspecto-onboarding.mdc",
+            localSource: "assistant-integrations/cursor/.cursor/rules/inspecto-onboarding.mdc"
+          }
+        ],
+        successMessage: "Installed Cursor rule to .cursor/rules/inspecto-onboarding.mdc",
+        nextStep: "Open a new Cursor chat."
+      };
+    case "agents":
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/cursor/AGENTS.md`,
+            target: "AGENTS.md",
+            localSource: "assistant-integrations/cursor/AGENTS.md"
+          }
+        ],
+        successMessage: "Installed Cursor compatibility instructions to AGENTS.md",
+        nextStep: "Open a new Cursor chat."
+      };
+    default:
+      throw new Error(`Unknown Cursor mode: ${mode}`);
+  }
+}
+async function loadAsset(asset) {
+  if (asset.localSource) {
+    const localPath = await resolveBundledAssetPath(asset.localSource);
+    if (localPath) {
+      return await fs.readFile(localPath, "utf-8");
     }
-    process.exit(1);
   }
-});
-cli.command("doctor", "Diagnose your Inspecto installation").option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
-  try {
-    await doctor();
-  } catch (err) {
-    log.error(err instanceof Error ? err.message : String(err));
-    if (options.debug && err instanceof Error && err.stack) {
-      console.error(err.stack);
+  return await downloadAsset(asset.source);
+}
+async function resolveBundledAssetPath(relativePath) {
+  const startDir = path.dirname(fileURLToPath(import.meta.url));
+  let currentDir = startDir;
+  for (let depth = 0; depth < 8; depth += 1) {
+    const candidate = path.join(currentDir, relativePath);
+    if (await exists(candidate)) {
+      return candidate;
     }
-    process.exit(1);
+    const parent = path.dirname(currentDir);
+    if (parent === currentDir) break;
+    currentDir = parent;
   }
-});
-cli.command("teardown", "Remove Inspecto from your project").option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+  return null;
+}
+async function downloadAsset(source) {
+  let response;
   try {
-    await teardown();
-  } catch (err) {
-    log.error(err instanceof Error ? err.message : String(err));
-    if (options.debug && err instanceof Error && err.stack) {
-      console.error(err.stack);
-    }
-    process.exit(1);
-  }
-});
-cli.help();
-cli.version(version);
-try {
-  cli.parse();
-} catch (err) {
-  log.error(err instanceof Error ? err.message : String(err));
+    response = await fetch(source);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to download ${source}: ${reason}`);
+  }
+  if (!response.ok) {
+    throw new Error(`Failed to download ${source}: ${response.status} ${response.statusText}`);
+  }
+  return await response.text();
+}
+
+// src/bin.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+var integrationScopes = ["project", "user"];
+var integrationModes = ["instructions", "agents", "rules"];
+function exitWithError(error, options = {}) {
+  reportCommandError(error, {
+    debug: options.debug ?? false,
+    json: options.json ?? false
+  });
   process.exit(1);
 }
+function createCli(_argv = process.argv) {
+  const cli = cac("inspecto");
+  cli.command("init", "Set up Inspecto in your project").option("--shared", "Share .inspecto/settings.json with your team via Git", { default: false }).option("--skip-install", "Skip npm dependency installation", { default: false }).option("--dry-run", "Preview changes without modifying files", { default: false }).option("--provider <provider>", "Set default provider (e.g. copilot, claude-code)").option("--no-extension", "Skip VS Code extension installation", { default: false }).option("--packages <names>", "(Monorepo) Comma-separated list of packages to inject").option("--force", "Force initialization even if environment is unsupported", {
+    default: false
+  }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await init({
+        shared: options.shared ?? false,
+        skipInstall: options.skipInstall ?? false,
+        dryRun: options.dryRun ?? false,
+        ...options.provider && { provider: options.provider },
+        noExtension: options.noExtension ?? false,
+        ...options.packages && {
+          packages: options.packages.split(",").map((s) => s.trim())
+        },
+        force: options.force ?? false
+      });
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.command("doctor", "Diagnose your Inspecto installation").option("--json", "Print machine-readable JSON output", { default: false }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await doctor({ json: options.json ?? false });
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.command("onboard", "Run assistant-oriented Inspecto onboarding in one structured flow").option("--json", "Print machine-readable JSON output", { default: false }).option("--target <packagePath>", "Select a monorepo target package explicitly").option("--yes", "Accept a lightweight confirmation gate automatically", { default: false }).option("--shared", "Write shared Inspecto settings instead of local-only settings").option("--skip-install", "Skip npm dependency installation").option("--dry-run", "Preview changes without modifying files").option("--no-extension", "Skip IDE extension installation").option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await onboard({
+        json: options.json ?? false,
+        ...options.target && { target: options.target },
+        yes: options.yes ?? false,
+        ...options.shared !== void 0 && { shared: options.shared },
+        ...options.skipInstall !== void 0 && { skipInstall: options.skipInstall },
+        ...options.dryRun !== void 0 && { dryRun: options.dryRun },
+        ...options.extension === false && { noExtension: true }
+      });
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.command("detect", "Detect whether the current project can be onboarded automatically").option("--json", "Print machine-readable JSON output", { default: false }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await detect(options.json ?? false);
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.command("plan", "Preview the onboarding plan for the current project").option("--json", "Print machine-readable JSON output", { default: false }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await plan(options.json ?? false);
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.command("apply", "Apply the onboarding plan to the current project").option("--json", "Print machine-readable JSON output", { default: false }).option("--shared", "Write shared Inspecto settings instead of local-only settings").option("--skip-install", "Skip npm dependency installation").option("--dry-run", "Preview changes without modifying files").option("--no-extension", "Skip IDE extension installation").option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await apply({
+        json: options.json ?? false,
+        ...options.shared !== void 0 && { shared: options.shared },
+        ...options.skipInstall !== void 0 && { skipInstall: options.skipInstall },
+        ...options.dryRun !== void 0 && { dryRun: options.dryRun },
+        ...options.extension === false && { noExtension: true }
+      });
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.command("teardown", "Remove Inspecto from your project").option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await teardown();
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.command("integrations [...args]", "Manage assistant integration assets").option(
+    "--scope <scope>",
+    "Set install scope for supported assistants (e.g. claude-code: project|user)"
+  ).option(
+    "--mode <mode>",
+    "Set install mode for supported assistants (e.g. copilot: instructions|agents)"
+  ).option("--force", "Overwrite existing integration files", { default: false }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (args, options) => {
+    try {
+      const [subcommand, assistant, ...rest] = args;
+      const integrationOptions = buildIntegrationOptions(options);
+      if (subcommand === "list") {
+        if (assistant || rest.length > 0 || options.scope || options.mode || options.force) {
+          throw new Error(
+            "The `list` subcommand does not accept assistant names, --scope, --mode, or --force."
+          );
+        }
+        printIntegrationList();
+        return;
+      }
+      if (subcommand === "path" && assistant) {
+        if (rest.length > 0) {
+          throw new Error("The `path` subcommand accepts exactly one assistant argument.");
+        }
+        if (options.force) {
+          throw new Error("The `path` subcommand does not support `--force`.");
+        }
+        printIntegrationPath(assistant, integrationOptions);
+        return;
+      }
+      if (subcommand !== "install" || !assistant) {
+        throw new Error(
+          [
+            "Usage:",
+            "  inspecto integrations list",
+            "  inspecto integrations path <assistant> [--scope <scope>] [--mode <mode>]",
+            "  inspecto integrations install <assistant> [--scope <scope>] [--mode <mode>] [--force]"
+          ].join("\n")
+        );
+      }
+      if (rest.length > 0) {
+        throw new Error("The `install` subcommand accepts exactly one assistant argument.");
+      }
+      await installIntegration(assistant, {
+        ...integrationOptions,
+        force: options.force ?? false
+      });
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.help();
+  cli.version(version);
+  return cli;
+}
+function buildIntegrationOptions(options) {
+  const resolved = {};
+  if (options.scope) {
+    if (isIntegrationScope(options.scope)) {
+      resolved.scope = options.scope;
+    } else {
+      throw new Error(`Unknown integration scope: ${options.scope}`);
+    }
+  }
+  if (options.mode) {
+    if (isIntegrationMode(options.mode)) {
+      resolved.mode = options.mode;
+    } else {
+      throw new Error(`Unknown integration mode: ${options.mode}`);
+    }
+  }
+  return resolved;
+}
+function isIntegrationScope(value) {
+  return integrationScopes.includes(value);
+}
+function isIntegrationMode(value) {
+  return integrationModes.includes(value);
+}
+async function runCli(argv = process.argv) {
+  const cli = createCli(argv);
+  const parsedArgv = [...argv];
+  try {
+    await cli.parse(parsedArgv);
+  } catch (error) {
+    exitWithError(error, { json: argv.includes("--json") });
+  }
+}
+var entryPath = process.argv[1];
+if (entryPath && fileURLToPath2(import.meta.url) === entryPath) {
+  void runCli();
+}
+export {
+  createCli,
+  runCli
+};