feat(extensions): support archive install sources

Author: kkhomej33-netizen

docs/users/extension/introduction.md

@@ -12,11 +12,11 @@ We offer a suite of extension management tools using both `qwen extensions` CLI
 
 You can manage extensions at runtime within the interactive CLI using `/extensions` slash commands. These commands support hot-reloading, meaning changes take effect immediately without restarting the application.
 
-| Command                               | Description                                                                  |
-| ------------------------------------- | ---------------------------------------------------------------------------- |
-| `/extensions` or `/extensions manage` | Manage all installed extensions                                              |
-| `/extensions install <source>`        | Install an extension from a git URL, local path, npm package, or marketplace |
-| `/extensions explore [source]`        | Open extensions source page(Gemini or ClaudeCode) in your browser            |
+| Command                               | Description                                                                                          |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `/extensions` or `/extensions manage` | Manage all installed extensions                                                                      |
+| `/extensions install <source>`        | Install an extension from a git URL, local path or archive, archive URL, npm package, or marketplace |
+| `/extensions explore [source]`        | Open extensions source page(Gemini or ClaudeCode) in your browser                                    |
 
 ### CLI Extension Management
 
@@ -131,8 +131,26 @@ This will install the github mcp server extension.
 qwen extensions install /path/to/your/extension
 ```
 
+Local `.zip` and `.tar.gz` archives are also supported:
+
+```bash
+qwen extensions install /path/to/your/extension.zip
+qwen extensions install /path/to/your/extension.tar.gz
+```
+
+The archive must contain a complete extension at its root, or a single top-level directory containing the extension.
+
 Note that we create a copy of the installed extension, so you will need to run `qwen extensions update` to pull in changes from both locally-defined extensions and those on GitHub.
 
+#### From Archive URL
+
+```bash
+qwen extensions install https://example.com/your/extension.zip
+qwen extensions install https://example.com/your/extension.tar.gz
+```
+
+Archive URLs can be updated later as long as the URL continues to point at a newer archive for the same extension.
+
 ### Uninstalling an extension
 
 To uninstall, run `qwen extensions uninstall extension-name`, so, in the case of the install example:
@@ -155,7 +173,7 @@ This is useful if you have an extension disabled at the top-level and only enabl
 
 ### Updating an extension
 
-For extensions installed from a local path, a git repository, or an npm registry, you can explicitly update to the latest version with `qwen extensions update extension-name`. For npm extensions installed without a version pin (e.g. `@scope/pkg`), updates check the `latest` dist-tag. For those installed with a specific dist-tag (e.g. `@scope/pkg@beta`), updates track that tag. Extensions pinned to an exact version (e.g. `@scope/pkg@1.2.0`) are always considered up-to-date.
+For extensions installed from a local path or archive, an archive URL, a git repository, or an npm registry, you can explicitly update to the latest version with `qwen extensions update extension-name`. For npm extensions installed without a version pin (e.g. `@scope/pkg`), updates check the `latest` dist-tag. For those installed with a specific dist-tag (e.g. `@scope/pkg@beta`), updates track that tag. Extensions pinned to an exact version (e.g. `@scope/pkg@1.2.0`) are always considered up-to-date.
 
 You can update all extensions with:
 

packages/acp-bridge/src/status.ts

@@ -857,7 +857,8 @@ export type ServeExtensionInstallType =
   | 'local'
   | 'link'
   | 'github-release'
-  | 'npm';
+  | 'npm'
+  | 'archive-url';
 
 export type ServeExtensionOriginSource = 'QwenCode' | 'Claude' | 'Gemini';
 

packages/cli/src/commands/extensions/install.test.ts

@@ -203,6 +203,61 @@ describe('handleInstall', () => {
     processSpy.mockRestore();
   });
 
+  it('should install an extension from an archive URL', async () => {
+    const processSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never);
+
+    mockParseInstallSource.mockResolvedValue({
+      type: 'archive-url',
+      source: 'https://example.com/extension.zip',
+    });
+    mockInstallExtension.mockResolvedValue({ name: 'archive-extension' });
+
+    await handleInstall({
+      source: 'https://example.com/extension.zip',
+      autoUpdate: true,
+    });
+
+    expect(mockInstallExtension).toHaveBeenCalledWith(
+      expect.objectContaining({
+        source: 'https://example.com/extension.zip',
+        type: 'archive-url',
+        autoUpdate: true,
+      }),
+      expect.any(Function),
+    );
+    expect(mockWriteStdoutLine).toHaveBeenCalledWith(
+      'Extension "archive-extension" installed successfully and enabled.',
+    );
+
+    processSpy.mockRestore();
+  });
+
+  it('should reject --ref for archive URL extensions', async () => {
+    const processSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never);
+
+    mockParseInstallSource.mockResolvedValue({
+      type: 'archive-url',
+      source: 'https://example.com/extension.zip',
+    });
+
+    await handleInstall({
+      source: 'https://example.com/extension.zip',
+      ref: 'v1.0.0',
+    });
+
+    expect(mockWriteStderrLine).toHaveBeenCalledWith(
+      '--ref is not applicable for archive URL extensions.',
+    );
+    expect(mockInstallExtension).not.toHaveBeenCalled();
+    expect(processSpy).toHaveBeenCalledWith(1);
+
+    processSpy.mockRestore();
+  });
+
   it('should throw an error if install extension fails', async () => {
     const processSpy = vi
       .spyOn(process, 'exit')
@@ -225,4 +280,29 @@ describe('handleInstall', () => {
 
     processSpy.mockRestore();
   });
+
+  it('should print archive validation errors from the extension manager', async () => {
+    const processSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never);
+
+    mockParseInstallSource.mockResolvedValue({
+      type: 'git',
+      source: 'owner/repo',
+    });
+    mockInstallExtension.mockRejectedValue(
+      new Error(
+        'Extension archive is missing qwen-extension.json. The archive must contain a complete extension at its root, or a single top-level extension directory.',
+      ),
+    );
+
+    await handleInstall({ source: 'owner/repo' });
+
+    expect(mockWriteStderrLine).toHaveBeenCalledWith(
+      'Extension archive is missing qwen-extension.json. The archive must contain a complete extension at its root, or a single top-level extension directory.',
+    );
+    expect(processSpy).toHaveBeenCalledWith(1);
+
+    processSpy.mockRestore();
+  });
 });

packages/cli/src/commands/extensions/install.ts

@@ -37,7 +37,8 @@ export async function handleInstall(args: InstallArgs) {
     if (
       installMetadata.type !== 'git' &&
       installMetadata.type !== 'github-release' &&
-      installMetadata.type !== 'npm'
+      installMetadata.type !== 'npm' &&
+      installMetadata.type !== 'archive-url'
     ) {
       if (args.ref || args.autoUpdate) {
         throw new Error(
@@ -48,10 +49,16 @@ export async function handleInstall(args: InstallArgs) {
       }
     }
 
-    if (installMetadata.type === 'npm' && args.ref) {
+    if (
+      (installMetadata.type === 'npm' ||
+        installMetadata.type === 'archive-url') &&
+      args.ref
+    ) {
       throw new Error(
         t(
-          '--ref is not applicable for npm extensions. Use @version suffix instead (e.g. @scope/package@1.2.0).',
+          installMetadata.type === 'npm'
+            ? '--ref is not applicable for npm extensions. Use @version suffix instead (e.g. @scope/package@1.2.0).'
+            : '--ref is not applicable for archive URL extensions.',
         ),
       );
     }
@@ -101,13 +108,13 @@ export async function handleInstall(args: InstallArgs) {
 export const installCommand: CommandModule = {
   command: 'install <source>',
   describe: t(
-    'Installs an extension from a git repository URL, local path, scoped npm package (@scope/name), or claude marketplace (marketplace-url:plugin-name).',
+    'Installs an extension from a git repository URL, local path or archive, archive URL, scoped npm package (@scope/name), or claude marketplace (marketplace-url:plugin-name).',
   ),
   builder: (yargs) =>
     yargs
       .positional('source', {
         describe: t(
-          'The github URL, local path, or marketplace source (marketplace-url:plugin-name) of the extension to install.',
+          'The github URL, local path or archive, archive URL, or marketplace source (marketplace-url:plugin-name) of the extension to install.',
         ),
         type: 'string',
         demandOption: true,

packages/core/src/config/config.ts

@@ -524,7 +524,7 @@ export type ExtensionOriginSource = 'QwenCode' | 'Claude' | 'Gemini';
 
 export interface ExtensionInstallMetadata {
   source: string;
-  type: 'git' | 'local' | 'link' | 'github-release' | 'npm';
+  type: 'git' | 'local' | 'link' | 'github-release' | 'npm' | 'archive-url';
   originSource?: ExtensionOriginSource;
   releaseTag?: string; // Only present for github-release and npm installs.
   registryUrl?: string; // Only present for npm installs.

packages/core/src/extension/extension-converter.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { EXTENSIONS_CONFIG_FILENAME } from './variables.js';
+import {
+  convertGeminiExtensionPackage,
+  isGeminiExtensionConfig,
+} from './gemini-converter.js';
+import { convertClaudePluginPackage } from './claude-converter.js';
+import type { ExtensionOriginSource } from '../config/config.js';
+
+export async function convertGeminiOrClaudeExtension(
+  extensionDir: string,
+  pluginName?: string,
+): Promise<{ extensionDir: string; originSource: ExtensionOriginSource }> {
+  let newExtensionDir = extensionDir;
+  let originSource: ExtensionOriginSource = 'QwenCode';
+  const configFilePath = path.join(extensionDir, EXTENSIONS_CONFIG_FILENAME);
+  if (fs.existsSync(configFilePath)) {
+    newExtensionDir = extensionDir;
+  } else if (isGeminiExtensionConfig(extensionDir)) {
+    newExtensionDir = (await convertGeminiExtensionPackage(extensionDir))
+      .convertedDir;
+    originSource = 'Gemini';
+  } else if (pluginName) {
+    newExtensionDir = (
+      await convertClaudePluginPackage(extensionDir, pluginName)
+    ).convertedDir;
+    originSource = 'Claude';
+  }
+  return { extensionDir: newExtensionDir, originSource };
+}