release: beta → main (next stable)

.ai/architecture.yaml

@@ -22,12 +22,12 @@ components:
       validationProvider.ts: Input validation with Quick Fixes
       componentBrowserProvider.ts: Component browser webview UI
       componentDetector.ts: Detect GitLab CI component usage in YAML
-      componentHtmlRenderer.ts: Render component docs as HTML
+      hoverContentBuilder.ts: Build the hover popup's markdown body (vscode-free, unit-tested)
     depends_on:
     - services
     - utils
     - types
-    - templates
+    - webview
   services:
     location: src/services/
     purpose: Business logic and data management
@@ -77,14 +77,17 @@ components:
     depends_on:
     - types
     - utils
-  templates:
-    location: src/templates/
-    purpose: HTML template generation for webview UIs
+  webview:
+    location: src/webview/
+    purpose: Helpers and assets for the webview documents rendered by the providers
     files:
-      detachedComponent.ts: Detached component view template
-      helpers/htmlBuilder.ts: HTML construction helper
-      helpers/styleBuilder.ts: CSS style helper
-      index.ts: Public exports
+      webviewHtml.ts: Nonce, Content-Security-Policy and asset-URI helpers for webview documents
+      inlineMarkdown.ts: HTML escaping and inline-Markdown rendering (vscode-free, unit-tested)
+      scriptData.ts: Safe JSON serialization for embedding data in a script block (vscode-free, unit-tested)
+      clientInlineMarkdown.ts: Source text for the browser-side twin of renderInlineMarkdown (vscode-free, unit-tested)
+      styles/: Stylesheets built to out/webview/styles/ and loaded via a CSP'd link
+    notes: Assets under styles/ (and client/ as scripts are extracted) are built by the webview esbuild
+      context and resolved at runtime through assetUri; they are not bundled into out/extension.js.
     depends_on:
     - types
   constants:
@@ -140,6 +143,26 @@ components:
       publish-release.sh: Publish to VS Code marketplace
       release-and-publish.sh: Combined release and publish
       setup-github-token.sh: GitHub token configuration
+  demo_gifs:
+    location: scripts/demo-gifs/
+    purpose: Maintainer tool that records the README demo GIFs by driving a real VS Code through Playwright over CDP
+    packaged: false (scripts/** in .vscodeignore; own package.json, out/ and node_modules/ gitignored)
+    files:
+      record.mjs: Entry point. Resets the work dir, packages + installs the VSIX, warms the cache, records scenes
+      lib/config.mjs: Paths, viewport (1280x800 at 2x), GIF size (1100 wide, 12 fps), env overrides; refuses a
+        GCH_DEMO_DIR not named gch-demo* or containing the home folder or repo, since it is wiped each run
+      lib/workspace.mjs: Throwaway profile, demo workspace (my-pipelines), vsce package + install
+      lib/vscode.mjs: Launch/stop VS Code, Command Palette, scene reset, webview frame lookup
+      lib/input.mjs: Drawn cursor, eased mouse moves, typing, wheel scrolling
+      lib/recorder.mjs: CDP screencast capture, ffmpeg GIF encode, per-second review sheet
+      scenes/: One module per GIF (browse, complete, hover, validate, versions)
+      fixtures/: Profile settings.json (component sources, quiet editor) and templates/deploy.yml for local includes
+    how_it_works:
+    - VS Code starts with --remote-debugging-port=0; the port is read from <profile>/DevToolsActivePort and
+      Playwright attaches with chromium.connectOverCDP, so a stray instance can't be picked up by mistake
+    - Emulation.setDeviceMetricsOverride fixes the viewport so output size doesn't depend on the screen
+    - The OS pointer isn't captured, so a cursor element is drawn in the top document and moved with page.mouse
+    - Page.startScreencast frames only arrive on change; an ffmpeg concat list holds each frame until the next
 interfaces:
   Component:
     location: src/types/git-component.ts
@@ -213,8 +236,8 @@ data_flow:
     component: componentService
     action: Fetch component details (cache-first)
   - step: 4
-    component: componentHtmlRenderer
-    action: Render documentation as HTML using templates/helpers
+    component: hoverContentBuilder
+    action: Build the hover markdown body (a MarkdownString, not HTML)
   - step: 5
     component: hoverProvider
     action: Display hover card

.ai/context.yaml

@@ -29,6 +29,7 @@ structure:
   types: src/types/
   utils: src/utils/
   scripts: scripts/
+  demo_gifs: scripts/demo-gifs/
 context_modules:
   architecture: architecture.yaml
   workflows: workflows.yaml

.ai/decisions.yaml

@@ -124,6 +124,42 @@ decisions:
     - .release-it/vscode-version.js
     - package.json (release:main, release:beta scripts)
     title: Release It
+  DEPENDABOT_TARGETS_BETA:
+    date: '2026-09-14'
+    status: accepted
+    context: Dependabot defaulted to the repository default branch (main), which is the stable
+      release line. Bumps opened there duplicated what had already landed on beta, and a merge
+      to main auto-cuts a stable release.
+    decision: 'Set target-branch: "beta" on every ecosystem in .github/dependabot.yml (npm,
+      github-actions, pip)'
+    rationale:
+    - A push to main runs release-it with .release-it.json and cuts a stable GitHub release, so
+      a routine dependency bump merged there ships a release out of band
+    - main trails beta by everything not yet released, so bumps against main duplicate versions
+      beta already carries (e.g. #291/#292/#295 re-proposed bumps merged weeks earlier)
+    - Retargeting such a PR to beta conflicts on package-lock.json, since beta has moved
+    - Updates reach main the same way every other change does, through the beta -> main release PR
+    implementation:
+      config: '.github/dependabot.yml, target-branch: "beta" on each of the three package-ecosystem
+        entries'
+      flow: dependabot -> beta -> release PR -> main
+    alternatives_considered:
+    - name: leave_targeting_main
+      rejected_because: Ships stable releases from dependency bumps and produces duplicate PRs
+    - name: retarget_each_pr_by_hand
+      rejected_because: Lockfile conflicts on every npm PR; recurring manual work
+    consequences:
+      positive:
+      - Dependency updates follow the same path as feature work
+      - No stable release cut by a dependency bump
+      - No duplicate bumps against a stale branch
+      negative:
+      - A security fix reaches main only when the next release PR merges
+    references:
+    - .github/dependabot.yml
+    - .release-it.json
+    - .release-it.beta.json
+    title: Dependabot Targets Beta
   MODULAR_SERVICE_SPLIT:
     date: '2026'
     status: accepted
@@ -391,6 +427,38 @@ decisions:
     - .mocharc.cjs
     - package.json (test scripts)
     title: Mocha Over Jest
+  DEMO_GIFS_RECORDED_BY_SCRIPT:
+    date: '2026-10'
+    status: accepted
+    context: README/Marketplace GIFs were hand-recorded, went stale as the UI changed, and risked showing the
+      maintainer's own projects and paths
+    decision: Record them with scripts/demo-gifs (Playwright driving a packaged VSIX in a throwaway profile) and
+      host the output as GitHub user-attachments linked from README.md
+    rationale:
+    - Re-recording after a UI change is one command, and every take looks the same
+    - Fresh profile, neutral my-pipelines folder and public gitlab.com components keep personal details out
+    - Installing the packaged VSIX keeps "[Extension Development Host]" out of the title bar
+    - user-attachments URLs are public for a public repo and render on the Marketplace; committing GIFs would
+      grow the repo by ~4 MB per re-record
+    consequences:
+      positive:
+      - Demos can be refreshed with every UI change
+      - Review sheets make the privacy check quick
+      negative:
+      - macOS + local VS Code only; not run in CI
+      - user-attachments links stop rendering publicly if the repo goes private, and GitHub doesn't promise
+        they last forever
+    alternatives_considered:
+    - name: manual screen recording
+      rejected_because: Inconsistent, slow to redo, easy to leak personal details
+    - name: commit GIFs under images/
+      rejected_because: Repo growth on every re-record
+    - name: extensionDevelopmentPath instead of a VSIX
+      rejected_because: Title bar shows [Extension Development Host]
+    references:
+    - scripts/demo-gifs/record.mjs
+    - .ai/workflows.yaml (record_demo_gifs)
+    title: Demo GIFs Recorded By Script
 future_decisions:
 - question: Should we support other CI/CD platforms (GitHub Actions, CircleCI)?
   status: under_consideration

.ai/errors.yaml

@@ -391,6 +391,26 @@ errors:
       - Re-enable v10 once @release-it/conventional-changelog adopts the render-function
         stack (conventional-changelog@8 / writer@9)
       reference: .github/dependabot.yml + package.json; see huntridge-labs/argus#318
+  demo_gif_recording_fails:
+    symptom: npm run record in scripts/demo-gifs fails or produces a wrong-looking GIF
+    causes:
+    - cause: 'listen EINVAL on .../1.13-main.sock or "IPC handle is longer than 103 chars"'
+      solution: Point GCH_DEMO_DIR at a short folder named gch-demo*, e.g. /tmp/gch-demo2 (default /tmp/gch-demo).
+        Other names are refused because the folder is wiped on every run
+    - cause: 'mach_port_rendezvous ... Permission denied, or "Starting inspector failed: operation not permitted"'
+      solution: Run outside the command sandbox; VS Code can't start inside it
+    - cause: VS Code never wrote DevToolsActivePort, or a stray instance from a crashed run holds the profile
+      solution: pkill -9 -f "user-data-dir=${GCH_DEMO_DIR:-/tmp/gch-demo}/profile" and run again
+    - cause: Command Palette did not highlight a command
+      solution: The command title changed in VS Code; update the name in the scene or lib/vscode.mjs
+    - cause: An empty "Drag a view here" pane or a side bar shows up
+      solution: prepareScene hides side bars by checking visibility; check the .part.* selectors still match
+    - cause: Typing lands at the wrong indent or Enter accepts a suggestion
+      solution: Scenes rely on fixtures/settings.json (wordBasedSuggestions off) and VS Code's YAML auto-indent;
+        re-check those after a VS Code update
+    - cause: A webview element is never found
+      solution: Webviews are out-of-process frames that only attach while the script is connected; open the
+        panel inside the same run and use webviewFrame(page, selector)
 debugging:
   enable_debug_logs:
     steps:

.ai/index.yaml

@@ -19,22 +19,24 @@ keys:
   - cache
   - component
   - constants
+  - demo_gifs
   - errors
   - extension
   - parsers
   - providers
   - scripts
   - services
-  - templates
   - types
   - utils
+  - webview
   workflows:
   - add_configuration_option
   - add_new_command
   - add_new_provider
   - build_and_package
   - debug_extension
   - fix_failing_test
+  - record_demo_gifs
   - release
   - run_tests
   - setup_dev_environment
@@ -43,6 +45,8 @@ keys:
   - BATCH_API_REQUESTS
   - CACHE_COMPONENTS
   - CENTRALIZED_ERROR_HANDLING
+  - DEMO_GIFS_RECORDED_BY_SCRIPT
+  - DEPENDABOT_TARGETS_BETA
   - EXTENSION_HOST_TEST_LAYER
   - FILE_SIZE_POLICY
   - MOCHA_OVER_JEST
@@ -61,6 +65,7 @@ keys:
   - cache_issues
   - compilation_errors
   - component_not_loading
+  - demo_gif_recording_fails
   - empty_changelog_conventionalcommits_v10
   - extension_not_activating
   - hover_not_working

.ai/workflows.yaml

@@ -138,13 +138,48 @@ workflows:
       command: npm test
     - action: commit_changes
       command: 'git commit -m ''chore: update dependencies'''
+  record_demo_gifs:
+    description: Re-record the README demo GIFs (browse, complete, hover, validate, versions) after a UI change
+    location: scripts/demo-gifs/
+    prerequisites:
+    - macOS with VS Code installed at /Applications (override with VSCODE_BIN / VSCODE_CLI)
+    - ffmpeg on PATH
+    - Network access to gitlab.com (scenes use public components/opentofu, sast, secret-detection, code-quality)
+    - Run outside any command sandbox; VS Code needs its mach port and debug port
+    - Root dependencies installed (npm ci at the repo root); vsce package runs the root vscode:prepublish build
+    steps:
+    - action: install_recorder_dependencies
+      command: cd scripts/demo-gifs && npm ci
+      note: Own package.json/lock, separate from the extension's; root npm install never touches it
+    - action: record
+      command: npm run record
+      note: 'All scenes, or name some: npm run record -- hover versions. Packages the extension with vsce,
+        installs it into a throwaway profile under /tmp/gch-demo (GCH_DEMO_DIR, which is wiped each run and must be
+        named gch-demo*), drives VS Code over CDP on a free debug port,
+        writes out/<scene>.gif and out/<scene>-review.png'
+    - action: privacy_review
+      check: Open every out/<scene>-review.png (one tile per second) and confirm no names, paths, accounts,
+        private projects or tokens appear. The profile is fresh and the folder is my-pipelines, but check anyway
+    - action: publish
+      steps:
+      - Drag the GIFs into a comment on the README PR on GitHub and post it
+      - Copy the github.com/user-attachments/assets/<id> URLs from the comment into README.md
+      - Confirm each URL loads without logging in (curl -sL -o /dev/null -w '%{http_code}' <url> returns 200)
+      note: GIFs are not committed; see decisions.yaml DEMO_GIFS_RECORDED_BY_SCRIPT
+    - action: add_or_change_a_scene
+      location: scripts/demo-gifs/scenes/{name}.mjs
+      contract: Export cursorStart, prepare(page) and perform(page); register it in SCENES in record.mjs
+      helpers: lib/vscode.mjs (prepareScene, runCommand, webviewFrame), lib/input.mjs (moveTo, clickOn, typeSlow,
+        wordPosition, scrollIntoView)
+    reference: scripts/demo-gifs/record.mjs
 common_commands:
   compile: npm run compile
   watch: npm run watch
   test: npm test
   debug: F5 (in VS Code)
   package: npm run package
   lint: npm run lint
+  lint_ci: npm run lint:ci (eslint + stylelint with GitHub annotation formatters; run by CI)
 git_workflow:
   branch_naming: feature/description or fix/description
   commit_format: 'type(scope): description'

.github/dependabot.yml

@@ -6,11 +6,18 @@
 # in osv-scanner.toml that the Argus scan honors. Do NOT add a dev-dep `ignore:` here to suppress
 # those alerts -- `ignore:` also stops the version-update PRs below, which are how dev tools stay
 # current and how a transitive fix (e.g. serialize-javascript >= 7.0.5) actually lands.
+#
+# Every ecosystem below sets `target-branch: "beta"`. Without it Dependabot opens against the default
+# branch (`main`), which is the STABLE release line: a push there auto-cuts a stable GitHub release, so a
+# routine dependency bump would ship one out of band. `main` also trails `beta` by whatever has not been
+# released yet, so bumps opened against it duplicate what already landed on `beta` and conflict on the
+# lockfile when retargeted. Everything reaches `main` through the beta -> main release PR instead.
 version: 2
 updates:
   # Maintain npm dependencies
   - package-ecosystem: "npm"
     directory: "/"
+    target-branch: "beta"
     schedule:
       interval: "weekly"
       day: "monday"
@@ -68,6 +75,7 @@ updates:
   # Maintain GitHub Actions
   - package-ecosystem: "github-actions"
     directory: "/"
+    target-branch: "beta"
     schedule:
       interval: "weekly"
       day: "monday"
@@ -85,6 +93,7 @@ updates:
   # Maintain pre-commit hooks
   - package-ecosystem: "pip"
     directory: "/"
+    target-branch: "beta"
     schedule:
       interval: "weekly"
       day: "monday"

.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
         run: npm ci
 
       - name: Run lint
-        run: npm run lint
+        run: npm run lint:ci
 
       - name: Run compile
         run: node esbuild.js

.github/workflows/security-hardening.yml

@@ -19,8 +19,10 @@ permissions:
 jobs:
   argus-hardening:
     name: Argus Reusable Hardening
-    # Pinned to the commit for Argus v1.11.0 for supply-chain safety.
-    uses: huntridge-labs/argus/.github/workflows/reusable-security-hardening.yml@9b444d8975f4a2253cc53e09a7c5837e5b509d24
+    # SHA-pinned rather than tag-pinned for supply-chain safety: a tag can be moved, a commit cannot.
+    # Dependabot bumps this SHA and names the tag it resolves to in the PR title, so read the version there
+    # rather than trusting a hand-written one here (this comment claimed v1.11.0 through three bumps past it).
+    uses: huntridge-labs/argus/.github/workflows/reusable-security-hardening.yml@3fb133a5d03ec81a7a534cf451dd19991e04a975
     with:
       scanners: codeql,gitleaks,osv,dependency-review
       enable_code_security: true