==============================================================================
PUBLISHING GUIDE — Bridgetek EAB MCP Server Extension
How to build and publish the extension to the VS Code Marketplace
==============================================================================

This guide walks you through packaging the extension into a .vsix file and
publishing it to the Visual Studio Code Marketplace.

NOTE: The publisher "Bridgetek" is referenced throughout this guide. Replace
it with your own publisher name if you are not Bridgetek.

------------------------------------------------------------------------------
Table of contents
------------------------------------------------------------------------------
  1. Prerequisites
  2. Build the extension (.vsix)
  3. Verify the .vsix locally (optional)
  4. Create a publisher on the Marketplace
  5. Obtain a Personal Access Token (PAT)
  6. Log in with vsce
  7. Publish
  8. Manage and update a published extension
  9. Troubleshooting
  10. Quick reference

------------------------------------------------------------------------------
1. Prerequisites
------------------------------------------------------------------------------

- Node.js 18+ (https://nodejs.org/).
- A GitHub account (used to log in via @vscode/vsce).
- The extension project located at:  public/vscode
- Install the project dependencies:

    cd public/vscode
    npm install

- Verify the build tooling works before publishing:

    npm run compile          # TypeScript compile (extension.ts -> out/)
    npm run bundle:server    # esbuild-bundle the MCP server + copy spec

------------------------------------------------------------------------------
2. Build the extension (.vsix)
------------------------------------------------------------------------------

A .vsix is the distributable package file for a VS Code extension. To produce
it:

    cd public/vscode
    npm run package

This runs the "vscode:prepublish" script (compile + bundle:server) and then
packages everything into:

    public-vsix/bridgetek-eab-mcp-server-extension-0.0.4.vsix

The .vsix bundles:
  - out/extension.js            (the extension host entry point)
  - server/dist/index.js        (the bundled MCP server, self-contained ESM)
  - server/EAB_mcp_data.json    (the spec / command catalog)
  - scripts/eab-mcp-launcher.mjs, setup-codex.mjs, eab-mcp-server.cmd
                                (Codex onboarding: HTTP bridge registration + stdio fallback)
  - package.json, readme.md, changelog.md, LICENSE.txt, images/icon.png

To control the exact package target, you can also run:

    npx @vscode/vsce package --out public-vsix/

NOTE: The 'public-vsix/' directory must exist before packaging (the script
creates it for you). If you package with a custom --out path, create the
directory first.

------------------------------------------------------------------------------
3. Verify the .vsix locally (optional)
------------------------------------------------------------------------------

Install the built package into a local VS Code to smoke-test it before
publishing:

    code --install-extension public-vsix/bridgetek-eab-mcp-server-extension-0.0.4.vsix

Then reload VS Code, open the Command Palette, and confirm:

  - "EAB MCP server: Input eab_tools.exe" is available.
  - The MCP server is registered (MCP panel / Copilot Chat).
  - You are prompted to pick the eab_tools.exe path on activation.

To uninstall after testing:

    code --uninstall-extension Bridgetek.eab-mcp-server

------------------------------------------------------------------------------
4. Create a publisher on the Marketplace
------------------------------------------------------------------------------

The "publisher" is the identity under which your extensions are published. It
is set in package.json ("publisher": "Bridgetek") and must be unique across
the Marketplace.

1. Go to:  https://marketplace.visualstudio.com/manage
2. Sign in with your GitHub (or Microsoft) account.
3. Click "Create Publisher" and enter:
     - Display name   (e.g., "Bridgetek")
     - Identifier     (must match the "publisher" field in package.json, e.g. "Bridgetek")
   Upload a logo if desired.

------------------------------------------------------------------------------
5. Obtain a Personal Access Token (PAT)
------------------------------------------------------------------------------

vsce uses an Azure DevOps Personal Access Token to publish.

1. Go to:  https://dev.azure.com/Bridgetek
   (Or create a new organization if you do not have one.)
2. Open  "User settings"  (top-right avatar)  ->  "Personal Access Tokens".
3. Click "New Token".
4. Set:
     - Name:          eab-mcp-server-publish
     - Organization:  All accessible organizations
     - Expiration:    as desired (recommended <= 30 days)
     - Scopes:        "Marketplace" -> "Manage"
5. Click "Create" and COPY the token immediately. It is shown only once.

IMPORTANT SECURITY: Never share, commit, or paste this token. If it leaks,
revoke it immediately in the Azure DevOps portal.

------------------------------------------------------------------------------
6. Log in with vsce
------------------------------------------------------------------------------

Login once so vsce remembers your publisher + token:

    cd public/vscode
    npx @vscode/vsce login Bridgetek

When prompted, paste the Personal Access Token from step 5.

The token is stored in your user profile (~/.vsce/... on Windows:
C:\Users\<you>\.vsce\) and reused for later publishes.

------------------------------------------------------------------------------
7. Publish
------------------------------------------------------------------------------

From the project folder, run:

    cd public/vscode
    npm run publish

(Equivalent to:  npx @vscode/vsce publish)

This builds and uploads the extension. When it completes, vsce prints:

    DONE  Published: Bridgetek.eab-mcp-server <version>

Your extension then appears at:

    https://marketplace.visualstudio.com/items?itemName=Bridgetek.eab-mcp-server

------------------------------------------------------------------------------
8. Manage and update a published extension
------------------------------------------------------------------------------

- Update the version in package.json ("version": "0.0.4") before each publish.
  vsce refuses to publish a version that already exists.
- Update CHANGELOG.md and README.md — both are shown on the Marketplace page.
- Unpublish / remove an extension (caution: irreversible for existing users):

    npx @vscode/vsce unpublish Bridgetek.eab-mcp-server

  Consider deprecating instead:

    npx @vscode/vsce deprecate Bridgetek.eab-mcp-server "Reason..."

- Remove a deprecated notice:

    npx @vscode/vsce undeprecate Bridgetek.eab-mcp-server

------------------------------------------------------------------------------
9. Troubleshooting
------------------------------------------------------------------------------

- "Extension name ... does not match the expected value"
  Ensure the publisher in package.json exactly matches the Marketplace
  publisher you created.

- "Access Denied" when publishing
  The PAT scope must include "Marketplace: Manage". Recreate the token.

- "'public-vsix' is a directory, not a file"
  Ensure the target directory exists before running vsce package with a
  custom --out path.

- "Extension not showing tools in Copilot"
  The first run requires the user to trust the MCP server / enable it. Also,
  changing EAB_TOOLS_PATH requires reloading the window (the server env is
  resolved at registration/activation).

- Version already exists
  Bump package.json "version" and rebuild before republishing.

------------------------------------------------------------------------------
10. Quick reference
------------------------------------------------------------------------------

  cd public/vscode
  npm install                              # once
  npm run package                          # build .vsix
  code --install-extension public-vsix/bridgetek-eab-mcp-server-extension-0.0.4.vsix   # test
  npx @vscode/vsce login Bridgetek        # once, with PAT
  npm run publish                          # publish to Marketplace

  Marketplace page:  https://marketplace.visualstudio.com/items?itemName=Bridgetek.eab-mcp-server
  Publisher portal:  https://marketplace.visualstudio.com/manage
  PAT (Azure DevOps): https://dev.azure.com/Bridgetek

==============================================================================
END OF GUIDE
==============================================================================
