eFAILution · eFAILution · Jun 28, 2026 · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -1,3 +1,11 @@
+# Dependabot version updates.
+#
+# Security-alert policy (handled OUTSIDE this file): dev-scoped npm vulnerabilities are not gated.
+# They are auto-dismissed by a Dependabot auto-triage rule (repo Settings -> Code security ->
+# Dependabot -> Auto-triage rules: scope = development -> dismiss), mirroring the dev-group override
+# 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.
 version: 2
 updates:
   # Maintain npm dependencies
@@ -31,10 +39,15 @@ updates:
         update-types:
           - "minor"
           - "patch"
-    # Ignore specific packages if needed
-    # ignore:
-    #   - dependency-name: "package-name"
-    #     versions: ["x.x.x"]
+    # @types/vscode is pinned to the engines.vscode floor (>=1.120.0): `vsce package`
+    # fails when @types/vscode > engines.vscode. Allow only patch bumps (which stay
+    # within the floor); a minor/major bump must be a deliberate engines.vscode raise,
+    # not an automatic dependency update. This stops the bump, not any security alert.
+    ignore:
+      - dependency-name: "@types/vscode"
+        update-types:
+          - "version-update:semver-minor"
+          - "version-update:semver-major"
 
   # Maintain GitHub Actions
   - package-ecosystem: "github-actions"

diff --git a/README.md b/README.md
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,45 @@
+# Extension API
+
+> **Status: not yet exposed.** `activate()` does not currently return this API, so `getExtension(...).activate()` resolves to `undefined`. This documents the *intended* contract for other extensions to consume; track its implementation before depending on it. See the [README](../README.md) for user-facing features.
+
+## Intended interface
+
+```typescript
+interface GitLabComponentAPI {
+    getComponentList(): Promise<Component[]>;
+    getComponentDetails(name: string, version?: string): Promise<ComponentDetails>;
+    validateComponent(component: Component): ValidationResult;
+    expandGitLabVariables(text: string, context?: VariableContext): string;
+    openComponentBrowser(context?: ComponentContext): Promise<void>;
+}
+
+interface Component {
+    name: string;
+    description: string;
+    parameters: ComponentParameter[];
+    version?: string;
+    source?: string;
+    gitlabInstance?: string;
+    sourcePath?: string;
+    availableVersions?: string[];
+    originalUrl?: string;
+}
+
+interface ComponentParameter {
+    name: string;
+    description?: string;
+    required: boolean;
+    type?: string;
+    default?: unknown;
+}
+```
+
+## Intended usage
+
+```typescript
+const api = await vscode.extensions.getExtension('eFAILution.gitlab-component-helper')?.activate();
+if (api) {
+    const components = await api.getComponentList();
+    // Use components...
+}
+```
diff --git a/docs/discovery.md b/docs/discovery.md
@@ -0,0 +1,53 @@
+# Component Discovery
+
+> Advanced configuration for how the extension scans a source repository for components. Most users need none of this — see the [README](../README.md) for the basics.
+
+By default the extension follows the [GitLab CI Components spec](https://docs.gitlab.com/ci/components/#directory-structure) when scanning a source repository: it looks for templates in `templates/` and one subdirectory level deep, matching `*.yml` and `*.yaml`. **No configuration is required for spec-compliant repos.**
+
+For repositories that pre-date the spec, use a custom layout, or store templates outside `templates/`, override discovery either globally or per source.
+
+## Global defaults
+
+```jsonc
+"gitlabComponentHelper.discovery.templateRoots": ["templates", "ci/components"],
+"gitlabComponentHelper.discovery.maxDepth": 2,
+"gitlabComponentHelper.discovery.filePatterns": ["*.yml", "*.yaml"],
+"gitlabComponentHelper.discovery.templateFileNames": ["template.yml", "template.yaml"]
+```
+
+These four settings are also editable from the **VS Code Settings UI** (search for "GitLab Component Helper Discovery").
+
+## Per-source override
+
+Need different rules for one repository? Add a `discovery` block to that source — its values override the global defaults for that source only.
+
+```jsonc
+"gitlabComponentHelper.componentSources": [
+  {
+    "name": "Standard CI Components",
+    "path": "components/opentofu",
+    "gitlabInstance": "gitlab.com"
+    // uses global discovery defaults
+  },
+  {
+    "name": "Legacy Internal Components",
+    "path": "infra/legacy-ci",
+    "gitlabInstance": "gitlab.company.com",
+    "discovery": {
+      "templateRoots": ["ci/components", "shared/pipelines"],
+      "maxDepth": 2
+    }
+  }
+]
+```
+
+## Limits
+
+To keep the extension fast and predictable:
+
+| Field | Limit |
+|---|---|
+| `templateRoots` | Up to 5 roots per source |
+| `maxDepth` | 0–3 (0 = root only, 1 = one subdirectory level, the spec default) |
+| `filePatterns` | Filename globs only — no path globs (e.g. `*.yml` ✅, `foo/*.yml` ❌) |
+| `templateFileNames` | Filenames only — no slashes |
diff --git a/docs/monorepo-tags.md b/docs/monorepo-tags.md
@@ -0,0 +1,39 @@
+# Monorepo Tag Conventions
+
+> How to scope per-component versions in a tag-per-component monorepo. Skip this for ordinary single-component repos — their tags are listed as-is. See the [README](../README.md) for the basics.
+
+When a single repository holds **many components**, each component is usually released under its own tags that embed the component name — e.g. `deploy-app-1.1.0`, `deploy-app-2`, `build-image-4.0.0`. Without any hint, the version dropdown for *every* component would list *every* tag in the repo.
+
+Set a **tag pattern** on the source to tell the extension how tags map to components. Each component's dropdown is then scoped to its own tags, and labels are shown without the prefix (e.g. `1.1.0`, not `deploy-app-1.1.0`). The full tag is still what gets inserted, so the GitLab include resolves correctly.
+
+```jsonc
+"gitlabComponentHelper.componentSources": [
+  {
+    "name": "Shared CI Monorepo",
+    "path": "infrastructure/shared-ci",
+    "gitlabInstance": "gitlab.com",
+    "tagPattern": "{name}-{version}"
+  }
+]
+```
+
+The template uses two tokens:
+
+| Token | Meaning |
+|---|---|
+| `{name}` | The component (= `templates/` directory) name. |
+| `{version}` | The version shown in the dropdown. Matches anything starting with a digit. |
+
+Everything else in the pattern is literal text, so other conventions work too:
+
+| Tag style | Pattern |
+|---|---|
+| `deploy-app-1.1.0` | `{name}-{version}` |
+| `apps/web/v2.0.0` | `apps/{name}/v{version}` |
+| `web_1.0.0` | `{name}_{version}` |
+
+> **Sibling names:** because `{version}` must start with a digit, a component named `build-image` won't pick up a sibling's `build-image-extra-1.0.0` tags. If you need pre-release-only tags with no leading digit (e.g. `web-rc1`), write a stricter custom pattern for that source.
+
+Leave `tagPattern` unset for ordinary single-component repos.
+
+> **Note:** the [version-check feature](../README.md#-stay-on-the-latest-version) only compares clean `X.Y.Z` refs, so components pinned to a full monorepo tag (e.g. `deploy-app@deploy-app-1.1.0`) are not currently flagged as outdated. Scoped monorepo comparison is planned.
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -2,7 +2,7 @@
   "name": "gitlab-component-helper",
   "displayName": "GitLab Component Helper",
   "description": "Provides intellisense for GitLab CI components",
-  "version": "0.12.2",
+  "version": "0.13.10",
   "icon": "images/icon.png",
   "engines": {
     "node": ">=22.0.0",
@@ -220,6 +220,20 @@
           },
           "default": [],
           "description": "Extra GitLab CI file globs, merged with the built-in defaults. Patterns match at any directory depth (e.g. 'ci/*.yml' is treated as '**/ci/*.yml')."
+        },
+        "gitlabComponentHelper.versionCheck.enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Warn when a component pinned to a semantic version (X.Y.Z) has a newer stable release available. Checked when a GitLab CI file is opened or saved."
+        },
+        "gitlabComponentHelper.versionCheck.severity": {
+          "type": "string",
+          "enum": [
+            "warning",
+            "information"
+          ],
+          "default": "warning",
+          "description": "Severity of the 'newer component version available' diagnostic."
         }
       }
     },
@@ -259,6 +273,10 @@
       {
         "command": "gitlab-component-helper.showPerformanceStats",
         "title": "GitLab CI: Show Performance Statistics"
+      },
+      {
+        "command": "gitlab-component-helper.updateAllComponentVersions",
+        "title": "GitLab CI: Update All Component Versions to Latest"
       }
     ],
     "menus": {
@@ -267,6 +285,11 @@
           "when": "gitlabComponentHelper.isCiFile",
           "command": "gitlab-component-helper.browseComponents",
           "group": "navigation"
+        },
+        {
+          "when": "gitlabComponentHelper.isCiFile",
+          "command": "gitlab-component-helper.updateAllComponentVersions",
+          "group": "navigation"
         }
       ]
     }
@@ -313,7 +336,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/mocha": "^10.0.10",
     "@types/node": "^26.0.0",
-    "@types/vscode": "^1.125.0",
+    "@types/vscode": "^1.120.0",
     "@typescript-eslint/eslint-plugin": "^8.61.1",
     "@typescript-eslint/parser": "^8.61.1",
     "@vscode/test-electron": "^3.0.0",

diff --git a/src/errors/guards.ts b/src/errors/guards.ts
@@ -0,0 +1,48 @@
+/**
+ * Runtime predicates over caught error values.
+ *
+ * These narrow the error classes declared in `./types` — kept separate so `types.ts` stays purely
+ * declarative (enum, classes, type aliases) and behaviour lives here.
+ */
+
+import { ErrorCode, GitLabComponentError, NetworkError } from './types';
+
+/**
+ * Extract an HTTP status code from an unknown thrown value.
+ *
+ * Prefers the typed `NetworkError.details.statusCode`, then falls back to a `statusCode` property on
+ * any error-shaped object so non-`NetworkError` throws (e.g. raw fetch errors) are still recognised.
+ *
+ * @param error  The caught value (typed `unknown` at catch sites).
+ * @returns      The HTTP status code if one can be safely extracted, otherwise `undefined`.
+ */
+export function extractStatusCode(error: unknown): number | undefined {
+  if (error instanceof NetworkError && error.details?.statusCode) {
+    return error.details.statusCode;
+  }
+  if (typeof error === 'object' && error !== null && 'statusCode' in error) {
+    const candidate = (error as { statusCode: unknown }).statusCode;
+    if (typeof candidate === 'number') {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Whether a caught value represents a GitLab authentication failure (expired/invalid/missing token).
+ *
+ * Recognises both the typed `UNAUTHORIZED` error code and a raw 401/403 status, so callers don't have
+ * to special-case how deep in the stack the error was constructed.
+ *
+ * @param error  The caught value (typed `unknown` at catch sites).
+ * @returns      `true` if the error is an `UNAUTHORIZED` GitLab error or carries a 401/403 status,
+ *               otherwise `false`.
+ */
+export function isAuthError(error: unknown): boolean {
+  if (error instanceof GitLabComponentError && error.code === ErrorCode.UNAUTHORIZED) {
+    return true;
+  }
+  const status = extractStatusCode(error);
+  return status === 401 || status === 403;
+}
diff --git a/src/errors/index.ts b/src/errors/index.ts
@@ -12,6 +12,11 @@ export {
   ConfigurationError
 } from './types';
 
+export {
+  extractStatusCode,
+  isAuthError
+} from './guards';
+
 export {
   ErrorHandler,
   ErrorHandlerOptions,

diff --git a/src/extension.ts b/src/extension.ts
@@ -132,6 +132,7 @@ export function activate(context: vscode.ExtensionContext) {
     logger.debug('[Extension] Registering addProjectToken command...', 'Extension');
     const service = getComponentService();
     service.setSecretStorage(context.secrets);
+    context.subscriptions.push(service);
     registerAddProjectTokenCommand(context, service);
 
     // Register component browser command
@@ -618,6 +619,31 @@ export function activate(context: vscode.ExtensionContext) {
     // Initialize the validation provider
     const validationProvider = new ValidationProvider(context);
 
+    // Register command to update every outdated component in the active file to its latest stable version.
+    logger.debug('[Extension] Registering updateAllComponentVersions command...', 'Extension');
+    context.subscriptions.push(
+      vscode.commands.registerCommand('gitlab-component-helper.updateAllComponentVersions', async () => {
+        const editor = vscode.window.activeTextEditor;
+        if (!editor) {
+          vscode.window.showErrorMessage('Open a GitLab CI file to update component versions.');
+          return;
+        }
+        try {
+          const updated = await validationProvider.updateAllComponentVersions(editor.document);
+          if (updated === 0) {
+            vscode.window.showInformationMessage('All components are already on their latest version.');
+          } else {
+            vscode.window.showInformationMessage(
+              `Updated ${updated} component${updated === 1 ? '' : 's'} to the latest version.`
+            );
+          }
+        } catch (error) {
+          logger.error(`[Extension] Failed to update component versions: ${error}`, 'Extension');
+          vscode.window.showErrorMessage(`Failed to update component versions: ${error}`);
+        }
+      })
+    );
+
     // Keep the `gitlabComponentHelper.isCiFile` context key in sync with `isGitLabCIFile` so the editor context menu
     // shows the Browse Components command on exactly the same files the providers activate on.
     const updateCiFileContext = (editor: vscode.TextEditor | undefined): void => {