@runfile/cli 0.40.0 → 0.42.0

package/README.md

@@ -1,6 +1,6 @@
 # Runfile
 
-[Quick start](#quick-start) · [Why Runfile?](#why-runfile) · [Features](#what-makes-it-different) · [Platforms](#platform-support) · [Docs](.github/DOCS.md)
+[Quick start](#quick-start) · [Why Runfile?](#why-runfile) · [Features](#what-makes-it-different) · [VS Code](#vs-code-extension) · [Platforms](#platform-support) · [Docs](.github/DOCS.md)
 
 **One JSON file. One binary. Every OS. Every shell.**
 
@@ -98,6 +98,30 @@ prints that command to run from a fresh shell (npm can't overwrite the running `
 
 ---
 
+## VS Code extension
+
+Every release ships a VS Code extension that puts your targets in the editor — no `tasks.json` to generate or keep
+in sync. It runs `run :generate task-descriptors` and turns the result into real VS Code tasks plus a
+**Runfile → Targets** sidebar, complete with namespace folders and a **Globals** bucket for machine-wide targets.
+
+**Install** — download `runfile-vscode-<version>.vsix` from the
+[latest release](https://github.com/JoaaoVerona/runfile/releases/latest), then:
+
+```bash
+code --install-extension runfile-vscode-<version>.vsix
+```
+
+(or, in VS Code: **Extensions → … → Install from VSIX…**)
+
+Targets then show up in **Terminal → Run Task…** and in the Runfile sidebar. Every task is invoked with
+`--stdin-args`, so targets that need input prompt for it right in the task terminal. Nothing is written to your
+repository.
+
+The source lives in [`editors/vscode`](editors/vscode) — see its [README](editors/vscode/README.md) for settings,
+commands, and how the sidebar groups targets.
+
+---
+
 ## Why Runfile?
 
 Other runners assume one platform and one shell. Runfile assumes **none**.
@@ -629,14 +653,9 @@ $ run :generate zed-tasks
 $ run :generate jetbrains-run-configurations
 ```
 
-Pass `--stdout` to any of these to print the generated configuration to standard output instead of
-writing it to disk — handy for previewing, piping, or diffing in CI. The output is the freshly
-generated config (not merged with any existing file on disk) and nothing is created or modified.
-For `jetbrains-run-configurations`, which produces one file per target, each block is delimited by a
-`<!-- .run/<file> -->` comment when more than one is emitted.
-
-By default only the local Runfile's own targets are generated. Two independent flags widen the set,
-and both compose with `--stdout` and the on-disk writers:
+Each writes its editor's config to disk (`.vscode/tasks.json`, `.zed/tasks.json`, `.run/*.run.xml`),
+merging with any existing file. By default only the local Runfile's own targets are generated; two
+independent flags widen the set:
 
 - `--include-namespaces` also generates entries for targets pulled in via `includes` — namespaced
   targets carry their `namespace:` prefixes, exactly as `run :list` shows them (e.g. `run api:build`).
@@ -644,6 +663,39 @@ and both compose with `--stdout` and the on-disk writers:
   `run :config global-files` — the same ones `run :list` folds in. Handy when an editor integration
   should offer your machine-wide targets (e.g. `run c`, `run backup-git`) alongside a project's own.
 
+##### Building your own integration: `task-descriptors`
+
+For tooling that builds its **own** editor integration (like the
+[Runfile VS Code extension](editors/vscode) shipped with this repo), there's an editor-agnostic
+alternative that always prints to stdout and never touches disk:
+
+```bash
+$ run :generate task-descriptors
+```
+
+It always resolves `includes` and merges registered global files (no `--include-*` flags), and emits
+a stable JSON document describing every runnable target grouped by its source file, with per-target
+provenance so a client can bucket local vs. included vs. global targets itself:
+
+```jsonc
+{
+  "formatVersion": 1,
+  "sources": [
+    {
+      "filePath": "/abs/path/Runfile.json",
+      "kind": "local",              // "local" | "included" | "global"
+      "targets": [
+        {
+          "name": "api:build",      // full canonical invocation name
+          "namespace": "api",       // omitted for un-namespaced targets
+          "description": "Build the API"
+        }
+      ]
+    }
+  ]
+}
+```
+
 Skip a target from the generated configs by setting `metadata.excludeFromGenerateCommand: true`. The
 `metadata` block on `globals` and on each target is **fully open** — any property of any JSON type
 (strings, numbers, booleans, arrays, deeply-nested objects) is accepted and round-trips untouched, so
@@ -747,6 +799,16 @@ run lint           # auto-format + clippy
 run test           # full workspace test suite
 ```
 
+The VS Code extension in [`editors/vscode`](editors/vscode) has its own targets, namespaced under `vscode:`:
+
+```bash
+run vscode:deps      # one-time: pnpm install (required before the targets below)
+run vscode:compile   # type-check + compile to editors/vscode/out
+run vscode:watch     # recompile on change
+run vscode:package   # build the .vsix
+run vscode:install   # package + install into VS Code
+```
+
 ---
 
 ## License

package/package.json

@@ -13,5 +13,5 @@
 	"license": "MIT",
 	"name": "@runfile/cli",
 	"repository": "https://github.com/JoaaoVerona/runfile",
-	"version": "0.40.0"
+	"version": "0.42.0"
 }