@iamsaroj/replicax 0.0.1 → 0.0.3

package/dist/index.js

@@ -129,15 +129,19 @@ var SECRET_GUARD_GLOBS = [
   "**/*.key",
   "**/*.p12",
   "**/*.pfx",
+  "**/*.p8",
   "**/*.cert",
   "**/*.crt",
   "**/*.keystore",
   "**/*.jks",
+  "**/*.ppk",
   "**/id_rsa*",
   "**/id_dsa*",
   "**/id_ecdsa*",
   "**/id_ed25519*",
   "**/.netrc",
+  "**/.pgpass",
+  "**/.htpasswd",
   "**/secrets.*",
   "**/*.secret",
   "**/*.secrets"
@@ -454,7 +458,7 @@ function detectFramework(pkg) {
     [has("svelte"), "svelte"],
     [has("solid-js"), "solid"],
     [has("react"), "react"],
-    [has("@fastify/fastify") || has("fastify"), "fastify"],
+    [has("fastify"), "fastify"],
     [has("koa"), "koa"],
     [has("express"), "express"]
   ];
@@ -943,9 +947,765 @@ async function maybeWriteIgnoreFile(root) {
   }
 }
 
-// src/commands/create.ts
+// src/commands/init-skill.ts
+import path7 from "path";
+import fs6 from "fs-extra";
+import ora2 from "ora";
+
+// src/config/ai-targets.ts
+var SKILL_TARGETS = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    entryPath: (slug) => `.claude/skills/${slug}/SKILL.md`,
+    note: "Claude Code loads skills from .claude/skills/<name>/SKILL.md"
+  },
+  {
+    id: "codex",
+    label: "OpenAI Codex CLI",
+    entryPath: (slug) => `.codex/skills/${slug}/SKILL.md`,
+    note: "Codex CLI loads project skills from .codex/skills/<name>/SKILL.md"
+  },
+  {
+    id: "antigravity",
+    label: "Google Antigravity",
+    entryPath: (slug) => `.agents/skills/${slug}.md`,
+    note: "Antigravity discovers skills under .agents/skills/"
+  }
+];
+var SKILL_TARGET_BY_ID = new Map(SKILL_TARGETS.map((t) => [t.id, t]));
+var SKILL_TARGET_IDS = SKILL_TARGETS.map((t) => t.id);
+
+// src/utils/slug.ts
+function slugify(input, fallback = "project") {
+  const slug = input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || fallback;
+}
+
+// src/core/skill-generator.ts
+var FRAMEWORK_LABELS = {
+  next: "Next.js",
+  nuxt: "Nuxt",
+  remix: "Remix",
+  astro: "Astro",
+  angular: "Angular",
+  sveltekit: "SvelteKit",
+  nestjs: "NestJS",
+  expo: "Expo",
+  "react-native": "React Native",
+  vue: "Vue",
+  svelte: "Svelte",
+  solid: "SolidJS",
+  react: "React",
+  fastify: "Fastify",
+  koa: "Koa",
+  express: "Express",
+  node: "Node",
+  unknown: "unknown"
+};
+var PRIMARY_SCRIPTS = [
+  "dev",
+  "start",
+  "build",
+  "test",
+  "test:watch",
+  "lint",
+  "format",
+  "format:check",
+  "typecheck"
+];
+function installCommand(pm) {
+  switch (pm) {
+    case "yarn":
+      return "yarn";
+    case "pnpm":
+      return "pnpm install";
+    case "bun":
+      return "bun install";
+    default:
+      return "npm install";
+  }
+}
+function runCommand(pm, script) {
+  switch (pm) {
+    case "yarn":
+      return `yarn ${script}`;
+    case "pnpm":
+      return `pnpm ${script}`;
+    case "bun":
+      return `bun run ${script}`;
+    default:
+      return `npm run ${script}`;
+  }
+}
+function orderedScripts(scripts) {
+  const names = Object.keys(scripts);
+  const primary = PRIMARY_SCRIPTS.filter((s) => names.includes(s));
+  const rest = names.filter((s) => !PRIMARY_SCRIPTS.includes(s)).sort();
+  return [...primary, ...rest];
+}
+function toolingByCategoryLabel(tooling) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const file of tooling.files) {
+    const label = CATEGORY_BY_ID.get(file.category)?.label ?? file.category;
+    const list = groups.get(label) ?? [];
+    list.push(file.path);
+    groups.set(label, list);
+  }
+  return [...groups.entries()].map(([label, paths]) => [label, paths.sort()]).sort((a, b) => a[0].localeCompare(b[0]));
+}
+function topLevelDirectories(structure) {
+  return structure.directories.filter((d) => !d.includes("/")).sort();
+}
+function yamlString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function testingTool(tooling, pkg) {
+  const haystack = [
+    ...tooling.files.map((f) => f.path),
+    ...Object.keys(pkg?.devDependencies ?? {}),
+    ...Object.keys(pkg?.dependencies ?? {})
+  ];
+  const has = (needle) => haystack.some((s) => s.includes(needle));
+  if (has("vitest")) return "Vitest";
+  if (has("jest")) return "Jest";
+  if (has("playwright")) return "Playwright";
+  if (has("cypress")) return "Cypress";
+  return void 0;
+}
+function hasCategory(tooling, categoryId) {
+  return tooling.files.some((f) => f.category === categoryId);
+}
+function conventionLines(args, scripts) {
+  const { metadata, tooling } = args;
+  const pm = metadata.packageManager;
+  const has = (s) => s in scripts;
+  const lines = [];
+  if (metadata.language === "typescript") {
+    lines.push(
+      has("typecheck") ? `Written in TypeScript \u2014 run \`${runCommand(pm, "typecheck")}\` before committing.` : "Written in TypeScript \u2014 prefer typed APIs and keep the type checker clean."
+    );
+  }
+  if (hasCategory(tooling, "prettier")) {
+    lines.push(
+      has("format") ? `Formatting is handled by Prettier \u2014 run \`${runCommand(pm, "format")}\`.` : "Formatting is handled by Prettier \u2014 match the configured style."
+    );
+  }
+  if (hasCategory(tooling, "eslint")) {
+    lines.push(
+      has("lint") ? `Linting via ESLint \u2014 run \`${runCommand(pm, "lint")}\`.` : "Linting via ESLint \u2014 keep the rules satisfied."
+    );
+  }
+  const tester = testingTool(tooling, args.pkg);
+  if (tester) {
+    lines.push(
+      has("test") ? `Tests use ${tester} \u2014 run \`${runCommand(pm, "test")}\`.` : `Tests use ${tester}.`
+    );
+  }
+  if (hasCategory(tooling, "docker")) {
+    lines.push("Containerized with Docker (see the Dockerfile / compose files).");
+  }
+  if (hasCategory(tooling, "cicd")) {
+    lines.push("CI is configured \u2014 keep the pipeline green before merging.");
+  }
+  if (hasCategory(tooling, "husky")) {
+    lines.push("Git hooks (Husky) run on commit \u2014 do not bypass them.");
+  }
+  lines.push("Match the existing code style and the folder layout shown above.");
+  return lines;
+}
+function buildSkill(args) {
+  const { name, metadata, tooling, structure, pkg } = args;
+  const slug = slugify(name);
+  const pm = metadata.packageManager;
+  const framework = FRAMEWORK_LABELS[metadata.framework] ?? metadata.framework;
+  const language = metadata.language === "typescript" ? "TypeScript" : "JavaScript";
+  const scripts = pkg?.scripts ?? {};
+  const description = `${name} project: ${framework}/${language} setup, build/test commands, and tooling conventions. Use this skill when working in or scaffolding this codebase.`;
+  const lines = [];
+  lines.push("---");
+  lines.push(`name: ${slug}`);
+  lines.push(`description: ${yamlString(description)}`);
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${name}`);
+  lines.push("");
+  lines.push(`Setup, commands, and conventions for \`${name}\`, generated by ReplicaX.`);
+  lines.push("");
+  lines.push("## Tech stack");
+  lines.push("");
+  lines.push(`- **Language:** ${language}`);
+  lines.push(`- **Framework:** ${framework}`);
+  lines.push(`- **Package manager:** ${pm}`);
+  lines.push(`- **Node version:** ${metadata.nodeVersion}`);
+  lines.push("");
+  lines.push("## Setup");
+  lines.push("");
+  lines.push("Install dependencies:");
+  lines.push("");
+  lines.push("```bash");
+  lines.push(installCommand(pm));
+  lines.push("```");
+  lines.push("");
+  const scriptNames = orderedScripts(scripts);
+  if (scriptNames.length > 0) {
+    lines.push("## Commands");
+    lines.push("");
+    for (const script of scriptNames) {
+      lines.push(`- **${script}** \u2014 \`${runCommand(pm, script)}\``);
+    }
+    lines.push("");
+  }
+  const groups = toolingByCategoryLabel(tooling);
+  if (groups.length > 0) {
+    lines.push("## Tooling");
+    lines.push("");
+    for (const [label, paths] of groups) {
+      lines.push(`- **${label}:** ${paths.join(", ")}`);
+    }
+    lines.push("");
+  }
+  const dirs = topLevelDirectories(structure);
+  if (dirs.length > 0) {
+    lines.push("## Project structure");
+    lines.push("");
+    lines.push("Top-level directories:");
+    lines.push("");
+    for (const dir of dirs) {
+      lines.push(`- \`${dir}/\``);
+    }
+    lines.push("");
+  }
+  lines.push("## Conventions");
+  lines.push("");
+  for (const line of conventionLines(args, scripts)) {
+    lines.push(`- ${line}`);
+  }
+  lines.push("");
+  return { slug, content: lines.join("\n") };
+}
+
+// src/core/ai/cli.ts
+import { spawn } from "child_process";
+async function commandExists(bin) {
+  const onWindows = process.platform === "win32";
+  const locator = onWindows ? "where" : "command";
+  const args = onWindows ? [bin] : ["-v", bin];
+  return new Promise((resolve) => {
+    const child = spawn(locator, args, {
+      // `command -v` is a POSIX shell builtin; `where` is a real Windows exe.
+      shell: !onWindows,
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child.on("error", () => resolve(false));
+    child.on("close", (code) => resolve(code === 0));
+  });
+}
+async function runWithStdin(bin, args, input, timeoutMs = 12e4) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { shell: true, windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error(`${bin} timed out after ${Math.round(timeoutMs / 1e3)}s`));
+    }, timeoutMs);
+    child.stdout.on("data", (d) => stdout += d.toString());
+    child.stderr.on("data", (d) => stderr += d.toString());
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0 && !stdout.trim()) {
+        reject(new Error(`${bin} exited with code ${code}: ${stderr.trim() || "no output"}`));
+      } else {
+        resolve({ stdout, code });
+      }
+    });
+    child.stdin.end(input);
+  });
+}
+
+// src/core/ai/providers.ts
+async function postJson(url, headers, body) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`HTTP ${res.status}: ${text.slice(0, 300) || res.statusText}`);
+  }
+  return res.json();
+}
+async function callAnthropic(prompt, apiKey, model) {
+  const data = await postJson(
+    "https://api.anthropic.com/v1/messages",
+    { "x-api-key": apiKey, "anthropic-version": "2023-06-01" },
+    { model, max_tokens: 8e3, messages: [{ role: "user", content: prompt }] }
+  );
+  return (data.content ?? []).filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("");
+}
+async function callOpenAI(prompt, apiKey, model) {
+  const data = await postJson(
+    "https://api.openai.com/v1/chat/completions",
+    { authorization: `Bearer ${apiKey}` },
+    { model, messages: [{ role: "user", content: prompt }] }
+  );
+  return data.choices?.[0]?.message?.content ?? "";
+}
+async function callGemini(prompt, apiKey, model) {
+  const data = await postJson(
+    `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`,
+    { "x-goog-api-key": apiKey },
+    { contents: [{ parts: [{ text: prompt }] }] }
+  );
+  return (data.candidates?.[0]?.content?.parts ?? []).map((p) => p.text ?? "").join("");
+}
+var PROVIDERS = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    cliBin: "claude",
+    cliArgs: ["-p"],
+    apiEnvVars: ["ANTHROPIC_API_KEY"],
+    modelEnvVar: "REPLICAX_ANTHROPIC_MODEL",
+    defaultModel: "claude-opus-4-8",
+    callApi: callAnthropic
+  },
+  {
+    id: "openai",
+    label: "OpenAI Codex",
+    cliBin: "codex",
+    cliArgs: ["exec"],
+    apiEnvVars: ["OPENAI_API_KEY"],
+    modelEnvVar: "REPLICAX_OPENAI_MODEL",
+    defaultModel: "gpt-5.5",
+    callApi: callOpenAI
+  },
+  {
+    id: "gemini",
+    label: "Gemini",
+    cliBin: "gemini",
+    cliArgs: [],
+    apiEnvVars: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+    modelEnvVar: "REPLICAX_GEMINI_MODEL",
+    defaultModel: "gemini-3.5-flash",
+    callApi: callGemini
+  }
+];
+var PROVIDER_IDS = PROVIDERS.map((p) => p.id);
+function firstEnv(vars) {
+  for (const v of vars) {
+    const val = process.env[v];
+    if (val && val.trim()) return val.trim();
+  }
+  return void 0;
+}
+function cliInvoker(def) {
+  return {
+    id: def.id,
+    via: `${def.label} CLI`,
+    run: async (prompt) => (await runWithStdin(def.cliBin, def.cliArgs, prompt)).stdout
+  };
+}
+function apiInvoker(def, apiKey, modelOverride) {
+  const model = modelOverride ?? process.env[def.modelEnvVar] ?? def.defaultModel;
+  return {
+    id: def.id,
+    via: `${def.label} API (${model})`,
+    run: (prompt) => def.callApi(prompt, apiKey, model)
+  };
+}
+async function resolveProvider(preference, modelOverride) {
+  if (preference) {
+    const def = PROVIDERS.find((p) => p.id === preference);
+    if (!def) {
+      throw new ReplicaxError(`Unknown provider "${preference}".`, [
+        `Valid providers: ${PROVIDER_IDS.join(", ")}.`
+      ]);
+    }
+    if (await commandExists(def.cliBin)) return cliInvoker(def);
+    const key = firstEnv(def.apiEnvVars);
+    if (key) return apiInvoker(def, key, modelOverride);
+    throw new ReplicaxError(`Provider "${preference}" is not available.`, [
+      `Install its CLI (\`${def.cliBin}\`) or set ${def.apiEnvVars[0]}.`
+    ]);
+  }
+  for (const def of PROVIDERS) {
+    if (await commandExists(def.cliBin)) return cliInvoker(def);
+    const key = firstEnv(def.apiEnvVars);
+    if (key) return apiInvoker(def, key, modelOverride);
+  }
+  return null;
+}
+
+// src/core/ai/prompt.ts
+function buildSkillPrompt(args) {
+  const scripts = Object.entries(args.scripts).map(([name, cmd]) => `  ${name}: ${cmd}`).join("\n");
+  const tooling = args.toolingPaths.map((p) => `  ${p}`).join("\n");
+  return `You are an expert developer-tooling assistant. Generate a high-quality "skill" for an AI coding assistant: a document (plus optional supporting files) that teaches the assistant how to work productively in a specific software project.
+
+STRICT RULES:
+- Base everything ONLY on the PROJECT ANALYSIS below. Do not invent tools, frameworks, commands, or files that are not present in the analysis.
+- Output ONLY a single JSON object \u2014 no prose, no markdown code fences, no commentary before or after.
+
+OUTPUT SHAPE (exactly this JSON structure):
+{"files":[{"path":"<relative path>","content":"<file contents>"}]}
+
+REQUIREMENTS:
+- Include exactly one entry file whose path is "${args.entryFile}". It MUST start with YAML frontmatter containing "name: ${args.slug}" and a concise single-line "description", then clear markdown covering: tech stack, setup/install, common commands, tooling, project structure, and conventions.
+- You MAY add a few supporting files under "references/" (e.g. "references/commands.md") when genuinely useful. Keep the bundle small and focused.
+- All paths must be relative, use forward slashes, and must NOT contain ".." or be absolute.
+- This skill targets ${args.target.label} and will be installed at ${args.entryPath}.
+
+PROJECT ANALYSIS (ground truth \u2014 refine and expand this, do not contradict it):
+${args.analysis}
+
+CAPTURED CONFIG FILES:
+${tooling || "  (none)"}
+
+PACKAGE SCRIPTS:
+${scripts || "  (none)"}
+`;
+}
+
+// src/core/ai/bundle.ts
+import { z as z2 } from "zod";
+var SkillFileSchema = z2.object({
+  path: z2.string().min(1),
+  content: z2.string()
+});
+var SkillBundleSchema = z2.object({
+  files: z2.array(SkillFileSchema).min(1)
+});
+function extractJson(raw) {
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start === -1 || end === -1 || end < start) return null;
+  return raw.slice(start, end + 1);
+}
+function parseSkillBundle(raw) {
+  const json = extractJson(raw);
+  if (!json) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  const result = SkillBundleSchema.safeParse(parsed);
+  if (!result.success) return null;
+  const files = [];
+  for (const file of result.data.files) {
+    const safe = safeJoinable(file.path);
+    if (!safe) return null;
+    files.push({ path: safe, content: file.content });
+  }
+  return files;
+}
+
+// src/commands/init-skill.ts
+async function initSkillCommand(options) {
+  if (options.verbose) setVerbose(true);
+  const targetId = options.target?.toLowerCase();
+  if (!targetId) {
+    throw new ReplicaxError("Missing --target.", [
+      `Choose an AI assistant: ${SKILL_TARGET_IDS.join(", ")}.`,
+      "Example: replicax init-skill --target codex"
+    ]);
+  }
+  const target = SKILL_TARGET_BY_ID.get(targetId);
+  if (!target) {
+    throw new ReplicaxError(`Unknown target "${options.target}".`, [
+      `Valid targets: ${SKILL_TARGET_IDS.join(", ")}.`
+    ]);
+  }
+  const root = process.cwd();
+  const spinner = ora2({ text: "Scanning project\u2026", isEnabled: !options.verbose }).start();
+  const scan = await scanProject(root);
+  spinner.succeed(
+    `Scanned ${scan.tooling.files.length} config file(s) and ${scan.structure.directories.length} director(ies)`
+  );
+  const name = options.name ?? scan.structure.root;
+  const seed = buildSkill({
+    name,
+    metadata: scan.metadata,
+    tooling: scan.tooling,
+    structure: scan.structure,
+    pkg: scan.pkg
+  });
+  reportSkippedSecrets(scan.skippedSecrets);
+  const entryRel = target.entryPath(seed.slug);
+  const entryFile = entryRel.split("/").pop();
+  const bundleRoot = entryRel.slice(0, entryRel.length - entryFile.length).replace(/\/$/, "");
+  logger.newline();
+  logger.info(`${target.label} skill \u2192 ${entryRel}`);
+  if (options.dryRun) {
+    logger.newline();
+    logger.out(seed.content);
+    logger.newline();
+    logger.info("Dry run \u2014 no files were written and no AI provider was contacted.");
+    return;
+  }
+  let files = null;
+  let via = "built-in template";
+  if (options.ai !== false) {
+    const provider = await resolveProvider(options.provider, options.model);
+    if (provider) {
+      logger.info(`Generating with ${provider.via} (sending project setup only)\u2026`);
+      const aiSpinner = ora2({ text: "Authoring skill\u2026", isEnabled: !options.verbose }).start();
+      try {
+        const prompt = buildSkillPrompt({
+          slug: seed.slug,
+          entryFile,
+          entryPath: entryRel,
+          target,
+          analysis: seed.content,
+          toolingPaths: scan.tooling.files.map((f) => f.path),
+          scripts: scan.pkg?.scripts ?? {}
+        });
+        const raw = await provider.run(prompt);
+        const parsed = parseSkillBundle(raw);
+        if (parsed && parsed.some((f) => (f.path.split("/").pop() ?? "") === entryFile)) {
+          files = parsed;
+          via = provider.via;
+          aiSpinner.succeed(`Authored ${parsed.length} file(s) with ${provider.via}`);
+        } else {
+          aiSpinner.fail("AI output was not a usable skill bundle");
+          logger.warn("Falling back to the built-in template.");
+        }
+      } catch (err) {
+        aiSpinner.fail("AI generation failed");
+        logger.warn(`${err.message}. Falling back to the built-in template.`);
+      }
+    } else {
+      logger.info("No configured AI provider found \u2014 using the built-in template.");
+      logger.hint(
+        "For AI-authored skills, install the Claude/Codex/Gemini CLI or set ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY."
+      );
+    }
+  }
+  if (!files) {
+    files = [{ path: entryFile, content: seed.content }];
+  }
+  const planned = files.map((f) => {
+    const rel = bundleRoot ? `${bundleRoot}/${f.path}` : f.path;
+    const safe = safeJoinable(rel);
+    if (!safe) {
+      throw new ReplicaxError(`Refusing to write unsafe skill path: ${f.path}`);
+    }
+    return { rel: safe, abs: path7.join(root, ...safe.split("/")), content: f.content };
+  });
+  const conflicts = [];
+  for (const file of planned) {
+    if (await fs6.pathExists(file.abs)) conflicts.push(file.rel);
+  }
+  if (conflicts.length > 0 && !options.force) {
+    throw new ReplicaxError(
+      `${conflicts.length} skill file(s) already exist: ${conflicts.join(", ")}.`,
+      ["Re-run with --force to overwrite them."]
+    );
+  }
+  for (const file of planned) {
+    await fs6.ensureDir(path7.dirname(file.abs));
+    await fs6.writeFile(file.abs, file.content, "utf8");
+    logger.detail(`wrote: ${file.rel}`);
+  }
+  logger.newline();
+  logger.success(`Skill "${seed.slug}" written (${planned.length} file(s), via ${via})`);
+  logger.hint(
+    `Location: ${relPosix(root, path7.join(root, ...(bundleRoot || entryFile).split("/")))}`
+  );
+  logger.hint(target.note);
+}
+
+// src/commands/extract.ts
+import path9 from "path";
+import ora3 from "ora";
+
+// src/core/github.ts
+import os from "os";
 import path8 from "path";
 import fs7 from "fs-extra";
+import { extract as tarExtract } from "tar";
+function parseGitHubRef(input) {
+  const raw = input.trim();
+  if (!raw) {
+    throw new ReplicaxError("No repository specified.", [
+      "Pass a repo, e.g. replicax extract owner/repo"
+    ]);
+  }
+  let work = raw;
+  let ref;
+  const hash = work.indexOf("#");
+  if (hash !== -1) {
+    ref = work.slice(hash + 1).trim() || void 0;
+    work = work.slice(0, hash);
+  }
+  work = work.replace(/^git@github\.com:/i, "").replace(/^(?:https?:\/\/)?(?:www\.)?github\.com\//i, "").replace(/^\/+/, "");
+  const segments = work.split("/").filter(Boolean);
+  const owner = segments[0];
+  const repoSegment = segments[1];
+  if (!owner || !repoSegment) {
+    throw new ReplicaxError(`Could not parse a GitHub repository from "${input}".`, [
+      "Use owner/repo, a full https://github.com/owner/repo URL, or add #branch."
+    ]);
+  }
+  let repo = repoSegment.replace(/\.git$/i, "");
+  if (!ref && repo.includes("@")) {
+    const [name, atRef] = repo.split("@");
+    repo = name ?? repo;
+    if (atRef) ref = atRef;
+  }
+  const kind = segments[2];
+  if (!ref && (kind === "tree" || kind === "commit" || kind === "blob")) {
+    const rest = segments.slice(3).join("/");
+    if (rest) ref = rest;
+  }
+  const valid = (s) => /^[\w.-]+$/.test(s) && s !== "." && s !== "..";
+  if (!valid(owner) || !valid(repo)) {
+    throw new ReplicaxError(`Invalid GitHub repository: "${owner}/${repo}".`, [
+      'Owner and repo may contain only letters, numbers, ".", "_", and "-".'
+    ]);
+  }
+  return { owner, repo, ...ref ? { ref } : {} };
+}
+function refLabel(ref) {
+  return `${ref.owner}/${ref.repo}${ref.ref ? `@${ref.ref}` : ""}`;
+}
+function tokenFromEnv() {
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  return token?.trim() || void 0;
+}
+function httpError(status, slug, hasToken) {
+  if (status === 404) {
+    return new ReplicaxError(`Repository not found: ${slug}.`, [
+      "Check the owner/repo spelling and the branch/tag/commit name.",
+      hasToken ? "If it is private, make sure your token can access it." : "If it is private, set GITHUB_TOKEN (or GH_TOKEN) with repo access."
+    ]);
+  }
+  if (status === 401) {
+    return new ReplicaxError(`GitHub rejected the credentials for ${slug}.`, [
+      "Check that GITHUB_TOKEN (or GH_TOKEN) is valid and not expired."
+    ]);
+  }
+  if (status === 403 || status === 429) {
+    return new ReplicaxError(`GitHub rate limit hit while fetching ${slug}.`, [
+      hasToken ? "Wait a moment and try again." : "Set GITHUB_TOKEN (or GH_TOKEN) to raise the limit, then retry."
+    ]);
+  }
+  return new ReplicaxError(`GitHub returned HTTP ${status} for ${slug}.`);
+}
+async function firstSubdir(dir) {
+  const entries = await fs7.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) return path8.join(dir, entry.name);
+  }
+  return null;
+}
+async function downloadRepo(ref) {
+  const slug = `${ref.owner}/${ref.repo}`;
+  const url = `https://api.github.com/repos/${ref.owner}/${ref.repo}/tarball` + (ref.ref ? `/${encodeURIComponent(ref.ref)}` : "");
+  const token = tokenFromEnv();
+  const headers = {
+    "user-agent": "replicax",
+    accept: "application/vnd.github+json"
+  };
+  if (token) headers.authorization = `Bearer ${token}`;
+  let res;
+  try {
+    res = await fetch(url, { headers, redirect: "follow" });
+  } catch (err) {
+    throw new ReplicaxError(`Failed to reach GitHub: ${err.message}`, [
+      "Check your internet connection and try again."
+    ]);
+  }
+  if (!res.ok) {
+    throw httpError(res.status, slug, Boolean(token));
+  }
+  const tmpRoot = await fs7.mkdtemp(path8.join(os.tmpdir(), "replicax-extract-"));
+  const cleanup = () => fs7.remove(tmpRoot);
+  try {
+    const tarPath = path8.join(tmpRoot, "repo.tar.gz");
+    await fs7.writeFile(tarPath, Buffer.from(await res.arrayBuffer()));
+    const extractDir = path8.join(tmpRoot, "src");
+    await fs7.ensureDir(extractDir);
+    await tarExtract({ file: tarPath, cwd: extractDir, strip: 0 });
+    const repoRoot = await firstSubdir(extractDir);
+    if (!repoRoot) {
+      throw new ReplicaxError(`The downloaded archive for ${slug} was empty.`);
+    }
+    return { dir: repoRoot, cleanup };
+  } catch (err) {
+    await cleanup();
+    throw err;
+  }
+}
+
+// src/commands/extract.ts
+async function extractCommand(repo, options) {
+  if (options.verbose) setVerbose(true);
+  const parsed = parseGitHubRef(repo);
+  const target = { owner: parsed.owner, repo: parsed.repo, ref: options.ref ?? parsed.ref };
+  const label = refLabel(target);
+  const fetchSpinner = ora3({
+    text: `Fetching ${label} from GitHub\u2026`,
+    isEnabled: !options.verbose
+  }).start();
+  let downloaded;
+  try {
+    downloaded = await downloadRepo(target);
+  } catch (err) {
+    fetchSpinner.fail(`Could not fetch ${label}`);
+    throw err;
+  }
+  fetchSpinner.succeed(`Downloaded ${label}`);
+  try {
+    const name = options.name ?? target.repo;
+    const scanSpinner = ora3({ text: "Scanning repository\u2026", isEnabled: !options.verbose }).start();
+    const scan = await scanProject(downloaded.dir);
+    scanSpinner.succeed(
+      `Scanned ${scan.tooling.files.length} config file(s) and ${scan.structure.directories.length} director(ies)`
+    );
+    scan.structure.root = name;
+    const bundle = buildBundle({
+      name,
+      tooling: scan.tooling,
+      structure: scan.structure,
+      metadata: scan.metadata
+    });
+    reportSkippedSecrets(scan.skippedSecrets);
+    printScanSummary(bundle);
+    logger.out(renderTree(bundle.structure.directories, bundle.structure.root));
+    if (options.dryRun) {
+      logger.newline();
+      logger.info("Dry run \u2014 no files were written.");
+      return;
+    }
+    const outRoot = options.out ? path9.resolve(options.out) : process.cwd();
+    const dir = profileDir(outRoot);
+    if (await profileExists(dir)) {
+      logger.warn(
+        `A ReplicaX profile already exists in ${relPosix(process.cwd(), dir)}/ \u2014 replacing it.`
+      );
+    }
+    await saveBundle(dir, bundle);
+    logger.newline();
+    logger.success(`Profile "${name}" written to ${relPosix(process.cwd(), dir)}/`);
+    logger.hint("Create a project from it with: replicax create <project-name>");
+  } finally {
+    await downloaded.cleanup();
+  }
+}
+
+// src/commands/create.ts
+import path11 from "path";
+import fs9 from "fs-extra";
 
 // src/core/conflict-resolver.ts
 import { select } from "@inquirer/prompts";
@@ -987,8 +1747,8 @@ var ConflictResolver = class {
 };
 
 // src/core/project-generator.ts
-import path7 from "path";
-import fs6 from "fs-extra";
+import path10 from "path";
+import fs8 from "fs-extra";
 async function generateProject(options) {
   const { bundle, targetDir, projectName, dryRun, conflict } = options;
   const result = {
@@ -998,16 +1758,16 @@ async function generateProject(options) {
     filesSkipped: 0,
     unsafeSkipped: []
   };
-  if (!dryRun) await fs6.ensureDir(targetDir);
+  if (!dryRun) await fs8.ensureDir(targetDir);
   for (const dir of bundle.structure.directories) {
     const safe = safeJoinable(dir);
     if (!safe) {
       result.unsafeSkipped.push(dir);
       continue;
     }
-    const full = path7.join(targetDir, safe);
-    const existed = await fs6.pathExists(full);
-    if (!dryRun) await fs6.ensureDir(full);
+    const full = path10.join(targetDir, safe);
+    const existed = await fs8.pathExists(full);
+    if (!dryRun) await fs8.ensureDir(full);
     if (!existed) result.dirsCreated += 1;
     result.entries.push({ kind: "dir", path: safe, action: existed ? "skip" : "create" });
   }
@@ -1031,8 +1791,8 @@ async function writeFile(relPath, content, options, result) {
     logger.warn(`Refusing to write unsafe path from profile: ${relPath}`);
     return;
   }
-  const full = path7.join(options.targetDir, safe);
-  const exists = await fs6.pathExists(full);
+  const full = path10.join(options.targetDir, safe);
+  const exists = await fs8.pathExists(full);
   let action2 = exists ? "overwrite" : "create";
   if (exists) {
     const decision = await options.conflict.resolve(safe);
@@ -1045,8 +1805,8 @@ async function writeFile(relPath, content, options, result) {
     action2 = "overwrite";
   }
   if (!options.dryRun) {
-    await fs6.ensureDir(path7.dirname(full));
-    await fs6.writeFile(full, content, "utf8");
+    await fs8.ensureDir(path10.dirname(full));
+    await fs8.writeFile(full, content, "utf8");
   }
   result.filesWritten += 1;
   result.entries.push({ kind: "file", path: safe, action: action2 });
@@ -1054,7 +1814,7 @@ async function writeFile(relPath, content, options, result) {
 }
 
 // src/core/installer.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 var COMMANDS = {
   npm: ["npm", "install"],
   pnpm: ["pnpm", "install"],
@@ -1065,7 +1825,7 @@ function installDependencies(cwd, manager) {
   if (manager === "unknown") return Promise.resolve(false);
   const [command, ...args] = COMMANDS[manager];
   return new Promise((resolve) => {
-    const child = spawn(command, args, {
+    const child = spawn2(command, args, {
       cwd,
       stdio: "inherit",
       // npm/pnpm/yarn are .cmd shims on Windows; a shell resolves them.
@@ -1095,9 +1855,9 @@ async function createCommand(projectName, options) {
     logger.warn(`Profile integrity check found ${mismatches.length} issue(s); continuing anyway.`);
     logger.hint("Run `replicax validate` for details.");
   }
-  const targetDir = path8.resolve(process.cwd(), projectName);
-  const leafName = path8.basename(targetDir);
-  if (path8.resolve(process.cwd()) === targetDir) {
+  const targetDir = path11.resolve(process.cwd(), projectName);
+  const leafName = path11.basename(targetDir);
+  if (path11.resolve(process.cwd()) === targetDir) {
     throw new ReplicaxError("Refusing to scaffold into the current directory.", [
       "Pass a new project name, e.g. `replicax create my-app`."
     ]);
@@ -1146,8 +1906,8 @@ async function maybeInstall(manager, targetDir, options, hasPackageJson) {
     logger.hint("No package manager detected; run your install command manually.");
     return;
   }
-  const pkgPath = path8.join(targetDir, "package.json");
-  const pkg = await fs7.readJson(pkgPath).catch(() => null);
+  const pkgPath = path11.join(targetDir, "package.json");
+  const pkg = await fs9.readJson(pkgPath).catch(() => null);
   if (!pkg?.devDependencies || Object.keys(pkg.devDependencies).length === 0) {
     logger.hint("No dependencies to install.");
     return;
@@ -1160,7 +1920,7 @@ async function maybeInstall(manager, targetDir, options, hasPackageJson) {
 }
 
 // src/commands/sync.ts
-import ora2 from "ora";
+import ora4 from "ora";
 
 // src/core/diff.ts
 function diffChecksums(prev, next) {
@@ -1230,7 +1990,7 @@ async function syncCommand(options) {
     throw new ReplicaxError("No ReplicaX profile to sync.", ["Run `replicax init` first."]);
   }
   const existing = await loadBundle(dir);
-  const spinner = ora2({ text: "Re-scanning project\u2026", isEnabled: !options.verbose }).start();
+  const spinner = ora4({ text: "Re-scanning project\u2026", isEnabled: !options.verbose }).start();
   const scan = await scanProject(root);
   spinner.succeed("Re-scan complete");
   const next = buildBundle({
@@ -1284,6 +2044,15 @@ function printList(title, items, marker) {
 
 // src/commands/inspect.ts
 import Table from "cli-table3";
+
+// src/utils/format.ts
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// src/commands/inspect.ts
 var SECTIONS = ["profile", "tooling", "structure", "metadata"];
 async function inspectCommand(options) {
   const dir = options.profile ? await resolveProfileDir(options.profile) : profileDir(process.cwd());
@@ -1356,11 +2125,6 @@ function printStructure(bundle) {
   logger.out(renderTree(structure.directories, structure.root));
   logger.out("");
 }
-function formatBytes(bytes) {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
 
 // src/commands/validate.ts
 async function validateCommand(options) {
@@ -1398,20 +2162,20 @@ async function validateCommand(options) {
 }
 
 // src/commands/export.ts
-import path10 from "path";
-import fs9 from "fs-extra";
-import ora3 from "ora";
+import path13 from "path";
+import fs11 from "fs-extra";
+import ora5 from "ora";
 
 // src/core/archive.ts
-import os from "os";
-import path9 from "path";
-import fs8 from "fs-extra";
-import { create as tarCreate, extract as tarExtract } from "tar";
+import os2 from "os";
+import path12 from "path";
+import fs10 from "fs-extra";
+import { create as tarCreate, extract as tarExtract2 } from "tar";
 async function exportProfile(profileDirectory, outPath) {
-  const resolvedOut = path9.resolve(outPath);
-  await fs8.ensureDir(path9.dirname(resolvedOut));
-  const parent = path9.dirname(profileDirectory);
-  const base = path9.basename(profileDirectory);
+  const resolvedOut = path12.resolve(outPath);
+  await fs10.ensureDir(path12.dirname(resolvedOut));
+  const parent = path12.dirname(profileDirectory);
+  const base = path12.basename(profileDirectory);
   await tarCreate(
     {
       gzip: true,
@@ -1424,21 +2188,21 @@ async function exportProfile(profileDirectory, outPath) {
   );
 }
 async function extractToTemp(archivePath) {
-  const resolved = path9.resolve(archivePath);
-  if (!await fs8.pathExists(resolved)) {
+  const resolved = path12.resolve(archivePath);
+  if (!await fs10.pathExists(resolved)) {
     throw new Error(`Archive not found: ${archivePath}`);
   }
-  const tmp = await fs8.mkdtemp(path9.join(os.tmpdir(), "replicax-import-"));
-  await tarExtract({ file: resolved, cwd: tmp, strip: 0 });
+  const tmp = await fs10.mkdtemp(path12.join(os2.tmpdir(), "replicax-import-"));
+  await tarExtract2({ file: resolved, cwd: tmp, strip: 0 });
   return tmp;
 }
 async function findProfileRoot(dir) {
-  const hasProfile = async (d) => fs8.pathExists(path9.join(d, PROFILE_FILES.profile));
+  const hasProfile = async (d) => fs10.pathExists(path12.join(d, PROFILE_FILES.profile));
   if (await hasProfile(dir)) return dir;
-  const entries = await fs8.readdir(dir, { withFileTypes: true });
+  const entries = await fs10.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.isDirectory()) {
-      const candidate = path9.join(dir, entry.name);
+      const candidate = path12.join(dir, entry.name);
       if (await hasProfile(candidate)) return candidate;
     }
   }
@@ -1446,40 +2210,34 @@ async function findProfileRoot(dir) {
 }
 
 // src/commands/export.ts
-function slug(name) {
-  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "profile";
-}
 async function exportCommand(options) {
   const dir = options.profile ? await resolveProfileDir(options.profile) : profileDir(process.cwd());
   if (!await profileExists(dir)) {
     throw new ReplicaxError("No ReplicaX profile found to export.", ["Run `replicax init` first."]);
   }
   const bundle = await loadBundle(dir);
-  const outPath = path10.resolve(options.out ?? `${slug(bundle.profile.name)}.replicax.tar.gz`);
-  const spinner = ora3({ text: "Packaging profile\u2026" }).start();
+  const outPath = path13.resolve(
+    options.out ?? `${slugify(bundle.profile.name, "profile")}.replicax.tar.gz`
+  );
+  const spinner = ora5({ text: "Packaging profile\u2026" }).start();
   await exportProfile(dir, outPath);
   spinner.stop();
-  const { size } = await fs9.stat(outPath);
+  const { size } = await fs11.stat(outPath);
   logger.success(
-    `Exported "${bundle.profile.name}" \u2192 ${path10.relative(process.cwd(), outPath)} (${formatBytes2(size)})`
+    `Exported "${bundle.profile.name}" \u2192 ${path13.relative(process.cwd(), outPath)} (${formatBytes(size)})`
   );
   logger.hint("Share it, then `replicax import <file>` elsewhere.");
 }
-function formatBytes2(bytes) {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
 
 // src/commands/import.ts
-import fs10 from "fs-extra";
-import ora4 from "ora";
+import fs12 from "fs-extra";
+import ora6 from "ora";
 import { confirm as confirm2 } from "@inquirer/prompts";
 async function importCommand(archivePath, options) {
   if (!archivePath) {
     throw new ReplicaxError("An archive path is required: replicax import <file>");
   }
-  const spinner = ora4({ text: "Extracting archive\u2026" }).start();
+  const spinner = ora6({ text: "Extracting archive\u2026" }).start();
   const tmp = await extractToTemp(archivePath);
   try {
     const source = await findProfileRoot(tmp);
@@ -1500,7 +2258,7 @@ async function importCommand(archivePath, options) {
           "Re-run with --force to overwrite it."
         ]);
       }
-      await fs10.remove(dest);
+      await fs12.remove(dest);
     }
     await saveBundle(dest, bundle);
     logger.newline();
@@ -1509,7 +2267,7 @@ async function importCommand(archivePath, options) {
     );
     logger.hint("Create a project with: replicax create <project-name>");
   } finally {
-    await fs10.remove(tmp).catch(() => void 0);
+    await fs12.remove(tmp).catch(() => void 0);
   }
 }
 
@@ -1549,6 +2307,10 @@ function handleError(err) {
 var program = new Command();
 program.name("replicax").description("Copy the setup, not the code.").version(packageVersion(), "-v, --version", "Print the ReplicaX version").showHelpAfterError("(run `replicax --help` for usage)");
 program.command("init").description("Scan the current project and create a ReplicaX profile in .replicax/").option("--name <name>", "Name the profile").option("--dry-run", "Preview what would be captured without writing").option("--verbose", "Show every detected file").action(action(initCommand));
+program.command("init-skill").description(
+  "Generate an AI assistant skill from the detected tech stack (uses your configured AI)"
+).option("--target <ai>", `Target AI assistant: ${SKILL_TARGET_IDS.join("|")}`).option("--name <name>", "Name the skill (defaults to the project folder name)").option("--provider <ai>", "Force the AI provider: claude|openai|gemini (default: auto-detect)").option("--model <id>", "Override the API model id for the chosen provider").option("--no-ai", "Skip the AI provider and use the built-in deterministic template").option("--dry-run", "Preview the skill without writing (no AI call)").option("--force", "Overwrite existing skill files").option("--verbose", "Show every detected file").action(action(initSkillCommand));
+program.command("extract").argument("<repo>", "GitHub repo: owner/repo, a github.com URL, or owner/repo#branch").description("Extract a ReplicaX profile from a remote GitHub repository").option("--ref <ref>", "Branch, tag, or commit to fetch (default: the repo default branch)").option("--name <name>", "Name the profile (defaults to the repo name)").option("--out <dir>", "Directory to write the .replicax profile into (default: current dir)").option("--dry-run", "Preview what would be captured without writing").option("--verbose", "Show every detected file").action(action(extractCommand));
 program.command("create").argument("<project-name>", "Directory/name for the new project").description("Create a new project from a profile").option("--profile <path>", "Use a profile from a custom path").option("--skip-install", "Do not run the package manager install step").option("--dry-run", "Preview the output without writing").option("--force", "Overwrite conflicting files without prompting").option("--verbose", "Show every written file").action(action(createCommand));
 program.command("sync").description("Update the profile from the current project state").option("--diff", "Show a detailed list of what changed").option("--force", "Rewrite the profile even if nothing changed").option("--verbose", "Show every detected file").action(action(syncCommand));
 program.command("inspect").description("Display captured configuration and structure").option("--json", "Output as JSON").option("--section <section>", "Inspect one section: profile|tooling|structure|metadata").option("--profile <path>", "Inspect a profile at a custom path").action(action(inspectCommand));