@descix/cli 1.0.0

package/agent-assets/reference/workspace-config.md

@@ -0,0 +1,415 @@
+# Workspace Configuration Guide
+
+**Status:** Implemented  
+**Version:** 2.0  
+**Last Updated:** January 2026
+
+This document describes how DeSciX workspaces are configured, including workspace modes, configuration files, and sync modes.
+
+---
+
+## 1. Workspace Modes
+
+The DeSciX CLI supports three workspace modes, determined by the structure of `workspace.json`.
+
+### 1.1 Single App Mode
+
+**Use Case:** Dedicated repository for a single app.
+
+```json
+{
+  "communities": {
+    "descix": {
+      "apps": {
+        "agent": {
+          "localPath": ".",
+          "sync_mode": "git"
+        }
+      }
+    }
+  }
+}
+```
+
+**Characteristics:**
+- Workspace root IS the app folder
+- No community subfolder created
+- Simplest structure for focused development
+
+**Folder Structure:**
+```
+[workspace-root]/
+├── .descix/
+│   └── workspace.json
+├── assets/
+├── kb/
+├── site/
+└── microservice/
+```
+
+### 1.2 Single Community Mode
+
+**Use Case:** Multiple apps within one community.
+
+```json
+{
+  "communities": {
+    "descix": {
+      "apps": {
+        "agent": { "localPath": "agent", "sync_mode": "git" },
+        "docs": { "localPath": "docs", "sync_mode": "git" }
+      }
+    }
+  }
+}
+```
+
+**Folder Structure:**
+```
+[workspace-root]/
+├── .descix/
+│   └── workspace.json
+├── agent/
+│   ├── assets/
+│   └── kb/
+└── docs/
+    ├── assets/
+    └── kb/
+```
+
+### 1.3 Multi-Community Mode
+
+**Use Case:** Working across multiple communities.
+
+```json
+{
+  "communities": {
+    "descix": {
+      "apps": {
+        "agent": { "localPath": "descix/agent", "sync_mode": "git" }
+      }
+    },
+    "myorg": {
+      "apps": {
+        "assistant": { "localPath": "myorg/assistant", "sync_mode": "git" }
+      }
+    }
+  }
+}
+```
+
+**Folder Structure:**
+```
+[workspace-root]/
+├── .descix/
+│   └── workspace.json
+├── descix/
+│   └── agent/
+│       ├── assets/
+│       └── kb/
+└── myorg/
+    └── assistant/
+        ├── assets/
+        └── kb/
+```
+
+---
+
+## 2. Configuration Files
+
+### 2.1 `.descix/workspace.json`
+
+**Location:** `[workspace-root]/.descix/workspace.json`  
+**Purpose:** Workspace-level configuration
+
+**Schema:**
+```json
+{
+  "communities": {
+    "[community_id]": {
+      "apps": {
+        "[app_id]": {
+          "localPath": "path/to/app",
+          "sync_mode": "git"
+        }
+      }
+    }
+  },
+  "driveConfig": {
+    "base_folder_id": "1ABC..."
+  },
+  "environment": "development",
+  "apiUrl": "https://localhost:4000"
+}
+```
+
+**Fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `communities` | Yes | Map of community IDs to their configuration |
+| `communities.[id].apps` | Yes | Map of app IDs to their configuration |
+| `communities.[id].apps.[id].localPath` | Yes | Relative path from workspace root |
+| `communities.[id].apps.[id].kbId` | No | Default KB folder name (default: `"General"`) |
+| `communities.[id].apps.[id].absolutePath` | No | Absolute path to app (auto-set during init) |
+| `communities.[id].apps.[id].site.port` | No | Local dev server port for CodeSite |
+| `communities.[id].apps.[id].service.port` | No | Local dev server port for Microservice |
+| `driveConfig.base_folder_id` | Yes | User's Drive base folder ID |
+| `environment` | No | `"development"` or `"production"` |
+| `apiUrl` | No | Override API URL (dev mode) |
+
+### 2.2 `.descix/wallet.json`
+
+**Location:** `[workspace-root]/.descix/wallet.json`  
+**Purpose:** Authentication credentials (Git-ignored)
+
+**Schema:**
+```json
+{
+  "walletAddress": "0x...",
+  "signature": "...",
+  "tokenSymbol": "DAITA",
+  "communityId": "descix",
+  "userId": "user_...",
+  "email": "user@example.com",
+  "sessionToken": "...",
+  "expiresAt": "2026-01-28T00:00:00.000Z"
+}
+```
+
+**Security:** This file is automatically added to `.gitignore` during setup.
+
+---
+
+## 3. Sync Modes
+
+DeSciX supports two sync modes, determined by how the app is managed:
+
+### 3.1 Git Mode (CLI Developers)
+
+**Source of Truth:** Local Git repository  
+**Versioning:** Git  
+**Tool:** CLI (`descix kb *` commands)
+
+**Workflow:**
+1. User creates/edits documents in Google Drive
+2. User runs `descix kb pull` to get text-converted content
+3. User edits text files locally (Git version control)
+4. User runs `descix kb chunk` to generate chunks
+5. User runs `descix kb sync` to push chunks to Pinecone
+6. User commits changes to Git
+
+**When to Use:**
+- Developers with local development environment
+- Need for Git version control
+- Offline development capability
+- Code review workflows
+- CodeSite or Microservice development
+
+### 3.2 Drive Mode (PWA Users)
+
+**Source of Truth:** Google Drive  
+**Versioning:** GCS/Firestore  
+**Tool:** PWA only (no CLI)
+
+**Workflow:**
+1. User edits files in Drive or PWA
+2. Backend automatically syncs to GCS/Pinecone
+3. No local CLI involvement
+
+**When to Use:**
+- Non-technical users
+- Browser-based editing
+- Real-time collaboration
+- No local tooling required
+- Knowledge-base-only apps (no CodeSite or Microservice)
+
+### 3.3 Mode Determination
+
+**Important:** The CLI only supports git-mode operations. If you're using the CLI, you're in git-mode.
+
+| Tool | Mode | Configuration |
+|------|------|---------------|
+| CLI | Git mode only | `workspace.json` |
+| PWA | Drive mode | Automatic (backend handles) |
+
+There is no CLI command to switch modes - the mode is determined by which tool you use.
+
+---
+
+## 4. Drive Configuration
+
+### 4.1 Base Folder ID
+
+The `base_folder_id` is the root of all DeSciX content in the user's Drive.
+
+**Structure in Drive:**
+```
+[User's Base Folder]/
+├── [community_id]/
+│   ├── community_assets/
+│   └── [app_id]/
+│       ├── assets/
+│       ├── kb/
+│       │   └── General/
+│       ├── site/
+│       └── microservice/
+└── [other_community]/
+```
+
+**Folder Navigation:**
+```javascript
+// Template-based navigation
+const kbPath = `${communityId}/${appId}/kb/${kbId}`;
+const folderId = await findFolderByPath(baseFolderId, kbPath);
+```
+
+### 4.2 Template-Based Navigation
+
+The SDK navigates Drive using predictable template paths:
+
+| Content | Drive Path |
+|---------|------------|
+| App folder | `{community}/{app}/` |
+| KB folder | `{community}/{app}/kb/{kb_name}/` |
+| Assets | `{community}/{app}/assets/` |
+| Site | `{community}/{app}/site/` |
+
+---
+
+## 5. ADC Authentication
+
+### Requirements
+
+Google Cloud ADC (Application Default Credentials) is required for Drive access.
+
+**Setup:**
+```bash
+gcloud auth application-default login \
+  --scopes=https://www.googleapis.com/auth/drive.file,https://www.googleapis.com/auth/drive
+```
+
+### Verification
+
+The CLI verifies ADC before operations:
+
+```javascript
+// google-storage-adc.js
+async function verifyDriveAuth() {
+  const auth = new google.auth.GoogleAuth({
+    scopes: ['https://www.googleapis.com/auth/drive']
+  });
+  const drive = google.drive({ version: 'v3', auth });
+  const response = await drive.about.get({ fields: 'user' });
+  return response.data.user;
+}
+```
+
+### Error Messages
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Could not load default credentials" | ADC not configured | Run `gcloud auth application-default login` |
+| "Drive authentication failed" | Scopes missing | Re-run with Drive scopes |
+| "base_folder_id missing" | Not setup | Run `descix setup` |
+
+---
+
+## 6. Workspace Detection
+
+### Algorithm
+
+```javascript
+function detectWorkspaceMode(workspaceConfig) {
+  const communities = Object.keys(workspaceConfig.communities || {});
+  
+  if (communities.length === 0) {
+    throw new Error('No communities configured');
+  }
+  
+  if (communities.length === 1) {
+    const apps = Object.keys(workspaceConfig.communities[communities[0]].apps);
+    if (apps.length === 1) {
+      const app = workspaceConfig.communities[communities[0]].apps[apps[0]];
+      if (app.localPath === '.' || app.localPath === '') {
+        return 'single_app';
+      }
+    }
+    return 'single_community';
+  }
+  
+  return 'multi_community';
+}
+```
+
+### Mode-Specific Behavior
+
+| Mode | Community Folder | App Folder | Context Inference |
+|------|-----------------|------------|-------------------|
+| single_app | Workspace root | Workspace root | Full (community + app) |
+| single_community | Workspace root | `./[app]/` | Community only |
+| multi_community | `./[community]/` | `./[community]/[app]/` | None |
+
+---
+
+## 7. CLI Context Resolution
+
+The CLI auto-detects app context from the current working directory:
+
+```javascript
+// WorkspaceConfig.detectContext() matches cwd against registered app paths
+detectContext(startDir = process.cwd()) {
+  const cwd = path.resolve(startDir);
+  for (const [commId, comm] of Object.entries(this.communities || {})) {
+    for (const [appId, app] of Object.entries(comm.apps || {})) {
+      if (app.absolutePath && cwd.startsWith(app.absolutePath)) {
+        return { communityId: commId, appId, kbId: app.kbId || 'General' };
+      }
+    }
+  }
+  return null;
+}
+
+// resolveContextWithOptions() combines CLI flags with autodiscovery
+resolveContextWithOptions(options = {}) {
+  // 1. Try explicit flags first
+  if (options.community && options.app) {
+    return { communityId: options.community, appId: options.app, ... };
+  }
+  
+  // 2. Fall back to autodiscovery from cwd
+  const detected = this.detectContext();
+  if (detected) {
+    return {
+      communityId: options.community || detected.communityId,
+      appId: options.app || detected.appId,
+      kbId: options.kb || detected.kbId
+    };
+  }
+  
+  return null;
+}
+```
+
+**Usage Pattern:**
+```bash
+# From within an app directory - auto-detects community/app
+cd descix/appsdk
+descix kb build           # Works without -c/-a flags
+
+# From workspace root - requires flags
+cd /workspace
+descix kb build -c descix -a appsdk
+```
+
+---
+
+## 8. File References
+
+| Component | Path | Description |
+|-----------|------|-------------|
+| WorkspaceConfig | `DeSciX_Core/descix-cli/lib/workspace-config.js` | Sole configuration class for CLI |
+| GlobalConfig | `DeSciX_Core/descix-cli/lib/global-config.js` | User-level settings (~/.descix) |
+| Workspace Utils | `DeSciX_Core/descix-cli/lib/workspace-utils.js` | Helper utilities |
+| Setup Command | `DeSciX_Core/descix-cli/lib/commands/setup.js` | Initial workspace setup |
+| Config Commands | `DeSciX_Core/descix-cli/lib/commands/config.js` | Configuration management |

package/agent-assets/rules/descix_mcp.template.mdc

@@ -0,0 +1,243 @@
+---
+alwaysApply: true
+---
+
+# DeSciX SDK Agent Instructions
+
+You have SDK agent assets available locally at `{{SDK_ASSETS_PATH}}/`.
+
+## Key Architecture Concepts
+
+### Configuration: workspace.json is the Config File
+
+- **`workspace.json`** at `.descix/workspace.json` is the configuration file
+- **Context auto-detection** - CLI commands detect community/app from current working directory
+
+### CLI = Git Mode ONLY
+
+- The CLI only supports **git-mode** operations (local processing with Git version control)
+- **Drive-mode** apps are managed via PWA only (server-side processing)
+- All content starts on Drive - developers pull it locally, then manage with Git
+
+### App Folder Structure (Convention-Based)
+
+```
+my-app/
+├── assets/          # App metadata (icon.png, app_description.md, system_instructions.md)
+├── kb/              # Knowledge base
+│   ├── staging/     # Files to push TO Drive
+│   ├── General/     # Text files pulled FROM Drive
+│   └── chunks/      # Generated JSON chunks (Git-tracked)
+├── site/            # CodeSite static files (optional)
+└── microservice/    # Backend service code (optional)
+```
+
+## Post-Setup Initialization
+
+**IMPORTANT**: Check `.descix/workspace.json` for `_needsAgentSetup: true`.
+
+When this flag is set, the user has just completed `descix setup` and needs your help configuring their workspace:
+
+1. **Greet the user** and confirm MCP is working: "I can see your DeSciX setup is complete. Let me help you configure your workspace."
+2. **Show their entitlements** from the cached JSON below (communities and apps they own)
+3. **Ask**: "Which app would you like to configure first?" or "Would you like me to scan your folders and suggest mappings?"
+4. **For each app folder**:
+   - Analyze the folder structure using heuristics from `{{SDK_ASSETS_PATH}}/instructions/folder-analysis.md`
+   - Recommend a packaging type using the decision tree from `{{SDK_ASSETS_PATH}}/instructions/packaging-types.md`
+   - Register the app in `workspace.json` with its localPath and absolutePath
+5. **When done**, set `_needsAgentSetup: false` in workspace.json
+
+If user asks "Help me configure my workspace" or similar, follow this flow.
+
+## Entitlements-First Principle
+
+**CRITICAL**: Users purchase apps/communities in the PWA first. Your role is to help configure local folders for apps they already own.
+
+### On First Interaction
+
+1. Check `.descix/workspace.json` for existing configuration
+2. If `_needsAgentSetup: true`, follow the Post-Setup Initialization flow above
+3. If unconfigured, read `{{SDK_ASSETS_PATH}}/instructions/onboarding-flow.md`
+4. For fresh entitlements: `execute_remote_command({ command: "fetch_my_purchases" })`
+5. Guide user through folder-to-app mapping in `workspace.json`
+
+## Local Asset References
+
+For quick decisions, read these local files (no network required):
+
+| File | Purpose |
+|------|---------|
+| `{{SDK_ASSETS_PATH}}/instructions/packaging-types.md` | App type taxonomy and decision tree |
+| `{{SDK_ASSETS_PATH}}/instructions/folder-analysis.md` | Detect project type from files |
+| `{{SDK_ASSETS_PATH}}/instructions/conversation-guides.md` | Dialogue templates |
+| `{{SDK_ASSETS_PATH}}/instructions/onboarding-flow.md` | Full onboarding workflow |
+
+## Template Usage
+
+When scaffolding apps, use templates from `{{SDK_ASSETS_PATH}}/templates/`:
+
+| Packaging Type | Templates Available |
+|----------------|---------------------|
+| `knowledge-only` | Assets folder only |
+| `static-site` | Site folder scaffold |
+| `microservice` | `manifest.json.template`, `SERVICE_README.template` |
+| `dynamic-site` | Site + microservice scaffolds |
+
+Replace `{{PLACEHOLDER}}` values with actual data from user input.
+
+## User Entitlements (Cached at Setup)
+
+```json
+{{ENTITLEMENTS_JSON}}
+```
+
+**Primary Community**: {{PRIMARY_COMMUNITY}}
+
+Use this cached data for quick checks. For fresh data, call `fetch_my_purchases`.
+
+## Tiered Access Pattern
+
+Use the appropriate tier based on what you need:
+
+### Tier 1: Local Files (Instant)
+```javascript
+// Read instructions directly
+Read("{{SDK_ASSETS_PATH}}/instructions/packaging-types.md")
+```
+**Use for**: Quick lookups, decision trees, templates
+
+### Tier 2: tell_me_how (Semantic Discovery)
+```javascript
+tell_me_how({ 
+  question: "How do I scaffold a microservice?",
+  scope: "entitlements"
+})
+```
+**Use for**: Finding the right tool for a task
+
+### Tier 3: chat_with_kb (Rich Context)
+```javascript
+chat_with_kb({
+  communityId: "descix",
+  appId: "docs",
+  kbId: "sdk",
+  message: "Explain the deployment workflow for dynamic sites"
+})
+```
+**Use for**: Complex questions requiring reasoning
+
+### Tier 4: execute_remote_command (Action)
+```javascript
+execute_remote_command({
+  command: "scaffold_app_type",
+  params: { type: "microservice", app_id: "myapp", ... }
+})
+```
+**Use for**: Actually creating/modifying things
+
+## Tool Discovery
+
+Use `tell_me_how` to discover platform capabilities:
+
+```javascript
+// Discover tools for a task
+tell_me_how({ question: "How do I deploy my app?", scope: "entitlements" })
+
+// Then execute the recommended command
+execute_remote_command({ command: "discovered_command", params: {...} })
+```
+
+**Scope Options**:
+- `project`: Only tools for apps in workspace.json
+- `entitlements`: Tools for all apps user owns (default)
+- `discovery`: All platform tools (may show purchasable)
+
+## App Configuration Workflow
+
+When user wants to configure a folder:
+
+1. **Analyze folder** using heuristics from `folder-analysis.md`
+2. **Recommend packaging type** using decision tree from `packaging-types.md`
+3. **Present options** using dialogue from `conversation-guides.md`
+4. **Register app** in `workspace.json` with localPath and absolutePath
+5. **Guide CLI commands** based on packaging type
+
+## Primary CLI Commands
+
+Guide users to these git-mode commands:
+
+### Knowledge Base Commands
+| Command | Purpose |
+|---------|---------|
+| `descix kb pull` | Pull text-converted content from Drive |
+| `descix kb push` | Push staging files to Drive |
+| `descix kb chunk` | Generate JSON chunks from text files |
+| `descix kb sync` | Push chunks to Pinecone |
+| `descix kb build` | Full pipeline: pull → chunk → sync |
+| `descix kb status` | Show local vs Pinecone sync status |
+
+### Site Commands
+| Command | Purpose |
+|---------|---------|
+| `descix site init` | Copy site scaffold to app |
+| `descix site upload` | Deploy CodeSite to GCS |
+| `descix site servelocal [port]` | Register local dev server port |
+| `descix site list` | List deployed site files |
+| `descix site status` | Get deployment status |
+
+### Microservice Commands
+| Command | Purpose |
+|---------|---------|
+| `descix microservice init` | Copy microservice scaffold to app |
+| `descix microservice register` | Register microservice with gateway |
+| `descix microservice vectorize` | Vectorize README for discovery |
+| `descix microservice list` | List registered microservices |
+| `descix microservice health <name>` | Check microservice health |
+| `descix microservice reload` | Reload manifests (admin) |
+
+**Context Auto-Detection**: When run from within an app directory, these commands auto-detect community/app from `workspace.json`. Otherwise use `-c` and `-a` flags.
+
+## SDK Tools Available (Remote)
+
+These tools are auto-registered and discoverable via `tell_me_how`:
+
+| Tool | Purpose |
+|------|---------|
+| `scaffold_app_type` | Create boilerplate for chosen packaging type |
+| `analyze_folder_structure` | Detect project type from folder contents |
+| `get_app_sync_status` | Check what's synced (KB, site, service) |
+| `fetch_my_purchases` | Get user's entitlements |
+| `register_service` | Register microservice with gateway |
+| `vectorize_service_readme` | Enable tell_me_how discovery |
+
+## Key Principles
+
+1. **Never assume** - Always ask before creating mappings
+2. **Entitlements are truth** - Can't configure apps user doesn't own
+3. **Local first** - Read local assets before making network calls
+4. **Guide, don't dictate** - Present options, let user choose
+5. **workspace.json is truth** - All configuration goes here
+
+## Error Recovery
+
+If commands fail:
+1. Check authentication: Is `wallet.json` valid?
+2. Check entitlements: Does user own the app?
+3. Check configuration: Is app registered in `workspace.json`?
+4. Check location: Are you in the app directory or using `-c/-a` flags?
+5. Use `tell_me_how` to find alternative approaches
+
+### Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Workspace not configured" | No workspace.json | Run `descix init` |
+| "Could not determine app context" | Not in app directory | `cd` to app or use `-c/-a` flags |
+| "ADC not configured" | Missing Google auth | Run `gcloud auth application-default login` |
+| "App not found in workspace" | App not registered | Run `descix setup` or add to workspace.json |
+
+---
+
+*Generated by DeSciX SDK Setup*
+*SDK Version: {{SDK_VERSION}}*
+*Workspace: {{WORKSPACE_PATH}}*