loor-cli 0.1.0

package/README.md

@@ -0,0 +1,307 @@
+# loor CLI
+
+CLI scaffolding tool for loor monorepo projects.
+
+## Installation
+
+```bash
+npm install -g loor
+# or
+pnpm add -g loor
+```
+
+## Commands
+
+### `loor init [name]`
+
+Create a new loor monorepo project.
+
+```bash
+loor init my-project
+```
+
+#### Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `name` | No | Project name. If omitted, prompted interactively. |
+
+#### Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--apps <apps>` | App types with optional names (comma-separated). Format: `type` or `type:name`. | `--apps api:backend,web-client:dashboard` |
+| `--packages <packages>` | Optional packages to include (comma-separated). | `--packages mediaKit,notification` |
+| `--no-packages` | Skip optional packages. Only required packages are installed. | |
+
+#### Usage Examples
+
+**Fully interactive** (prompts for everything):
+```bash
+loor init
+```
+
+**Non-interactive** (no prompts):
+```bash
+loor init my-saas \
+  --apps api:backend,web-client:dashboard \
+  --packages mediaKit,notification
+```
+
+**Partial — only skip app selection:**
+```bash
+loor init my-saas --apps api,web-client
+# App names default to "api" and "admin"
+# Packages will be prompted interactively
+```
+
+**Partial — only skip package selection:**
+```bash
+loor init my-saas --no-packages
+# App types and names will be prompted interactively
+# No optional packages installed (only required ones)
+```
+
+**Custom app names:**
+```bash
+loor init my-saas --apps api:my-api,web-client:admin,web-client:portal
+```
+
+#### App Types
+
+| Type | Description | Default Name |
+|------|-------------|--------------|
+| `api` | Express.js + MongoDB REST API server | `api` |
+| `web-client` | React + Vite admin panel / frontend | `admin` |
+
+Multiple apps of the same type are allowed (e.g., two `web-client` apps with different names).
+
+#### Required Packages
+
+These packages are always installed based on selected app types — they cannot be deselected:
+
+**API apps:** `auth`, `base`, `expressRouteKit`, `logger`, `eslintConfig`, `typescriptConfig`
+
+**Web Client apps:** `auth`, `base`, `storage`, `ui`, `i18n`, `routerProvider`, `commandMenu`, `apiClient`, `eslintConfig`, `typescriptConfig`
+
+#### What It Does
+
+1. Creates project directory with root config files (`turbo.json`, `pnpm-workspace.yaml`, `tsconfig.json`, etc.)
+2. Generates `package.json` programmatically
+3. Copies selected app templates from the reference apps
+4. Copies all packages, then removes artifacts of unselected packages (subtractive approach)
+5. Resolves transitive package dependencies automatically
+6. Replaces `@loor/` scope with `@<projectName>/` across the project
+
+---
+
+### `loor add app <type> [name]`
+
+Add a new app to an existing project.
+
+```bash
+loor add app api backend
+loor add app web-client dashboard
+```
+
+#### Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `type` | Yes | App type: `api` or `web-client` |
+| `name` | No | App name. Defaults to `api` for API, `admin` for web-client. |
+
+#### What It Does
+
+1. Copies reference app template to `apps/<name>/`
+2. Installs required packages for the app type (if missing)
+3. Removes artifacts of non-installed packages from the new app
+
+---
+
+### `loor add package <name>`
+
+Add a package to an existing project.
+
+```bash
+loor add package mediaKit
+loor add package notification
+```
+
+#### Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `name` | Yes | Package name from the registry |
+
+#### What It Does
+
+1. Resolves transitive dependencies automatically
+2. Copies package source to `packages/<name>/`
+3. Generates infra adapters in API apps (`src/infra/`)
+4. Generates client setup files in client apps
+5. Adds env vars to `.env.example`
+6. Merges npm dependencies into app `package.json` files
+7. Injects config annotation blocks
+
+---
+
+### `loor list`
+
+List all available packages with their descriptions, categories, and compatibility.
+
+```bash
+loor list
+```
+
+Packages are organized by category: **core**, **server**, **client**, **config**.
+
+---
+
+### `loor update`
+
+Force-refresh the package registry from the remote source.
+
+```bash
+loor update
+```
+
+The registry is cached locally (~/.loor/registry/) with a 24-hour TTL. This command forces a re-download.
+
+---
+
+### `loor config`
+
+Configure the CLI registry source (local development or remote production).
+
+```bash
+# Show current config
+loor config
+
+# Use local repo as source (for CLI development)
+loor config --local
+loor config --local /path/to/loor
+
+# Switch back to remote
+loor config --remote
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--local [path]` | Use a local repo as scaffold source. Defaults to current directory. |
+| `--remote` | Use the remote GitHub registry (production). |
+
+The `LOOR_LOCAL` environment variable overrides any persisted config.
+
+---
+
+### `loor ai init`
+
+Generate AI context files for the project.
+
+```bash
+loor ai init
+```
+
+#### What It Does
+
+1. Generates `CLAUDE.md` with project-specific context (apps, packages, conventions, routes, infra)
+2. Generates `.mcp.json` to register the loor MCP server
+
+---
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--debug` | Enable debug mode with detailed error output |
+| `--version` | Show CLI version |
+| `--help` | Show help for any command |
+
+```bash
+loor --debug init my-project
+loor init --help
+loor add app --help
+```
+
+---
+
+## MCP Server
+
+The CLI includes a built-in MCP (Model Context Protocol) server for AI integrations.
+
+```bash
+loor --mcp
+```
+
+This starts a stdio-based MCP server that exposes the following tools:
+
+| Tool | Description |
+|------|-------------|
+| `list_packages` | List available packages with optional category/compatibility filters |
+| `get_package_guide` | Get detailed guide for a specific package (patterns, infra, env vars) |
+| `get_conventions` | Get project conventions (architecture, routes, features) |
+| `how_to` | Step-by-step guides for common tasks |
+| `cli_usage` | Complete CLI command reference and usage examples |
+
+The MCP server is auto-registered via `loor ai init`.
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LOOR_LOCAL` | Path to local loor repo (overrides config) | — |
+| `LOOR_REPO` | GitHub repository | `ismailyagci/loor` |
+| `LOOR_BRANCH` | Git branch to use | `master` |
+
+---
+
+## Workflow Examples
+
+### Create a full-stack project (interactive)
+
+```bash
+loor init my-app
+# Select: api + web-client
+# Name api: api
+# Name web-client: admin
+# Select packages: mediaKit, notification
+cd my-app && pnpm install && pnpm dev
+```
+
+### Create a full-stack project (non-interactive / CI)
+
+```bash
+loor init my-app \
+  --apps api,web-client:admin \
+  --packages mediaKit,notification
+cd my-app && pnpm install && pnpm dev
+```
+
+### Add a second frontend to an existing project
+
+```bash
+cd my-app
+loor add app web-client portal
+pnpm install
+```
+
+### Add a package to an existing project
+
+```bash
+cd my-app
+loor add package mediaKit
+pnpm install
+```
+
+### Set up AI tooling
+
+```bash
+cd my-app
+loor ai init
+# CLAUDE.md and .mcp.json are generated
+```

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import {
+  enableDebug,
+  isDebug,
+  log
+} from "./chunk-AUVNDYJL.js";
+
+// src/bin.ts
+if (process.argv.includes("--debug")) enableDebug();
+try {
+  if (process.argv.includes("--mcp")) {
+    const { startMcpServer } = await import("./server-R2ZGYYBT.js");
+    await startMcpServer();
+  } else {
+    const { cli } = await import("./cli-PUXM5F6I.js");
+    await cli.parseAsync(process.argv);
+  }
+} catch (err) {
+  if (isDebug()) {
+    console.error("");
+    log.error("Command failed with error:");
+    console.error(err instanceof Error ? err.stack : err);
+  } else {
+    log.error(err instanceof Error ? err.message : String(err));
+    log.dim("  Run with --debug for full error details.");
+  }
+  process.exit(1);
+}

package/dist/chunk-AUVNDYJL.js

@@ -0,0 +1,26 @@
+// src/utils/logger.ts
+import chalk from "chalk";
+var debugEnabled = false;
+function enableDebug() {
+  debugEnabled = true;
+}
+function isDebug() {
+  return debugEnabled;
+}
+var log = {
+  info: (msg) => console.log(chalk.blue("info") + " " + msg),
+  success: (msg) => console.log(chalk.green("done") + " " + msg),
+  warn: (msg) => console.log(chalk.yellow("warn") + " " + msg),
+  error: (msg) => console.log(chalk.red("error") + " " + msg),
+  step: (msg) => console.log(chalk.cyan(">>") + " " + msg),
+  dim: (msg) => console.log(chalk.dim(msg)),
+  debug: (msg) => {
+    if (debugEnabled) console.log(chalk.magenta("debug") + " " + msg);
+  }
+};
+
+export {
+  enableDebug,
+  isDebug,
+  log
+};

package/dist/chunk-E6WOLYO3.js

@@ -0,0 +1,289 @@
+import {
+  log
+} from "./chunk-AUVNDYJL.js";
+
+// src/registry/packageRegistry.ts
+import path from "path";
+import fs from "fs-extra";
+var PackageRegistry = class {
+  packages = /* @__PURE__ */ new Map();
+  packagesDir;
+  constructor(packagesDir) {
+    this.packagesDir = packagesDir;
+  }
+  async load() {
+    const registryJsonPath = path.join(this.packagesDir, "..", "registry.json");
+    if (await fs.pathExists(registryJsonPath)) {
+      const manifests = await fs.readJson(registryJsonPath);
+      for (const m of manifests) {
+        this.packages.set(m.name, m);
+      }
+      return;
+    }
+    const entries = await fs.readdir(this.packagesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === "cli") continue;
+      const manifestPath = path.join(this.packagesDir, entry.name, "loor.json");
+      if (await fs.pathExists(manifestPath)) {
+        const manifest = await fs.readJson(manifestPath);
+        this.packages.set(manifest.name, manifest);
+      }
+    }
+  }
+  get(name) {
+    return this.packages.get(name);
+  }
+  getAll() {
+    return Array.from(this.packages.values());
+  }
+  getByCategory(category) {
+    return this.getAll().filter((pkg) => pkg.category === category);
+  }
+  getCompatible(appType) {
+    return this.getAll().filter((pkg) => pkg.compatibility.includes(appType));
+  }
+  getPackagesDir() {
+    return this.packagesDir;
+  }
+};
+
+// src/utils/fs.ts
+import path3 from "path";
+import os2 from "os";
+import fs3 from "fs-extra";
+
+// src/utils/config.ts
+import path2 from "path";
+import os from "os";
+import fs2 from "fs-extra";
+var CONFIG_DIR = path2.join(os.homedir(), ".loor");
+var CONFIG_PATH = path2.join(CONFIG_DIR, "config.json");
+var DEFAULT_CONFIG = { source: "remote" };
+async function readConfig() {
+  if (!await fs2.pathExists(CONFIG_PATH)) return DEFAULT_CONFIG;
+  try {
+    return await fs2.readJson(CONFIG_PATH);
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+async function writeConfig(config) {
+  await fs2.ensureDir(CONFIG_DIR);
+  await fs2.writeJson(CONFIG_PATH, config, { spaces: 2 });
+}
+
+// src/utils/fs.ts
+async function getRegistryDir() {
+  if (process.env.LOOR_LOCAL) return process.env.LOOR_LOCAL;
+  const config = await readConfig();
+  if (config.source === "local" && config.localPath) return config.localPath;
+  return path3.join(os2.homedir(), ".loor", "registry");
+}
+async function getPackagesDir() {
+  return path3.join(await getRegistryDir(), "packages");
+}
+async function getAppsDir() {
+  return path3.join(await getRegistryDir(), "apps");
+}
+async function detectProject(dir) {
+  return fs3.pathExists(path3.join(dir, "turbo.json"));
+}
+async function removeBetweenAnnotations(filePath, packageName) {
+  if (!await fs3.pathExists(filePath)) return;
+  const content = await fs3.readFile(filePath, "utf-8");
+  const lines = content.split("\n");
+  const result = [];
+  let skipping = false;
+  const startPatterns = [
+    `// @loor:package(${packageName})`,
+    `# @loor:package(${packageName})`
+  ];
+  const endPatterns = [
+    `// @loor:end(${packageName})`,
+    `# @loor:end(${packageName})`
+  ];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (startPatterns.some((p) => trimmed === p)) {
+      skipping = true;
+      continue;
+    }
+    if (endPatterns.some((p) => trimmed === p)) {
+      skipping = false;
+      continue;
+    }
+    if (!skipping) {
+      result.push(line);
+    }
+  }
+  await fs3.writeFile(filePath, result.join("\n"), "utf-8");
+}
+async function addAnnotatedBlock(filePath, packageName, content, commentPrefix = "//") {
+  if (!await fs3.pathExists(filePath)) return;
+  const fileContent = await fs3.readFile(filePath, "utf-8");
+  const startMarker = `${commentPrefix} @loor:package(${packageName})`;
+  const endMarker = `${commentPrefix} @loor:end(${packageName})`;
+  if (fileContent.includes(startMarker)) return;
+  const block = `
+  ${startMarker}
+${content}
+  ${endMarker}`;
+  if (filePath.endsWith(".ts")) {
+    const lastClose = fileContent.lastIndexOf("};");
+    if (lastClose !== -1) {
+      const before = fileContent.slice(0, lastClose);
+      const after = fileContent.slice(lastClose);
+      await fs3.writeFile(filePath, before + block + "\n" + after, "utf-8");
+      return;
+    }
+  }
+  const envBlock = `
+${startMarker}
+${content}
+${endMarker}
+`;
+  await fs3.writeFile(filePath, fileContent + envBlock, "utf-8");
+}
+async function replaceInFile(filePath, search, replace) {
+  if (!await fs3.pathExists(filePath)) return;
+  const content = await fs3.readFile(filePath, "utf-8");
+  const updated = content.split(search).join(replace);
+  await fs3.writeFile(filePath, updated, "utf-8");
+}
+async function removeDependencies(packageJsonPath, depNames) {
+  if (!await fs3.pathExists(packageJsonPath)) return;
+  const pkg = await fs3.readJson(packageJsonPath);
+  for (const name of depNames) {
+    if (pkg.dependencies) delete pkg.dependencies[name];
+    if (pkg.devDependencies) delete pkg.devDependencies[name];
+  }
+  await fs3.writeJson(packageJsonPath, pkg, { spaces: 2 });
+}
+async function mergeDependencies(packageJsonPath, deps, type = "dependencies") {
+  if (!await fs3.pathExists(packageJsonPath)) return;
+  const pkg = await fs3.readJson(packageJsonPath);
+  pkg[type] = { ...pkg[type], ...deps };
+  pkg[type] = Object.fromEntries(
+    Object.entries(pkg[type]).sort(([a], [b]) => a.localeCompare(b))
+  );
+  await fs3.writeJson(packageJsonPath, pkg, { spaces: 2 });
+}
+
+// src/utils/cache.ts
+import path4 from "path";
+import os3 from "os";
+import fs4 from "fs-extra";
+import { execSync } from "child_process";
+var CACHE_DIR = path4.join(os3.homedir(), ".loor");
+var REGISTRY_DIR = path4.join(CACHE_DIR, "registry");
+var META_PATH = path4.join(CACHE_DIR, "meta.json");
+var DEFAULT_REPO = "ismailyagci/loor";
+var DEFAULT_BRANCH = "master";
+var CACHE_TTL = 24 * 60 * 60 * 1e3;
+var GITHUB_TOKEN = "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";
+function getRepo() {
+  return process.env.LOOR_REPO || DEFAULT_REPO;
+}
+function getBranch() {
+  return process.env.LOOR_BRANCH || DEFAULT_BRANCH;
+}
+async function readMeta() {
+  if (!await fs4.pathExists(META_PATH)) return null;
+  try {
+    return await fs4.readJson(META_PATH);
+  } catch {
+    return null;
+  }
+}
+async function writeMeta(meta) {
+  await fs4.ensureDir(CACHE_DIR);
+  await fs4.writeJson(META_PATH, meta, { spaces: 2 });
+}
+function isCacheValid(meta) {
+  const repo = getRepo();
+  const branch = getBranch();
+  if (meta.repo !== repo || meta.branch !== branch) return false;
+  return Date.now() - meta.lastUpdated < CACHE_TTL;
+}
+async function ensureCache(opts) {
+  const envPath = process.env.LOOR_LOCAL;
+  if (envPath) {
+    if (!await fs4.pathExists(envPath)) {
+      throw new Error(`LOOR_LOCAL path does not exist: ${envPath}`);
+    }
+    log.info(`Using local registry: ${envPath}`);
+    return envPath;
+  }
+  const config = await readConfig();
+  if (config.source === "local" && config.localPath) {
+    if (!await fs4.pathExists(config.localPath)) {
+      throw new Error(`Configured local path does not exist: ${config.localPath}
+Run "loor config --remote" to switch back.`);
+    }
+    log.info(`Using local registry: ${config.localPath}`);
+    return config.localPath;
+  }
+  const meta = await readMeta();
+  if (!opts?.force && meta && isCacheValid(meta) && await fs4.pathExists(REGISTRY_DIR)) {
+    return REGISTRY_DIR;
+  }
+  const repo = getRepo();
+  const branch = getBranch();
+  const tarballUrl = `https://api.github.com/repos/${repo}/tarball/${branch}`;
+  log.info(`Fetching registry from ${repo}@${branch}...`);
+  try {
+    await downloadAndExtract(tarballUrl, REGISTRY_DIR);
+  } catch (err) {
+    if (meta && await fs4.pathExists(REGISTRY_DIR)) {
+      log.warn("Failed to update registry, using cached version.");
+      return REGISTRY_DIR;
+    }
+    throw new Error(
+      `Failed to download registry from ${tarballUrl}. Check your internet connection and ensure the repo exists.
+${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  await writeMeta({ lastUpdated: Date.now(), repo, branch });
+  log.success("Registry updated.");
+  return REGISTRY_DIR;
+}
+async function downloadAndExtract(url, destDir) {
+  await fs4.ensureDir(CACHE_DIR);
+  const tmpFile = path4.join(CACHE_DIR, "registry.tar.gz");
+  try {
+    const headers = { Accept: "application/vnd.github+json" };
+    if (GITHUB_TOKEN) {
+      headers["Authorization"] = `Bearer ${GITHUB_TOKEN}`;
+    }
+    const response = await fetch(url, { headers, redirect: "follow" });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    await fs4.writeFile(tmpFile, buffer);
+    await fs4.remove(destDir);
+    await fs4.ensureDir(destDir);
+    execSync(`tar -xzf "${tmpFile}" --strip-components=1 -C "${destDir}"`, {
+      stdio: "ignore"
+    });
+  } finally {
+    await fs4.remove(tmpFile);
+  }
+}
+
+export {
+  PackageRegistry,
+  readConfig,
+  writeConfig,
+  getRegistryDir,
+  getPackagesDir,
+  getAppsDir,
+  detectProject,
+  removeBetweenAnnotations,
+  addAnnotatedBlock,
+  replaceInFile,
+  removeDependencies,
+  mergeDependencies,
+  ensureCache
+};