refactor(ado-script): flatten bundled artifact paths (#671)

Author: Copilot

.github/workflows/release.yml

@@ -67,13 +67,13 @@ jobs:
         run: |
           npm ci
           npm run build
-        # `npm run build` runs codegen + ncc and outputs dist/gate/index.js.
+        # `npm run build` runs codegen + ncc and outputs gate.js + import.js.
 
       - name: Package ado-script bundle
         run: |
           set -euo pipefail
           cd scripts
-          zip -r ../ado-script.zip ado-script/dist
+          zip -r ../ado-script.zip ado-script/gate.js ado-script/import.js
 
       - name: Upload release assets
         env:

AGENTS.md

@@ -161,8 +161,8 @@ Every compiled pipeline runs as three sequential jobs:
 ├── scripts/              # Supporting scripts shipped as release artifacts
 │   └── ado-script/       # TypeScript workspace for bundled gate.js, import.js, and future bundles
 │       └── src/
-│           ├── gate/     # Gate evaluator source (bundled to dist/gate/index.js)
-│           ├── import/   # Runtime prompt resolver source (bundled to dist/import/index.js)
+│           ├── gate/     # Gate evaluator source (bundled to gate.js)
+│           ├── import/   # Runtime prompt resolver source (bundled to import.js)
 │           └── shared/   # Shared modules across bundles (auth, ado-client, env-facts, types.gen.ts)
 ├── tests/                # Integration tests and fixtures
 ├── docs/                 # Per-concept reference documentation (see index below)

docs/ado-script.md

@@ -51,7 +51,7 @@ because the compiler always embeds an absolute marker path and
 `import.js` is single-pass (nested markers inside the inlined body are
 not re-expanded).
 
-The bundle lives at `dist/import/index.js` and ships in the same
+The bundle lives at `import.js` and ships in the same
 `ado-script.zip` release asset as `gate.js`, so pipelines download it
 through the same Setup-job asset flow. `import.js` uses only the Node
 standard library, so the ncc bundle is small (~1.5 KB) and carries no
@@ -137,7 +137,7 @@ job.
 ## Runtime env-var contract
 
 The compiler injects these environment variables on the
-`bash: node gate/index.js` step. `gate.js` reads them via
+`bash: node gate.js` step. `gate.js` reads them via
 `process.env`:
 
 | Env var | Source | Purpose |
@@ -187,13 +187,13 @@ scripts/ado-script/
 │       ├── index.ts             # main(): expand runtime-import markers in place
 │       └── __tests__/           # marker, path-resolution, and single-pass coverage
 ├── test/                        # End-to-end smoke tests
-└── dist/                        # ncc bundle output (gitignored)
-    ├── gate/index.js
-    └── import/index.js
+├── gate.js                      # ncc bundle output (gitignored)
+└── import.js                    # ncc bundle output (gitignored)
 ```
 
 The release workflow (`.github/workflows/release.yml`) runs
-`npm ci && npm run build`, then zips `scripts/ado-script/dist/` into
+`npm ci && npm run build`, then zips `scripts/ado-script/gate.js` and
+`scripts/ado-script/import.js` into
 the `ado-script.zip` release asset. Pipelines download that asset at
 runtime by URL pinned to the compiler's `CARGO_PKG_VERSION`, verify
 its SHA-256 against the `checksums.txt` asset, then extract.
@@ -250,7 +250,7 @@ three step strings into the Setup job:
    `CARGO_PKG_VERSION`, verifies the zip's SHA-256, then
    `unzip -o /tmp/ado-aw-scripts/ado-script.zip -d /tmp/ado-aw-scripts/`.
    Also capped at `timeoutInMinutes: 5`.
-3. **`bash: node '/tmp/ado-aw-scripts/ado-script/dist/gate/index.js'`** —
+3. **`bash: node '/tmp/ado-aw-scripts/ado-script/gate.js'`** —
    runs the gate with `GATE_SPEC` and the env-var contract documented
    above.
 
@@ -263,7 +263,7 @@ the Agent job's existing `{{ prepare_steps }}` block:
 1. **`NodeTool@0`** — same shape as above.
 2. **`curl` download + verify + extract** — same artefact, same
    verification.
-3. **`bash: node '/tmp/ado-aw-scripts/ado-script/dist/import/index.js'`** —
+3. **`bash: node '/tmp/ado-aw-scripts/ado-script/import.js'`** —
    expands `{{#runtime-import …}}` markers in
    `/tmp/awf-tools/agent-prompt.md` in place. See
    [`runtime-imports.md`](runtime-imports.md) for marker syntax.
@@ -324,16 +324,16 @@ The IR-to-bash codegen that produces the gate step is
    `scripts/ado-script/src/poll/`. Reuse anything in `src/shared/`.
 2. Add a build script to `package.json`:
    ```json
-   "build:poll": "ncc build src/poll/index.ts -o dist/poll -m -t"
+   "build:poll": "ncc build src/poll/index.ts -o .ado-build/poll -m -t && node -e \"const fs=require('node:fs'); fs.copyFileSync('.ado-build/poll/index.js','poll.js'); fs.rmSync('.ado-build/poll',{recursive:true,force:true});\""
    ```
    and extend `build` to also run it.
 3. Add vitest tests under `src/poll/__tests__/`.
 4. Wire from a new `CompilerExtension` (or extend an existing one)
    that downloads `ado-script.zip` (already a release asset) and
-   invokes `node /tmp/ado-aw-scripts/ado-script/dist/poll/index.js`
+   invokes `node /tmp/ado-aw-scripts/ado-script/poll.js`
    as a runtime step.
-5. No release-workflow change is needed — `zip -r ado-script/dist`
-   picks up the new bundle automatically.
+5. Update release packaging to include `scripts/ado-script/poll.js`
+   in `ado-script.zip` alongside other bundles.
 
 ### Local development loop
 
@@ -344,7 +344,7 @@ npm ci                 # one-time
 npm run codegen        # regenerate types.gen.ts (compiles ado-aw first)
 npm test               # vitest unit tests
 npm run typecheck      # strict tsc --noEmit
-npm run build          # ncc-bundle to dist/gate/index.js
+npm run build          # ncc-bundle to gate.js
 npm run test:smoke     # build + smoke test the bundle end-to-end
 ```
 

docs/filter-ir.md

@@ -235,7 +235,7 @@ require heuristic analysis and could produce false positives.
 
 Produces a complete ADO pipeline step (`- bash: |`) with a **data-driven
 architecture**: bash is a thin ADO-macro shim, all filter logic lives in
-the bundled Node.js gate evaluator (`scripts/ado-script/dist/gate/index.js`) that reads a JSON
+the bundled Node.js gate evaluator (`scripts/ado-script/gate.js`) that reads a JSON
 gate spec.
 
 #### Generated Step Structure
@@ -257,7 +257,7 @@ gate spec.
     export ADO_SYSTEM_ACCESS_TOKEN="$SYSTEM_ACCESSTOKEN"
 
     # 4. Run the bundled Node evaluator (downloaded by the Setup job)
-    node '/tmp/ado-aw-scripts/ado-script/dist/gate/index.js'
+    node '/tmp/ado-aw-scripts/ado-script/gate.js'
   name: prGate
   displayName: "Evaluate PR filters"
   env:
@@ -304,7 +304,7 @@ acquisition logic.
 #### Bundled Gate Evaluator (`scripts/ado-script/src/gate/`)
 
 The evaluator is a TypeScript program ncc-bundled to a single
-self-contained `scripts/ado-script/dist/gate/index.js` (~1.1 MB) that ships as part of the
+self-contained `scripts/ado-script/gate.js` (~1.1 MB) that ships as part of the
 `ado-script.zip` release asset. See [`ado-script.md`](ado-script.md) for the
 full design and codegen pipeline. It handles:
 
@@ -364,9 +364,9 @@ For the gate path it controls:
    LTS so `gate.js` has a runtime.
 2. **Download step** — fetches `ado-script.zip` from the ado-aw release
    artifacts, verifies its SHA256 checksum via `checksums.txt`, then
-   extracts `gate.js` to `/tmp/ado-aw-scripts/ado-script/dist/gate/index.js`.
+   extracts `gate.js` to `/tmp/ado-aw-scripts/ado-script/gate.js`.
 3. **Gate step** — calls `compile_gate_step_external()` to generate a step
-   that runs `node /tmp/ado-aw-scripts/ado-script/dist/gate/index.js` (no inline heredoc).
+   that runs `node /tmp/ado-aw-scripts/ado-script/gate.js` (no inline heredoc).
 4. **Validation** — runs `validate_pr_filters()` / `validate_pipeline_filters()`
    during compilation via the `validate()` trait method.
 
@@ -416,7 +416,7 @@ The `expression` escape hatch is also ANDed if present.
 
 The `gate.js` bundle is built from the TypeScript workspace at
 `scripts/ado-script/` (see [`ado-script.md`](ado-script.md)) and emitted to
-`scripts/ado-script/dist/gate/index.js` by the release workflow's build step. It ships inside
+`scripts/ado-script/gate.js` by the release workflow's build step. It ships inside
 the `ado-script.zip` release asset, alongside any future bundled helpers
 (e.g. `poll.js`, `stats.js`). The download URL is deterministic based on
 the ado-aw version:
@@ -425,7 +425,7 @@ the ado-aw version:
 A `checksums.txt` file is also published at the same URL base and used to
 verify the SHA256 integrity of `ado-script.zip` before extraction.
 
-The Setup-job download step pulls the zip, extracts `ado-script/dist/gate/index.js`,
+The Setup-job download step pulls the zip, extracts `ado-script/gate.js`,
 and discards the rest. New per-use-site bundles follow the same pattern
 (per-bundle ncc entry + per-bundle download step).
 

docs/runtime-imports.md

@@ -75,7 +75,7 @@ compile time instead of on the pipeline runner.
 
 ## Implementation notes
 
-- **Runtime**: `dist/import/index.js` is ncc-bundled into `ado-script.zip`.
+- **Runtime**: `import.js` is ncc-bundled into `ado-script.zip`.
   The always-on `AdoScriptExtension`'s `prepare_steps()` injects three
   steps into the Agent job's existing `{{ prepare_steps }}` block:
   `NodeTool@0` install, the `ado-script.zip` download/verify/extract,

scripts/ado-script/.gitignore

@@ -1,4 +1,6 @@
 node_modules
-dist
+.ado-build
+gate.js
+import.js
 schema
 *.tsbuildinfo

scripts/ado-script/README.md

@@ -22,7 +22,7 @@ This invokes `cargo run -- export-gate-schema` to write the JSON Schema, then ru
 - `src/shared/` — modules shared across all bundles (auth, ado-client, vso-logger, env-facts, policy state machine)
 - `src/gate/` — gate evaluator entry point and per-concern modules
 - `src/import/` — runtime-import resolver entry point
-- `dist/` — ncc bundle output (gitignored); `npm run build` writes `dist/gate/index.js` and `dist/import/index.js`, both of which ship in `ado-script.zip`
+- `gate.js` / `import.js` — ncc bundle outputs (gitignored); `npm run build` writes both at the workspace root, and both ship in `ado-script.zip`
 
 ## See also
 

scripts/ado-script/package.json

@@ -7,10 +7,11 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "npm run codegen && npm run build:gate && npm run build:import",
-    "build:gate": "ncc build src/gate/index.ts -o dist/gate -m -t",
-    "build:import": "ncc build src/import/index.ts -o dist/import -m -t",
-    "build:check": "ls -lh dist/gate/index.js && wc -c dist/gate/index.js",
+    "build": "npm run codegen && npm run clean && npm run build:gate && npm run build:import",
+    "clean": "node -e \"const fs=require('node:fs'); fs.rmSync('.ado-build',{recursive:true,force:true}); fs.rmSync('gate.js',{force:true}); fs.rmSync('import.js',{force:true});\"",
+    "build:gate": "ncc build src/gate/index.ts -o .ado-build/gate -m -t && node -e \"const fs=require('node:fs'); fs.copyFileSync('.ado-build/gate/index.js','gate.js'); fs.rmSync('.ado-build/gate',{recursive:true,force:true});\"",
+    "build:import": "ncc build src/import/index.ts -o .ado-build/import -m -t && node -e \"const fs=require('node:fs'); fs.copyFileSync('.ado-build/import/index.js','import.js'); fs.rmSync('.ado-build/import',{recursive:true,force:true});\"",
+    "build:check": "ls -lh gate.js && wc -c gate.js",
     "codegen": "node -e \"require('node:fs').mkdirSync('schema', { recursive: true })\" && cargo run --quiet --manifest-path ../../Cargo.toml -- export-gate-schema --output schema/gate-spec.schema.json && npx json2ts schema/gate-spec.schema.json -o src/shared/types.gen.ts --bannerComment \"// AUTO-GENERATED from Rust IR via cargo run -- export-gate-schema. Do not edit; run npm run codegen.\"",
     "test": "vitest run",
     "test:smoke": "npm run build:gate && npm run build:import && vitest run -c vitest.config.smoke.ts",

scripts/ado-script/src/gate/predicates.ts

@@ -164,7 +164,7 @@ export function evaluatePredicate(p: PredicateSpec, facts: Map<string, unknown>)
       const unknownType = (p as { type?: unknown }).type;
       logWarning(
         `Unknown predicate type '${String(unknownType)}'; failing closed. ` +
-          "Update scripts/ado-script/dist/gate/index.js (or the bundled ado-script.zip) to a " +
+          "Update scripts/ado-script/gate.js (or the bundled ado-script.zip) to a " +
           "release that supports this predicate.",
       );
       return false;

scripts/ado-script/src/shared/auth.ts

@@ -12,7 +12,7 @@
  * (e.g. a manual build that hits the bypass branch in `bypass.ts`, or
  * a pipeline whose facts are all pipeline variables). The dynamic
  * `import()` below is statically analysable by ncc, so the SDK is
- * still bundled into `dist/gate/index.js` — only its module-evaluation
+ * still bundled into `gate.js` — only its module-evaluation
  * cost is deferred until the first `getWebApi()` call.
  *
  * Env-var contract (set by the compiler in