@qodalis/cli 2.0.0-beta.13 → 2.0.0-beta.14

package/public-api.js

@@ -413,8 +413,27 @@ var CliKeyValueStore_TOKEN = "cli-key-value-store";
 var SyntaxHighlighterRegistry_TOKEN = "syntax-highlighter-registry";
 
 // src/lib/version.ts
-var LIBRARY_VERSION = "2.0.0-beta.13";
+var LIBRARY_VERSION = "2.0.0-beta.14";
 var API_VERSION = 2;
+var ANONYMOUS = "\0anonymous";
+function aliasOwner(context2) {
+  let auth;
+  try {
+    auth = context2.services.get(cliCore.ICliAuthorizationService_TOKEN);
+  } catch {
+    auth = void 0;
+  }
+  if (!auth) return void 0;
+  return auth.getPrincipal()?.name ?? ANONYMOUS;
+}
+function aliasesFor(state, owner) {
+  if (owner === void 0) return state?.aliases ?? {};
+  return state?.aliasesByUser?.[owner] ?? {};
+}
+function withAliases(state, owner, aliases) {
+  if (owner === void 0) return { aliases };
+  return { aliasesByUser: { ...state?.aliasesByUser ?? {}, [owner]: aliases } };
+}
 var CliAliasCommandProcessor = class {
   constructor() {
     this.command = "alias";
@@ -431,26 +450,33 @@ var CliAliasCommandProcessor = class {
       },
       storeName: "aliases"
     };
+    /** Shared aliases (used when no auth module is loaded) */
     this.userAliases = {};
+    this.aliasState = {};
     this.processors = [
       {
         command: "ls",
         description: "List all aliases",
         processCommand: async (_, context2) => {
           const { writer } = context2;
+          const visible = this.aliasesFor(context2);
           writer.writeln("Aliases:");
-          Object.entries(this.userAliases).forEach(
+          Object.entries(visible).forEach(
             ([alias, command2]) => {
               writer.writeInfo(`  ${alias} -> ${command2}`);
             }
           );
-          if (Object.keys(this.userAliases).length === 0) {
+          if (Object.keys(visible).length === 0) {
             writer.writeInfo("  No aliases defined");
           }
         }
       }
     ];
   }
+  /** Aliases visible to the current principal */
+  aliasesFor(context2) {
+    return aliasesFor(this.aliasState, aliasOwner(context2));
+  }
   writeDescription(context2) {
     const { writer, translator: t } = context2;
     writer.writeln(t.t("cli.alias.long_description", "Create shortcut aliases for frequently used commands"));
@@ -496,18 +522,20 @@ var CliAliasCommandProcessor = class {
       }
       context2.writer.writeInfo(`${alias} -> ${command2.args[alias]}`);
     }
-    context2.state.updateState({
-      aliases: {
-        ...this.userAliases,
+    const owner = aliasOwner(context2);
+    context2.state.updateState(
+      withAliases(this.aliasState, owner, {
+        ...aliasesFor(this.aliasState, owner),
         ...command2.args
-      }
-    });
+      })
+    );
     await context2.state.persist();
   }
   async initialize(context2) {
     this.stateSubscription?.unsubscribe();
-    this.stateSubscription = context2.state.select((x) => x["aliases"]).subscribe((aliases) => {
-      this.userAliases = aliases ?? {};
+    this.stateSubscription = context2.state.select((x) => x).subscribe((state) => {
+      this.aliasState = state ?? {};
+      this.userAliases = this.aliasState.aliases ?? {};
     });
   }
 };
@@ -1335,7 +1363,9 @@ var CliEvalCommandProcessor = class {
     this.acceptsRawInput = true;
     this.metadata = {
       icon: "\u{1F9EE}",
-      module: "misc"
+      module: "misc",
+      // Enforced only when an auth module is loaded (eval also needs allowEval)
+      requiredPermissions: ["system:eval"]
     };
   }
   async processCommand(command, context) {
@@ -2450,7 +2480,9 @@ var CliUnAliasCommandProcessor = class {
   async processCommand(command2, context2) {
     const { writer } = context2;
     const aliasToRemove = command2.value;
-    const { aliases } = context2.state.getState();
+    const state = context2.state.getState();
+    const owner = aliasOwner(context2);
+    const aliases = aliasesFor(state, owner);
     if (!aliases[aliasToRemove]) {
       writer.writeError(`Alias ${aliasToRemove} not found`);
       context2.process.exit(-1);
@@ -2460,9 +2492,7 @@ var CliUnAliasCommandProcessor = class {
     Object.keys(aliases).filter((alias) => alias !== aliasToRemove).forEach((alias) => {
       updated[alias] = aliases[alias];
     });
-    context2.state.updateState({
-      aliases: updated
-    });
+    context2.state.updateState(withAliases(state, owner, updated));
     await context2.state.persist();
   }
 };
@@ -4698,7 +4728,9 @@ var CliPackagesCommandProcessor = class {
     this.metadata = {
       sealed: true,
       icon: "\u{1F4E6}",
-      module: "system"
+      module: "system",
+      // Enforced only when an auth module is loaded
+      requiredPermissions: ["system:packages"]
     };
     this.stateConfiguration = {
       initialState: {
@@ -5773,6 +5805,8 @@ var CliServerConnection = class _CliServerConnection {
     this._basePath = "";
     this._wsReconnectAttempts = 0;
     this._wsReconnectTimer = null;
+    /** True once this connection registered its `server-events:<name>` background service */
+    this._eventServiceRegistered = false;
     this._healthCheckTimer = null;
     this._healthCheckAttempts = 0;
   }
@@ -5814,6 +5848,18 @@ var CliServerConnection = class _CliServerConnection {
     }
     return cliCore.resolveHeaders(this._config.headers);
   }
+  /**
+   * WebSocket URL for this server with auth: single-use upgrade params from
+   * auth providers when available, otherwise headers copied into the URL.
+   */
+  async buildWebSocketUrl(path) {
+    const url = this.toWebSocketUrl(this.normalizeUrl(this._config.url)) + path;
+    const params = await this._authService?.getWebSocketParams?.(this._config.name);
+    if (params) {
+      return cliCore.appendQueryParams(url, params);
+    }
+    return cliCore.buildAuthenticatedWebSocketUrl(url, () => this.resolveAuthHeaders());
+  }
   async connect() {
     try {
       const baseUrl = this.normalizeUrl(this._config.url);
@@ -6005,18 +6051,25 @@ var CliServerConnection = class _CliServerConnection {
       return;
     }
     const serviceName = `server-events:${this._config.name}`;
+    if (this._eventServiceRegistered && this._backgroundServices.getStatus(serviceName)) {
+      const status = this._backgroundServices.getStatus(serviceName).status;
+      const restart = status === "running" ? this._backgroundServices.restart(serviceName) : this._backgroundServices.start(serviceName);
+      restart.catch((e) => {
+        this._logger?.debug(`Background event service failed for "${this._config.name}", falling back to direct: ${e}`);
+        this.connectEventSocketDirect();
+      });
+      return;
+    }
     try {
       this._backgroundServices.register({
         name: serviceName,
         description: `Event stream for server '${this._config.name}'`,
         type: "daemon",
         onStart: async (ctx) => {
-          const baseUrl = this.normalizeUrl(this._config.url);
-          const wsUrl = cliCore.buildAuthenticatedWebSocketUrl(
-            this.toWebSocketUrl(baseUrl) + "/ws/v1/qcli/events",
-            () => this.resolveAuthHeaders()
-          );
-          ctx.log(`Connecting to ${wsUrl}`);
+          const wsUrl = await this.buildWebSocketUrl("/ws/v1/qcli/events");
+          if (!this._connected) return;
+          ctx.log(`Connecting to ${wsUrl.split("?")[0]}`);
+          this.closeEventSocketDirect();
           this._eventSocket = new WebSocket(wsUrl);
           this._eventSocket.onopen = () => {
             this._wsReconnectAttempts = 0;
@@ -6039,7 +6092,11 @@ var CliServerConnection = class _CliServerConnection {
             } catch {
             }
           };
-          this._eventSocket.onclose = () => {
+          this._eventSocket.onclose = (event) => {
+            if (this.isSessionEndedClose(event)) {
+              ctx.log("Event socket closed: session ended", "info");
+              return;
+            }
             if (this._connected) {
               ctx.log("WebSocket closed unexpectedly, scheduling reconnect", "warn");
               this.scheduleWsReconnect();
@@ -6053,6 +6110,7 @@ var CliServerConnection = class _CliServerConnection {
           this.closeEventSocketDirect();
         }
       });
+      this._eventServiceRegistered = true;
       this._backgroundServices.start(serviceName).catch((e) => {
         this._logger?.debug(`Background event service failed for "${this._config.name}", falling back to direct: ${e}`);
         this.connectEventSocketDirect();
@@ -6063,12 +6121,13 @@ var CliServerConnection = class _CliServerConnection {
     }
   }
   connectEventSocketDirect() {
+    void this.connectEventSocketDirectAsync();
+  }
+  async connectEventSocketDirectAsync() {
     try {
-      const baseUrl = this.normalizeUrl(this._config.url);
-      const wsUrl = cliCore.buildAuthenticatedWebSocketUrl(
-        this.toWebSocketUrl(baseUrl) + "/ws/v1/qcli/events",
-        () => this.resolveAuthHeaders()
-      );
+      const wsUrl = await this.buildWebSocketUrl("/ws/v1/qcli/events");
+      if (!this._connected) return;
+      this.closeEventSocketDirect();
       this._eventSocket = new WebSocket(wsUrl);
       this._eventSocket.onopen = () => {
         this._wsReconnectAttempts = 0;
@@ -6086,7 +6145,8 @@ var CliServerConnection = class _CliServerConnection {
         } catch {
         }
       };
-      this._eventSocket.onclose = () => {
+      this._eventSocket.onclose = (event) => {
+        if (this.isSessionEndedClose(event)) return;
         if (this._connected) {
           this.scheduleWsReconnect();
         }
@@ -6097,6 +6157,16 @@ var CliServerConnection = class _CliServerConnection {
       this._logger?.debug(`WebSocket not available for "${this._config.name}": ${e}`);
     }
   }
+  /**
+   * The server closes the event socket with 4401 when the session behind it
+   * ended (logout, revoke, expiry). Retrying with the same credentials cannot
+   * succeed; the auth layer reconnects the server when the session changes.
+   */
+  isSessionEndedClose(event) {
+    if (event?.code !== 4401) return false;
+    this.closeEventSocketDirect();
+    return true;
+  }
   handleServerDisconnect() {
     this._connected = false;
     this._commands = [];
@@ -6307,6 +6377,7 @@ var CliServerProxyProcessor = class _CliServerProxyProcessor {
     this.processors = descriptor.processors?.map(
       (sub) => new _CliServerProxyProcessor(connection, sub, serverName, true, this.commandPath)
     );
+    this.acceptsRawInput = !this.processors?.length;
   }
   async processCommand(command2, context2) {
     return executeOnServer(
@@ -6355,6 +6426,7 @@ var CliServerMultiProxyProcessor = class _CliServerMultiProxyProcessor {
       }).filter((e) => e !== null);
       return new _CliServerMultiProxyProcessor(subEntries, this.provider, this.commandPath);
     });
+    this.acceptsRawInput = !this.processors?.length;
   }
   async processCommand(command2, context2) {
     const defaultServer = this.provider.defaultServer;
@@ -6445,10 +6517,21 @@ var CliServerManager = class {
     this.authService = authService;
     this.connections = /* @__PURE__ */ new Map();
     this._defaultServer = null;
+    /** Bare-name aliases this manager registered (only these are ever removed) */
+    this._bareAliases = /* @__PURE__ */ new Set();
   }
   get defaultServer() {
     return this._defaultServer;
   }
+  preferredServer() {
+    if (this._defaultServer && this.connections.get(this._defaultServer)?.connected) {
+      return this._defaultServer;
+    }
+    for (const [name, connection] of this.connections) {
+      if (connection.connected) return name;
+    }
+    return null;
+  }
   setDefaultServer(name) {
     if (name !== null && !this.connections.has(name)) {
       throw new Error(`Unknown server: ${name}`);
@@ -6511,6 +6594,7 @@ var CliServerManager = class {
     await connection.connect();
     if (connection.connected) {
       this.registerProxyProcessors(connection, name);
+      this.unregisterBareAliases();
       this.registerBareAliases();
       return { success: true, commandCount: connection.commands.length };
     }
@@ -6541,11 +6625,12 @@ var CliServerManager = class {
     this.registerBareAliases();
   }
   unregisterBareAliases() {
-    for (const p of [...this.registry.processors]) {
-      if (p.metadata?.module === "server:multi" || p.metadata?.requireServer && !p.command.includes(":")) {
+    for (const p of this._bareAliases) {
+      if (this.registry.processors.includes(p)) {
         this.registry.unregisterProcessor(p);
       }
     }
+    this._bareAliases.clear();
   }
   registerProxyProcessors(connection, serverName) {
     for (const descriptor of connection.commands) {
@@ -6569,7 +6654,7 @@ var CliServerManager = class {
     }
     for (const [command2, servers] of commandCounts) {
       const existingProcessor = this.registry.findProcessor(command2, []);
-      if (existingProcessor && !existingProcessor.metadata?.requireServer)
+      if (existingProcessor && !this._bareAliases.has(existingProcessor))
         continue;
       if (servers.length === 1) {
         const serverName = servers[0];
@@ -6591,6 +6676,7 @@ var CliServerManager = class {
         alias.command = command2;
         alias.aliases = [namespacedCommand];
         this.registry.registerProcessor(alias);
+        this._bareAliases.add(alias);
       } else {
         const entries = servers.map((serverName) => {
           const connection = this.connections.get(serverName);
@@ -6601,6 +6687,7 @@ var CliServerManager = class {
         });
         const multi = new CliServerMultiProxyProcessor(entries, this);
         this.registry.registerProcessor(multi);
+        this._bareAliases.add(multi);
       }
     }
   }
@@ -6746,6 +6833,28 @@ var WASM_SEARCH_PATHS = [
   "./assets/wasm/qodalis_cli_wasm_bg.wasm",
   "/wasm/qodalis_cli_wasm_bg.wasm"
 ];
+function wasmCandidates(wasmUrl, baseUri) {
+  const baseUrl = (typeof document !== "undefined" ? document.baseURI : void 0);
+  let base;
+  try {
+    base = baseUrl ? new URL(baseUrl) : void 0;
+  } catch {
+    base = void 0;
+  }
+  const resolve = (url) => {
+    if (!base) return url;
+    try {
+      return new URL(url, base).href;
+    } catch {
+      return url;
+    }
+  };
+  const candidates = [];
+  if (wasmUrl) candidates.push(resolve(wasmUrl));
+  if (base) candidates.push(resolve("assets/wasm/qodalis_cli_wasm_bg.wasm"));
+  candidates.push(...WASM_SEARCH_PATHS.map(resolve));
+  return [...new Set(candidates)];
+}
 var wasm;
 var cachedDataViewMemory0 = null;
 var cachedInt32ArrayMemory0 = null;
@@ -6974,7 +7083,7 @@ async function initWasmAccelerator(wasmUrl) {
     return accelerator;
   }
   try {
-    const paths = wasmUrl ? [wasmUrl, ...WASM_SEARCH_PATHS] : WASM_SEARCH_PATHS;
+    const paths = wasmCandidates(wasmUrl);
     const bytes = await fetchWasmBinary(paths);
     await instantiateWasm(bytes);
     accelerator = createWasmAccelerator();
@@ -8710,7 +8819,9 @@ var CliServicesCommandProcessor = class {
     this.metadata = {
       sealed: true,
       icon: "\u2699",
-      module: "system"
+      module: "system",
+      // Enforced only when an auth module is loaded
+      requiredPermissions: ["system:services"]
     };
     this.processors = [
       // ── list ──────────────────────────────────────────────
@@ -11426,8 +11537,6 @@ var CliBackgroundServiceRegistry = class {
     }
   }
 };
-
-// src/lib/services/cli-http-client.ts
 var CliHttpClient = class {
   constructor(signal) {
     this.signal = signal;
@@ -11477,17 +11586,15 @@ var CliHttpClient = class {
   // ── Internals ────────────────────────────────────────────────────
   async jsonRequest(method, url, body, options) {
     const { timeout, ...fetchOptions } = options ?? {};
-    const headers = {
-      ...fetchOptions.headers ?? {}
-    };
+    const headers = new Headers(fetchOptions.headers);
     let resolvedBody;
     if (body !== void 0 && body !== null) {
       if (this.isRawBody(body)) {
         resolvedBody = body;
       } else {
         resolvedBody = JSON.stringify(body);
-        if (!headers["Content-Type"]) {
-          headers["Content-Type"] = "application/json";
+        if (!headers.has("Content-Type")) {
+          headers.set("Content-Type", "application/json");
         }
       }
     }
@@ -11511,16 +11618,23 @@ var CliHttpClient = class {
       });
       if (!response.ok) {
         let errorMessage = `${response.status} ${response.statusText}`;
+        let errorBody;
         try {
-          const errorBody = await response.json();
-          if (errorBody.error) {
-            errorMessage = errorBody.error;
-          } else if (errorBody.message) {
-            errorMessage = errorBody.message;
+          errorBody = await response.json();
+          const parsed = errorBody;
+          if (parsed.error) {
+            errorMessage = parsed.error;
+          } else if (parsed.message) {
+            errorMessage = parsed.message;
           }
         } catch {
         }
-        throw new Error(errorMessage);
+        throw new cliCore.CliHttpError(
+          errorMessage,
+          response.status,
+          response.statusText,
+          errorBody
+        );
       }
       const text = await response.text();
       if (!text) {
@@ -14553,7 +14667,7 @@ var CliTerminalLineRenderer = class {
    */
   getPromptString(options) {
     const name = options.userName ?? "";
-    let promptStart = options.hideUserName || !name ? "" : `\x1B[32m${name}\x1B[0m:`;
+    let promptStart = options.hideUserName ? "" : name ? `\x1B[32m${name}\x1B[0m:` : options.anonymousName ? `\x1B[90m${options.anonymousName}\x1B[0m:` : "";
     if (options.contextProcessor) {
       promptStart = `${options.contextProcessor}`;
     }
@@ -14866,9 +14980,11 @@ var CliExecutionContext = class {
   getPromptOptions() {
     const usersConfig = this.services.get("cli-users-module-config");
     const hideUserName = usersConfig?.hideUserName ?? false;
+    const anonymousName = usersConfig && !this.userSession ? (usersConfig.anonymousName ?? "anonymous") || void 0 : void 0;
     return {
       userName: this.userSession?.displayName,
       hideUserName,
+      anonymousName,
       contextProcessor: this.contextProcessor?.command,
       pathProvider: this.promptPathProvider
     };
@@ -15479,7 +15595,7 @@ var CliCommandExecutor = class {
     }
     if (!processor) {
       const aliasProcessor = this.registry.findProcessor("alias", []);
-      const aliases = aliasProcessor?.userAliases ?? {};
+      const aliases = aliasProcessor?.aliasesFor?.(context2) ?? aliasProcessor?.userAliases ?? {};
       if (aliases[mainCommand]) {
         this.completeProcess(processEntry, context2, 0);
         return await this.executeSingleCommand(
@@ -15536,13 +15652,21 @@ var CliCommandExecutor = class {
     }
     const value = processor.acceptsRawInput || processor.valueRequired ? cliCore.getRightOfWord(commandName, processor.command) : void 0;
     commandToProcess.value = value;
+    const blockedBy = await this.runGuards(commandToProcess, processor, context2);
+    if (blockedBy) {
+      context2.writer.writeError(blockedBy);
+      this.failProcess(processEntry, context2);
+      context2.process.exit(-1, { silent: true });
+      return;
+    }
     const hasPositionalInput = !!value || !!data;
     const hasNamedArgs = Object.keys(args).length > 0;
     if (processor.valueRequired && !hasPositionalInput && !hasNamedArgs) {
       context2.writer.writeError(
         `Value required: ${context2.writer.wrapInColor(`${commandName} <value>`, cliCore.CliForegroundColor.Cyan)}`
       );
-      context2.process.exit(-1);
+      this.failProcess(processEntry, context2);
+      context2.process.exit(-1, { silent: true });
       return;
     }
     if (!this.validateBeforeExecution(context2, processor, args, hasPositionalInput)) {
@@ -15558,7 +15682,8 @@ var CliCommandExecutor = class {
         context2.writer.writeError(
           validationResult?.message || "An error occurred while validating the command."
         );
-        context2.process.exit(-1);
+        this.failProcess(processEntry, context2);
+        context2.process.exit(-1, { silent: true });
         return;
       }
     }
@@ -15622,6 +15747,10 @@ var CliCommandExecutor = class {
             "Process exited successfully with code 0"
           );
         }
+      } else if (cliCore.isCliAccessDeniedError(e)) {
+        this.failProcess(processEntry, context2);
+        context2.writer.writeError(e.message);
+        context2.process.exit(-1);
       } else {
         this.failProcess(processEntry, context2);
         context2.writer.writeError(`Error executing command: ${e}`);
@@ -15706,6 +15835,52 @@ var CliCommandExecutor = class {
    * parameter.  In that case the global handler must be skipped so the
    * processor can handle the flag itself.
    */
+  /**
+   * Runs all registered {@link ICliCommandGuard}s that apply to this command,
+   * in priority order. Returns the block message of the first guard that
+   * denies the command, or `undefined` when every guard allows it.
+   * A guard that throws is treated as a denial (fail closed).
+   */
+  async runGuards(command2, processor, context2) {
+    let guards;
+    try {
+      guards = context2.services.getAll(cliCore.ICliCommandGuard_TOKEN);
+    } catch {
+      return void 0;
+    }
+    if (!guards.length) {
+      return void 0;
+    }
+    const ordered = [...guards].sort(
+      (a, b) => (a.priority ?? 0) - (b.priority ?? 0)
+    );
+    for (const guard of ordered) {
+      let result;
+      try {
+        if (guard.appliesTo && !await guard.appliesTo(processor, command2, context2)) {
+          continue;
+        }
+        result = await guard.canActivate(command2, processor, context2);
+      } catch (e) {
+        return `${processor.command}: blocked by guard '${guard.name}' (${e?.message ?? e})`;
+      }
+      const denial = this.guardDenial(result, processor.command);
+      if (denial) {
+        return denial;
+      }
+    }
+    return void 0;
+  }
+  guardDenial(result, commandName) {
+    const denied = `${commandName}: permission denied`;
+    if (result === void 0 || result === true) return void 0;
+    if (result === false) return denied;
+    if (typeof result === "string") return result || denied;
+    if (typeof result === "object" && result !== null) {
+      return result.allowed ? void 0 : result.message || denied;
+    }
+    return void 0;
+  }
   processorOwnsParameter(processor, globalParam) {
     const globalNames = /* @__PURE__ */ new Set([
       globalParam.name,
@@ -16228,6 +16403,18 @@ var CliBoot = class {
     if (module.services && module.services.length > 0) {
       this.services.set(module.services);
     }
+    if (module.guards && module.guards.length > 0) {
+      this.services.set(
+        module.guards.map((guard) => ({
+          provide: cliCore.ICliCommandGuard_TOKEN,
+          useValue: guard,
+          multi: true
+        }))
+      );
+    }
+    if (module.permissions && module.permissions.length > 0) {
+      this.services.get(cliCore.ICliPermissionRegistry_TOKEN)?.register(module.permissions, module.name);
+    }
     if (module.translations) {
       for (const [locale, translations] of Object.entries(module.translations)) {
         context2.translator.addTranslations(locale, translations);
@@ -16275,19 +16462,47 @@ var CliBoot = class {
         this.registry.registerProcessor(processor);
       }
       await this.initializeProcessorsInternal(context2, filtered);
+      this.adoptMergedSubProcessors(filtered);
     }
     this.bootedModules.add(module.name);
     if (!this.moduleRegistry.has(module.name)) {
       this.moduleRegistry.track(module);
     }
   }
+  /**
+   * Sub-processors of an `extendsProcessor` processor are merged into the
+   * processor it extends, so they belong to that one: re-parent them so they
+   * inherit its access rules (`requiredPermissions` etc.) and help/root
+   * lookups resolve to the registered processor.
+   */
+  adoptMergedSubProcessors(processors) {
+    for (const processor of processors) {
+      if (!processor.extendsProcessor) continue;
+      const name = processor.command.toLowerCase();
+      const host = this.registry.processors.find(
+        (p) => p.command.toLowerCase() === name
+      );
+      if (!host || host === processor) continue;
+      for (const sub of processor.processors ?? []) {
+        if (host.processors?.includes(sub)) {
+          sub.parent = host;
+        }
+      }
+    }
+  }
   buildCoreModule() {
     return {
       apiVersion: API_VERSION,
       name: "@qodalis/cli-core",
       version: cliCore.LIBRARY_VERSION,
       description: "Core CLI services and utilities",
-      processors: [...builtinProcessors]
+      processors: [...builtinProcessors],
+      permissions: [
+        { name: "system:packages", description: "Install, update and remove packages (pkg)" },
+        { name: "system:services", description: "Start and stop background services" },
+        { name: "system:eval", description: "Evaluate JavaScript (eval, also requires allowEval)" },
+        { name: "shell:execute", description: "Open a remote shell on a server (ssh)" }
+      ]
     };
   }
   /**
@@ -16419,6 +16634,29 @@ var CliDragDropService = class {
   }
 };
 
+// src/lib/services/cli-permission-registry.ts
+var CliPermissionRegistry = class {
+  constructor() {
+    this.definitions = /* @__PURE__ */ new Map();
+  }
+  register(definitions, module) {
+    for (const def of definitions ?? []) {
+      const name = def?.name?.trim();
+      if (!name) continue;
+      const key = name.toLowerCase();
+      if (!this.definitions.has(key)) {
+        this.definitions.set(key, { ...def, name, module: def.module ?? module });
+      }
+    }
+  }
+  list() {
+    return [...this.definitions.values()].sort((a, b) => a.name.localeCompare(b.name));
+  }
+  get(name) {
+    return this.definitions.get(name.trim().toLowerCase());
+  }
+};
+
 // src/lib/addons/overlay.ts
 var OverlayAddon = class {
   constructor() {
@@ -16720,6 +16958,22 @@ var CliServerAuthService = class {
     }
     return merged;
   }
+  async getWebSocketParams(serverName) {
+    const providers = this.services.getAll(
+      cliCore.ICliServerAuthTokenProvider_TOKEN
+    );
+    let handled = false;
+    const merged = {};
+    for (const provider of providers) {
+      if (!provider.getWebSocketParams) continue;
+      const params = await provider.getWebSocketParams(serverName);
+      if (params) {
+        handled = true;
+        Object.assign(merged, params);
+      }
+    }
+    return handled ? merged : void 0;
+  }
 };
 
 // src/lib/completion/cli-command-completion-provider.ts
@@ -17237,7 +17491,9 @@ var CliSshCommandProcessor = class {
     this.valueRequired = false;
     this.metadata = {
       module: "@qodalis/cli-server",
-      icon: "\u{1F5A5}"
+      icon: "\u{1F5A5}",
+      // Enforced only when an auth module is loaded; the server checks it too
+      requiredPermissions: [cliCore.CliServerPermissions.ShellExecute]
     };
     this.parameters = [
       {
@@ -17247,9 +17503,6 @@ var CliSshCommandProcessor = class {
         type: "string"
       }
     ];
-    this.socket = null;
-    this.context = null;
-    this.resolved = false;
   }
   async processCommand(command2, context2) {
     const manager = context2.services.getRequired(
@@ -17281,26 +17534,34 @@ var CliSshCommandProcessor = class {
       await this.executeInteractive(connection, serverName, context2);
     }
   }
-  async onData(data, context2) {
-    if (this.socket?.readyState === WebSocket.OPEN) {
-      const msg = { type: "stdin", data };
-      this.socket.send(JSON.stringify(msg));
-    }
-  }
-  onResize(cols, rows, _context) {
-    if (this.socket?.readyState === WebSocket.OPEN) {
-      const msg = { type: "resize", cols, rows };
-      this.socket.send(JSON.stringify(msg));
-    }
-  }
-  onDispose(_context) {
-    if (this.socket) {
-      if (this.socket.readyState === WebSocket.OPEN || this.socket.readyState === WebSocket.CONNECTING) {
-        this.socket.close();
+  /**
+   * Full-screen handler for one session: input, resize and disposal go to
+   * that session's socket only.
+   */
+  fullScreenHandler(session) {
+    const handler = Object.create(this);
+    handler.onData = async (data) => {
+      if (session.socket?.readyState === WebSocket.OPEN) {
+        const msg = { type: "stdin", data };
+        session.socket.send(JSON.stringify(msg));
       }
-      this.socket = null;
-    }
-    this.context = null;
+    };
+    handler.onResize = (cols, rows) => {
+      if (session.socket?.readyState === WebSocket.OPEN) {
+        const msg = { type: "resize", cols, rows };
+        session.socket.send(JSON.stringify(msg));
+      }
+    };
+    handler.onDispose = () => {
+      session.disposed = true;
+      if (session.socket) {
+        if (session.socket.readyState === WebSocket.OPEN || session.socket.readyState === WebSocket.CONNECTING) {
+          session.socket.close();
+        }
+        session.socket = null;
+      }
+    };
+    return handler;
   }
   async resolveServer(command2, shellServers, context2) {
     const empty = { serverName: null, oneShotCmd: null, connection: null };
@@ -17326,7 +17587,7 @@ var CliSshCommandProcessor = class {
       const candidateName = parts[0];
       const entry2 = shellServers.find((s) => s.name === candidateName);
       if (entry2) {
-        const oneShotCmd = parts.slice(1).join(" ") || null;
+        const oneShotCmd = this.remoteCommandFromRaw(command2.rawCommand, candidateName) ?? (parts.slice(1).join(" ") || null);
         return {
           serverName: candidateName,
           oneShotCmd,
@@ -17380,41 +17641,57 @@ var CliSshCommandProcessor = class {
     };
   }
   async executeInteractive(connection, serverName, context2) {
-    this.context = context2;
+    const session = { socket: null, resolved: false, disposed: false };
     const cols = context2.terminal.cols;
     const rows = context2.terminal.rows;
-    const wsUrl = this.buildShellUrl(connection, cols, rows);
+    const wsUrl = await this.buildShellUrl(connection, cols, rows);
     context2.spinner?.show(`Connecting to ${serverName}...`);
-    this.resolved = false;
+    let fullScreen = false;
     return new Promise((resolve) => {
+      const signal = context2.signal;
       const resolveOnce = () => {
-        if (!this.resolved) {
-          this.resolved = true;
+        signal?.removeEventListener("abort", onAbort);
+        if (!session.resolved) {
+          session.resolved = true;
           resolve();
         }
       };
+      const onAbort = () => {
+        context2.spinner?.hide();
+        this.cleanup(session);
+        if (fullScreen) context2.exitFullScreenMode();
+        context2.process.exit(130, { silent: true });
+        resolveOnce();
+      };
+      if (signal?.aborted) {
+        onAbort();
+        return;
+      }
+      signal?.addEventListener("abort", onAbort, { once: true });
       try {
-        this.socket = new WebSocket(wsUrl);
+        session.socket = new WebSocket(wsUrl);
       } catch (e) {
         context2.spinner?.hide();
         context2.writer.writeError(
           `Failed to connect to '${serverName}': ${e.message}`
         );
-        context2.process.exit(1);
+        context2.process.exit(1, { silent: true });
         resolveOnce();
         return;
       }
-      this.socket.onopen = () => {
+      session.socket.onopen = () => {
       };
-      this.socket.onmessage = (event) => {
-        const msg = JSON.parse(event.data);
+      session.socket.onmessage = (event) => {
+        const msg = parseShellMessage(event.data);
+        if (!msg) return;
         switch (msg.type) {
           case "ready":
             context2.spinner?.hide();
             context2.writer.writeInfo(
               `Connected to ${serverName} (${msg.os}, ${msg.shell})`
             );
-            context2.enterFullScreenMode(this);
+            context2.enterFullScreenMode(this.fullScreenHandler(session));
+            fullScreen = true;
             context2.terminal.write("\x1B[2J\x1B[H\x1B[?25h");
             break;
           case "stdout":
@@ -17424,70 +17701,82 @@ var CliSshCommandProcessor = class {
             context2.terminal.write(msg.data);
             break;
           case "exit":
-            context2.exitFullScreenMode();
+            if (fullScreen) context2.exitFullScreenMode();
             context2.writer.writeInfo(
               `Shell exited with code ${msg.code}.`
             );
-            context2.process.exit(msg.code);
-            this.cleanup();
+            context2.process.exit(msg.code, { silent: true });
+            this.cleanup(session);
             resolveOnce();
             break;
           case "error":
             context2.spinner?.hide();
-            context2.exitFullScreenMode();
+            if (fullScreen) context2.exitFullScreenMode();
             context2.writer.writeError(
               `Server error: ${msg.message}`
             );
-            context2.process.exit(1);
-            this.cleanup();
+            context2.process.exit(1, { silent: true });
+            this.cleanup(session);
             resolveOnce();
             break;
         }
       };
-      this.socket.onclose = () => {
+      let errored = false;
+      session.socket.onclose = (event) => {
         context2.spinner?.hide();
-        if (this.context && !this.resolved) {
-          context2.exitFullScreenMode();
-          context2.writer.writeWarning(
-            `Connection to '${serverName}' closed.`
-          );
-          context2.process.exit(1);
+        if (!session.disposed && !session.resolved) {
+          if (fullScreen) context2.exitFullScreenMode();
+          const reason = describeShellClose(event ?? {}, serverName);
+          if (reason) context2.writer.writeError(reason);
+          else if (errored) context2.writer.writeError(`WebSocket error connecting to '${serverName}'.`);
+          else context2.writer.writeWarning(`Connection to '${serverName}' closed.`);
+          context2.process.exit(1, { silent: true });
         }
-        this.cleanup();
+        this.cleanup(session);
         resolveOnce();
       };
-      this.socket.onerror = () => {
-        context2.spinner?.hide();
-        if (!this.resolved) {
-          context2.writer.writeError(
-            `WebSocket error connecting to '${serverName}'.`
-          );
-          context2.process.exit(1);
-        }
-        this.cleanup();
-        resolveOnce();
+      session.socket.onerror = () => {
+        errored = true;
       };
     });
   }
   async executeOneShot(connection, serverName, cmd, context2) {
     const cols = context2.terminal.cols;
     const rows = context2.terminal.rows;
-    const wsUrl = this.buildShellUrl(connection, cols, rows, cmd);
+    const wsUrl = await this.buildShellUrl(connection, cols, rows, cmd);
     context2.spinner?.show(`Running on ${serverName}...`);
-    return new Promise((resolve) => {
+    const session = { socket: null, resolved: false, disposed: false };
+    return new Promise((resolvePromise) => {
+      const signal = context2.signal;
+      const resolve = () => {
+        signal?.removeEventListener("abort", onAbort);
+        resolvePromise();
+      };
+      const onAbort = () => {
+        context2.spinner?.hide();
+        this.cleanup(session);
+        context2.process.exit(130, { silent: true });
+        resolve();
+      };
+      if (signal?.aborted) {
+        onAbort();
+        return;
+      }
+      signal?.addEventListener("abort", onAbort, { once: true });
       try {
-        this.socket = new WebSocket(wsUrl);
+        session.socket = new WebSocket(wsUrl);
       } catch (e) {
         context2.spinner?.hide();
         context2.writer.writeError(
           `Failed to connect to '${serverName}': ${e.message}`
         );
-        context2.process.exit(1);
+        context2.process.exit(1, { silent: true });
         resolve();
         return;
       }
-      this.socket.onmessage = (event) => {
-        const msg = JSON.parse(event.data);
+      session.socket.onmessage = (event) => {
+        const msg = parseShellMessage(event.data);
+        if (!msg) return;
         switch (msg.type) {
           case "ready":
             context2.spinner?.hide();
@@ -17500,9 +17789,9 @@ var CliSshCommandProcessor = class {
             break;
           case "exit":
             if (msg.code !== 0) {
-              context2.process.exit(msg.code);
+              context2.process.exit(msg.code, { silent: true });
             }
-            this.cleanup();
+            this.cleanup(session);
             resolve();
             break;
           case "error":
@@ -17510,53 +17799,82 @@ var CliSshCommandProcessor = class {
             context2.writer.writeError(
               `Server error: ${msg.message}`
             );
-            context2.process.exit(1);
-            this.cleanup();
+            context2.process.exit(1, { silent: true });
+            this.cleanup(session);
             resolve();
             break;
         }
       };
-      this.socket.onclose = () => {
+      let errored = false;
+      session.socket.onclose = (event) => {
         context2.spinner?.hide();
-        this.cleanup();
+        const reason = describeShellClose(event ?? {}, serverName);
+        if (reason || errored) {
+          context2.writer.writeError(reason ?? `WebSocket error connecting to '${serverName}'.`);
+          context2.process.exit(1, { silent: true });
+        }
+        this.cleanup(session);
         resolve();
       };
-      this.socket.onerror = () => {
-        context2.spinner?.hide();
-        context2.writer.writeError(
-          `WebSocket error connecting to '${serverName}'.`
-        );
-        context2.process.exit(1);
-        this.cleanup();
-        resolve();
+      session.socket.onerror = () => {
+        errored = true;
       };
     });
   }
+  /** `ssh <server> <cmd...>` → `<cmd...>` exactly as typed */
+  remoteCommandFromRaw(raw, serverName) {
+    const match = raw?.trim().match(/^\S+\s+(\S+)\s+([\s\S]+)$/);
+    return match && match[1] === serverName ? match[2].trim() : null;
+  }
   buildShellUrl(connection, cols, rows, cmd) {
-    const baseUrl = connection.config.url.endsWith("/") ? connection.config.url.slice(0, -1) : connection.config.url;
-    const wsBase = baseUrl.replace(/^https:/, "wss:").replace(/^http:/, "ws:");
-    let url = `${wsBase}/ws/v1/qcli/shell?cols=${cols}&rows=${rows}`;
+    let path = `/ws/v1/qcli/shell?cols=${cols}&rows=${rows}`;
     if (cmd) {
-      url += `&cmd=${encodeURIComponent(cmd)}`;
+      path += `&cmd=${encodeURIComponent(cmd)}`;
     }
-    return cliCore.buildAuthenticatedWebSocketUrl(
-      url,
-      () => connection.resolveAuthHeaders()
-    );
+    return connection.buildWebSocketUrl(path);
   }
-  cleanup() {
-    if (this.socket) {
-      this.socket.onmessage = null;
-      this.socket.onclose = null;
-      this.socket.onerror = null;
-      if (this.socket.readyState === WebSocket.OPEN || this.socket.readyState === WebSocket.CONNECTING) {
-        this.socket.close();
+  cleanup(session) {
+    const socket = session.socket;
+    if (socket) {
+      socket.onmessage = null;
+      socket.onclose = null;
+      socket.onerror = null;
+      if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+        socket.close();
       }
-      this.socket = null;
+      session.socket = null;
     }
-    this.context = null;
   }
 };
+function parseShellMessage(data) {
+  try {
+    const msg = typeof data === "string" ? JSON.parse(data) : null;
+    return msg && typeof msg === "object" && typeof msg.type === "string" ? msg : null;
+  } catch {
+    return null;
+  }
+}
+function describeShellClose(event, serverName) {
+  const reason = (event.reason ?? "").toLowerCase();
+  switch (event.code) {
+    case 4401:
+      if (reason === "session ended") return `ssh: shell closed by '${serverName}' (session ended or shell access revoked)`;
+      if (reason === "shell access is not configured") {
+        return `ssh: shell access is not configured on '${serverName}'`;
+      }
+      return `ssh: login required on '${serverName}'`;
+    case 4403:
+      return `ssh: permission denied on '${serverName}' (requires shell:execute or a valid shell token)`;
+    case 4404:
+      return `ssh: the shell is disabled on '${serverName}'`;
+    case 4408:
+      return `ssh: shell timed out on '${serverName}'`;
+    case 4429:
+      return `ssh: too many shell sessions on '${serverName}'`;
+    default:
+      return null;
+  }
+}
 
 // src/lib/server/cli-server-module.ts
 function createServerModule() {
@@ -17892,6 +18210,20 @@ async function initializeServices(options) {
       sealed: true
     }
   ]);
+  services.set(
+    cliCore.cliAccessMetadataGuards.map((guard) => ({
+      provide: cliCore.ICliCommandGuard_TOKEN,
+      useValue: guard,
+      multi: true
+    }))
+  );
+  services.set([
+    {
+      provide: cliCore.ICliPermissionRegistry_TOKEN,
+      useValue: new CliPermissionRegistry(),
+      sealed: true
+    }
+  ]);
   const translator = new CliTranslationService();
   services.set([
     { provide: cliCore.ICliTranslationService_TOKEN, useValue: translator, sealed: true }
@@ -17963,7 +18295,7 @@ var CliEngine = class {
    * Initialize the terminal, wire up services, boot modules, and show welcome message.
    */
   async start() {
-    initWasmAccelerator().catch(() => {
+    initWasmAccelerator(this.options?.wasmUrl).catch(() => {
     });
     await waitForLayout(this.container);
     const terminalOpts = getTerminalOptions(this.options?.terminalOptions);
@@ -18257,6 +18589,24 @@ var CliTestHarness = class {
       provide: ICliEnvironment_TOKEN,
       useValue: new CliEnvironment()
     });
+    this.services.set({
+      provide: cliCore.ICliPermissionRegistry_TOKEN,
+      useValue: new CliPermissionRegistry()
+    });
+    this.services.set(
+      cliCore.cliAccessMetadataGuards.map((guard) => ({
+        provide: cliCore.ICliCommandGuard_TOKEN,
+        useValue: guard,
+        multi: true
+      }))
+    );
+  }
+  /**
+   * Resolve `context.userSession` on every command from this function
+   * (e.g. a session service), instead of the value set via setUserSession().
+   */
+  setUserSessionProvider(provider) {
+    this.userSessionProvider = provider;
   }
   /**
    * Register a service in the test container.
@@ -18341,7 +18691,7 @@ var CliTestHarness = class {
       options: void 0,
       logger: createNoopLogger(),
       process,
-      userSession: this.userSession,
+      userSession: this.userSessionProvider ? this.userSessionProvider() : this.userSession,
       state: this.stateStoreManager.getStateStore("shared"),
       backgroundServices: createNoopBackgroundServices(),
       http: new CliHttpClient(),
@@ -18635,6 +18985,7 @@ exports.CliOpenCommandProcessor = CliOpenCommandProcessor;
 exports.CliPackageManagerService = CliPackageManagerService;
 exports.CliPackageManagerService_TOKEN = CliPackageManagerService_TOKEN;
 exports.CliPackagesCommandProcessor = CliPackagesCommandProcessor;
+exports.CliPermissionRegistry = CliPermissionRegistry;
 exports.CliPingCommandProcessor = CliPingCommandProcessor;
 exports.CliProcessRegistry = CliProcessRegistry;
 exports.CliProcessRegistry_TOKEN = CliProcessRegistry_TOKEN;
@@ -18687,6 +19038,7 @@ exports.builtinProcessors = builtinProcessors;
 exports.computeDiff = computeDiff;
 exports.contextGlobalParameter = contextGlobalParameter;
 exports.createServerModule = createServerModule;
+exports.describeShellClose = describeShellClose;
 exports.executeOnServer = executeOnServer;
 exports.expandEnvironmentVars = expandEnvironmentVars;
 exports.formatDiff = formatDiff;