@r0hitsharma/uikit-cli 0.12.0-rohit-fork-ci.1

package/README.md

@@ -0,0 +1,286 @@
+# @r0hitsharma/uikit-cli
+
+CLI tool for local package linking during active development with consumer repositories.
+
+## 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 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 @r0hitsharma/uikit-cli --workspace <workspace-name>
+```
+
+Example for a consuming project:
+```bash
+cd /path/to/your-project/ts
+npm link @r0hitsharma/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 uikit-cli-managed `oxlint` and `oxfmt` versions internally (resolved via its
+lockfile), so downstream workspaces do not need to declare those tool packages directly.
+
+`format` fills in `-c ./.oxfmtrc.ts` when you omit a config flag and that file is in the
+current directory, because `oxfmt` only auto-discovers the `.json` form. `lint` deliberately
+does not do the same: `oxlint` resolves `oxlint.config.ts` per target file by walking up from
+it, so a run spanning several packages picks up each package's own config. Injecting `-c`
+would replace that with whichever config sits in the current directory, which in the git-hook
+shape — cwd at the repo root, targets in several packages — silently drops those packages'
+rules. Pass `-c` yourself when you do want one config to win.
+
+`lint` applies `--max-warnings=0` by default, because `oxlint` exits 0 on warnings and the
+shared presets set the `correctness` and `suspicious` categories to `warn`. Pass your own
+`--max-warnings` or `--deny-warnings` to change that.
+
+If your consumer workspace prefers to run tooling directly, it can install and invoke
+`oxlint`/`oxfmt` itself. In that setup, `@r0hitsharma/oxlint-config` and
+`@r0hitsharma/oxfmt-config` remain reusable config packages, while `uikit-cli` remains an
+optional workflow wrapper.
+
+### Check a generated stylesheet for silently-dropped CSS
+
+```bash
+./node_modules/.bin/uikit-cli doctor                      # finds styled-system/styles.css
+./node_modules/.bin/uikit-cli doctor path/to/styles.css   # explicit path
+./node_modules/.bin/uikit-cli doctor --codegen            # runs `panda cssgen` itself
+```
+
+Use `--codegen` when you use the Panda PostCSS plugin and never write a frozen
+`styled-system/styles.css`.
+
+Findings carry a severity. `doctor` exits non-zero on any **error**, so it gates CI;
+**warnings** are printed and do not affect the exit code. Only roleless `colorPalette` can
+warn — see [error or warning](#roleless-colorpalette-error-or-warning) below.
+
+The design system's authoring model has failure modes that produce *no error anywhere* — the
+build passes, the console is clean, and the style simply does not apply. `doctor` scans the
+generated stylesheet for them:
+
+| Check | Severity | What silently breaks |
+| --- | --- | --- |
+| `missing-static-css` | error | No design-system recipe classes were emitted at all, so runtime-selected variants (status tones, dense tables, drawer sizes) render unstyled. Fix by spreading `designSystemStaticCssRecipes` into your Panda config's `staticCss.recipes`. |
+| `unresolved-token` | error | A declaration whose value is a bare `token.path` (e.g. `color: text.subtle`) rather than a `var(--…)`. Invalid CSS the browser drops. |
+| `roleless-color-palette` | error or warning | A `colorPalette` value that defines no role for the property styled with it — `var(--colors-color-palette-solid-bg)` is well-formed but undefined in that scope, so the browser drops the declaration. Only `neutral`, `gray`, `green`, `red`, `amber` and `blue` carry full role sub-tokens; other hues map the 50–950 scale only. |
+
+#### Roleless `colorPalette`: error or warning
+
+A role reference is only a *definite* miss when every `colorPalette` its scope can be set to
+lacks the role — then no combination of that recipe's variants avoids the dropped declaration.
+When some assignable palette does define the role, the breaking pairing is possible but
+unproven: a recipe exposing `colorPalette: violet` alongside a `solid` emphasis variant may
+never combine the two in an app, and the stylesheet cannot say. That is reported as a warning —
+worth printing, not worth failing a build over.
+
+| Palettes assignable in the scope | Which lack the role | Severity | Exit code |
+| --- | --- | --- | --- |
+| one | it does | error | non-zero |
+| several | all of them | error | non-zero |
+| several | some of them | warning | 0 |
+| several | none | no finding | 0 |
+| none (no `colorPalette` assigned in scope) | — | no finding | 0 |
+
+#### Roleless `colorPalette`: detection boundary
+
+Resolving which palette applies to a declaration is the CSS cascade, and `doctor` does not
+simulate it. It resolves exactly one scope — a **recipe**, keyed by the class-name stem Panda
+derives from `className` — and flags a role reference only when a palette assigned somewhere in
+that same recipe's classes fails to define the role. Slots share the scope, since the root slot's
+palette properties cascade into the others.
+
+These cases are *not* flagged, on purpose, because scope is ambiguous and a false pass is far
+cheaper than a false failure:
+
+- atomic utilities (`.color-palette_violet` plus a separate `.bg_colorPalette\.solid\.bg`) — the
+  stylesheet cannot prove the two classes land on the same element, nor that an ancestor already
+  supplied the role;
+- a palette set on an outer recipe with the role consumed by an inner one;
+- `var(--colors-color-palette-…, fallback)` — a fallback means the declaration survives.
+
+The palette→roles map is read out of the stylesheet itself (each `colorPalette` assignment
+ruleset *is* the preset's role tokens in generated form), so palettes added to the preset — or
+defined in a consumer's own preset extension — are covered with no list to keep in sync.
+
+### Register the local uikit packages
+
+```bash
+./node_modules/.bin/uikit-cli register
+```
+
+Runs `npm link` in every local `@r0hitsharma/*` package so they are available to link
+from. `link` and `unlink` do this themselves, so run it directly only to register the
+packages without touching a consumer. Pass `--uikit-root <path>` when the uikit checkout
+cannot be auto-discovered.
+
+### Link uikit packages into a consumer repository
+
+From your consumer repository:
+
+```bash
+./node_modules/.bin/uikit-cli link
+```
+
+This command links all `@r0hitsharma/*` 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": "./node_modules/.bin/uikit-cli link",
+    "uikit:unlink": "./node_modules/.bin/uikit-cli unlink"
+  }
+}
+```
+
+### Restore registry versions
+
+When co-development is complete, restore published versions from npm:
+
+```bash
+./node_modules/.bin/uikit-cli unlink
+```
+
+## How it works
+
+The CLI manages local development links by:
+
+1. Auto-registering local `@r0hitsharma/*` packages from your uikit checkout via `npm link`
+2. Linking only the 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 root and all dependent packages, working from any
+directory within the project. Both consumer shapes are supported: an **npm-workspaces monorepo**
+(the root with a `workspaces` field), and a **single package** that installs uikit directly (no
+`workspaces` field) — in the single-package case the root package is linked directly.
+
+The CLI auto-discovers the local uikit monorepo for typical sibling-checkout layouts.
+
+## Requirements
+
+- Local clone of the uikit monorepo
+- 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
+
+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
+```
+
+### `useTheme must be used within ThemeProvider` (duplicated React context) after linking
+
+With `resolve.preserveSymlinks: true` (which linking relies on) Vite can serve a linked package
+under **two** URLs at once — `/node_modules/…` (the root symlink) and `/@fs/…` (the real path) —
+producing two module graphs and two copies of singletons like `ThemeContext`. A component and its
+`ThemeProvider` then hold different context objects and the hook throws. This is a link artifact,
+not a bug in the app or the design system.
+
+To confirm: look for the same module served at both URLs in the dev server (both HTTP 200). To
+recover: run `uikit-cli unlink` and restart the dev server (touch the Vite config so it
+re-optimizes) — the module collapses back to a single URL. To stay linked, add the linked
+package(s) plus `react`/`react-dom` to your Vite `resolve.dedupe`, or drop `preserveSymlinks`.
+
+### A partial link reported as success
+
+If `link` prints that some packages did **not** link (PARTIAL), the named packages may still
+resolve to a stale registry version. A consumer `.npmrc` with `min-release-age` is the usual
+cause — npm rejects a fresh prerelease with `ETARGET`. Re-run with an override (e.g.
+`--min-release-age=0`) or link those packages manually.
+
+### The CLI cannot repair a stale copy of itself
+
+`link` links `@r0hitsharma/*` into the consumer — and that includes `uikit-cli` itself. So
+`npm run uikit:link` runs whatever `uikit-cli` is currently in the consumer's `node_modules`: if
+that copy is **stale**, the old code runs, and no source fix can change the run that needs it (a
+stale binary can't even report its own staleness). When developing the CLI, or right after pulling
+CLI changes, bypass the linked copy and invoke the monorepo's freshly-built binary directly so you
+always run current code:
+
+```bash
+npm run build --workspace packages/uikit-cli   # in the uikit checkout
+node <path-to-uikit>/packages/uikit-cli/dist/cli.js link --uikit-root <path-to-uikit>
+```
+
+Or install the published version from the registry, which sidesteps linking entirely.
+
+## Development workflow
+
+In a consumer workspace:
+
+```bash
+# One-time setup (see Setup section above)
+npm link @r0hitsharma/uikit-cli --workspace <workspace-name>
+
+# Link uikit packages for local development
+npm run uikit:link
+
+# Verify links
+npm run uikit:link -- --verify
+
+# Later, restore registry versions
+npm run uikit:unlink
+```
+
+## Debug mode
+
+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

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { NpmCommandExecutor } from './command-executor.js';
+import { DoctorCommand } from './commands/doctor.js';
+import { FormatCommand } from './commands/format.js';
+import { LinkCommand } from './commands/link.js';
+import { LintCommand } from './commands/lint.js';
+import { RegisterCommand } from './commands/register.js';
+import { UnlinkCommand } from './commands/unlink.js';
+import { RealFileSystem } from './fs-utils.js';
+import { LinkValidator } from './link-validator.js';
+import { ConsoleLogger } from './logger.js';
+import { PackageDiscovery } from './package-discovery.js';
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Parse command line arguments
+ */
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    if (args.length === 0) {
+        throw new Error('Usage: uikit-cli <register|link|unlink|lint|format|doctor> [--verify] [--debug] [--uikit-root <path>] [args...]');
+    }
+    const mode = args[0];
+    const validModes = [
+        'lint',
+        'format',
+        'register',
+        'link',
+        'unlink',
+        'doctor',
+    ];
+    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];
+        // Unreachable given the loop bound; narrows `arg` to `string`.
+        if (arg === undefined)
+            break;
+        if (arg === '--uikit-root' && i + 1 < args.length) {
+            uikitRoot = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--verify') {
+            verify = true;
+            i += 1;
+        }
+        else if (arg === '--debug') {
+            debug = true;
+            i += 1;
+        }
+        else {
+            commandArgs.push(arg);
+            i += 1;
+        }
+    }
+    // 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);
+        }
+        if (discovery.isValidUIKitRoot(relativeRoot)) {
+            uikitRoot = relativeRoot;
+            if (debug) {
+                console.log('[DEBUG parseArgs] Found valid uikit root at relative location');
+            }
+        }
+    }
+    if (!uikitRoot && mode !== 'lint' && mode !== 'format' && mode !== 'doctor') {
+        // Try to find from consumer
+        try {
+            const tempConsumerRoot = discovery.findConsumerRoot(process.cwd());
+            const foundRoot = discovery.findUIKitRootFromConsumer(tempConsumerRoot);
+            if (foundRoot) {
+                uikitRoot = foundRoot;
+            }
+        }
+        catch {
+            // Will throw error below if needed
+        }
+    }
+    if (!uikitRoot && mode !== 'lint' && mode !== 'format' && mode !== 'doctor') {
+        // Try walking up from cwd
+        const foundRoot = discovery.findUIKitRoot(process.cwd());
+        if (foundRoot) {
+            uikitRoot = foundRoot;
+        }
+    }
+    if (!uikitRoot && mode !== 'lint' && mode !== 'format' && mode !== 'doctor') {
+        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,
+    };
+}
+/**
+ * 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 });
+    }
+}
+/**
+ * Link CLI into consumer for convenience
+ */
+function linkCliIntoConsumer(consumerRoot, executor, logger) {
+    const result = executor.exec('npm link "@r0hitsharma/uikit-cli" --package-lock=false --save=false --no-workspaces', { cwd: consumerRoot });
+    if (!result.success) {
+        logger.warn('Could not link the local @r0hitsharma/uikit-cli — you may be running ' +
+            'the registry version, which can lag behind the local one (e.g. missing ' +
+            '`doctor --codegen`). A consumer .npmrc with `min-release-age` can reject ' +
+            'a fresh prerelease with ETARGET here.');
+    }
+}
+/**
+ * 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);
+    // Lint and format forward the tool's verdict as the exit code — exiting 0
+    // unconditionally left `--check` runs unable to gate CI.
+    if (mode === 'lint') {
+        const lintCmd = new LintCommand(executor);
+        process.exit(lintCmd.execute(commandArgs) ? 0 : 1);
+    }
+    if (mode === 'format') {
+        const formatCmd = new FormatCommand(executor, fs);
+        process.exit(formatCmd.execute(commandArgs) ? 0 : 1);
+    }
+    // Doctor scans the consumer's generated CSS; it runs in the consumer cwd and
+    // needs no uikit root. Non-zero exit on findings so it gates CI.
+    if (mode === 'doctor') {
+        const doctorCmd = new DoctorCommand(fs, logger, executor);
+        process.exit(doctorCmd.execute(commandArgs) ? 0 : 1);
+    }
+    // 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);
+    }
+    // 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, logger);
+    if (mode === 'link') {
+        const linkCmd = new LinkCommand(discovery, executor, validator, fs, logger);
+        linkCmd.execute(consumerRoot, uikitRoot, verify);
+        process.exit(0);
+    }
+    if (mode === 'unlink') {
+        const unlinkCmd = new UnlinkCommand(executor, logger);
+        unlinkCmd.execute(consumerRoot, uikitRoot, discovery);
+        process.exit(0);
+    }
+}
+catch (error) {
+    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;
+    }
+}