@sublay/cli 7.0.1 → 7.2.0

package/README.md

@@ -51,18 +51,27 @@ Sublay ships these layers as **pre-modeled bundles** that attach to one shared e
 
 ## Bundles you can install
 
-- **Comments & Threads** — threaded discussions with mentions, replies, sorting
-- **Reactions & Votes** — upvotes, downvotes, multi-emoji reactions
-- **Spaces & Communities** — groups, sub-forums, membership
-- **Notifications** — in-app notification fan-out with optional webhook delivery
-- **Feeds & Discovery** — hot / top / new / controversial, filtered by tag, geography, timeframe, or follow graph
-- **Real-Time Chat** — direct messages and group threads
-- **Follows & Connections** — one-way follows, mutual connections
-- **Files & Storage** — file blob storage with managed upload URLs
-- **AI-Powered Search** — semantic search across your entity tree
-- **Moderation** — report queues and content-removal workflows
-
-Every bundle attaches to the same model. No mismatches, no extra databases. One schema for everything.
+Every project always includes the **`core`** bundle — users, authentication, and OAuth identity — installed automatically and it can't be removed. On top of that, install only what your product needs:
+
+- **Entities** (`entities`) — the base content unit for anything your users create (posts, articles, listings), with views, drafts, and publishing
+- **Comments** (`comments`) — threaded comments on entities · requires `entities`
+- **Reactions** (`reactions`) — emoji reactions on entities and comments
+- **Storage** (`files-images`) — file and image uploads, including user avatars and banners
+- **Follows** (`follows`) — one-way follow relationships
+- **Connections** (`connections`) — bidirectional, friend-style connection requests
+- **Spaces** (`spaces`) — hierarchical community spaces with membership, roles, and rules
+- **Workspaces** (`workspaces`) — self-nesting SaaS/team workspaces with invitations and per-member authority
+- **Chat** (`chat`) — real-time 1:1 and group conversations with message reactions
+- **Collections** (`collections`) — user-owned bookmarking and folders for saving entities · requires `entities`
+- **Events** (`events`) — online, physical, or hybrid events with RSVP tracking, capacity limits, hosts, and invites
+- **Moderation** (`moderation`) — reports, report resolution, user blocking, and account suspensions
+- **App Notifications** (`notifications`) — in-app notification fan-out
+- **Push Notifications** (`push`) — native push delivery to iOS, Android, and Web
+- **Reputation** (`reputation`) — per-space reputation buckets, a maintained overall total per user, and reputation grants
+- **Semantic Search & AI** (`ai-search`) — content embeddings, semantic search, and an AI-answer endpoint
+- **Interest Matching** (`interest-matching`) — activity-derived interest facets for matching users by what they engage with · requires `ai-search`
+
+Every bundle attaches to the same project schema — no mismatches, no extra databases. Install, remove, or add bundles at any time from the dashboard's Database page; removing a bundle drops its tables (and clears references to it from other bundles) for good.
 
 ## How it works
 
@@ -84,7 +93,7 @@ The dashboard at [dash.sublay.io](https://dash.sublay.io) is a database/backend
 
 ## The Sublay SDK family
 
-- [`@sublay/core`](https://www.npmjs.com/package/@sublay/core) — platform-agnostic hooks and utilities
+- [`@sublay/core`](https://www.npmjs.com/package/@sublay/core) — hooks and utilities shared across the React, React Native, and Expo SDKs
 - [`@sublay/react-js`](https://www.npmjs.com/package/@sublay/react-js) — React (web)
 - [`@sublay/react-native`](https://www.npmjs.com/package/@sublay/react-native) — React Native
 - [`@sublay/expo`](https://www.npmjs.com/package/@sublay/expo) — Expo with SecureStore token storage

package/dist/index.js

@@ -60,6 +60,34 @@ async function detectTypeScript() {
     return false;
   }
 }
+async function detectFramework(platform) {
+  if (platform !== "react") {
+    return platform;
+  }
+  try {
+    const packageJsonPath = path.join(process.cwd(), "package.json");
+    if (!await fs.pathExists(packageJsonPath)) {
+      return "other";
+    }
+    const packageJson2 = await fs.readJson(packageJsonPath);
+    const deps = {
+      ...packageJson2.dependencies,
+      ...packageJson2.devDependencies
+    };
+    if (deps["next"]) {
+      return "next";
+    }
+    if (deps["react-scripts"]) {
+      return "cra";
+    }
+    if (deps["vite"]) {
+      return "vite";
+    }
+    return "other";
+  } catch (error) {
+    return "other";
+  }
+}
 
 // src/commands/init.ts
 async function init() {
@@ -151,79 +179,283 @@ var __filename = fileURLToPath(import.meta.url);
 var __dirname = path3.dirname(__filename);
 var LOCAL_REGISTRY_PATH = path3.resolve(__dirname, "..", "..", "..", "registry");
 var REMOTE_REGISTRY_BASE = "https://raw.githubusercontent.com/sublay-io/monorepo/main/registry";
-async function fetchRegistry(componentName, config) {
+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 = `${REMOTE_REGISTRY_BASE}/${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;
+  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/");
@@ -232,11 +464,30 @@ function transformImports(content, config) {
       /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";
@@ -244,6 +495,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(`
@@ -280,6 +532,55 @@ function parseDependencyName(dep) {
   }
   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");
@@ -292,17 +593,22 @@ async function checkComponentDependencies(dependencies) {
       ...packageJson2.dependencies,
       ...packageJson2.devDependencies
     };
-    const requiredDeps = dependencies.map(parseDependencyName);
-    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) => missingDeps.includes(parseDependencyName(dep))
-    );
-    missingDepsWithVersions.forEach((dep) => console.log(chalk2.dim(`  - ${dep}`)));
+    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({
@@ -314,12 +620,12 @@ async function checkComponentDependencies(dependencies) {
       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) {
@@ -356,7 +662,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;
@@ -373,9 +679,27 @@ function convertFileExtension(filePath) {
 }
 
 // src/commands/add.ts
-async function add(componentName) {
+var STRINGS_FILE = "utils/strings.ts";
+var DEFAULT_LANGUAGE = "en";
+var ENV_FILE = "utils/env.ts";
+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");
@@ -411,38 +735,74 @@ async function add(componentName) {
       spinner.start(`Fetching ${componentName}...`);
     }
     spinner.text = `Fetching ${componentName}...`;
-    const registry = await fetchRegistry(componentName, config);
-    if (!registry) {
-      spinner.fail(`Component "${componentName}" not found`);
-      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
-      );
+    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 frameworkFile = resolveFrameworkFile(
+      registry,
+      await detectFramework(config.platform),
+      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
+      });
     }
-    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);
+    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 : frameworkFile && registryPath === ENV_FILE ? frameworkFile : 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...";
@@ -462,34 +822,138 @@ 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}';`
+        `  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 './${relativeImportPath}';`
+          `  import { ${componentInfo.mainComponent}, type ${componentInfo.typeExport} } from './${relativeImportPath2}';`
         )
       );
     }
-    printAppSetupNotes(registry.dependencies);
+    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 resolveFrameworkFile(registry, framework, componentName) {
+  const frameworks = registry.frameworks && typeof registry.frameworks === "object" ? registry.frameworks : {};
+  const frameworkFile = Object.prototype.hasOwnProperty.call(frameworks, framework) ? frameworks[framework] : void 0;
+  if (frameworkFile === void 0) {
+    return null;
+  }
+  if (typeof frameworkFile !== "string" || !/^[A-Za-z0-9_][A-Za-z0-9._/-]*$/.test(frameworkFile) || frameworkFile.split("/").includes("..")) {
+    throw new RegistryError(
+      `The "${framework}" entry under "frameworks" for ${componentName} is not a usable file path.`
+    );
+  }
+  if (!registry.files.some((file) => file.path === ENV_FILE)) {
+    throw new RegistryError(
+      `${componentName} lists frameworks but has no ${ENV_FILE} to put them in.`
+    );
+  }
+  return frameworkFile;
+}
+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;
@@ -565,6 +1029,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);
@@ -622,5 +1089,13 @@ var packageJson = require2("../package.json");
 var program = new Command();
 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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublay/cli",
-  "version": "7.0.1",
+  "version": "7.2.0",
   "private": false,
   "license": "Apache-2.0",
   "author": "Sublay, maintained by Yanay Tsabary",
@@ -43,13 +43,15 @@
     "fs-extra": "^11.3.4",
     "node-fetch": "^3.3.2",
     "ora": "^9.3.0",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "semver": "^7.7.3"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^25.9.2",
     "@types/prompts": "^2.4.9",
+    "@types/semver": "^7.7.1",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^1.6.1"