refactor(compile): drop unused ADO_AW_IMPORT_BASE env var

`import.js` consults `ADO_AW_IMPORT_BASE` only when resolving a
relative marker path (`isAbsolute(rawPath) ? rawPath : resolve(base,
rawPath)`). In the pipeline the only marker `import.js` ever sees is
the compiler-generated top-level body marker, which embeds an absolute
`\/…` path. The resolver is also single-pass
by design, so author-written nested relative markers inside the inlined
body are never re-expanded at runtime. The env var was therefore dead
code at runtime.

Changes:
- Remove the `env:` block from `resolver_step()` in
  `src/compile/extensions/ado_script.rs` (and update its unit test to
  assert the variable is **absent**).
- Drop the `process.env.ADO_AW_IMPORT_BASE ??` fallback in
  `scripts/ado-script/src/import/index.ts`; `import.js` now always
  uses `dirname(argv[2])` for relative-path resolution (irrelevant in
  pipeline use, useful for local invocations).
- Replace the `ADO_AW_IMPORT_BASE`-override vitest with a
  `dirname(target)` default-base test that pins the fallback for
  standalone callers.
- Update `docs/ado-script.md` and `docs/runtime-imports.md` to drop
  the env-var contract and explain why the runtime never sees a
  relative marker.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesadevine

docs/ado-script.md

@@ -45,9 +45,11 @@ syntax.
 
 ### Env-var contract
 
-| Env var | Required | Purpose |
-|---|---|---|
-| `ADO_AW_IMPORT_BASE` | No | Base directory for relative imports. Defaults to `dirname(argv[2])`. |
+`import.js` takes no environment variables. Relative-path markers
+resolve against `dirname(argv[2])`; in pipeline use this is irrelevant
+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
 `ado-script.zip` release asset as `gate.js`, so pipelines download it

docs/runtime-imports.md

@@ -36,10 +36,9 @@ along with any author-written markers.
 
 ## Path resolution
 
-- **Absolute paths** are used as-is.
-- **Relative paths at runtime** are resolved against the `ADO_AW_IMPORT_BASE`
-  environment variable. For user-facing imports, the compiler sets this to
-  `{{ trigger_repo_directory }}`.
+- **Absolute paths** are used as-is. The compiler always emits an
+  absolute marker path for the agent body itself (`$(Build.SourcesDirectory)/…`)
+  so the resolver step never has to resolve a relative path at runtime.
 - **Relative paths at compile time** (`inlined-imports: true`) are resolved
   against the source `.md` file's directory.
 

scripts/ado-script/src/import/__tests__/path-resolution.test.ts

@@ -1,4 +1,3 @@
-import { resolve } from "node:path";
 import { describe, expect, it } from "vitest";
 import { readText, runImportSource, withScratchDir, writeFixture } from "./helpers.js";
 
@@ -19,21 +18,23 @@ describe("runtime-import path resolution", () => {
     });
   });
 
-  it("resolves relative paths against ADO_AW_IMPORT_BASE when set", () => {
-    withScratchDir("base-override", (dir) => {
-      writeFixture(dir, "imports/nested/snippet.md", "OVERRIDE\n");
+  it("resolves relative paths against dirname(target)", () => {
+    // The compiler always emits an absolute marker path, so this branch
+    // is unreachable in pipeline use. The test pins the fallback so a
+    // standalone invocation of `import.js` (e.g. local dev or future
+    // callers) behaves predictably.
+    withScratchDir("relative-default-base", (dir) => {
+      writeFixture(dir, "snippet.md", "SIBLING\n");
       const target = writeFixture(
         dir,
-        "prompt/prompt.md",
-        "start\n{{#runtime-import nested/snippet.md}}\nend\n",
+        "prompt.md",
+        "start\n{{#runtime-import ./snippet.md}}\nend\n",
       );
 
-      const result = runImportSource(target, {
-        ADO_AW_IMPORT_BASE: resolve(dir, "imports"),
-      });
+      const result = runImportSource(target);
 
       expect(result.status).toBe(0);
-      expect(readText(target)).toBe("start\nOVERRIDE\n\nend\n");
+      expect(readText(target)).toBe("start\nSIBLING\n\nend\n");
     });
   });
 });

scripts/ado-script/src/import/index.ts

@@ -31,7 +31,7 @@ function main(): void {
     fail([`target file not found: ${sanitizeForVsoMessage(target)}`]);
   }
 
-  const base = process.env.ADO_AW_IMPORT_BASE ?? dirname(target);
+  const base = dirname(target);
   const original = readFileSync(target, "utf8");
   const errors: string[] = [];
 

src/compile/extensions/ado_script.rs

@@ -100,17 +100,16 @@ fn install_and_download_steps() -> Vec<String> {
 /// The resolver step that runs in the Agent job to expand
 /// `{{#runtime-import …}}` markers in the agent prompt file in place.
 ///
-/// `ADO_AW_IMPORT_BASE` is `$(Build.SourcesDirectory)` so that
-/// author-written relative imports (e.g.
-/// `{{#runtime-import shared/snippet.md}}`) resolve against the trigger
-/// repo's checkout root — matching gh-aw's path-resolution semantics.
+/// The compiler always emits an absolute marker path (built from
+/// `$(Build.SourcesDirectory)` plus the repo-relative source path) and
+/// the resolver is single-pass, so relative-path resolution never
+/// happens in practice; `import.js` falls back to `dirname(target)` for
+/// the unreachable relative-path case.
 fn resolver_step() -> String {
     format!(
         r#"- bash: |
     set -eo pipefail
     node '{IMPORT_EVAL_PATH}' /tmp/awf-tools/agent-prompt.md
-  env:
-    ADO_AW_IMPORT_BASE: $(Build.SourcesDirectory)
   displayName: "Resolve runtime imports (agent prompt)"
   condition: succeeded()"#
     )
@@ -368,7 +367,10 @@ mod tests {
         assert!(steps[1].contains("Download ado-aw scripts"));
         assert!(steps[2].contains("node '/tmp/ado-aw-scripts/ado-script/dist/import/index.js'"));
         assert!(steps[2].contains("Resolve runtime imports (agent prompt)"));
-        assert!(steps[2].contains("ADO_AW_IMPORT_BASE: $(Build.SourcesDirectory)"));
+        assert!(
+            !steps[2].contains("ADO_AW_IMPORT_BASE"),
+            "resolver step must not export ADO_AW_IMPORT_BASE — the compiler emits absolute marker paths and import.js is single-pass, so the env var would never be consulted"
+        );
     }
 
     #[test]