@descix/cli 1.0.1 → 1.0.3

package/lib/workspace-config.js

@@ -1,5 +1,35 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
+import { ENV_ORIGINS } from '@descix/app-sdk/dev';
+import { resolveOrigin } from './origin.js';
+
+/**
+ * ONE OWNER for turning a workspace-relative localPath into an absolute path.
+ *
+ * This was resolved four different ways across this file and its callers — three with
+ * path.join and one with path.resolve — and the two treatments DISAGREE on an absolute
+ * localPath. path.join('/ws', '/ws/app') yields '/ws/ws/app' (the "doubling"); path.resolve
+ * yields '/ws/app'. Concretely, getAppByAppId() and detectContext() both derive from the same
+ * _appIdToConfig entry, so an absolute localPath made detectContext match a directory that
+ * getAppByAppId reported as a doubled path that does not exist.
+ *
+ * FAIL LOUD rather than quietly absorbing it. An absolute localPath in workspace.json is a
+ * PORTABILITY defect, not a valid configuration: workspace.json is shared across checkouts and
+ * machines, and a machine-specific absolute path cannot survive either. Silently resolving it
+ * would make the doubling disappear while leaving the unshareable config in place. Name the
+ * offending entry and the config verb that fixes it.
+ */
+export function resolveWorkspacePath(workspaceRoot, localPath, label = 'app') {
+    if (!localPath) return null;
+    if (path.isAbsolute(localPath)) {
+        throw new Error(
+            `workspace.json: localPath for '${label}' is an absolute path (${localPath}). ` +
+            `localPath must be relative to the workspace root so the workspace is portable across ` +
+            `checkouts and machines. Fix it with the config verb — never by hand-editing workspace.json.`
+        );
+    }
+    return path.resolve(workspaceRoot, localPath);
+}
 
 /**
  * WorkspaceConfig - Manages workspace-specific configuration
@@ -18,16 +48,11 @@ export class WorkspaceConfig {
     this.version = config.version || '1.0';
     this.type = config.type || 'workspace'; // 'workspace', 'community', or 'app'
     
-    // Legacy fields (v1 compatibility)
-    this.primaryCommunity = config.primaryCommunity;
-    this.directoryMappings = config.directoryMappings || {};
-    this.additionalContexts = config.additionalContexts || [];
+    // Legacy fields (kept for save() PWA response conversion compatibility)
     this.defaultContext = config.defaultContext;
     this.apiUrl = config.apiUrl;
     this.environment = config.environment;
-    
-    // V2 community tracking (root workspace)
-    this.communities = config.communities || {};
+    this.directoryMappings = config.directoryMappings || {};
 
     // V2.1 Product tracking (Unified Registry)
     this.products = config.products || {};
@@ -89,7 +114,7 @@ export class WorkspaceConfig {
     // env.platform + env.products (primary for manually crafted workspace)
     const fromEnv = this._appIdToConfig[appId];
     if (fromEnv) {
-      const absPath = path.join(this.workspaceRoot, fromEnv.localPath);
+      const absPath = resolveWorkspacePath(this.workspaceRoot, fromEnv.localPath, appId);
       return {
         localPath: fromEnv.localPath,
         absolutePath: absPath,
@@ -98,33 +123,29 @@ export class WorkspaceConfig {
       };
     }
 
-    // Legacy: products object
-    const product = this.products[appId];
-    if (product?.localPath) {
-      const absPath = product.absolutePath || path.join(this.workspaceRoot, product.localPath);
-      return {
-        localPath: product.localPath,
-        absolutePath: absPath,
-        communityId: product.context?.community || null,
-        kbId: product.kbId || 'General'
-      };
-    }
+    return null;
+  }
 
-    // Legacy: communities.apps
-    for (const [, comm] of Object.entries(this.communities || {})) {
-      const app = comm?.apps?.[appId];
-      if (app?.localPath) {
-        const absPath = app.absolutePath || path.join(this.workspaceRoot, app.localPath);
-        return {
-          localPath: app.localPath,
-          absolutePath: absPath,
-          communityId: null, // Will be derived from Products on backend
-          kbId: app.kbId || 'General'
-        };
-      }
-    }
+  /**
+   * Get the absolute path to an app's site/ directory
+   * @param {string} appId - App identifier
+   * @returns {string|null} Absolute path to site/ or null if app not mapped
+   */
+  getSitePath(appId) {
+    const appConfig = this.getAppByAppId(appId);
+    if (!appConfig?.absolutePath) return null;
+    return path.join(appConfig.absolutePath, 'site');
+  }
 
-    return null;
+  /**
+   * Get the absolute path to an app's microservice/ directory
+   * @param {string} appId - App identifier
+   * @returns {string|null} Absolute path to microservice/ or null if app not mapped
+   */
+  getMicroservicePath(appId) {
+    const appConfig = this.getAppByAppId(appId);
+    if (!appConfig?.absolutePath) return null;
+    return path.join(appConfig.absolutePath, 'microservice');
   }
   
   /**
@@ -178,24 +199,30 @@ export class WorkspaceConfig {
    */
   static async load(startDir = process.cwd()) {
     // First, find workspace root by searching upward
-    // If startDir is provided, use it. If not, use process.cwd()
     const workspaceRoot = await WorkspaceConfig.findWorkspaceRoot(startDir);
     if (!workspaceRoot) {
-      // Fallback: Check if we are running from within a package in the repo
-      // and try to find the root by looking for .descix in parent directories
-      // This is redundant with findWorkspaceRoot but let's be explicit about the error
       throw new Error(
         'Workspace not configured.\n' +
         'Run "npx descix init" first to initialize your workspace.'
       );
     }
-    
+
     const configPath = path.join(workspaceRoot, '.descix', 'workspace.json');
     try {
       const data = await fs.readFile(configPath, 'utf-8');
       const parsed = JSON.parse(data);
+
+      // v1 format hard-error: has communities block but no env block
+      if (parsed.communities && !parsed.env) {
+        throw new Error(
+          'v1 workspace format is not supported. Migrate to v2.1.\n' +
+          'Delete .descix/workspace.json and re-run "descix app init" to create a v2.1 workspace.'
+        );
+      }
+
       return new WorkspaceConfig(parsed, workspaceRoot);
     } catch (error) {
+      if (error.message.includes('v1 workspace format')) throw error;
       throw new Error(
         'Workspace not configured.\n' +
         'Run "npx descix init" first to initialize your workspace.'
@@ -220,9 +247,7 @@ export class WorkspaceConfig {
   
   /**
    * Save workspace configuration in v2.1 format.
-   * Always writes env.platform / env.products structure — never v1 communities.
-   * If loaded from a v1 communities format (e.g. PWA device_check_status response),
-   * auto-converts communities.apps → env.products on write.
+   * Always writes env.platform / env.products structure.
    * @param {string} [workspaceRoot] - Workspace root directory (uses stored root if not provided)
    * @returns {Promise<string>} Path to saved config
    */
@@ -238,25 +263,8 @@ export class WorkspaceConfig {
 
     this.workspaceRoot = root;
 
-    // Build env block for v2.1 output.
-    // Native v2.1 path: this.env is already populated from env.platform/env.products.
-    // Legacy conversion path: this.env is absent but communities are populated (v1 PWA response).
-    let envBlock = (this.env && Object.keys(this.env).length > 0) ? this.env : null;
-
-    if (!envBlock && Object.keys(this.communities || {}).length > 0) {
-      const products = [];
-      for (const [, community] of Object.entries(this.communities)) {
-        for (const [appId, app] of Object.entries(community.apps || {})) {
-          if (app.localPath) {
-            products.push({ appId, localPath: app.localPath, kbId: app.kbId || 'General' });
-          }
-        }
-      }
-      envBlock = { products };
-      // Update in-memory state so callers see a consistent env after save
-      this.env = envBlock;
-      this._appIdToConfig = this._buildAppIdMap({ env: this.env, workspaceRoot: this.workspaceRoot });
-    }
+    // Build env block for v2.1 output
+    const envBlock = (this.env && Object.keys(this.env).length > 0) ? this.env : null;
 
     const configData = {
       version: '2.1',
@@ -279,46 +287,17 @@ export class WorkspaceConfig {
    */
   computeAbsolutePaths(workspaceRoot) {
     const absWorkspaceRoot = path.resolve(workspaceRoot);
-    
-    for (const [communityId, community] of Object.entries(this.communities || {})) {
-      // Compute community absolute path
-      if (community.localPath) {
-        community.absolutePath = path.join(absWorkspaceRoot, community.localPath);
-      }
-      
-      // Compute app absolute paths
-      for (const [appId, app] of Object.entries(community.apps || {})) {
-        if (app.localPath) {
-          app.absolutePath = path.join(absWorkspaceRoot, app.localPath);
-        }
-      }
-    }
 
     // Compute absolute paths for products
     for (const [productId, product] of Object.entries(this.products || {})) {
       if (product.localPath) {
-        product.absolutePath = path.join(absWorkspaceRoot, product.localPath);
+        product.absolutePath = resolveWorkspacePath(absWorkspaceRoot, product.localPath, productId);
       }
     }
   }
   
-  // ============ Community Tracking Methods ============
-  
-  /**
-   * Register a community in the root workspace
-   * @param {string} communityId - Community identifier
-   * @param {Object} communityConfig - Community configuration
-   * @param {string} communityConfig.localPath - Local folder path
-   * @param {string} communityConfig.tokenSymbol - Token symbol
-   * @param {Object} [communityConfig.apps] - Apps in this community
-   * @returns {boolean} Success status
-   */
-  registerCommunity(communityId, communityConfig) {
-    // V2: Community identity is server-authoritative (Products registry).
-    // workspace.json does not track communities. No-op.
-    return true;
-  }
-  
+  // ============ App Registration Methods ============
+
   /**
    * Register an app in the v2.1 workspace (env.platform or env.products).
    * community_id is server-authoritative — not stored in workspace.json.
@@ -337,11 +316,18 @@ export class WorkspaceConfig {
     if (!this.env) this.env = {};
     if (!Array.isArray(this.env.products)) this.env.products = [];
 
+    // communityId is STORED, not just validated. It was previously accepted as a parameter and
+    // silently discarded, so `descix init -c egpt` wrote no trace of `egpt` anywhere — and
+    // `workspace-identity.js` (this entry's reader) then had no community to report, which is
+    // how the generated agent files named nobody's community. Writer and reader are a pair:
+    // the key order in `readIdentity()` mirrors the shape written here.
     const entry = { appId, localPath: appConfig.localPath, kbId: appConfig.kbId || 'General' };
+    if (communityId) entry.communityId = communityId;
 
     if (this.env.platform?.appId === appId) {
       this.env.platform.localPath = appConfig.localPath;
       if (appConfig.kbId) this.env.platform.kbId = appConfig.kbId;
+      if (communityId) this.env.platform.communityId = communityId;
     } else {
       const idx = this.env.products.findIndex(p => p.appId === appId);
       if (idx >= 0) {
@@ -356,85 +342,6 @@ export class WorkspaceConfig {
     return true;
   }
   
-  /**
-   * Get community configuration by ID
-   * @param {string} communityId - Community identifier
-   * @returns {Object|null} Community configuration or null
-   */
-  getCommunity(communityId) {
-    return this.communities[communityId] || null;
-  }
-  
-  /**
-   * Get app configuration from a community
-   * @param {string} communityId - Community identifier
-   * @param {string} appId - App identifier
-   * @returns {Object|null} App configuration or null
-   */
-  getApp(communityId, appId) {
-    const community = this.communities[communityId];
-    if (!community || !community.apps) return null;
-    return community.apps[appId] || null;
-  }
-  
-  /**
-   * List all registered communities
-   * @returns {Array} Array of community IDs
-   */
-  listCommunities() {
-    return Object.keys(this.communities);
-  }
-  
-  /**
-   * List all apps in a community
-   * @param {string} communityId - Community identifier
-   * @returns {Array} Array of app IDs
-   */
-  listApps(communityId) {
-    const community = this.communities[communityId];
-    if (!community || !community.apps) return [];
-    return Object.keys(community.apps);
-  }
-  
-  /**
-   * Remove a community registration
-   * @param {string} communityId - Community identifier
-   * @returns {boolean} Success status
-   */
-  unregisterCommunity(communityId) {
-    if (this.communities[communityId]) {
-      // Remove directory mappings for all apps
-      const apps = this.communities[communityId].apps || {};
-      for (const [appId, appConfig] of Object.entries(apps)) {
-        if (appConfig.localPath) {
-          delete this.directoryMappings[appConfig.localPath];
-        }
-      }
-      delete this.communities[communityId];
-      return true;
-    }
-    return false;
-  }
-  
-  /**
-   * Remove an app registration
-   * @param {string} communityId - Community identifier
-   * @param {string} appId - App identifier
-   * @returns {boolean} Success status
-   */
-  unregisterApp(communityId, appId) {
-    const community = this.communities[communityId];
-    if (community && community.apps && community.apps[appId]) {
-      const appConfig = community.apps[appId];
-      if (appConfig.localPath) {
-        delete this.directoryMappings[appConfig.localPath];
-      }
-      delete community.apps[appId];
-      return true;
-    }
-    return false;
-  }
-  
   /**
    * Register a product (Unified Registry)
    * @param {string} productId - Global product identifier
@@ -535,7 +442,7 @@ export class WorkspaceConfig {
     // env.platform + env.products (Unified Registry - primary)
     if (wsRoot) {
       for (const [appId, cfg] of Object.entries(this._appIdToConfig || {})) {
-        const appPath = path.resolve(wsRoot, cfg.localPath);
+        const appPath = resolveWorkspacePath(wsRoot, cfg.localPath, appId);
         if (cwd.startsWith(appPath)) {
           return {
             appId,
@@ -546,28 +453,11 @@ export class WorkspaceConfig {
       }
     }
     
-    for (const [commId, comm] of Object.entries(this.communities || {})) {
-      for (const [appId, app] of Object.entries(comm.apps || {})) {
-        let appPath = app.absolutePath;
-        if (!appPath && app.localPath && wsRoot) {
-          appPath = path.join(wsRoot, app.localPath);
-        }
-        
-        if (appPath && cwd.startsWith(appPath)) {
-          return {
-            communityId: commId,
-            appId,
-            kbId: app.kbId || 'General'
-          };
-        }
-      }
-    }
-
     // products object (legacy)
     for (const [productId, product] of Object.entries(this.products || {})) {
       let productPath = product.absolutePath;
       if (!productPath && product.localPath && wsRoot) {
-        productPath = path.join(wsRoot, product.localPath);
+        productPath = resolveWorkspacePath(wsRoot, product.localPath, productId);
       }
 
       if (productPath && cwd.startsWith(productPath)) {
@@ -634,16 +524,303 @@ export class WorkspaceConfig {
   }
 
   /**
-   * Get API URL for the current workspace.
-   * In DEV mode, derives from env.platform.microservice.port (v2.1 format).
-   * Eliminates the need for DESCIX_API_URL in local dev.
-   * @returns {string}
+   * Get the API origin this workspace is configured for, or NULL when none is configured.
+   *
+   * Priority: env.apiUrl > legacy this.apiUrl. There is NO third branch. This used to end in
+   * `return DEFAULT_API_URL` — the shipped PROD origin — which meant an unconfigured workspace
+   * was indistinguishable from one that had deliberately chosen production, and every caller
+   * received a prod origin the developer had never picked. Resolution and the fail-loud live in
+   * `lib/origin.js`; this method only reports what THIS workspace file says.
+   *
+   * There is likewise no environment-name-to-localhost derivation: an environment names a cloud
+   * environment, and localhost is a URL you set explicitly
+   * (`descix config set-env dev --url https://localhost:4000`, or env.apiUrl).
+   *
+   * @returns {string|null} the configured origin, or null if this workspace names none
    */
   getApiUrl() {
-    if (this.apiUrl) return this.apiUrl;
-    const platformPort = this.env?.platform?.microservice?.port;
-    if (platformPort && this.env?.environment === 'DEV') return `https://localhost:${platformPort}`;
-    return 'https://descix.net';
+    // Consumes the ONE origin owner rather than re-deriving the precedence or re-spelling the
+    // declared default. Under (A') an unconfigured workspace resolves to the declared default
+    // PROD; the SOURCE that distinguishes "chose prod" from "chose nothing" is carried by
+    // resolveOrigin() and printed by the api-client, never by a null returned from here.
+    return resolveOrigin({
+      workspaceEnvApiUrl: this.env?.apiUrl,
+      legacyApiUrl: this.apiUrl,
+    }).origin;
+  }
+
+  /**
+   * Known environment URL mapping.
+   * Shared between `descix config set-env` and the `--env` global flag.
+   * Origins come from the ONE owner (@descix/app-sdk/dev envOrigins); this map
+   * adds only the CLI's own concern, the Secret Manager label.
+   * @type {Object.<string, {url: string, secretLabel: string}>}
+   */
+  static ENV_MAP = {
+    dev:  { url: ENV_ORIGINS.dev,  secretLabel: 'DEBUG' },
+    demo: { url: ENV_ORIGINS.demo, secretLabel: 'DEMO' },
+    prod: { url: ENV_ORIGINS.prod, secretLabel: 'LIVE' },
+  };
+
+  /**
+   * Set a WORKSPACE-LEVEL env key (env.gateway.port, env.devCerts, env.powchUrl,
+   * env.siteUrl) — the keys that describe the workspace itself rather than one app.
+   *
+   * These all previously had NO CLI verb, so the only way to set them was to hand-edit
+   * .descix/workspace.json (redteam G-6). Hand-editing a generated file is how the
+   * shape drifts and how a developer ends up debugging their own typo, which is the
+   * opposite of "it should all just work".
+   *
+   * Pass null to REMOVE a key; empty parent objects are cleaned up so the file never
+   * accumulates `"devCerts": {}` noise.
+   *
+   * @param {string} dottedKey - one of: gateway.port | devCerts.dir | devCerts.cert | devCerts.key | powchUrl | siteUrl
+   * @param {string|number|null} value
+   * @returns {Promise<string>} Path to saved config (from save())
+   */
+  async setEnvKey(dottedKey, value) {
+    const ALLOWED = ['gateway.port', 'devCerts.dir', 'devCerts.cert', 'devCerts.key', 'powchUrl', 'siteUrl'];
+    if (!ALLOWED.includes(dottedKey)) {
+      throw new Error(
+        `"${dottedKey}" is not a workspace-level env key.\n` +
+        `  Settable here: ${ALLOWED.join(', ')}\n` +
+        '  Per-app keys have their own verbs: descix app set-site / set-port / set-localpath.'
+      );
+    }
+
+    if (!this.env) this.env = {};
+    const parts = dottedKey.split('.');
+
+    if (value === null || value === undefined) {
+      if (parts.length === 1) {
+        delete this.env[parts[0]];
+      } else {
+        const parent = this.env[parts[0]];
+        if (parent) {
+          delete parent[parts[1]];
+          if (Object.keys(parent).length === 0) delete this.env[parts[0]];
+        }
+      }
+      return this.save();
+    }
+
+    if (parts.length === 1) {
+      this.env[parts[0]] = value;
+    } else {
+      if (!this.env[parts[0]]) this.env[parts[0]] = {};
+      this.env[parts[0]][parts[1]] = value;
+    }
+    return this.save();
+  }
+
+  /**
+   * Update an app's site.port in env.products[] (or env.platform if it is the platform app).
+   *
+   * Pass `null` to remove site.port; if site.{} becomes empty, site.{} is also deleted.
+   * Persists via save() at the end — same auto-save pattern as setEnvironment().
+   * Hard-fails if appId is not mapped in env.platform or env.products.
+   *
+   * @param {string} appId - App identifier (must exist in env.platform or env.products)
+   * @param {number|string|null} port - Port number to set, or null to remove site.port
+   * @returns {Promise<string>} Path to saved config (from save())
+   */
+  async setSitePort(appId, port) {
+    if (!appId) throw new Error('appId is required');
+
+    // Find the live env entry (platform or products[]) — not a copy
+    let entry = null;
+    if (this.env?.platform?.appId === appId) {
+      entry = this.env.platform;
+    } else if (Array.isArray(this.env?.products)) {
+      entry = this.env.products.find(p => p.appId === appId) || null;
+    }
+
+    if (!entry) {
+      throw new Error(
+        `App "${appId}" is not mapped in workspace.json. ` +
+        'Use `descix app init` to register, or `descix app set-localpath -a <id> -p <path>` to repoint.'
+      );
+    }
+
+    if (port === null || port === undefined) {
+      // Remove site.port; clean up empty site.{}
+      if (entry.site) {
+        delete entry.site.port;
+        if (Object.keys(entry.site).length === 0) {
+          delete entry.site;
+        }
+      }
+    } else {
+      if (!entry.site) entry.site = {};
+      entry.site.port = port;
+    }
+
+    return this.save();
+  }
+
+  /**
+   * Update an app's microservice.port in env.products[] (or env.platform if it is the platform app).
+   *
+   * Parallel to setSitePort(), but operates on the entry's microservice.{} slot.
+   * This is the canonical write path for the microservice port that `descix microservice init`
+   * reads (and hard-fails on if missing). Backs the `descix app set-port` command, closing
+   * WS-CLI-MESH-ROUTING-GAP without hand-editing workspace.json.
+   *
+   * Pass `null` to remove microservice.port; if microservice.{} becomes empty, it is also deleted.
+   * Persists via save() at the end — same auto-save pattern as setSitePort()/setEnvironment().
+   * Hard-fails if appId is not mapped in env.platform or env.products.
+   *
+   * @param {string} appId - App identifier (must exist in env.platform or env.products)
+   * @param {number|string|null} port - Port number to set, or null to remove microservice.port
+   * @returns {Promise<string>} Path to saved config (from save())
+   */
+  async setMicroservicePort(appId, port) {
+    if (!appId) throw new Error('appId is required');
+
+    // Find the live env entry (platform or products[]) — not a copy
+    let entry = null;
+    if (this.env?.platform?.appId === appId) {
+      entry = this.env.platform;
+    } else if (Array.isArray(this.env?.products)) {
+      entry = this.env.products.find(p => p.appId === appId) || null;
+    }
+
+    if (!entry) {
+      throw new Error(
+        `App "${appId}" is not mapped in workspace.json. ` +
+        'Use `descix app init` to register, or `descix app set-localpath -a <id> -p <path>` to repoint.'
+      );
+    }
+
+    if (port === null || port === undefined) {
+      // Remove microservice.port; clean up empty microservice.{}
+      if (entry.microservice) {
+        delete entry.microservice.port;
+        if (Object.keys(entry.microservice).length === 0) {
+          delete entry.microservice;
+        }
+      }
+    } else {
+      if (!entry.microservice) entry.microservice = {};
+      entry.microservice.port = port;
+    }
+
+    return this.save();
+  }
+
+  /**
+   * Update an app's site config in env.products[] (or env.platform if it is the platform app).
+   *
+   * Parallel to setSitePort()/setMicroservicePort(), but operates on the entry's site.{} slot's
+   * static-site fields. This is the canonical write path for site.static — the relative path the
+   * dev gateway's staticSitePlugin serves at /p/{appId}/ (see createViteProxyConfig:
+   * site.static is resolved against the app's localPath; "." means the localPath itself).
+   * Backs the `descix app set-site` command, closing the site.static workspace gap without
+   * hand-editing workspace.json (the org rule forbids hand edits — CEO-D-2026-06-02-SSGPOD-SITE-PREPROD).
+   *
+   * Mutates site.static and/or site.port. Pass static === null to remove site.static; pass
+   * port === null to remove site.port. If site.{} becomes empty after removals it is deleted.
+   * Persists via save() at the end — same auto-save pattern as setSitePort()/setMicroservicePort().
+   * Hard-fails if appId is not mapped in env.platform or env.products.
+   *
+   * @param {string} appId - App identifier (must exist in env.platform or env.products)
+   * @param {Object} fields - Fields to set on site.{}
+   * @param {string|null} [fields.static] - Relative static-site path to set, or null to remove site.static
+   * @param {number|string|null} [fields.port] - Site dev-server port to set, or null to remove site.port
+   * @returns {Promise<string>} Path to saved config (from save())
+   */
+  async setStaticSite(appId, fields = {}) {
+    if (!appId) throw new Error('appId is required');
+    if (!fields || typeof fields !== 'object') throw new Error('fields object is required');
+
+    // Find the live env entry (platform or products[]) — not a copy
+    let entry = null;
+    if (this.env?.platform?.appId === appId) {
+      entry = this.env.platform;
+    } else if (Array.isArray(this.env?.products)) {
+      entry = this.env.products.find(p => p.appId === appId) || null;
+    }
+
+    if (!entry) {
+      throw new Error(
+        `App "${appId}" is not mapped in workspace.json. ` +
+        'Use `descix app init` to register, or `descix app set-localpath -a <id> -p <path>` to repoint.'
+      );
+    }
+
+    if (!entry.site) entry.site = {};
+
+    // site.static — set or remove
+    if ('static' in fields) {
+      if (fields.static === null || fields.static === undefined) {
+        delete entry.site.static;
+      } else {
+        entry.site.static = fields.static;
+      }
+    }
+
+    // site.port — set or remove (parallel to setSitePort, for static+devCommand sites)
+    if ('port' in fields) {
+      if (fields.port === null || fields.port === undefined) {
+        delete entry.site.port;
+      } else {
+        entry.site.port = fields.port;
+      }
+    }
+
+    // Clean up an empty site.{} so we never leave a bare {} behind
+    if (Object.keys(entry.site).length === 0) {
+      delete entry.site;
+    }
+
+    return this.save();
+  }
+
+  /**
+   * Persistently set the target environment in workspace.json.
+   *
+   * Updates env.environment and env.apiUrl, then saves. EVERY environment writes a
+   * URL — including dev, which writes the cloud DEV origin. Pointing at a local
+   * backend is `--url`: `descix config set-env dev --url https://localhost:4000`.
+   * For custom envs, uses --url or defaults to https://{name}.descix.net.
+   *
+   * @param {string} envName - Environment name (dev, demo, prod, or custom)
+   * @param {string|null} [apiUrl] - Explicit API URL override
+   * @returns {Promise<{configPath: string, environment: string, apiUrl: string, secretLabel: string}>}
+   */
+  async setEnvironment(envName, apiUrl = null) {
+    const normalized = envName.toLowerCase();
+    const known = WorkspaceConfig.ENV_MAP[normalized];
+
+    let resolvedUrl;
+    let secretLabel;
+    let envLabel;
+
+    if (known) {
+      resolvedUrl = apiUrl || known.url; // explicit --url overrides even for known envs
+      secretLabel = known.secretLabel;
+      envLabel = normalized.toUpperCase();
+    } else {
+      resolvedUrl = apiUrl || `https://${normalized}.descix.net`;
+      secretLabel = normalized.toUpperCase();
+      envLabel = normalized.toUpperCase();
+    }
+
+    // Update in-memory state
+    if (!this.env) this.env = {};
+    this.env.environment = envLabel;
+
+    this.env.apiUrl = resolvedUrl;
+
+    // Save to disk
+    const configPath = await this.save();
+
+    return {
+      configPath,
+      environment: envLabel,
+      apiUrl: resolvedUrl,
+      secretLabel
+    };
   }
   
   /**
@@ -665,44 +842,12 @@ export class WorkspaceConfig {
    */
   validate() {
     const errors = [];
-    
-    // For v2 root workspace with communities
-    if (this.version === '2.0' && Object.keys(this.communities).length > 0) {
-      for (const [communityId, community] of Object.entries(this.communities)) {
-        if (community.apps) {
-          for (const [appId, app] of Object.entries(community.apps)) {
-            if (!app.localPath) {
-              errors.push(`Community "${communityId}" app "${appId}" missing localPath`);
-            }
-          }
-        }
-      }
-      return {
-        isValid: errors.length === 0,
-        errors
-      };
-    }
-    
-    // Legacy v1 validation
-    if (!this.primaryCommunity) {
-      errors.push('Missing primaryCommunity');
-    }
-    
-    if (!this.defaultContext) {
-      errors.push('Missing defaultContext');
-    } else {
-      if (!this.defaultContext.communityId) errors.push('defaultContext missing communityId');
-      if (!this.defaultContext.appId) errors.push('defaultContext missing appId');
-      if (!this.defaultContext.kbId) errors.push('defaultContext missing kbId');
-    }
-    
-    // Validate directory mappings
-    for (const [dir, context] of Object.entries(this.directoryMappings)) {
-      if (!context.communityId) errors.push(`Directory "${dir}" mapping missing communityId`);
-      if (!context.appId) errors.push(`Directory "${dir}" mapping missing appId`);
-      if (!context.kbId) errors.push(`Directory "${dir}" mapping missing kbId`);
+
+    // v2.1 validation: must have env block
+    if (!this.env || Object.keys(this.env).length === 0) {
+      errors.push('Missing env block — workspace.json must be v2.1 format with env.platform or env.products');
     }
-    
+
     return {
       isValid: errors.length === 0,
       errors