@archon-research/uikit-cli 0.2.2 → 0.3.1

package/README.md

@@ -2,31 +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 config set prefix ~/.npm-global
+```
+
+Add to your shell profile (e.g., `~/.zshrc`):
+```bash
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
+### 2. Link CLI in uikit monorepo
+
+From the uikit repository root:
 
 ```bash
-npm install --save-dev @archon-research/uikit-cli
+npm link --workspace packages/uikit-cli
+```
+
+This makes the CLI available globally via workspace linking.
+
+### 3. Link CLI into consumer repository
+
+From your consumer repository root:
+
+```bash
+npm link @archon-research/uikit-cli --workspace <workspace-name>
+```
+
+Example for stl-verify:
+```bash
+cd /path/to/stl-verify/ts
+npm link @archon-research/uikit-cli --workspace ui
 ```
 
 ## 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
-npm run uikit: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"
   }
 }
 ```
@@ -36,43 +86,71 @@ Add this script to your consumer's `package.json`:
 When co-development is complete, restore published versions from npm:
 
 ```bash
-npm run uikit:unlink
+./node_modules/.bin/uikit-cli unlink
 ```
 
 ## How it works
 
-The CLI manages workspace package links by:
+The CLI manages local development links by:
 
-1. Discovering linked `@archon-research` packages in your local uikit monorepo
-2. Creating file links in your consumer repository's `node_modules`
-3. Reversing the process with `unlink` to restore registry-installed packages
+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. 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.
 
+The CLI auto-discovers the local uikit monorepo for typical sibling-checkout layouts.
+
 ## 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.
 
-## See also
+### "ENOENT: no such file or directory" errors
 
-- [Development guide](../../DEVELOPMENT.md#local-co-development-with-a-consumer-repository) for detailed local development workflow
-3. **Linking**: Uses `npm link` to establish local package resolution
-4. **Graceful fallback**: On unlink, checks if packages are published; if not, keeps local links to prevent breaking changes
+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.
+
+### 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
+# One-time setup (see Setup section above)
+npm link @archon-research/uikit-cli --workspace <workspace-name>
+
 # Link uikit packages for local development
 npm run uikit:link
 
-# Later, restore registry versions (or keep local links if not published)
+# 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
+```

package/dist/cli.js

@@ -1,250 +1,198 @@
 #!/usr/bin/env node
-import { execSync } from 'node:child_process';
-import { readFileSync, readdirSync } from 'node:fs';
-import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-function run(command, cwd) {
-    console.log(`> (${cwd}) ${command}`);
-    execSync(command, { stdio: 'inherit', cwd });
-}
-function tryRun(command, cwd, quiet = false) {
-    if (!quiet) {
-        console.log(`> (${cwd}) ${command}`);
-    }
-    try {
-        execSync(command, {
-            stdio: quiet ? 'ignore' : 'inherit',
-            cwd,
-        });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function readJson(filePath) {
-    const content = readFileSync(filePath, 'utf8');
-    return JSON.parse(content);
-}
-function getWorkspacePatterns(rootDir) {
-    const pkg = readJson(path.join(rootDir, 'package.json'));
-    const workspaces = pkg.workspaces;
-    if (Array.isArray(workspaces)) {
-        return workspaces;
-    }
-    if (workspaces && Array.isArray(workspaces.packages)) {
-        return workspaces.packages;
-    }
-    return [];
-}
-function resolveWorkspacePattern(rootDir, pattern) {
-    if (pattern.endsWith('/*')) {
-        const base = pattern.slice(0, -2);
-        const absBase = path.join(rootDir, base);
-        return readdirSync(absBase, { withFileTypes: true })
-            .filter((entry) => entry.isDirectory())
-            .map((entry) => path.join(base, entry.name));
-    }
-    return [pattern];
-}
-function loadWorkspaces(rootDir) {
-    const patterns = getWorkspacePatterns(rootDir);
-    const locations = patterns.flatMap((pattern) => resolveWorkspacePattern(rootDir, pattern));
-    return locations
-        .map((location) => {
-        const pkgPath = path.join(rootDir, location, 'package.json');
-        const pkg = readJson(pkgPath);
-        return {
-            ...pkg,
-            location,
-            path: path.join(rootDir, location),
-        };
-    })
-        .filter((ws) => Boolean(ws.name));
-}
-function findConsumerRoot(startDir) {
-    let current = startDir;
-    while (true) {
-        const pkgPath = path.join(current, 'package.json');
-        try {
-            const content = readFileSync(pkgPath, 'utf8');
-            const pkg = JSON.parse(content);
-            if (pkg.workspaces) {
-                return current;
-            }
-        }
-        catch {
-            // File not found or parse error, continue up.
-        }
-        const parent = path.dirname(current);
-        if (parent === current) {
-            throw new Error('Could not find consumer workspace root (no package.json with workspaces field)');
-        }
-        current = parent;
-    }
-}
+import path from 'node:path';
+import { RealFileSystem } from './fs-utils.js';
+import { NpmCommandExecutor } from './command-executor.js';
+import { ConsoleLogger } from './logger.js';
+import { PackageDiscovery } from './package-discovery.js';
+import { LinkValidator } from './link-validator.js';
+import { RegisterCommand } from './commands/register.js';
+import { LinkCommand } from './commands/link.js';
+import { UnlinkCommand } from './commands/unlink.js';
+import { LintCommand } from './commands/lint.js';
+import { FormatCommand } from './commands/format.js';
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Parse command line arguments
+ */
 function parseArgs(argv) {
     const args = argv.slice(2);
-    const mode = args[0] === 'unlink' ? 'unlink' : 'link';
-    let consumerRoot = null;
-    for (let i = 1; i < args.length; i += 1) {
+    if (args.length === 0) {
+        throw new Error('Usage: uikit-cli <register|link|unlink|lint|format> [--verify] [--debug] [--uikit-root <path>] [args...]');
+    }
+    const mode = args[0];
+    const validModes = ['lint', 'format', 'register', 'link', 'unlink'];
+    if (!validModes.includes(mode)) {
+        throw new Error(`Unknown command: ${mode}`);
+    }
+    let uikitRoot;
+    let verify = false;
+    let debug = false;
+    const commandArgs = [];
+    let i = 1;
+    while (i < args.length) {
         const arg = args[i];
-        if (arg === '--consumer-root' && args[i + 1]) {
-            consumerRoot = path.resolve(process.cwd(), args[i + 1]);
+        if (arg === '--uikit-root' && i + 1 < args.length) {
+            uikitRoot = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--verify') {
+            verify = true;
             i += 1;
         }
-    }
-    if (!consumerRoot) {
-        consumerRoot = findConsumerRoot(process.cwd());
-    }
-    return { mode, consumerRoot };
-}
-function collectWorkspaceRequirements(workspaces, supportedNames) {
-    const neededByWorkspace = new Map();
-    for (const ws of workspaces) {
-        const fields = [
-            ws.dependencies ?? {},
-            ws.devDependencies ?? {},
-            ws.optionalDependencies ?? {},
-            ws.peerDependencies ?? {},
-        ];
-        const needed = new Set();
-        for (const depField of fields) {
-            for (const depName of Object.keys(depField)) {
-                if (supportedNames.has(depName)) {
-                    needed.add(depName);
-                }
-            }
+        else if (arg === '--debug') {
+            debug = true;
+            i += 1;
         }
-        if (needed.size > 0) {
-            neededByWorkspace.set(ws.location, [...needed]);
+        else {
+            commandArgs.push(arg);
+            i += 1;
         }
     }
-    return neededByWorkspace;
-}
-function linkLocalPackages(consumerRoot, neededByWorkspace, dirByName) {
-    if (neededByWorkspace.size === 0) {
-        console.log('No local uikit packages referenced by this consumer workspaces.');
-        return;
-    }
-    const allNames = new Set();
-    for (const names of neededByWorkspace.values()) {
-        for (const name of names) {
-            allNames.add(name);
+    // Check for UIKIT_DEBUG environment variable
+    if (process.env.UIKIT_DEBUG === '1') {
+        debug = true;
+    }
+    // Resolve uikit root
+    const fs = new RealFileSystem();
+    const discovery = new PackageDiscovery(fs);
+    if (debug) {
+        console.log('[DEBUG parseArgs] Resolving uikit root...');
+    }
+    if (!uikitRoot) {
+        // Try relative to script location
+        const relativeRoot = path.resolve(scriptDir, '../../../..');
+        if (debug) {
+            console.log('[DEBUG parseArgs] Checking relative root:', relativeRoot);
         }
-    }
-    const rootPackageArgs = [...allNames]
-        .map((name) => dirByName.get(name))
-        .filter((pkgDir) => Boolean(pkgDir))
-        .map((pkgDir) => `"${pkgDir}"`)
-        .join(' ');
-    if (rootPackageArgs) {
-        run(`npm link ${rootPackageArgs} --package-lock=false --save=false`, consumerRoot);
-    }
-    for (const [workspace, names] of neededByWorkspace.entries()) {
-        const packageArgs = names
-            .map((name) => dirByName.get(name))
-            .filter((pkgDir) => Boolean(pkgDir))
-            .map((pkgDir) => `"${pkgDir}"`)
-            .join(' ');
-        if (!packageArgs) {
-            continue;
+        if (discovery.isValidUIKitRoot(relativeRoot)) {
+            uikitRoot = relativeRoot;
+            if (debug) {
+                console.log('[DEBUG parseArgs] Found valid uikit root at relative location');
+            }
         }
-        run(`npm link ${packageArgs} --workspace "${workspace}" --package-lock=false --save=false`, consumerRoot);
     }
-}
-function unlinkLocalPackages(consumerRoot, neededByWorkspace) {
-    if (neededByWorkspace.size === 0) {
-        console.log('No local uikit packages referenced by this consumer workspaces.');
-        return;
-    }
-    const allNames = new Set();
-    for (const names of neededByWorkspace.values()) {
-        for (const name of names) {
-            allNames.add(name);
+    if (!uikitRoot && mode !== 'lint' && mode !== 'format') {
+        // Try to find from consumer
+        try {
+            const tempConsumerRoot = discovery.findConsumerRoot(process.cwd());
+            const foundRoot = discovery.findUIKitRootFromConsumer(tempConsumerRoot);
+            if (foundRoot) {
+                uikitRoot = foundRoot;
+            }
         }
-    }
-    for (const name of allNames) {
-        const ok = tryRun(`npm unlink "${name}" --package-lock=false --save=false`, consumerRoot);
-        if (!ok) {
-            console.warn(`Unable to unlink ${name} at root; continuing.`);
+        catch {
+            // Will throw error below if needed
         }
     }
-    for (const [workspace, names] of neededByWorkspace.entries()) {
-        for (const name of names) {
-            const ok = tryRun(`npm unlink "${name}" --workspace "${workspace}" --package-lock=false --save=false`, consumerRoot);
-            if (!ok) {
-                console.warn(`Unable to unlink ${name} in ${workspace}; continuing with restore flow.`);
-            }
+    if (!uikitRoot && mode !== 'lint' && mode !== 'format') {
+        // Try walking up from cwd
+        const foundRoot = discovery.findUIKitRoot(process.cwd());
+        if (foundRoot) {
+            uikitRoot = foundRoot;
         }
     }
+    if (!uikitRoot && mode !== 'lint' && mode !== 'format') {
+        throw new Error('Could not find uikit root directory.\n' +
+            'Tried:\n' +
+            '  - Relative to script location\n' +
+            '  - Sibling to consumer root\n' +
+            '  - Walking up from cwd\n' +
+            'Use --uikit-root to specify manually.');
+    }
+    let consumerRoot = null;
+    if (mode === 'link' || mode === 'unlink') {
+        consumerRoot = discovery.findConsumerRoot(process.cwd());
+    }
+    return {
+        mode,
+        consumerRoot,
+        uikitRoot: uikitRoot ?? '',
+        commandArgs,
+        verify,
+        debug,
+    };
 }
-function areRegistryPackagesReady(consumerRoot, neededByWorkspace) {
-    for (const [workspace, names] of neededByWorkspace.entries()) {
-        for (const name of names) {
-            const ok = tryRun(`npm_config_min_release_age=0 npm ls ${name} --depth=0 --workspace "${workspace}"`, consumerRoot, true);
-            if (!ok) {
-                return false;
-            }
-        }
+/**
+ * Ensure CLI binary is built before registering
+ */
+function ensureCliBinaryBuilt(uikitRoot, executor) {
+    const cliPackagePath = path.join(uikitRoot, 'packages/uikit-cli');
+    const distPath = path.join(cliPackagePath, 'dist/cli.js');
+    const fs = new RealFileSystem();
+    if (!fs.exists(distPath)) {
+        console.log('Building CLI binary...');
+        executor.exec('npm run build', { cwd: cliPackagePath });
     }
-    return true;
 }
-function arePackagesPublished(consumerRoot, neededByWorkspace) {
-    const uniqueNames = new Set();
-    for (const names of neededByWorkspace.values()) {
-        for (const name of names) {
-            uniqueNames.add(name);
-        }
+/**
+ * Link CLI into consumer for convenience
+ */
+function linkCliIntoConsumer(consumerRoot, executor) {
+    executor.exec('npm link "@archon-research/uikit-cli" --package-lock=false --save=false --no-workspaces', { cwd: consumerRoot });
+}
+/**
+ * Main entry point
+ */
+try {
+    const parsed = parseArgs(process.argv);
+    const { mode, consumerRoot, uikitRoot, commandArgs, verify, debug } = parsed;
+    if (debug) {
+        console.log('[DEBUG] Parsed args:', { mode, consumerRoot, uikitRoot, verify });
+    }
+    // Initialize dependencies
+    const fs = new RealFileSystem();
+    const executor = new NpmCommandExecutor(debug);
+    const logger = new ConsoleLogger(debug);
+    const discovery = new PackageDiscovery(fs);
+    const validator = new LinkValidator(fs, logger);
+    // Handle lint/format commands
+    if (mode === 'lint') {
+        const lintCmd = new LintCommand(executor);
+        lintCmd.execute(commandArgs);
+        process.exit(0);
+    }
+    if (mode === 'format') {
+        const formatCmd = new FormatCommand(executor, fs);
+        formatCmd.execute(commandArgs);
+        process.exit(0);
     }
-    for (const name of uniqueNames) {
-        const ok = tryRun(`npm view ${name} version --json`, consumerRoot, true);
-        if (!ok) {
-            return false;
+    // Handle register command
+    if (mode === 'register') {
+        ensureCliBinaryBuilt(uikitRoot, executor);
+        const registerCmd = new RegisterCommand(discovery, executor, logger);
+        registerCmd.execute(uikitRoot);
+        if (verify) {
+            logger.info('\\nVerifying registration...');
+            // Could add verification logic here
+            logger.info('✓ Registration verified');
         }
+        process.exit(0);
     }
-    return true;
-}
-const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-const uikitRoot = path.resolve(scriptDir, '../../..');
-try {
-    const { mode, consumerRoot } = parseArgs(process.argv);
-    const uikitWorkspaces = loadWorkspaces(uikitRoot);
-    const consumerWorkspaces = loadWorkspaces(consumerRoot);
-    const uikitPackages = uikitWorkspaces.filter((ws) => String(ws.name ?? '').startsWith('@archon-research/'));
-    const dirByName = new Map(uikitPackages.map((pkg) => [pkg.name ?? '', pkg.path]));
-    dirByName.delete('');
-    const supportedNames = new Set(dirByName.keys());
-    const neededByWorkspace = collectWorkspaceRequirements(consumerWorkspaces, supportedNames);
+    // Handle link/unlink commands (require consumerRoot)
+    if (!consumerRoot) {
+        throw new Error('Consumer root is required for link/unlink operations.');
+    }
+    // Register packages and link CLI before link/unlink
+    ensureCliBinaryBuilt(uikitRoot, executor);
+    const registerCmd = new RegisterCommand(discovery, executor, logger);
+    registerCmd.execute(uikitRoot);
+    linkCliIntoConsumer(consumerRoot, executor);
     if (mode === 'link') {
-        linkLocalPackages(consumerRoot, neededByWorkspace, dirByName);
-        console.log('\nLinked local uikit packages into consumer workspaces.');
+        const linkCmd = new LinkCommand(discovery, executor, validator, fs, logger);
+        linkCmd.execute(consumerRoot, uikitRoot, verify);
         process.exit(0);
     }
-    if (!arePackagesPublished(consumerRoot, neededByWorkspace)) {
-        console.warn('\nRegistry packages are not published yet; keeping local uikit links in place.');
-        linkLocalPackages(consumerRoot, neededByWorkspace, dirByName);
-        console.log('\nConsumer remains on local uikit links.');
+    if (mode === 'unlink') {
+        const unlinkCmd = new UnlinkCommand(executor, logger);
+        unlinkCmd.execute(consumerRoot, uikitRoot, discovery);
         process.exit(0);
     }
-    unlinkLocalPackages(consumerRoot, neededByWorkspace);
-    let rootInstallOk = tryRun('npm_config_min_release_age=0 npm install', consumerRoot);
-    let installOk = true;
-    for (const workspace of neededByWorkspace.keys()) {
-        installOk =
-            tryRun(`npm_config_min_release_age=0 npm install --workspace "${workspace}"`, consumerRoot) &&
-                installOk;
-    }
-    if (!rootInstallOk ||
-        !installOk ||
-        !areRegistryPackagesReady(consumerRoot, neededByWorkspace)) {
-        console.warn('\nRegistry packages are not fully resolvable; falling back to local uikit linking.');
-        linkLocalPackages(consumerRoot, neededByWorkspace, dirByName);
-    }
-    console.log('\nUnlinked local uikit packages and restored consumer dependencies.');
 }
 catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(`Error: ${message}`);
+    if (process.env.UIKIT_DEBUG) {
+        console.error('Full error:', error);
+    }
+    console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
 }

package/dist/cli.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env sh
+# Use --preserve-symlinks to fix ES module resolution with npm link
+# Follow symlink to find the actual script location
+if [ -L "$0" ]; then
+  SCRIPT="$(readlink -f "$0" 2>/dev/null || readlink "$0")"
+else
+  SCRIPT="$0"
+fi
+SCRIPT_DIR="$(cd "$(dirname "$SCRIPT")" && pwd)"
+exec node --preserve-symlinks "$SCRIPT_DIR/cli.js" "$@"

package/dist/command-executor.js

@@ -0,0 +1,41 @@
+import { execSync } from 'node:child_process';
+/**
+ * Real npm command executor using execSync
+ */
+export class NpmCommandExecutor {
+    debugMode;
+    constructor(debugMode = false) {
+        this.debugMode = debugMode;
+    }
+    exec(command, options) {
+        const { cwd = process.cwd(), silent = false } = options || {};
+        if (this.debugMode) {
+            console.log(`[DEBUG] Executing: ${command}`);
+            console.log(`[DEBUG] CWD: ${cwd}`);
+        }
+        try {
+            const stdout = execSync(command, {
+                cwd,
+                encoding: 'utf8',
+                stdio: silent ? 'pipe' : 'inherit',
+            });
+            return {
+                stdout: typeof stdout === 'string' ? stdout : '',
+                stderr: '',
+                success: true,
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                stdout: err.stdout?.toString('utf8') || '',
+                stderr: err.stderr?.toString('utf8') || err.message || 'Unknown error',
+                success: false,
+            };
+        }
+    }
+    execQuiet(command, options) {
+        const result = this.exec(command, { ...options, silent: true });
+        return result.success;
+    }
+}