@yopem-ui/cli 0.1.1 → 0.1.3

package/README.md

@@ -1,7 +1,8 @@
 # @yopem-ui/cli
 
-Copy Yopem UI components and configure StyleX in an existing React project.
-Requires Bun. Registry requests default to `https://ui.yopem.com/r`.
+Copy Yopem UI components into an existing React project. Configure StyleX with
+the CLI. The CLI requires Bun. Registry requests use `https://ui.yopem.com/r` by
+default.
 
 ```sh
 bunx @yopem-ui/cli init
@@ -11,19 +12,20 @@ bunx @yopem-ui/cli --help
 bunx @yopem-ui/cli --version
 ```
 
-No arguments or `--help` (`-h`) prints usage; `--version` (`-v`) prints the
-installed CLI version. These commands need no project and exit successfully.
-Invalid commands or arguments exit with status 1.
+Run the CLI without arguments, or with `--help` (`-h`), to show usage. Use
+`--version` (`-v`) to show the installed CLI version. These commands do not need
+a project. They exit successfully. Invalid commands or arguments exit with
+status 1.
 
-`init` supports Vite, TanStack Router, TanStack Start, React Router, Next.js App
-Router, and Astro. Pass `--framework <name>` if autodetection is ambiguous.
-Installed source changes stay intact on `init` and `add`; `update` rejects
-modified files unless `--force` is supplied. Installed files and their hashes
-are tracked in `ui.json`.
+The `init` command supports Vite, TanStack Router, TanStack Start, React Router,
+Next.js App Router, and Astro. Pass `--framework <name>` if the CLI cannot
+identify one framework. The `init` and `add` commands keep local changes to
+installed source. The `update` command rejects modified files unless you pass
+`--force`. The CLI records installed files and their hashes in `ui.json`.
 
 ## Dry run
 
-Preview `add` or `update` before installing:
+Preview `add` or `update` before installation:
 
 ```sh
 bunx @yopem-ui/cli add button --dry-run
@@ -31,33 +33,35 @@ bunx @yopem-ui/cli update button --dry-run
 bunx @yopem-ui/cli update button --dry-run --force
 ```
 
-The plan lists file writes (including tracking in `ui.json`), skips, all local
-file conflicts, and runtime/dev dependency additions. Forced source overwrites
-are marked explicitly. As in normal mode, `add` skips modified tracked files;
-`update` reports them as conflicts without `--force`. Conflicts block a real
-install until resolved or forced. Dependency lists show the package arguments
-the installer would request, not package-manager version resolution.
-
-Dry runs still read the registry and validate URLs, schemas, paths, and file
-integrity. They write no files, create no directories or temporary files, never
-run a package manager, and do not create or change `ui.json`, project config,
-package manifests, lockfiles, or dependencies. `--cwd` and `--registry` work as
-usual. `init --dry-run` and `initProject({ dryRun: true })` are rejected before
-any changes.
-
-Programmatic callers use `installItem(name, { dryRun: true })` through
-`@yopem-ui/cli/install`. The result adds `preview.files` (`path`, `action`,
-optional `reason` and `forced`), `preview.dependencies`, and
-`preview.devDependencies`; `installed` is zero. Normal calls retain their
-`{ installed, skipped }` result. Previewed writes apply when no conflicts block
-the command and files have not changed before a subsequent real install.
+The plan lists file writes, skipped files, local conflicts, and runtime and
+development dependency additions. File writes include tracking changes in
+`ui.json`. The plan identifies forced source overwrites explicitly. As in normal
+mode, `add` skips modified tracked files. Without `--force`, `update` reports
+those files as conflicts. Resolve conflicts before a real installation, or use
+`--force` to overwrite files. Dependency lists show requested package arguments,
+not package-manager version resolution.
+
+Dry runs read the registry. They validate URLs, schemas, paths, and file
+integrity. They do not write files or create directories or temporary files.
+They do not run a package manager. They do not change `ui.json`, project
+configuration, package manifests, lockfiles, or dependencies. Use `--cwd` and
+`--registry` as usual. The `init --dry-run` command also previews setup for
+supported frameworks and shared UI workspaces.
+
+Programmatic callers can use `installItem(name, { dryRun: true })` through
+`@yopem-ui/cli/install`. The result includes `preview.files`,
+`preview.dependencies`, and `preview.devDependencies`. Each preview file has
+`path` and `action`, with optional `reason` and `forced`. The `installed` count
+is zero. Normal calls return `{ installed, skipped }`. Previewed writes apply
+only if no conflicts block the command and files remain unchanged before the
+real installation.
 
 ## Registry
 
 Pass `--registry <URL>` to `init`, `add`, or `update` to use another registry.
-The override applies to that command only; it is not stored in `ui.json`. URLs
-must use HTTPS, except HTTP on `localhost` or loopback addresses. Credentials,
-query strings, and fragments are rejected.
+The setting applies only to that command. The CLI does not store it in
+`ui.json`. URLs must use HTTPS, except HTTP on `localhost` or loopback
+addresses. The CLI rejects credentials, query strings, and fragments.
 
 For local development, start this repository's docs server with `bun run dev`:
 
@@ -67,16 +71,17 @@ bunx @yopem-ui/cli add button --registry http://localhost:3100/r
 bunx @yopem-ui/cli update button --registry http://localhost:3100/r
 ```
 
-Each request has a 30-second timeout covering connection and JSON body reads.
-Failures report timeout, network, HTTP status, or malformed JSON details without
-writing source, configuration, or dependencies. Programmatic callers can set
-`InstallOptions.registryUrl` and `requestTimeoutMs` (milliseconds).
+Each request has a 30-second timeout for connection and JSON body reads.
+Failures report timeout, network, HTTP status, or malformed JSON details. The
+CLI makes no source, configuration, or dependency changes after these failures.
+Programmatic callers can set `InstallOptions.registryUrl` and
+`requestTimeoutMs`. The timeout uses milliseconds.
 
 ## Monorepos
 
-Target an app from the repository root with `--cwd`. Package manager detection
-uses the app and its workspace root; dependencies stay in the target package.
-Bun, npm, pnpm, and Yarn workspaces are supported.
+Use `--cwd` to target an app from the repository root. The CLI detects the
+package manager from the app and its workspace root. Dependencies stay in the
+target package. The CLI supports Bun, npm, pnpm, and Yarn workspaces.
 
 ```sh
 bunx @yopem-ui/cli init --cwd apps/web
@@ -84,7 +89,8 @@ bunx @yopem-ui/cli add button --cwd apps/web
 ```
 
 For shared components, use an existing named React package in the same
-workspace. `--ui` is relative to the target app, not the repository root.
+workspace. The `--ui` path is relative to the target app, not the repository
+root.
 
 ```sh
 bunx @yopem-ui/cli init --cwd apps/web --ui ../../packages/ui
@@ -92,20 +98,22 @@ bunx @yopem-ui/cli add button --cwd packages/ui
 bunx @yopem-ui/cli update button --cwd packages/ui
 ```
 
-`init --ui` installs base files in the UI package, adds source subpath exports,
-links the app, and configures StyleX to scan both packages. Next.js also gets
-`transpilePackages`. Init registers shared package imports with the Yopem UI
-Oxlint rules, preserving existing rule options and explicit opt-outs. Shared
-source imports use the UI package name, such as `@acme/ui/components/ui/button`;
-later `add` and `update` reuse that name from its `ui.json`. Run `init --ui` for
-each consuming app and keep passing `--ui` when repeating init. Existing
-conflicting exports or build configuration require manual review; init does not
-migrate app-local components.
+The `init --ui` command installs base files in the UI package. It adds source
+subpath exports and links the app. It configures StyleX to scan both packages.
+For Next.js, it also adds `transpilePackages`. The command registers shared
+package imports with the Yopem UI Oxlint rules. It keeps existing rule options
+and explicit opt-outs.
+
+Shared source imports use the UI package name, such as
+`@acme/ui/components/ui/button`. Later `add` and `update` commands use that name
+from the package's `ui.json`. Run `init --ui` for each consuming app. Pass
+`--ui` again when you repeat init. Review conflicting exports or build
+configuration manually. The init command does not migrate app-local components.
 
 ## Development checks
 
-From the repository root, generate registry fixtures and build the lint plugin
-before running CLI tests:
+Generate registry fixtures from the repository root. Build the lint plugin
+before you run CLI tests:
 
 ```sh
 bun run registry:build
@@ -113,27 +121,31 @@ bun run --cwd packages/oxlint-plugin build
 bun test packages/cli
 ```
 
-`bun run --cwd packages/cli test` also runs the CLI suite. Tests use `bun:test`,
-not browsers; packaged installation checks explicitly pass a local `--registry`
-and serve registry JSON with Bun when port 3100 has no registry server. Registry
-network tests use isolated local Bun servers for successful workflows, header
-and body stalls, malformed JSON, and HTTP/network failures. Command logs and
-configuration artifacts are saved in `packages/cli/test-results/`.
-
-`bun test packages/cli/test/dry-run.test.ts` checks real fixture projects with
-local registries, whole-project file/directory snapshots, dependency-call
-tracking, conflict/force previews, shared import prefixes, validation failures,
-and CLI argument rules. Snapshot and preview evidence is saved in
-`step5-dry-run.json` under the results directory.
-
-`bun test packages/cli/test/public.test.ts` runs packed CLI production smoke
-checks: help, version matching the packed manifest, dry-run previews, init, add
-Button, lint, and build in Vite and Next.js App Router apps, including shared UI
-workspaces. Requires Node.js for Next.js and network access for fixture
-dependencies. Tests verify build artifacts and compiled StyleX CSS, then save
-`packaged-*.log`, `packaged-*.html`, and `packaged-*.css` evidence.
+The `bun run --cwd packages/cli test` command also runs the CLI suite. Tests use
+`bun:test`, not browsers. Packaged installation checks explicitly pass a local
+`--registry`. They serve registry JSON with Bun if port 3100 has no registry
+server.
+
+Registry network tests use isolated local Bun servers. They cover successful
+workflows, header and body stalls, malformed JSON, and HTTP and network
+failures. Tests save command logs and configuration artifacts in
+`packages/cli/test-results/`.
+
+Run `bun test packages/cli/test/dry-run.test.ts` for real fixture project
+checks. These checks use local registries and complete file and directory
+snapshots. They cover dependency-call tracking, conflict and force previews,
+shared import prefixes, validation failures, and CLI argument rules. Tests save
+snapshot and preview evidence in `step5-dry-run.json` in the results directory.
+
+Run `bun test packages/cli/test/public.test.ts` for packed CLI production
+checks. These checks cover help, version matching, dry-run previews, init,
+Button installation, lint, and builds. They use Vite and Next.js App Router
+apps, including shared UI workspaces. Next.js checks require Node.js. Fixture
+dependencies require network access. Tests verify build artifacts and compiled
+StyleX CSS. They save evidence in `packaged-*.log`, `packaged-*.html`, and
+`packaged-*.css`.
 
 ## Licence
 
-This project is licensed under the terms of the
+This project uses the
 [MIT license](https://github.com/yopem/ui/blob/main/LICENSE.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yopem-ui/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI for installing Yopem UI source components and StyleX setup",
   "keywords": [
     "cli",

package/src/init.ts

@@ -1402,7 +1402,6 @@ const lintRules = {
   "yopem-ui/no-raw-stylex-colors": "error",
   "yopem-ui/prefer-layout-primitives": "error",
   "yopem-ui/static-stylex": "error",
-  "yopem-ui/valid-polymorphic-as": "error",
 }
 
 function lintConfig(content: string, shared?: SharedUI) {
@@ -1441,7 +1440,6 @@ function lintConfig(content: string, shared?: SharedUI) {
     for (const name of [
       "yopem-ui/enforce-styling-methods",
       "yopem-ui/no-restyle",
-      "yopem-ui/valid-polymorphic-as",
     ]) {
       const setting = configuredRules[name] ?? "error"
       const level = Array.isArray(setting) ? (setting[0] ?? "error") : setting
@@ -1519,10 +1517,11 @@ function nextScripts(value: JsonValue | undefined) {
 }
 
 async function chooseFile(root: string, names: string[], fallback?: string) {
-  const matches: string[] = []
+  const existing = await Promise.all(
+    names.map((name) => existingFile(root, name)),
+  )
 
-  for (const name of names)
-    if (await existingFile(root, name)) matches.push(name)
+  const matches = names.filter((_, index) => existing[index])
 
   if (matches.length > 1)
     throw new Error(`Ambiguous configuration: ${matches.join(", ")}`)
@@ -1619,8 +1618,11 @@ export async function initProject(
     }
   }
 
-  const packageRun = await packageRunner(root, options.run)
-  const uiRun = await packageRunner(uiRoot, options.run)
+  const [packageRun, uiRun] = await Promise.all([
+    packageRunner(root, options.run),
+    packageRunner(uiRoot, options.run),
+  ])
+
   const edits = new Map<string, { before: string | null; after: string }>()
 
   const plannedFiles: {

package/src/install.ts

@@ -490,26 +490,34 @@ export async function writeFiles(
   }
 
   try {
-    for (const [path, change] of changes) {
-      const exists = await existingFile(root, path)
-      const before = exists ? await readFile(join(root, path)) : null
-
-      if ((before?.toString("utf8") ?? null) !== change.before) {
-        throw new Error(`File changed before commit: ${path}`)
-      }
-
-      const mode = exists ? (await lstat(join(root, path))).mode & 0o7777 : null
-      const after = change.after === null ? null : Buffer.from(change.after)
-      staged.push({
-        path,
-        before,
-        after,
-        mode,
-        afterMode: mode,
-        changed: change.before !== change.after,
-        directory: null,
-      })
-    }
+    staged.push(
+      ...(await Promise.all(
+        [...changes].map(async ([path, change]): Promise<StagedFile> => {
+          const exists = await existingFile(root, path)
+          const before = exists ? await readFile(join(root, path)) : null
+
+          if ((before?.toString("utf8") ?? null) !== change.before) {
+            throw new Error(`File changed before commit: ${path}`)
+          }
+
+          const mode = exists
+            ? (await lstat(join(root, path))).mode & 0o7777
+            : null
+
+          const after = change.after === null ? null : Buffer.from(change.after)
+
+          return {
+            path,
+            before,
+            after,
+            mode,
+            afterMode: mode,
+            changed: change.before !== change.after,
+            directory: null,
+          }
+        }),
+      )),
+    )
 
     for (const file of staged) {
       if (!file.changed) continue
@@ -535,7 +543,9 @@ export async function writeFiles(
 
     await prepare?.()
 
-    for (const file of staged) await verify(file, file.before, file.mode)
+    await Promise.all(
+      staged.map((file) => verify(file, file.before, file.mode)),
+    )
 
     for (const file of staged) {
       if (!file.changed) continue
@@ -737,10 +747,16 @@ export async function planInstall(name: string, options: InstallOptions = {}) {
     manifest.provenance[path] = { registryUrl, items: ownership }
   }
 
-  for (const [path, file] of files) {
-    const exists = await existingFile(root, path)
+  const currentFiles = await Promise.all(
+    [...files].map(async ([path, file]) => {
+      const exists = await existingFile(root, path)
+      const before = exists ? await readFile(join(root, path), "utf8") : null
+
+      return { path, file, before }
+    }),
+  )
 
-    const before = exists ? await readFile(join(root, path), "utf8") : null
+  for (const { path, file, before } of currentFiles) {
     const current = before === null ? null : hash(before)
     changes.set(path, { before, after: before })
     const previous = manifest.files[path]

package/src/project.ts

@@ -166,8 +166,12 @@ async function packageManager(root: string) {
     ["yarn", "yarn.lock"],
   ]
 
-  for (const [manager, path] of locks) {
-    if (await existingFile(root, path)) found.add(manager)
+  const existingLocks = await Promise.all(
+    locks.map(([, path]) => existingFile(root, path)),
+  )
+
+  for (const [index, [manager]] of locks.entries()) {
+    if (existingLocks[index]) found.add(manager)
   }
 
   if (found.size > 1) {
@@ -184,8 +188,12 @@ export async function packageRunner(
   run?: InstallOptions["run"],
 ): Promise<NonNullable<InstallOptions["run"]>> {
   const target = await realpath(root)
-  const owner = await workspaceRoot(target)
-  const local = await packageManager(target)
+
+  const [owner, local] = await Promise.all([
+    workspaceRoot(target),
+    packageManager(target),
+  ])
+
   const workspace = owner === target ? local : await packageManager(owner)
 
   if (local && workspace && local !== workspace) {