lattice-ui 0.4.3

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 astra-void
+
+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,45 @@
+# @lattice-ui/cli
+
+Node CLI for Lattice UI projects.
+
+## Install (Optional Global)
+
+```bash
+npm i -g @lattice-ui/cli
+```
+
+## Usage
+
+```bash
+lattice <command> [options]
+```
+
+### Commands
+
+- `lattice create [project-path] [--yes] [--pm <pnpm|npm|yarn>] [--git] [--template rbxts] [--lint] [--no-lint]`
+- `lattice init [--yes] [--dry-run] [--pm <pnpm|npm|yarn>] [--template rbxts] [--lint]`
+- `lattice add [name...] [--preset <preset...>] [--pm <pnpm|npm|yarn>] [--yes] [--dry-run]`
+- `lattice remove [name...] [--preset <preset...>] [--pm <pnpm|npm|yarn>] [--yes] [--dry-run]`
+- `lattice upgrade [name...] [--preset <preset...>] [--pm <pnpm|npm|yarn>] [--yes] [--dry-run]`
+- `lattice doctor [--pm <pnpm|npm|yarn>]`
+- `lattice help`
+- `lattice version`
+
+### Global options
+
+- `--help`
+- `--version`
+
+### Examples
+
+```bash
+npx @lattice-ui/cli create
+npx @lattice-ui/cli create my-game --pm npm --git --no-lint
+npx @lattice-ui/cli init --dry-run
+npx @lattice-ui/cli add dialog,toast --preset overlay
+npx @lattice-ui/cli remove dialog --dry-run
+npx @lattice-ui/cli upgrade --dry-run
+npx @lattice-ui/cli doctor
+```
+
+When `--pm` is omitted, the CLI resolves a package manager automatically from the project lockfile or installed managers. Use `--pm` to override that choice explicitly.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,426 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCli = runCli;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const add_1 = require("./commands/add");
+const create_1 = require("./commands/create");
+const doctor_1 = require("./commands/doctor");
+const init_1 = require("./commands/init");
+const remove_1 = require("./commands/remove");
+const upgrade_1 = require("./commands/upgrade");
+const errors_1 = require("./core/errors");
+const ctx_1 = require("./ctx");
+const HELP_TEXT = `Lattice CLI
+
+Usage:
+  lattice <command> [options]
+
+Commands:
+  create [project-path] [--yes] [--pm <pnpm|npm|yarn>] [--git] [--template rbxts] [--lint] [--no-lint]
+    Create a new project from the rbxts template.
+
+  init [--yes] [--dry-run] [--pm <pnpm|npm|yarn>] [--template rbxts] [--lint]
+    Initialize Lattice in an existing project.
+
+  add [name...] [--preset <preset...>] [--pm <pnpm|npm|yarn>] [--yes] [--dry-run]
+    Install component packages and their required peers.
+
+  remove [name...] [--preset <preset...>] [--pm <pnpm|npm|yarn>] [--yes] [--dry-run]
+    Remove selected component packages.
+
+  upgrade [name...] [--preset <preset...>] [--pm <pnpm|npm|yarn>] [--yes] [--dry-run]
+    Upgrade installed @lattice-ui/* packages.
+
+  doctor [--pm <pnpm|npm|yarn>]
+    Check lockfiles, peers, and provider expectations.
+
+  help
+    Show this help message.
+
+  version
+    Print CLI version.
+
+Global options:
+  --help
+  --version
+
+Examples:
+  npx @lattice-ui/cli create
+  npx @lattice-ui/cli create my-game --pm npm --git --no-lint
+  npx @lattice-ui/cli init --dry-run
+  npx @lattice-ui/cli add dialog,toast --preset overlay
+  npx @lattice-ui/cli remove dialog --dry-run
+  npx @lattice-ui/cli upgrade --dry-run
+  npx @lattice-ui/cli doctor
+`;
+function splitList(value) {
+    return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function parseTopLevel(argv) {
+    if (argv.length === 0) {
+        return {
+            showHelp: true,
+            showVersion: false,
+            commandArgs: [],
+        };
+    }
+    const first = argv[0];
+    if (first === "--help" || first === "-h" || first === "help") {
+        return {
+            showHelp: true,
+            showVersion: false,
+            commandArgs: [],
+        };
+    }
+    if (first === "--version" || first === "-v" || first === "version") {
+        return {
+            showHelp: false,
+            showVersion: true,
+            commandArgs: [],
+        };
+    }
+    if (first.startsWith("-")) {
+        throw (0, errors_1.usageError)(`Unknown global option: ${first}`);
+    }
+    return {
+        command: first,
+        commandArgs: argv.slice(1),
+        showHelp: false,
+        showVersion: false,
+    };
+}
+function parseCreateArgs(args) {
+    const positionals = [];
+    let yes = false;
+    let pm;
+    let git;
+    let template;
+    let lint;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === "--yes") {
+            yes = true;
+            continue;
+        }
+        if (token === "--pm") {
+            const value = args[index + 1];
+            if (!value) {
+                throw (0, errors_1.usageError)("Missing value for --pm.");
+            }
+            pm = value;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--pm=")) {
+            pm = token.slice("--pm=".length);
+            continue;
+        }
+        if (token === "--git") {
+            git = true;
+            continue;
+        }
+        if (token === "--lint") {
+            if (lint === false) {
+                throw (0, errors_1.usageError)("Cannot use --lint and --no-lint together.");
+            }
+            lint = true;
+            continue;
+        }
+        if (token === "--no-lint") {
+            if (lint === true) {
+                throw (0, errors_1.usageError)("Cannot use --lint and --no-lint together.");
+            }
+            lint = false;
+            continue;
+        }
+        if (token === "--template") {
+            const value = args[index + 1];
+            if (!value) {
+                throw (0, errors_1.usageError)("Missing value for --template.");
+            }
+            template = value;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--template=")) {
+            template = token.slice("--template=".length);
+            continue;
+        }
+        if (token.startsWith("-")) {
+            throw (0, errors_1.usageError)(`Unknown option for create: ${token}`);
+        }
+        positionals.push(token);
+    }
+    if (positionals.length > 1) {
+        throw (0, errors_1.usageError)("create accepts at most one [project-path] argument.");
+    }
+    return {
+        projectPath: positionals[0],
+        yes,
+        pm,
+        git,
+        template,
+        lint,
+    };
+}
+function parseInitArgs(args) {
+    let yes = false;
+    let dryRun = false;
+    let pm;
+    let template;
+    let lint;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === "--yes") {
+            yes = true;
+            continue;
+        }
+        if (token === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (token === "--pm") {
+            const value = args[index + 1];
+            if (!value) {
+                throw (0, errors_1.usageError)("Missing value for --pm.");
+            }
+            pm = value;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--pm=")) {
+            pm = token.slice("--pm=".length);
+            continue;
+        }
+        if (token === "--template") {
+            const value = args[index + 1];
+            if (!value) {
+                throw (0, errors_1.usageError)("Missing value for --template.");
+            }
+            template = value;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--template=")) {
+            template = token.slice("--template=".length);
+            continue;
+        }
+        if (token === "--lint") {
+            lint = true;
+            continue;
+        }
+        if (token.startsWith("-")) {
+            throw (0, errors_1.usageError)(`Unknown option for init: ${token}`);
+        }
+        throw (0, errors_1.usageError)("init does not accept positional arguments.");
+    }
+    return {
+        yes,
+        dryRun,
+        pm,
+        template,
+        lint,
+    };
+}
+function parseSelectionArgs(args, command) {
+    const names = [];
+    const presets = [];
+    let pm;
+    let yes = false;
+    let dryRun = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === "--preset") {
+            const value = args[index + 1];
+            if (!value) {
+                throw (0, errors_1.usageError)("Missing value for --preset.");
+            }
+            presets.push(...splitList(value));
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--preset=")) {
+            presets.push(...splitList(token.slice("--preset=".length)));
+            continue;
+        }
+        if (token === "--pm") {
+            const value = args[index + 1];
+            if (!value) {
+                throw (0, errors_1.usageError)("Missing value for --pm.");
+            }
+            pm = value;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--pm=")) {
+            pm = token.slice("--pm=".length);
+            continue;
+        }
+        if (token === "--yes") {
+            yes = true;
+            continue;
+        }
+        if (token === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (token.startsWith("-")) {
+            throw (0, errors_1.usageError)(`Unknown option for ${command}: ${token}`);
+        }
+        names.push(...splitList(token));
+    }
+    return {
+        names,
+        presets,
+        pm,
+        yes,
+        dryRun,
+    };
+}
+function parseDoctorArgs(args) {
+    let pm;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === "--pm") {
+            const value = args[index + 1];
+            if (!value) {
+                throw (0, errors_1.usageError)("Missing value for --pm.");
+            }
+            pm = value;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--pm=")) {
+            pm = token.slice("--pm=".length);
+            continue;
+        }
+        if (token.startsWith("-")) {
+            throw (0, errors_1.usageError)(`Unknown option for doctor: ${token}`);
+        }
+        throw (0, errors_1.usageError)("doctor does not accept positional arguments.");
+    }
+    return { pm };
+}
+async function readCliVersion() {
+    const packageJsonPath = path.resolve(__dirname, "../package.json");
+    const content = await node_fs_1.promises.readFile(packageJsonPath, "utf8");
+    const parsed = JSON.parse(content);
+    return parsed.version ?? "0.0.0";
+}
+function printHelp() {
+    process.stdout.write(HELP_TEXT);
+}
+async function runCli(argv) {
+    const normalizedArgv = argv[0] === "--" ? argv.slice(1) : argv;
+    const parsed = parseTopLevel(normalizedArgv);
+    if (parsed.showVersion) {
+        process.stdout.write(`${await readCliVersion()}\n`);
+        return;
+    }
+    if (parsed.showHelp || !parsed.command) {
+        printHelp();
+        return;
+    }
+    if (parsed.command === "init") {
+        const initArgs = parseInitArgs(parsed.commandArgs);
+        await (0, init_1.runInitCommand)({
+            cwd: process.cwd(),
+            ...initArgs,
+        });
+        return;
+    }
+    if (parsed.command === "create") {
+        const createArgs = parseCreateArgs(parsed.commandArgs);
+        await (0, create_1.runCreateCommand)({
+            cwd: process.cwd(),
+            ...createArgs,
+        });
+        return;
+    }
+    if (parsed.command === "add") {
+        const selection = parseSelectionArgs(parsed.commandArgs, "add");
+        const ctx = await (0, ctx_1.createContext)({
+            cwd: process.cwd(),
+            pm: selection.pm,
+            dryRun: selection.dryRun,
+            yes: selection.yes,
+            verbose: false,
+        });
+        await (0, add_1.runAddCommand)(ctx, { names: selection.names, presets: selection.presets });
+        return;
+    }
+    if (parsed.command === "upgrade") {
+        const selection = parseSelectionArgs(parsed.commandArgs, "upgrade");
+        const ctx = await (0, ctx_1.createContext)({
+            cwd: process.cwd(),
+            pm: selection.pm,
+            dryRun: selection.dryRun,
+            yes: selection.yes,
+            verbose: false,
+        });
+        await (0, upgrade_1.runUpgradeCommand)(ctx, { names: selection.names, presets: selection.presets });
+        return;
+    }
+    if (parsed.command === "remove") {
+        const selection = parseSelectionArgs(parsed.commandArgs, "remove");
+        const ctx = await (0, ctx_1.createContext)({
+            cwd: process.cwd(),
+            pm: selection.pm,
+            dryRun: selection.dryRun,
+            yes: selection.yes,
+            verbose: false,
+        });
+        await (0, remove_1.runRemoveCommand)(ctx, { names: selection.names, presets: selection.presets });
+        return;
+    }
+    if (parsed.command === "doctor") {
+        const doctorArgs = parseDoctorArgs(parsed.commandArgs);
+        const ctx = await (0, ctx_1.createContext)({
+            cwd: process.cwd(),
+            pm: doctorArgs.pm,
+            dryRun: false,
+            yes: false,
+            verbose: false,
+        });
+        await (0, doctor_1.runDoctorCommand)(ctx);
+        return;
+    }
+    throw (0, errors_1.usageError)(`Unknown command: ${parsed.command}`);
+}

package/dist/commands/add.d.ts

@@ -0,0 +1,3 @@
+import type { CliContext } from "../ctx";
+import { type SelectionInput } from "./selection";
+export declare function runAddCommand(ctx: CliContext, input: SelectionInput): Promise<void>;

package/dist/commands/add.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAddCommand = runAddCommand;
+const errors_1 = require("../core/errors");
+const patch_1 = require("../core/fs/patch");
+const output_1 = require("../core/output");
+const readPackageJson_1 = require("../core/project/readPackageJson");
+const prompt_1 = require("../core/prompt");
+const schema_1 = require("../core/registry/schema");
+const selection_1 = require("./selection");
+async function resolveSelectionInput(ctx, input) {
+    if (input.names.length > 0 || input.presets.length > 0) {
+        return input;
+    }
+    if (ctx.options.yes) {
+        throw (0, errors_1.usageError)("No components selected. Provide component names or --preset when using --yes.");
+    }
+    const runtime = {
+        yes: ctx.options.yes,
+    };
+    const presetOptions = Object.keys(ctx.registry.presets)
+        .sort((left, right) => left.localeCompare(right))
+        .map((presetName) => ({
+        label: `${presetName} (${ctx.registry.presets[presetName].join(", ")})`,
+        value: presetName,
+    }));
+    const componentOptions = Object.keys(ctx.registry.packages)
+        .sort((left, right) => left.localeCompare(right))
+        .map((componentName) => ({
+        label: componentName,
+        value: componentName,
+    }));
+    const selectedPresets = await (0, prompt_1.promptMultiSelect)(runtime, "Select presets (optional)", presetOptions, {
+        allowEmpty: true,
+    });
+    const selectedComponents = await (0, prompt_1.promptMultiSelect)(runtime, "Select components (optional)", componentOptions, {
+        allowEmpty: true,
+    });
+    return {
+        names: selectedComponents,
+        presets: selectedPresets,
+    };
+}
+async function runAddCommand(ctx, input) {
+    const resolvedInput = await resolveSelectionInput(ctx, input);
+    const components = (0, selection_1.resolveComponentSelection)(ctx, resolvedInput);
+    const specs = new Set();
+    const optionalProviders = new Set();
+    const notes = [];
+    for (const component of components) {
+        const entry = ctx.registry.packages[component];
+        specs.add(entry.npm);
+        for (const peer of entry.peers ?? []) {
+            specs.add(peer);
+        }
+        for (const rawProvider of entry.providers ?? []) {
+            const provider = (0, schema_1.parseProviderRequirement)(rawProvider);
+            if (provider.optional) {
+                optionalProviders.add(provider.raw);
+            }
+            else {
+                specs.add(provider.packageName);
+            }
+        }
+        for (const note of entry.notes ?? []) {
+            notes.push(`${component}: ${note}`);
+        }
+    }
+    const packageJson = await (0, readPackageJson_1.readPackageJson)(ctx.projectRoot);
+    const installed = (0, patch_1.getDependencyNames)(packageJson);
+    const plannedSpecs = [...specs]
+        .filter((spec) => !installed.has((0, patch_1.toPackageName)(spec)))
+        .sort((left, right) => left.localeCompare(right));
+    const localLattice = (0, output_1.resolveLocalLatticeCommand)(ctx.pmName);
+    ctx.logger.section("Selecting");
+    ctx.logger.kv("Project", ctx.projectRoot);
+    ctx.logger.section("Planning");
+    const componentSummary = (0, output_1.summarizeItems)(components);
+    ctx.logger.kv("Components", String(componentSummary.total));
+    if (componentSummary.total > 0) {
+        ctx.logger.list(componentSummary.visible);
+        if (componentSummary.hidden > 0) {
+            ctx.logger.step(`...and ${componentSummary.hidden} more`);
+        }
+    }
+    const plannedSummary = (0, output_1.summarizeItems)(plannedSpecs);
+    ctx.logger.kv("Packages to install", String(plannedSummary.total));
+    if (plannedSummary.total > 0) {
+        ctx.logger.list(plannedSummary.visible);
+        if (plannedSummary.hidden > 0) {
+            ctx.logger.step(`...and ${plannedSummary.hidden} more`);
+        }
+    }
+    if (ctx.options.dryRun) {
+        ctx.logger.section("Dry Run");
+        if (plannedSpecs.length > 0) {
+            ctx.logger.step(`[dry-run] ${ctx.pmName} add ${plannedSpecs.join(" ")}`);
+        }
+        else {
+            ctx.logger.step("[dry-run] No install actions required.");
+        }
+        ctx.logger.step("No files were changed.");
+    }
+    else {
+        ctx.logger.section("Applying");
+        if (plannedSpecs.length > 0) {
+            ctx.logger.step(`${ctx.pmName} add ${plannedSpecs.join(" ")}`);
+            const confirmed = await ctx.logger.confirm(`Install ${plannedSpecs.length} package(s) in ${ctx.projectRoot}?`);
+            if (!confirmed) {
+                ctx.logger.section("Result");
+                ctx.logger.warn("Add command cancelled.");
+                ctx.logger.section("Next Steps");
+                ctx.logger.step(`${localLattice} doctor`);
+                return;
+            }
+            const spinner = ctx.logger.spinner(`Installing ${plannedSpecs.length} package(s)...`);
+            await ctx.pm.add(false, plannedSpecs, ctx.projectRoot);
+            spinner.succeed("Dependencies installed.");
+        }
+        else {
+            ctx.logger.step("No installation required.");
+        }
+    }
+    ctx.logger.section("Result");
+    if (plannedSpecs.length === 0) {
+        ctx.logger.success("No new packages were needed.");
+    }
+    else {
+        ctx.logger.success(`Added components: ${components.join(", ")}`);
+    }
+    ctx.logger.kv("Installed packages", String(plannedSpecs.length));
+    if (optionalProviders.size > 0) {
+        const optionalSummary = (0, output_1.summarizeItems)([...optionalProviders].sort((left, right) => left.localeCompare(right)));
+        ctx.logger.warn(`Optional providers available: ${optionalSummary.total}`);
+        ctx.logger.list(optionalSummary.visible);
+        if (optionalSummary.hidden > 0) {
+            ctx.logger.step(`...and ${optionalSummary.hidden} more`);
+        }
+    }
+    if (notes.length > 0) {
+        const noteSummary = (0, output_1.summarizeItems)(notes);
+        ctx.logger.info(`Notes: ${noteSummary.total}`);
+        ctx.logger.list(noteSummary.visible);
+        if (noteSummary.hidden > 0) {
+            ctx.logger.step(`...and ${noteSummary.hidden} more`);
+        }
+    }
+    ctx.logger.section("Next Steps");
+    ctx.logger.step(`${localLattice} doctor`);
+    if (optionalProviders.size > 0) {
+        ctx.logger.step(`${localLattice} add <component>`);
+    }
+    if (notes.length > 0) {
+        ctx.logger.step("Review notes above before integrating components.");
+    }
+}

package/dist/commands/create.d.ts

@@ -0,0 +1,23 @@
+import { createLogger } from "../core/logger";
+import { resolveLatestVersions } from "../core/npm/latest";
+import { detectPackageManager } from "../core/pm/detect";
+import { promptInput, promptSelect } from "../core/prompt";
+export interface CreateCommandInput {
+    cwd: string;
+    projectPath?: string;
+    pm?: string;
+    yes: boolean;
+    git?: boolean;
+    template?: string;
+    lint?: boolean;
+}
+interface CreateCommandRuntimeOverrides {
+    detectPackageManagerFn?: typeof detectPackageManager;
+    resolveLatestVersionsFn?: typeof resolveLatestVersions;
+    runProcessFn?: (command: string, args: string[], cwd: string) => Promise<void>;
+    createLoggerFn?: typeof createLogger;
+    promptInputFn?: typeof promptInput;
+    promptSelectFn?: typeof promptSelect;
+}
+export declare function runCreateCommand(input: CreateCommandInput, runtimeOverrides?: CreateCommandRuntimeOverrides): Promise<void>;
+export {};