Metadata-Version: 2.4
Name: vscx
Version: 0.1.0
Summary: A thin package manager for VS Code extensions distributed via GitHub Releases / VSIX URLs
Keywords: vscode,extension,vsix,package-manager,cli,marketplace,github-releases
Author: Kenji Sato
Author-email: Kenji Sato <mail@kenjisato.jp>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Dist: typer>=0.12
Requires-Dist: platformdirs>=4.0
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/kenjisato/vscx
Project-URL: Repository, https://github.com/kenjisato/vscx
Project-URL: Issues, https://github.com/kenjisato/vscx/issues
Description-Content-Type: text/markdown

# vscx

A thin package manager for Visual Studio Code (VS Code) extensions.

`vscx` lets you install and update VS Code extensions that are distributed as
`.vsix` files via **GitHub Releases** (or a direct URL) with the same
one-command ease you get for Marketplace extensions — without publishing to the
Marketplace. It is handy while an extension is still in development (pre-release)
and for keeping the same extensions in sync across several machines.

`vscx` does not replace VS Code. Marketplace install/list/update is delegated to
the editor CLI; `vscx` adds source management and an install ledger for
GitHub / URL / local-VSIX extensions. It also works with VS Code forks
(Cursor, Positron, VSCodium, Windsurf) — see *Editors* below.

> Requires your editor's CLI (`code` by default) on your PATH. Run `vscx doctor` to check.

## Install

```bash
uv tool install vscx
# Restart the terminal if `vscx` is not found.
```

## Quick start (single extension)

If you author an extension and distribute it via GitHub Releases, put these
lines in your repository's README and your users are done:

```bash
# install the latest pre-release build
vscx install github:OWNER/REPO --pre-release

# update it later
vscx update REPO        # short name, e.g. "shakyo"
```

No config file is needed for this. Other ways to specify what to install:

| Target                          | Meaning                                  |
| ------------------------------- | ---------------------------------------- |
| `publisher.extension`           | Marketplace extension (latest)           |
| `publisher.extension@version`   | Marketplace extension, pinned version    |
| `github:owner/repo`             | latest release's `.vsix` on GitHub       |
| `github:owner/repo@tag`         | a specific release tag (pinned)          |
| `https://.../something.vsix`    | a direct VSIX URL                        |
| `path/to/something.vsix`        | a local VSIX file                        |

Private repositories: set `GITHUB_TOKEN`.

```bash
GITHUB_TOKEN=... vscx install github:owner/private-repo
```

### Local build (extension author inner loop)

```bash
npx @vscode/vsce package
vscx install --local        # installs the newest *.vsix in the current dir (--force)
```

`vscx install ./shakyo-0.1.0.vsix` installs a specific file. Local installs are
never auto-updated and your `.vsix` file is never deleted.

## Channels (stable / pre-release)

`vscx` has two channels, mirroring VS Code's own `--pre-release`:

- **stable** — releases not marked *pre-release* on GitHub
- **pre-release** — the newest release, including ones marked *pre-release*

The channel for a command is decided in this order (first wins):

1. `@tag` / `@version` (exact pin — ignores channel)
2. `--pre-release` / `--stable` on the command
3. per-extension `channel` in `vscx.toml`
4. the machine default (`vscx default`)
5. built-in default: `stable`

Set the machine default once per machine (like `rustup default`):

```bash
vscx default              # show current default
vscx default pre-release  # e.g. on your dev machine
vscx default stable
```

## Updating

```bash
vscx update shakyo                  # one (or more) by name
vscx update --all                   # all GitHub extensions + Marketplace
vscx update                         # same as --all
vscx update --pre-release           # only pre-release-tracked extensions
vscx update --owner kenjisato       # only github:kenjisato/* extensions
```

Each GitHub extension is updated along the channel it was installed on. `update`
does not change channels — to switch, re-install with `--stable` / `--pre-release`.
Tag-pinned extensions are never auto-updated. Marketplace extensions are updated
via `code --update-extensions`, and only when updating everything.

## Multiple extensions / multiple machines (manifest)

For an extension *set* — shared across machines, or distributed by a teacher /
team — declare it in a `vscx.toml` manifest. Like `pip install -r`, the manifest
is **always specified explicitly** with `--file <path>`; vscx never auto-reads a
`vscx.toml` from the current directory.

```toml
[marketplace]
extensions = [
  "ms-python.python",
  "charliermarsh.ruff@0.5.0",   # @version pins a version
]

[github]
extensions = [
  "someone/their-extension",                                    # follows the default channel
  { repo = "kenjisato/my-extension", channel = "pre-release" }, # track pre-release for your own
  { repo = "kenjisato/frozen-tool", tag = "v0.0.3" },           # pin a tag
]

[vsix]
urls = ["https://example.com/some-extension.vsix"]
```

```bash
vscx install --file ./vscx.toml                    # a project/repo manifest
vscx install --file ~/dotfiles/vscx.toml           # your own fleet (keep it in dotfiles)
vscx install --file ./vscx.toml --pre-release      # force a channel for this run
vscx install --file ./vscx.toml --profile course   # into a VS Code profile
```

Manifest install only **adds/updates**; it never removes extensions not listed
(there is no `prune`). Keep the manifest wherever you like (e.g. dotfiles) and
point `--file` at it; each machine picks its own channel with `vscx default`, so
a dev machine can track pre-release while others stay on stable. After the first
install, keep extensions current with `vscx update`.

## Removing extensions

By default vscx removes only what it installed (its ledger). Extensions you
installed another way (VS Code UI, plain `code`) need `--force`.

```bash
vscx uninstall <extension-id | github:owner/repo | url>  # one vscx-installed extension
vscx uninstall some.ext --force                          # remove something vscx didn't install
vscx uninstall --file ./vscx.toml                        # the manifest's set (tracked entries)
vscx uninstall --all                                     # everything vscx tracks (the ledger)
```

## Editors (VS Code forks)

vscx's local/GitHub/URL `.vsix` installs are gallery-agnostic, so they work on
any VS Code fork whose CLI accepts `--install-extension`. Pick the editor CLI
(no auto-detection; default is `code`):

```bash
vscx --editor cursor install github:owner/repo   # per-invocation
export VSCX_EDITOR=codium                         # per-shell
# or set `editor = "positron"` in config.toml (see `vscx path`)
```

Marketplace-id installs on a fork resolve against its gallery (often Open VSX);
the `.vsix` paths above are unaffected.

## Other commands

```bash
vscx list [--show-versions] [--profile NAME]   # delegates to code --list-extensions
vscx doctor                                    # environment diagnostics
vscx path                                       # show resolved file locations
```

## Files

`vscx` stores data in OS-standard locations (via `platformdirs`); run
`vscx path` to see the resolved paths:

- `vscx.toml` — which extensions to install (a manifest; keep it anywhere and
  pass it with `--file`; share it)
- `config.toml` — this machine's default channel and editor (`user_config_dir`; do not share)
- `state.json` — the install ledger (`user_state_dir`)

## Development

```bash
uv sync          # install deps (incl. dev group)
uv run pytest    # run the hermetic test suite (no network, no VS Code needed)
```

See [docs/SPEC.md](docs/SPEC.md) for the full specification.

> Note: `vscx` is unrelated to Microsoft's `@vscode/vsce` (the official
> extension *packaging* tool). vscx installs/manages extensions; `vsce` builds
> them.

## License

MIT — see [LICENSE](LICENSE).

## Trademarks

`vscx` is an independent project and is **not affiliated with, endorsed by, or
sponsored by Microsoft**. "Visual Studio Code" and "VS Code" are trademarks of
Microsoft Corporation; "Cursor", "Positron", "VSCodium", and "Windsurf" are
trademarks of their respective owners. These names are used only to describe
compatibility.
