cc-vscode-shebang-markdown 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.0
+
+Initial public release.
+
+### Added
+
+- Custom shebang detection on the first line.
+- Automatic language mode switch to Markdown.
+- Configurable detection pattern.
+- Configurable target language id.
+- Local VSIX packaging scripts.
+- npm package metadata and documentation.
+
+## 0.1.1
+
+### Added
+
+- POSIX shell shebang fallback for `bash`, `zsh` and `sh`.
+- Support for `/bin/*`, `/usr/bin/*`, `/usr/local/bin/*` and `/usr/bin/env` shebang variants.
+- Support for `/usr/bin/env -S bash ...` style shebangs.
+- Fallback detection for `nginx.conf` and `conf.d/*.conf`.
+- Content-based nginx fallback for common nginx blocks.
+
+### Fixed
+
+- Removed `.vscodeignore` because VSCE does not support using `.vscodeignore` together with the `files` property in `package.json`.

package/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+Contributions are welcome.
+
+## Development
+
+```bash
+npm install
+npm run pack:vsix
+npm run reinstall
+```
+
+## Before opening a pull request
+
+Please check:
+
+```bash
+npm run pack:npm
+npm run pack:vsix
+```
+
+## Guidelines
+
+- Keep the extension small.
+- Avoid project-specific hardcoding.
+- Preserve the configurable shebang pattern.
+- Document behavior changes in `CHANGELOG.md`.

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 CodeCorn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files, to deal in the Software
+without restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,337 @@
+# CodeCorn Shebang Markdown
+
+[![npm version](https://img.shields.io/npm/v/cc-vscode-shebang-markdown.svg)](https://www.npmjs.com/package/cc-vscode-shebang-markdown)
+[![npm downloads](https://img.shields.io/npm/dm/cc-vscode-shebang-markdown.svg)](https://www.npmjs.com/package/cc-vscode-shebang-markdown)
+[![license](https://img.shields.io/npm/l/cc-vscode-shebang-markdown.svg)](LICENSE)
+[![VS Code](https://img.shields.io/badge/VS%20Code-%5E1.80.0-blue.svg)](https://code.visualstudio.com/)
+
+**CodeCorn Shebang Markdown** is a tiny Visual Studio Code extension that detects a custom shebang on the first line of a file and switches the editor language mode to Markdown.
+
+It is designed for workflows where Markdown-like operational files, scripts, notes or generated artifacts do not use the `.md` extension, but still need to be handled as Markdown by VS Code, markdownlint, formatters and language-aware tooling.
+
+Italian documentation: [README_IT.md](README_IT.md)
+
+---
+
+## Why
+
+VS Code file associations are path/name based. They are great when a file extension or filename is predictable, but they do not inspect the first line of a document.
+
+This extension fills that gap with a small content-based rule:
+
+```text
+first line contains a CodeCorn Markdown shebang
+→ switch document language mode to markdown
+```
+
+Example:
+
+```text
+#!/usr/bin/env cc-md
+
+# Deployment checklist
+
+- backup database
+- dump environment
+- apply patch
+- verify logs
+```
+
+Even if the file has no `.md` extension, VS Code will treat it as Markdown.
+
+---
+
+## Features
+
+- Detects custom Markdown shebangs on the first line.
+- Forces VS Code language mode to `markdown`.
+- Works with untitled files, extensionless files and script-like notes.
+- Configurable regex pattern.
+- Configurable target VS Code language id.
+- Useful with `markdownlint`, Markdown formatters and editor tooling.
+- No runtime dependencies.
+- Minimal extension footprint.
+
+---
+
+## Default shebangs
+
+The default pattern is:
+
+```text
+^#!.*\bcc-(md|markdown)\b
+```
+
+Supported examples:
+
+```text
+#!/usr/bin/env cc-md
+```
+
+```text
+#!cc-md
+```
+
+```text
+#!/usr/bin/env cc-markdown
+```
+
+```text
+#!cc-markdown
+```
+
+---
+
+## Installation
+
+### Local VSIX install
+
+This package is primarily a VS Code extension. For local development or internal usage:
+
+```bash
+npm install
+npm run reinstall
+```
+
+This builds the `.vsix` package and installs it in VS Code.
+
+### npm package
+
+The package is also published on npm for traceability, reuse and source distribution:
+
+```bash
+npm install cc-vscode-shebang-markdown
+```
+
+Installing from npm does not automatically install the extension into VS Code. For actual editor installation, use a generated `.vsix` file or publish the extension to the Visual Studio Code Marketplace.
+
+---
+
+## Usage
+
+Create or open any file whose first line matches the configured shebang pattern:
+
+```text
+#!/usr/bin/env cc-md
+
+# Server audit
+
+## Build log
+
+- collect build output
+- inspect warnings
+- normalize report
+```
+
+When the document opens, the extension switches its language mode to:
+
+```text
+markdown
+```
+
+You can verify this in the bottom-right language selector in VS Code.
+
+---
+
+## Configuration
+
+### `ccShebangMarkdown.pattern`
+
+Regex applied to the first line of the document.
+
+Default:
+
+```json
+{
+  "ccShebangMarkdown.pattern": "^#!.*\\bcc-(md|markdown)\\b"
+}
+```
+
+### `ccShebangMarkdown.targetLanguage`
+
+VS Code language id to apply when the pattern matches.
+
+Default:
+
+```json
+{
+  "ccShebangMarkdown.targetLanguage": "markdown"
+}
+```
+
+Advanced example:
+
+```json
+{
+  "ccShebangMarkdown.pattern": "^#!.*\\bcompany-doc\\b",
+  "ccShebangMarkdown.targetLanguage": "markdown"
+}
+```
+
+---
+
+## markdownlint note
+
+Some lint configurations require the first line of a Markdown document to be a heading. A shebang intentionally violates that rule.
+
+For shebang-based Markdown files, you may want to disable `MD041`:
+
+```json
+{
+  "markdownlint.config": {
+    "MD041": false
+  }
+}
+```
+
+---
+
+## Development
+
+Clone the repository and install dependencies:
+
+```bash
+npm install
+```
+
+Package the VS Code extension:
+
+```bash
+npm run pack:vsix
+```
+
+Install it locally:
+
+```bash
+npm run reinstall
+```
+
+Check npm package contents before publishing:
+
+```bash
+npm run pack:npm
+```
+
+---
+
+## Release flow
+
+Bump the version in `package.json`, then run:
+
+```bash
+npm install
+npm run pack:vsix
+npm run pack:npm
+npm publish
+```
+
+For scoped npm packages, npm requires public scoped packages to be published with `npm publish --access public`. This package is intentionally unscoped, so plain `npm publish` is enough.
+
+---
+
+## Design principles
+
+- Do one thing.
+- Avoid filename conventions when the contract belongs in the file content.
+- Keep the rule explicit and visible.
+- Do not hijack unrelated files.
+- Prefer configurable detection over hardcoded project paths.
+
+---
+
+## Security
+
+This extension only reads the first line of open text documents and changes VS Code language mode through the VS Code API.
+
+It does not:
+
+- execute file contents;
+- send telemetry;
+- perform network requests;
+- read secrets;
+- modify files on disk.
+
+Please report security issues privately when possible. See [SECURITY.md](SECURITY.md).
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+## Maintainer
+
+Built and maintained by **Federico Girolami** / **CodeCorn Technology**.
+
+CodeCorn™ — We build software that Corn.
+
+## Language fallback rules
+
+Besides CodeCorn Markdown shebangs, the extension also ships with defensive fallback rules for common script/config files.
+
+### Shell scripts
+
+The extension reinforces VS Code detection for:
+
+```text
+#!/bin/bash
+#!/bin/zsh
+#!/bin/sh
+#!/usr/bin/bash
+#!/usr/bin/zsh
+#!/usr/bin/sh
+#!/usr/local/bin/bash
+#!/usr/bin/env bash
+#!/usr/bin/env zsh
+#!/usr/bin/env sh
+#!/usr/bin/env -S bash -euo pipefail
+```
+
+Matching files are switched to:
+
+```text
+shellscript
+```
+
+### nginx
+
+The extension includes a defensive fallback for:
+
+```text
+nginx.conf
+conf.d/*.conf
+```
+
+and for files containing common nginx blocks near the top:
+
+```nginx
+events {
+}
+
+http {
+}
+
+server {
+}
+
+upstream backend {
+}
+```
+
+Matching files are switched to:
+
+```text
+nginx
+```
+
+If the `nginx` language id is not available in the current VS Code installation, the rule falls back to `plaintext` instead of throwing.

package/README_IT.md

@@ -0,0 +1,96 @@
+# CodeCorn Shebang Markdown
+
+**CodeCorn Shebang Markdown** è una piccola estensione per Visual Studio Code che legge la prima riga di un file e, se trova uno shebang configurato, forza il language mode a Markdown.
+
+Serve quando hai file senza estensione `.md`, oppure file operativi/script-like, che devono comunque essere trattati come Markdown da VS Code, markdownlint e formatter.
+
+---
+
+## Esempio
+
+```text
+#!/usr/bin/env cc-md
+
+# Checklist deploy
+
+- backup database
+- dump env
+- patch
+- verifica log
+```
+
+Anche senza estensione `.md`, VS Code imposta il file come `markdown`.
+
+---
+
+## Shebang supportati
+
+Pattern default:
+
+```text
+^#!.*\bcc-(md|markdown)\b
+```
+
+Esempi:
+
+```text
+#!/usr/bin/env cc-md
+```
+
+```text
+#!cc-md
+```
+
+```text
+#!/usr/bin/env cc-markdown
+```
+
+---
+
+## Configurazione
+
+```json
+{
+  "ccShebangMarkdown.pattern": "^#!.*\\bcc-(md|markdown)\\b",
+  "ccShebangMarkdown.targetLanguage": "markdown"
+}
+```
+
+---
+
+## Nota markdownlint
+
+Se `markdownlint` segnala che la prima riga non è un heading, puoi disattivare `MD041` per questo workflow:
+
+```json
+{
+  "markdownlint.config": {
+    "MD041": false
+  }
+}
+```
+
+---
+
+## Installazione locale
+
+```bash
+npm install
+npm run reinstall
+```
+
+Questo genera il `.vsix` e lo installa in VS Code.
+
+---
+
+## Licenza
+
+MIT.
+
+---
+
+## Maintainer
+
+Federico Girolami / CodeCorn Technology.
+
+CodeCorn™ — We build software that Corn.

package/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest published version.
+
+## Reporting a vulnerability
+
+Please report security issues privately when possible.
+
+Contact:
+
+- Federico Girolami
+- f.girolami@codecorn.it
+
+## Security model
+
+This extension only reads the first line of open text documents and changes the VS Code language mode when the configured pattern matches.
+
+It does not execute file contents, send telemetry, perform network requests or modify files on disk.

package/extension.js

@@ -0,0 +1,221 @@
+const vscode = require('vscode');
+
+const applying = new WeakSet();
+
+const DEFAULT_RULES = [
+  {
+    name: 'CodeCorn Markdown shebang',
+    when: 'firstLine',
+    pattern: '^#!.*\\bcc-(md|markdown)\\b',
+    language: 'markdown'
+  },
+  {
+    name: 'POSIX shell shebang',
+    when: 'firstLine',
+    pattern: '^#!\\s*(?:/(?:usr/)?(?:local/)?bin/(?:bash|zsh|sh)\\b|/usr/bin/env\\s+(?:-[^\\s]+\\s+)*(?:bash|zsh|sh)\\b|/bin/env\\s+(?:-[^\\s]+\\s+)*(?:bash|zsh|sh)\\b)',
+    language: 'shellscript'
+  },
+  {
+    name: 'nginx.conf path',
+    when: 'path',
+    pattern: '(?:^|[/\\\\])nginx\\.conf$|(?:^|[/\\\\])conf\\.d[/\\\\].*\\.conf$',
+    language: 'nginx',
+    fallbackLanguage: 'plaintext'
+  },
+  {
+    name: 'nginx content fallback',
+    when: 'content',
+    pattern: '(?m)^\\s*(events|http|server|upstream)\\s*\\{|^\\s*location\\s+[^\\n]+\\{',
+    language: 'nginx',
+    fallbackLanguage: 'plaintext'
+  }
+];
+
+function compileRule(rule) {
+  if (!rule || typeof rule !== 'object') return null;
+  if (!rule.pattern || !rule.language) return null;
+
+  try {
+    return {
+      name: String(rule.name || rule.language),
+      when: String(rule.when || 'firstLine'),
+      pattern: new RegExp(String(rule.pattern)),
+      language: String(rule.language),
+      fallbackLanguage: rule.fallbackLanguage ? String(rule.fallbackLanguage) : ''
+    };
+  } catch (err) {
+    console.warn('[cc-shebang-markdown] Invalid rule regex:', rule, err);
+    return null;
+  }
+}
+
+function readRules() {
+  const cfg = vscode.workspace.getConfiguration();
+
+  const legacyPattern = cfg.get(
+    'ccShebangMarkdown.pattern',
+    '^#!.*\\bcc-(md|markdown)\\b'
+  );
+
+  const legacyTargetLanguage = cfg.get(
+    'ccShebangMarkdown.targetLanguage',
+    'markdown'
+  );
+
+  const configuredRules = cfg.get('ccShebangMarkdown.rules', DEFAULT_RULES);
+
+  const rules = Array.isArray(configuredRules) && configuredRules.length > 0
+    ? configuredRules
+    : DEFAULT_RULES;
+
+  const compiled = rules
+    .map(compileRule)
+    .filter(Boolean);
+
+  /*
+   * Backward compatibility:
+   * old config keys still work and remain first priority.
+   */
+  const legacyRule = compileRule({
+    name: 'legacy ccShebangMarkdown.pattern',
+    when: 'firstLine',
+    pattern: legacyPattern,
+    language: legacyTargetLanguage
+  });
+
+  return [
+    legacyRule,
+    ...compiled
+  ].filter(Boolean);
+}
+
+function getProbeText(document) {
+  if (!document || document.lineCount < 1) return '';
+
+  const endLine = Math.min(document.lineCount, 80);
+  const endCharacter = endLine > 0 ? document.lineAt(endLine - 1).text.length : 0;
+
+  return document.getText(
+    new vscode.Range(0, 0, Math.max(0, endLine - 1), endCharacter)
+  );
+}
+
+function matchesRule(document, rule) {
+  if (!document || !rule) return false;
+
+  if (rule.when === 'path') {
+    const path = document.uri && document.uri.fsPath
+      ? document.uri.fsPath
+      : document.fileName || '';
+
+    return rule.pattern.test(path);
+  }
+
+  if (rule.when === 'content') {
+    return rule.pattern.test(getProbeText(document));
+  }
+
+  const firstLine = document.lineCount > 0
+    ? document.lineAt(0).text
+    : '';
+
+  return rule.pattern.test(firstLine);
+}
+
+async function resolveLanguage(rule) {
+  const available = await vscode.languages.getLanguages();
+
+  if (available.includes(rule.language)) {
+    return rule.language;
+  }
+
+  if (rule.fallbackLanguage && available.includes(rule.fallbackLanguage)) {
+    console.warn(
+      `[cc-shebang-markdown] Language "${rule.language}" unavailable, using fallback "${rule.fallbackLanguage}" for rule "${rule.name}".`
+    );
+
+    return rule.fallbackLanguage;
+  }
+
+  console.warn(
+    `[cc-shebang-markdown] Language "${rule.language}" unavailable for rule "${rule.name}".`
+  );
+
+  return '';
+}
+
+async function maybeForceLanguage(document) {
+  if (!document || document.isClosed) return;
+  if (document.lineCount < 1) return;
+  if (applying.has(document)) return;
+
+  const rules = readRules();
+  const matchedRule = rules.find((rule) => matchesRule(document, rule));
+
+  if (!matchedRule) return;
+
+  const targetLanguage = await resolveLanguage(matchedRule);
+
+  if (!targetLanguage) return;
+  if (document.languageId === targetLanguage) return;
+
+  applying.add(document);
+
+  try {
+    await vscode.languages.setTextDocumentLanguage(document, targetLanguage);
+    console.info(
+      `[cc-shebang-markdown] Applied "${targetLanguage}" via rule "${matchedRule.name}".`
+    );
+  } catch (err) {
+    console.warn(
+      '[cc-shebang-markdown] Could not change language mode:',
+      err
+    );
+  } finally {
+    applying.delete(document);
+  }
+}
+
+function activate(context) {
+  for (const document of vscode.workspace.textDocuments) {
+    maybeForceLanguage(document);
+  }
+
+  context.subscriptions.push(
+    vscode.workspace.onDidOpenTextDocument((document) => {
+      maybeForceLanguage(document);
+    }),
+
+    vscode.workspace.onDidChangeTextDocument((event) => {
+      const touchesFirstLine = event.contentChanges.some((change) => {
+        return change.range.start.line === 0 || change.range.end.line === 0;
+      });
+
+      /*
+       * For content-based fallbacks, also retry on early document edits.
+       */
+      const touchesProbeArea = event.contentChanges.some((change) => {
+        return change.range.start.line < 80 || change.range.end.line < 80;
+      });
+
+      if (touchesFirstLine || touchesProbeArea) {
+        maybeForceLanguage(event.document);
+      }
+    }),
+
+    vscode.workspace.onDidChangeConfiguration((event) => {
+      if (!event.affectsConfiguration('ccShebangMarkdown')) return;
+
+      for (const document of vscode.workspace.textDocuments) {
+        maybeForceLanguage(document);
+      }
+    })
+  );
+}
+
+function deactivate() {}
+
+module.exports = {
+  activate,
+  deactivate
+};

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "cc-vscode-shebang-markdown",
+  "displayName": "CodeCorn Shebang Markdown",
+  "description": "VS Code extension that detects custom shebangs and file fallbacks to switch language mode for linters.",
+  "version": "0.1.1",
+  "publisher": "codecorn",
+  "engines": {
+    "vscode": "^1.80.0"
+  },
+  "categories": [
+    "Linters",
+    "Other"
+  ],
+  "activationEvents": [
+    "onStartupFinished",
+    "onLanguage:plaintext",
+    "onLanguage:shellscript"
+  ],
+  "main": "./extension.js",
+  "contributes": {
+    "configuration": {
+      "title": "CodeCorn Shebang Markdown",
+      "properties": {
+        "ccShebangMarkdown.pattern": {
+          "type": "string",
+          "default": "^#!.*\\\\bcc-(md|markdown)\\\\b",
+          "description": "Legacy regex applicata alla prima riga. Se matcha, viene applicato ccShebangMarkdown.targetLanguage."
+        },
+        "ccShebangMarkdown.targetLanguage": {
+          "type": "string",
+          "default": "markdown",
+          "description": "Legacy VS Code language id da applicare quando ccShebangMarkdown.pattern matcha."
+        },
+        "ccShebangMarkdown.rules": {
+          "type": "array",
+          "description": "Regole ordinate per forzare il language mode in base a firstLine, path o content.",
+          "default": [
+            {
+              "name": "CodeCorn Markdown shebang",
+              "when": "firstLine",
+              "pattern": "^#!.*\\\\bcc-(md|markdown)\\\\b",
+              "language": "markdown"
+            },
+            {
+              "name": "POSIX shell shebang",
+              "when": "firstLine",
+              "pattern": "^#!\\\\s*(?:/(?:usr/)?(?:local/)?bin/(?:bash|zsh|sh)\\\\b|/usr/bin/env\\\\s+(?:-[^\\\\s]+\\\\s+)*(?:bash|zsh|sh)\\\\b|/bin/env\\\\s+(?:-[^\\\\s]+\\\\s+)*(?:bash|zsh|sh)\\\\b)",
+              "language": "shellscript"
+            },
+            {
+              "name": "nginx.conf path",
+              "when": "path",
+              "pattern": "(?:^|[/\\\\\\\\])nginx\\\\.conf$|(?:^|[/\\\\\\\\])conf\\\\.d[/\\\\\\\\].*\\\\.conf$",
+              "language": "nginx",
+              "fallbackLanguage": "plaintext"
+            },
+            {
+              "name": "nginx content fallback",
+              "when": "content",
+              "pattern": "(?m)^\\\\s*(events|http|server|upstream)\\\\s*\\\\{|^\\\\s*location\\\\s+[^\\\\n]+\\\\{",
+              "language": "nginx",
+              "fallbackLanguage": "plaintext"
+            }
+          ],
+          "items": {
+            "type": "object",
+            "required": [
+              "pattern",
+              "language"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "when": {
+                "type": "string",
+                "enum": [
+                  "firstLine",
+                  "path",
+                  "content"
+                ],
+                "default": "firstLine"
+              },
+              "pattern": {
+                "type": "string"
+              },
+              "language": {
+                "type": "string"
+              },
+              "fallbackLanguage": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "scripts": {
+    "build": "npm run pack:vsix",
+    "package": "vsce package",
+    "pack:npm": "npm pack --dry-run",
+    "pack:vsix": "vsce package",
+    "install:local": "bash scripts/cc-install-local.sh",
+    "reinstall": "npm run pack:vsix && npm run install:local",
+    "bump": "bash scripts/cc-npm-bump.sh",
+    "publish": "bash scripts/cc-npm-publish.sh",
+    "prepublishOnly": "npm run pack:npm"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fgirolami/cc-vscode-shebang-markdown.git"
+  },
+  "keywords": [
+    "vscode",
+    "vscode-extension",
+    "markdown",
+    "shebang",
+    "markdownlint",
+    "linter",
+    "language-detection",
+    "language-mode",
+    "developer-tools",
+    "codecorn"
+  ],
+  "author": {
+    "name": "Federico Girolami",
+    "email": "f.girolami@codecorn.it",
+    "url": "https://codecorn.it"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@vscode/vsce": "^3.9.2"
+  },
+  "files": [
+    "extension.js",
+    "README.md",
+    "README_IT.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "package.json",
+    "scripts/cc-install-local.sh",
+    "scripts/cc-npm-bump.sh",
+    "scripts/cc-npm-publish.sh"
+  ],
+  "sideEffects": false
+}

package/scripts/cc-install-local.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+set -euo pipefail
+
+PKG_NAME="$(node -p "require('./package.json').name")"
+VERSION="$(node -p "require('./package.json').version")"
+VSIX="${PKG_NAME}-${VERSION}.vsix"
+
+echo "===== CC LOCAL VSIX INSTALL ====="
+echo "PKG_NAME: $PKG_NAME"
+echo "VERSION:  $VERSION"
+echo "VSIX:     $VSIX"
+echo
+
+if [ ! -f "$VSIX" ]; then
+  echo "VSIX non trovato, genero package..."
+  npm run pack:vsix
+fi
+
+code --install-extension "$VSIX" --force

package/scripts/cc-npm-bump.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+set -euo pipefail
+
+BUMP="${1:-patch}"
+NO_COMMIT="${NO_COMMIT:-0}"
+
+if [ ! -f package.json ]; then
+  echo "ERRORE: package.json non trovato."
+  exit 1
+fi
+
+CURRENT_VERSION="$(node -p "require('./package.json').version")"
+PKG_NAME="$(node -p "require('./package.json').name")"
+
+echo "===== CC NPM BUMP ====="
+echo "PKG_NAME:        $PKG_NAME"
+echo "CURRENT_VERSION: $CURRENT_VERSION"
+echo "BUMP:            $BUMP"
+echo
+
+BACKUP_DIR=".cc-backups/npm-bump-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$BACKUP_DIR"
+cp -p package.json "$BACKUP_DIR/package.json"
+[ -f package-lock.json ] && cp -p package-lock.json "$BACKUP_DIR/package-lock.json"
+
+echo "Backup: $BACKUP_DIR"
+echo
+
+echo "===== VERSION UPDATE ====="
+npm version "$BUMP" --no-git-tag-version
+
+NEW_VERSION="$(node -p "require('./package.json').version")"
+
+echo
+echo "===== LOCK REFRESH ====="
+npm install --package-lock-only
+
+echo
+echo "===== INSTALL SCRIPT VERSION CHECK ====="
+node <<'NODE'
+const fs = require('fs');
+
+const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+const version = pkg.version;
+const name = pkg.name;
+
+if (!pkg.scripts) pkg.scripts = {};
+
+pkg.scripts['install:local'] = 'bash scripts/cc-install-local.sh';
+pkg.scripts['reinstall'] = 'npm run pack:vsix && npm run install:local';
+
+fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+
+console.log(`${name}@${version}`);
+NODE
+
+echo
+echo "===== GIT DIFF ====="
+git diff -- package.json package-lock.json || true
+
+if [ "$NO_COMMIT" = "1" ]; then
+  echo
+  echo "NO_COMMIT=1: commit saltato."
+else
+  echo
+  echo "===== GIT COMMIT ====="
+  git add package.json package-lock.json
+
+  if ! git diff --cached --quiet; then
+    git commit -m "chore: bump version to ${NEW_VERSION}"
+  else
+    echo "Nothing to commit."
+  fi
+fi
+
+echo
+echo "===== DONE ====="
+echo "${PKG_NAME}: ${CURRENT_VERSION} -> ${NEW_VERSION}"
+echo
+echo "Next:"
+echo "npm run publish"

package/scripts/cc-npm-publish.sh

@@ -0,0 +1,134 @@
+#!/bin/bash
+set -euo pipefail
+
+PKG_NAME="${PKG_NAME:-$(node -p "require('./package.json').name")}"
+VERSION="${VERSION:-$(node -p "require('./package.json').version")}"
+REMOTE_NAME="${REMOTE_NAME:-origin}"
+
+PUBLISH_NEEDED=1
+PUBLISH_OK=0
+NPM_AUTH_OK=0
+NPM_USER=""
+
+echo "===== PACKAGE META ====="
+echo "PKG_NAME: $PKG_NAME"
+echo "VERSION:  $VERSION"
+echo
+
+echo "===== NPM AUTH CHECK ====="
+if NPM_USER="$(npm whoami 2>/dev/null)"; then
+  NPM_AUTH_OK=1
+  echo "NPM_USER: $NPM_USER"
+else
+  NPM_AUTH_OK=0
+  echo "WARN: npm non è loggato oppure la sessione è scaduta."
+  echo "      Esegui: npm login"
+  echo "      Publish e tag verranno saltati, ma build/commit continuano."
+fi
+
+echo
+echo "===== INSTALL / LOCK REFRESH ====="
+npm install
+
+echo
+echo "===== VSIX BUILD ====="
+npm run pack:vsix
+
+echo
+echo "===== NPM PACK DRY RUN ====="
+npm run pack:npm
+
+echo
+echo "===== NPM VERSION CHECK ====="
+EXISTING_LATEST="$(npm view "$PKG_NAME" version 2>/dev/null || true)"
+EXISTING_THIS_VERSION="$(npm view "${PKG_NAME}@${VERSION}" version 2>/dev/null || true)"
+
+if [ -n "$EXISTING_LATEST" ]; then
+  echo "Package npm già esistente: $PKG_NAME"
+  echo "Latest npm version: $EXISTING_LATEST"
+else
+  echo "Package npm non ancora esistente: $PKG_NAME"
+fi
+
+if [ -n "$EXISTING_THIS_VERSION" ]; then
+  echo "Versione già pubblicata su npm: ${PKG_NAME}@${VERSION}"
+  echo "Publish non necessario."
+  PUBLISH_NEEDED=0
+else
+  echo "Versione pubblicabile: ${PKG_NAME}@${VERSION}"
+  PUBLISH_NEEDED=1
+fi
+
+echo
+echo "===== GIT COMMIT ====="
+git add package.json package-lock.json README.md README_IT.md CHANGELOG.md SECURITY.md CONTRIBUTING.md .npmignore .vscodeignore extension.js LICENSE scripts/cc-npm-publish.sh scripts/cc-npm-bump.sh scripts/cc-install-local.sh 2>/dev/null || true
+
+if ! git diff --cached --quiet; then
+  git commit -m "chore: prepare npm package ${VERSION}"
+else
+  echo "Nothing to commit."
+fi
+
+echo
+echo "===== GIT PUSH MAIN ====="
+if git remote get-url "$REMOTE_NAME" >/dev/null 2>&1; then
+  git push "$REMOTE_NAME" main
+else
+  echo "WARN: remote '$REMOTE_NAME' non configurato. Push main saltato."
+fi
+
+echo
+echo "===== NPM PUBLISH ====="
+if [ "$PUBLISH_NEEDED" = "0" ]; then
+  echo "SKIP: ${PKG_NAME}@${VERSION} è già pubblicato."
+  PUBLISH_OK=1
+elif [ "$NPM_AUTH_OK" != "1" ]; then
+  echo "SKIP: npm auth non disponibile."
+  echo
+  echo "Dopo login puoi rilanciare:"
+  echo "npm run publish"
+  PUBLISH_OK=0
+else
+  if npm publish; then
+    PUBLISH_OK=1
+    echo "OK: pubblicato ${PKG_NAME}@${VERSION}"
+  else
+    PUBLISH_OK=0
+    echo "WARN: npm publish fallito."
+    echo "      Possibili cause: sessione scaduta, 2FA/OTP, permessi package, nome già riservato."
+    echo "      Nessun tag git verrà creato."
+  fi
+fi
+
+echo
+echo "===== GIT TAG ====="
+if [ "$PUBLISH_OK" = "1" ]; then
+  TAG="v${VERSION}"
+
+  if git rev-parse "$TAG" >/dev/null 2>&1; then
+    echo "Tag già esistente localmente: $TAG"
+  else
+    git tag "$TAG"
+  fi
+
+  if git remote get-url "$REMOTE_NAME" >/dev/null 2>&1; then
+    git push "$REMOTE_NAME" "$TAG"
+  else
+    echo "WARN: remote '$REMOTE_NAME' non configurato. Push tag saltato."
+  fi
+else
+  echo "SKIP: tag saltato perché npm publish non è andato a buon fine."
+fi
+
+echo
+echo "===== DONE ====="
+echo "Package: ${PKG_NAME}@${VERSION}"
+
+if npm view "$PKG_NAME" version >/dev/null 2>&1; then
+  echo "NPM VERSION:"
+  npm view "$PKG_NAME" version
+  echo "NPM HOMEPAGE:"
+  npm view "$PKG_NAME" homepage 2>/dev/null || true
+else
+  echo "Npm package non ancora visibile/pubblicato."
+fi