loor-cli 0.1.0

package/dist/server-R2ZGYYBT.js

@@ -0,0 +1,954 @@
+import {
+  PackageRegistry,
+  ensureCache,
+  getPackagesDir
+} from "./chunk-E6WOLYO3.js";
+import "./chunk-AUVNDYJL.js";
+
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/mcp/tools/listPackages.ts
+import { z } from "zod";
+function registerListPackages(server, registry) {
+  server.tool(
+    "list_packages",
+    "List all available loor packages with descriptions, categories, and compatibility info",
+    {
+      category: z.enum(["core", "server", "client", "config"]).optional().describe("Filter by category"),
+      compatibility: z.enum(["api", "client"]).optional().describe("Filter by app compatibility")
+    },
+    async ({ category, compatibility }) => {
+      let packages = registry.getAll();
+      if (category) {
+        packages = packages.filter((p) => p.category === category);
+      }
+      if (compatibility) {
+        packages = packages.filter((p) => p.compatibility.includes(compatibility));
+      }
+      const result = packages.map((p) => ({
+        name: p.name,
+        description: p.description,
+        category: p.category,
+        compatibility: p.compatibility,
+        requires: p.requires
+      }));
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/mcp/tools/getPackageGuide.ts
+import path from "path";
+import fs from "fs-extra";
+import { z as z2 } from "zod";
+function registerGetPackageGuide(server, registry) {
+  server.tool(
+    "get_package_guide",
+    "Get detailed guide for a specific loor package including patterns, donts, architecture docs, and infra info",
+    {
+      name: z2.string().describe('Package name (e.g. "auth", "mediaKit", "expressRouteKit")')
+    },
+    async ({ name }) => {
+      const manifest = registry.get(name);
+      if (!manifest) {
+        return {
+          content: [{ type: "text", text: `Package "${name}" not found. Use list_packages to see available packages.` }],
+          isError: true
+        };
+      }
+      const sections = [];
+      sections.push(`# ${manifest.name}`);
+      sections.push(`${manifest.description}`);
+      sections.push(`**Category:** ${manifest.category} | **Compatibility:** ${manifest.compatibility.join(", ")}`);
+      if (manifest.requires.length > 0) {
+        sections.push(`**Requires:** ${manifest.requires.join(", ")}`);
+      }
+      if (manifest.ai?.patterns?.length) {
+        sections.push("\n## DO");
+        for (const p of manifest.ai.patterns) {
+          sections.push(`- ${p}`);
+        }
+      }
+      if (manifest.ai?.donts?.length) {
+        sections.push("\n## DON'T");
+        for (const d of manifest.ai.donts) {
+          sections.push(`- ${d}`);
+        }
+      }
+      if (manifest.apiInfra?.length) {
+        sections.push("\n## API Infrastructure Files");
+        for (const infra of manifest.apiInfra) {
+          sections.push(`- \`${infra.path}\` \u2014 ${infra.description}`);
+        }
+      }
+      if (manifest.clientSetup?.length) {
+        sections.push("\n## Client Setup Files");
+        for (const setup of manifest.clientSetup) {
+          sections.push(`- \`${setup.path}\` \u2014 ${setup.description}`);
+        }
+      }
+      if (manifest.envVars?.length) {
+        sections.push("\n## Environment Variables");
+        for (const env of manifest.envVars) {
+          const req = env.required ? "(required)" : "(optional)";
+          sections.push(`- \`${env.key}\` ${req} \u2014 ${env.description}`);
+        }
+      }
+      const pkgDir = path.join(registry.getPackagesDir(), name);
+      const archDocPath = manifest.ai?.guide ? path.join(pkgDir, manifest.ai.guide) : path.join(pkgDir, "docs", "architecture.md");
+      if (await fs.pathExists(archDocPath)) {
+        const archDoc = await fs.readFile(archDocPath, "utf-8");
+        sections.push("\n## Architecture Guide");
+        sections.push(archDoc);
+      }
+      const readmePath = path.join(pkgDir, "README.md");
+      if (await fs.pathExists(readmePath)) {
+        const readme = await fs.readFile(readmePath, "utf-8");
+        sections.push("\n## README");
+        sections.push(readme);
+      }
+      return {
+        content: [{ type: "text", text: sections.join("\n") }]
+      };
+    }
+  );
+}
+
+// src/mcp/tools/getConventions.ts
+import { z as z3 } from "zod";
+
+// src/mcp/context/conventions.ts
+import path2 from "path";
+import fs2 from "fs-extra";
+async function loadConventions(packagesDir) {
+  const docsDir = path2.join(packagesDir, "..", "docs");
+  const packageStandardPath = path2.join(docsDir, "PACKAGE_STANDARD.md");
+  const packageArchPath = path2.join(docsDir, "PACKAGE_ARCHITECTURE.md");
+  const packageStandard = await fs2.pathExists(packageStandardPath) ? await fs2.readFile(packageStandardPath, "utf-8") : "";
+  const packageArch = await fs2.pathExists(packageArchPath) ? await fs2.readFile(packageArchPath, "utf-8") : "";
+  return {
+    architecture: packageArch || getFallbackArchitecture(),
+    packageStructure: packageStandard || getFallbackPackageStructure(),
+    routePattern: getRoutePatternConventions(),
+    featureDev: getFeatureDevConventions()
+  };
+}
+function getFallbackArchitecture() {
+  return `# Architecture Conventions
+
+## Hexagonal Architecture (Ports & Adapters)
+
+- **Packages** define abstract ports (interfaces) in \`ports/\` folder
+- **Apps** implement adapters in \`infra/\` folder
+- Factory functions accept ports as dependencies for DI
+
+## Package Exports
+
+\`\`\`
+packages/<name>/src/
+\u251C\u2500\u2500 index.ts         # Pure exports (browser, RN, Edge compatible)
+\u251C\u2500\u2500 server/index.ts  # Node.js only exports
+\u2514\u2500\u2500 client/index.ts  # Browser only exports (optional)
+\`\`\`
+
+- Use \`Uint8Array\` instead of \`Buffer\` for universal compatibility
+- Keep \`index.ts\` free of Node.js-specific imports (fs, streams, etc.)`;
+}
+function getFallbackPackageStructure() {
+  return `# Package Structure Conventions
+
+## Directory Layout
+
+\`\`\`
+packages/<name>/
+\u251C\u2500\u2500 src/
+\u2502   \u251C\u2500\u2500 index.ts           # Pure exports
+\u2502   \u251C\u2500\u2500 server/index.ts    # Node.js adapters
+\u2502   \u251C\u2500\u2500 client/index.ts    # Browser adapters
+\u2502   \u251C\u2500\u2500 core/              # Business logic
+\u2502   \u251C\u2500\u2500 ports/             # Interface definitions
+\u2502   \u2514\u2500\u2500 adapters/          # Adapter implementations
+\u251C\u2500\u2500 docs/
+\u2502   \u2514\u2500\u2500 architecture.md    # Package design docs
+\u251C\u2500\u2500 loor.json        # Package manifest
+\u251C\u2500\u2500 package.json
+\u2514\u2500\u2500 tsconfig.json
+\`\`\`
+
+## Key Rules
+
+1. Ports define interfaces, adapters implement them
+2. Core logic depends only on ports, never on adapters
+3. Apps wire adapters in \`src/infra/\` directory`;
+}
+function getRoutePatternConventions() {
+  return `# Route Pattern Conventions
+
+## File-System Route Discovery
+
+Routes are placed in \`src/routes/<domain>/<action>/index.ts\` and auto-discovered by routerLoader.
+
+## RouteProvider Pattern
+
+Each route extends \`RouteProvider\` and implements:
+- \`method\`: HTTP method (GET, POST, PUT, DELETE)
+- \`path\`: URL path with params (e.g. \`/admin/creators/:id\`)
+- \`middleware\`: Array of Express middleware (auth, role check)
+- \`validate(req)\`: Zod schema validation, returns typed data
+- \`handle(req, res, data)\`: Business logic with validated data
+
+## Response Helpers
+
+Use \`sendSuccess(res, data)\` and \`sendError(res, error)\` from expressRouteKit.
+
+## Example Structure
+
+\`\`\`
+src/routes/
+\u251C\u2500\u2500 admin/
+\u2502   \u251C\u2500\u2500 users/
+\u2502   \u2502   \u251C\u2500\u2500 list/index.ts    # GET /admin/users
+\u2502   \u2502   \u251C\u2500\u2500 get/index.ts     # GET /admin/users/:id
+\u2502   \u2502   \u251C\u2500\u2500 create/index.ts  # POST /admin/users
+\u2502   \u2502   \u2514\u2500\u2500 delete/index.ts  # DELETE /admin/users/:id
+\u2502   \u2514\u2500\u2500 creators/
+\u2502       \u251C\u2500\u2500 list/index.ts
+\u2502       \u2514\u2500\u2500 approve/index.ts
+\u251C\u2500\u2500 auth/
+\u2502   \u2514\u2500\u2500 admin/
+\u2502       \u251C\u2500\u2500 login/index.ts
+\u2502       \u2514\u2500\u2500 refreshToken/index.ts
+\u2514\u2500\u2500 media/
+    \u251C\u2500\u2500 image/upload/index.ts
+    \u2514\u2500\u2500 image/download/index.ts
+\`\`\``;
+}
+function getFeatureDevConventions() {
+  return `# Feature Development Conventions (Client Apps)
+
+## Feature Folder Structure
+
+\`\`\`
+src/features/<featureName>/
+\u251C\u2500\u2500 index.tsx                  # Main page/component
+\u251C\u2500\u2500 components/
+\u2502   \u251C\u2500\u2500 columns.tsx            # DataTable column definitions
+\u2502   \u251C\u2500\u2500 dataTableToolbar.tsx   # Search/filter toolbar
+\u2502   \u2514\u2500\u2500 selectionActionBar.tsx # Bulk action bar
+\u251C\u2500\u2500 hooks/
+\u2502   \u251C\u2500\u2500 use<Feature>Form.ts   # Form logic (react-hook-form + zod)
+\u2502   \u2514\u2500\u2500 useDelete<Feature>.ts # Delete mutation hook
+\u251C\u2500\u2500 types/
+\u2502   \u2514\u2500\u2500 index.ts              # Feature-specific types
+\u251C\u2500\u2500 validations/
+\u2502   \u2514\u2500\u2500 index.ts              # Zod schemas
+\u2514\u2500\u2500 locales/
+    \u251C\u2500\u2500 en.ts                  # English translations
+    \u2514\u2500\u2500 ar.ts                  # Arabic translations
+\`\`\`
+
+## Key Patterns
+
+1. Each feature is self-contained with its own components, hooks, types, locales
+2. DataTable pattern: columns.tsx + dataTableToolbar.tsx + selectionActionBar.tsx
+3. Form pattern: useForm hook wrapping react-hook-form with zodResolver
+4. API calls through RTK Query hooks from apiClient services
+5. All user-facing strings via i18n translation keys`;
+}
+
+// src/mcp/tools/getConventions.ts
+function registerGetConventions(server, registry) {
+  server.tool(
+    "get_conventions",
+    "Get loor project conventions for architecture, package structure, route patterns, and feature development",
+    {
+      topic: z3.enum(["all", "architecture", "package_structure", "route_pattern", "feature_dev"]).optional().default("all").describe("Convention topic to retrieve")
+    },
+    async ({ topic }) => {
+      const conventions = await loadConventions(registry.getPackagesDir());
+      const sections = [];
+      if (topic === "all" || topic === "architecture") {
+        sections.push(conventions.architecture);
+      }
+      if (topic === "all" || topic === "package_structure") {
+        sections.push(conventions.packageStructure);
+      }
+      if (topic === "all" || topic === "route_pattern") {
+        sections.push(conventions.routePattern);
+      }
+      if (topic === "all" || topic === "feature_dev") {
+        sections.push(conventions.featureDev);
+      }
+      return {
+        content: [{ type: "text", text: sections.join("\n\n---\n\n") }]
+      };
+    }
+  );
+}
+
+// src/mcp/tools/howTo.ts
+import { z as z4 } from "zod";
+
+// src/mcp/context/howToGuides.ts
+var guides = {
+  create_project: `# How To: Create a New Project
+
+## Interactive Mode
+
+\`\`\`bash
+loor init
+\`\`\`
+
+Prompts for: project name, app types, app names, and optional packages.
+
+## Non-Interactive Mode (CI / Scripted)
+
+\`\`\`bash
+loor init my-saas --apps api:backend,web-client:dashboard --packages mediaKit,notification
+\`\`\`
+
+## --apps Flag Format
+
+\`type\` or \`type:name\`, comma-separated:
+- \`--apps api\` \u2192 API app with default name "api"
+- \`--apps api:backend\` \u2192 API app named "backend"
+- \`--apps api,web-client\` \u2192 API "api" + web-client "admin" (defaults)
+- \`--apps api:backend,web-client:dash,web-client:portal\` \u2192 multiple apps
+
+Valid types: \`api\`, \`web-client\`
+
+## --packages Flag Format
+
+- \`--packages mediaKit,notification\` \u2192 include these optional packages
+- \`--no-packages\` \u2192 skip optional packages (only required ones installed)
+- *(omit flag)* \u2192 prompted interactively
+
+## Partial Flag Usage
+
+Each flag independently skips its prompt:
+- Only \`--apps\` \u2192 packages still prompted
+- Only \`--packages\` \u2192 apps still prompted
+- Both \u2192 fully non-interactive
+
+## After Creation
+
+\`\`\`bash
+cd my-saas
+pnpm install
+pnpm dev
+\`\`\`
+
+## Adding More Apps Later
+
+\`\`\`bash
+loor add app web-client portal
+pnpm install
+\`\`\`
+
+## Adding More Packages Later
+
+\`\`\`bash
+loor add package scheduler
+pnpm install
+\`\`\``,
+  add_api_route: `# How To: Add an API Route
+
+## Steps
+
+### 1. Create the route file
+Create \`src/routes/<domain>/<action>/index.ts\` in your API app.
+
+### 2. Extend RouteProvider
+\`\`\`typescript
+import { RouteProvider, sendSuccess, sendError } from '@workspace/expressRouteKit';
+import { z } from 'zod';
+
+const schema = z.object({
+  // define request validation
+});
+
+export default class extends RouteProvider {
+  method = 'post' as const;
+  path = '/domain/action';
+  middleware = []; // add auth, role middleware as needed
+
+  validate(req: Request) {
+    return schema.parse(req.body);
+  }
+
+  async handle(req: Request, res: Response, data: z.infer<typeof schema>) {
+    // business logic
+    sendSuccess(res, { result });
+  }
+}
+\`\`\`
+
+### 3. Add middleware (if protected)
+\`\`\`typescript
+import { bearerAuthMiddleware } from '@/infra/tokenService';
+import { roleMiddleware } from '@workspace/auth/server';
+
+middleware = [bearerAuthMiddleware, roleMiddleware(['admin'])];
+\`\`\`
+
+### 4. Test
+The route is auto-discovered by routerLoader. Restart the server and test the endpoint.
+
+## Key Points
+- Routes are auto-discovered from the file system \u2014 no manual registration needed
+- Always validate input with Zod in \`validate()\`
+- Use \`sendSuccess()\` and \`sendError()\` for consistent response format
+- Add rate limiting for public endpoints`,
+  add_feature: `# How To: Add a Client Feature
+
+## Steps
+
+### 1. Create feature directory
+\`\`\`
+src/features/<featureName>/
+\u251C\u2500\u2500 index.tsx
+\u251C\u2500\u2500 components/
+\u251C\u2500\u2500 hooks/
+\u251C\u2500\u2500 types/
+\u251C\u2500\u2500 validations/
+\u2514\u2500\u2500 locales/
+    \u251C\u2500\u2500 en.ts
+    \u2514\u2500\u2500 ar.ts
+\`\`\`
+
+### 2. Define types
+\`\`\`typescript
+// types/index.ts
+export interface MyEntity {
+  id: string;
+  name: string;
+  // ...
+}
+\`\`\`
+
+### 3. Create API service (if needed)
+\`\`\`typescript
+// In src/api/services/<domain>.ts
+import { baseApi } from '../baseApi';
+
+const api = baseApi.injectEndpoints({
+  endpoints: (build) => ({
+    listEntities: build.query({ query: () => '/entities' }),
+    createEntity: build.mutation({ query: (body) => ({ url: '/entities', method: 'POST', body }) }),
+  }),
+});
+
+export const { useListEntitiesQuery, useCreateEntityMutation } = api;
+\`\`\`
+
+### 4. Build the page component
+\`\`\`typescript
+// index.tsx
+import { DataTable } from '@workspace/ui';
+import { columns } from './components/columns';
+
+export default function MyFeaturePage() {
+  const { data } = useListEntitiesQuery();
+  return <DataTable columns={columns} data={data ?? []} />;
+}
+\`\`\`
+
+### 5. Add route
+Register the page in your router config with appropriate auth guards.
+
+### 6. Add translations
+Add \`en.ts\` and \`ar.ts\` locale files and register them with i18n.
+
+## Key Points
+- Each feature is self-contained
+- Use DataTable for list views with sorting, filtering, pagination
+- Use react-hook-form + zod for forms
+- All strings through i18n`,
+  add_package: `# How To: Add a Package to a Project
+
+## Using CLI (Recommended)
+
+\`\`\`bash
+loor add package <name>
+\`\`\`
+
+This will:
+1. Resolve transitive dependencies automatically
+2. Copy package source to \`packages/<name>/\`
+3. Generate infra adapters in API apps (\`src/infra/\`)
+4. Generate client setup files in client apps
+5. Add env vars to \`.env.example\`
+6. Merge app dependencies into \`package.json\`
+
+## Adding Packages During Project Init
+
+You can also include packages at project creation time:
+
+\`\`\`bash
+# Interactive selection
+loor init my-project
+
+# Via CLI flag (non-interactive)
+loor init my-project --apps api,web-client --packages mediaKit,notification
+
+# Skip optional packages entirely
+loor init my-project --apps api --no-packages
+\`\`\`
+
+## Manual Steps (if needed)
+
+### 1. Copy package
+Copy from the registry to \`packages/<name>/\`.
+
+### 2. Wire infrastructure
+For API packages, create adapter files in \`apps/<apiApp>/src/infra/\`:
+\`\`\`typescript
+// Example: src/infra/logger.ts
+import { createPinoLogger } from '@workspace/logger/server';
+import config from '../config';
+
+export const logger = createPinoLogger({
+  level: config.log.level,
+  pretty: config.log.pretty,
+});
+\`\`\`
+
+### 3. Add dependencies
+Install the package's \`appDependencies\` in the relevant apps.
+
+### 4. Configure env vars
+Add required env vars from the package manifest to \`.env\`.
+
+## Key Points
+- Always check \`requires\` field \u2014 install dependencies first
+- Use \`loor list\` to see available packages
+- Run \`pnpm install\` after adding packages
+- Use \`cli_usage\` MCP tool for full CLI reference`,
+  add_infra_adapter: `# How To: Add an Infrastructure Adapter
+
+## Overview
+Adapters implement package ports (interfaces) with concrete dependencies. They live in \`apps/<appName>/src/infra/\`.
+
+## Steps
+
+### 1. Identify the port
+Find the port interface in the package's \`src/ports/\` directory:
+\`\`\`typescript
+// packages/logger/src/ports/errorLog.port.ts
+export interface ErrorLogPort {
+  error(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+}
+\`\`\`
+
+### 2. Create the adapter
+\`\`\`typescript
+// apps/myApi/src/infra/logger.ts
+import { createPinoLogger } from '@workspace/logger/server';
+import config from '../config';
+
+export const logger = createPinoLogger({
+  level: config.log.level,
+  pretty: config.log.pretty,
+});
+\`\`\`
+
+### 3. Inject into services
+Pass the adapter as a dependency where needed:
+\`\`\`typescript
+import { logger } from '@/infra/logger';
+import { createAuthService } from '@workspace/auth';
+
+export const authService = createAuthService({ logger });
+\`\`\`
+
+### 4. Add config/env vars
+If the adapter needs configuration:
+- Add env vars to \`.env.example\`
+- Add config keys to \`src/config/index.ts\`
+
+## Naming Convention
+- File: \`src/infra/<adapterName>.ts\`
+- Export: named export matching the port purpose (e.g. \`logger\`, \`tokenService\`, \`mediaStorage\`)
+
+## Key Points
+- One adapter file per port implementation
+- Import factory from \`@workspace/<package>/server\`
+- Wire config values from \`src/config/\`
+- Adapters are singletons \u2014 instantiate once, export for reuse`
+};
+function getHowToGuide(task) {
+  return guides[task];
+}
+
+// src/mcp/tools/howTo.ts
+function registerHowTo(server) {
+  server.tool(
+    "how_to",
+    "Get step-by-step instructions for common loor development tasks",
+    {
+      task: z4.enum(["create_project", "add_api_route", "add_feature", "add_package", "add_infra_adapter"]).describe("The task you need step-by-step instructions for")
+    },
+    async ({ task }) => {
+      const guide = getHowToGuide(task);
+      return {
+        content: [{ type: "text", text: guide }]
+      };
+    }
+  );
+}
+
+// src/mcp/tools/cliUsage.ts
+import { z as z5 } from "zod";
+var commands = {
+  init: `# loor init [name]
+
+Create a new loor monorepo project.
+
+## Arguments
+
+- \`name\` (optional) \u2014 Project name. If omitted, prompted interactively.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| \`--apps <apps>\` | App types with optional names (comma-separated). Format: \`type\` or \`type:name\`. |
+| \`--packages <packages>\` | Optional packages to include (comma-separated). |
+| \`--no-packages\` | Skip optional packages \u2014 only required ones are installed. |
+
+## App Types
+
+| Type | Description | Default Name |
+|------|-------------|--------------|
+| \`api\` | Express.js + MongoDB REST API | \`api\` |
+| \`web-client\` | React + Vite frontend | \`admin\` |
+
+Multiple apps of the same type are allowed (e.g., two web-client apps with different names).
+
+## Examples
+
+### Fully interactive
+\`\`\`bash
+loor init
+\`\`\`
+
+### Fully non-interactive
+\`\`\`bash
+loor init my-saas --apps api:backend,web-client:dashboard --packages mediaKit,notification
+\`\`\`
+
+### Custom app names, default packages prompt
+\`\`\`bash
+loor init my-saas --apps api:my-api,web-client:admin
+\`\`\`
+
+### Default app names
+\`\`\`bash
+loor init my-saas --apps api,web-client
+# api app \u2192 "api", web-client app \u2192 "admin"
+\`\`\`
+
+### Skip optional packages
+\`\`\`bash
+loor init my-saas --apps api,web-client --no-packages
+\`\`\`
+
+### Only specify packages (apps prompted interactively)
+\`\`\`bash
+loor init my-saas --packages mediaKit,notification
+\`\`\`
+
+## Required Packages (always installed)
+
+**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 configs (turbo.json, pnpm-workspace.yaml, tsconfig.json, etc.)
+2. Generates package.json programmatically
+3. Copies selected app templates from 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`,
+  add_app: `# loor add app <type> [name]
+
+Add a new app to an existing project. Must be run from the project root.
+
+## 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. |
+
+## Examples
+
+\`\`\`bash
+loor add app api
+loor add app api backend
+loor add app web-client dashboard
+loor add app web-client portal
+\`\`\`
+
+## What It Does
+
+1. Copies reference app template to \`apps/<name>/\`
+2. Installs required packages for the app type (if missing from project)
+3. Removes artifacts of non-installed packages from the new app
+4. You need to run \`pnpm install\` after`,
+  add_package: `# loor add package <name>
+
+Add a package to an existing project. Must be run from the project root.
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| \`name\` | Yes | Package name from the registry |
+
+## Examples
+
+\`\`\`bash
+loor add package mediaKit
+loor add package notification
+loor add package scheduler
+\`\`\`
+
+## 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
+
+## Tips
+
+- Use \`loor list\` to see all available packages
+- Already-installed packages are skipped
+- Run \`pnpm install\` after adding packages`,
+  list: `# loor list
+
+List all available packages with descriptions, categories, and compatibility info.
+
+\`\`\`bash
+loor list
+\`\`\`
+
+Packages are organized by category: **core**, **server**, **client**, **config**.
+
+Each entry shows: name, description, compatibility (api/client), and required dependencies.`,
+  update: `# 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 regardless of cache age.`,
+  config: `# loor config
+
+Configure the CLI registry source \u2014 local development or remote production.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| \`--local [path]\` | Use a local repo as scaffold source. Defaults to current directory. |
+| \`--remote\` | Use the remote GitHub registry (production). |
+| *(no flags)* | Show current configuration. |
+
+## Examples
+
+\`\`\`bash
+# Show current config
+loor config
+
+# Use local repo (current directory)
+loor config --local
+
+# Use local repo (specific path)
+loor config --local /path/to/loor
+
+# Switch back to remote
+loor config --remote
+\`\`\`
+
+## Environment Variable
+
+The \`LOOR_LOCAL\` env var overrides any persisted config. When set, CLI always uses the path it points to.`,
+  ai_init: `# loor ai init
+
+Generate AI context files for the project.
+
+\`\`\`bash
+loor ai init
+\`\`\`
+
+## What It Does
+
+1. Scans the project for installed apps and packages
+2. Generates \`CLAUDE.md\` with project-specific AI context:
+   - App list with types and paths
+   - Architecture overview
+   - Installed packages with DO/DON'T patterns
+   - Infra files and required env vars
+   - Conventions (hexagonal architecture, routes, features)
+   - App-specific context (routes, infra, features)
+3. Generates \`.mcp.json\` to register the loor MCP server
+
+## MCP Tools Available After Init
+
+| Tool | Description |
+|------|-------------|
+| \`list_packages\` | List packages with optional category/compatibility filters |
+| \`get_package_guide\` | Detailed package guide (patterns, infra, env vars, docs) |
+| \`get_conventions\` | Project conventions (architecture, routes, features) |
+| \`how_to\` | Step-by-step guides for common development tasks |
+| \`cli_usage\` | Complete CLI command reference and usage examples |`,
+  overview: `# loor CLI \u2014 Complete Reference
+
+## All Commands
+
+| Command | Description |
+|---------|-------------|
+| \`loor init [name]\` | Create a new monorepo project |
+| \`loor add app <type> [name]\` | Add an app to existing project |
+| \`loor add package <name>\` | Add a package to existing project |
+| \`loor list\` | List available packages |
+| \`loor update\` | Refresh registry cache |
+| \`loor config\` | Configure registry source |
+| \`loor ai init\` | Generate AI context files |
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| \`--debug\` | Enable debug mode with detailed error output |
+| \`--version\` | Show CLI version |
+| \`--help\` | Show help for any command |
+
+## Init Command \u2014 Quick Reference
+
+\`\`\`bash
+# Fully interactive
+loor init
+
+# Fully non-interactive
+loor init my-saas --apps api:backend,web-client:dashboard --packages mediaKit
+
+# Skip optional packages
+loor init my-saas --apps api,web-client --no-packages
+
+# Only specify apps
+loor init my-saas --apps api:my-api,web-client:admin
+
+# Only specify packages
+loor init my-saas --packages mediaKit,notification
+\`\`\`
+
+## --apps Flag Format
+
+\`type\` or \`type:name\`, comma-separated:
+- \`--apps api\` \u2192 API app named "api"
+- \`--apps api:backend\` \u2192 API app named "backend"
+- \`--apps api,web-client\` \u2192 API "api" + web-client "admin"
+- \`--apps api:backend,web-client:dash\` \u2192 API "backend" + web-client "dash"
+
+Valid types: \`api\`, \`web-client\`
+
+## --packages Flag Format
+
+Comma-separated package names:
+- \`--packages mediaKit\` \u2192 add mediaKit
+- \`--packages mediaKit,notification,scheduler\` \u2192 add multiple
+- \`--no-packages\` \u2192 no optional packages
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| \`LOOR_LOCAL\` | Override config to use local repo path |
+| \`LOOR_REPO\` | GitHub repo (default: ismailyagci/loor) |
+| \`LOOR_BRANCH\` | Branch (default: master) |
+
+## Typical Workflows
+
+### New project (CI/scripted)
+\`\`\`bash
+loor init my-app --apps api,web-client:admin --packages mediaKit
+cd my-app && pnpm install && pnpm dev
+\`\`\`
+
+### Add second frontend
+\`\`\`bash
+cd my-app
+loor add app web-client portal
+pnpm install
+\`\`\`
+
+### Add package
+\`\`\`bash
+cd my-app
+loor add package notification
+pnpm install
+\`\`\`
+
+### Setup AI context
+\`\`\`bash
+cd my-app
+loor ai init
+\`\`\``
+};
+function registerCliUsage(server) {
+  server.tool(
+    "cli_usage",
+    "Get detailed CLI command reference, usage examples, and available options for loor commands",
+    {
+      command: z5.enum(["overview", "init", "add_app", "add_package", "list", "update", "config", "ai_init"]).optional().default("overview").describe('CLI command to get usage info for. Use "overview" for complete reference.')
+    },
+    async ({ command }) => {
+      const content = commands[command];
+      return {
+        content: [{ type: "text", text: content }]
+      };
+    }
+  );
+}
+
+// src/mcp/server.ts
+async function startMcpServer() {
+  const originalLog = console.log;
+  console.log = console.error;
+  try {
+    await ensureCache();
+  } finally {
+    console.log = originalLog;
+  }
+  const registry = new PackageRegistry(await getPackagesDir());
+  await registry.load();
+  const server = new McpServer({
+    name: "loor",
+    version: "0.1.0"
+  });
+  registerListPackages(server, registry);
+  registerGetPackageGuide(server, registry);
+  registerGetConventions(server, registry);
+  registerHowTo(server);
+  registerCliUsage(server);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+export {
+  startMcpServer
+};