Marketplace prep: official icon, CHANGELOG, PUBLISHING guide, metadata (#16)

azizbecha · web-flow · commit a636bbbddf75 · 2026-05-03T22:59:11.000+01:00
- Replace the hand-rolled phone SVG with the official agent-device mark
  (purple #8232FF) from the agent-device docs site
- media/icon.png 128x128: official mark centered on #3b2860 (sampled
  from agent-device-banner.jpg), rendered via sharp
- galleryBanner.color updated to #3b2860 so the marketplace listing
  banner matches the icon background
- package.json: bump 0.0.1 -&gt; 0.1.0, add icon, keywords, homepage,
  bugs.url, galleryBanner, preview: true; drop "private": true so
  the marketplace will accept the package; tighten description
- CHANGELOG.md (Keep a Changelog) seeded with [0.1.0] release notes
- PUBLISHING.md: end-to-end ops guide — publisher creation, PAT,
  vsce login, release pipeline, smoke-install, pre-release flag,
  Open VSX mirror via ovsx, rollback strategy
- README: CI badge, MIT badge, links to LICENSE, CHANGELOG, PUBLISHING

Doesn't change runtime behavior. Open before publishing: register the
"agent-device" publisher (or whatever ID you settle on) at
marketplace.visualstudio.com and update package.json.publisher.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this extension will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-03
+
+Initial public release.
+
+### Authoring
+
+- TextMate grammar for `.ad` files (commands, `@eN` refs, flags, double-quoted strings, `${VAR}` interpolation, `#` comments).
+- Completion: top-level commands, command-scoped flags, `context` keys, `find` sub-actions.
+- Variable completion inside `${...}` (built-in `AD_*` plus `env`-defined names).
+- Element-ref (`@eN`) completion populated from the latest `snapshot -i` output.
+- Platform value completion + diagnostic for `--platform` / `context platform=`.
+- Hover docs for commands, directives, and flags.
+
+### Running
+
+- Run Output panel in the bottom container with a workspace-wide `.ad` file picker, live per-step status, expandable stdout / stderr / error blocks with copy buttons, and a Stop button that kills the in-flight subprocess.
+- CodeLenses on every action line: `▶ Run` (this line only) and `▶ Run up to here`.
+- Native gutter test icons via per-step `TestItem`s with ranges.
+- Test Explorer integration — runs from any entry point (panel, CodeLens, palette, native gutter) all reflect in the Testing view.
+- Status-bar pill + popup notifications on success / failure / cancellation.
+- Keybinding: `Ctrl+Shift+Enter` / `Cmd+Shift+Enter` runs the active `.ad`.
+
+### Templates
+
+- `+ New` opens a QuickPick of nine starter templates (empty, iOS / Android Settings smoke, login flow, search & assert, scroll & discover, swipe gestures, visual baseline, React Native + Metro).
+
+### Devices
+
+- Sidebar tree of every iOS simulator and Android AVD, grouped by platform with booted entries floated.
+- Boot / Shut down with inline icons, right-click, palette, and quick-pick fallbacks. iOS uses `xcrun simctl` directly; Android uses `emulator -avd` and `adb emu kill`.
+
+### Snapshot Inspector
+
+- Sidebar view with a tree of `@eN` refs from the most recent snapshot. Click a row to insert at the cursor; copy and search affordances built in.
+- `Refresh Snapshot` and `Clear Snapshot` commands wired to the view title.
+
+### Reports
+
+- Self-contained HTML run reports under `<workspace>/.agent-device-reports/<iso-timestamp>/index.html`. Sticky toolbar with search, status filter pills, expand-all toggle, per-step copy buttons, and prefers-color-scheme support.
+
+### Settings
+
+- Sidebar Settings panel with a User / Workspace scope toggle, source labels per field, and per-field reset.
+- `agentDevice.cliPath`, `session`, `androidSdkPath`, `report.enabled`, `notifications.enabled`.
+
+### Tooling
+
+- Strict TypeScript, oxlint + oxfmt, vitest unit tests for the parsers and helpers, GitHub Actions CI.
diff --git a/PUBLISHING.md b/PUBLISHING.md
@@ -0,0 +1,117 @@
+# Publishing to the VS Code Marketplace
+
+These steps assume the work that's already in this repo: the `package.json` `publisher`, `version`, `icon`, `keywords`, `repository`, `bugs`, `homepage`, `galleryBanner`, and `preview` fields are configured. The `LICENSE`, `README.md`, and `CHANGELOG.md` are present. CI is green on `main`.
+
+## One-time setup
+
+1. **Create a publisher**
+
+   Visit <https://marketplace.visualstudio.com/manage> and sign in with the Microsoft account that should own the listing. Click "Create publisher" and pick an ID. Update `package.json` `publisher` to match.
+
+   > Right now `package.json` has `"publisher": "agent-device"`. That string must match a publisher you (or your org) actually own on the marketplace.
+
+2. **Create a Personal Access Token (PAT)**
+
+   Go to <https://dev.azure.com> → User settings → Personal access tokens → New token.
+   - Organization: **All accessible organizations**
+   - Scopes: **Custom defined** → **Marketplace** → **Manage**
+   - Expiration: pick something you can rotate (90 days is the maximum)
+
+   Copy the token. It is shown once.
+
+3. **Log in `vsce` locally**
+
+   ```bash
+   npx vsce login <publisher>
+   # paste the PAT when prompted
+   ```
+
+   The token is cached under `~/.vsce`. You won't need to re-paste it for subsequent publishes from the same machine.
+
+## Each release
+
+1. **Bump the version** in `package.json` (semver). Update `CHANGELOG.md` to add a section for the new version and move items out of `[Unreleased]`.
+
+2. **Sanity check** — the same checks CI runs:
+
+   ```bash
+   npm run lint
+   npm run format:check
+   npm test
+   npm run compile
+   npm run package    # produces agent-device-vscode-<version>.vsix
+   ```
+
+3. **Smoke-install the `.vsix`** locally:
+
+   ```bash
+   code --install-extension agent-device-vscode-<version>.vsix
+   ```
+
+   Open a folder with `.ad` files, click the Agent Device tab, run a script.
+
+4. **Publish**:
+
+   ```bash
+   npx vsce publish
+   ```
+
+   Or, to bump and publish in one step:
+
+   ```bash
+   npx vsce publish patch
+   npx vsce publish minor
+   npx vsce publish major
+   ```
+
+   These bump `package.json` for you, commit the bump, and tag.
+
+5. **Tag and push** if you bumped manually:
+
+   ```bash
+   git tag v$(node -p "require('./package.json').version")
+   git push --tags
+   ```
+
+6. **Verify on the marketplace** at `https://marketplace.visualstudio.com/items?itemName=<publisher>.agent-device-vscode`.
+
+## Pre-release vs stable
+
+`package.json` currently has `"preview": true`. That marks the listing as a preview in the marketplace UI but does **not** make it a pre-release in the install-flow sense. To publish as a pre-release that only users opting into pre-releases see:
+
+```bash
+npx vsce publish --pre-release
+```
+
+When you're ready to flip to stable, drop `"preview": true` from `package.json` and run `npx vsce publish` (or `vsce publish minor` for a 1.0 push).
+
+## Open VSX (Cursor, VSCodium, code-server, …)
+
+VS Code Marketplace listings don't auto-mirror to Open VSX. To support Cursor and the other forks:
+
+1. Create an account at <https://open-vsx.org>.
+2. Generate an access token under your profile.
+3. Publish:
+
+   ```bash
+   npx ovsx publish agent-device-vscode-<version>.vsix --pat <token>
+   ```
+
+You can wire this into CI later (the `HaaLeo/publish-vscode-extension` GitHub Action handles both marketplaces from one workflow).
+
+## Rollback
+
+The marketplace doesn't support deleting a published version. To roll back:
+
+1. Bump the version (`patch` is fine).
+2. Revert the offending commit on `main`.
+3. `npx vsce publish patch` to ship the older code under the new version.
+
+## Known checks the marketplace runs
+
+- `package.json` must not have `"private": true` (we already removed it).
+- `LICENSE` must exist (it does; MIT).
+- `icon` must point to a 128×128 PNG (it does — `media/icon.png`, the official agent-device mark in `#8232FF` on the brand dark purple `#3b2860`).
+- The README, CHANGELOG, and LICENSE are bundled into the `.vsix` (default vsce behavior).
+
+If a publish fails, run `npx vsce ls` to inspect what's actually being included in the `.vsix` and `npx vsce package` to produce a local copy you can test.
diff --git a/README.md b/README.md
@@ -1,5 +1,8 @@
 # Agent Device for VS Code
 
+[![CI](https://github.com/azizbecha/agent-device-vscode/actions/workflows/ci.yml/badge.svg)](https://github.com/azizbecha/agent-device-vscode/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
 Author, run, and inspect [agent-device](https://incubator.callstack.com/agent-device) `.ad` scripts inside VS Code — Vitest-style.
 
 ![Agent Device for VS Code — overview](media/screenshots/overview.png)
@@ -106,6 +109,10 @@ examples/
 
 The runner spawns the `agent-device` CLI per step (so cancellation kills the in-flight subprocess immediately), parses `.ad` itself for variable interpolation and step-by-step events, and emits a typed event stream that every UI surface consumes.
 
+## Releases
+
+See [CHANGELOG.md](CHANGELOG.md). Publishing is documented in [PUBLISHING.md](PUBLISHING.md).
+
 ## License
 
-MIT.
+[MIT](LICENSE).
diff --git a/media/agent-device.svg b/media/agent-device.svg
@@ -1,5 +1,3 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
-  <rect x="6" y="2" width="12" height="20" rx="2.5" />
-  <line x1="11" y1="18.5" x2="13" y2="18.5" />
-  <circle cx="12" cy="9" r="2" />
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M18 21H6V3H18V21ZM8 19H16V5H8V19ZM4 17H2V15H4V17ZM13 17H11V15H13V17ZM22 17H20V15H22V17ZM2 15H0V13H2V15ZM24 15H22V13H24V15ZM4 13H2V11H4V13ZM22 13H20V11H22V13ZM2 11H0V9H2V11ZM24 11H22V9H24V11ZM4 9H2V7H4V9ZM22 9H20V7H22V9Z" fill="#8232FF"/>
 </svg>
diff --git a/media/icon.png b/media/icon.png
diff --git a/package.json b/package.json
@@ -1,20 +1,37 @@
 {
   "name": "agent-device-vscode",
   "displayName": "Agent Device",
-  "version": "0.0.1",
-  "private": true,
-  "description": "Author, run, and inspect agent-device .ad scripts inside VS Code.",
+  "version": "0.1.0",
+  "description": "Author, run, and inspect agent-device .ad scripts inside your IDE.",
   "categories": [
     "Other",
     "Programming Languages",
     "Testing"
   ],
+  "keywords": [
+    "ad",
+    "agent-device",
+    "android",
+    "appium",
+    "automation",
+    "e2e",
+    "ios",
+    "playwright",
+    "react-native",
+    "replay",
+    "simulator",
+    "testing"
+  ],
+  "homepage": "https://github.com/callstackincubator/agent-device#readme",
+  "bugs": {
+    "url": "https://github.com/callstackincubator/agent-device/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/azizbecha/agent-device-vscode"
+    "url": "https://github.com/callstackincubator/agent-device"
   },
-  "publisher": "agent-device",
+  "publisher": "azizbecha",
   "main": "./out/extension.js",
   "scripts": {
     "vscode:prepublish": "npm run compile",
@@ -262,6 +279,12 @@
     "onView:agentDevice.settings",
     "onView:agentDevice.snapshotInspector"
   ],
+  "icon": "media/icon.png",
+  "galleryBanner": {
+    "color": "#3b2860",
+    "theme": "dark"
+  },
+  "preview": true,
   "engines": {
     "vscode": "^1.95.0"
   }
