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

package/README.md

@@ -10,12 +10,35 @@ npm install --save-dev @archon-research/uikit-cli
 
 ## Usage
 
+### Run lint and format tools without downstream installs
+
+From any consumer workspace:
+
+```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
+```
+
+The CLI runs pinned `oxlint` and `oxfmt` versions internally, so downstream workspaces do not
+need to declare those tool packages directly.
+
+### Register local uikit packages for downstream consumers
+
+From the uikit repository:
+
+```bash
+uikit-cli register
+```
+
+This registers local public `@archon-research/*` packages globally via `npm link`, so downstream
+consumer repositories can link by package name without needing package paths.
+
 ### Link uikit packages into a consumer repository
 
 From your consumer repository:
 
 ```bash
-npm run uikit:link
+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.
@@ -36,19 +59,21 @@ Add this script to your consumer's `package.json`:
 When co-development is complete, restore published versions from npm:
 
 ```bash
-npm run uikit:unlink
+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
+2. Linking only consumer workspaces that actually depend on those packages
+3. Reversing links with `unlink`, restoring registry installs when available
 
 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
@@ -57,19 +82,20 @@ The CLI automatically detects the consumer workspace root and all dependent pack
 ## See also
 
 - [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
 
 ## Development workflow
 
 In a synome workspace:
 
 ```bash
+# Optional: run once in uikit repo to pre-register packages
+uikit-cli register
+
 # Link uikit packages for local development
-npm run uikit:link
+uikit-cli link
 
 # Later, restore registry versions (or keep local links if not published)
-npm run uikit:unlink
+uikit-cli unlink
 ```
 
 ## Scripts in synome package.json

package/dist/cli.js

@@ -1,8 +1,13 @@
 #!/usr/bin/env node
 import { execSync } from 'node:child_process';
-import { readFileSync, readdirSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+const OXLINT_VERSION = '1.62.0';
+const OXFMT_VERSION = '0.47.0';
+function shellEscape(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
 function run(command, cwd) {
     console.log(`> (${cwd}) ${command}`);
     execSync(command, { stdio: 'inherit', cwd });
@@ -22,6 +27,52 @@ function tryRun(command, cwd, quiet = false) {
         return false;
     }
 }
+function removeWorkspaceShadowInstall(consumerRoot, workspace, packageName) {
+    const packagePath = path.join(consumerRoot, workspace, 'node_modules', packageName);
+    if (!existsSync(packagePath)) {
+        return;
+    }
+    try {
+        const stats = lstatSync(packagePath);
+        if (stats.isSymbolicLink()) {
+            return;
+        }
+        // Remove workspace-local regular install so Node resolves to linked root package.
+        rmSync(packagePath, { recursive: true, force: true });
+        console.log(`Removed shadow install at ${workspace}/node_modules/${packageName} to preserve local links.`);
+    }
+    catch {
+        // Best effort cleanup; linking may still succeed via root resolution.
+    }
+}
+function ensureLinkedPath(consumerRoot, packageName, expectedTarget) {
+    const packagePath = path.join(consumerRoot, 'node_modules', packageName);
+    try {
+        const stats = lstatSync(packagePath);
+        if (stats.isSymbolicLink() && realpathSync(packagePath) === expectedTarget) {
+            return;
+        }
+        rmSync(packagePath, { recursive: true, force: true });
+    }
+    catch {
+        // Path may not exist yet; continue and create symlink.
+    }
+    mkdirSync(path.dirname(packagePath), { recursive: true });
+    symlinkSync(expectedTarget, packagePath, 'dir');
+}
+function clearWorkspaceViteCache(consumerRoot, workspace) {
+    const viteCachePath = path.join(consumerRoot, workspace, 'node_modules', '.vite');
+    if (!existsSync(viteCachePath)) {
+        return;
+    }
+    try {
+        rmSync(viteCachePath, { recursive: true, force: true });
+        console.log(`Cleared Vite cache at ${workspace}/node_modules/.vite.`);
+    }
+    catch {
+        // Best-effort cache cleanup; linking still succeeds without this.
+    }
+}
 function readJson(filePath) {
     const content = readFileSync(filePath, 'utf8');
     return JSON.parse(content);
@@ -83,21 +134,179 @@ function findConsumerRoot(startDir) {
         current = parent;
     }
 }
+function findUIKitRoot(startDir) {
+    let current = startDir;
+    while (true) {
+        if (isValidUIKitRoot(current)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function isValidUIKitRoot(rootDir) {
+    try {
+        const pkgPath = path.join(rootDir, 'package.json');
+        const pkg = readJson(pkgPath);
+        if (!pkg.workspaces) {
+            return false;
+        }
+        const workspaces = loadWorkspaces(rootDir);
+        return workspaces.some((ws) => ws.name === '@archon-research/design-system');
+    }
+    catch {
+        return false;
+    }
+}
+function findUIKitRootFromConsumer(consumerRoot) {
+    const candidateNames = ['uikit'];
+    let current = consumerRoot;
+    while (true) {
+        for (const candidateName of candidateNames) {
+            const candidate = path.join(current, candidateName);
+            if (isValidUIKitRoot(candidate)) {
+                return candidate;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function resolveUIKitRoot(explicitUIKitRoot, consumerRoot) {
+    if (explicitUIKitRoot) {
+        const resolved = path.resolve(process.cwd(), explicitUIKitRoot);
+        if (!isValidUIKitRoot(resolved)) {
+            throw new Error(`Invalid uikit root: ${resolved}. Expected a workspace root containing @archon-research/design-system.`);
+        }
+        return resolved;
+    }
+    const scriptRelativeRoot = path.resolve(scriptDir, '../../..');
+    if (isValidUIKitRoot(scriptRelativeRoot)) {
+        return scriptRelativeRoot;
+    }
+    if (consumerRoot) {
+        const discovered = findUIKitRootFromConsumer(consumerRoot);
+        if (discovered) {
+            return discovered;
+        }
+    }
+    const fromCwd = findUIKitRoot(process.cwd());
+    if (fromCwd) {
+        return fromCwd;
+    }
+    throw new Error('Could not locate local uikit workspace automatically. Run from a consumer workspace near your uikit checkout, or pass --uikit-root / set UIKIT_ROOT.');
+}
 function parseArgs(argv) {
     const args = argv.slice(2);
-    const mode = args[0] === 'unlink' ? 'unlink' : 'link';
+    const command = args[0];
+    let mode;
+    if (!command || command === 'link') {
+        mode = 'link';
+    }
+    else if (command === 'unlink') {
+        mode = 'unlink';
+    }
+    else if (command === 'register') {
+        mode = 'register';
+    }
+    else if (command === 'lint') {
+        mode = 'lint';
+    }
+    else if (command === 'format') {
+        mode = 'format';
+    }
+    else {
+        throw new Error(`Unknown command: ${command}. Expected one of: link, unlink, register, lint, format.`);
+    }
+    const commandArgs = args.slice(1);
     let consumerRoot = null;
+    let uikitRoot = process.env.UIKIT_ROOT ?? null;
     for (let i = 1; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === '--consumer-root' && args[i + 1]) {
             consumerRoot = path.resolve(process.cwd(), args[i + 1]);
             i += 1;
+            continue;
+        }
+        if (arg === '--uikit-root' && args[i + 1]) {
+            uikitRoot = args[i + 1];
+            i += 1;
         }
     }
-    if (!consumerRoot) {
+    if (mode !== 'register' &&
+        mode !== 'lint' &&
+        mode !== 'format' &&
+        !consumerRoot) {
         consumerRoot = findConsumerRoot(process.cwd());
     }
-    return { mode, consumerRoot };
+    if (mode === 'lint' || mode === 'format') {
+        return {
+            mode,
+            consumerRoot: null,
+            uikitRoot: '',
+            commandArgs,
+        };
+    }
+    return {
+        mode,
+        consumerRoot,
+        uikitRoot: resolveUIKitRoot(uikitRoot, consumerRoot),
+        commandArgs,
+    };
+}
+function runLint(commandArgs) {
+    const forwarded = commandArgs.map(shellEscape).join(' ');
+    run(`npm exec --yes --package oxlint@${OXLINT_VERSION} -- oxlint ${forwarded}`.trim(), process.cwd());
+}
+function hasConfigFlag(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '-c' || arg === '--config' || arg.startsWith('--config=')) {
+            return true;
+        }
+    }
+    return false;
+}
+function runFormat(commandArgs) {
+    const args = [...commandArgs];
+    const defaultConfig = './.oxfmtrc.ts';
+    if (!hasConfigFlag(args) && existsSync(path.join(process.cwd(), '.oxfmtrc.ts'))) {
+        args.unshift(defaultConfig);
+        args.unshift('-c');
+    }
+    const forwarded = args.map(shellEscape).join(' ');
+    run(`npm exec --yes --package oxfmt@${OXFMT_VERSION} -- oxfmt ${forwarded}`.trim(), process.cwd());
+}
+function registerLocalPackages(uikitRoot, supportedNames) {
+    const uikitWorkspaces = loadWorkspaces(uikitRoot);
+    const uikitPackages = uikitWorkspaces.filter((ws) => String(ws.name ?? '').startsWith('@archon-research/') &&
+        !ws.private &&
+        (!supportedNames || supportedNames.has(String(ws.name))));
+    if (uikitPackages.length === 0) {
+        console.log('No public @archon-research packages found in this uikit workspace.');
+        return;
+    }
+    for (const pkg of uikitPackages) {
+        if (!pkg.name) {
+            continue;
+        }
+        // Ensure CLI bin target exists before linking globally.
+        if (pkg.name === '@archon-research/uikit-cli' &&
+            !existsSync(path.join(pkg.path, 'dist', 'cli.js'))) {
+            run('npm run build', pkg.path);
+        }
+        run('npm link', pkg.path);
+    }
+    console.log('\nRegistered local uikit packages for downstream consumers.');
+}
+function linkCliIntoConsumer(consumerRoot) {
+    run('npm link "@archon-research/uikit-cli" --package-lock=false --save=false', consumerRoot);
 }
 function collectWorkspaceRequirements(workspaces, supportedNames) {
     const neededByWorkspace = new Map();
@@ -133,24 +342,30 @@ function linkLocalPackages(consumerRoot, neededByWorkspace, dirByName) {
             allNames.add(name);
         }
     }
-    const rootPackageArgs = [...allNames]
-        .map((name) => dirByName.get(name))
-        .filter((pkgDir) => Boolean(pkgDir))
-        .map((pkgDir) => `"${pkgDir}"`)
-        .join(' ');
+    const rootPackageArgs = [...allNames].map((name) => `"${name}"`).join(' ');
     if (rootPackageArgs) {
         run(`npm link ${rootPackageArgs} --package-lock=false --save=false`, consumerRoot);
     }
+    // npm can materialize regular installs in some workspace setups; enforce root links.
+    for (const name of allNames) {
+        const target = dirByName.get(name);
+        if (!target) {
+            continue;
+        }
+        ensureLinkedPath(consumerRoot, name, target);
+    }
     for (const [workspace, names] of neededByWorkspace.entries()) {
-        const packageArgs = names
-            .map((name) => dirByName.get(name))
-            .filter((pkgDir) => Boolean(pkgDir))
-            .map((pkgDir) => `"${pkgDir}"`)
-            .join(' ');
+        const packageArgs = names.map((name) => `"${name}"`).join(' ');
         if (!packageArgs) {
             continue;
         }
         run(`npm link ${packageArgs} --workspace "${workspace}" --package-lock=false --save=false`, consumerRoot);
+        // npm --workspace link can leave a regular install in some workspace layouts.
+        // Removing workspace shadow installs keeps resolution aligned to linked root packages.
+        for (const name of names) {
+            removeWorkspaceShadowInstall(consumerRoot, workspace, name);
+        }
+        clearWorkspaceViteCache(consumerRoot, workspace);
     }
 }
 function unlinkLocalPackages(consumerRoot, neededByWorkspace) {
@@ -171,12 +386,19 @@ function unlinkLocalPackages(consumerRoot, neededByWorkspace) {
         }
     }
     for (const [workspace, names] of neededByWorkspace.entries()) {
+        const workspaceDir = path.join(consumerRoot, workspace);
         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.`);
             }
+            // Fallback for cases where --workspace unlink does not clear workspace-local links.
+            const fallbackOk = tryRun(`npm unlink "${name}" --package-lock=false --save=false`, workspaceDir, true);
+            if (!fallbackOk) {
+                console.warn(`Unable to unlink ${name} directly in ${workspace}; continuing with restore flow.`);
+            }
         }
+        clearWorkspaceViteCache(consumerRoot, workspace);
     }
 }
 function areRegistryPackagesReady(consumerRoot, neededByWorkspace) {
@@ -206,9 +428,23 @@ function arePackagesPublished(consumerRoot, neededByWorkspace) {
     return true;
 }
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-const uikitRoot = path.resolve(scriptDir, '../../..');
 try {
-    const { mode, consumerRoot } = parseArgs(process.argv);
+    const { mode, consumerRoot, uikitRoot, commandArgs } = parseArgs(process.argv);
+    if (mode === 'lint') {
+        runLint(commandArgs);
+        process.exit(0);
+    }
+    if (mode === 'format') {
+        runFormat(commandArgs);
+        process.exit(0);
+    }
+    if (mode === 'register') {
+        registerLocalPackages(uikitRoot);
+        process.exit(0);
+    }
+    if (!consumerRoot) {
+        throw new Error('Consumer root is required for link/unlink operations.');
+    }
     const uikitWorkspaces = loadWorkspaces(uikitRoot);
     const consumerWorkspaces = loadWorkspaces(consumerRoot);
     const uikitPackages = uikitWorkspaces.filter((ws) => String(ws.name ?? '').startsWith('@archon-research/'));
@@ -216,6 +452,8 @@ try {
     dirByName.delete('');
     const supportedNames = new Set(dirByName.keys());
     const neededByWorkspace = collectWorkspaceRequirements(consumerWorkspaces, supportedNames);
+    registerLocalPackages(uikitRoot, supportedNames);
+    linkCliIntoConsumer(consumerRoot);
     if (mode === 'link') {
         linkLocalPackages(consumerRoot, neededByWorkspace, dirByName);
         console.log('\nLinked local uikit packages into consumer workspaces.');
@@ -241,6 +479,8 @@ try {
         console.warn('\nRegistry packages are not fully resolvable; falling back to local uikit linking.');
         linkLocalPackages(consumerRoot, neededByWorkspace, dirByName);
     }
+    // Keep consumer on the local CLI implementation so repeated link/unlink stays stable.
+    linkCliIntoConsumer(consumerRoot);
     console.log('\nUnlinked local uikit packages and restored consumer dependencies.');
 }
 catch (error) {

package/package.json

@@ -1,5 +1,6 @@
 {
   "name": "@archon-research/uikit-cli",
+  "version": "0.3.0-rohit-improve-cli.2",
   "type": "module",
   "description": "CLI for managing local uikit package linking in consumer workspaces",
   "scripts": {
@@ -21,7 +22,6 @@
   "files": [
     "dist"
   ],
-  "version": "0.2.2",
   "repository": {
     "url": "https://github.com/archon-research/uikit"
   }