@archon-research/uikit-cli 0.1.0-dev25004766367

package/README.md

@@ -0,0 +1,69 @@
+# @archon-research/uikit-cli
+
+CLI for managing local uikit package linking in consumer workspaces.
+
+## Installation
+
+Once published to GitHub Packages, install globally:
+
+```bash
+npm install -g @archon-research/uikit-cli
+```
+
+For development, link locally:
+
+```bash
+cd /path/to/uikit/packages/uikit-cli
+npm link
+```
+
+## Usage
+
+### Link local uikit packages
+
+```bash
+uikit-cli link
+```
+
+Automatically detects the consumer workspace root by walking up to the nearest `package.json` with a `workspaces` field. Links all `@archon-research/*` packages that the consumer depends on.
+
+### Unlink local packages (restore registry versions)
+
+```bash
+uikit-cli unlink
+```
+
+Attempts to unlink all local uikit packages and restore registered versions. If packages are not yet published, keeps local links in place.
+
+### Working from any subdirectory
+
+The CLI works from any directory within a workspace:
+
+```bash
+cd my-consumer/src/explorer
+uikit-cli link  # auto-detects workspace root and links packages
+```
+
+## How it works
+
+1. **Auto-detection**: Walks up from current working directory to find the nearest `package.json` with a `workspaces` field
+2. **Discovery**: Queries locally available uikit packages and determines which ones are needed by consumer workspaces
+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
+# Link uikit packages for local development
+npm run uikit:link
+
+# Later, restore registry versions (or keep local links if not published)
+npm run uikit:unlink
+```
+
+## Scripts in synome package.json
+
+- `uikit:link` — Uses the CLI with auto-detection
+- `uikit:unlink` — Unlinks using the CLI

package/dist/cli.js

@@ -0,0 +1,250 @@
+#!/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;
+    }
+}
+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) {
+        const arg = args[i];
+        if (arg === '--consumer-root' && args[i + 1]) {
+            consumerRoot = path.resolve(process.cwd(), args[i + 1]);
+            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);
+                }
+            }
+        }
+        if (needed.size > 0) {
+            neededByWorkspace.set(ws.location, [...needed]);
+        }
+    }
+    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);
+        }
+    }
+    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;
+        }
+        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);
+        }
+    }
+    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.`);
+        }
+    }
+    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.`);
+            }
+        }
+    }
+}
+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;
+            }
+        }
+    }
+    return true;
+}
+function arePackagesPublished(consumerRoot, neededByWorkspace) {
+    const uniqueNames = new Set();
+    for (const names of neededByWorkspace.values()) {
+        for (const name of names) {
+            uniqueNames.add(name);
+        }
+    }
+    for (const name of uniqueNames) {
+        const ok = tryRun(`npm view ${name} version --json`, consumerRoot, true);
+        if (!ok) {
+            return false;
+        }
+    }
+    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);
+    if (mode === 'link') {
+        linkLocalPackages(consumerRoot, neededByWorkspace, dirByName);
+        console.log('\nLinked local uikit packages into consumer workspaces.');
+        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.');
+        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}`);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@archon-research/uikit-cli",
+  "version": "0.1.0-dev25004766367",
+  "type": "module",
+  "description": "CLI for managing local uikit package linking in consumer workspaces",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepare": "npm run build"
+  },
+  "bin": {
+    "uikit-cli": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@archon-research/tsconfig": "*",
+    "@types/node": "^24.7.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "url": "https://github.com/archon-research/uikit"
+  }
+}