diff --git a/AGENTS.md b/AGENTS.md index 1de1f57..fc5173a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,7 +66,7 @@ Compilation is delegated to the project's own npm scripts rather than reimplemen ## Extension architecture -- **[`src/model.ts`](src/model.ts)** — the logic layer, near-free of UI: graph discovery (`findGraphFile` probes `.fallout/temp` then `.nuke/temp` across workspace folders), parsing, `checkCompatibility`, and `toMermaid`. The schema `version` is a **hard gate**; the extension-vs-framework `major.minor` comparison is a **soft warning**, deduplicated via a module-level `warned` set. +- **[`src/model.ts`](src/model.ts)** — the logic layer, near-free of UI: graph discovery (`findGraphFile` probes `.fallout/temp` then `.nuke/temp` across workspace folders), parsing, `checkCompatibility`, `toMermaid`, and `loadDeclarations` (declared parameters and verbosity levels for Run Configuration: `parameters[]` from the graph once Fallout#499 ships, otherwise `.fallout/build.schema.json`, where a `[Secret]` member is marked by a placeholder `default`). The schema `version` is a **hard gate**; the extension-vs-framework `major.minor` comparison is a **soft warning**, deduplicated via a module-level `warned` set. - **[`src/extension.ts`](src/extension.ts)** — tree data provider plus command registration. Relations (`dependsOn`, `after`, `triggeredBy`, `triggers`) render as recursively expandable children. A `**/build-graph.json` watcher refreshes both tree and panel; parse failures during refresh are swallowed deliberately, because the build may be mid-write and the next watcher event re-reads it. - **[`src/goToTarget.ts`](src/goToTarget.ts)** — C# workspace symbol provider first (precise, needs Roslyn warmed up), regex scan over `**/*.cs` as fallback. `declaredIn` from the graph disambiguates same-named targets declared across component interfaces. - **[`src/graphPanel.ts`](src/graphPanel.ts)** — singleton webview, CSP-locked with a nonce, `localResourceRoots` scoped to Mermaid's `dist`. Talks to the page via `ready` / `graph` / `run` messages. diff --git a/README.md b/README.md index 778a389..7573b47 100644 --- a/README.md +++ b/README.md @@ -26,10 +26,11 @@ Inline ▶ on any target runs it in an integrated terminal — `./build.ps1` on ### Run Configuration -A form for the parameters and secrets your build takes: +A form for the parameters and secrets your build takes. Everything the build declares is listed up front, read from the `build.schema.json` the build writes on every run, so `NuGetApiKey` and its peers appear without typing. Free-form rows remain for anything else. - **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. +- **Verbosity** is a drop-down of the levels your Fallout version supports (`Information` on 10.5+). +- **Secrets** read *not set* until you enter a value. They 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) diff --git a/src/extension.ts b/src/extension.ts index c28d0b1..73a87a1 100644 --- a/src/extension.ts +++ b/src/extension.ts @@ -1,5 +1,5 @@ import * as vscode from 'vscode'; -import { BuildGraph, GraphSource, Relation, Target, checkCompatibility, findGraphFile, loadGraph } from './model'; +import { BuildGraph, GraphSource, Relation, Target, checkCompatibility, findGraphFile, loadDeclarations, loadGraph } from './model'; import { GraphPanel } from './graphPanel'; import { goToTarget } from './goToTarget'; import { RunConfigStore, RunConfigViewProvider } from './runConfig'; @@ -163,8 +163,14 @@ export function activate(context: vscode.ExtensionContext): void { runInTerminal(root, edited, await runConfig.buildEnv()); }; + const runConfigView = new RunConfigViewProvider( + runConfig, + context.subscriptions, + () => loadDeclarations(workspaceRoot(), provider.graph)); + const refreshAll = () => { provider.refresh(); + runConfigView.refreshDeclarations(); const source = findGraphFile(); if (source) { try { @@ -180,14 +186,21 @@ export function activate(context: vscode.ExtensionContext): void { watcher.onDidCreate(refreshAll); watcher.onDidDelete(() => provider.refresh()); + // The build rewrites build.schema.json on every initialization, next to the graph. + const schemaWatcher = vscode.workspace.createFileSystemWatcher('**/build.schema.json'); + schemaWatcher.onDidChange(() => runConfigView.refreshDeclarations()); + schemaWatcher.onDidCreate(() => runConfigView.refreshDeclarations()); + schemaWatcher.onDidDelete(() => runConfigView.refreshDeclarations()); + context.subscriptions.push( // Same provider instance backs both the Fallout-container Build view and the // mirrored Explorer dock — one graph, two homes; refresh() updates both. vscode.window.registerTreeDataProvider('fallout.build', provider), vscode.window.registerTreeDataProvider('fallout.buildExplorer', provider), vscode.window.registerTreeDataProvider('fallout.deployment', new DeploymentProvider()), - vscode.window.registerWebviewViewProvider('fallout.runConfig', new RunConfigViewProvider(runConfig, context.subscriptions)), + vscode.window.registerWebviewViewProvider('fallout.runConfig', runConfigView), watcher, + schemaWatcher, vscode.commands.registerCommand('fallout.refreshTargets', refreshAll), vscode.commands.registerCommand('fallout.runTarget', (item?: TargetItem) => { if (item?.target) { diff --git a/src/model.ts b/src/model.ts index 3a33dff..5eb983a 100644 --- a/src/model.ts +++ b/src/model.ts @@ -19,11 +19,30 @@ export interface Target { triggers: string[]; } +/** A declared build parameter: `parameters[]` in build-graph.json (Fallout#499) or a property of build.schema.json. */ +export interface ParameterDecl { + name: string; + description?: string; + secret: boolean; + /** Allowed values, when the parameter is an enumeration or has a value set. */ + values?: string[]; + declaredIn?: string; +} + +/** What the build declares, for the Run Configuration view. */ +export interface BuildDeclarations { + parameters: ParameterDecl[]; + /** Verbosity levels the running Fallout version supports; empty when unknown. */ + verbosityLevels: string[]; +} + /** Parsed contents of build-graph.json. */ export interface BuildGraph { version: number; falloutVersion?: string; targets: Target[]; + /** Additive, once the framework emits it (Fallout#499). */ + parameters?: ParameterDecl[]; } /** Where the graph was found: the workspace root plus the absolute file path. */ @@ -79,6 +98,61 @@ export function loadGraph(source: GraphSource): BuildGraph { return JSON.parse(fs.readFileSync(source.file, 'utf8')); } +const SCHEMA_LOCATIONS = ['.fallout/build.schema.json', '.nuke/build.schema.json']; + +/** The framework writes this placeholder as the `default` of every `[Secret]` parameter. */ +const SECRET_DEFAULT_MARKER = 'Secrets must be entered via'; + +/** + * What the build declares: `parameters[]` from the graph when the framework emits it, otherwise + * the `[Parameter]` members in build.schema.json (the build writes it next to the graph on every + * initialization). Empty when neither exists, which leaves Run Configuration free-form. + */ +export function loadDeclarations(root: string | undefined, graph?: BuildGraph): BuildDeclarations { + const schema = readSchema(root); + return { + parameters: graph?.parameters ?? parametersFromSchema(schema), + verbosityLevels: schema?.definitions?.Verbosity?.enum ?? [], + }; +} + +function readSchema(root: string | undefined): any { + const file = root + ? SCHEMA_LOCATIONS.map(rel => path.join(root, ...rel.split('/'))).find(f => fs.existsSync(f)) + : undefined; + if (!file) { + return undefined; + } + try { + return JSON.parse(fs.readFileSync(file, 'utf8')); + } catch { + return undefined; // the build may be mid-write; the next watcher event re-reads it + } +} + +// Shape: { definitions, allOf: [ , { $ref: FalloutBuild } ] }. Only the first +// part holds declared parameters; the framework's own (Target, Skip, Verbosity, ...) are not run inputs. +function parametersFromSchema(schema: any): ParameterDecl[] { + const properties: Record = schema?.allOf?.[0]?.properties ?? {}; + return Object.entries(properties) + .map(([name, p]): ParameterDecl => { + const resolved = resolveRef(schema, p); + const values = resolved.enum ?? resolved.items?.enum ?? resolveRef(schema, resolved.items).enum; + return { + name, + description: p.description ?? resolved.description, + secret: typeof p.default === 'string' && p.default.startsWith(SECRET_DEFAULT_MARKER), + values: Array.isArray(values) && values.length > 0 ? values : undefined, + }; + }) + .sort((a, b) => a.name.localeCompare(b.name)); +} + +function resolveRef(schema: any, node: any): any { + const ref: string | undefined = node?.$ref; + return ref?.startsWith('#/definitions/') ? schema?.definitions?.[ref.slice('#/definitions/'.length)] ?? {} : node ?? {}; +} + /** * Builds the Mermaid flowchart definition. Same edge semantics as the --plan HTML: * solid = execution dependency, dashed = order dependency, thick = trigger. diff --git a/src/runConfig.ts b/src/runConfig.ts index df1a27c..6950c70 100644 --- a/src/runConfig.ts +++ b/src/runConfig.ts @@ -1,4 +1,5 @@ import * as vscode from 'vscode'; +import { BuildDeclarations } from './model'; /** A build parameter passed to a local run as `--name value`. */ export interface Parameter { @@ -27,16 +28,20 @@ export class RunConfigStore { return this.context.workspaceState.get(PARAMS_KEY, []); } + /** Names compare ignoring case, like the framework's argument parser. A blank value clears the parameter. */ async setParameter(name: string, value: string): Promise { - const params = this.getParameters().filter(p => p.name !== name); - params.push({ name, value }); + const key = name.trim().toLowerCase(); + const trimmed = value.trim(); + const params = this.getParameters().filter(p => p.name.toLowerCase() !== key); + if (trimmed !== '') { params.push({ name: name.trim(), value: trimmed }); } params.sort((a, b) => a.name.localeCompare(b.name)); await this.context.workspaceState.update(PARAMS_KEY, params); this.onDidChangeEmitter.fire(); } async removeParameter(name: string): Promise { - await this.context.workspaceState.update(PARAMS_KEY, this.getParameters().filter(p => p.name !== name)); + const key = name.trim().toLowerCase(); + await this.context.workspaceState.update(PARAMS_KEY, this.getParameters().filter(p => p.name.toLowerCase() !== key)); this.onDidChangeEmitter.fire(); } @@ -61,6 +66,7 @@ export class RunConfigStore { /** Parameters rendered as a CLI argument string, e.g. `--configuration Release`. */ buildArgs(): string { return this.getParameters() + .filter(p => p.value.trim() !== '') .map(p => `--${p.name} ${quoteArg(p.value)}`) .join(' '); } @@ -82,13 +88,17 @@ function quoteArg(value: string): string { return /\s/.test(value) ? `"${value.replace(/"/g, '\\"')}"` : value; } -/** The "Run Configuration" webview view — a form for parameters and secret names. */ +/** + * The "Run Configuration" webview view — a form for parameters and secrets. Members the build + * declares are listed up front; free-form rows remain for anything else. + */ export class RunConfigViewProvider implements vscode.WebviewViewProvider { private view: vscode.WebviewView | undefined; constructor( private readonly store: RunConfigStore, disposables: vscode.Disposable[], + private readonly getDeclarations: () => BuildDeclarations, ) { disposables.push(this.store.onDidChange(() => this.postState())); } @@ -119,11 +129,17 @@ export class RunConfigViewProvider implements vscode.WebviewViewProvider { }); } + /** Re-reads what the build declares (called when the graph or schema file changes). */ + refreshDeclarations(): void { + this.postState(); + } + private postState(): void { void this.view?.webview.postMessage({ type: 'state', parameters: this.store.getParameters(), secretNames: this.store.getSecretNames(), + declared: this.getDeclarations(), }); } @@ -148,11 +164,20 @@ export class RunConfigViewProvider implements vscode.WebviewViewProvider { .name { flex: 0 0 40%; font-family: var(--vscode-editor-font-family); } .hint { opacity: 0.65; font-size: 11px; margin: 2px 0 8px; } .secret-val { font-family: var(--vscode-editor-font-family); opacity: 0.6; } + .secret-val.unset { font-style: italic; } + select { flex: 1 1 auto; min-width: 0; background: var(--vscode-dropdown-background); color: var(--vscode-dropdown-foreground); + border: 1px solid var(--vscode-dropdown-border, transparent); padding: 3px 6px; border-radius: 2px; } + +

Parameters

-
Passed to local runs as --name value.
+
Passed to local runs as --name value. Empty values are not passed.
+
@@ -162,6 +187,7 @@ export class RunConfigViewProvider implements vscode.WebviewViewProvider {

Secrets

Stored in the OS keychain (SecretStorage); passed as environment variables. Values are never shown.
+
@@ -173,29 +199,120 @@ export class RunConfigViewProvider implements vscode.WebviewViewProvider { const vscodeApi = acquireVsCodeApi(); const el = id => document.getElementById(id); + const VERBOSITY = 'verbosity'; + const send = msg => vscodeApi.postMessage(msg); + const lower = s => s.toLowerCase(); + + // An empty value clears the parameter instead of passing "--name ". + function setOrClear(name, value) { + value = value.trim(); + send(value === '' ? { type: 'removeParameter', name } : { type: 'setParameter', name, value }); + } + + // Fills a drop-down. A stored value the build no longer lists stays visible, marked unsupported, + // because it is still passed to the build until the user changes it. + function fillSelect(sel, values, current) { + sel.innerHTML = ''; + const all = ['', ...values]; + if (current !== '' && !values.includes(current)) { all.push(current); } + for (const v of all) { + const o = document.createElement('option'); o.value = v; + o.textContent = v === '' ? '(default)' : values.includes(v) || v === '' ? v : v + ' (unsupported)'; + sel.append(o); + } + sel.value = current; + } + + function valueControl(decl, current) { + if (decl.values && decl.values.length > 0) { + const sel = document.createElement('select'); + fillSelect(sel, decl.values, current); + sel.addEventListener('change', () => setOrClear(decl.name, sel.value)); + return sel; + } + const input = document.createElement('input'); input.value = current; + input.addEventListener('change', () => setOrClear(decl.name, input.value)); + return input; + } + function render(state) { + const declared = state.declared || { parameters: [], verbosityLevels: [] }; + const stored = new Map(state.parameters.map(p => [lower(p.name), p.value])); + const declaredParams = declared.parameters.filter(p => !p.secret); + const declaredSecrets = declared.parameters.filter(p => p.secret); + const declaredNames = new Set(declared.parameters.map(p => lower(p.name))); + + // Verbosity: levels come from the build's schema, so 10.5's Information appears only on 10.5+. + const hasVerbosity = declared.verbosityLevels.length > 0; + el('verbosityBlock').hidden = !hasVerbosity; + if (hasVerbosity) { + const sel = el('verbosity'); + fillSelect(sel, declared.verbosityLevels, stored.get(VERBOSITY) ?? ''); + sel.onchange = () => setOrClear(VERBOSITY, sel.value); + } + + const dp = el('declaredParams'); + dp.innerHTML = ''; + for (const d of declaredParams) { + const row = document.createElement('div'); + row.className = 'row'; + const name = document.createElement('span'); name.className = 'name'; name.textContent = d.name; + if (d.description) { name.title = d.description; } + row.append(name, valueControl(d, stored.get(lower(d.name)) ?? '')); + dp.append(row); + } + + // Free-form rows: stored parameters the build does not declare (verbosity has its own control). const params = el('params'); params.innerHTML = ''; for (const p of state.parameters) { + if (declaredNames.has(lower(p.name)) || (hasVerbosity && lower(p.name) === VERBOSITY)) { continue; } const row = document.createElement('div'); row.className = 'row'; const name = document.createElement('span'); name.className = 'name'; name.textContent = p.name; const val = document.createElement('input'); val.value = p.value; - val.addEventListener('change', () => vscodeApi.postMessage({ type: 'setParameter', name: p.name, value: val.value })); + val.addEventListener('change', () => send({ type: 'setParameter', name: p.name, value: val.value })); const rm = document.createElement('button'); rm.className = 'icon'; rm.textContent = '✕'; - rm.addEventListener('click', () => vscodeApi.postMessage({ type: 'removeParameter', name: p.name })); + rm.addEventListener('click', () => send({ type: 'removeParameter', name: p.name })); row.append(name, val, rm); params.append(row); } + + // Declared secrets read "not set" until a value is stored; values never reach this page. + const ds = el('declaredSecrets'); + ds.innerHTML = ''; + for (const d of declaredSecrets) { + const isSet = state.secretNames.includes(d.name); + const row = document.createElement('div'); + row.className = 'row'; + const name = document.createElement('span'); name.className = 'name'; name.textContent = d.name; + if (d.description) { name.title = d.description; } + row.append(name); + if (isSet) { + const masked = document.createElement('span'); masked.className = 'secret-val'; masked.textContent = '••••••••'; + masked.style.flex = '1 1 auto'; + const rm = document.createElement('button'); rm.className = 'icon'; rm.textContent = '✕'; + rm.addEventListener('click', () => send({ type: 'removeSecret', name: d.name })); + row.append(masked, rm); + } else { + const input = document.createElement('input'); input.type = 'password'; input.placeholder = 'not set'; + const set = document.createElement('button'); set.textContent = 'Set'; + set.addEventListener('click', () => { if (input.value) { send({ type: 'setSecret', name: d.name, value: input.value }); } }); + row.append(input, set); + } + ds.append(row); + } + const secrets = el('secrets'); secrets.innerHTML = ''; for (const name of state.secretNames) { + if (declaredSecrets.some(d => d.name === name)) { continue; } const row = document.createElement('div'); row.className = 'row'; const n = document.createElement('span'); n.className = 'name'; n.textContent = name; const masked = document.createElement('span'); masked.className = 'secret-val'; masked.textContent = '••••••••'; const rm = document.createElement('button'); rm.className = 'icon'; rm.textContent = '✕'; - rm.addEventListener('click', () => vscodeApi.postMessage({ type: 'removeSecret', name })); + rm.addEventListener('click', () => send({ type: 'removeSecret', name })); row.append(n, masked, rm); secrets.append(row); }