@sublay/cli 7.0.0 → 7.1.0

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { createRequire } from "module";
 import { Command } from "commander";
 
 // src/commands/init.ts
@@ -18,12 +19,15 @@ async function detectProjectType() {
     if (!await fs.pathExists(packageJsonPath)) {
       return "unknown";
     }
-    const packageJson = await fs.readJson(packageJsonPath);
+    const packageJson2 = await fs.readJson(packageJsonPath);
     const deps = {
-      ...packageJson.dependencies,
-      ...packageJson.devDependencies
+      ...packageJson2.dependencies,
+      ...packageJson2.devDependencies
     };
-    if (deps["react-native"] || deps["expo"]) {
+    if (deps["expo"]) {
+      return "expo";
+    }
+    if (deps["react-native"]) {
       return "react-native";
     }
     if (deps["react"]) {
@@ -42,12 +46,12 @@ async function detectTypeScript() {
     }
     const packageJsonPath = path.join(process.cwd(), "package.json");
     if (await fs.pathExists(packageJsonPath)) {
-      const packageJson = await fs.readJson(packageJsonPath);
+      const packageJson2 = await fs.readJson(packageJsonPath);
       const deps = {
-        ...packageJson.dependencies,
-        ...packageJson.devDependencies
+        ...packageJson2.dependencies,
+        ...packageJson2.devDependencies
       };
-      if (deps["typescript"] || deps["@types/react"]) {
+      if (deps["typescript"]) {
         return true;
       }
     }
@@ -62,6 +66,19 @@ async function init() {
   console.log(chalk.bold("\n\u{1F680} Welcome to Sublay CLI\n"));
   const projectType = await detectProjectType();
   const hasTypeScript = await detectTypeScript();
+  if (!process.stdin.isTTY) {
+    console.error(
+      chalk.red(
+        "\n\u274C sublay init requires an interactive terminal \u2014 no TTY detected."
+      )
+    );
+    console.error(
+      chalk.dim(
+        "   Run it directly in a terminal, not through a script or pipe.\n"
+      )
+    );
+    process.exit(1);
+  }
   const answers = await prompts([
     {
       type: "select",
@@ -72,7 +89,7 @@ async function init() {
         { title: "React Native", value: "react-native" },
         { title: "Expo", value: "expo" }
       ],
-      initial: projectType === "react-native" ? 1 : 0
+      initial: projectType === "expo" ? 2 : projectType === "react-native" ? 1 : 0
     },
     {
       type: "select",
@@ -90,22 +107,26 @@ async function init() {
       initial: "src/components"
     }
   ]);
-  if (!answers.platform) {
+  if (!answers.platform || answers.style === void 0 || answers.componentsPath === void 0) {
     console.log(chalk.yellow("\n\u26A0\uFE0F  Setup cancelled"));
     process.exit(0);
   }
+  const componentsPath = answers.componentsPath || "src/components";
   const config = {
     platform: answers.platform,
     style: answers.style || "styled",
     typescript: hasTypeScript,
     paths: {
-      components: answers.componentsPath || "src/components"
+      components: componentsPath
     },
     aliases: {
-      "@/components": `./src/components`
+      "@/components": `./${componentsPath}`
     }
   };
   const configPath = path2.join(process.cwd(), "sublay.json");
+  if (await fs2.pathExists(configPath)) {
+    console.log(chalk.yellow("\n\u26A0\uFE0F  Overwriting existing configuration: sublay.json"));
+  }
   await fs2.writeJson(configPath, config, { spaces: 2 });
   console.log(chalk.green("\n\u2705 Configuration saved to sublay.json"));
   console.log(chalk.bold("\n\u{1F389} Sublay CLI initialized successfully!\n"));
@@ -129,92 +150,316 @@ import { fileURLToPath } from "url";
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = path3.dirname(__filename);
 var LOCAL_REGISTRY_PATH = path3.resolve(__dirname, "..", "..", "..", "registry");
-async function fetchRegistry(componentName, config) {
+var REMOTE_REGISTRY_BASE = "https://raw.githubusercontent.com/sublay-io/monorepo/main/registry";
+var DEFAULT_REGISTRY_REF = "main";
+var LOCAL_PATH_ENV = "SUBLAY_REGISTRY_LOCAL_PATH";
+var REMOTE_BASE_ENV = "SUBLAY_REGISTRY_BASE_URL";
+var RegistryError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RegistryError";
+  }
+};
+function validateRef(ref) {
+  if (typeof ref !== "string" || ref.length === 0) {
+    return "A ref cannot be empty.";
+  }
+  if (!/^[A-Za-z0-9._\-/]+$/.test(ref)) {
+    return `Invalid ref "${ref}": a ref may only contain letters, digits, ".", "_", "-" and "/".`;
+  }
+  const segments = ref.split("/");
+  if (segments.some((segment) => segment === "..")) {
+    return `Invalid ref "${ref}": a ref cannot contain a ".." segment.`;
+  }
+  if (segments.some((segment) => segment.length === 0)) {
+    return `Invalid ref "${ref}": a ref cannot start or end with "/" or contain "//".`;
+  }
+  return null;
+}
+function validateComponentName(name) {
+  if (typeof name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+    return `Invalid component name "${name}": a component name may only contain lowercase letters, digits and hyphens (for example "comments-threaded").`;
+  }
+  return null;
+}
+function getRemoteRegistryBase(ref = DEFAULT_REGISTRY_REF, env = process.env) {
+  const base = (env[REMOTE_BASE_ENV] || REMOTE_REGISTRY_BASE).replace(/\/+$/, "");
+  const suffix = `/${DEFAULT_REGISTRY_REF}/registry`;
+  if (!base.endsWith(suffix)) {
+    throw new RegistryError(
+      `Registry base URL "${base}" must end with "${suffix}".`
+    );
+  }
+  if (ref === DEFAULT_REGISTRY_REF) {
+    return base;
+  }
+  return `${base.slice(0, -suffix.length)}/${ref}/registry`;
+}
+function resolveRegistrySource(ref, env = process.env) {
+  if (ref === void 0) {
+    return {
+      ref: DEFAULT_REGISTRY_REF,
+      explicitRef: false,
+      localRoot: env[LOCAL_PATH_ENV] || LOCAL_REGISTRY_PATH,
+      remoteBase: getRemoteRegistryBase(DEFAULT_REGISTRY_REF, env)
+    };
+  }
+  const problem = validateRef(ref);
+  if (problem) {
+    throw new RegistryError(problem);
+  }
+  return {
+    ref,
+    explicitRef: true,
+    localRoot: null,
+    remoteBase: getRemoteRegistryBase(ref, env)
+  };
+}
+function getRegistryPlatform(config) {
+  return config.platform === "expo" ? "react-native" : config.platform;
+}
+function getComponentLocation(componentName, config) {
+  const problem = validateComponentName(componentName);
+  if (problem) {
+    throw new RegistryError(problem);
+  }
+  return `${getRegistryPlatform(config)}/${componentName}/${config.style}`;
+}
+function getRemoteUrl(source, registryPath) {
+  return `${source.remoteBase}/${registryPath}`;
+}
+async function readRegistryPath(source, registryPath) {
+  if (source.localRoot) {
+    const localPath = path3.join(source.localRoot, ...registryPath.split("/"));
+    if (await fs3.pathExists(localPath)) {
+      return { ok: true, content: await fs3.readFile(localPath, "utf-8") };
+    }
+    if (source.localOnly) {
+      return {
+        ok: false,
+        url: localPath,
+        status: 404,
+        reason: "not found in the local registry"
+      };
+    }
+  }
+  const url = getRemoteUrl(source, registryPath);
   try {
-    const registryPlatform = config.platform === "expo" ? "react-native" : config.platform;
-    const registryPath = path3.join(
-      LOCAL_REGISTRY_PATH,
-      registryPlatform,
-      componentName,
-      config.style,
-      "registry.json"
-    );
-    const localExists = await fs3.pathExists(registryPath);
-    if (localExists) {
-      return await fs3.readJson(registryPath);
-    }
-    const url = `https://raw.githubusercontent.com/sublay-io/cli/main/registry/${registryPlatform}/${componentName}/${config.style}/registry.json`;
-    try {
-      const response = await fetch(url);
-      if (!response.ok) {
-        if (response.status === 404) {
-          console.error(`Component "${componentName}" with style "${config.style}" not found in registry.`);
-        } else {
-          console.error(`Failed to fetch registry from ${url}: ${response.status} ${response.statusText}`);
-        }
-        return null;
-      }
-      return await response.json();
-    } catch (fetchError) {
-      console.error(`Error fetching from GitHub (${url}):`, fetchError);
-      return null;
+    const response = await fetch(url);
+    if (!response.ok) {
+      return {
+        ok: false,
+        url,
+        status: response.status,
+        reason: `${response.status} ${response.statusText}`.trim()
+      };
     }
+    return { ok: true, content: await response.text() };
   } catch (error) {
-    console.error("Error fetching registry:", error);
-    return null;
+    return {
+      ok: false,
+      url,
+      reason: error instanceof Error ? error.message : String(error)
+    };
   }
 }
-async function fetchFile(registryUrl, filePath) {
-  try {
-    const urlParts = registryUrl.split("/");
-    const style = urlParts[urlParts.length - 1];
-    const componentName = urlParts[urlParts.length - 2];
-    const platform = urlParts[urlParts.length - 3];
-    const localPath = path3.join(
-      LOCAL_REGISTRY_PATH,
-      platform,
-      componentName,
-      style,
-      filePath
-    );
-    const localExists = await fs3.pathExists(localPath);
-    if (localExists) {
-      return await fs3.readFile(localPath, "utf-8");
-    }
-    const fileUrl = `${registryUrl}/${filePath}`;
+async function pinRegistrySource(source, componentName, config) {
+  if (!source.localRoot) {
+    return source;
+  }
+  const location = getComponentLocation(componentName, config);
+  const manifestPath = path3.join(
+    source.localRoot,
+    ...location.split("/"),
+    "registry.json"
+  );
+  return await fs3.pathExists(manifestPath) ? { ...source, localOnly: true } : { ...source, localRoot: null };
+}
+async function fetchRegistry(componentName, config, source) {
+  const location = getComponentLocation(componentName, config);
+  const result = await readRegistryPath(source, `${location}/registry.json`);
+  if (result.ok) {
     try {
-      const response = await fetch(fileUrl);
-      if (!response.ok) {
-        console.error(`Failed to fetch file from ${fileUrl}: ${response.status} ${response.statusText}`);
-        return null;
-      }
-      return await response.text();
-    } catch (fetchError) {
-      console.error(`Error fetching file from GitHub (${fileUrl}):`, fetchError);
-      return null;
+      return JSON.parse(result.content);
+    } catch {
+      throw new RegistryError(
+        `The registry manifest for "${componentName}" (${location}/registry.json) is not valid JSON.`
+      );
     }
-  } catch (error) {
-    console.error(`Error fetching file ${filePath}:`, error);
-    return null;
   }
+  if (result.status !== 404) {
+    throw new RegistryError(
+      `Failed to fetch registry from ${result.url}: ${result.reason}`
+    );
+  }
+  if (!source.explicitRef) {
+    throw new RegistryError(
+      `Component "${componentName}" with style "${config.style}" not found in registry.`
+    );
+  }
+  const probe = await readRegistryPath(source, "package.json");
+  if (probe.ok) {
+    throw new RegistryError(
+      `Component "${componentName}" with style "${config.style}" not found on branch "${source.ref}".`
+    );
+  }
+  if (probe.status === 404) {
+    throw new RegistryError(
+      `Branch "${source.ref}" not found: no registry is served from that branch.`
+    );
+  }
+  throw new RegistryError(
+    `Failed to fetch registry from ${probe.url}: ${probe.reason}`
+  );
+}
+async function fetchFile(source, location, filePath) {
+  const result = await readRegistryPath(source, `${location}/${filePath}`);
+  if (!result.ok) {
+    throw new RegistryError(
+      `Could not fetch ${filePath} from ${result.url}: ${result.reason}`
+    );
+  }
+  return result.content;
+}
+function getSharedManifestPath(platform) {
+  return `shared/${platform}/shared.json`;
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function parseSharedManifest(raw, label) {
+  const invalid = (detail) => new RegistryError(`The shared manifest ${label} is malformed: ${detail}.`);
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw invalid("it must be an object");
+  }
+  const { platform, pieces } = raw;
+  if (typeof pieces !== "object" || pieces === null || Array.isArray(pieces)) {
+    throw invalid('"pieces" must be an object keyed by piece name');
+  }
+  const parsed = {};
+  for (const [name, value] of Object.entries(pieces)) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw invalid(`piece "${name}" must be an object`);
+    }
+    const { files, requires = [], dependencies = [] } = value;
+    if (!isStringArray(files) || files.length === 0) {
+      throw invalid(`piece "${name}" must list at least one file`);
+    }
+    const outside = files.find(
+      (file) => !/^[A-Za-z0-9_][A-Za-z0-9._/-]*$/.test(file) || file.split("/").includes("..")
+    );
+    if (outside !== void 0) {
+      throw invalid(
+        `piece "${name}" lists "${outside}", which is not a path inside the shared folder`
+      );
+    }
+    if (!isStringArray(requires)) {
+      throw invalid(`piece "${name}" has a "requires" that is not a list of piece names`);
+    }
+    if (!isStringArray(dependencies)) {
+      throw invalid(`piece "${name}" has a "dependencies" that is not a list of packages`);
+    }
+    parsed[name] = { files, requires, dependencies };
+  }
+  return {
+    platform: typeof platform === "string" ? platform : "",
+    pieces: parsed
+  };
+}
+async function fetchSharedManifest(platform, source) {
+  const manifestPath = getSharedManifestPath(platform);
+  const result = await readRegistryPath(source, manifestPath);
+  if (!result.ok) {
+    throw new RegistryError(
+      `Could not fetch the shared manifest ${manifestPath} from ${result.url}: ${result.reason}`
+    );
+  }
+  let raw;
+  try {
+    raw = JSON.parse(result.content);
+  } catch {
+    throw new RegistryError(`The shared manifest ${manifestPath} is not valid JSON.`);
+  }
+  return parseSharedManifest(raw, manifestPath);
+}
+function resolveSharedPieces(names, manifest, labels) {
+  const resolved = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (name, requiredBy) => {
+    if (visited.has(name)) {
+      return;
+    }
+    if (!Object.prototype.hasOwnProperty.call(manifest.pieces, name)) {
+      throw new RegistryError(
+        requiredBy === null ? `Shared piece "${name}", listed in ${labels.componentManifest}, is not defined in ${labels.sharedManifest}.` : `Shared piece "${requiredBy}" requires "${name}", which is not defined in ${labels.sharedManifest}.`
+      );
+    }
+    visited.add(name);
+    const piece = manifest.pieces[name];
+    for (const requirement of piece.requires) {
+      visit(requirement, name);
+    }
+    resolved.push({ name, ...piece });
+  };
+  for (const name of names) {
+    visit(name, null);
+  }
+  return resolved;
+}
+async function fetchSharedFile(source, platform, filePath) {
+  return fetchFile(source, `shared/${platform}`, filePath);
 }
 
 // src/utils/transform.ts
-function transformImports(content, config) {
+var SHARED_ALIAS_IMPORT = /\b((?:from|import|require)\s*\(?\s*)(['"])~shared\/([^'"/]+)\/([^'"]+)\2/g;
+function findSharedAliasImports(content) {
+  return Array.from(content.matchAll(SHARED_ALIAS_IMPORT), (match) => ({
+    platform: match[3],
+    piece: match[4]
+  }));
+}
+function transformImports(content, config, options = {}) {
   let transformed = content;
-  transformed = transformed.replace(/from\s+['"]\.\.\/files\//g, 'from "../components/');
-  transformed = transformed.replace(/import\s+['"]\.\.\/files\//g, 'import "../components/');
-  transformed = transformed.replace(/import\(['"]\.\.\/files\//g, 'import("../components/');
+  const { installedPath } = options;
+  if (installedPath !== void 0) {
+    const fromDir = posixDirname(installedPath);
+    transformed = transformed.replace(
+      SHARED_ALIAS_IMPORT,
+      (_match, lead, quote, _platform, piece) => `${lead}${quote}${relativeImportPath(fromDir, `shared/${piece}`)}${quote}`
+    );
+  }
+  transformed = transformed.replace(/from(\s+)(['"])\.\.\/files\//g, "from$1$2../components/");
+  transformed = transformed.replace(/import(\s+)(['"])\.\.\/files\//g, "import$1$2../components/");
+  transformed = transformed.replace(/import\((['"])\.\.\/files\//g, "import($1../components/");
   if (config.platform === "expo") {
     transformed = transformed.replace(
       /from\s+["']@sublay\/react-native["']/g,
       'from "@sublay/expo"'
     );
+    transformed = transformed.replace(
+      /^(\s*\*\s+-\s+)@sublay\/react-native(?=\s|$)/gm,
+      "$1@sublay/expo"
+    );
   }
   if (config.aliases["@/components"]) {
   }
   return transformed;
 }
+function posixDirname(filePath) {
+  const index = filePath.lastIndexOf("/");
+  return index === -1 ? "" : filePath.slice(0, index);
+}
+function relativeImportPath(fromDir, target) {
+  const from = fromDir.split("/").filter(Boolean);
+  const to = target.split("/").filter(Boolean);
+  let common = 0;
+  while (common < from.length && common < to.length - 1 && from[common] === to[common]) {
+    common++;
+  }
+  const up = from.length - common;
+  const down = to.slice(common).join("/");
+  return up === 0 ? `./${down}` : `${"../".repeat(up)}${down}`;
+}
 
 // src/utils/dependencies.ts
 import fs4 from "fs-extra";
@@ -222,6 +467,7 @@ import path4 from "path";
 import chalk2 from "chalk";
 import prompts2 from "prompts";
 import { execa } from "execa";
+import semver from "semver";
 async function installDependencies(deps) {
   try {
     console.log(chalk2.blue(`
@@ -251,6 +497,62 @@ async function detectPackageManager() {
   }
   return "npm";
 }
+function parseDependencyName(dep) {
+  const parts = dep.split("@").filter(Boolean);
+  if (dep.startsWith("@")) {
+    return `@${parts[0]}`;
+  }
+  return parts[0];
+}
+function parseDependencySpec(dep) {
+  const name = parseDependencyName(dep);
+  const rest = dep.slice(name.length);
+  return { name, range: rest.startsWith("@") ? rest.slice(1) : "" };
+}
+function mergeDependencies(componentDependencies, sharedDependencies) {
+  const merged = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const dep of [...componentDependencies, ...sharedDependencies]) {
+    const name = parseDependencyName(dep);
+    if (seen.has(name)) {
+      continue;
+    }
+    seen.add(name);
+    merged.push(dep);
+  }
+  return merged;
+}
+function isDeclaredRangeBelow(declared, required) {
+  const options = { includePrerelease: true };
+  if (typeof declared !== "string" || !required || !semver.validRange(declared, options) || !semver.validRange(required, options)) {
+    return false;
+  }
+  if (semver.intersects(declared, required, options)) {
+    return false;
+  }
+  const declaredMin = semver.minVersion(declared);
+  const requiredMin = semver.minVersion(required);
+  if (!declaredMin || !requiredMin) {
+    return false;
+  }
+  return semver.lt(declaredMin, requiredMin);
+}
+function findDependencyStatus(dependencies, declaredDependencies) {
+  const missing = [];
+  const upgrades = [];
+  for (const spec of dependencies) {
+    const { name, range } = parseDependencySpec(spec);
+    const declared = declaredDependencies[name];
+    if (!declared) {
+      missing.push(spec);
+      continue;
+    }
+    if (name.startsWith("@sublay/") && typeof declared === "string" && isDeclaredRangeBelow(declared, range)) {
+      upgrades.push({ spec, declared });
+    }
+  }
+  return { missing, upgrades };
+}
 async function checkComponentDependencies(dependencies) {
   try {
     const packageJsonPath = path4.join(process.cwd(), "package.json");
@@ -258,44 +560,44 @@ async function checkComponentDependencies(dependencies) {
       console.log(chalk2.yellow("\n\u26A0\uFE0F  No package.json found"));
       return;
     }
-    const packageJson = await fs4.readJson(packageJsonPath);
+    const packageJson2 = await fs4.readJson(packageJsonPath);
     const allDeps = {
-      ...packageJson.dependencies,
-      ...packageJson.devDependencies
+      ...packageJson2.dependencies,
+      ...packageJson2.devDependencies
     };
-    const requiredDeps = dependencies.map((dep) => {
-      const parts = dep.split("@").filter(Boolean);
-      if (dep.startsWith("@")) {
-        return `@${parts[0]}`;
-      } else {
-        return parts[0];
-      }
-    });
-    const missingDeps = requiredDeps.filter((dep) => !allDeps[dep]);
-    if (missingDeps.length === 0) {
+    const { missing, upgrades } = findDependencyStatus(dependencies, allDeps);
+    if (missing.length === 0 && upgrades.length === 0) {
       console.log(chalk2.green("\n\u2705 All required dependencies are installed"));
       return;
     }
-    console.log(chalk2.yellow("\n\u26A0\uFE0F  Missing required dependencies:"));
-    const missingDepsWithVersions = dependencies.filter((dep) => {
-      const parts = dep.split("@").filter(Boolean);
-      const pkgName = dep.startsWith("@") ? `@${parts[0]}` : parts[0];
-      return missingDeps.includes(pkgName);
-    });
-    missingDepsWithVersions.forEach((dep) => console.log(chalk2.dim(`  - ${dep}`)));
-    const { install } = await prompts2({
-      type: "confirm",
-      name: "install",
-      message: "Would you like to install them now?",
-      initial: true
-    });
+    if (missing.length > 0) {
+      console.log(chalk2.yellow("\n\u26A0\uFE0F  Missing required dependencies:"));
+      missing.forEach((dep) => console.log(chalk2.dim(`  - ${dep}`)));
+    }
+    if (upgrades.length > 0) {
+      console.log(chalk2.yellow("\n\u26A0\uFE0F  Dependencies that need an upgrade:"));
+      upgrades.forEach(
+        ({ spec, declared }) => console.log(chalk2.dim(`  - ${spec} (your project has ${declared})`))
+      );
+    }
+    const toInstall = [...missing, ...upgrades.map((upgrade) => upgrade.spec)];
+    let install = false;
+    if (process.stdin.isTTY) {
+      const answer = await prompts2({
+        type: "confirm",
+        name: "install",
+        message: "Would you like to install them now?",
+        initial: true
+      });
+      install = Boolean(answer.install);
+    }
     if (install) {
-      await installDependencies(missingDepsWithVersions);
+      await installDependencies(toInstall);
     } else {
       console.log(chalk2.dim("\nYou can install them later with:"));
       const packageManager = await detectPackageManager();
       const installCmd = packageManager === "npm" ? "npm install" : packageManager === "yarn" ? "yarn add" : "pnpm add";
-      console.log(chalk2.dim(`  ${installCmd} ${missingDepsWithVersions.join(" ")}
+      console.log(chalk2.dim(`  ${installCmd} ${toInstall.join(" ")}
 `));
     }
   } catch (error) {
@@ -332,7 +634,7 @@ async function stripTypes(code, filePath) {
       retainLines: true
       // Try to keep line numbers similar
     });
-    if (!result || !result.code) {
+    if (!result || typeof result.code !== "string") {
       throw new Error("Babel transformation returned no code");
     }
     return result.code;
@@ -349,49 +651,124 @@ function convertFileExtension(filePath) {
 }
 
 // src/commands/add.ts
-async function add(componentName) {
+var STRINGS_FILE = "utils/strings.ts";
+var DEFAULT_LANGUAGE = "en";
+var FETCH_CONCURRENCY = 8;
+async function add(componentName, options = {}) {
   const spinner = ora("Initializing...").start();
   try {
+    let source;
+    try {
+      const nameProblem = validateComponentName(componentName);
+      if (nameProblem) {
+        throw new RegistryError(nameProblem);
+      }
+      source = resolveRegistrySource(options.ref);
+    } catch (error) {
+      if (error instanceof RegistryError) {
+        spinner.fail(error.message);
+        process.exit(1);
+      }
+      throw error;
+    }
     const configPath = path5.join(process.cwd(), "sublay.json");
     if (!await fs5.pathExists(configPath)) {
       spinner.fail("No sublay.json found");
       console.log(chalk3.yellow("\n\u26A0\uFE0F  Please run: npx @sublay/cli init"));
       process.exit(1);
     }
-    const config = await fs5.readJson(configPath);
-    spinner.text = `Fetching ${componentName}...`;
-    const registry = await fetchRegistry(componentName, config);
-    if (!registry) {
-      spinner.fail(`Component "${componentName}" not found`);
+    let rawConfig;
+    try {
+      rawConfig = await fs5.readJson(configPath);
+    } catch {
+      rawConfig = null;
+    }
+    if (!isValidConfig(rawConfig)) {
+      spinner.fail("sublay.json is malformed");
+      console.error(
+        chalk3.red(
+          "\n\u274C sublay.json is missing or malformed \u2014 delete it and run `npx @sublay/cli init` again."
+        )
+      );
       process.exit(1);
     }
-    if (config.platform === "expo") {
-      registry.dependencies = registry.dependencies.map(
-        (dep) => dep.startsWith("@sublay/react-native") ? dep.replace("@sublay/react-native", "@sublay/expo") : dep
+    const config = rawConfig;
+    const componentDir = path5.join(
+      process.cwd(),
+      config.paths.components,
+      componentName
+    );
+    if (await fs5.pathExists(componentDir)) {
+      spinner.stop();
+      console.log(
+        chalk3.yellow(`\u26A0\uFE0F  Overwriting existing component: ${componentName}`)
       );
+      spinner.start(`Fetching ${componentName}...`);
     }
-    spinner.text = "Downloading files...";
-    let filesInstalled = 0;
-    for (const file of registry.files) {
-      if (shouldExcludeFile(file.path)) {
-        continue;
-      }
-      const fileContent = await fetchFile(registry.registryUrl, file.path);
-      if (!fileContent) {
-        console.log(chalk3.yellow(`
-\u26A0\uFE0F  Could not fetch ${file.path}`));
-        continue;
-      }
-      let transformed = transformImports(fileContent, config);
-      let finalFilePath = file.path;
-      if (!config.typescript && (file.path.endsWith(".ts") || file.path.endsWith(".tsx"))) {
-        transformed = await stripTypes(transformed, file.path);
-        finalFilePath = convertFileExtension(file.path);
+    spinner.text = `Fetching ${componentName}...`;
+    source = await pinRegistrySource(source, componentName, config);
+    const registry = await fetchRegistry(componentName, config, source);
+    registry.dependencies = registry.dependencies.map(
+      (dep) => renameForPlatform(dep, config)
+    );
+    const languageFile = resolveLanguageFile(registry, options.lang, componentName);
+    const platform = getRegistryPlatform(config);
+    const location = getComponentLocation(componentName, config);
+    const componentManifestLabel = `${location}/registry.json`;
+    const sharedManifestLabel = getSharedManifestPath(platform);
+    const sharedNames = readSharedNames(registry, componentManifestLabel);
+    let sharedPieces = [];
+    if (sharedNames.length > 0) {
+      const sharedManifest = await fetchSharedManifest(platform, source);
+      sharedPieces = resolveSharedPieces(sharedNames, sharedManifest, {
+        componentManifest: componentManifestLabel,
+        sharedManifest: sharedManifestLabel
+      });
+    }
+    const dependencies = mergeDependencies(
+      registry.dependencies,
+      sharedPieces.flatMap((piece) => piece.dependencies).map((dep) => renameForPlatform(dep, config))
+    );
+    spinner.text = sharedPieces.length > 0 ? `Downloading files and ${sharedPieces.length} shared piece(s)...` : "Downloading files...";
+    const installedPieces = new Set(sharedPieces.map((piece) => piece.name));
+    const downloads = [
+      ...registry.files.map((file) => ({ registryPath: file.path, shared: false })),
+      ...sharedPieces.flatMap(
+        (piece) => piece.files.map((file) => ({ registryPath: file, shared: true }))
+      )
+    ].filter(
+      // Skip development files
+      (download) => !shouldExcludeFile(download.registryPath)
+    );
+    const pendingFiles = await mapWithConcurrency(
+      downloads,
+      FETCH_CONCURRENCY,
+      async ({ registryPath, shared }) => {
+        const fileContent = shared ? await fetchSharedFile(source, platform, registryPath) : await fetchFile(
+          source,
+          location,
+          languageFile && registryPath === STRINGS_FILE ? languageFile : registryPath
+        );
+        for (const used of findSharedAliasImports(fileContent)) {
+          if (used.platform !== platform || !installedPieces.has(used.piece)) {
+            throw new RegistryError(
+              `${registryPath} imports the shared piece "${used.platform}/${used.piece}", which ${componentManifestLabel} does not list under "shared" for ${sharedManifestLabel}.`
+            );
+          }
+        }
+        return prepareFile(
+          shared ? `shared/${registryPath}` : registryPath,
+          fileContent,
+          config,
+          componentName
+        );
       }
-      const targetPath = getTargetPath(finalFilePath, config, componentName);
-      const fullPath = path5.join(process.cwd(), targetPath);
+    );
+    let filesInstalled = 0;
+    for (const file of pendingFiles) {
+      const fullPath = path5.join(process.cwd(), file.targetPath);
       await fs5.ensureDir(path5.dirname(fullPath));
-      await fs5.writeFile(fullPath, transformed, "utf-8");
+      await fs5.writeFile(fullPath, file.content, "utf-8");
       filesInstalled++;
     }
     spinner.text = "Creating index file...";
@@ -411,31 +788,184 @@ async function add(componentName) {
         )}`
       )
     );
-    await checkComponentDependencies(registry.dependencies);
+    if (sharedPieces.length > 0) {
+      console.log(
+        chalk3.dim(
+          `\u{1F9E9} Shared pieces in ${path5.join(
+            config.paths.components,
+            componentName,
+            "shared"
+          )}: ${sharedPieces.map((piece) => piece.name).join(", ")}`
+        )
+      );
+    }
+    await checkComponentDependencies(dependencies);
     const componentInfo = getComponentInfo(registry);
-    const relativeImportPath = path5.relative(
+    const relativeImportPath2 = path5.relative(
       process.cwd(),
       path5.join(config.paths.components, componentName)
     );
     console.log(chalk3.bold("\n\u{1F4D6} Usage:"));
     console.log(
       chalk3.dim(
-        `  import { ${componentInfo.mainComponent} } from './${relativeImportPath}';`
-      )
-    );
-    console.log(chalk3.dim(`  // With types:`));
-    console.log(
-      chalk3.dim(
-        `  import { ${componentInfo.mainComponent}, type ${componentInfo.typeExport} } from './${relativeImportPath}';`
+        `  import { ${componentInfo.mainComponent} } from './${relativeImportPath2}';`
       )
     );
+    if (componentInfo.typeExport) {
+      console.log(chalk3.dim(`  // With types:`));
+      console.log(
+        chalk3.dim(
+          `  import { ${componentInfo.mainComponent}, type ${componentInfo.typeExport} } from './${relativeImportPath2}';`
+        )
+      );
+    }
+    printAppSetupNotes(dependencies);
     console.log();
   } catch (error) {
+    if (error instanceof RegistryError) {
+      spinner.fail(error.message);
+      console.error(chalk3.dim("\nNothing was written to your project."));
+      process.exit(1);
+    }
     spinner.fail("Failed to add component");
     console.error(chalk3.red("\n\u274C Error:"), error);
     process.exit(1);
   }
 }
+async function prepareFile(filePath, fileContent, config, componentName) {
+  const componentDir = path5.join(config.paths.components, componentName);
+  const needsTypeStrip = !config.typescript && (filePath.endsWith(".ts") || filePath.endsWith(".tsx"));
+  const finalFilePath = needsTypeStrip ? convertFileExtension(filePath) : filePath;
+  const targetPath = getTargetPath(finalFilePath, config, componentName);
+  const installedPath = path5.relative(componentDir, targetPath).split(path5.sep).join("/");
+  if (installedPath === ".." || installedPath.startsWith("../") || path5.isAbsolute(installedPath)) {
+    throw new RegistryError(
+      `${filePath} would be installed outside ${componentDir}; refusing to write it.`
+    );
+  }
+  let transformed = transformImports(fileContent, config, { installedPath });
+  if (needsTypeStrip) {
+    transformed = await stripTypes(transformed, filePath);
+  }
+  return { targetPath, content: transformed };
+}
+function renameForPlatform(dep, config) {
+  return config.platform === "expo" && dep.startsWith("@sublay/react-native") ? dep.replace("@sublay/react-native", "@sublay/expo") : dep;
+}
+function resolveLanguageFile(registry, lang, componentName) {
+  if (lang === void 0 || lang === DEFAULT_LANGUAGE) {
+    return null;
+  }
+  const languages = registry.languages && typeof registry.languages === "object" ? registry.languages : {};
+  const available = [DEFAULT_LANGUAGE, ...Object.keys(languages)].join(", ");
+  const languageFile = Object.prototype.hasOwnProperty.call(languages, lang) ? languages[lang] : void 0;
+  if (languageFile === void 0) {
+    throw new RegistryError(
+      `${componentName} is not available in "${lang}". Available languages: ${available}.`
+    );
+  }
+  if (typeof languageFile !== "string" || !/^[A-Za-z0-9_][A-Za-z0-9._/-]*$/.test(languageFile) || languageFile.split("/").includes("..")) {
+    throw new RegistryError(
+      `The "${lang}" entry under "languages" for ${componentName} is not a usable file path.`
+    );
+  }
+  if (!registry.files.some((file) => file.path === STRINGS_FILE)) {
+    throw new RegistryError(
+      `${componentName} lists languages but has no ${STRINGS_FILE} to put them in.`
+    );
+  }
+  return languageFile;
+}
+function readSharedNames(registry, manifestLabel) {
+  const { shared } = registry;
+  if (shared === void 0 || shared === null) {
+    return [];
+  }
+  if (!Array.isArray(shared) || shared.some((name) => typeof name !== "string")) {
+    throw new RegistryError(
+      `"shared" in ${manifestLabel} must be a list of shared piece names.`
+    );
+  }
+  return shared;
+}
+async function mapWithConcurrency(items, limit, task) {
+  const results = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await task(items[index]);
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, worker)
+  );
+  return results;
+}
+function isValidConfig(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const config = value;
+  if (config.platform !== "react" && config.platform !== "react-native" && config.platform !== "expo") {
+    return false;
+  }
+  if (config.style !== "styled" && config.style !== "tailwind") {
+    return false;
+  }
+  if (typeof config.typescript !== "boolean") {
+    return false;
+  }
+  const paths = config.paths;
+  if (typeof paths !== "object" || paths === null) {
+    return false;
+  }
+  if (typeof paths.components !== "string") {
+    return false;
+  }
+  const aliases = config.aliases;
+  if (typeof aliases !== "object" || aliases === null) {
+    return false;
+  }
+  if (typeof aliases["@/components"] !== "string") {
+    return false;
+  }
+  return true;
+}
+function printAppSetupNotes(dependencies) {
+  const deps = dependencies.map((dep) => dep.toLowerCase());
+  const usesNativeWind = deps.some((dep) => dep.includes("nativewind"));
+  const usesBottomSheet = deps.some((dep) => dep.includes("@gorhom/bottom-sheet"));
+  if (!usesNativeWind && !usesBottomSheet) {
+    return;
+  }
+  console.log(chalk3.bold("\n\u{1F527} App-level setup required:"));
+  if (usesNativeWind) {
+    console.log(
+      chalk3.yellow("  \u2022 NativeWind: these files use `className` props.")
+    );
+    console.log(
+      chalk3.dim(
+        "    Wire up babel.config.js, metro.config.js, and add this component"
+      )
+    );
+    console.log(
+      chalk3.dim("    directory to your Tailwind config's `content` globs.")
+    );
+  }
+  if (usesBottomSheet) {
+    console.log(
+      chalk3.yellow("  \u2022 Bottom sheets need a gesture-handler root.")
+    );
+    console.log(
+      chalk3.dim(
+        "    Wrap your app root in <GestureHandlerRootView style={{ flex: 1 }}>"
+      )
+    );
+    console.log(chalk3.dim("    from 'react-native-gesture-handler'."));
+  }
+  console.log(chalk3.dim("\n  Setup guides: https://docs.sublay.io"));
+}
 function getTargetPath(filePath, config, componentName) {
   const componentDir = path5.join(config.paths.components, componentName);
   if (filePath.startsWith("hooks/")) {
@@ -447,6 +977,9 @@ function getTargetPath(filePath, config, componentName) {
   if (filePath.startsWith("context/")) {
     return path5.join(componentDir, "context", path5.basename(filePath));
   }
+  if (filePath.startsWith("shared/")) {
+    return path5.join(componentDir, "shared", filePath.substring(7));
+  }
   if (filePath.startsWith("files/")) {
     const normalizedPath = filePath.substring(6);
     return path5.join(componentDir, "components", normalizedPath);
@@ -499,8 +1032,18 @@ function shouldExcludeFile(filePath) {
 }
 
 // src/index.ts
+var require2 = createRequire(import.meta.url);
+var packageJson = require2("../package.json");
 var program = new Command();
-program.name("sublay").description("CLI for installing Sublay UI components").version("0.1.0");
+program.name("sublay").description("CLI for installing Sublay UI components").version(packageJson.version);
 program.command("init").description("Initialize Sublay configuration in your project").action(init);
-program.command("add <component>").description("Add a component to your project").action(add);
+program.command("add <component>").description("Add a component to your project").option(
+  "--ref <branch>",
+  "read the component from this branch of the registry instead of the default"
+).option(
+  "--lang <code>",
+  "install the component's text in this language instead of English (for example: he)"
+).action(
+  (component, options) => add(component, { ref: options.ref, lang: options.lang })
+);
 program.parse();