@l4yercak3/cli 1.2.21 → 1.3.0

package/bin/cli.js

@@ -18,6 +18,10 @@ const apiKeysCommand = require('../src/commands/api-keys');
 const upgradeCommand = require('../src/commands/upgrade');
 const mcpServerCommand = require('../src/commands/mcp-server');
 const mcpSetupCommand = require('../src/commands/mcp-setup');
+const pagesCommand = require('../src/commands/pages');
+const connectCommand = require('../src/commands/connect');
+const scaffoldCommand = require('../src/commands/scaffold');
+const syncCommand = require('../src/commands/sync');
 
 // Create CLI program
 const program = new Command();
@@ -78,6 +82,27 @@ program
   .description(mcpSetupCommand.description)
   .action(mcpSetupCommand.handler);
 
+program
+  .command(connectCommand.command)
+  .description(connectCommand.description)
+  .action(connectCommand.handler);
+
+program
+  .command(scaffoldCommand.command)
+  .description(scaffoldCommand.description)
+  .action(scaffoldCommand.handler);
+
+program
+  .command(syncCommand.command)
+  .description(syncCommand.description)
+  .action(syncCommand.handler);
+
+program
+  .command(pagesCommand.command)
+  .description(pagesCommand.description)
+  .argument('[subcommand]', 'sync, list, or detect')
+  .action((subcommand) => pagesCommand.handler([subcommand]));
+
 // Show logo and welcome message if no command provided
 if (process.argv.length === 2) {
   console.log(''); // initial spacing

package/docs/CLI_PAGE_DETECTION_REQUIREMENTS.md

@@ -0,0 +1,519 @@
+# CLI Page Auto-Detection Requirements
+
+## Overview
+
+The CLI needs to auto-detect pages/screens in connected applications and sync them to the L4YERCAK3 backend. This enables the Activity Protocol to track data flow per-page and allows users to configure object bindings for each page.
+
+## Backend API Endpoints (HTTP)
+
+**Base URL**: `https://your-deployment.convex.site/api/v1/activity`
+
+**Authentication**: All endpoints require authentication via one of:
+- CLI session token: `Authorization: Bearer <cli_session_token>`
+- API key: `X-API-Key: <api_key>`
+- OAuth token: `Authorization: Bearer <oauth_token>`
+
+**Required Scopes**:
+- Read operations: `activity:read` or `applications:read`
+- Write operations: `activity:write` or `applications:write`
+
+---
+
+### 1. Bulk Register Pages (Recommended for Auto-Detection)
+
+**POST** `/api/v1/activity/pages/bulk`
+
+```bash
+curl -X POST "https://your-deployment.convex.site/api/v1/activity/pages/bulk" \
+  -H "Authorization: Bearer <cli_session_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "applicationId": "k1234567890abcdef",
+    "pages": [
+      { "path": "/", "name": "Home", "pageType": "static" },
+      { "path": "/dashboard", "name": "Dashboard", "pageType": "static" },
+      { "path": "/dashboard/[id]", "name": "Dashboard Detail", "pageType": "dynamic" },
+      { "path": "/api/users", "name": "API: Users", "pageType": "api_route" }
+    ]
+  }'
+```
+
+**Request Body**:
+```typescript
+{
+  applicationId: string,      // The connected_application object ID
+  pages: Array<{
+    path: string,             // Route path, e.g., "/dashboard", "/checkout/[id]"
+    name: string,             // Display name, e.g., "Dashboard", "Checkout Page"
+    pageType?: string,        // "static", "dynamic", "api_route"
+  }>
+}
+```
+
+**Response** (200 OK):
+```typescript
+{
+  success: true,
+  results: Array<{
+    path: string,
+    pageId: string,           // Object ID for the page
+    created: boolean          // true if new, false if updated
+  }>,
+  total: number,
+  created: number,            // Count of newly created pages
+  updated: number             // Count of updated pages
+}
+```
+
+---
+
+### 2. Register Single Page
+
+**POST** `/api/v1/activity/pages`
+
+```bash
+curl -X POST "https://your-deployment.convex.site/api/v1/activity/pages" \
+  -H "Authorization: Bearer <cli_session_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "applicationId": "k1234567890abcdef",
+    "path": "/checkout/[productId]",
+    "name": "Checkout",
+    "detectionMethod": "cli_auto",
+    "pageType": "dynamic",
+    "objectBindings": [
+      {
+        "objectType": "product",
+        "accessMode": "read",
+        "syncEnabled": true,
+        "syncDirection": "pull"
+      }
+    ]
+  }'
+```
+
+**Request Body**:
+```typescript
+{
+  applicationId: string,
+  path: string,
+  name: string,
+  detectionMethod: "cli_auto" | "manual" | "runtime",
+  pageType?: string,
+  objectBindings?: Array<{
+    objectType: string,
+    accessMode: "read" | "write" | "read_write",
+    boundObjectIds?: string[],
+    syncEnabled: boolean,
+    syncDirection?: "push" | "pull" | "bidirectional"
+  }>
+}
+```
+
+**Response** (201 Created / 200 Updated):
+```typescript
+{
+  success: true,
+  pageId: string,
+  created: boolean
+}
+```
+
+---
+
+### 3. Get Application Pages
+
+**GET** `/api/v1/activity/pages?applicationId=<id>`
+
+```bash
+curl -X GET "https://your-deployment.convex.site/api/v1/activity/pages?applicationId=k1234567890abcdef" \
+  -H "Authorization: Bearer <cli_session_token>"
+```
+
+**Query Parameters**:
+- `applicationId` (required): The connected application ID
+- `status` (optional): Filter by status (e.g., "active", "archived")
+
+**Response** (200 OK):
+```typescript
+{
+  success: true,
+  pages: Array<{
+    id: string,
+    name: string,
+    path: string,
+    detectionMethod: string,
+    pageType: string,
+    objectBindings: Array<{...}>,
+    status: string,
+    createdAt: number,
+    updatedAt: number
+  }>,
+  total: number
+}
+```
+
+---
+
+### 4. Log Activity Events
+
+**POST** `/api/v1/activity/events`
+
+```bash
+curl -X POST "https://your-deployment.convex.site/api/v1/activity/events" \
+  -H "Authorization: Bearer <cli_session_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "applicationId": "k1234567890abcdef",
+    "eventType": "object_created",
+    "severity": "info",
+    "category": "object",
+    "summary": "Contact '\''John Smith'\'' created",
+    "details": {
+      "objectType": "contact",
+      "objectName": "John Smith",
+      "durationMs": 125,
+      "correlationId": "req_abc123"
+    }
+  }'
+```
+
+**Request Body**:
+```typescript
+{
+  applicationId: string,
+  eventType: string,           // "api_request", "object_created", "sync_started", etc.
+  severity: "debug" | "info" | "warning" | "error",
+  category: string,            // "api", "sync", "object", "webhook", "transform"
+  summary: string,             // Human-readable: "Contact 'John Smith' created"
+  pageId?: string,             // Optional: link event to a specific page
+  details?: {
+    requestId?: string,
+    method?: string,           // HTTP method
+    endpoint?: string,         // API endpoint
+    statusCode?: number,
+    objectType?: string,
+    objectId?: string,
+    objectName?: string,
+    inputSummary?: string,
+    outputSummary?: string,
+    syncDirection?: string,
+    recordsAffected?: number,
+    durationMs?: number,
+    errorCode?: string,
+    errorMessage?: string,
+    stackTrace?: string,
+    sourceFile?: string,
+    sourceLine?: number,
+    correlationId?: string,    // Group related events
+  }
+}
+```
+
+**Response** (201 Created):
+```typescript
+{
+  success: true,
+  eventId: string,
+  timestamp: number
+}
+```
+
+---
+
+### 5. Get Activity Events
+
+**GET** `/api/v1/activity/events?applicationId=<id>`
+
+```bash
+curl -X GET "https://your-deployment.convex.site/api/v1/activity/events?applicationId=k1234567890abcdef&severity=error&limit=50" \
+  -H "Authorization: Bearer <cli_session_token>"
+```
+
+**Query Parameters**:
+- `applicationId` (required): The connected application ID
+- `severity` (optional): Filter by severity (debug, info, warning, error)
+- `category` (optional): Filter by category (api, sync, object, webhook, transform)
+- `debugMode` (optional): Include debug-level events (true/false)
+- `limit` (optional): Max results, default 50, max 200
+
+**Response** (200 OK):
+```typescript
+{
+  success: true,
+  events: Array<{
+    _id: string,
+    eventType: string,
+    severity: string,
+    category: string,
+    summary: string,
+    timestamp: number,
+    details?: {...}
+  }>,
+  hasMore: boolean,
+  nextCursor: string | null
+}
+```
+
+---
+
+### 6. Get Activity Statistics
+
+**GET** `/api/v1/activity/stats?applicationId=<id>`
+
+```bash
+curl -X GET "https://your-deployment.convex.site/api/v1/activity/stats?applicationId=k1234567890abcdef&timeRange=24h" \
+  -H "Authorization: Bearer <cli_session_token>"
+```
+
+**Query Parameters**:
+- `applicationId` (required): The connected application ID
+- `timeRange` (optional): "1h", "24h", or "7d" (default: "24h")
+
+**Response** (200 OK):
+```typescript
+{
+  success: true,
+  stats: {
+    total: number,
+    bySeverity: { debug: number, info: number, warning: number, error: number },
+    byCategory: { [category: string]: number },
+    recentErrors: Array<{ summary: string, timestamp: number, errorMessage?: string }>
+  }
+}
+```
+
+---
+
+### 7. Activity Settings
+
+**GET** `/api/v1/activity/settings?applicationId=<id>`
+
+**PATCH** `/api/v1/activity/settings`
+
+```bash
+# Update settings
+curl -X PATCH "https://your-deployment.convex.site/api/v1/activity/settings" \
+  -H "Authorization: Bearer <cli_session_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "applicationId": "k1234567890abcdef",
+    "enabled": true,
+    "debugModeDefault": false,
+    "retentionDays": 7,
+    "alertsEnabled": true
+  }'
+```
+
+---
+
+## CLI Implementation Requirements
+
+### Phase 1: Page Detection
+
+The CLI should scan the connected application and detect pages based on framework:
+
+#### Next.js (App Router)
+```
+app/
+├── page.tsx           → "/"
+├── about/
+│   └── page.tsx       → "/about"
+├── dashboard/
+│   ├── page.tsx       → "/dashboard"
+│   └── [id]/
+│       └── page.tsx   → "/dashboard/[id]"
+└── api/
+    └── users/
+        └── route.ts   → "/api/users" (api_route)
+```
+
+#### Next.js (Pages Router)
+```
+pages/
+├── index.tsx          → "/"
+├── about.tsx          → "/about"
+├── dashboard/
+│   ├── index.tsx      → "/dashboard"
+│   └── [id].tsx       → "/dashboard/[id]"
+└── api/
+    └── users.ts       → "/api/users" (api_route)
+```
+
+#### Remix
+```
+app/routes/
+├── _index.tsx         → "/"
+├── about.tsx          → "/about"
+├── dashboard._index.tsx → "/dashboard"
+└── dashboard.$id.tsx  → "/dashboard/$id"
+```
+
+#### Astro
+```
+src/pages/
+├── index.astro        → "/"
+├── about.astro        → "/about"
+└── blog/
+    └── [slug].astro   → "/blog/[slug]"
+```
+
+### Phase 2: Page Name Generation
+
+Convert paths to human-readable names:
+- `/` → "Home"
+- `/about` → "About"
+- `/dashboard` → "Dashboard"
+- `/dashboard/[id]` → "Dashboard Detail"
+- `/api/users` → "API: Users"
+- `/checkout/[productId]` → "Checkout"
+
+### Phase 3: Page Type Detection
+
+- `page.tsx`, `index.tsx`, `.astro` → "static" or "dynamic"
+- `route.ts`, `api/*.ts` → "api_route"
+- Files with `[param]` → "dynamic"
+
+### Phase 4: Sync Command
+
+```bash
+# Detect and sync pages
+l4yercak3 pages sync
+
+# Output:
+# Scanning for pages...
+# Found 12 pages in Next.js App Router
+#
+# Syncing to L4YERCAK3...
+#   ✓ / (Home) - created
+#   ✓ /about (About) - created
+#   ✓ /dashboard (Dashboard) - created
+#   ✓ /dashboard/[id] (Dashboard Detail) - created
+#   ✓ /api/users (API: Users) - created
+#   ...
+#
+# Done! 12 pages synced.
+```
+
+### Phase 5: Activity Logging (Optional Enhancement)
+
+The CLI could generate code to automatically log activity events:
+
+```typescript
+// Generated: lib/l4yercak3-activity.ts
+const L4YERCAK3_API_URL = process.env.L4YERCAK3_API_URL;
+const L4YERCAK3_API_KEY = process.env.L4YERCAK3_API_KEY;
+const L4YERCAK3_APP_ID = process.env.L4YERCAK3_APPLICATION_ID;
+
+export async function logActivity(context: {
+  eventType: string;
+  category: string;
+  summary: string;
+  severity?: 'debug' | 'info' | 'warning' | 'error';
+  details?: Record<string, unknown>;
+}) {
+  try {
+    await fetch(`${L4YERCAK3_API_URL}/api/v1/activity/events`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': L4YERCAK3_API_KEY!,
+      },
+      body: JSON.stringify({
+        applicationId: L4YERCAK3_APP_ID,
+        eventType: context.eventType,
+        severity: context.severity || 'info',
+        category: context.category,
+        summary: context.summary,
+        details: context.details,
+      }),
+    });
+  } catch (error) {
+    // Fire-and-forget logging, don't block the application
+    console.error('[L4YERCAK3] Failed to log activity:', error);
+  }
+}
+
+export async function withActivityLogging<T>(
+  operation: () => Promise<T>,
+  context: {
+    eventType: string;
+    category: string;
+    summary: string;
+    objectType?: string;
+  }
+): Promise<T> {
+  const correlationId = crypto.randomUUID();
+  const startTime = Date.now();
+
+  try {
+    const result = await operation();
+    logActivity({
+      ...context,
+      severity: 'info',
+      details: {
+        correlationId,
+        durationMs: Date.now() - startTime,
+        objectType: context.objectType,
+      }
+    });
+    return result;
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logActivity({
+      ...context,
+      severity: 'error',
+      details: {
+        correlationId,
+        durationMs: Date.now() - startTime,
+        errorMessage,
+        objectType: context.objectType,
+      }
+    });
+    throw error;
+  }
+}
+```
+
+## Data Flow
+
+```
+┌─────────────────┐     ┌──────────────────────────────┐     ┌─────────────────┐
+│   CLI Tool      │────▶│     HTTP API Endpoints       │────▶│   Objects DB    │
+│                 │     │                              │     │                 │
+│ • Scan pages    │     │ POST /api/v1/activity/pages/bulk   │ type=           │
+│ • Detect types  │     │ POST /api/v1/activity/pages  │     │ application_page│
+│ • Generate names│     │ POST /api/v1/activity/events │     │                 │
+└─────────────────┘     └──────────────────────────────┘     └─────────────────┘
+                                        │
+                                        ▼
+                                ┌──────────────────┐
+                                │  Activity Events │
+                                │  (Rolling Window)│
+                                │  7-day default   │
+                                └──────────────────┘
+```
+
+## Testing
+
+1. Create a test Next.js app with various page structures
+2. Run `l4yercak3 pages sync`
+3. Verify pages appear in L4YERCAK3 Web Publishing → Applications → [App] → Pages & Bindings
+4. Test that updates (re-running sync) update existing pages rather than creating duplicates
+
+## Open Questions for CLI Team
+
+1. **Incremental vs Full Sync**: Should we detect deleted pages and mark them as archived?
+2. **Watch Mode**: Should we support `l4yercak3 pages watch` for real-time detection?
+3. **Config File**: Should page detection be configurable via `.l4yercak3/pages.json`?
+4. **Exclusions**: How do we handle pages that shouldn't be tracked (e.g., internal admin routes)?
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| `INVALID_SESSION` | Authentication failed - token expired or invalid |
+| `INSUFFICIENT_PERMISSIONS` | Missing required scope |
+| `VALIDATION_ERROR` | Missing or invalid request parameters |
+| `NOT_FOUND` | Resource not found |
+| `INTERNAL_ERROR` | Server error |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@l4yercak3/cli",
-  "version": "1.2.21",
+  "version": "1.3.0",
   "description": "Icing on the L4yercak3 - The sweet finishing touch for your Layer Cake integration",
   "main": "src/index.js",
   "bin": {