@descix/cli 1.0.6 → 1.0.8

package/lib/workspace-config.js

@@ -54,9 +54,98 @@ export function resolveWorkspacePath(workspaceRoot, localPath, label = 'app') {
     return path.resolve(workspaceRoot, localPath);
 }
 
+/**
+ * The ONE text for "there is no workspace here". It is correct advice for exactly one state —
+ * the file does not exist — and it is a lie for every other state, which is why it now has a
+ * single owner instead of being retyped at each throw site.
+ */
+const NOT_CONFIGURED_MESSAGE =
+  'Workspace not configured.\n' +
+  'Run "npx descix init" first to initialize your workspace.';
+
+/**
+ * THE ONE OWNER of "how do I set the API origin". Named by every refusal that turns a developer
+ * away from a retired way of setting it (the retired setter verb, a top-level `apiUrl` key), so
+ * the three live surfaces are spelled once. Order: persistent known env, persistent custom
+ * origin, per-run.
+ */
+export const TOP_LEVEL_API_URL_REMEDY =
+  'descix config init --env dev|demo|prod         # pin a known environment (writes env.apiUrl)\n' +
+  '  descix config set-env <name> --url <origin>    # pin a custom origin under your own env name\n' +
+  '  descix --api-url <origin> <command>            # this run only; no workspace change (e.g. serve)';
+
+/**
+ * THE ONE OWNER of the "move it aside, do not delete it" remedy.
+ *
+ * TWO different diagnoses reach this SAME remedy: a workspace.json that cannot be READ
+ * (WorkspaceUnreadableError) and one that reads fine but carries the retired v1 schema
+ * (load()'s v1 branch). Each used to hand-write its own remedy and THEY DISAGREED - the v1
+ * branch prescribed DELETING the file outright, while its sibling forty lines above it in this
+ * same file told the user their contents are lost only if they delete it. Two derivations of
+ * one fact drift silently; this is the extracted owner both now consume.
+ *
+ * A REFUSAL MUST NEVER PRESCRIBE A REMEDY THAT DESTROYS THE THING IT IS DIAGNOSING. That rule
+ * was ALREADY WRITTEN IN THIS FILE, as prose, a few lines above the branch that violated it -
+ * and it still shipped. A rule stated beside code does not enforce itself, and proximity may
+ * even hurt: a reader who sees the rule assumes it is in force. So it is expressed here as a
+ * FUNCTION every refusal must CALL, rather than a comment every author must NOTICE.
+ *
+ * @param {string} configPath - absolute path to the workspace.json being refused
+ * @param {string} initVerb - the verb that creates a fresh workspace once this file is aside
+ * @returns {string} the remedy block (no trailing newline)
+ */
+export function moveAsideRemedy(configPath, initVerb) {
+  return (
+    `  • Recover it: restore ${path.basename(configPath)} from version control or a backup.\n` +
+    `  • If you do not need its contents, move it aside first\n` +
+    `    (mv "${configPath}" "${configPath}.broken") and then run "${initVerb}".\n` +
+    `    Its contents are lost only if you delete it.`
+  );
+}
+
+/**
+ * THE ONE OWNER of "this workspace.json EXISTS and I could not read it".
+ *
+ * ABSENT and UNREADABLE are two different facts about the world and they need two different
+ * remedies. load() used to collapse them — every read error, JSON syntax error and permission
+ * error became NOT_CONFIGURED_MESSAGE — so a corrupt-but-present workspace.json reported as
+ * absent and the message prescribed `descix init` over a file that was still recoverable. A
+ * REFUSAL MUST NEVER PRESCRIBE A REMEDY THAT DESTROYS THE THING IT IS DIAGNOSING.
+ *
+ * It is a TYPE, not a message prefix, because callers have to branch on it (tryLoad returns
+ * null for absent and rethrows this) and matching on error text is the narrow-string-matching
+ * anti-pattern this file already suffered from — load()'s own v1 re-throw was an
+ * `error.message.includes(...)` test, and it is deleted in the same change.
+ *
+ * save() already refuses to overwrite a present-but-unparseable file and names it. This is the
+ * READ side of that same judgment, so the two halves of the file's lifecycle now agree.
+ */
+export class WorkspaceUnreadableError extends Error {
+  constructor(configPath, cause) {
+    // fs errors already lead with their code ("EACCES: permission denied, open ..."); JSON.parse
+    // errors carry no code at all. Prefix only when it is not already there, so the reason line
+    // never reads "EACCES: EACCES: ...".
+    const raw = cause?.message || String(cause);
+    const detail = cause?.code && !raw.startsWith(cause.code) ? `${cause.code}: ${raw}` : raw;
+    super(
+      `Workspace config exists but could not be read.\n` +
+      `  File:   ${configPath}\n` +
+      `  Reason: ${detail}\n` +
+      `\n` +
+      `This file is still on disk and has NOT been modified. Do NOT run "descix init" here —\n` +
+      `that command is for a workspace that is ABSENT, and this one is DAMAGED.\n` +
+      moveAsideRemedy(configPath, 'descix init')
+    );
+    this.name = 'WorkspaceUnreadableError';
+    this.code = 'WORKSPACE_UNREADABLE';
+    this.configPath = configPath;
+    this.cause = cause;
+  }
+}
+
 /**
  * WorkspaceConfig - Manages workspace-specific configuration
- * 
+ *
  * This is the SOLE configuration methodology for DeSciX CLI.
  * All path resolution and context detection uses workspace.json.
  * 
@@ -73,13 +162,9 @@ export class WorkspaceConfig {
     
     // Legacy fields (kept for save() PWA response conversion compatibility)
     this.defaultContext = config.defaultContext;
-    this.apiUrl = config.apiUrl;
     this.environment = config.environment;
     this.directoryMappings = config.directoryMappings || {};
 
-    // V2.1 Product tracking (Unified Registry)
-    this.products = config.products || {};
-
     // app_id → localPath map from env.platform + env.products (Unified Registry)
     this._appIdToConfig = this._buildAppIdMap(config);
     
@@ -149,6 +234,87 @@ export class WorkspaceConfig {
     return null;
   }
 
+  /**
+   * The RAW registry entry for an app — `localPath` exactly as workspace.json carries it, with NO
+   * path resolution and therefore no possibility of throwing on a bad stored value.
+   *
+   * This exists for exactly one caller shape: a command that is about to REPLACE an app's
+   * localPath. Such a command must not resolve the OUTGOING value. getAppByAppId() resolves, and
+   * resolving the value you are on your way to overwrite is what made `descix app set-localpath`
+   * unusable precisely when it was needed — a workspace already carrying a rejected localPath
+   * could not be repaired by the one verb whose job is repairing it, while the rejection itself
+   * forbade hand-editing. The verb was the prescribed remedy and the verb refused.
+   *
+   * It reads the SAME map getAppByAppId reads (_buildAppIdMap is still the one owner of "what is
+   * mapped"); it simply stops short of resolution. Do NOT use it to obtain a usable path — take
+   * getAppByAppId().absolutePath for that, so the loader's rejection still runs.
+   *
+   * @param {string} appId - App/product identifier
+   * @returns {{ localPath: string, communityId: string|null, kbId: string }|null}
+   */
+  getAppEntry(appId) {
+    if (!appId) return null;
+    return this._appIdToConfig?.[appId] || null;
+  }
+
+  /**
+   * THE ONE OWNER of "find the LIVE env entry for this app, or hard-fail".
+   *
+   * Live means the actual object inside this.env — mutate it and save() persists the mutation.
+   * getAppByAppId() and getAppEntry() both return copies and are useless for writing.
+   *
+   * The one lookup every entry setter (setMicroservicePort, setStaticSite, setLocalPath) uses. A
+   * private walk of env.products ONLY misses the platform app, finds nothing, writes nothing and
+   * still reports success.
+   *
+   * @param {string} appId - App identifier
+   * @returns {Object} the live env.platform or env.products[] entry
+   * @throws if appId is not mapped
+   */
+  _liveEnvEntry(appId) {
+    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(unmappedAppMessage(appId));
+    }
+    return entry;
+  }
+
+  /**
+   * Update an app's localPath in env.platform or env.products[].
+   *
+   * The canonical write path for localPath. Backs `descix app set-localpath`.
+   *
+   * localPath MUST be workspace-root-relative. It is validated here through
+   * resolveWorkspacePath — the LOADER'S OWN resolver, not a second copy of its rules — so a
+   * value the loader will refuse on the next read is refused now, before anything is written.
+   * Writing a value the loader rejects is what bricked workspaces: every subsequent command
+   * threw, including the repair verbs, while the rejection forbade hand-editing.
+   *
+   * Persists via save() — same auto-save pattern as its siblings.
+   * 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 {string} localPath - New path, relative to the workspace root
+   * @returns {Promise<string>} Path to saved config (from save())
+   */
+  async setLocalPath(appId, localPath) {
+    if (!appId) throw new Error('appId is required');
+    if (!localPath) throw new Error('localPath is required');
+
+    const entry = this._liveEnvEntry(appId);
+
+    // Validate through the loader's own resolver. Throws on an absolute path.
+    resolveWorkspacePath(this.workspaceRoot, localPath, appId);
+
+    entry.localPath = localPath;
+    return this.save();
+  }
+
   /**
    * Get the absolute path to an app's site/ directory
    * @param {string} appId - App identifier
@@ -216,54 +382,98 @@ export class WorkspaceConfig {
    * 
    * Automatically searches upward from startDir to find workspace root.
    * 
+   * ABSENT vs UNREADABLE IS DECIDED HERE AND NOWHERE ELSE. Callers consume the distinction as a
+   * type (WorkspaceUnreadableError), never by re-deciding it or by matching on message text.
+   *
    * @param {string} startDir - Directory to start searching from (default: cwd)
    * @returns {Promise<WorkspaceConfig>} Configuration object
-   * @throws {Error} If workspace not found
+   * @throws {Error} NOT_CONFIGURED_MESSAGE when no workspace.json exists
+   * @throws {WorkspaceUnreadableError} when one exists and cannot be read or parsed
    */
   static async load(startDir = process.cwd()) {
     // First, find workspace root by searching upward
     const workspaceRoot = await WorkspaceConfig.findWorkspaceRoot(startDir);
     if (!workspaceRoot) {
-      throw new Error(
-        'Workspace not configured.\n' +
-        'Run "npx descix init" first to initialize your workspace.'
-      );
+      throw new Error(NOT_CONFIGURED_MESSAGE);
     }
 
     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.'
-        );
-      }
+    let data;
+    try {
+      data = await fs.readFile(configPath, 'utf-8');
+    } catch (error) {
+      // ENOENT is the only genuinely ABSENT case reachable here: findWorkspaceRoot stat'd this
+      // file a moment ago, so ENOENT means it disappeared in between. Everything else — EACCES
+      // on a file we can see but not open, EISDIR, EIO — is a file that EXISTS. Reporting any of
+      // those as "not configured" is what sent users to `descix init` over recoverable data.
+      if (error.code === 'ENOENT') throw new Error(NOT_CONFIGURED_MESSAGE);
+      throw new WorkspaceUnreadableError(configPath, error);
+    }
 
-      return new WorkspaceConfig(parsed, workspaceRoot);
+    let parsed;
+    try {
+      parsed = JSON.parse(data);
     } catch (error) {
-      if (error.message.includes('v1 workspace format')) throw error;
+      // The file is present and holds bytes we could not parse. Name the parse error and the
+      // path; never absorb this into "not configured".
+      throw new WorkspaceUnreadableError(configPath, error);
+    }
+
+    // v1 format hard-error: has communities block but no env block.
+    // This throw now sits OUTSIDE any catch, so it propagates on its own. The previous
+    // `error.message.includes('v1 workspace format')` re-throw was narrow string matching
+    // (DeSciX anti-pattern #6) guarding a catch that should never have been this wide.
+    if (parsed.communities && !parsed.env) {
       throw new Error(
-        'Workspace not configured.\n' +
-        'Run "npx descix init" first to initialize your workspace.'
+        'v1 workspace format is not supported. Migrate to v2.1.\n' +
+        `  File:   ${configPath}\n` +
+        '\n' +
+        'This file is still on disk and has NOT been modified. There is no automatic v1 → v2.1\n' +
+        'migration: no surviving code reads the v1 layout, so its contents cannot be converted\n' +
+        'for you — but they are still readable BY YOU, and this file is the only copy of them.\n' +
+        moveAsideRemedy(configPath, 'descix app init')
       );
     }
+
+    // A v2.1 file carrying a TOP-LEVEL `apiUrl` is refused by name. That key is retired: no
+    // reader consumes it (the origin owner resolves `env.apiUrl` only) and save() never writes
+    // it, so a developer who set it by hand would be silently ignored on every invocation —
+    // exactly what the retired setter verb used to do from the other side, printing a success
+    // banner over a value that landed nowhere. The file is otherwise fine; the remedy is to remove the
+    // one key and set the origin where it is read. Nothing here is destructive.
+    if (typeof parsed.apiUrl === 'string' && parsed.apiUrl.trim() !== '') {
+      throw new Error(
+        'workspace.json carries a top-level "apiUrl", which is a retired v1 key that nothing reads.\n' +
+        `  File:   ${configPath}\n` +
+        `  Value:  ${parsed.apiUrl.trim()}\n` +
+        '\n' +
+        'The API origin lives at env.apiUrl. Remove the top-level key, then set the origin with:\n' +
+        `  ${TOP_LEVEL_API_URL_REMEDY}`
+      );
+    }
+
+    return new WorkspaceConfig(parsed, workspaceRoot);
   }
-  
+
   /**
    * Try to load workspace configuration, return null if not found
    * Useful for commands that need to check if workspace exists
-   * 
+   *
+   * RETURNS NULL FOR ABSENT, THROWS FOR UNREADABLE. "There is no workspace here" and "the
+   * workspace here is damaged" are different answers and only the first one is a soft no.
+   * Swallowing the second made a corrupt workspace look like a fresh directory, which is how a
+   * damaged workspace silently fell back to the DEFAULT (prod) origin instead of stopping.
+   *
    * @param {string} startDir - Directory to start searching from
-   * @returns {Promise<WorkspaceConfig|null>}
+   * @returns {Promise<WorkspaceConfig|null>} config, or null when no workspace.json exists
+   * @throws {WorkspaceUnreadableError} when one exists and cannot be read or parsed
    */
   static async tryLoad(startDir = process.cwd()) {
     try {
       return await WorkspaceConfig.load(startDir);
-    } catch {
+    } catch (error) {
+      if (error instanceof WorkspaceUnreadableError) throw error;
       return null;
     }
   }
@@ -338,23 +548,6 @@ export class WorkspaceConfig {
     return configPath;
   }
   
-  /**
-   * Compute and store absolute paths for all communities and apps
-   * Called automatically by save() to ensure paths are pre-computed
-   * 
-   * @param {string} workspaceRoot - Workspace root directory
-   */
-  computeAbsolutePaths(workspaceRoot) {
-    const absWorkspaceRoot = path.resolve(workspaceRoot);
-
-    // Compute absolute paths for products
-    for (const [productId, product] of Object.entries(this.products || {})) {
-      if (product.localPath) {
-        product.absolutePath = resolveWorkspacePath(absWorkspaceRoot, product.localPath, productId);
-      }
-    }
-  }
-  
   // ============ App Registration Methods ============
 
   /**
@@ -372,6 +565,14 @@ export class WorkspaceConfig {
       throw new Error('appId and localPath are required');
     }
 
+    // Validate through THE LOADER'S OWN RESOLVER — the same owner setLocalPath consumes, never a
+    // second copy of its rules. Three writers persisted a localPath and only ONE validated it, so
+    // `descix app init -p /abs` wrote an absolute value, created directories at that arbitrary
+    // absolute location, printed success, and bricked the workspace on the NEXT read — the loader
+    // refused the value for every command including the repair verbs, while the refusal forbade
+    // hand-editing. A path this CLI accepts must be honoured, or refused before anything is written.
+    resolveWorkspacePath(this.workspaceRoot, appConfig.localPath, appId);
+
     if (!this.env) this.env = {};
     if (!Array.isArray(this.env.products)) this.env.products = [];
 
@@ -401,58 +602,6 @@ export class WorkspaceConfig {
     return true;
   }
   
-  /**
-   * Register a product (Unified Registry)
-   * @param {string} productId - Global product identifier
-   * @param {Object} productConfig - Product configuration
-   * @returns {boolean} Success status
-   */
-  registerProduct(productId, productConfig) {
-    if (!productId || !productConfig.localPath) {
-      throw new Error('productId and localPath are required');
-    }
-    
-    this.products[productId] = {
-      type: productConfig.type || 'APP',
-      localPath: productConfig.localPath,
-      context: productConfig.context || {},
-      registeredAt: new Date().toISOString()
-    };
-    
-    this.version = '2.0';
-    return true;
-  }
-
-  /**
-   * Get product configuration
-   * @param {string} productId 
-   * @returns {Object|null}
-   */
-  getProduct(productId) {
-    return this.products[productId] || null;
-  }
-
-  /**
-   * List all registered products
-   * @returns {Array} Array of product IDs
-   */
-  listProducts() {
-    return Object.keys(this.products);
-  }
-
-  /**
-   * Remove a product registration
-   * @param {string} productId 
-   * @returns {boolean}
-   */
-  unregisterProduct(productId) {
-    if (this.products[productId]) {
-      delete this.products[productId];
-      return true;
-    }
-    return false;
-  }
-
   /**
    * Resolve context based on file path
    * 
@@ -512,23 +661,6 @@ export class WorkspaceConfig {
       }
     }
     
-    // products object (legacy)
-    for (const [productId, product] of Object.entries(this.products || {})) {
-      let productPath = product.absolutePath;
-      if (!productPath && product.localPath && wsRoot) {
-        productPath = resolveWorkspacePath(wsRoot, product.localPath, productId);
-      }
-
-      if (productPath && cwd.startsWith(productPath)) {
-        return {
-          productId,
-          communityId: product.context?.community || null,
-          appId: product.context?.app || productId,
-          kbId: product.kbId || 'General'
-        };
-      }
-    }
-    
     return null;
   }
   
@@ -583,19 +715,20 @@ export class WorkspaceConfig {
   }
 
   /**
-   * Get the API origin this workspace is configured for, or NULL when none is configured.
+   * Get the API origin this workspace is configured for.
    *
-   * Priority: env.apiUrl > legacy this.apiUrl. There is NO third branch. This used to end in
+   * The workspace names its origin at `env.apiUrl` and nowhere else. 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).
+   * There is no environment-name-to-localhost derivation: an environment names a cloud
+   * environment. A local origin is either per-run (`descix --api-url https://localhost:4000
+   * serve ...`) or a custom env (`descix config set-env local --url ...`) — see
+   * TOP_LEVEL_API_URL_REMEDY, the one owner of that list.
    *
-   * @returns {string|null} the configured origin, or null if this workspace names none
+   * @returns {string} the configured origin, or the declared default when this workspace names none
    */
   getApiUrl() {
     // Consumes the ONE origin owner rather than re-deriving the precedence or re-spelling the
@@ -604,7 +737,6 @@ export class WorkspaceConfig {
     // resolveOrigin() and printed by the api-client, never by a null returned from here.
     return resolveOrigin({
       workspaceEnvApiUrl: this.env?.apiUrl,
-      legacyApiUrl: this.apiUrl,
     }).origin;
   }
 
@@ -672,60 +804,16 @@ export class WorkspaceConfig {
     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(
-        unmappedAppMessage(appId)
-      );
-    }
-
-    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.
+   * 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().
+   * 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)
@@ -735,19 +823,7 @@ export class WorkspaceConfig {
   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(
-        unmappedAppMessage(appId)
-      );
-    }
+    const entry = this._liveEnvEntry(appId);
 
     if (port === null || port === undefined) {
       // Remove microservice.port; clean up empty microservice.{}
@@ -768,7 +844,7 @@ export class WorkspaceConfig {
   /**
    * 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
+   * Parallel to 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).
@@ -777,7 +853,7 @@ export class WorkspaceConfig {
    *
    * 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().
+   * Persists via save() at the end — same auto-save pattern as 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)
@@ -790,19 +866,7 @@ export class WorkspaceConfig {
     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(
-        unmappedAppMessage(appId)
-      );
-    }
+    const entry = this._liveEnvEntry(appId);
 
     if (!entry.site) entry.site = {};
 
@@ -815,7 +879,7 @@ export class WorkspaceConfig {
       }
     }
 
-    // site.port — set or remove (parallel to setSitePort, for static+devCommand sites)
+    // site.port — set or remove (for static+devCommand sites)
     if ('port' in fields) {
       if (fields.port === null || fields.port === undefined) {
         delete entry.site.port;
@@ -836,9 +900,12 @@ export class WorkspaceConfig {
    * 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.
+   * URL — including dev, which writes the cloud DEV origin. For custom envs, uses --url or
+   * defaults to https://{name}.descix.net. The `config set-env` verb refuses `--url` on a
+   * KNOWN name (it sends you to `config init --env`), so a local backend is either per-run —
+   * `descix --api-url https://localhost:4000 <command>`, no workspace change — or a custom name
+   * (`set-env local --url ...`). Mind that cloud-core derives DEPLOY_ENV and port auto-detect
+   * only from `env.environment === 'DEV'`, so a custom name is not a DEV workspace.
    *
    * @param {string} envName - Environment name (dev, demo, prod, or custom)
    * @param {string|null} [apiUrl] - Explicit API URL override

package/lib/workspace-identity.js

@@ -68,7 +68,6 @@ export function readIdentity(config = {}) {
     const resolved = resolveOrigin({
         envVar: process.env.DESCIX_API_URL,
         workspaceEnvApiUrl: env.apiUrl,
-        legacyApiUrl: config.apiUrl,
     });
 
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",
@@ -16,7 +16,8 @@
   "scripts": {
     "test": "node --test \"tests/*.test.js\"",
     "pack": "npm pack",
-    "check:doc-paths": "node scripts/check-doc-paths.js"
+    "check:doc-paths": "node scripts/check-doc-paths.js",
+    "briefer": "node scripts/briefer/run.mjs"
   },
   "keywords": [
     "descix",
@@ -29,7 +30,7 @@
   "author": "DeSciX",
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "@descix/app-sdk": "^0.1.2",
+    "@descix/app-sdk": "^0.1.5",
     "@descix/sdk": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "axios": "^1.7.9",
@@ -41,6 +42,9 @@
     "ora": "^9.0.0",
     "@descix/platform-api": "^2.0.0"
   },
+  "devDependencies": {
+    "acorn": "^8.18.0"
+  },
   "files": [
     "bin",
     "lib",