Support declarative extension contributions

Author: mehmetozguldev

CONTRIBUTING.md

@@ -21,7 +21,7 @@ manifests.json          # Combined manifests (auto-generated, do not edit manual
 scripts/                # Validation and generation scripts
 ```
 
-- `extension.json` defines the extension manifest (category, capabilities, tool references)
+- `extension.json` defines the extension manifest (category, contributions, capabilities, tool references)
 - `tooling.json` (optional) defines pre-built platform-specific binaries distributed as tarballs
 - Not every extension has a `tooling.json`. Extensions without one rely on runtime-installed tools
 
@@ -40,18 +40,25 @@ scripts/                # Validation and generation scripts
   "version": "1.0.0",
   "description": "MyLang language support with LSP",
   "publisher": "Athas",
+  "engines": {
+    "athas": ">=0.7.0"
+  },
   "categories": ["Language"],
-  "languages": [
-    {
-      "id": "mylang",
-      "extensions": [".ml"],
-      "aliases": ["MyLang"]
-    }
-  ]
+  "contributes": {
+    "languages": [
+      {
+        "id": "mylang",
+        "extensions": [".ml"],
+        "filenames": ["MyLangfile"],
+        "filenamePatterns": ["*.mylang.json"],
+        "aliases": ["MyLang"]
+      }
+    ]
+  }
 }
 ```
 
-3. Add capability entries in `capabilities` only for tooling provided by the extension (`lsp`, `formatter`, `linter`, snippets/commands as needed).
+3. Add capability entries in `capabilities` only for tooling provided by the extension (`lsp`, `formatter`, `linter`, grammar assets as needed). Snippets, commands, themes, icon themes, agents, database providers, and keybindings should be declared under `contributes`.
 
 4. Regenerate generated files:
    ```bash
@@ -75,6 +82,38 @@ scripts/                # Validation and generation scripts
 | `version` | string | Semver version |
 | `categories` | string[] | Extension categories (`Language`, `Theme`, `Snippets`, `Keymaps`, etc.) |
 
+### Contributions
+
+New manifests should prefer the declarative `contributes` model:
+
+```json
+"contributes": {
+  "languages": [],
+  "snippets": [],
+  "themes": [],
+  "iconThemes": [],
+  "databaseProviders": [],
+  "agents": [],
+  "commands": [],
+  "keybindings": []
+}
+```
+
+Top-level arrays such as `languages`, `themes`, `iconThemes`, `agents`, and `databaseProviders`
+are still supported for existing manifests. Validation, catalog generation, theme/icon packaging,
+and database sidecar packaging read both forms.
+
+Language contributions can match by file extension, exact filename, or filename pattern:
+
+```json
+{
+  "id": "jsonc",
+  "extensions": [".jsonc"],
+  "filenames": ["tsconfig.json", "jsconfig.json"],
+  "filenamePatterns": ["tsconfig.*.json", "jsconfig.*.json"]
+}
+```
+
 ### Categories
 
 - `Language` - Language tooling support (LSP, formatter, linter, snippets, commands)
@@ -101,7 +140,7 @@ scripts/                # Validation and generation scripts
 
 Use `packages` for runtime-managed companion packages that must be installed beside the primary package, such as TypeScript SDK packages required by JavaScript-based language servers.
 
-Supported runtimes: `bun`, `node`, `python`, `go`, `rust`, `ruby`, `binary`
+Supported runtimes: `bun`, `node`, `python`, `go`, `rust`, `binary`
 
 #### Formatter
 

README.md

@@ -5,6 +5,10 @@ Extensions for the [Athas](https://athas.dev) editor.
 Syntax highlighting is now bundled in Athas core by default. This repository focuses on
 language tooling extensions (LSP, formatter, linter, snippets), plus themes and icon themes.
 
+Extension manifests are declarative. New manifests should prefer the
+`contributes` shape for editor contributions, while managed runtime tooling stays under
+`capabilities`. Existing top-level contribution fields are still supported.
+
 ## Structure
 
 Language extensions can live under `extensions/{name}/`. Marketplace contribution
@@ -31,6 +35,46 @@ Root-level files:
 - `registry.json` / `index.json` - Extension registry for the marketplace
 - `manifests.json` - Combined manifests (auto-generated, do not edit manually)
 
+## Manifest Shape
+
+```json
+{
+  "$schema": "https://athas.dev/schemas/extension.json",
+  "id": "athas.mylang",
+  "name": "MyLang",
+  "displayName": "MyLang",
+  "version": "1.0.0",
+  "publisher": "Athas",
+  "categories": ["Language"],
+  "engines": {
+    "athas": ">=0.7.0"
+  },
+  "contributes": {
+    "languages": [
+      {
+        "id": "mylang",
+        "extensions": [".ml"],
+        "filenames": ["MyLangfile"],
+        "filenamePatterns": ["*.mylang.json"],
+        "aliases": ["MyLang"]
+      }
+    ]
+  },
+  "capabilities": {
+    "lsp": {
+      "name": "mylang-language-server",
+      "runtime": "node",
+      "package": "mylang-language-server",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+Supported contribution arrays include `languages`, `snippets`, `themes`, `iconThemes`,
+`databaseProviders`, `agents`, `commands`, and `keybindings`. The validation and catalog
+scripts read both top-level arrays and `contributes.*`.
+
 ## Scripts
 
 ```bash

scripts/build-extensions-index.ts

@@ -11,7 +11,7 @@ type ExternalLanguageManifest = {
   categories?: string[];
   languages?: Array<{
     id: string;
-    extensions: string[];
+    extensions?: string[];
   }>;
   databaseProviders?: Array<{
     id: string;
@@ -25,6 +25,24 @@ type ExternalLanguageManifest = {
   iconThemes?: Array<{
     id: string;
   }>;
+  contributes?: {
+    languages?: Array<{
+      id: string;
+      extensions?: string[];
+    }>;
+    databaseProviders?: Array<{
+      id: string;
+    }>;
+    agents?: Array<{
+      id: string;
+    }>;
+    themes?: Array<{
+      id: string;
+    }>;
+    iconThemes?: Array<{
+      id: string;
+    }>;
+  };
   installation?: {
     size?: number;
     platformArch?: Record<string, { size?: number }>;
@@ -106,6 +124,16 @@ function resolveInstallSize(manifest: ExternalLanguageManifest): number | undefi
   return typeof size === "number" && size > 0 ? size : undefined;
 }
 
+function getManifestContributions<K extends keyof NonNullable<ExternalLanguageManifest["contributes"]>>(
+  manifest: ExternalLanguageManifest,
+  key: K,
+): NonNullable<ExternalLanguageManifest["contributes"]>[K] {
+  return [
+    ...(((manifest as Record<string, unknown>)[key] as unknown[]) || []),
+    ...((manifest.contributes?.[key] as unknown[]) || []),
+  ] as NonNullable<ExternalLanguageManifest["contributes"]>[K];
+}
+
 function withTrailingNewline(json: unknown): string {
   return `${JSON.stringify(json, null, 2)}\n`;
 }
@@ -146,11 +174,11 @@ async function buildCatalog() {
       throw new Error(`Missing id in ${manifestPath}`);
     }
 
-    const languages = manifest.languages ?? [];
-    const databaseProviders = manifest.databaseProviders ?? [];
-    const agents = manifest.agents ?? [];
-    const themes = manifest.themes ?? [];
-    const iconThemes = manifest.iconThemes ?? [];
+    const languages = getManifestContributions(manifest, "languages") ?? [];
+    const databaseProviders = getManifestContributions(manifest, "databaseProviders") ?? [];
+    const agents = getManifestContributions(manifest, "agents") ?? [];
+    const themes = getManifestContributions(manifest, "themes") ?? [];
+    const iconThemes = getManifestContributions(manifest, "iconThemes") ?? [];
     if (
       languages.length === 0 &&
       databaseProviders.length === 0 &&

scripts/package-database-sidecars.ts

@@ -43,6 +43,25 @@ function hasCompletePackageInfo(value: unknown): value is Record<string, unknown
   );
 }
 
+function getContributionArray(
+  manifest: Record<string, unknown>,
+  key: string,
+): Array<Record<string, unknown>> {
+  const contributes =
+    typeof manifest.contributes === "object" &&
+    manifest.contributes !== null &&
+    !Array.isArray(manifest.contributes)
+      ? (manifest.contributes as Record<string, unknown>)
+      : {};
+
+  return [
+    ...(Array.isArray(manifest[key]) ? (manifest[key] as Array<Record<string, unknown>>) : []),
+    ...(Array.isArray(contributes[key])
+      ? (contributes[key] as Array<Record<string, unknown>>)
+      : []),
+  ];
+}
+
 async function createPackage(params: {
   extensionDir: string;
   manifest: Record<string, unknown>;
@@ -91,7 +110,7 @@ for (const folder of databaseFolders) {
   const extensionDir = join(extensionsDir, "database", folder);
   const manifestPath = join(extensionDir, "extension.json");
   const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
-  const provider = (manifest.databaseProviders as Array<Record<string, unknown>> | undefined)?.[0];
+  const provider = getContributionArray(manifest, "databaseProviders")[0];
   const sidecar = provider?.sidecar as Record<string, string> | undefined;
   const sidecarPath = sidecar?.[platformArch];
 

scripts/package-extensions.ts

@@ -11,6 +11,19 @@ const extensionsDir = join(root, "extensions");
 const packagesDir = join(root, "packages");
 const cdnBaseUrl = process.env.EXTENSIONS_CDN_BASE_URL || "https://athas.dev/extensions";
 
+function contributionCount(manifest: Record<string, unknown>, key: string): number {
+  const contributes =
+    typeof manifest.contributes === "object" &&
+    manifest.contributes !== null &&
+    !Array.isArray(manifest.contributes)
+      ? (manifest.contributes as Record<string, unknown>)
+      : {};
+
+  const topLevel = Array.isArray(manifest[key]) ? manifest[key].length : 0;
+  const contributed = Array.isArray(contributes[key]) ? contributes[key].length : 0;
+  return topLevel + contributed;
+}
+
 async function collectExtensionFolders(directory: string, folders: string[] = []) {
   const entries = await readdir(directory, { withFileTypes: true });
 
@@ -29,12 +42,10 @@ async function collectExtensionFolders(directory: string, folders: string[] = []
 }
 
 function shouldPackage(manifest: Record<string, unknown>) {
-  const hasNativeSidecar =
-    Array.isArray(manifest.databaseProviders) && manifest.databaseProviders.length > 0;
-  const isLanguage = Array.isArray(manifest.languages) && manifest.languages.length > 0;
+  const hasNativeSidecar = contributionCount(manifest, "databaseProviders") > 0;
+  const isLanguage = contributionCount(manifest, "languages") > 0;
   const isPureAssetExtension =
-    (Array.isArray(manifest.themes) && manifest.themes.length > 0) ||
-    (Array.isArray(manifest.iconThemes) && manifest.iconThemes.length > 0);
+    contributionCount(manifest, "themes") > 0 || contributionCount(manifest, "iconThemes") > 0;
 
   return isPureAssetExtension && !hasNativeSidecar && !isLanguage;
 }