@stacksjs/defaults 0.75.41 → 0.75.42

package/ide/vscode/README.md

@@ -1,8 +1,31 @@
 # Stacks for VS Code
 
-Build a Stacks app without leaving the editor. Start the dev server, preview it in VS Code's built-in Simple Browser, and run any `buddy` command from the Command Palette. The extension also installs a small pack of extensions that Stacks projects are configured for.
+Everything a Stacks project needs in the editor, in one extension: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every `buddy` command. It installs no other extensions and works without any.
 
-The extension activates in workspaces that contain a `buddy` file or a `config/app.ts`.
+The Stacks commands, pickier and the env features activate in workspaces that contain a `buddy` file or a `config/app.ts`. stx support also starts for any `.stx` file.
+
+## stx templates
+
+`.stx` files get the full stx language support: highlighting, completions for directives, components and props, hovers, diagnostics, go to definition, folding, semantic highlighting, snippets, and previews of utility classes with their colors.
+
+It is the same code as the standalone [stx extension](https://marketplace.visualstudio.com/items?itemName=Stacks.vscode-stx) (`Stacks.vscode-stx`), built in from `@stacksjs/stx-vscode`. You do not need that extension; if you have both, it stands down so nothing is registered twice.
+
+## Pickier
+
+Files `./buddy lint` checks (`.ts`, `.js`, `.json`, `.md`, `.yaml`) are linted as you type, with the project's own pickier and its config (`config/code-style.ts`, `pickier.config.ts` or `.config/pickier.ts`), so the editor and `./buddy lint` always agree. Pickier runs in a Bun process per project, on the project's `pantry/.bin/bun` when it has one.
+
+- **Format Document** formats with pickier when the extension is the formatter: `"editor.defaultFormatter": "Stacks.vscode-stacks"`, which new projects already set.
+- **Fix all**: the `source.fixAll.pickier` code action applies every fix `./buddy lint --fix` would. New projects run it on save through `"editor.codeActionsOnSave": { "source.fixAll.pickier": "explicit" }`. It needs pickier 0.1.66 or later.
+- **Quick fixes** on a pickier problem: fix all, or `// pickier-disable-next-line <rule>` for that line.
+
+## Env files
+
+- **Hover** an `encrypted:` value to see it decrypted, with the same code and keys `./buddy env:get` uses: `DOTENV_PRIVATE_KEY_<ENV>` or `DOTENV_PRIVATE_KEY`, from `.env.keys` or the environment. The value is only shown; it is never cached, logged or written anywhere.
+- **Missing keys**: keys `.env.example` declares that `.env` does not set are flagged in `.env`.
+- **Commands** run the project's `./buddy env:*` directly, without a shell, so a value you set does not end up in your shell history. They act on the env file that is open, or `.env`.
+- The **preview** decrypts an encrypted `APP_URL` or `PORT` the same way, so it opens the URL `./buddy dev` serves.
+
+VS Code highlights `.env` files itself.
 
 ## Commands
 
@@ -13,6 +36,13 @@ Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and type `Stacks`.
 | **Stacks: Open Preview** | Opens the running dev server in the Simple Browser, beside your editor. If nothing is running, it offers to start the dev server. |
 | **Stacks: Start Dev Server** | Runs `./buddy dev` in a terminal named `Stacks Dev` at the project root. Once the server is up, the preview opens in the Simple Browser. |
 | **Stacks: Run Buddy Command...** | Lists every command `./buddy list` knows, including your own in `app/Commands/`. Pick one, and if it takes arguments you are asked for them. You can also type a full command line, such as `migrate --diff` or `make:model Post`. The command runs in a terminal named `Stacks Buddy`. |
+| **Stacks: Fix All Lint Problems** | Applies pickier's fixes to the open file. |
+| **Stacks: Restart Pickier** | Restarts the pickier process, after changing its config outside the editor or updating pickier. Saving the config in the editor restarts it for you. |
+| **Stacks: Env: Get Value...** | `./buddy env:get`: pick a key, then copy its value. |
+| **Stacks: Env: Set Value...** | `./buddy env:set`: the value is typed into a password box, and encrypted when the file is. |
+| **Stacks: Env: Encrypt File** | `./buddy env:encrypt`. |
+| **Stacks: Env: Decrypt File** | `./buddy env:decrypt`, after a warning: it writes every value to disk in plaintext. |
+| **Stacks: Env: Rotate Keys** | `./buddy env:rotate`, after a warning: deployments holding the old private key can no longer decrypt the file. |
 
 The **Stacks** item in the status bar opens the preview.
 
@@ -39,43 +69,38 @@ The extension checks that the frontend port is accepting connections before it o
 | `stacks.devServer.args` | `[]` | Extra arguments for `./buddy dev`, e.g. `["frontend"]` or `["--site"]`. |
 | `stacks.devServer.openPreview` | `true` | Open the Simple Browser once the dev server is up, instead of letting `buddy dev` open your system browser. |
 | `stacks.statusBar.enabled` | `true` | Show the Stacks status bar item. |
+| `stacks.pickier.enable` | `true` | Lint, format and fix with the project's pickier. |
+| `stacks.pickier.run` | `"onType"` | Lint as you type (`onType`) or only on save (`onSave`). |
+| `stacks.bunPath` | `""` | The Bun that runs pickier. Empty means the project's `pantry/.bin/bun`, then `bun` on the `PATH`. |
+| `stacks.env.decryptOnHover` | `true` | Show encrypted env values decrypted on hover. |
+| `stacks.env.missingKeys` | `true` | Flag keys `.env.example` has that `.env` does not set. |
 
-The extension also sets a few editor defaults for Stacks projects: `.stx` files use HTML language support, the `buddy` script is highlighted as a shell script, `npm.packageManager` is `bun`, Go to Definition prefers source files over `.d.ts`, and TypeScript uses the workspace version.
+The `stx.*` settings (diagnostics, completion, hover, utility classes and so on) are the stx extension's, and work the same here.
 
-## Included extensions
+The extension also sets a few editor defaults for Stacks projects: the `buddy` script is highlighted as a shell script, `npm.packageManager` is `bun`, Go to Definition prefers source files over `.d.ts`, and TypeScript uses the workspace version.
 
-- [Bun for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=oven.bun-vscode) - Bun runtime and test integration
-- [Dotenvx](https://marketplace.visualstudio.com/items?itemName=dotenv.dotenvx-vscode) - encrypted environment file support
-- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - editor integration for the project's lint rules
-- [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) - Markdown linting
-- [shell-format](https://marketplace.visualstudio.com/items?itemName=foxundermoon.shell-format) - shell script and Dockerfile formatting
-- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - spell checking with the Stacks dictionary
-- [Total TypeScript Error Translator](https://marketplace.visualstudio.com/items?itemName=mattpocock.ts-error-translator) - plain-English TypeScript errors
-- [Prettify TypeScript](https://marketplace.visualstudio.com/items?itemName=mylesmurphy.prettify-ts) - readable type hovers
-- [Twoslash Query Comments](https://marketplace.visualstudio.com/items?itemName=Orta.vscode-twoslash-queries) - inline `// ^?` type queries
-- [AWS Toolkit](https://marketplace.visualstudio.com/items?itemName=amazonwebservices.aws-toolkit-vscode) - the AWS resources `buddy deploy` creates
+## No extension pack
 
-Some extensions were dropped from the pack because VS Code now does the same thing itself:
+Earlier versions installed a pack of other extensions. It is gone, and the extension depends on none:
 
-- **Goto Definition Alias**: built-in **Go to Source Definition**, which this extension enables by default.
-- **npm Intellisense**: TypeScript's built-in package import completions.
-- **DotENV**: VS Code's built-in `dotenv` language highlights `.env` and `.env.*` files.
-- **Gremlins**: built-in Unicode highlighting (`editor.unicodeHighlight.*`) flags invisible and confusable characters.
+- **stx Language Support**, **ESLint** and **Dotenvx** are replaced by the built-in stx, pickier and env support above. Stacks lints with pickier, not ESLint.
+- **Bun for Visual Studio Code**, **AWS Toolkit**, **markdownlint**, **shell-format**, **Code Spell Checker**, **Total TypeScript Error Translator**, **Prettify TypeScript** and **Twoslash Query Comments** were dropped. They are general-purpose tools rather than anything Stacks-specific, and markdownlint and shell-format formatted files pickier formats. Install any of them yourself if you want them.
 
 ## Development
 
 ```bash
-bun run build      # bundle src/ into dist/extension.js
-bun test ./tests   # unit tests for URL detection, `buddy list` parsing and the commands
+bun run build      # bundle src/ into dist/ (extension, pickier worker, stx assets)
+bun test ./tests   # unit tests, plus a build that must load as CommonJS on Node
 bun run typecheck
+bun run sync:stx   # after updating @stacksjs/stx-vscode: copy its contributions into package.json
 bun run package    # build and create a .vsix
 code --install-extension vscode-stacks-<version>.vsix
 ```
 
-The extension has no runtime dependencies. It is published automatically by the Stacks release workflow, and `vscode:prepublish` builds `dist/` first.
+The extension has no runtime dependencies: `@stacksjs/stx-vscode` and the env decryption from `core/env` are bundled into `dist/extension.js`. It is published automatically by the Stacks release workflow, and `vscode:prepublish` builds `dist/` first.
 
 ## Relevant links
 
 - [GitHub](https://github.com/stacksjs/stacks)
-- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=stacks.vscode-stacks)
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Stacks.vscode-stacks)
 - [IDE setup guide](https://stacksjs.com/docs/bootcamp/how-to/ide-setup)

package/ide/vscode/build.ts

@@ -0,0 +1,43 @@
+/**
+ * Builds the extension into dist/:
+ *
+ *   extension.js                the extension, for VS Code's Node host; only `vscode` is external
+ *   pickier-worker.js           the Bun process that runs the project's pickier (src/pickier-worker.ts)
+ *   pickier-worker.bunfig.toml  an empty bunfig, so the worker skips the project's preloads
+ *   stx/                        grammar, language configuration and snippets from @stacksjs/stx-vscode
+ *
+ * `vsce package` runs this first (`vscode:prepublish`), and `files` in
+ * package.json ships exactly these.
+ */
+import { cpSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+
+const here = import.meta.dir
+const dist = join(here, 'dist')
+
+rmSync(dist, { recursive: true, force: true })
+mkdirSync(dist, { recursive: true })
+
+const builds = await Promise.all([
+  // bunfig stays out: the stx utility-class engine imports it only to load a
+  // config file, which the extension never asks for, and its module-scope
+  // `await` and `import.meta.require` would make the CommonJS bundle a syntax
+  // error in VS Code's Node host. tests/build.test.ts parses the bundle.
+  Bun.build({ entrypoints: [join(here, 'src/extension.ts')], outdir: dist, target: 'node', format: 'cjs', external: ['vscode', 'bunfig'], minify: true }),
+  Bun.build({ entrypoints: [join(here, 'src/pickier-worker.ts')], outdir: dist, target: 'bun', format: 'esm' }),
+])
+
+for (const build of builds) {
+  if (!build.success) {
+    console.error(build.logs)
+    process.exit(1)
+  }
+}
+
+writeFileSync(join(dist, 'pickier-worker.bunfig.toml'), '# Intentionally empty: the pickier worker must not run the project\'s bunfig preloads.\n')
+
+const stxAssets = join(dirname(Bun.resolveSync('@stacksjs/stx-vscode/contributes.json', here)), 'assets')
+cpSync(stxAssets, join(dist, 'stx'), { recursive: true })
+
+console.log('Built dist/')

package/ide/vscode/package.json

@@ -2,8 +2,8 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.41",
-  "description": "Develop Stacks apps without leaving VS Code: preview the dev server in the Simple Browser, start it, and run any buddy command.",
+  "version": "0.75.42",
+  "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",
   "sponsor": {
@@ -21,23 +21,29 @@
   "keywords": [
     "stacks",
     "stacksjs",
+    "stx",
+    "pickier",
+    "lint",
+    "format",
+    "dotenv",
+    "env",
     "buddy",
     "preview",
-    "simple browser",
-    "dev server",
-    "extension pack"
+    "dev server"
   ],
   "categories": [
-    "Extension Packs",
+    "Programming Languages",
+    "Linters",
+    "Formatters",
     "Other"
   ],
   "icon": "logo.png",
   "main": "./dist/extension.js",
   "files": [
-    ".vscode/extensions.json",
-    ".vscode/settings.json",
-    ".vscode/stacks.code-snippets",
     "dist/extension.js",
+    "dist/pickier-worker.js",
+    "dist/pickier-worker.bunfig.toml",
+    "dist/stx/**",
     "LICENSE.md",
     "README.md",
     "logo.png"
@@ -50,7 +56,8 @@
   ],
   "activationEvents": [
     "workspaceContains:buddy",
-    "workspaceContains:config/app.ts"
+    "workspaceContains:config/app.ts",
+    "onLanguage:stx"
   ],
   "capabilities": {
     "untrustedWorkspaces": {
@@ -60,10 +67,11 @@
     "virtualWorkspaces": false
   },
   "scripts": {
-    "build": "bun build ./src/extension.ts --outdir dist --target node --format cjs --external vscode",
+    "build": "bun build.ts",
     "vscode:prepublish": "bun run build",
     "test": "bun test ./tests",
     "typecheck": "bun x --bun tsc --noEmit -p tsconfig.json",
+    "sync:stx": "bun scripts/stx-contributes.ts --write",
     "package": "bunx --bun vsce package --no-dependencies",
     "release": "bunx --bun vsce publish --no-dependencies"
   },
@@ -90,6 +98,50 @@
         "title": "Run Buddy Command...",
         "category": "Stacks",
         "icon": "$(terminal)"
+      },
+      {
+        "command": "stacks.pickier.fixAll",
+        "title": "Fix All Lint Problems",
+        "category": "Stacks"
+      },
+      {
+        "command": "stacks.pickier.restart",
+        "title": "Restart Pickier",
+        "category": "Stacks"
+      },
+      {
+        "command": "stacks.env.get",
+        "title": "Env: Get Value...",
+        "category": "Stacks"
+      },
+      {
+        "command": "stacks.env.set",
+        "title": "Env: Set Value...",
+        "category": "Stacks"
+      },
+      {
+        "command": "stacks.env.encrypt",
+        "title": "Env: Encrypt File",
+        "category": "Stacks"
+      },
+      {
+        "command": "stacks.env.decrypt",
+        "title": "Env: Decrypt File",
+        "category": "Stacks"
+      },
+      {
+        "command": "stacks.env.rotate",
+        "title": "Env: Rotate Keys",
+        "category": "Stacks"
+      },
+      {
+        "command": "stx.sortClasses",
+        "title": "Sort Utility Classes",
+        "category": "stx"
+      },
+      {
+        "command": "css.reload",
+        "title": "Css: Reload Configuration"
       }
     ],
     "menus": {
@@ -105,65 +157,262 @@
         {
           "command": "stacks.runBuddyCommand",
           "when": "stacks.isProject"
-        }
-      ]
-    },
-    "configuration": {
-      "title": "Stacks",
-      "properties": {
-        "stacks.preview.url": {
-          "type": "string",
-          "default": "",
-          "markdownDescription": "URL `Stacks: Open Preview` always opens, e.g. `http://localhost:3000/dashboard`. Leave empty to find the running dev server the way `./buddy dev` picks its URL (`APP_URL`, `PORT`, `APP_PATH`)."
         },
-        "stacks.preview.preferLocalhost": {
-          "type": "boolean",
-          "default": false,
-          "markdownDescription": "Preview `http://localhost:<PORT>` even when `APP_URL` gives the app a pretty `https://` domain. Useful when the local certificate is not trusted, which leaves the Simple Browser blank."
+        {
+          "command": "stacks.pickier.fixAll",
+          "when": "stacks.isProject"
         },
-        "stacks.devServer.args": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "default": [],
-          "markdownDescription": "Extra arguments for `./buddy dev`, e.g. `[\"frontend\"]` or `[\"--site\"]`. They are passed to the shell as written."
+        {
+          "command": "stacks.pickier.restart",
+          "when": "stacks.isProject"
         },
-        "stacks.devServer.openPreview": {
-          "type": "boolean",
-          "default": true,
-          "markdownDescription": "Open the preview in the Simple Browser once `Stacks: Start Dev Server` is up, instead of letting `./buddy dev` open the system browser."
+        {
+          "command": "stacks.env.get",
+          "when": "stacks.isProject"
         },
-        "stacks.statusBar.enabled": {
-          "type": "boolean",
-          "default": true,
-          "description": "Show the Stacks item in the status bar, which opens the preview."
+        {
+          "command": "stacks.env.set",
+          "when": "stacks.isProject"
+        },
+        {
+          "command": "stacks.env.encrypt",
+          "when": "stacks.isProject"
+        },
+        {
+          "command": "stacks.env.decrypt",
+          "when": "stacks.isProject"
+        },
+        {
+          "command": "stacks.env.rotate",
+          "when": "stacks.isProject"
         }
-      }
+      ]
     },
+    "configuration": [
+      {
+        "title": "Stacks",
+        "properties": {
+          "stacks.preview.url": {
+            "type": "string",
+            "default": "",
+            "markdownDescription": "URL `Stacks: Open Preview` always opens, e.g. `http://localhost:3000/dashboard`. Leave empty to find the running dev server the way `./buddy dev` picks its URL (`APP_URL`, `PORT`, `APP_PATH`)."
+          },
+          "stacks.preview.preferLocalhost": {
+            "type": "boolean",
+            "default": false,
+            "markdownDescription": "Preview `http://localhost:<PORT>` even when `APP_URL` gives the app a pretty `https://` domain. Useful when the local certificate is not trusted, which leaves the Simple Browser blank."
+          },
+          "stacks.devServer.args": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "default": [],
+            "markdownDescription": "Extra arguments for `./buddy dev`, e.g. `[\"frontend\"]` or `[\"--site\"]`. They are passed to the shell as written."
+          },
+          "stacks.devServer.openPreview": {
+            "type": "boolean",
+            "default": true,
+            "markdownDescription": "Open the preview in the Simple Browser once `Stacks: Start Dev Server` is up, instead of letting `./buddy dev` open the system browser."
+          },
+          "stacks.statusBar.enabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "Show the Stacks item in the status bar, which opens the preview."
+          },
+          "stacks.pickier.enable": {
+            "type": "boolean",
+            "default": true,
+            "markdownDescription": "Lint with the project's own pickier and config, the same as `./buddy lint`, and offer it as a formatter and a `source.fixAll.pickier` code action."
+          },
+          "stacks.pickier.run": {
+            "type": "string",
+            "enum": [
+              "onType",
+              "onSave"
+            ],
+            "default": "onType",
+            "markdownDescription": "Lint as you type, or only when a file is saved."
+          },
+          "stacks.bunPath": {
+            "type": "string",
+            "default": "",
+            "markdownDescription": "The Bun binary that runs pickier. Leave empty to use the project's `pantry/.bin/bun`, then `bun` on the `PATH`."
+          },
+          "stacks.env.decryptOnHover": {
+            "type": "boolean",
+            "default": true,
+            "markdownDescription": "Hovering an `encrypted:` value in an env file shows it decrypted, with the private key from `.env.keys` or `DOTENV_PRIVATE_KEY*`. The plaintext is only shown, never written anywhere."
+          },
+          "stacks.env.missingKeys": {
+            "type": "boolean",
+            "default": true,
+            "markdownDescription": "Flag keys `.env.example` declares that `.env` does not set."
+          }
+        }
+      },
+      {
+        "title": "stx",
+        "properties": {
+          "stxTypescriptPlugin.enabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable TypeScript language features in stx files"
+          },
+          "stx.diagnostics.enable": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable diagnostics (errors and warnings) for stx files"
+          },
+          "stx.diagnostics.validateUnclosedDirectives": {
+            "type": "boolean",
+            "default": true,
+            "description": "Validate unclosed directives like @if without @endif"
+          },
+          "stx.diagnostics.validateMismatchedDirectives": {
+            "type": "boolean",
+            "default": true,
+            "description": "Validate mismatched directives like @if closed with @endforeach"
+          },
+          "stx.diagnostics.validateTemplatePaths": {
+            "type": "boolean",
+            "default": true,
+            "description": "Validate that template paths in @include and @component directives exist"
+          },
+          "stx.completion.enable": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable auto-completion for stx directives"
+          },
+          "stx.completion.showSnippets": {
+            "type": "boolean",
+            "default": true,
+            "description": "Show snippet completions with placeholders for directive parameters"
+          },
+          "stx.hover.enable": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable hover documentation for stx directives"
+          },
+          "stx.hover.showExamples": {
+            "type": "boolean",
+            "default": true,
+            "description": "Show code examples in hover documentation"
+          },
+          "stx.codeActions.enable": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable quick fixes and code actions"
+          },
+          "stx.folding.enable": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable code folding for directive blocks"
+          },
+          "stx.semanticHighlighting.enable": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable semantic syntax highlighting for directives"
+          },
+          "stx.utilityClasses.enable": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable utility class features (tooltips, color previews, sorting)"
+          },
+          "stx.utilityClasses.framework": {
+            "type": "string",
+            "enum": [
+              "tailwind",
+              "unocss",
+              "auto"
+            ],
+            "default": "auto",
+            "markdownDescription": "Utility CSS framework to use. `auto` will detect from config files"
+          },
+          "stx.utilityClasses.colorPreview": {
+            "type": "boolean",
+            "default": true,
+            "description": "Show inline color decorations for color utility classes"
+          },
+          "stx.utilityClasses.hoverPreview": {
+            "type": "boolean",
+            "default": true,
+            "description": "Show CSS output when hovering over utility classes"
+          },
+          "stx.utilityClasses.underline": {
+            "type": "boolean",
+            "default": true,
+            "description": "Underline matched utility classes"
+          },
+          "stx.utilityClasses.sortOnSave": {
+            "type": "boolean",
+            "default": false,
+            "description": "Automatically sort utility classes on file save"
+          },
+          "stx.utilityClasses.colorPreviewRadius": {
+            "type": "string",
+            "default": "0",
+            "description": "Border radius for color preview blocks ('0' for square like Tailwind, '50%' for circle)"
+          },
+          "stx.utilityClasses.selectionStyle": {
+            "type": "boolean",
+            "default": false,
+            "description": "Show CSS preview for selected utility classes"
+          },
+          "stx.utilityClasses.autocomplete": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable autocomplete for utility classes"
+          },
+          "css.remToPxRatio": {
+            "type": "number",
+            "default": 16,
+            "description": "Rem to px conversion ratio for hover previews"
+          }
+        }
+      }
+    ],
     "configurationDefaults": {
       "files.associations": {
-        "buddy": "shellscript",
-        "*.stx": "html"
+        "buddy": "shellscript"
       },
       "npm.packageManager": "bun",
       "typescript.preferGoToSourceDefinition": true,
       "typescript.tsdk": "node_modules/typescript/lib"
-    }
+    },
+    "languages": [
+      {
+        "id": "stx",
+        "aliases": [
+          "stx",
+          "STX"
+        ],
+        "extensions": [
+          ".stx"
+        ],
+        "configuration": "./dist/stx/languages/stx.configuration.json"
+      }
+    ],
+    "grammars": [
+      {
+        "language": "stx",
+        "scopeName": "text.html.ts.stx",
+        "path": "./dist/stx/syntaxes/stx.tmLanguage.json",
+        "embeddedLanguages": {
+          "source.css": "css",
+          "source.js": "javascript",
+          "source.ts": "typescript",
+          "meta.embedded.block.typescript": "typescript",
+          "meta.embedded.block.javascript": "javascript",
+          "meta.embedded.line.typescript": "typescript",
+          "meta.component.parameters.stx": "typescript"
+        }
+      }
+    ]
   },
-  "extensionPack": [
-    "dotenv.dotenvx-vscode",
-    "amazonwebservices.aws-toolkit-vscode",
-    "dbaeumer.vscode-eslint",
-    "davidanson.vscode-markdownlint",
-    "foxundermoon.shell-format",
-    "mattpocock.ts-error-translator",
-    "mylesmurphy.prettify-ts",
-    "Orta.vscode-twoslash-queries",
-    "oven.bun-vscode",
-    "streetsidesoftware.code-spell-checker"
-  ],
   "devDependencies": {
+    "@stacksjs/stx-vscode": "^0.2.352",
+    "@types/vscode": "~1.109.0",
     "@vscode/vsce": "^4.0.0"
   }
 }

package/ide/vscode/scripts/stx-contributes.ts

@@ -0,0 +1,66 @@
+/**
+ * Keeps the stx half of package.json's `contributes` equal to what
+ * `@stacksjs/stx-vscode` ships.
+ *
+ * VS Code reads languages, grammars, commands and settings only from the
+ * manifest, so the built-in stx support needs them declared here, pointing at
+ * dist/stx/ (copied there by build.ts). The library describes them in
+ * `contributes.json`; this derives the manifest from it rather than keeping a
+ * second copy by hand. Snippets are left out on purpose: the extension offers
+ * them as completions only when the stx extension is not installed, because
+ * a manifest entry would show every snippet twice next to it.
+ *
+ *   bun scripts/stx-contributes.ts --write   update package.json (`bun run sync:stx`)
+ *
+ * tests/manifest.test.ts fails while the two disagree.
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import process from 'node:process'
+
+export interface StxContributes {
+  languages: Array<Record<string, unknown> & { id: string, configuration: string }>
+  grammars: Array<Record<string, unknown> & { language: string, path: string }>
+  commands: Array<{ command: string, title: string, category?: string }>
+  configuration: { title: string, properties: Record<string, unknown> }
+}
+
+const STX_DIR = './dist/stx/'
+
+function fromStx(path: string): string {
+  return STX_DIR + path.replace(/^\.\//, '')
+}
+
+/** `manifest` with its stx contributions replaced by the library's. */
+export function withStxContributes(manifest: any, stx: StxContributes): any {
+  const stxCommands = new Set(stx.commands.map(command => command.command))
+  const contributes = manifest.contributes
+  const sections: Array<{ title: string }> = Array.isArray(contributes.configuration) ? contributes.configuration : [contributes.configuration]
+
+  return {
+    ...manifest,
+    contributes: {
+      ...contributes,
+      languages: stx.languages.map(language => ({ ...language, configuration: fromStx(language.configuration) })),
+      grammars: stx.grammars.map(grammar => ({ ...grammar, path: fromStx(grammar.path) })),
+      commands: [...contributes.commands.filter((command: { command: string }) => !stxCommands.has(command.command)), ...stx.commands],
+      configuration: [...sections.filter(section => section.title !== stx.configuration.title), stx.configuration],
+    },
+  }
+}
+
+export function libraryContributes(root: string): StxContributes {
+  return JSON.parse(readFileSync(Bun.resolveSync('@stacksjs/stx-vscode/contributes.json', root), 'utf8'))
+}
+
+if (import.meta.main) {
+  const root = join(import.meta.dir, '..')
+  const path = join(root, 'package.json')
+  const manifest = JSON.parse(readFileSync(path, 'utf8'))
+  const next = `${JSON.stringify(withStxContributes(manifest, libraryContributes(root)), null, 2)}\n`
+
+  if (process.argv.includes('--write'))
+    writeFileSync(path, next)
+  else
+    process.stdout.write(next)
+}