@elyri/cli 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 轻爪科技
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/elyri.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+import { createInterface } from 'node:readline/promises';
+
+import { add, detectPackageManager, ExistingFilesError, parseArgs } from './lib.mjs';
+import { components } from './manifest.mjs';
+
+const [, , command, ...args] = process.argv;
+
+const printUsage = () => {
+  console.error('Usage: elyri add <component...> [--dir <path>] [--overwrite]');
+  console.error('       elyri list');
+  console.error('Run `elyri list` to see every available component.');
+};
+
+/** Ask a yes/no question. Only called when stdin is a TTY. */
+const ask = async (question) => {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return /^y(es)?$/i.test((await rl.question(question)).trim());
+  } catch {
+    // Stdin closed early (Ctrl+D): treat it as declining rather than dumping a raw error.
+    return false;
+  } finally {
+    rl.close();
+  }
+};
+
+/** Group components by the package they come from, so usage never needs one long line. */
+const list = () => {
+  const byPackage = new Map();
+  for (const [slug, { pkg }] of Object.entries(components)) {
+    if (!byPackage.has(pkg)) byPackage.set(pkg, []);
+    byPackage.get(pkg).push(slug);
+  }
+
+  for (const [pkg, slugs] of byPackage) {
+    console.log(`${pkg} (${slugs.length})`);
+    for (const slug of slugs) console.log(`  ${slug}`);
+  }
+};
+
+const run = async (options) => {
+  const { destination, files } = await add(options);
+  for (const file of files) console.log(`Added ${file}`);
+  console.log(`Import the components from your ${destination} directory.`);
+};
+
+const copy = async (rawArgs) => {
+  const { names, dir, overwrite } = parseArgs(rawArgs);
+  if (!names.length) {
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const cwd = process.cwd();
+  const options = { cwd, names, registry: components, manager: detectPackageManager(cwd), dir, overwrite };
+
+  try {
+    await run(options);
+  } catch (error) {
+    if (!(error instanceof ExistingFilesError)) throw error;
+
+    // Interactive terminals get a confirmation prompt; scripts must pass --overwrite.
+    if (process.stdin.isTTY) {
+      console.log(error.message);
+      if (await ask('Overwrite these files? (y/N) ')) {
+        await run({ ...options, overwrite: true });
+        return;
+      }
+      console.error('Aborted; no files were changed.');
+    } else {
+      console.error(error.message);
+      console.error('Pass --overwrite to replace them.');
+    }
+    process.exitCode = 1;
+  }
+};
+
+if (command === 'list') {
+  list();
+} else if (command === 'add') {
+  try {
+    await copy(args);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  }
+} else {
+  printUsage();
+  process.exitCode = 1;
+}

package/bin/elyri.test.mjs

@@ -0,0 +1,299 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, readdir, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { test } from 'node:test';
+
+import {
+  add,
+  detectPackageManager,
+  ExistingFilesError,
+  parseArgs,
+  resolveDestination,
+  resolveSelection,
+  rewriteSource,
+} from './lib.mjs';
+import { components } from './manifest.mjs';
+
+const cli = fileURLToPath(new URL('./elyri.mjs', import.meta.url));
+
+// Package name → its root directory inside this workspace
+const PACKAGE_ROOT = {
+  '@elyri/motion': fileURLToPath(new URL('../../motion/', import.meta.url)),
+  '@elyri/ui': fileURLToPath(new URL('../../ui/', import.meta.url)),
+  '@elyri/blocks': fileURLToPath(new URL('../../blocks/', import.meta.url)),
+};
+
+/** Every package the registry pulls source from */
+const manifestPackages = [...new Set(Object.values(components).map((entry) => entry.pkg))];
+
+const tempDir = () => mkdtemp(join(tmpdir(), 'elyri-cli-'));
+
+/** Create a throwaway project and link the given source packages into its node_modules */
+const createProject = async (packages) => {
+  const cwd = await tempDir();
+  await mkdir(join(cwd, 'src'), { recursive: true });
+  for (const pkg of packages) {
+    const target = join(cwd, 'node_modules', pkg);
+    await mkdir(join(cwd, 'node_modules', pkg, '..'), { recursive: true });
+    await symlink(PACKAGE_ROOT[pkg], target, 'dir');
+  }
+  return cwd;
+};
+
+const withProject = async (packages, run) => {
+  const cwd = await createProject(packages);
+  try {
+    await run(cwd);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+};
+
+const withTempDir = async (run) => {
+  const cwd = await tempDir();
+  try {
+    await run(cwd);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+};
+
+test('parseArgs separates names, dir and overwrite flags', () => {
+  assert.deepEqual(parseArgs(['a', 'b']), { names: ['a', 'b'], dir: undefined, overwrite: false });
+  assert.deepEqual(parseArgs(['a', '--dir', 'app/ui', '--overwrite']), {
+    names: ['a'],
+    dir: 'app/ui',
+    overwrite: true,
+  });
+  assert.deepEqual(parseArgs(['a', '--dir=app/ui', '-f']), { names: ['a'], dir: 'app/ui', overwrite: true });
+  assert.throws(() => parseArgs(['a', '--dir']), /needs a path/);
+});
+
+test('resolveSelection expands deps in order and rejects cycles', () => {
+  const registry = {
+    a: { pkg: 'p', folder: 'a', name: 'A', deps: ['b'] },
+    b: { pkg: 'p', folder: 'b', name: 'B' },
+    c: { pkg: 'p', folder: 'c', name: 'C', deps: ['c'] },
+  };
+
+  assert.deepEqual(
+    resolveSelection(['a', 'b'], registry).map((entry) => entry.slug),
+    ['b', 'a'],
+  );
+  assert.throws(() => resolveSelection(['c'], registry), /Circular dependency/);
+  assert.throws(() => resolveSelection(['nope'], registry), /Unknown component/);
+});
+
+test('rewriteSource points the shared runtime at the package', () => {
+  const source = "import { cn } from '../../core';\nimport './A.css';\n";
+  assert.equal(
+    rewriteSource(source, '@elyri/motion', 'A.tsx'),
+    "import { cn } from '@elyri/motion/core';\nimport './A.css';\n",
+  );
+  // A nested file may still reference siblings inside the component folder
+  const nested = "import './x.css';\nimport { y } from '../y';\n";
+  assert.equal(rewriteSource(nested, '@elyri/motion', 'parts/A.tsx'), nested);
+});
+
+test('rewriteSource rejects imports that escape the component folder', () => {
+  assert.throws(
+    () => rewriteSource("import { useX } from '../../hooks/useX';\n", '@elyri/motion', 'A.tsx'),
+    /outside the component folder/,
+  );
+});
+
+test('detectPackageManager prefers the user agent and falls back to lockfiles', async () => {
+  await withTempDir(async (cwd) => {
+    assert.equal(detectPackageManager(cwd, ''), 'pnpm');
+    await writeFile(join(cwd, 'yarn.lock'), '');
+    assert.equal(detectPackageManager(cwd, ''), 'yarn');
+    assert.equal(detectPackageManager(cwd, 'npm/11.0.0 node/v20'), 'npm');
+  });
+});
+
+test('resolveDestination follows tsconfig aliases, src layout and --dir', async () => {
+  await withTempDir(async (cwd) => {
+    // Neither a src directory nor a config: fall back to components/elyri
+    assert.equal(await resolveDestination(cwd), resolve(cwd, 'components/elyri'));
+
+    await mkdir(join(cwd, 'src'), { recursive: true });
+    assert.equal(await resolveDestination(cwd), resolve(cwd, 'src/components/elyri'));
+
+    // The alias is inherited through extends, so baseUrl resolves against the declaring config
+    await writeFile(join(cwd, 'tsconfig.json'), JSON.stringify({ extends: './tsconfig.base' }));
+    await writeFile(
+      join(cwd, 'tsconfig.base.json'),
+      JSON.stringify({ compilerOptions: { paths: { react: ['./node_modules/react'], '@/*': ['./app/*'] } } }),
+    );
+    assert.equal(await resolveDestination(cwd), resolve(cwd, 'app/components/elyri'));
+
+    assert.equal(await resolveDestination(cwd, 'lib/elyri'), resolve(cwd, 'lib/elyri'));
+  });
+});
+
+test('add copies the whole component folder and never overwrites', async () => {
+  await withProject(['@elyri/motion'], async (cwd) => {
+    const { destination, files } = await add({ cwd, names: ['aurora'], registry: components, manager: 'pnpm' });
+    const target = join(cwd, 'src/components/elyri/Aurora');
+
+    assert.equal(destination, join('src', 'components', 'elyri'));
+    for (const file of ['Aurora.tsx', 'Aurora.css', 'index.ts']) {
+      assert.ok(
+        files.some((path) => path.endsWith(`/Aurora/${file}`)),
+        `${file} should be copied`,
+      );
+    }
+
+    const component = await readFile(join(target, 'Aurora.tsx'), 'utf8');
+    assert.match(component, /from '@elyri\/motion\/core'/);
+    assert.doesNotMatch(component, /\.\.\/\.\.\/\.\.\/core/);
+    assert.ok((await readFile(join(target, 'Aurora.css'), 'utf8')).length > 0);
+  });
+});
+
+test('add reports every existing file and writes nothing', async () => {
+  await withProject(['@elyri/motion'], async (cwd) => {
+    await add({ cwd, names: ['aurora'], registry: components, manager: 'pnpm' });
+
+    const target = join(cwd, 'src/components/elyri/Aurora/Aurora.tsx');
+    await writeFile(target, 'custom content');
+
+    await assert.rejects(add({ cwd, names: ['aurora'], registry: components, manager: 'pnpm' }), (error) => {
+      assert.ok(error instanceof ExistingFilesError);
+      assert.ok(error.files.some((file) => file.endsWith('/Aurora/Aurora.tsx')));
+      return true;
+    });
+    assert.equal(await readFile(target, 'utf8'), 'custom content');
+  });
+});
+
+test('add replaces existing files when overwrite is set', async () => {
+  await withProject(['@elyri/motion'], async (cwd) => {
+    await add({ cwd, names: ['aurora'], registry: components, manager: 'pnpm' });
+
+    const target = join(cwd, 'src/components/elyri/Aurora/Aurora.tsx');
+    await writeFile(target, 'custom content');
+
+    await add({ cwd, names: ['aurora'], registry: components, manager: 'pnpm', overwrite: true });
+
+    const component = await readFile(target, 'utf8');
+    assert.match(component, /from '@elyri\/motion\/core'/);
+    assert.doesNotMatch(component, /custom content/);
+  });
+});
+
+test('add honours an explicit dir', async () => {
+  await withProject(['@elyri/motion'], async (cwd) => {
+    const { destination } = await add({
+      cwd,
+      names: ['fade-in'],
+      registry: components,
+      manager: 'pnpm',
+      dir: 'app/ui',
+    });
+
+    assert.equal(destination, join('app', 'ui'));
+    const component = await readFile(join(cwd, 'app/ui/FadeIn/FadeIn.tsx'), 'utf8');
+    assert.match(component, /from '@elyri\/motion\/core'/);
+  });
+});
+
+test('every registered component can be copied', async () => {
+  await withProject(manifestPackages, async (cwd) => {
+    await add({ cwd, names: Object.keys(components), registry: components, manager: 'pnpm' });
+
+    for (const { name } of Object.values(components)) {
+      const entry = await readFile(join(cwd, 'src/components/elyri', name, 'index.ts'), 'utf8');
+      assert.match(entry, /^export /m);
+    }
+  });
+});
+
+test('add rewrites cross-component imports for declared deps', async () => {
+  await withProject(['@elyri/ui'], async (cwd) => {
+    await add({ cwd, names: ['data-table'], registry: components, manager: 'pnpm' });
+
+    const source = await readFile(join(cwd, 'src/components/elyri/DataTable/DataTable.tsx'), 'utf8');
+    assert.match(source, /from '\.\.\/Checkbox'/);
+    assert.match(source, /from '\.\.\/Pagination'/);
+    assert.doesNotMatch(source, /\.\.\/\.\.\/(forms|navigation)\//);
+
+    // deps are copied as sibling folders that the rewritten imports resolve to
+    for (const name of ['Checkbox', 'Pagination']) {
+      assert.match(await readFile(join(cwd, 'src/components/elyri', name, 'index.ts'), 'utf8'), /^export /m);
+    }
+  });
+});
+
+test('add asks to install the matching package first', async () => {
+  await withTempDir(async (cwd) => {
+    await assert.rejects(
+      add({ cwd, names: ['fade-in'], registry: components, manager: 'npm' }),
+      /npm install @elyri\/motion/,
+    );
+  });
+});
+
+test('add explains when the installed package is too old', async () => {
+  await withTempDir(async (cwd) => {
+    const packageRoot = join(cwd, 'node_modules/@elyri/motion');
+    await mkdir(join(packageRoot, 'src/components'), { recursive: true });
+    await writeFile(join(packageRoot, 'package.json'), JSON.stringify({ name: '@elyri/motion', version: '0.0.1' }));
+
+    await assert.rejects(
+      add({ cwd, names: ['aurora'], registry: components, manager: 'yarn' }),
+      /@elyri\/motion@0\.0\.1 does not ship backgrounds\/Aurora[\s\S]*yarn add @elyri\/motion@latest/,
+    );
+  });
+});
+
+test('cli lists components and reports usage on misuse', async () => {
+  await withProject(['@elyri/motion'], async (cwd) => {
+    const listed = execFileSync(process.execPath, [cli, 'list'], { cwd, encoding: 'utf8' });
+    assert.match(listed, /@elyri\/motion/);
+    assert.match(listed, /fade-in/);
+
+    execFileSync(process.execPath, [cli, 'add', 'fade-in'], { cwd });
+    const component = await readFile(join(cwd, 'src/components/elyri/FadeIn/FadeIn.tsx'), 'utf8');
+    assert.match(component, /from '@elyri\/motion\/core'/);
+
+    execFileSync(process.execPath, [cli, 'add', 'tilt', '--dir=app/ui'], { cwd });
+    assert.match(await readFile(join(cwd, 'app/ui/Tilt/Tilt.tsx'), 'utf8'), /from '@elyri\/motion\/core'/);
+
+    // stdin is a pipe here, so a conflict must fail with a hint instead of prompting
+    assert.throws(() => execFileSync(process.execPath, [cli, 'add', 'fade-in'], { cwd }), /Pass --overwrite/);
+    execFileSync(process.execPath, [cli, 'add', 'fade-in', '--overwrite'], { cwd });
+
+    assert.throws(() => execFileSync(process.execPath, [cli, 'add'], { cwd }), /Usage/);
+    assert.throws(() => execFileSync(process.execPath, [cli, 'add', 'nope'], { cwd }), /Unknown component/);
+    assert.throws(() => execFileSync(process.execPath, [cli, 'add', 'fade-in', '--dir'], { cwd }), /needs a path/);
+  });
+});
+
+test('manifest registers every component on disk', async () => {
+  const onDisk = [];
+  for (const [pkg, root] of Object.entries(PACKAGE_ROOT)) {
+    for (const category of await readdir(join(root, 'src/components'), { withFileTypes: true })) {
+      if (!category.isDirectory()) continue;
+      const categoryRoot = join(root, 'src/components', category.name);
+      for (const entry of await readdir(categoryRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        // A folder counts as a component once it holds a .tsx file; empty placeholders do not
+        const files = await readdir(join(categoryRoot, entry.name));
+        if (files.some((file) => file.endsWith('.tsx'))) onDisk.push(`${pkg}:${category.name}/${entry.name}`);
+      }
+    }
+  }
+  const registered = Object.values(components).map(({ pkg, folder }) => `${pkg}:${folder}`);
+  assert.deepEqual(onDisk.sort(), registered.sort());
+});
+
+test('runtime packages publish the source the cli copies', async () => {
+  for (const pkg of new Set(Object.values(components).map((entry) => entry.pkg))) {
+    const manifest = JSON.parse(await readFile(join(PACKAGE_ROOT[pkg], 'package.json'), 'utf8'));
+    assert.ok(manifest.files.includes('src/components'), `${pkg} must publish src/components`);
+  }
+});

package/bin/lib.mjs

@@ -0,0 +1,282 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { dirname, join, posix, relative, resolve, sep } from 'node:path';
+
+/** The shared runtime is always imported as `<pkg>/core`, whatever depth the source used. */
+const coreImport = /from\s+(['"])(?:\.\.\/)+core\1/g;
+/** Any other relative import (side-effect imports and re-exports included); used to verify a copy cannot escape its folder. */
+const relativeImport = /(?:from\s+|^\s*import\s+)(['"])(\.\.?\/[^'"]*)\1/gm;
+/** Extensions whose imports are rewritten. */
+const scriptExtensions = ['.ts', '.tsx'];
+const packageManagers = ['pnpm', 'npm', 'yarn', 'bun'];
+const installCommands = { pnpm: 'pnpm add', npm: 'npm install', yarn: 'yarn add', bun: 'bun add' };
+
+/** Fallback destination when the project has neither a source alias nor a `src/` directory. */
+const defaultDestination = 'src/components/elyri';
+
+/** Thrown when a target file already exists; `files` lists every conflicting path. */
+export class ExistingFilesError extends Error {
+  constructor(files) {
+    super(`Already exists; no files were changed:\n${files.map((file) => `  ${file}`).join('\n')}`);
+    this.name = 'ExistingFilesError';
+    this.files = files;
+  }
+}
+
+const isScript = (file) => scriptExtensions.some((ext) => file.endsWith(ext));
+
+const readJson = async (file) => {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+/** Split component names from `--dir` / `--overwrite`, order independent. */
+export const parseArgs = (rawArgs) => {
+  const names = [];
+  let dir;
+  let overwrite = false;
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === '--dir' || arg === '-d') {
+      dir = rawArgs[index + 1];
+      if (!dir) throw new Error(`${arg} needs a path`);
+      index += 1;
+    } else if (arg.startsWith('--dir=')) {
+      dir = arg.slice('--dir='.length);
+      if (!dir) throw new Error('--dir needs a path');
+    } else if (arg === '--overwrite' || arg === '--force' || arg === '-f') {
+      overwrite = true;
+    } else {
+      names.push(arg);
+    }
+  }
+
+  return { names, dir, overwrite };
+};
+
+/** Detect the package manager from `npm_config_user_agent`, then lockfiles, then default to pnpm. */
+export const detectPackageManager = (cwd, userAgent = process.env.npm_config_user_agent ?? '') => {
+  const fromAgent = packageManagers.find((manager) => userAgent.startsWith(manager));
+  if (fromAgent) return fromAgent;
+
+  const lockfiles = [
+    ['pnpm', 'pnpm-lock.yaml'],
+    ['yarn', 'yarn.lock'],
+    ['bun', 'bun.lockb'],
+    ['bun', 'bun.lock'],
+    ['npm', 'package-lock.json'],
+  ];
+  return lockfiles.find(([, lockfile]) => existsSync(join(cwd, lockfile)))?.[0] ?? 'pnpm';
+};
+
+/** Install command for a package, so errors suggest something that works in the user's setup. */
+const installCommand = (manager, pkg) => `${installCommands[manager] ?? installCommands.pnpm} ${pkg}`;
+
+/** Only these alias keys are treated as the project source root, so `react`-style mappings are ignored. */
+const aliasKeys = ['@/*', '~/*', '#/*'];
+const configFiles = ['tsconfig.json', 'tsconfig.app.json', 'jsconfig.json'];
+
+/** Walk `extends` to the first config that declares `paths`, keeping the file that declared them. */
+const findPathsConfig = async (file, seen = new Set()) => {
+  const full = resolve(file);
+  if (seen.has(full)) return null;
+  seen.add(full);
+
+  const json = await readJson(full);
+  if (!json) return null;
+  if (json.compilerOptions?.paths) {
+    return {
+      paths: json.compilerOptions.paths,
+      baseUrl: json.compilerOptions.baseUrl ?? '.',
+      dir: dirname(full),
+    };
+  }
+  if (typeof json.extends === 'string' && json.extends.startsWith('.')) {
+    const next = json.extends.endsWith('.json') ? json.extends : `${json.extends}.json`;
+    return findPathsConfig(resolve(dirname(full), next), seen);
+  }
+  return null;
+};
+
+/** Infer the source root from a tsconfig alias, e.g. "@/*": ["./src/*"] → <cwd>/src. */
+const findAliasRoot = async (cwd) => {
+  for (const configFile of configFiles) {
+    const found = await findPathsConfig(join(cwd, configFile));
+    if (!found) continue;
+
+    for (const key of aliasKeys) {
+      const [target] = Array.isArray(found.paths[key]) ? found.paths[key] : [];
+      if (typeof target !== 'string') continue;
+      const root = target.replace(/\*.*$/, '').replace(/\/+$/, '');
+      if (!root) continue;
+      return resolve(found.dir, found.baseUrl, root);
+    }
+  }
+  return null;
+};
+
+/** Copy target: `--dir` wins, then the tsconfig source alias, then the usual layout with or without `src/`. */
+export const resolveDestination = async (cwd, dir) => {
+  if (dir) return resolve(cwd, dir);
+
+  const aliasRoot = await findAliasRoot(cwd);
+  if (aliasRoot) return join(aliasRoot, 'components', 'elyri');
+
+  return resolve(cwd, existsSync(join(cwd, 'src')) ? defaultDestination : 'components/elyri');
+};
+
+/** Expand `deps` recursively, keeping declaration order, de-duplicating and rejecting cycles. */
+export const resolveSelection = (names, registry) => {
+  const selection = [];
+  const visiting = new Set();
+  const resolved = new Set();
+
+  const visit = (slug) => {
+    if (resolved.has(slug)) return;
+    const entry = registry[slug];
+    if (!entry) throw new Error(`Unknown component: ${slug}`);
+    if (visiting.has(slug)) throw new Error(`Circular dependency: ${slug}`);
+
+    visiting.add(slug);
+    for (const dep of entry.deps ?? []) visit(dep);
+    visiting.delete(slug);
+    resolved.add(slug);
+    selection.push({ slug, ...entry });
+  };
+
+  for (const name of new Set(names)) visit(name);
+  return selection;
+};
+
+/** Every file inside a component folder, as `/`-separated paths relative to it. */
+const collectFiles = async (componentRoot) => {
+  const files = [];
+
+  const walk = async (dir) => {
+    for (const item of await readdir(dir, { withFileTypes: true })) {
+      if (item.name.startsWith('.')) continue;
+      const full = join(dir, item.name);
+      if (item.isDirectory()) await walk(full);
+      else files.push(relative(componentRoot, full).split(sep).join('/'));
+    }
+  };
+
+  await walk(componentRoot);
+  return files.sort();
+};
+
+/**
+ * Rewrite one source file so the shared runtime is imported from the package.
+ * A relative import may also point at another registered component: when `resolveComponent`
+ * maps that specifier to a sibling folder name, it is rewritten accordingly (deps are copied
+ * as siblings). Any other import that would escape the component folder is an error: copying
+ * it would produce a file that cannot resolve its own imports.
+ */
+export const rewriteSource = (source, pkg, file, resolveComponent) => {
+  const depth = file.split('/').length - 1;
+
+  const escaping = new Set();
+  const rewritten = source
+    .replace(coreImport, (_match, quote) => `from ${quote}${pkg}/core${quote}`)
+    .replace(relativeImport, (match, quote, specifier) => {
+      const prefix = /^(?:\.\.\/)+/.exec(specifier)?.[0] ?? '';
+      const up = prefix ? prefix.split('../').length - 1 : 0;
+      if (up <= depth) return match;
+
+      const replacement = resolveComponent?.(specifier);
+      if (!replacement) {
+        escaping.add(specifier);
+        return match;
+      }
+      return match.replace(specifier, replacement);
+    });
+
+  if (escaping.size) {
+    throw new Error(`${file} imports outside the component folder: ${[...escaping].join(', ')}`);
+  }
+
+  return rewritten;
+};
+
+/**
+ * Map a cross-component relative import to the sibling folder a copy will live in.
+ * `fromDir` is the importing file's directory relative to `<pkg>/src/components`.
+ * Returns the new specifier, or null when the target is not a registered component.
+ */
+const rewriteComponentImport = (registry, pkg, fromDir, file, specifier) => {
+  const target = posix.normalize(posix.join(fromDir, specifier));
+  const dep = Object.values(registry).find((entry) => entry.pkg === pkg && entry.folder === target);
+  if (!dep) return null;
+
+  const depth = posix.dirname(file).split('/').filter((segment) => segment && segment !== '.').length;
+  return `${'../'.repeat(depth + 1)}${dep.name}`;
+};
+
+/**
+ * Copy component source into the user's project. A component is copied as a whole
+ * folder (including its index.ts), so relative imports inside it keep working;
+ * only the shared runtime is rewritten to `<pkg>/core`.
+ */
+export const add = async ({ cwd, names, registry, manager = 'pnpm', dir, overwrite = false }) => {
+  const selection = resolveSelection(names, registry);
+  const destination = await resolveDestination(cwd, dir);
+
+  // 1. Read everything into memory first: a failure here must not leave a half-written copy.
+  const pending = [];
+  for (const entry of selection) {
+    const packageRoot = resolve(cwd, 'node_modules', entry.pkg);
+    const sourceRoot = join(packageRoot, 'src/components');
+    if (!existsSync(sourceRoot)) {
+      throw new Error(`Missing ${entry.pkg}. Install it first: ${installCommand(manager, entry.pkg)}`);
+    }
+
+    const componentRoot = join(sourceRoot, entry.folder);
+    if (!existsSync(componentRoot)) {
+      // The package is installed but does not ship this component: usually a stale version.
+      const version = (await readJson(join(packageRoot, 'package.json')))?.version ?? 'unknown';
+      throw new Error(
+        `${entry.pkg}@${version} does not ship ${entry.folder}. Update it first: ${installCommand(manager, `${entry.pkg}@latest`)}`,
+      );
+    }
+
+    const files = await collectFiles(componentRoot);
+    if (!files.length) throw new Error(`${entry.pkg} ships no files for ${entry.slug}`);
+
+    for (const file of files) {
+      const from = join(componentRoot, file);
+      const source = await readFile(from, 'utf8');
+      const fromDir = posix.join(entry.folder, posix.dirname(file));
+      pending.push({
+        from,
+        to: join(destination, entry.name, file),
+        content: isScript(file)
+          ? rewriteSource(source, entry.pkg, file, (specifier) =>
+              rewriteComponentImport(registry, entry.pkg, fromDir, file, specifier),
+            )
+          : source,
+      });
+    }
+  }
+
+  // 2. Pre-check conflicts: an existing file, or two components writing the same path.
+  const seen = new Set();
+  const conflicts = new Set();
+  for (const { to } of pending) {
+    if (seen.has(to) || existsSync(to)) conflicts.add(to);
+    seen.add(to);
+  }
+  if (conflicts.size && !overwrite) throw new ExistingFilesError([...conflicts]);
+
+  // 3. Only write once every pre-check passed.
+  for (const { to, content } of pending) {
+    await mkdir(dirname(to), { recursive: true });
+    // `wx` never clobbers a file created between the pre-check and the write.
+    await writeFile(to, content, { flag: overwrite ? 'w' : 'wx' });
+  }
+
+  return { destination: relative(cwd, destination) || '.', files: pending.map(({ to }) => to) };
+};

package/bin/manifest.mjs

@@ -0,0 +1,76 @@
+// Component registry: slug → source package, source folder and component name.
+// `pkg` decides which package the CLI copies from and how the shared runtime is imported (<pkg>/core).
+// An entry may declare `deps: ['other-slug']`; the CLI copies those first, recursively.
+export const components = {
+  'ascii-image': { pkg: '@elyri/motion', folder: 'media/AsciiImage', name: 'AsciiImage' },
+  aurora: { pkg: '@elyri/motion', folder: 'backgrounds/Aurora', name: 'Aurora' },
+  caustics: { pkg: '@elyri/motion', folder: 'backgrounds/Caustics', name: 'Caustics' },
+  contours: { pkg: '@elyri/motion', folder: 'backgrounds/Contours', name: 'Contours' },
+  'count-up': { pkg: '@elyri/motion', folder: 'animations/CountUp', name: 'CountUp' },
+  'dot-field': { pkg: '@elyri/motion', folder: 'backgrounds/DotField', name: 'DotField' },
+  'dragon-scales': { pkg: '@elyri/motion', folder: 'backgrounds/DragonScales', name: 'DragonScales' },
+  'fade-in': { pkg: '@elyri/motion', folder: 'animations/FadeIn', name: 'FadeIn' },
+  filaments: { pkg: '@elyri/motion', folder: 'backgrounds/Filaments', name: 'Filaments' },
+  'flip-tiles': { pkg: '@elyri/motion', folder: 'backgrounds/FlipTiles', name: 'FlipTiles' },
+  'gradient-text': { pkg: '@elyri/motion', folder: 'text/GradientText', name: 'GradientText' },
+  halo: { pkg: '@elyri/motion', folder: 'backgrounds/Halo', name: 'Halo' },
+  magnetic: { pkg: '@elyri/motion', folder: 'animations/Magnetic', name: 'Magnetic' },
+  marquee: { pkg: '@elyri/motion', folder: 'text/Marquee', name: 'Marquee' },
+  'mesh-gradient': { pkg: '@elyri/motion', folder: 'backgrounds/MeshGradient', name: 'MeshGradient' },
+  'particle-text': { pkg: '@elyri/motion', folder: 'text/ParticleText', name: 'ParticleText' },
+  'pixel-vortex': { pkg: '@elyri/motion', folder: 'backgrounds/PixelVortex', name: 'PixelVortex' },
+  planet: { pkg: '@elyri/motion', folder: 'backgrounds/Planet', name: 'Planet' },
+  'rotating-text': { pkg: '@elyri/motion', folder: 'text/RotatingText', name: 'RotatingText' },
+  'scale-in': { pkg: '@elyri/motion', folder: 'animations/ScaleIn', name: 'ScaleIn' },
+  'scramble-text': { pkg: '@elyri/motion', folder: 'text/ScrambleText', name: 'ScrambleText' },
+  'scroll-marquee': { pkg: '@elyri/motion', folder: 'text/ScrollMarquee', name: 'ScrollMarquee' },
+  'scroll-reveal': { pkg: '@elyri/motion', folder: 'text/ScrollReveal', name: 'ScrollReveal' },
+  'silk-waves': { pkg: '@elyri/motion', folder: 'backgrounds/SilkWaves', name: 'SilkWaves' },
+  'split-reveal': { pkg: '@elyri/motion', folder: 'text/SplitReveal', name: 'SplitReveal' },
+  spotlight: { pkg: '@elyri/motion', folder: 'animations/Spotlight', name: 'Spotlight' },
+  tilt: { pkg: '@elyri/motion', folder: 'animations/Tilt', name: 'Tilt' },
+  typewriter: { pkg: '@elyri/motion', folder: 'text/Typewriter', name: 'Typewriter' },
+  velvet: { pkg: '@elyri/motion', folder: 'backgrounds/Velvet', name: 'Velvet' },
+  'wave-text': { pkg: '@elyri/motion', folder: 'text/WaveText', name: 'WaveText' },
+
+  // @elyri/ui
+  accordion: { pkg: '@elyri/ui', folder: 'navigation/Accordion', name: 'Accordion' },
+  alert: { pkg: '@elyri/ui', folder: 'feedback/Alert', name: 'Alert' },
+  avatar: { pkg: '@elyri/ui', folder: 'data-display/Avatar', name: 'Avatar' },
+  button: { pkg: '@elyri/ui', folder: 'forms/Button', name: 'Button' },
+  'button-group': { pkg: '@elyri/ui', folder: 'forms/ButtonGroup', name: 'ButtonGroup' },
+  card: { pkg: '@elyri/ui', folder: 'data-display/Card', name: 'Card' },
+  checkbox: { pkg: '@elyri/ui', folder: 'forms/Checkbox', name: 'Checkbox' },
+  'context-menu': { pkg: '@elyri/ui', folder: 'overlays/ContextMenu', name: 'ContextMenu' },
+  'data-table': {
+    pkg: '@elyri/ui',
+    folder: 'data-display/DataTable',
+    name: 'DataTable',
+    deps: ['checkbox', 'pagination'],
+  },
+  dialog: { pkg: '@elyri/ui', folder: 'overlays/Dialog', name: 'Dialog' },
+  divider: { pkg: '@elyri/ui', folder: 'data-display/Divider', name: 'Divider' },
+  'dropdown-menu': { pkg: '@elyri/ui', folder: 'overlays/DropdownMenu', name: 'DropdownMenu' },
+  empty: { pkg: '@elyri/ui', folder: 'data-display/Empty', name: 'Empty' },
+  field: { pkg: '@elyri/ui', folder: 'forms/Field', name: 'Field' },
+  input: { pkg: '@elyri/ui', folder: 'forms/Input', name: 'Input' },
+  item: { pkg: '@elyri/ui', folder: 'data-display/Item', name: 'Item' },
+  'number-input': { pkg: '@elyri/ui', folder: 'forms/NumberInput', name: 'NumberInput' },
+  pagination: { pkg: '@elyri/ui', folder: 'navigation/Pagination', name: 'Pagination' },
+  popover: { pkg: '@elyri/ui', folder: 'overlays/Popover', name: 'Popover' },
+  progress: { pkg: '@elyri/ui', folder: 'feedback/Progress', name: 'Progress' },
+  radio: { pkg: '@elyri/ui', folder: 'forms/Radio', name: 'Radio' },
+  select: { pkg: '@elyri/ui', folder: 'forms/Select', name: 'Select' },
+  sidebar: { pkg: '@elyri/ui', folder: 'navigation/Sidebar', name: 'Sidebar' },
+  skeleton: { pkg: '@elyri/ui', folder: 'feedback/Skeleton', name: 'Skeleton' },
+  slider: { pkg: '@elyri/ui', folder: 'forms/Slider', name: 'Slider' },
+  switch: { pkg: '@elyri/ui', folder: 'forms/Switch', name: 'Switch' },
+  tabs: { pkg: '@elyri/ui', folder: 'navigation/Tabs', name: 'Tabs' },
+  tag: { pkg: '@elyri/ui', folder: 'data-display/Tag', name: 'Tag' },
+  textarea: { pkg: '@elyri/ui', folder: 'forms/Textarea', name: 'Textarea' },
+  toast: { pkg: '@elyri/ui', folder: 'feedback/Toast', name: 'Toast' },
+  tooltip: { pkg: '@elyri/ui', folder: 'overlays/Tooltip', name: 'Tooltip' },
+
+  // @elyri/blocks（页面区块，依赖 @elyri/ui 与 @elyri/motion）
+  login: { pkg: '@elyri/blocks', folder: 'auth/Login', name: 'Login' },
+};

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@elyri/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "CLI that copies Elyri component source into your project.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TechCat-Team/Elyri.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "files": [
+    "bin"
+  ],
+  "bin": {
+    "elyri": "bin/elyri.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "react",
+    "cli",
+    "component-library",
+    "css-variables"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test bin/*.test.mjs"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.