@dalexto/lexsys-cli 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LexSys
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# lexsys CLI
+
+**Audience:** Maintainers, contributors, and agents
+**Type:** Package README
+**Source of truth for:** Package role, command surface, core module boundaries
+**Full CLI reference:** [docs/reference/cli/CLI.md](../../docs/reference/cli/CLI.md)
+**Verified against:** `packages/cli/src/`
+
+---
+
+## Package Role
+
+`packages/cli` is the command-line installer. It reads registry metadata from
+`@dalexto/lexsys-registry` and installs components, utilities, and styles into consumer
+projects.
+
+This package owns:
+
+- the `lexsys` binary entry point
+- all CLI commands and their argument parsing
+- consumer project detection (Vite, Tailwind, package manager)
+- idempotent file installation and conflict reporting
+- `lexsys.config.json` read/write lifecycle
+
+This package does not own:
+
+- registry item metadata (owned by `@dalexto/lexsys-registry`)
+- install templates (owned by `@dalexto/lexsys-registry/templates`)
+- design token source (owned by `@dalexto/lexsys-tokens`)
+- component implementations (owned by `@dalexto/lexsys-ui`)
+
+---
+
+## Binary
+
+```
+lexsys
+```
+
+Installed via `npm install -g lexsys` or run directly with `pnpm exec lexsys`.
+
+---
+
+## Command Surface
+
+| Command                        | Purpose                                                                     |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| `lexsys init`                  | Initialize inside an existing supported Vite app                            |
+| `lexsys init vite [directory]` | Scaffold a new Vite + React consumer                                        |
+| `lexsys init next [directory]` | Scaffold a new Next.js App Router consumer (pinned Next.js 15.3.3)          |
+| `lexsys add <component>`       | Install one or more components into the consumer project                    |
+| `lexsys update [component]`    | Update installed components; `--sync`, `--utilities`, `--styles`, `--force` |
+| `lexsys list`                  | List available registry components                                          |
+| `lexsys status`                | Show installed component versions vs registry versions                      |
+| `lexsys doctor`                | Check project health and config validity                                    |
+| `lexsys config`                | Read or modify `lexsys.config.json`                                         |
+| `lexsys registry`              | Inspect the active registry source                                          |
+| `lexsys uninstall <component>` | Remove installed component files when they match registry templates         |
+| `lexsys version`               | Print CLI version                                                           |
+| `lexsys help`                  | Print command list                                                          |
+
+### Global flags
+
+| Flag            | Purpose                                                       |
+| --------------- | ------------------------------------------------------------- |
+| `--cwd <path>`  | Override working directory for all operations                 |
+| `--yes`         | Skip confirmation prompts                                     |
+| `--no-fallback` | Disable fallback to local registry when remote is unavailable |
+
+---
+
+## Core Modules
+
+| Module                      | Role                                                                        |
+| --------------------------- | --------------------------------------------------------------------------- |
+| `core/config.ts`            | Read/write `lexsys.config.json`; defines `LexsysConfig` schema and defaults |
+| `core/installer.ts`         | File copy, conflict detection, idempotent installs                          |
+| `core/registry-provider.ts` | Selects local vs remote registry source                                     |
+| `core/registry-resolver.ts` | Resolves registry items, utilities, and styles from active registry         |
+| `core/tailwind-setup.ts`    | Detects and wires Tailwind v4 CSS entrypoint                                |
+| `core/vite-scaffold.ts`     | Detects and patches Vite config for Tailwind plugin                         |
+| `core/package-manager.ts`   | Detects npm/pnpm/yarn and runs installs                                     |
+| `core/context.ts`           | Process-level `cwd` override via `--cwd` flag                               |
+| `core/flags.ts`             | Shared flag parsing utilities                                               |
+| `core/cli-error.ts`         | Typed CLI error class and top-level error handler                           |
+
+---
+
+## Config Schema and Install Behavior
+
+Full `lexsys.config.json` schema (all fields, defaults, aliases) and install idempotency rules (created / updated / skipped / conflicted states, conflict detection, backup behavior): [docs/reference/cli/CLI.md](../../docs/reference/cli/CLI.md).
+
+---
+
+## Development
+
+Root aliases (full list: [docs/operations/SCRIPTS.md](../../docs/operations/SCRIPTS.md)):
+
+```sh
+pnpm cli:build
+pnpm cli:typecheck
+pnpm cli:check
+```
+
+---
+
+## Dependencies
+
+- `@dalexto/lexsys-registry` — registry metadata and templates
+- `prompts` — interactive CLI prompts

package/dist/commands/add.d.ts

@@ -0,0 +1 @@
+export declare const runAdd: (args: string[]) => Promise<void>;

package/dist/commands/config.d.ts

@@ -0,0 +1,8 @@
+interface RunConfigOptions {
+    path?: boolean;
+    exists?: boolean;
+    setRegistryUrl?: string;
+    clearRegistryUrl?: boolean;
+}
+export declare const runConfig: (options?: RunConfigOptions) => Promise<void>;
+export {};

package/dist/commands/doctor.d.ts

@@ -0,0 +1,5 @@
+interface RunDoctorOptions {
+    noFallback?: boolean;
+}
+export declare const runDoctor: (options?: RunDoctorOptions) => Promise<void>;
+export {};

package/dist/commands/help.d.ts

@@ -0,0 +1,2 @@
+export declare const runHelpFor: (command: string) => void;
+export declare const runHelp: () => void;

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare const runInit: (args?: string[]) => Promise<void>;

package/dist/commands/list.d.ts

@@ -0,0 +1,6 @@
+interface RunListOptions {
+    json?: boolean;
+    noFallback?: boolean;
+}
+export declare const runList: (options?: RunListOptions) => Promise<void>;
+export {};

package/dist/commands/registry.d.ts

@@ -0,0 +1,9 @@
+interface RunRegistryOptions {
+    summary?: boolean;
+    source?: boolean;
+    local?: boolean;
+    remote?: boolean;
+    noFallback?: boolean;
+}
+export declare const runRegistry: (options?: RunRegistryOptions) => Promise<void>;
+export {};

package/dist/commands/status.d.ts

@@ -0,0 +1,5 @@
+interface RunStatusOptions {
+    noFallback?: boolean;
+}
+export declare const runStatus: (options?: RunStatusOptions) => Promise<void>;
+export {};

package/dist/commands/uninstall.d.ts

@@ -0,0 +1 @@
+export declare const runUninstall: (args: string[]) => Promise<void>;

package/dist/commands/update.d.ts

@@ -0,0 +1 @@
+export declare const runUpdate: (args: string[]) => Promise<void>;

package/dist/commands/version.d.ts

@@ -0,0 +1 @@
+export declare const runVersion: () => Promise<void>;

package/dist/config/config.d.ts

@@ -0,0 +1,28 @@
+export interface LexsysPathsConfig {
+    components: string;
+    utilities: string;
+    styles: string;
+}
+export interface LexsysAliasesConfig {
+    components: string;
+    ui: string;
+    utils: string;
+    lib: string;
+    hooks: string;
+}
+export interface LexsysConfig {
+    style: "default";
+    paths: LexsysPathsConfig;
+    aliases: LexsysAliasesConfig;
+    tailwind: LexsysTailwindConfig;
+    installed?: Record<string, string>;
+    registryUrl?: string | null;
+}
+export interface LexsysTailwindConfig {
+    version: "v4";
+    css: string;
+}
+export declare const defaultConfig: LexsysConfig;
+export declare const getConfigPath: () => string;
+export declare const loadConfig: () => Promise<LexsysConfig>;
+export declare const saveConfig: (config: LexsysConfig) => Promise<void>;

package/dist/core/backup.d.ts

@@ -0,0 +1 @@
+export declare const createBackupFile: (path: string) => Promise<string | null>;

package/dist/core/cli-error.d.ts

@@ -0,0 +1,5 @@
+export declare class CliError extends Error {
+    suggestion?: string;
+    constructor(message: string, suggestion?: string);
+}
+export declare const handleCliError: (error: unknown) => never;

package/dist/core/context.d.ts

@@ -0,0 +1,2 @@
+export declare const setCwd: (cwd: string) => void;
+export declare const getCwd: () => string;

package/dist/core/flags.d.ts

@@ -0,0 +1,4 @@
+export declare const hasFlag: (args: string[], ...flags: string[]) => boolean;
+export declare const removeFlags: (args: string[], flags: string[]) => string[];
+export declare const getFlagValue: (args: string[], ...flags: string[]) => string | undefined;
+export declare const removeFlagsWithValues: (args: string[], flags: string[]) => string[];

package/dist/core/fs.d.ts

@@ -0,0 +1,3 @@
+export declare const fileExists: (path: string) => Promise<boolean>;
+export declare const filesAreEqual: (sourcePath: string, targetPath: string) => Promise<boolean>;
+export declare const writeFileIfMissing: (path: string, content: string) => Promise<void>;

package/dist/core/hash.d.ts

@@ -0,0 +1,3 @@
+export declare const hashContent: (content: string) => string;
+export declare const hashFile: (path: string) => Promise<string>;
+export declare const hashesAreEqual: (firstContent: string, secondContent: string) => boolean;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};