@sfdxy/anypoint-connect 0.11.1 → 0.13.0

package/README.md

@@ -1,196 +1,183 @@
 <p align="center">
-  <img src="docs/assets/logo.svg" alt="Anypoint Connect Banner" width="600" />
+  <img src="docs/assets/logo.svg" alt="Anypoint Connect — CLI and MCP toolkit for Anypoint Platform" width="640" />
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@sfdxy/anypoint-connect"><img src="https://img.shields.io/npm/v/@sfdxy/anypoint-connect?style=flat-square&color=34d399" alt="npm version" /></a>
-  <a href="https://github.com/Avinava/anypoint-connect/actions"><img src="https://img.shields.io/github/actions/workflow/status/Avinava/anypoint-connect/ci.yml?style=flat-square&color=38bdf8" alt="CI" /></a>
-  <a href="https://github.com/Avinava/anypoint-connect/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@sfdxy/anypoint-connect?style=flat-square&color=818cf8" alt="License" /></a>
-  <a href="https://www.npmjs.com/package/@sfdxy/anypoint-connect"><img src="https://img.shields.io/npm/dm/@sfdxy/anypoint-connect?style=flat-square&color=fbbf24" alt="Downloads" /></a>
+  <a href="https://www.npmjs.com/package/@sfdxy/anypoint-connect"><img src="https://img.shields.io/npm/v/@sfdxy/anypoint-connect?style=flat-square&color=087ea4" alt="npm version" /></a>
+  <a href="https://github.com/Avinava/anypoint-connect/actions"><img src="https://img.shields.io/github/actions/workflow/status/Avinava/anypoint-connect/ci.yml?style=flat-square" alt="CI status" /></a>
+  <a href="https://github.com/Avinava/anypoint-connect/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@sfdxy/anypoint-connect?style=flat-square" alt="MIT license" /></a>
 </p>
 
 <p align="center">
-  <strong>CLI + MCP toolkit for Anypoint Platform — deploy, tail logs, pull metrics, manage API specs, with production safety nets.</strong>
+  <strong>Operate Anypoint Platform from a CLI, an MCP client, or JavaScript—with guarded mutations and one shared authentication layer.</strong>
 </p>
 
 <p align="center">
-  <a href="https://avinava.github.io/anypoint-connect/">Documentation</a> •
-  <a href="#quick-start">Quick Start</a> •
-  <a href="#what-it-does">Capabilities</a> •
-  <a href="#mcp-server">MCP</a> •
-  <a href="#safety">Safety</a> •
-  <a href="#ecosystem">Ecosystem</a>
+  <a href="https://avinava.github.io/anypoint-connect/">Documentation</a> ·
+  <a href="https://avinava.github.io/anypoint-connect/getting-started/">Getting started</a> ·
+  <a href="https://avinava.github.io/anypoint-connect/credentials/">Credentials</a> ·
+  <a href="https://avinava.github.io/anypoint-connect/recipes/">Recipes</a>
 </p>
 
 ---
 
-## Quick Start
+## Start here
+
+You need Node.js `>=22`; Node.js 24 LTS is recommended. If Node and npm are unfamiliar, follow the
+[15-minute setup](https://avinava.github.io/anypoint-connect/getting-started/) instead of guessing through
+the commands below.
 
 ```bash
-# 1. Install
-npm install -g @sfdxy/anypoint-connect
+# Install
+npm install --global @sfdxy/anypoint-connect
 
-# 2. Configure (interactive — prompts for Client ID & Secret)
+# Save a Connected App Client ID and Secret
 anc config init
 
-# 3. Authenticate (opens browser for OAuth)
+# Authorize your Anypoint user in the browser
 anc auth login
 
-# 4. Verify
+# Verify the local session and one visible environment
 anc auth status
+anc apps list --env Sandbox
 ```
 
-No Connected App yet? The four-step setup, including the exact scopes to grant, is in
-[Getting started](https://avinava.github.io/anypoint-connect/getting-started/). Requires Node.js
-`>=20.0.0`.
+The Connected App must be **App acts on behalf of a user**, use Authorization Code, redirect to
+`http://localhost:3000/api/callback`, and include **Full Access** plus **Background Access**. The
+[credential guide](https://avinava.github.io/anypoint-connect/credentials/) gives the exact UI fields,
+administrator handoff, storage model, rotation steps, and troubleshooting.
 
-```bash
-anc apps list --env Sandbox
-anc logs tail my-api --env Sandbox
-anc monitor view --env Production
-```
+## Credential model
+
+| Item | Purpose | Storage |
+| --- | --- | --- |
+| Client ID | Identifies the Connected App | Profile `config.json` |
+| Client Secret | Authenticates the local client | Profile `config.json`, restricted to the current OS user |
+| OAuth tokens | Represent the user-authorized session | AES-256-GCM encrypted `tokens.enc` |
 
-Working across several organizations? Use named profiles —
-[Profiles and multiple orgs](https://avinava.github.io/anypoint-connect/profiles/).
+The ID and Secret do not provide access without a browser-authorized user session. Environment variables
+can override where app credentials come from, but they do not implement headless CI authentication. This
+release does not support the `client_credentials` grant, and its encrypted token file is machine-bound.
 
 ## What it does
 
 | Area | Examples |
 | --- | --- |
 | Applications | Status, deployment spec, resources, settings, deploy, redeploy, rollback, restart, scale, stop, start, delete |
-| Logs | Tail, download, error clustering with context windows, recurring patterns, statistical health |
-| Monitoring | Request metrics, percentiles, time series, per-replica, JVM memory and GC, freeform AMQL |
-| Exchange | Search, asset detail, spec download, JAR publication, environment comparison |
+| Logs | Tail, download, error clustering with context, recurring patterns, statistical health |
+| Monitoring | Request metrics, percentiles, time series, per-replica metrics, JVM memory and GC, freeform AMQL |
+| Exchange | Search, asset details, spec download, JAR publication, environment comparison |
 | API Manager | Instances, policies, SLA tiers, alerts |
-| Design Center | Projects, files, read, update, publish |
-| Platform | Environments, entitlements, audit log |
-| Anypoint MQ | Queues, depth and throughput, dead-letter browsing, test publishing |
-| Object Store v2 | Stores, keys, values |
+| Design Center | Projects, branches, conflict-safe file synchronization, governed publication |
+| Platform services | Environments, entitlements, audit log, Anypoint MQ, Object Store v2 |
 
-Every command is documented in the
-[CLI reference](https://avinava.github.io/anypoint-connect/cli-reference/).
+Copyable task flows are in [Common recipes](https://avinava.github.io/anypoint-connect/recipes/); every CLI
+command is in the [CLI reference](https://avinava.github.io/anypoint-connect/cli-reference/).
 
 ## MCP server
 
-56 tools for AI agents. Set up credentials first — the server has nothing to offer an unauthenticated
-session.
-
-```bash
-anc config init
-anc auth login
-```
-
-Every host runs the same command; only the file and the wrapping key differ.
-
-| Host | Where it goes | Wrapping key |
-| --- | --- | --- |
-| Claude Code | `.mcp.json`, or `claude mcp add` | `mcpServers` |
-| Claude Desktop | `claude_desktop_config.json` | `mcpServers` |
-| Codex | `.codex/config.toml`, or `codex mcp add` | `[mcp_servers.anypoint-connect]` |
-| VS Code, Copilot Chat | `.vscode/mcp.json` | `servers`, plus `"type": "stdio"` |
-| Copilot CLI, Gemini, other MCP clients | `.mcp.json` | `mcpServers` |
+Authenticate in a terminal before starting the server. The MCP host never receives the Client Secret or
+OAuth tokens; it sends tool calls to the local server that owns the session.
 
 ```json
 {
   "mcpServers": {
     "anypoint-connect": {
       "command": "npx",
-      "args": ["-y", "@sfdxy/anypoint-connect@0.11.0", "mcp"]
+      "args": ["-y", "@sfdxy/anypoint-connect@0.13.0", "mcp"]
     }
   }
 }
 ```
 
-Installed globally, use `"command": "anc", "args": ["mcp"]` and skip the download. No `env` block is
-needed: the active profile resolves from the project's `.anypoint-connect.json`, falling back to
-`default`. Credentials never pass through the protocol — the server holds the session, the agent calls
-tools.
+VS Code uses a `servers` wrapper and Codex uses TOML. See the
+[MCP guide](https://avinava.github.io/anypoint-connect/mcp/) or copy a checked-in configuration from
+[`examples/mcp`](examples/mcp).
 
-Per-host examples, prompts, and resources are in the
-[MCP guide](https://avinava.github.io/anypoint-connect/mcp/); the full tool table is in the
-[catalog](https://avinava.github.io/anypoint-connect/tools/).
+Example requests use synthetic names:
+
+```text
+What applications are visible in Sandbox? Read only.
+Analyze errors for sample-orders-api in Sandbox over the last two hours.
+Preview a deployment of target/sample-orders-api-1.3.0-mule-application.jar to Sandbox; do not apply it.
+```
 
 ## Safety
 
-Every mutating operation is **dry-run by default**: without `confirm: true` it returns a preview and
-changes nothing. Redeploying an existing app changes **only** the artifact reference, so runtime, target,
-replicas, and settings are preserved and a version bump cannot silently downgrade a runtime or halve
-capacity. `update_app_settings` PATCHes only application properties, merging protected values rather than
-blanking them. Deletion requires a deployment-ID-bound confirmation — plus a separate acknowledgement in
-production — so it fails closed if the deployment changed since you looked.
+Mutating MCP tools are previews until `confirm: true` is supplied. Artifact updates preserve runtime,
+target, replicas, and settings. Deletion requires the deployment ID returned by the preview, and
+production operations require an additional acknowledgement.
 
 ```jsonc
-// preview
-deploy_jar({ "jarPath": "target/example-api-1.0.0-mule-application.jar", "appName": "example-api", "environment": "Sandbox" })
-// apply
-deploy_jar({ "jarPath": "target/example-api-1.0.0-mule-application.jar", "appName": "example-api", "environment": "Sandbox", "confirm": true })
+// Preview only
+update_app_artifact({
+  "appName": "sample-orders-api",
+  "environment": "Sandbox",
+  "version": "1.3.0"
+})
+
+// Apply the reviewed change
+update_app_artifact({
+  "appName": "sample-orders-api",
+  "environment": "Sandbox",
+  "version": "1.3.0",
+  "confirm": true
+})
 ```
 
-Full model in [Safety](https://avinava.github.io/anypoint-connect/safety/); the build, publish, deploy,
-and rollback path in [Deploying a JAR](https://avinava.github.io/anypoint-connect/deployment-tools/).
-
-## When something fails
-
-Access problems come in six distinct states — not configured, not authenticated, environment not visible,
-not permitted, transient, and ready — and they have different fixes. The error text names which one you
-are in. See [Access readiness](https://avinava.github.io/anypoint-connect/readiness/) and
-[Troubleshooting](https://avinava.github.io/anypoint-connect/troubleshooting/).
+The complete contract is in the [safety model](https://avinava.github.io/anypoint-connect/safety/).
 
 ## Library
 
-```typescript
+The library reuses a profile authenticated with `anc auth login`. The Client ID and Secret construct the
+client; the profile selects the encrypted token store.
+
+```javascript
 import { AnypointClient } from '@sfdxy/anypoint-connect';
 
 const client = new AnypointClient({
-  clientId: process.env.ANYPOINT_CLIENT_ID!,
-  clientSecret: process.env.ANYPOINT_CLIENT_SECRET!,
+  clientId: process.env.ANYPOINT_CLIENT_ID,
+  clientSecret: process.env.ANYPOINT_CLIENT_SECRET,
+  profileName: process.env.ANYPOINT_PROFILE || 'default',
 });
 
-const me = await client.whoami();
-const envs = await client.accessManagement.getEnvironments(me.organization.id);
+const identity = await client.whoami();
+const environments = await client.accessManagement.getEnvironments(identity.organization.id);
+console.log(`Authenticated; ${environments.length} environment(s) visible.`);
 ```
 
-The API clients give you token refresh, rate limiting, and caching, but not the confirmation gates — those
-live in the CLI and MCP layers. More in the
-[library guide](https://avinava.github.io/anypoint-connect/library/).
+Direct API clients include bearer injection, refresh, rate limiting, and caching. They do not include the
+CLI/MCP confirmation gates. Start with the runnable JavaScript example in
+[`examples/library`](examples/library) and read the [library guide](https://avinava.github.io/anypoint-connect/library/).
 
-## Documentation
+## Profiles and multiple organizations
 
-Published at **<https://avinava.github.io/anypoint-connect/>** with search.
+Use neutral profile names rather than customer names:
 
-| Page | Contents |
-| --- | --- |
-| [Getting started](docs/getting-started.md) | Install, Connected App, scopes, credentials, authenticate |
-| [Profiles](docs/profiles.md) | Multiple organizations, resolution order, storage layout |
-| [Access readiness](docs/readiness.md) | The six access states and their fixes |
-| [CLI reference](docs/cli-reference.md) | Every command group |
-| [MCP server](docs/mcp.md) | Host setup, prompts, resources |
-| [Tool catalog](docs/tools.md) | All 56 tools, and how to choose between overlapping ones |
-| [Safety model](docs/safety.md) | Dry runs, narrow updates, bound deletion |
-| [Deploying a JAR](docs/deployment-tools.md) | Build, publish, deploy, roll back |
-| [Library API](docs/library.md) | Programmatic use |
-| [Troubleshooting](docs/troubleshooting.md) | Symptoms and causes |
-| [Architecture](docs/architecture.md) | Layers and design notes |
-
-## Ecosystem
-
-The canonical package matrix and supported combination live in the
-[`mule-skills` ecosystem hub](https://avinava.github.io/mule-skills/ecosystem/). This is the only tool
-in the set that needs Anypoint credentials. A complete release crosses two boundaries: `mule-build`
-produces and versions the artifact, while this package puts it in an environment. More detail is on
-the local [ecosystem page](docs/ecosystem.md).
+```bash
+anc config init --profile team-a
+anc auth login --profile team-a
+anc config use team-a
+```
+
+The directory binding contains only a local profile label, but it can still reveal internal context. Add
+`.anypoint-connect.json` to the project's `.gitignore`. Resolution rules and storage layout are in
+[Profiles](https://avinava.github.io/anypoint-connect/profiles/).
 
 ## Development
 
 ```bash
+nvm use
 npm install
 npm run build
 npm test
 npm run lint
+npm run docs:check
+mkdocs build --strict
 ```
 
-Releases are tag-triggered: bump the version, push the tag with `git push --follow-tags`, and GitHub
-Actions runs CI, publishes to npm with provenance, and creates the release.
+CI tests Node 22, 24, and 26. Documentation is built with MkDocs Material and published through GitHub
+Pages. Releases are tag-triggered and published to npm with provenance.
 
 ## License
 

package/dist/api/DesignCenterApi.d.ts

@@ -31,6 +31,10 @@ export interface DesignCenterBranch {
     commitId?: string;
     isDefault?: boolean;
 }
+export interface DesignCenterSaveFile {
+    path: string;
+    content: string;
+}
 export interface PublishToExchangeOptions {
     name: string;
     apiVersion: string;
@@ -56,24 +60,25 @@ export declare class DesignCenterApi {
     /**
      * List all Design Center projects in the organization.
      */
-    getProjects(orgId: string): Promise<DesignCenterProject[]>;
+    getProjects(orgId: string, refresh?: boolean): Promise<DesignCenterProject[]>;
     /**
      * Get project details by ID.
      */
     getProject(orgId: string, projectId: string): Promise<DesignCenterProject>;
-    /**
-     * Find a project by name (case-insensitive partial match).
-     */
+    /** Find a project by exact name. Partial project matching is intentionally unsafe. */
     findByName(orgId: string, name: string): Promise<DesignCenterProject | null>;
     /**
      * Find a project by name, throwing if not found.
      * Preferred over findByName when the project must exist.
      */
     findByNameOrThrow(orgId: string, name: string): Promise<DesignCenterProject>;
+    /** Create a new API design project after an exact collision check. */
+    createProject(orgId: string, name: string, classifier: 'raml' | 'oas'): Promise<DesignCenterProject>;
     /**
      * List branches for a project.
      */
     getBranches(orgId: string, projectId: string): Promise<DesignCenterBranch[]>;
+    createBranch(orgId: string, projectId: string, name: string, commitId?: string): Promise<DesignCenterBranch>;
     /**
      * List all files in a project branch.
      */
@@ -97,10 +102,15 @@ export declare class DesignCenterApi {
      * Release the write lock on a project branch.
      */
     releaseLock(orgId: string, projectId: string, branch?: string): Promise<void>;
+    /** Refresh a branch lock before the service's approximately one-minute expiry. */
+    maintainLock(orgId: string, projectId: string, branch?: string): Promise<void>;
     /**
      * Save a file to a project branch. Requires the lock to be held.
      */
     saveFile(orgId: string, projectId: string, filePath: string, content: string, branch?: string, commitMessage?: string): Promise<void>;
+    /** Save multiple files in the API's single batch operation. Requires a held lock. */
+    saveFiles(orgId: string, projectId: string, files: DesignCenterSaveFile[], branch?: string, commitMessage?: string): Promise<void>;
+    withLock<T>(orgId: string, projectId: string, branch: string, operation: () => Promise<T>): Promise<T>;
     /**
      * Atomically update a file: acquires lock → saves → releases lock.
      * Uses try/finally to always release the lock, even on failure.
@@ -112,7 +122,8 @@ export declare class DesignCenterApi {
      */
     getExchangeJson(orgId: string, projectId: string, branch?: string): Promise<Record<string, unknown> | null>;
     /**
-     * Publish a Design Center project to Anypoint Exchange.
+     * Legacy direct publication path retained for compatibility.
+     * New callers should use the preview-bound DesignCenterWorkflow.
      *
      * The DC XP API expects all publish parameters in the JSON body, NOT in the URL path.
      * Endpoint: POST /designcenter/api-designer/projects/{projectId}/branches/{branch}/publish/exchange
@@ -125,5 +136,11 @@ export declare class DesignCenterApi {
         assetId: string;
         version: string;
     }>;
+    /** Publish while the caller holds the branch lock. */
+    publishToExchangeLocked(orgId: string, projectId: string, options: PublishToExchangeOptions, branch?: string): Promise<{
+        groupId: string;
+        assetId: string;
+        version: string;
+    }>;
 }
 //# sourceMappingURL=DesignCenterApi.d.ts.map

package/dist/api/DesignCenterApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DesignCenterApi.d.ts","sourceRoot":"","sources":["../../src/api/DesignCenterApi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DesignCenterApi.d.ts","sourceRoot":"","sources":["../../src/api/DesignCenterApi.ts"],"names":[],"mappings":"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"}

package/dist/api/DesignCenterApi.js

@@ -40,9 +40,11 @@ export class DesignCenterApi {
     /**
      * List all Design Center projects in the organization.
      */
-    async getProjects(orgId) {
+    async getProjects(orgId, refresh = false) {
         const ownerId = await this.getOwnerId();
         const cacheKey = `dc:projects:${orgId}`;
+        if (refresh)
+            this.cache.delete(cacheKey);
         return this.cache.getOrCompute(cacheKey, async () => {
             return this.http.get(`${BASE}/projects`, {
                 headers: this.dcHeaders(orgId, ownerId),
@@ -58,25 +60,42 @@ export class DesignCenterApi {
             headers: this.dcHeaders(orgId, ownerId),
         });
     }
-    /**
-     * Find a project by name (case-insensitive partial match).
-     */
+    /** Find a project by exact name. Partial project matching is intentionally unsafe. */
     async findByName(orgId, name) {
         const projects = await this.getProjects(orgId);
-        const lower = name.toLowerCase();
-        return projects.find((p) => p.name.toLowerCase().includes(lower)) || null;
+        const exact = projects.find((project) => project.name === name);
+        if (exact)
+            return exact;
+        const insensitive = projects.filter((project) => project.name.toLowerCase() === name.toLowerCase());
+        if (insensitive.length > 1) {
+            throw new Error(`Multiple projects have the same case-insensitive name "${name}"; use the project ID.`);
+        }
+        return insensitive[0] || null;
     }
     /**
      * Find a project by name, throwing if not found.
      * Preferred over findByName when the project must exist.
      */
     async findByNameOrThrow(orgId, name) {
-        const project = await this.findByName(orgId, name);
+        const projects = await this.getProjects(orgId);
+        const byId = projects.find((candidate) => candidate.id === name);
+        const project = byId || (await this.findByName(orgId, name));
         if (!project) {
             throw new Error(`Project "${name}" not found. Use list_design_center_projects to see available projects.`);
         }
         return project;
     }
+    /** Create a new API design project after an exact collision check. */
+    async createProject(orgId, name, classifier) {
+        const projects = await this.getProjects(orgId, true);
+        if (projects.some((project) => project.name.toLowerCase() === name.toLowerCase())) {
+            throw new Error(`A Design Center project named "${name}" already exists.`);
+        }
+        const ownerId = await this.getOwnerId();
+        const project = await this.http.post(`${BASE}/projects`, { name, classifier }, { headers: this.dcHeaders(orgId, ownerId, { Accept: 'application/json' }) });
+        this.cache.delete(`dc:projects:${orgId}`);
+        return project;
+    }
     // ── Branches ───────────────────────────────────
     /**
      * List branches for a project.
@@ -87,6 +106,10 @@ export class DesignCenterApi {
             headers: this.dcHeaders(orgId, ownerId),
         });
     }
+    async createBranch(orgId, projectId, name, commitId) {
+        const ownerId = await this.getOwnerId();
+        return this.http.post(`${BASE}/projects/${projectId}/branches`, { name, ...(commitId ? { commitId } : {}) }, { headers: this.dcHeaders(orgId, ownerId, { Accept: 'application/json' }) });
+    }
     // ── Files ──────────────────────────────────────
     /**
      * List all files in a project branch.
@@ -182,24 +205,44 @@ export class DesignCenterApi {
             throw new Error(`Failed to release lock: ${errorMessage(e)}`);
         }
     }
+    /** Refresh a branch lock before the service's approximately one-minute expiry. */
+    async maintainLock(orgId, projectId, branch = 'master') {
+        const ownerId = await this.getOwnerId();
+        await this.http.post(`${BASE}/projects/${projectId}/branches/${branch}/status`, {}, { headers: this.dcHeaders(orgId, ownerId) });
+    }
     /**
      * Save a file to a project branch. Requires the lock to be held.
      */
     async saveFile(orgId, projectId, filePath, content, branch = 'master', commitMessage) {
+        await this.saveFiles(orgId, projectId, [{ path: filePath, content }], branch, commitMessage);
+    }
+    /** Save multiple files in the API's single batch operation. Requires a held lock. */
+    async saveFiles(orgId, projectId, files, branch = 'master', commitMessage) {
         const ownerId = await this.getOwnerId();
         try {
-            await this.http.post(`${BASE}/projects/${projectId}/branches/${branch}/save`, [
-                {
-                    path: filePath,
-                    content,
-                    type: 'file',
-                },
-            ], {
+            await this.http.post(`${BASE}/projects/${projectId}/branches/${branch}/save`, files.map((file) => ({ path: file.path, content: file.content, type: 'FILE' })), {
                 headers: this.dcHeaders(orgId, ownerId, commitMessage ? { 'x-commit-message': commitMessage } : {}),
             });
         }
         catch (e) {
-            throw new Error(`Failed to save file: ${errorMessage(e)}`);
+            throw new Error(`Failed to save files: ${errorMessage(e)}`);
+        }
+    }
+    async withLock(orgId, projectId, branch, operation) {
+        await this.acquireLock(orgId, projectId, branch);
+        try {
+            const result = await operation();
+            await this.releaseLock(orgId, projectId, branch);
+            return result;
+        }
+        catch (operationError) {
+            try {
+                await this.releaseLock(orgId, projectId, branch);
+            }
+            catch {
+                // Preserve the operation failure; the branch lock expires server-side.
+            }
+            throw operationError;
         }
     }
     /**
@@ -209,13 +252,7 @@ export class DesignCenterApi {
     async updateFile(orgId, projectId, filePath, content, branch = 'master', commitMessage) {
         // Clear project cache since we're modifying
         this.cache.delete(`dc:projects:${orgId}`);
-        await this.acquireLock(orgId, projectId, branch);
-        try {
-            await this.saveFile(orgId, projectId, filePath, content, branch, commitMessage);
-        }
-        finally {
-            await this.releaseLock(orgId, projectId, branch);
-        }
+        await this.withLock(orgId, projectId, branch, () => this.saveFile(orgId, projectId, filePath, content, branch, commitMessage));
     }
     // ── Publish ────────────────────────────────────
     /**
@@ -232,7 +269,8 @@ export class DesignCenterApi {
         }
     }
     /**
-     * Publish a Design Center project to Anypoint Exchange.
+     * Legacy direct publication path retained for compatibility.
+     * New callers should use the preview-bound DesignCenterWorkflow.
      *
      * The DC XP API expects all publish parameters in the JSON body, NOT in the URL path.
      * Endpoint: POST /designcenter/api-designer/projects/{projectId}/branches/{branch}/publish/exchange
@@ -241,35 +279,31 @@ export class DesignCenterApi {
      * If assetId or main file aren't specified, we auto-detect them from exchange.json.
      */
     async publishToExchange(orgId, projectId, options, branch = 'master') {
+        return this.withLock(orgId, projectId, branch, () => this.publishToExchangeLocked(orgId, projectId, options, branch));
+    }
+    /** Publish while the caller holds the branch lock. */
+    async publishToExchangeLocked(orgId, projectId, options, branch = 'master') {
         const ownerId = await this.getOwnerId();
         // Read exchange.json for defaults (assetId, main file, etc.)
         const exchangeMeta = await this.getExchangeJson(orgId, projectId, branch);
         const groupId = options.groupId || exchangeMeta?.groupId || orgId;
         const assetId = options.assetId || exchangeMeta?.assetId || options.name;
         const mainFile = options.main || exchangeMeta?.main;
-        // Acquire lock before publishing (required by DC API)
-        await this.acquireLock(orgId, projectId, branch);
-        try {
-            const response = await this.http
-                .post(`${BASE}/projects/${projectId}/branches/${branch}/publish/exchange`, {
-                name: options.name,
-                apiVersion: options.apiVersion,
-                version: options.version,
-                classifier: options.classifier,
-                main: mainFile,
-                assetId,
-                groupId,
-            }, {
-                headers: this.dcHeaders(orgId, ownerId),
-            })
-                .catch((e) => {
-                throw new Error(`Failed to publish: ${errorMessage(e)}`);
-            });
-            return response;
-        }
-        finally {
-            await this.releaseLock(orgId, projectId, branch);
-        }
+        return this.http
+            .post(`${BASE}/projects/${projectId}/branches/${branch}/publish/exchange`, {
+            name: options.name,
+            apiVersion: options.apiVersion,
+            version: options.version,
+            classifier: options.classifier,
+            main: mainFile,
+            assetId,
+            groupId,
+        }, {
+            headers: this.dcHeaders(orgId, ownerId),
+        })
+            .catch((e) => {
+            throw new Error(`Failed to publish: ${errorMessage(e)}`);
+        });
     }
 }
 //# sourceMappingURL=DesignCenterApi.js.map