@supa-magic/spm 0.1.0 → 0.2.1

package/dist/bin/spm.js

@@ -1,13 +1,886 @@
 #!/usr/bin/env node
 import { Command } from "commander";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, relative, resolve, normalize } from "node:path";
+import { parse, stringify } from "yaml";
+import { execSync, spawn } from "node:child_process";
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
 const registerDoctorCommand = (program2) => {
   program2.command("doctor").description("Check project health and compatibility").action(() => {
     console.log("Not implemented yet");
   });
 };
+const knownProviders = {
+  claude: ".claude",
+  cursor: ".cursor/rules",
+  copilot: ".copilot",
+  aider: ".aider",
+  codeium: ".codeium",
+  cody: ".cody"
+};
+const detectProviders = (root) => Object.entries(knownProviders).reduce(
+  (providers, [name, path]) => {
+    const fullPath = join(root, path);
+    if (existsSync(fullPath)) {
+      providers[name] = { path };
+    }
+    return providers;
+  },
+  {}
+);
+const getGitRoot = () => {
+  try {
+    return execSync("git rev-parse --show-toplevel", { encoding: "utf-8" }).trim();
+  } catch {
+    return void 0;
+  }
+};
+const getProjectRoot = () => getGitRoot() ?? process.cwd();
+const CONFIG_FILE = ".spmrc.yml";
+const getConfigPath = (root) => join(root ?? getProjectRoot(), CONFIG_FILE);
+const createDefaultConfig = (root) => ({
+  version: 1,
+  providers: detectProviders(root)
+});
+const readConfig = (root) => {
+  const resolvedRoot = getProjectRoot();
+  const configPath = getConfigPath(resolvedRoot);
+  if (!existsSync(configPath)) {
+    const config = createDefaultConfig(resolvedRoot);
+    writeConfig(config, resolvedRoot);
+    return { config, created: true };
+  }
+  const content = readFileSync(configPath, "utf-8");
+  return { config: parse(content), created: false };
+};
+const writeConfig = (config, root) => {
+  const configPath = getConfigPath(root);
+  writeFileSync(configPath, stringify(config), "utf-8");
+};
+const green = "\x1B[32m";
+const red = "\x1B[31m";
+const cyan = "\x1B[36m";
+const dim$1 = "\x1B[2m";
+const reset$2 = "\x1B[0m";
+const hideCursor = "\x1B[?25l";
+const showCursor = "\x1B[?25h";
+const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const funMessages = {
+  packages: [
+    "Resolving dependency tree...",
+    "Negotiating versions...",
+    "Cross-referencing package manifests...",
+    "Validating checksums...",
+    "Flattening nested dependencies...",
+    "Fetching metadata from the registry...",
+    "Comparing lockfile with remote...",
+    "Deduplicating shared packages...",
+    // ~20% worried
+    "This package has 47 peer deps. Deep breath...",
+    "The lockfile disagrees. The lockfile is wrong..."
+  ],
+  skills: [
+    "Loading skill into working memory...",
+    "Parsing skill metadata...",
+    "Checking for skill conflicts...",
+    "Mapping skill dependencies...",
+    "Indexing knowledge base...",
+    "Verifying skill signatures...",
+    "Wiring skills into a blockchain...",
+    "Calibrating expertise level...",
+    "Cross-referencing existing skills...",
+    "Analyzing project conventions...",
+    "Merging skill definitions...",
+    "Resolving naming conflicts...",
+    "Adapting skills to project rules...",
+    "Aligning intentions with context...",
+    "Validating output structure...",
+    "Making sure skills actually work...",
+    "Mapping file dependencies...",
+    "Warming up the tubes and transistors...",
+    "Reading configuration files...",
+    "Scanning project structure...",
+    "Writing changes to disk...",
+    // ~20% worried
+    "Something looks off in the skill graph...",
+    "Skill definition is ambiguous. Guessing...",
+    "Agent returned something weird. Reading it charitably...",
+    "The agent went off-script. Gently correcting..."
+  ],
+  generic: [
+    "Warming up the tubes and transistors...",
+    "Reading configuration files...",
+    "Scanning project structure...",
+    "Writing changes to disk...",
+    "Tidying up temporary files...",
+    "Verifying file integrity...",
+    "Syncing state...",
+    "Finishing up loose ends...",
+    // ~20% worried
+    "This should've worked. Looking into it...",
+    "That took longer than expected. Moving on..."
+  ]
+};
+const write = (s) => process.stdout.write(s);
+const createStepper = () => {
+  let frameIndex = 0;
+  let currentText = "";
+  let currentCategory = "generic";
+  let items = [];
+  let interval;
+  let renderedLineCount = 0;
+  let renderedItemCount = 0;
+  let prevKeptCount = 0;
+  let spinnerRendered = false;
+  let startTime = 0;
+  let funIndex = 0;
+  let lastFunSwap = 0;
+  let cursorHidden = false;
+  let funLineRendered = false;
+  let currentFunText = "";
+  const writeCursorHide = () => {
+    if (!cursorHidden) {
+      write(hideCursor);
+      cursorHidden = true;
+    }
+  };
+  const writeCursorShow = () => {
+    if (cursorHidden) {
+      write(showCursor);
+      cursorHidden = false;
+    }
+  };
+  const clearRendered = () => {
+    if (renderedLineCount > 0) {
+      write(`\x1B[${renderedLineCount}A\r\x1B[J`);
+      renderedLineCount = 0;
+      renderedItemCount = 0;
+      prevKeptCount = 0;
+      spinnerRendered = false;
+      funLineRendered = false;
+      currentFunText = "";
+    }
+  };
+  const donePrefix = `  ${green}•${reset$2} `;
+  const pendingPrefix = `  ${dim$1}•${reset$2} `;
+  const render = () => {
+    const elapsed = Date.now() - startTime;
+    const frame = frames[frameIndex % frames.length];
+    if (!spinnerRendered) {
+      write(`${cyan}${frame}${reset$2} ${currentText}\x1B[K
+`);
+      renderedLineCount++;
+      spinnerRendered = true;
+    } else {
+      const dist = renderedLineCount - prevKeptCount;
+      write(
+        `\x1B[${dist}A\r${cyan}${frame}${reset$2} ${currentText}\x1B[K\x1B[${dist}B\r`
+      );
+    }
+    items.forEach((it, i) => {
+      if (i < renderedItemCount && it.done && !it.renderedDone) {
+        const linesUp = renderedLineCount - prevKeptCount - 1 - i;
+        write(
+          `\x1B[${linesUp}A\r${donePrefix}${it.text}\x1B[K\x1B[${linesUp}B\r`
+        );
+        it.renderedDone = true;
+      }
+    });
+    if (renderedItemCount < items.length && funLineRendered) {
+      write("\x1B[1A\r\x1B[K");
+      renderedLineCount--;
+      funLineRendered = false;
+    }
+    while (renderedItemCount < items.length) {
+      const it = items[renderedItemCount];
+      const prefix = it.done ? donePrefix : pendingPrefix;
+      write(`${prefix}${it.text}\x1B[K
+`);
+      if (it.done) it.renderedDone = true;
+      renderedItemCount++;
+      renderedLineCount++;
+    }
+    if (elapsed > 1e4) {
+      const msgs = funMessages[currentCategory];
+      if (lastFunSwap === 0 || Date.now() - lastFunSwap > 1e4) {
+        funIndex = (funIndex + 1) % msgs.length;
+        lastFunSwap = Date.now();
+      }
+      const newFunText = msgs[funIndex];
+      const funLine = `  └ ${dim$1}${newFunText}${reset$2}`;
+      if (!funLineRendered) {
+        write(`${funLine}\x1B[K
+`);
+        renderedLineCount++;
+        funLineRendered = true;
+        currentFunText = newFunText;
+      } else if (newFunText !== currentFunText) {
+        write(`\x1B[1A\r${funLine}\x1B[K\x1B[1B\r`);
+        currentFunText = newFunText;
+      }
+    }
+    frameIndex++;
+  };
+  const stopInterval = () => {
+    if (interval) {
+      clearInterval(interval);
+      interval = void 0;
+    }
+  };
+  const startInterval = () => {
+    stopInterval();
+    interval = setInterval(render, 80);
+    render();
+  };
+  const onExit = () => writeCursorShow();
+  process.on("exit", onExit);
+  return {
+    start: (text, category) => {
+      writeCursorHide();
+      currentText = text;
+      currentCategory = category ?? "generic";
+      items = [];
+      renderedItemCount = 0;
+      spinnerRendered = false;
+      funLineRendered = false;
+      currentFunText = "";
+      startTime = Date.now();
+      lastFunSwap = 0;
+      funIndex = Math.floor(Math.random() * funMessages[currentCategory].length);
+      startInterval();
+    },
+    item: (text) => {
+      const last = items.at(-1);
+      if (last && !last.done) last.done = true;
+      items.push({
+        text: text.replace(/^• /, ""),
+        done: false,
+        renderedDone: false
+      });
+    },
+    succeed: (text, dimText) => {
+      stopInterval();
+      clearRendered();
+      const dimPart = dimText ? ` ${dim$1}${dimText}${reset$2}` : "";
+      write(`${green}✔${reset$2} ${text}${dimPart}
+`);
+      const keptItems = items.length <= 1 ? [] : items;
+      keptItems.forEach((it) => {
+        write(`${donePrefix}${it.text}\x1B[K
+`);
+      });
+      prevKeptCount = keptItems.length;
+      renderedLineCount = prevKeptCount;
+      renderedItemCount = 0;
+      items = [];
+      spinnerRendered = false;
+    },
+    fail: (text) => {
+      stopInterval();
+      clearRendered();
+      write(`${red}✖${reset$2} ${text}
+`);
+      writeCursorShow();
+    },
+    stop: () => {
+      stopInterval();
+      clearRendered();
+      writeCursorShow();
+      process.removeListener("exit", onExit);
+    }
+  };
+};
+const registerInitCommand = (program2) => {
+  program2.command("init").description("Initialize project configuration (.spmrc.yml)").action(() => {
+    const stepper = createStepper();
+    const { config, created } = readConfig();
+    const providers = Object.keys(config.providers);
+    if (created) {
+      stepper.succeed(`Created ${CONFIG_FILE}`);
+    } else {
+      stepper.succeed(`${CONFIG_FILE} already exists`);
+    }
+    stepper.start("Detecting providers...", "generic");
+    providers.forEach((name) => stepper.item(name));
+    if (providers.length > 0) {
+      stepper.succeed(`Detected ${providers.length} provider(s)`);
+    } else {
+      stepper.fail("No providers detected");
+    }
+    stepper.stop();
+  });
+};
+const downloadFromGitHub = async (source) => {
+  const url = `https://raw.githubusercontent.com/${source.owner}/${source.repository}/${source.ref}/${source.path}`;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download from GitHub: ${url} (${response.status} ${response.statusText})`
+    );
+  }
+  return response.text();
+};
+const downloadFromUrl = async (source) => {
+  const response = await fetch(source.url);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download from URL: ${source.url} (${response.status} ${response.statusText})`
+    );
+  }
+  return response.text();
+};
+const readLocalFile = async (source) => {
+  try {
+    return await readFile(source.filePath, "utf-8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to read local file: ${source.filePath} (${message})`
+    );
+  }
+};
+const getContent = (source) => {
+  if (source.kind === "github") return downloadFromGitHub(source);
+  if (source.kind === "url") return downloadFromUrl(source);
+  return readLocalFile(source);
+};
+const downloadFile = async (source) => {
+  const content = await getContent(source);
+  return { content, source };
+};
+const template = '# Skillset Integration\n\nYou are integrating a new skillset into the project. Analyze the existing project setup and intelligently integrate the new files.\n\n## Context\n\n- **Downloaded files**: `{{downloadDir}}`\n- **Provider directory**: `{{providerDir}}`\n- **Skillset**: `{{skillsetName}}` v`{{skillsetVersion}}`\n- **Source**: `{{source}}`\n- **Config file**: `{{configPath}}`\n\nIdentical files have already been removed from the download folder. Only files that need action remain. If the download folder is empty, skip to the config update step.\n\n## Output Format\n\nCRITICAL — follow exactly:\n- NEVER wrap output in code blocks or backticks\n- NEVER write conversational text ("Now let me...", "Let me check...", "The files are...")\n- NEVER use emojis\n- Output ONLY structured log lines\n- Step headers are plain text ending with `...` — these are parsed by the CLI to drive spinner states\n- Items below headers are indented with 2 spaces and use `• ` prefix\n- File lists use ASCII tree: `├─`, `└─`, `│`\n- End with `Done` on its own line\n\nStep headers (use these exactly):\n\n1. `Analyzing existing setup...`\n2. `Analyzing downloaded files...`\n3. `Detecting conflicts...`\n4. `Integrating...`\n5. `Updating config...`\n6. `Running setup...` (only if a setup file exists)\n7. `Cleaning up...`\n8. `Done`\n\nExample output:\n\nAnalyzing existing setup...\n  • 4 skills, 2 rules, 1 hook\n\nAnalyzing downloaded files...\n  • skills: git, github, implement\n  • rules: coding\n  • hook: biome-format\n\nDetecting conflicts...\n  • No conflicts\n\nIntegrating...\n  • skills/git/SKILL.md\n  • skills/git/branch.md\n  • skills/github/SKILL.md\n\nUpdating config...\n  • skillset: skill-creator@1.0.0\n\nRunning setup...\n  • Configured MCP server: biome\n\nCleaning up...\n  • Removed .spm/skill-creator\n\nDone\n\n## Step 1: Analyzing existing setup\n\nRead the provider directory (`{{providerDir}}`) and catalog what is already in place: skills, rules, agents, hooks, mcp servers, memory files.\n\n## Step 2: Analyzing downloaded files\n\nRead all files in `{{downloadDir}}`. Only files present in this folder need to be installed.\n\n## Step 3: Detecting conflicts\n\nFor each downloaded file, check if a file with the same name exists in the provider directory.\n\n- **No existing file** → install as new\n- **Different skillset version** → replace silently (new version supersedes)\n- **Same version or no version info** → conflict — ask the user:\n\nDetecting conflicts...\n  • rules/coding.md — local has custom rules\n  • Choose: (r)eplace / (s)kip / (m)erge\n\nWait for response before proceeding.\n\n## Step 4: Integrating\n\nInstall files into `{{providerDir}}`, following the directory structure from the download folder.\n\n**Integrate, don\'t copy.** When a new skill can leverage existing project conventions, adapt it:\n\n- If the project has `rules/coding.md` with specific conventions → make new skills follow those rules instead of their own defaults\n- If existing skills handle branching or committing → reference them instead of duplicating instructions\n- If the project has naming conventions, testing patterns, or architectural rules → align new skills with them\n\n## Step 5: Updating config\n\nUpdate `{{configPath}}`:\n\n- Under the provider with path `{{providerDir}}`, add the skillset entry under `skillsets`:\n  `{{skillsetName}}: "{{source}}@{{skillsetVersion}}"`\n- Do NOT add individual skill, agent, or file names to the config\n- The `skills` map is reserved for standalone skill installations\n\n{{setupSection}}\n\n## Step 7: Cleaning up (last step before Done)\n\nDelete the download folder `{{downloadDir}}` and its contents.\n\n## Rules\n\n- Setup files are NOT installed — they contain instructions to configure the project\n- Do not delete or modify existing files in the provider directory unless resolving a conflict\n- Always delete the download folder when done\n';
+const buildSetupSection = (setupFile) => setupFile ? [
+  "## Step 6: Running setup",
+  "",
+  `Read the setup file at \`${setupFile}\` and follow its instructions.`,
+  "Setup files configure the project environment (e.g. MCP servers, LSP, tooling).",
+  "Do NOT copy the setup file into the provider directory — only execute its instructions."
+].join("\n") : "";
+const buildInstructions = (input) => template.replace(/\{\{downloadDir\}\}/g, input.downloadDir).replace(/\{\{providerDir\}\}/g, input.providerDir).replace(/\{\{skillsetName\}\}/g, input.skillsetName).replace(/\{\{skillsetVersion\}\}/g, input.skillsetVersion).replace(/\{\{source\}\}/g, input.source).replace(/\{\{configPath\}\}/g, input.configPath).replace("{{setupSection}}", buildSetupSection(input.setupFile));
+const writeInstructionsFile = (input) => {
+  const filePath = join(tmpdir(), "spm", `install-${input.skillsetName}.md`);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, buildInstructions(input), "utf-8");
+  return filePath;
+};
+const TIMEOUT_MS = 12e4;
+const isNoise = (line) => line === "```" || line.startsWith("```") || /^(now |let me |the files? |i'll |i will |looking |checking )/i.test(line);
+const isStepHeader = (raw, trimmed) => !raw.startsWith(" ") && !raw.startsWith("	") && trimmed.endsWith("...");
+const stepCategory = (header) => {
+  if (header.startsWith("Integrating") || header.startsWith("Analyzing") || header.startsWith("Detecting"))
+    return "skills";
+  return "generic";
+};
+const irregulars = {
+  Running: "Ran"
+};
+const toSuccessText = (header) => {
+  const text = header.replace(/\.{3}$/, "").trim();
+  const firstWord = text.split(" ")[0];
+  if (irregulars[firstWord]) {
+    return text.replace(firstWord, irregulars[firstWord]);
+  }
+  return text.replace(/^(\w+)ing\b/, "$1ed");
+};
+const toRelativePath = (filePath, providerDir) => {
+  const normalized = filePath.replace(/\\/g, "/");
+  const base = providerDir.replace(/\\/g, "/");
+  const marker = `${base}/`;
+  const idx = normalized.lastIndexOf(marker);
+  if (idx !== -1) return normalized.slice(idx + marker.length);
+  return normalized.split("/").pop() ?? normalized;
+};
+const spawnClaude = (instructionsFilePath, stepper, providerDir) => new Promise((resolve2, reject) => {
+  const args = [
+    "-p",
+    "Install the skill as instructed.",
+    "--append-system-prompt-file",
+    instructionsFilePath,
+    "--verbose",
+    "--output-format",
+    "stream-json",
+    "--allowedTools",
+    "Read,Write,Edit,Bash,Glob,Grep"
+  ];
+  const isWindows = process.platform === "win32";
+  const child = spawn("claude", args, {
+    timeout: TIMEOUT_MS,
+    shell: isWindows,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let resultText = "";
+  let lineBuffer = "";
+  let currentStepHeader = "Analyzing existing setup...";
+  let stepItems = [];
+  let stepFileCount = 0;
+  const state = { doneReceived: false };
+  const writtenFiles = [];
+  const succeedCurrentStep = () => {
+    if (!currentStepHeader) return;
+    const base = toSuccessText(currentStepHeader);
+    if (currentStepHeader.startsWith("Detecting")) {
+      const noConflicts = stepItems.some((i) => /no conflict/i.test(i));
+      stepper.succeed(noConflicts ? "No conflicts" : base);
+      return;
+    }
+    if (currentStepHeader.startsWith("Integrating")) {
+      stepper.succeed(
+        stepFileCount > 0 ? `Skillset was integrated (${stepFileCount} file(s))` : "Skillset was integrated"
+      );
+      return;
+    }
+    if (currentStepHeader.startsWith("Running setup")) {
+      const context2 = stepItems.length === 1 ? stepItems[0] : void 0;
+      stepper.succeed("Skillset setup completed", context2);
+      return;
+    }
+    const context = stepItems.length === 1 ? stepItems[0] : void 0;
+    stepper.succeed(base, context);
+  };
+  stepper.start("Analyzing existing setup...", "skills");
+  child.stdout.on("data", (chunk) => {
+    lineBuffer += chunk.toString();
+    const lines = lineBuffer.split("\n");
+    lineBuffer = lines.pop() ?? "";
+    lines.filter(Boolean).forEach((line) => {
+      try {
+        const event = JSON.parse(line);
+        if (event.type === "result" && event.result) {
+          resultText = event.result;
+          return;
+        }
+        if (event.type !== "assistant") return;
+        const blocks = event.message?.content;
+        if (!blocks) return;
+        blocks.forEach((block) => {
+          if (block.type === "text" && block.text) {
+            block.text.split("\n").forEach((ln) => {
+              const trimmed = ln.trim();
+              if (!trimmed || isNoise(trimmed)) return;
+              if (trimmed === "Done") {
+                succeedCurrentStep();
+                currentStepHeader = "";
+                state.doneReceived = true;
+                return;
+              }
+              if (isStepHeader(ln, trimmed)) {
+                if (trimmed === currentStepHeader) return;
+                succeedCurrentStep();
+                currentStepHeader = trimmed;
+                stepItems = [];
+                stepFileCount = 0;
+                stepper.start(trimmed, stepCategory(trimmed));
+              } else if (!currentStepHeader.startsWith("Integrating")) {
+                stepItems.push(trimmed);
+                stepper.item(trimmed);
+              }
+            });
+          }
+          if (block.type === "tool_use" && (block.name === "Write" || block.name === "Edit")) {
+            const filePath = block.input?.file_path;
+            if (typeof filePath === "string") {
+              const relative2 = toRelativePath(filePath, providerDir);
+              writtenFiles.push(relative2);
+              stepFileCount++;
+              if (currentStepHeader.startsWith("Integrating")) {
+                stepper.item(relative2);
+              }
+            }
+          }
+        });
+      } catch {
+      }
+    });
+  });
+  child.stderr.on("data", () => {
+  });
+  child.on("error", (err) => {
+    if ("code" in err && err.code === "ENOENT") {
+      reject(
+        new Error(
+          "Claude CLI not found. Install it: npm i -g @anthropic-ai/claude-code"
+        )
+      );
+      return;
+    }
+    reject(err);
+  });
+  child.on("close", (code) => {
+    if (currentStepHeader) {
+      succeedCurrentStep();
+    }
+    const completed = state.doneReceived || resultText.length > 0;
+    if (code !== 0 && code !== null) {
+      reject(new Error(`Claude CLI exited with code ${code}`));
+      return;
+    }
+    if (code === null && !completed) {
+      reject(new Error("Claude CLI was interrupted before completing"));
+      return;
+    }
+    resolve2({
+      success: true,
+      output: resultText,
+      files: writtenFiles
+    });
+  });
+});
+const installSkillset = (input, stepper) => spawnClaude(writeInstructionsFile(input), stepper, input.providerDir);
+const hash = (content) => createHash("sha256").update(content).digest("hex");
+const collectFiles = (dir) => readdirSync(dir).flatMap((entry) => {
+  const fullPath = join(dir, entry);
+  return statSync(fullPath).isDirectory() ? collectFiles(fullPath) : [fullPath];
+});
+const pruneUnchanged = (downloadDir, providerDir) => {
+  const files = collectFiles(downloadDir);
+  let removed = 0;
+  files.forEach((downloadedFile) => {
+    const relativePath = relative(downloadDir, downloadedFile);
+    const existingFile = join(providerDir, relativePath);
+    if (!existsSync(existingFile)) return;
+    const downloadedHash = hash(readFileSync(downloadedFile, "utf-8"));
+    const existingHash = hash(readFileSync(existingFile, "utf-8"));
+    if (downloadedHash === existingHash) {
+      unlinkSync(downloadedFile);
+      removed++;
+    }
+  });
+  return removed;
+};
+const requiredFields = ["name", "version", "description", "provider"];
+const validateSkillset = (data) => {
+  if (!data || typeof data !== "object") {
+    throw new Error("Invalid skillset: expected a YAML object.");
+  }
+  const record = data;
+  const missing = requiredFields.filter(
+    (field) => typeof record[field] !== "string"
+  );
+  if (missing.length > 0) {
+    throw new Error(
+      `Invalid skillset: missing required fields: ${missing.join(", ")}.`
+    );
+  }
+  return record;
+};
+const fetchSkillset = async (location) => {
+  const url = `https://raw.githubusercontent.com/${location.owner}/${location.repository}/${location.ref}/${location.path}`;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch skillset from ${url} (${response.status} ${response.statusText})`
+    );
+  }
+  const text = await response.text();
+  return validateSkillset(parse(text));
+};
+const parseGitHubUrl = (url) => {
+  const match = url.match(
+    /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/tree\/[^/]+\/(.+)$/
+  );
+  if (!match) return void 0;
+  return { owner: match[1], repository: match[2], path: match[3] };
+};
+const parseAtIdentifier = (input) => {
+  const parts = input.slice(1).split("/").filter(Boolean);
+  if (parts.length < 3) {
+    throw new Error(
+      `Invalid identifier "${input}". Expected format: @owner/repo/path (e.g., @supa-magic/skillbox/claude/fsd).`
+    );
+  }
+  return {
+    owner: parts[0],
+    repository: parts[1],
+    path: parts.slice(2).join("/")
+  };
+};
+const parseIdentifier = (input) => {
+  const trimmed = input.trim();
+  if (trimmed.startsWith("https://") || trimmed.startsWith("http://")) {
+    const result = parseGitHubUrl(trimmed);
+    if (!result) {
+      throw new Error(
+        `Invalid GitHub URL "${trimmed}". Expected format: https://github.com/owner/repo/tree/branch/path.`
+      );
+    }
+    return result;
+  }
+  if (!trimmed.startsWith("@")) {
+    throw new Error(
+      `Invalid identifier "${trimmed}". Must start with @ or be a GitHub URL.`
+    );
+  }
+  return parseAtIdentifier(trimmed);
+};
+const fetchDefaultBranch = async (owner, repository) => {
+  const response = await fetch(
+    `https://api.github.com/repos/${owner}/${repository}`
+  );
+  if (!response.ok) {
+    return "main";
+  }
+  const data = await response.json();
+  return data.default_branch ?? "main";
+};
+const resolveIdentifier = async (input) => {
+  const identifier = parseIdentifier(input);
+  const ref = await fetchDefaultBranch(identifier.owner, identifier.repository);
+  return {
+    owner: identifier.owner,
+    repository: identifier.repository,
+    path: `${identifier.path}/skillset.yml`,
+    ref
+  };
+};
+const resolveSkillSource = (source, location) => {
+  if (source.startsWith("./")) {
+    const skillsetDir = location.path.replace(/\/skillset\.yml$/, "");
+    const relativePath = source.slice(2).replace(/\/+$/, "");
+    return {
+      owner: location.owner,
+      repository: location.repository,
+      basePath: `${skillsetDir}/${relativePath}`
+    };
+  }
+  if (source.startsWith("@")) {
+    const parts = source.slice(1).split("/").filter(Boolean);
+    if (parts.length < 3) {
+      throw new Error(
+        `Invalid cross-repo source "${source}". Expected format: @owner/repo/path.`
+      );
+    }
+    return {
+      owner: parts[0],
+      repository: parts[1],
+      basePath: parts.slice(2).join("/")
+    };
+  }
+  const normalized = source.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (normalized.includes("..")) {
+    throw new Error(
+      `Invalid skill source "${source}". Path traversal ("..") is not allowed.`
+    );
+  }
+  return {
+    owner: location.owner,
+    repository: location.repository,
+    basePath: normalized
+  };
+};
+const resolveSkillset = (skillset, location) => {
+  const entries = [];
+  const skillsetDir = location.path.replace(/\/skillset\.yml$/, "");
+  if (skillset.setup) {
+    entries.push({
+      owner: location.owner,
+      repository: location.repository,
+      path: `${skillsetDir}/${skillset.setup}`,
+      type: "setup"
+    });
+  }
+  if (skillset.skills) {
+    Object.entries(skillset.skills).forEach(
+      ([skillName, { source, files }]) => {
+        const resolved = resolveSkillSource(source, location);
+        files.forEach((file) => {
+          entries.push({
+            owner: resolved.owner,
+            repository: resolved.repository,
+            path: `${resolved.basePath}/${file}`,
+            type: "skill",
+            skillName
+          });
+        });
+      }
+    );
+  }
+  const localFileTypes = ["agents", "hooks", "mcp", "memory", "rules"];
+  const typeMap = {
+    agents: "agent",
+    hooks: "hook",
+    mcp: "mcp",
+    memory: "memory",
+    rules: "rule"
+  };
+  localFileTypes.forEach((key) => {
+    const files = skillset[key];
+    if (files) {
+      files.forEach((file) => {
+        entries.push({
+          owner: location.owner,
+          repository: location.repository,
+          path: `${skillsetDir}/${file}`,
+          type: typeMap[key]
+        });
+      });
+    }
+  });
+  return entries;
+};
+const toGitHubSource = (entry, ref) => ({
+  kind: "github",
+  owner: entry.owner,
+  repository: entry.repository,
+  path: entry.path,
+  ref
+});
+const downloadEntries = async (entries, location, onFile) => {
+  const results = await Promise.all(
+    entries.map((entry) => {
+      const source = toGitHubSource(entry, location.ref);
+      return downloadFile(source).then((result) => {
+        onFile(entry.type, entry.path);
+        return {
+          ...result,
+          type: entry.type,
+          path: entry.path,
+          skillName: entry.skillName
+        };
+      });
+    })
+  );
+  return results;
+};
+const safePath = (baseDir, filePath) => {
+  const resolved = resolve(baseDir, normalize(filePath));
+  if (!resolved.startsWith(baseDir)) {
+    throw new Error(`Path traversal detected: "${filePath}"`);
+  }
+  return resolved;
+};
+const buildFileTree = (paths) => {
+  const root = { name: "", children: [] };
+  paths.forEach((p) => {
+    const parts = p.split("/");
+    let current = root;
+    parts.forEach((part) => {
+      const existing = current.children.find((c) => c.name === part);
+      if (existing) {
+        current = existing;
+      } else {
+        const node = { name: part, children: [] };
+        current.children.push(node);
+        current = node;
+      }
+    });
+  });
+  return root;
+};
+const renderTree = (node, prefix = "") => node.children.flatMap((child, i) => {
+  const isLast = i === node.children.length - 1;
+  const connector = isLast ? "└─" : "├─";
+  const childPrefix = prefix + (isLast ? "   " : "│  ");
+  const isDir = child.children.length > 0;
+  const name = isDir ? `${child.name}/` : child.name;
+  return [`${prefix}${connector} ${name}`, ...renderTree(child, childPrefix)];
+});
+const printSummary = (files) => {
+  if (files.length === 0) return;
+  const unique = [...new Set(files)];
+  const tree = buildFileTree(unique);
+  process.stdout.write(`
+📂 Installed files:
+`);
+  renderTree(tree).forEach((line) => {
+    process.stdout.write(`  ${dim$1}${line}${reset$2}
+`);
+  });
+};
 const registerInstallCommand = (program2) => {
-  program2.command("install <skillset>").alias("i").description("Install a skillset into the project").action((skillset) => {
-    console.log(`install ${skillset}: Not implemented yet`);
+  program2.command("install <skillset>").alias("i").description("Install a skillset into the project").action(async (input) => {
+    const stepper = createStepper();
+    const startedAt = Date.now();
+    try {
+      const { config } = readConfig();
+      stepper.start("Resolving endpoint...", "packages");
+      const location = await resolveIdentifier(input);
+      const locationRef = `${location.owner}/${location.repository}@${location.ref}`;
+      stepper.succeed("Resolved", locationRef);
+      stepper.start("Fetching skillset manifest...", "packages");
+      const skillset = await fetchSkillset(location);
+      stepper.succeed(
+        `Fetched skillset manifest`,
+        `${skillset.name} v${skillset.version}`
+      );
+      const providerEntry = Object.entries(config.providers).find(
+        ([name]) => name === skillset.provider
+      );
+      if (!providerEntry) {
+        throw new Error(
+          `Provider "${skillset.provider}" not found in config. Run "spm init" to detect providers.`
+        );
+      }
+      const [, provider] = providerEntry;
+      const entries = resolveSkillset(skillset, location);
+      if (entries.length === 0) {
+        stepper.succeed("No files to download");
+        stepper.stop();
+        return;
+      }
+      const projectRoot = getProjectRoot();
+      const downloadDir = join(projectRoot, ".spm", skillset.name);
+      const skillsetDir = location.path.replace(/\/[^/]+$/, "");
+      const stripPrefix = (p) => p.startsWith(`${skillsetDir}/`) ? p.slice(skillsetDir.length + 1) : p;
+      stepper.start(`Downloading ${entries.length} file(s)...`, "packages");
+      const results = await downloadEntries(
+        entries,
+        location,
+        (type, path) => stepper.item(`${type} ${stripPrefix(path)}`)
+      );
+      const setupResults = results.filter((r) => r.type === "setup");
+      const installResults = results.filter((r) => r.type !== "setup");
+      await Promise.all(
+        installResults.map(async (result2) => {
+          const relative2 = stripPrefix(result2.path);
+          const filePath = safePath(downloadDir, relative2);
+          await mkdir(dirname(filePath), { recursive: true });
+          await writeFile(filePath, result2.content, "utf-8");
+        })
+      );
+      let setupFile;
+      if (setupResults.length > 0) {
+        const setup = setupResults[0];
+        const relative2 = stripPrefix(setup.path);
+        setupFile = join(downloadDir, relative2);
+        await mkdir(dirname(setupFile), { recursive: true });
+        await writeFile(setupFile, setup.content, "utf-8");
+      }
+      stepper.succeed(`Downloaded ${results.length} file(s)`);
+      const downloadedPaths = installResults.map((r) => stripPrefix(r.path));
+      const providerFullPath = join(projectRoot, provider.path);
+      const pruned = pruneUnchanged(downloadDir, providerFullPath);
+      if (pruned > 0) {
+        stepper.succeed(`Skipped ${pruned} unchanged file(s)`);
+      }
+      const result = await installSkillset(
+        {
+          downloadDir,
+          setupFile,
+          providerDir: provider.path,
+          skillsetName: skillset.name,
+          skillsetVersion: skillset.version,
+          source: `@${location.owner}/${location.repository}`,
+          configPath: getConfigPath()
+        },
+        stepper
+      );
+      stepper.stop();
+      const elapsed = Math.round((Date.now() - startedAt) / 1e3);
+      const timeStr = elapsed >= 60 ? `${Math.floor(elapsed / 60)}m${(elapsed % 60).toString().padStart(2, "0")}s` : `${elapsed}s`;
+      process.stdout.write(
+        `${green}✔${reset$2} Installation completed ${dim$1}in ${timeStr}${reset$2}
+`
+      );
+      const summaryFiles = result.files.length > 0 ? result.files : downloadedPaths;
+      printSummary(summaryFiles);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      stepper.fail(message);
+      stepper.stop();
+      process.exitCode = 1;
+    }
   });
 };
 const registerListCommand = (program2) => {
@@ -25,17 +898,18 @@ const banner = (version2) => [
   `${shade}▝▜${light}████▛▘  ${reset$1}${dim}v${version2} ✨ supa-magic${reset$1}`,
   `${shade}  ▘${light}  ▝`
 ].join("\n");
-const version = "0.1.0";
+const version = "0.2.1";
 const program = new Command();
 const gray = "\x1B[90m";
 const reset = "\x1B[0m";
-program.name("spm").description(banner(version)).version(version).configureHelp({
+program.name("spm").description(banner(version)).version(version, "-v, --version").configureHelp({
   formatHelp: (cmd, helper) => {
     const defaultHelp = Command.prototype.createHelp().formatHelp(cmd, helper);
     const [description, ...rest] = defaultHelp.split("\n\n");
     return [description, `${gray}${rest.join("\n\n")}${reset}`].join("\n\n");
   }
 });
+registerInitCommand(program);
 registerInstallCommand(program);
 registerListCommand(program);
 registerDoctorCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supa-magic/spm",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI tool for managing AI skillsets",
   "license": "MIT",
   "contributors": [
@@ -27,20 +27,23 @@
     "node": ">=20"
   },
   "scripts": {
-    "start": "clear && claude --dangerously-skip-permissions",
     "build": "vite build",
     "pretest": "npm run build",
+    "start": "clear && claude --dangerously-skip-permissions",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "tokscale": "npx tokscale@latest"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.6",
     "@types/node": "^25.4.0",
     "typescript": "5.8.3",
+    "typescript-language-server": "^5.1.3",
     "vite": "^7.3.1",
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "yaml": "^2.8.2"
   }
 }