@archon-research/uikit-cli 0.3.0-rohit-improve-cli.2 → 0.3.1

package/README.md

@@ -2,54 +2,81 @@
 
 CLI tool for local package linking during active development with consumer repositories.
 
-## Installation
+## Setup (One-time)
+
+### 1. Configure npm prefix for writable global packages
+
+If using nix-managed Node.js, configure npm to use a writable location:
 
 ```bash
-npm install --save-dev @archon-research/uikit-cli
+npm config set prefix ~/.npm-global
 ```
 
-## Usage
+Add to your shell profile (e.g., `~/.zshrc`):
+```bash
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
 
-### Run lint and format tools without downstream installs
+### 2. Link CLI in uikit monorepo
 
-From any consumer workspace:
+From the uikit repository root:
 
 ```bash
-uikit-cli lint -c ./.oxlintrc.ts src panda.config.ts vite.config.ts
-uikit-cli format -c ./.oxfmtrc.ts --write "src/**/*.ts" "src/**/*.tsx" panda.config.ts vite.config.ts
+npm link --workspace packages/uikit-cli
 ```
 
-The CLI runs pinned `oxlint` and `oxfmt` versions internally, so downstream workspaces do not
-need to declare those tool packages directly.
+This makes the CLI available globally via workspace linking.
+
+### 3. Link CLI into consumer repository
 
-### Register local uikit packages for downstream consumers
+From your consumer repository root:
 
-From the uikit repository:
+```bash
+npm link @archon-research/uikit-cli --workspace <workspace-name>
+```
 
+Example for stl-verify:
 ```bash
-uikit-cli register
+cd /path/to/stl-verify/ts
+npm link @archon-research/uikit-cli --workspace ui
 ```
 
-This registers local public `@archon-research/*` packages globally via `npm link`, so downstream
-consumer repositories can link by package name without needing package paths.
+## Usage
+
+### Run lint and format tools without downstream installs
+
+From any consumer workspace:
+
+```bash
+./node_modules/.bin/uikit-cli lint -c ./.oxlintrc.ts src panda.config.ts vite.config.ts
+./node_modules/.bin/uikit-cli format -c ./.oxfmtrc.ts --write "src/**/*.ts" "src/**/*.tsx" panda.config.ts vite.config.ts
+```
+
+The CLI runs pinned `oxlint` and `oxfmt` versions internally, so downstream workspaces do not
+need to declare those tool packages directly.
 
 ### Link uikit packages into a consumer repository
 
 From your consumer repository:
 
 ```bash
-uikit-cli link
+./node_modules/.bin/uikit-cli link
 ```
 
 This command links all `@archon-research/*` packages from your local uikit monorepo into your consumer project, allowing you to develop packages and see changes immediately.
 
+Verify links are working:
+```bash
+./node_modules/.bin/uikit-cli link --verify
+```
+
 Add this script to your consumer's `package.json`:
 
 ```json
 {
   "scripts": {
-    "uikit:link": "uikit-cli link",
-    "uikit:unlink": "uikit-cli unlink"
+    "uikit:link": "./node_modules/.bin/uikit-cli link",
+    "uikit:unlink": "./node_modules/.bin/uikit-cli unlink"
   }
 }
 ```
@@ -59,16 +86,17 @@ Add this script to your consumer's `package.json`:
 When co-development is complete, restore published versions from npm:
 
 ```bash
-uikit-cli unlink
+./node_modules/.bin/uikit-cli unlink
 ```
 
 ## How it works
 
 The CLI manages local development links by:
 
-1. Auto-registering local `@archon-research/*` packages from your uikit checkout
+1. Auto-registering local `@archon-research/*` packages from your uikit checkout via `npm link`
 2. Linking only consumer workspaces that actually depend on those packages
-3. Reversing links with `unlink`, restoring registry installs when available
+3. Cleaning up shadow installs and Vite caches to ensure symlinks work correctly
+4. Using `--preserve-symlinks` flag and bundling to avoid ES module resolution issues
 
 The CLI automatically detects the consumer workspace root and all dependent packages, working from any directory within the workspace.
 
@@ -77,28 +105,52 @@ The CLI auto-discovers the local uikit monorepo for typical sibling-checkout lay
 ## Requirements
 
 - Local clone of the uikit monorepo
-- Node.js and npm installed
+- Node.js 24+ and npm installed
+- Writable npm prefix configured (see Setup)
+
+## Troubleshooting
+
+### "EACCES: permission denied" when using npm link
+
+You need to configure npm to use a writable prefix location. See Setup step 1 above.
+
+### "ENOENT: no such file or directory" errors
 
-## See also
+Use the workspace-based linking approach (Setup steps 2-3) instead of global npm link. The CLI bundle includes `--preserve-symlinks` to handle ES module resolution with symlinks.
 
-- [Development guide](../../DEVELOPMENT.md#local-co-development-with-a-consumer-repository) for detailed local development workflow
+### Links not working after linking
+
+Run with `--verify` flag to check link status:
+```bash
+./node_modules/.bin/uikit-cli link --verify
+```
 
 ## Development workflow
 
-In a synome workspace:
+In a consumer workspace:
 
 ```bash
-# Optional: run once in uikit repo to pre-register packages
-uikit-cli register
+# One-time setup (see Setup section above)
+npm link @archon-research/uikit-cli --workspace <workspace-name>
 
 # Link uikit packages for local development
-uikit-cli link
+npm run uikit:link
 
-# Later, restore registry versions (or keep local links if not published)
-uikit-cli unlink
+# Verify links
+npm run uikit:link -- --verify
+
+# Later, restore registry versions
+npm run uikit:unlink
 ```
 
-## Scripts in synome package.json
+## Debug mode
 
-- `uikit:link` — Uses the CLI with auto-detection
-- `uikit:unlink` — Unlinks using the CLI
+Run with debug output:
+```bash
+UIKIT_DEBUG=1 ./node_modules/.bin/uikit-cli link --verify
+```
+
+Or use the `--debug` flag:
+```bash
+./node_modules/.bin/uikit-cli link --debug --verify
+```