@yopem-ui/cli 0.0.2 → 0.1.0

package/README.md

@@ -1,19 +1,137 @@
 # @yopem-ui/cli
 
 Copy Yopem UI components and configure StyleX in an existing React project.
-Requires Bun. Until the registry is deployed, run the docs server on
-`http://localhost:3100` before using the CLI.
+Requires Bun. Registry requests default to `https://ui.yopem.com/r`.
 
 ```sh
 bunx @yopem-ui/cli init
 bunx @yopem-ui/cli add button
 bunx @yopem-ui/cli update button
+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.
+
 `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.
+modified files unless `--force` is supplied. Installed files and their hashes
+are tracked in `ui.json`.
+
+## Dry run
+
+Preview `add` or `update` before installing:
+
+```sh
+bunx @yopem-ui/cli add button --dry-run
+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.
+
+## 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.
+
+For local development, start this repository's docs server with `bun run dev`:
+
+```sh
+bunx @yopem-ui/cli init --registry http://localhost:3100/r
+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).
+
+## 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.
+
+```sh
+bunx @yopem-ui/cli init --cwd apps/web
+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.
+
+```sh
+bunx @yopem-ui/cli init --cwd apps/web --ui ../../packages/ui
+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.
+
+## Development checks
+
+From the repository root, generate registry fixtures and build the lint plugin
+before running CLI tests:
+
+```sh
+bun run registry:build
+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.
 
 ## Licence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yopem-ui/cli",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "CLI for installing Yopem UI source components and StyleX setup",
   "keywords": [
     "cli",
@@ -27,12 +27,14 @@
   "exports": {
     "./cli": "./src/cli.ts",
     "./init": "./src/init.ts",
-    "./install": "./src/install.ts"
+    "./install": "./src/install.ts",
+    "./project": "./src/project.ts"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "test": "bun test ./test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package/src/cli.ts

@@ -1,12 +1,14 @@
 #!/usr/bin/env bun
 
-import type { InitOptions } from "./init"
+import type { InitOptions } from "@yopem-ui/cli/init"
+import type { JsonValue } from "@yopem-ui/cli/install"
 
-import { initProject } from "./init"
-import { installItem } from "./install"
+import { initProject } from "@yopem-ui/cli/init"
+import { installItem, isRecord, isString } from "@yopem-ui/cli/install"
+import { resolve } from "node:path"
 
 const usage =
-  "Usage: yopem-ui init [--framework vite|tanstack-router|tanstack-start|react-router|next|astro] | <add|update> <name> [--force]"
+  "Usage: yopem-ui [--help | --version] | init [--framework vite|tanstack-router|tanstack-start|react-router|next|astro] [--ui <path>] [--cwd <path>] [--registry <URL>] | <add|update> <name> [--force] [--dry-run] [--cwd <path>] [--registry <URL>]"
 
 function isFramework(
   value: string | undefined,
@@ -22,21 +24,78 @@ function isFramework(
 }
 
 export async function runCli(args: string[], options: InitOptions = {}) {
-  const [command, name, ...flags] = args
+  const [command, ...rest] = args
+
+  if (command === undefined || command === "--help" || command === "-h") {
+    if (rest.length) throw new Error(usage)
+    console.info(usage)
+
+    return
+  }
+
+  if (command === "--version" || command === "-v") {
+    if (rest.length) throw new Error(usage)
+
+    const manifest: JsonValue = await Bun.file(
+      new URL("../package.json", import.meta.url),
+    ).json()
+
+    if (!isRecord(manifest) || !isString(manifest.version)) {
+      throw new Error("Invalid CLI package version")
+    }
+
+    console.info(manifest.version)
+
+    return
+  }
+
+  const positional: string[] = []
+  const flags = new Map<string, string>()
+
+  for (let index = 0; index < rest.length; index++) {
+    const argument = rest[index]!
+
+    if (!argument.startsWith("--")) {
+      positional.push(argument)
+      continue
+    }
+
+    if (flags.has(argument)) throw new Error(usage)
+
+    if (argument === "--force" || argument === "--dry-run") {
+      flags.set(argument, "true")
+      continue
+    }
+
+    if (!["--cwd", "--ui", "--framework", "--registry"].includes(argument))
+      throw new Error(usage)
+    const value = rest[++index]
+
+    if (!value || value.startsWith("--")) throw new Error(usage)
+    flags.set(argument, value)
+  }
+
+  const cwd = resolve(options.cwd ?? process.cwd(), flags.get("--cwd") ?? ".")
+  const registryUrl = flags.get("--registry") ?? options.registryUrl
 
   if (command === "init") {
-    const framework = name === "--framework" ? args[2] : undefined
+    if (flags.has("--dry-run") || options.dryRun)
+      throw new Error("--dry-run is not supported for init")
+    const framework = flags.get("--framework")
 
     if (
-      args.length !== 1 &&
-      !(args.length === 3 && name === "--framework" && isFramework(framework))
-    ) {
+      positional.length ||
+      flags.has("--force") ||
+      (framework !== undefined && !isFramework(framework))
+    )
       throw new Error(usage)
-    }
 
     const result = await initProject({
       ...options,
-      framework: isFramework(framework) ? framework : undefined,
+      cwd,
+      registryUrl,
+      ui: flags.get("--ui") ?? options.ui,
+      framework: isFramework(framework) ? framework : options.framework,
     })
 
     console.info(
@@ -48,21 +107,42 @@ export async function runCli(args: string[], options: InitOptions = {}) {
 
   if (
     (command !== "add" && command !== "update") ||
-    !name ||
-    flags.some((flag) => flag !== "--force")
+    positional.length !== 1 ||
+    flags.has("--ui") ||
+    flags.has("--framework")
   ) {
     throw new Error(usage)
   }
 
-  const result = await installItem(name, {
+  const result = await installItem(positional[0]!, {
     ...options,
+    cwd,
+    registryUrl,
     mode: command,
-    force: flags.includes("--force"),
+    force: flags.has("--force"),
+    dryRun: flags.has("--dry-run") || options.dryRun,
   })
 
-  console.info(
-    `Installed ${result.installed} file(s), skipped ${result.skipped}`,
-  )
+  if (result.preview) {
+    const { files, dependencies, devDependencies } = result.preview
+    const labels = { write: "Write", skip: "Skip", conflict: "Conflict" }
+
+    for (const file of files) {
+      console.info(
+        `${labels[file.action]} ${file.reason ?? file.path}${file.forced ? " (forced overwrite)" : ""}`,
+      )
+    }
+
+    console.info(`Runtime dependencies: ${dependencies.join(", ") || "none"}`)
+    console.info(`Dev dependencies: ${devDependencies.join(", ") || "none"}`)
+    console.info(
+      `Dry run: ${files.filter((file) => file.action === "write").length} file write(s), ${files.filter((file) => file.action === "skip").length} skip(s), ${files.filter((file) => file.action === "conflict").length} conflict(s). No files written.`,
+    )
+  } else {
+    console.info(
+      `Installed ${result.installed} file(s), skipped ${result.skipped}`,
+    )
+  }
 
   return result
 }