feat: add \configure\ command to detect pipelines and update GITHUB_TOKEN (#92)

* feat: add \configure\ command to detect pipelines and update GITHUB_TOKEN

Add a new \�do-aw configure\ CLI command that:
- Detects agentic pipelines by scanning YAML files for a new \# @ado-aw\ header
- Infers ADO org/project from the git remote URL
- Matches detected pipelines to ADO build definitions (by YAML path, then name)
- Updates the GITHUB_TOKEN pipeline variable via the Build Definitions API

The compiler now prepends a header comment to all compiled YAML output:
  # This file is auto-generated by ado-aw. Do not edit manually.
  # @ado-aw source=<input-path> version=<compiler-version>

New modules: src/detect.rs (scanning/parsing), src/configure.rs (orchestration + ADO API).

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

* fix: address PR review feedback for configure command

- Security: read --token and --pat from env vars (GITHUB_TOKEN, AZURE_DEVOPS_EXT_PAT)
  via clap's env attribute, avoiding exposure in process listings
- Performance: use BufReader to read only first 5 lines in pipeline detection
  instead of loading entire files
- Correctness: paginate ADO Build Definitions API using x-ms-continuationtoken
  header to handle projects with >100 pipelines
- Correctness: tighten name-based fallback matching — warn on fuzzy matches,
  skip ambiguous ones (multiple candidates)
- Correctness: replace std::process::exit(1) with anyhow::bail! to preserve
  Rust error handling and cleanup
- Cleanup: remove hardcoded version string in user-facing message
- Docs: add race condition comment on GET→PUT update cycle

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

* feat: prompt for GITHUB_TOKEN interactively when not provided

The --token flag now falls back to an interactive password prompt (via
inquire) when neither the CLI flag nor the GITHUB_TOKEN env var is set.
This avoids exposing the token in shell history or process listings.

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

* fix: address second round of PR review feedback

- Fix header marker prefix matching: require exact '# @ado-aw ' with
  trailing space so '# @ado-aw-v2' is not falsely detected
- Quote source path in header comment to support paths with spaces;
  parser handles both quoted and unquoted for backward compatibility
- Strip newlines from input_path in header generation to prevent injection
- Guard index access in integration test with lines.len() >= 2 assertion

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

* fix: address third round of PR review feedback

- URL-encode continuation token in ADO pagination (use reqwest .query())
- Escape double quotes in source path in header comment
- Handle escaped quotes in header parser for correct round-trip
- Extract fuzzy name matching into testable pure function
- Add unit tests for fuzzy matching (single, ambiguous, none, empty, case)
- Add tests for header comment quote escaping and round-trip

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

* fix: address fourth round of PR review feedback

- Preserve existing allowOverride when updating pipeline variable instead
  of silently hardcoding true (security posture fix)
- Add interactive prompt fallback for --pat (matching --token behavior)
- Add 30s timeout to reqwest HTTP client for better UX when ADO is slow
- Canonicalize repo_path early for clearer error messages
- Update --pat help text to recommend env var over CLI flag

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

---------

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

Author: jamesadevine

Cargo.lock

@@ -4,7 +4,7 @@ version = "0.4.0"
 edition = "2024"
 
 [dependencies]
-clap = { features = ["derive"], version = "4.5.40" }
+clap = { features = ["derive", "env"], version = "4.5.40" }
 anyhow = "1.0.100"
 async-trait = "0.1"
 chrono = "0.4"
@@ -23,3 +23,4 @@ env_logger = "0.11"
 regex-lite = "0.1"
 inquire = { version = "0.9.2", features = ["editor"] }
 terminal_size = "0.4.3"
+url = "2.5.8"

Cargo.toml

@@ -462,6 +462,34 @@ pub const AWF_VERSION: &str = "0.25.4";
 /// See: https://pkgs.dev.azure.com/msazuresphere/_packaging/Guardian1ESPTUpstreamOrgFeed/nuget/v3/index.json
 pub const COPILOT_CLI_VERSION: &str = "1.0.6";
 
+/// Prefix used to identify agentic pipeline YAML files generated by ado-aw.
+pub const HEADER_MARKER: &str = "# @ado-aw";
+
+/// Generate the header comment block prepended to all compiled pipeline YAML.
+///
+/// The header includes:
+/// - A human-readable "do not edit" warning
+/// - A machine-readable `@ado-aw` marker with source path and compiler version
+///
+/// The source path is the input path as provided to the compiler (e.g., `agents/my-agent.md`,
+/// `.azdo/pipelines/review.md`, or any other location the user chose). Path separators
+/// are normalized to forward slashes for cross-platform consistency.
+pub fn generate_header_comment(input_path: &std::path::Path) -> String {
+    let version = env!("CARGO_PKG_VERSION");
+    let source_path = input_path
+        .to_string_lossy()
+        .replace('\\', "/")
+        .replace('\n', "")
+        .replace('\r', "")
+        .replace('"', "\\\"");
+
+    format!(
+        "# This file is auto-generated by ado-aw. Do not edit manually.\n\
+         # @ado-aw source=\"{}\" version={}\n",
+        source_path, version
+    )
+}
+
 /// Generate source path for the execute command.
 ///
 /// Returns a path using `{{ workspace }}` as the base, which gets resolved
@@ -988,4 +1016,27 @@ mod tests {
         assert!(result.contains("SYSTEM_ACCESSTOKEN"));
         assert!(result.contains("cancelling"));
     }
+
+    // ─── generate_header_comment ────────────────────────────────────────────
+
+    #[test]
+    fn test_generate_header_comment_escapes_quotes() {
+        let path = std::path::Path::new("agents/my \"agent\".md");
+        let header = generate_header_comment(path);
+        assert!(
+            header.contains(r#"source="agents/my \"agent\".md""#),
+            "Quotes in path should be escaped: {}",
+            header
+        );
+    }
+
+    #[test]
+    fn test_generate_header_comment_round_trip_with_quotes() {
+        let path = std::path::Path::new("agents/my \"agent\".md");
+        let header = generate_header_comment(path);
+        let marker_line = header.lines().nth(1).expect("Should have second line");
+        let meta = crate::detect::parse_header_line(marker_line)
+            .expect("Should parse header with escaped quotes");
+        assert_eq!(meta.source, r#"agents/my "agent".md"#);
+    }
 }

src/compile/common.rs

@@ -18,6 +18,7 @@ use std::path::{Path, PathBuf};
 
 pub use common::parse_markdown;
 pub use common::sanitize_filename;
+pub use common::HEADER_MARKER;
 pub use types::{CompileTarget, FrontMatter, PermissionsConfig};
 
 /// Trait for pipeline compilers.

src/compile/mod.rs

@@ -20,8 +20,8 @@ use super::common::{
     self, AWF_VERSION, COPILOT_CLI_VERSION, DEFAULT_POOL, compute_effective_workspace, generate_copilot_params,
     generate_acquire_ado_token, generate_checkout_self, generate_checkout_steps,
     generate_ci_trigger, generate_copilot_ado_env, generate_executor_ado_env,
-    generate_pipeline_path, generate_pipeline_resources, generate_pr_trigger,
-    generate_repositories, generate_schedule, generate_source_path,
+    generate_header_comment, generate_pipeline_path, generate_pipeline_resources,
+    generate_pr_trigger, generate_repositories, generate_schedule, generate_source_path,
     generate_working_directory, replace_with_indent, validate_comment_target,
     validate_update_work_item_target, validate_write_permissions,
 };
@@ -194,6 +194,10 @@ displayName: "Finalize""#,
             );
         }
 
+        // Prepend header comment for pipeline detection
+        let header = generate_header_comment(input_path);
+        let pipeline_yaml = format!("{}{}", header, pipeline_yaml);
+
         Ok(pipeline_yaml)
     }
 }

src/compile/onees.rs

@@ -17,12 +17,11 @@ use super::common::{
     self, AWF_VERSION, COPILOT_CLI_VERSION, DEFAULT_POOL, compute_effective_workspace, generate_copilot_params,
     generate_acquire_ado_token, generate_cancel_previous_builds, generate_checkout_self,
     generate_checkout_steps, generate_ci_trigger, generate_copilot_ado_env,
-    generate_executor_ado_env, generate_pipeline_path, generate_pipeline_resources,
-    generate_pr_trigger, generate_repositories, generate_schedule, generate_source_path,
-    generate_working_directory, replace_with_indent, sanitize_filename,
-    validate_write_permissions,
-    validate_comment_target,
-    validate_update_work_item_target,
+    generate_executor_ado_env, generate_header_comment, generate_pipeline_path,
+    generate_pipeline_resources, generate_pr_trigger, generate_repositories,
+    generate_schedule, generate_source_path, generate_working_directory,
+    replace_with_indent, sanitize_filename, validate_write_permissions,
+    validate_comment_target, validate_update_work_item_target,
 };
 use super::types::{FrontMatter, McpConfig};
 use crate::allowed_hosts::{CORE_ALLOWED_HOSTS, mcp_required_hosts};
@@ -198,6 +197,10 @@ impl Compiler for StandaloneCompiler {
             &firewall_config_json,
         );
 
+        // Prepend header comment for pipeline detection
+        let header = generate_header_comment(input_path);
+        let pipeline_yaml = format!("{}{}", header, pipeline_yaml);
+
         Ok(pipeline_yaml)
     }
 }