@descix/cli 1.0.5 → 1.0.7

package/lib/workspace-config.js

@@ -2,6 +2,29 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { ENV_ORIGINS } from '@descix/app-sdk/dev';
 import { resolveOrigin } from './origin.js';
+// The one canonical KB-sync surface, from its owner. The example in requireContext() is a remedy
+// a stuck developer will copy verbatim, so it must resolve to the live verb rather than a literal
+// that can go stale where nobody is watching.
+import { CANONICAL_KB_SYNC } from './commands/retired-kb-sync.js';
+
+/**
+ * THE ONE OWNER of "this app is not mapped in workspace.json, here is how to fix it".
+ *
+ * This text existed as three byte-identical copies in this file, and TWO OTHER call sites in
+ * bin/descix.js answered the same condition with a DIFFERENT and wrong remedy — `npx descix init`,
+ * which initialises a WORKSPACE and cannot map an app, so a developer who followed it stayed
+ * exactly as stuck. That is the mirror-drift tell: the same condition explained two ways, and the
+ * wrong one was the one a developer actually hit on the onboarding path.
+ *
+ * @param {string} appId - the app that is not mapped
+ * @returns {string}
+ */
+export function unmappedAppMessage(appId) {
+  return (
+    `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.'
+  );
+}
 
 /**
  * ONE OWNER for turning a workspace-relative localPath into an absolute path.
@@ -31,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.
  * 
@@ -50,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);
     
@@ -126,6 +234,90 @@ 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.
+   *
+   * This existed as three byte-identical copies (setSitePort, setMicroservicePort,
+   * setStaticSite) and `set-localpath` hand-rolled a FOURTH variant in bin/descix.js that
+   * walked env.products ONLY. That omission is the whole reason the platform app silently
+   * failed: the loop found nothing, wrote nothing, and the command still printed success.
+   * A fourth copy here would have reproduced the same class of bug, so there is now one.
+   *
+   * @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, and the sibling that was missing while
+   * setSitePort/setMicroservicePort/setStaticSite all existed. 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
@@ -193,54 +385,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;
     }
   }
@@ -248,6 +484,17 @@ export class WorkspaceConfig {
   /**
    * Save workspace configuration in v2.1 format.
    * Always writes env.platform / env.products structure.
+   *
+   * PRESERVES KEYS IT DOES NOT UNDERSTAND. This method used to serialize a fixed field list from
+   * memory over the whole file, so ANY top-level key it did not itself enumerate was silently
+   * destroyed by the next `descix app set-port` — a writer re-serializing a known schema and
+   * discarding the rest. That is the same defect class as a record writer dropping a field it was
+   * never taught about, and it is invisible: the write succeeds, the file looks well-formed, and
+   * the loss is only discovered by whoever needed the missing key.
+   *
+   * The on-disk file is re-read at save time rather than trusted from construction, because the
+   * instance may have been held across another writer's save.
+   *
    * @param {string} [workspaceRoot] - Workspace root directory (uses stored root if not provided)
    * @returns {Promise<string>} Path to saved config
    */
@@ -266,7 +513,32 @@ export class WorkspaceConfig {
     // Build env block for v2.1 output
     const envBlock = (this.env && Object.keys(this.env).length > 0) ? this.env : null;
 
+    // The keys this writer OWNS. Everything else on disk is carried through untouched.
+    const OWNED = ['version', 'workspaceRoot', 'type', 'env', 'driveConfig'];
+
+    let onDisk = {};
+    try {
+      const existing = await fs.readFile(configPath, 'utf-8');
+      const parsed = JSON.parse(existing);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) onDisk = parsed;
+    } catch (err) {
+      // ENOENT is the ordinary first save. A PRESENT-BUT-UNPARSEABLE file is different: carrying
+      // on would overwrite content we could not read, so refuse and name the file.
+      if (err.code !== 'ENOENT') {
+        throw new Error(
+          `Refusing to overwrite ${configPath}: it exists but could not be read as JSON ` +
+          `(${err.message}). Fix or remove it — saving now would destroy whatever it holds.`
+        );
+      }
+    }
+
+    const carried = {};
+    for (const [k, v] of Object.entries(onDisk)) {
+      if (!OWNED.includes(k)) carried[k] = v;
+    }
+
     const configData = {
+      ...carried,
       version: '2.1',
       workspaceRoot: path.resolve(root),
       type: this.type,
@@ -279,23 +551,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 ============
 
   /**
@@ -313,6 +568,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 = [];
 
@@ -342,58 +605,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
    * 
@@ -453,23 +664,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;
   }
   
@@ -508,7 +702,7 @@ export class WorkspaceConfig {
         'Options:\n' +
         '  1. cd into an app directory\n' +
         '  2. Use flag: -a <app_id>\n\n' +
-        'Example: npx descix update kb -a daita'
+        `Example: npx ${CANONICAL_KB_SYNC} -a daita`
       );
     }
     
@@ -524,19 +718,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
@@ -545,7 +740,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;
   }
 
@@ -627,20 +821,7 @@ export class WorkspaceConfig {
   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.'
-      );
-    }
+    const entry = this._liveEnvEntry(appId);
 
     if (port === null || port === undefined) {
       // Remove site.port; clean up empty site.{}
@@ -677,20 +858,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(
-        `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.'
-      );
-    }
+    const entry = this._liveEnvEntry(appId);
 
     if (port === null || port === undefined) {
       // Remove microservice.port; clean up empty microservice.{}
@@ -733,20 +901,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(
-        `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.'
-      );
-    }
+    const entry = this._liveEnvEntry(appId);
 
     if (!entry.site) entry.site = {};
 
@@ -780,9 +935,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.5",
+  "version": "1.0.7",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",
@@ -29,8 +29,8 @@
   "author": "DeSciX",
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "@descix/app-sdk": "^0.1.2",
-    "@descix/sdk": "^1.0.0",
+    "@descix/app-sdk": "^0.1.5",
+    "@descix/sdk": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "axios": "^1.7.9",
     "chalk": "^5.6.2",