diff --git a/.assets/screenshots/README.md b/.assets/screenshots/README.md new file mode 100644 index 0000000..90d4a48 --- /dev/null +++ b/.assets/screenshots/README.md @@ -0,0 +1,24 @@ +# Screenshots + +README and marketplace imagery. Kept here rather than in `media/` because `media/` +ships inside the `.vsix` (the extension icon lives there) and these do not — +`.assets/**` is `.vscodeignore`d. + +README links these with **absolute** `raw.githubusercontent.com` URLs pinned to +`develop`. Verified: `vsce` passes absolute URLs through unchanged, while it +rewrites relative ones to a base that is not guaranteed to match this repo's +default branch. + +| File | Used for | +|---|---| +| `overview.png` | Hero. Explorer file tree, the Fallout Build dock, and the graph in one frame. | +| `targets-and-source.png` | Build view — the `DependsOn` chain in the tree beside the C# that declares it. | +| `run-configuration.png` | Run Configuration — a parameter and a secret, with the keychain note visible. | +| `run-a-target.png` | Run a target — ▶ from the tree, ending on Fallout's green summary table. | + +## Capturing + +Extension Development Host (F5) with this repository open — it builds with +Fallout, so the graph is already populated. Dark theme, to match the banner. Crop to +the panel plus a little context; roughly 1000–1400px wide reads best, and a 2× retina +capture scaled down is sharpest. diff --git a/.assets/screenshots/overview.png b/.assets/screenshots/overview.png new file mode 100644 index 0000000..b4586fb Binary files /dev/null and b/.assets/screenshots/overview.png differ diff --git a/.assets/screenshots/run-a-target.png b/.assets/screenshots/run-a-target.png new file mode 100644 index 0000000..c6b7409 Binary files /dev/null and b/.assets/screenshots/run-a-target.png differ diff --git a/.assets/screenshots/run-configuration.png b/.assets/screenshots/run-configuration.png new file mode 100644 index 0000000..ac912ce Binary files /dev/null and b/.assets/screenshots/run-configuration.png differ diff --git a/.assets/screenshots/targets-and-source.png b/.assets/screenshots/targets-and-source.png new file mode 100644 index 0000000..94563df Binary files /dev/null and b/.assets/screenshots/targets-and-source.png differ diff --git a/README.md b/README.md index 66391bc..778a389 100644 --- a/README.md +++ b/README.md @@ -2,21 +2,66 @@ Explore, run, and visualize your [Fallout](https://github.com/Fallout-build/Fallout) (the NUKE successor) build targets without leaving the editor. +Your build is a C# console app. This makes it feel like part of the IDE: every target listed, one click to run, go-to-definition onto the `Target X => …` declaration, and the whole dependency graph as a diagram. + +![The Fallout Build view docked in the Explorer, beside the build graph](https://raw.githubusercontent.com/Fallout-build/Fallout.Extensions.VSCode/develop/.assets/screenshots/overview.png) + ## Features -- **Targets view** — a dedicated Fallout container in the activity bar lists every build target, with the default target and each target's relations (`depends on`, `runs after`, `triggered by`, `triggers`) as expandable children. -- **Run a target** — inline ▶ on any target runs it in an integrated terminal (`./build.ps1` on Windows, `./build.sh` elsewhere). -- **Go to definition** — jump straight to the `Target X => ...` C# declaration; disambiguated by declaring type when several components declare the same name. -- **Build graph** — a Mermaid diagram of the whole dependency graph; click a node to run that target. -- Auto-refreshes as the build graph changes. +### Build view + +A dedicated Fallout container in the activity bar lists every target in the build. The default target is marked, unlisted targets are dimmed, and each target's relations — `depends on`, `runs after`, `triggered by`, `triggers` — expand as children, recursively, so you can walk the graph in either direction. + +The same tree is also docked in the **Explorer**, collapsed by default, for when you don't want to leave the file tree. + +![Targets expanded to show their dependencies, beside the C# that declares them](https://raw.githubusercontent.com/Fallout-build/Fallout.Extensions.VSCode/develop/.assets/screenshots/targets-and-source.png) + +The tree is a view of your C#: expanding `PackVsix` shows the `DependsOn` chain exactly as the build declares it. + +### Run a target + +Inline ▶ on any target runs it in an integrated terminal — `./build.ps1` on Windows, `./build.sh` elsewhere. **Run Target with Parameters…** runs the same target with your saved run configuration applied. + +![Running PackVsix from the tree, with Fallout's summary table in the terminal](https://raw.githubusercontent.com/Fallout-build/Fallout.Extensions.VSCode/develop/.assets/screenshots/run-a-target.png) + +### Run Configuration + +A form for the parameters and secrets your build takes: + +- **Parameters** are passed as `--name value` arguments and stored per workspace. +- **Secrets** are stored in VS Code's [SecretStorage](https://code.visualstudio.com/api/references/vscode-api#SecretStorage) — OS keychain-backed — and passed as **environment variables**, so they never reach your shell history, the process list, or a log. Values are never rendered back into the view; only names are. + +![The Run Configuration view with a parameter and a secret](https://raw.githubusercontent.com/Fallout-build/Fallout.Extensions.VSCode/develop/.assets/screenshots/run-configuration.png) + +### Go to definition + +Jump straight to the `Target X => …` C# declaration. Uses the C# language service when it's warmed up and falls back to a workspace scan, and disambiguates by declaring type when several components declare a target of the same name. + +### Build graph + +A Mermaid diagram of the whole dependency graph, with the same edge semantics as the framework's own `--plan` output — solid for an execution dependency, dashed for an order dependency, thick for a trigger. Click any node to run that target. + +Everything auto-refreshes as the build graph changes, so a target you add shows up as soon as the build re-runs. ## Requirements -**Fallout 10.4.0 or later.** The extension reads a `build-graph.json` that the Fallout build writes into `.fallout/temp/` (or the legacy `.nuke/temp/`) on every build initialization — the emission landed in 10.4.0, so older framework versions produce no graph at all. Run the build once (e.g. `./build.ps1 --plan`) to generate it. +**Fallout 10.4.0 or later.** The extension reads a `build-graph.json` that the Fallout build writes into `.fallout/temp/` (or the legacy `.nuke/temp/`) on every build initialization. Emission landed in 10.4.0, so older versions produce no graph at all and the views stay empty. + +Run the build once to generate it: + +```bash +./build.sh --plan # ./build.ps1 --plan on Windows +``` + +## Settings + +| Setting | Default | What it does | +|---|---|---| +| `fallout.deployment.enabled` | `false` | Shows the **Deployment** view. Off by default — the continuous-delivery graph isn't emitted by any released Fallout version yet, so the view can only show a placeholder. Turn it on to follow the work. | ## Versioning -The extension's `major.minor` track the Fallout framework release line it targets — 10.4.x builds against Fallout 10.4 — while the patch moves independently. A mismatch between the extension and the framework your workspace builds with surfaces as a non-blocking warning. +The extension's `major.minor` track the Fallout release line it targets — 10.4.x builds against Fallout 10.4 — while the patch moves independently. A mismatch between the extension and the framework your workspace builds with surfaces as a non-blocking warning. Versions are computed by [Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning) from `version.json`, the same as the framework itself; the build fails if the declared line drifts from the Fallout version it actually references. Release candidates are published as GitHub pre-releases only. diff --git a/package-lock.json b/package-lock.json index 3a596f3..93c05db 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "fallout", - "version": "2026.1.0", + "version": "0.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "fallout", - "version": "2026.1.0", + "version": "0.0.0", "license": "MIT", "dependencies": { "mermaid": "^11.4.1" @@ -309,9 +309,9 @@ } }, "node_modules/@mermaid-js/parser": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.2.0.tgz", - "integrity": "sha512-oYPyv8A4As1yH5Bx+04iQEQxXuIQDe0GKCNSRgao6z8AM9jixXIfP0vsppRLvGf+nKIOb9/LdpWA4YuJiVvESA==", + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.2.1.tgz", + "integrity": "sha512-n12NohV3mrUyUL2o93IgG/ifeW9FTyeJn3zDxkhwa8MJ9Fxg3HQMlA3RiGmD/3UnJvheztkjjQAjA2T4LmUcpw==", "license": "MIT", "dependencies": { "@chevrotain/types": "~11.1.2" @@ -1615,16 +1615,16 @@ "license": "BSD-2-Clause" }, "node_modules/brace-expansion": { - "version": "5.0.7", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.7.tgz", - "integrity": "sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==", + "version": "5.0.9", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz", + "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==", "dev": true, "license": "MIT", "dependencies": { "balanced-match": "^4.0.2" }, "engines": { - "node": "18 || 20 || >=22" + "node": "20 || >=22" } }, "node_modules/braces": { @@ -2612,9 +2612,9 @@ } }, "node_modules/dompurify": { - "version": "3.4.12", - "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.12.tgz", - "integrity": "sha512-zQvGet8Z2sWbQhCmfFz/T5QWH2oBmjnqK3qvOjaqaNLrLEF912WamU+ohnTp0TCep/MFVHpdJuCZEdFOdTnEFg==", + "version": "3.4.15", + "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.15.tgz", + "integrity": "sha512-EUBjM+B+lkDE41iE82DDSCfkoPGfXx8IxFxPMjNzm/Uk4xDet77rTN9wqlxlVg71kK7XGuUMv6wUxJUwwv+Xyw==", "license": "(MPL-2.0 OR Apache-2.0)", "optionalDependencies": { "@types/trusted-types": "^2.0.7" @@ -2830,9 +2830,9 @@ } }, "node_modules/fast-uri": { - "version": "3.1.3", - "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.3.tgz", - "integrity": "sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg==", + "version": "3.1.7", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.7.tgz", + "integrity": "sha512-dOvZVzjdZdz7phd9v6jCbwxrBW3fK6n8Rc0CtdmM4bumzMnxywBYhuph6J819RRw/ku+rLbelwfMunktuzVVHg==", "dev": true, "funding": [ { @@ -2846,6 +2846,15 @@ ], "license": "BSD-3-Clause" }, + "node_modules/fastdom": { + "version": "1.0.12", + "resolved": "https://registry.npmjs.org/fastdom/-/fastdom-1.0.12.tgz", + "integrity": "sha512-LB+xjSTEbjHE1cWsxu+tN2Xqr1kpi+V9aADI7sVM5ZMaXyYGPHULQMzpJMYqOTULK/73pUkWVzzObFRBkPr+hg==", + "license": "MIT", + "dependencies": { + "strictdom": "^1.0.1" + } + }, "node_modules/fastq": { "version": "1.20.1", "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.20.1.tgz", @@ -3459,9 +3468,9 @@ "license": "MIT" }, "node_modules/js-yaml": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz", - "integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==", + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz", + "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==", "dev": true, "funding": [ { @@ -3796,26 +3805,27 @@ } }, "node_modules/mermaid": { - "version": "11.16.0", - "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.16.0.tgz", - "integrity": "sha512-Zvm3kbstgdpvIJPPItlL7fppIZ3kibvc1oZIGxdvk9t6UFz6flv+Jw7FtRGKwfcI8OckmH04LqG6LlS6X4B1pA==", + "version": "11.17.2", + "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.17.2.tgz", + "integrity": "sha512-V6K3C8EBdEsPFZXSKMJe6ppQOENxuHARr9GvHX4hh47lAbhMRD9qf4oEK7LoaRQxULMa80/qt5gHO73aCleBBg==", "license": "MIT", "dependencies": { "@braintree/sanitize-url": "^7.1.2", "@iconify/utils": "^3.0.2", - "@mermaid-js/parser": "^1.2.0", + "@mermaid-js/parser": "^1.2.1", "@types/d3": "^7.4.3", "@upsetjs/venn.js": "^2.0.0", - "cytoscape": "^3.33.3", + "cytoscape": "^3.34.0", "cytoscape-cose-bilkent": "^4.1.0", "cytoscape-fcose": "^2.2.0", "d3": "^7.9.0", "d3-sankey": "^0.12.3", "dagre-d3-es": "7.0.14", - "dayjs": "^1.11.20", + "dayjs": "^1.11.21", "dompurify": "^3.3.3", "es-toolkit": "^1.45.1", - "katex": "^0.16.45", + "fastdom": "1.0.12", + "katex": "^0.16.47", "khroma": "^2.1.0", "marked": "^16.3.0", "roughjs": "^4.6.6", @@ -4386,9 +4396,9 @@ } }, "node_modules/qs": { - "version": "6.15.3", - "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.3.tgz", - "integrity": "sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==", + "version": "6.16.0", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.16.0.tgz", + "integrity": "sha512-h6fhOIaRrID2CbEY2fqs+7t+UXZo+MLAnU5gRIq85uFtdiUPCdsApMlHhXogKVM4HM2DVbIjGNTTYH2OcmP1vA==", "dev": true, "license": "BSD-3-Clause", "dependencies": { @@ -4871,6 +4881,12 @@ "dev": true, "license": "CC0-1.0" }, + "node_modules/strictdom": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/strictdom/-/strictdom-1.0.1.tgz", + "integrity": "sha512-cEmp9QeXXRmjj/rVp9oyiqcvyocWab/HaoN4+bwFeZ7QzykJD6L3yD4v12K1x0tHpqRqVpJevN3gW7kyM39Bqg==", + "license": "MIT" + }, "node_modules/string_decoder": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz", @@ -5231,9 +5247,9 @@ "license": "MIT" }, "node_modules/undici": { - "version": "7.28.0", - "resolved": "https://registry.npmjs.org/undici/-/undici-7.28.0.tgz", - "integrity": "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==", + "version": "7.29.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.29.1.tgz", + "integrity": "sha512-RYONW2MeafgYlkVOKYKkA/Ag7BmXqgIWCa8t1m0JcxrQg9pI9lEqRhAOruOBCbAohOa/gkCF+iPi9hrgvTzu6Q==", "dev": true, "license": "MIT", "engines": { diff --git a/package.json b/package.json index b5dd1d4..785b2c7 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,10 @@ "publisher": "fallout", "license": "MIT", "icon": "media/icon.png", + "galleryBanner": { + "color": "#0d0d0f", + "theme": "dark" + }, "engines": { "vscode": "^1.85.0" }, @@ -59,7 +63,8 @@ "id": "fallout.deployment", "name": "Deployment", "icon": "media/fallout.svg", - "contextualTitle": "Fallout" + "contextualTitle": "Fallout", + "when": "config.fallout.deployment.enabled" }, { "id": "fallout.runConfig", @@ -79,6 +84,16 @@ } ] }, + "configuration": { + "title": "Fallout", + "properties": { + "fallout.deployment.enabled": { + "type": "boolean", + "default": false, + "markdownDescription": "Show the **Deployment** view. Off by default: the continuous-delivery graph (channels \u2192 environments \u2192 targets) is not emitted by any released Fallout version yet, so the view can only show its placeholder. Turn it on to follow the work." + } + } + }, "viewsWelcome": [ { "view": "fallout.build", @@ -90,7 +105,7 @@ }, { "view": "fallout.deployment", - "contents": "No deployment graph yet.\nThe continuous-delivery model (channels → environments → targets) is emitted by a later Fallout build (ADR-0009). This view lights up once the framework writes a `deployment-graph.json`." + "contents": "No deployment graph yet.\nThe continuous-delivery model (channels \u2192 environments \u2192 targets) is emitted by a later Fallout build (ADR-0009). This view lights up once the framework writes a `deployment-graph.json`." } ], "commands": [ @@ -108,7 +123,7 @@ }, { "command": "fallout.runTargetWithParameters", - "title": "Run Target with Parameters…", + "title": "Run Target with Parameters\u2026", "category": "Fallout", "icon": "$(run-all)" },