azdo-cli 0.2.0-develop.8 → 0.2.0

package/README.md

@@ -1,79 +1,73 @@
-# bd - Beads
+# azdo-cli
 
-**Distributed, git-backed graph issue tracker for AI agents.**
+A command-line interface for Azure DevOps.
 
-**Platforms:** macOS, Linux, Windows, FreeBSD
+[![npm version](https://img.shields.io/npm/v/azdo-cli)](https://www.npmjs.com/package/azdo-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=alkampfergit_azdo-cli&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=alkampfergit_azdo-cli)
 
-[![License](https://img.shields.io/github/license/steveyegge/beads)](LICENSE)
-[![Go Report Card](https://goreportcard.com/badge/github.com/steveyegge/beads)](https://goreportcard.com/report/github.com/steveyegge/beads)
-[![Release](https://img.shields.io/github/v/release/steveyegge/beads)](https://github.com/steveyegge/beads/releases)
-[![npm version](https://img.shields.io/npm/v/@beads/bd)](https://www.npmjs.com/package/@beads/bd)
-[![PyPI](https://img.shields.io/pypi/v/beads-mcp)](https://pypi.org/project/beads-mcp/)
+## Installation
 
-Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.
+```bash
+npm install -g azdo-cli
+```
 
-## ⚡ Quick Start
+## Usage
 
 ```bash
-# Install beads CLI (system-wide - don't clone this repo into your project)
-curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
-
-# Initialize in YOUR project
-cd your-project
-bd init
+# Show help
+azdo --help
 
-# Tell your agent
-echo "Use 'bd' for task tracking" >> AGENTS.md
+# Show version
+azdo --version
+azdo -v
 ```
 
-**Note:** Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.
+## Current Status
 
-## 🛠 Features
+This project is in early development (v0.2.0). The base CLI scaffold is in place with support for `--help` and `--version`. Azure DevOps commands (work items, pipelines, repos, etc.) will be added in future releases.
 
-* **Git as Database:** Issues stored as JSONL in `.beads/`. Versioned, branched, and merged like code.
-* **Agent-Optimized:** JSON output, dependency tracking, and auto-ready task detection.
-* **Zero Conflict:** Hash-based IDs (`bd-a1b2`) prevent merge collisions in multi-agent/multi-branch workflows.
-* **Invisible Infrastructure:** SQLite local cache for speed; background daemon for auto-sync.
-* **Compaction:** Semantic "memory decay" summarizes old closed tasks to save context window.
+## Development
 
-## 📖 Essential Commands
-
-| Command | Action |
-| --- | --- |
-| `bd ready` | List tasks with no open blockers. |
-| `bd create "Title" -p 0` | Create a P0 task. |
-| `bd update <id> --claim` | Atomically claim a task (sets assignee + in_progress). |
-| `bd dep add <child> <parent>` | Link tasks (blocks, related, parent-child). |
-| `bd show <id>` | View task details and audit trail. |
+### Prerequisites
 
-## 🔗 Hierarchy & Workflow
+- Node.js LTS (20+)
+- npm
 
-Beads supports hierarchical IDs for epics:
+### Setup
 
-* `bd-a3f8` (Epic)
-* `bd-a3f8.1` (Task)
-* `bd-a3f8.1.1` (Sub-task)
-
-**Stealth Mode:** Run `bd init --stealth` to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects.
+```bash
+git clone https://github.com/alkampfergit/azdo-cli.git
+cd azdo-cli
+npm install
+```
 
-**Contributor vs Maintainer:** When working on open-source projects:
+### Scripts
 
-* **Contributors** (forked repos): Run `bd init --contributor` to route planning issues to a separate repo (e.g., `~/.beads-planning`). Keeps experimental work out of PRs.
-* **Maintainers** (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need `git config beads.role maintainer` if using GitHub HTTPS without credentials but you have write access.
+| Command | Description |
+| --- | --- |
+| `npm run build` | Build the CLI with tsup |
+| `npm test` | Run tests with vitest |
+| `npm run lint` | Lint source files with ESLint |
+| `npm run typecheck` | Type-check with tsc (no emit) |
+| `npm run format` | Check formatting with Prettier |
 
-## 📦 Installation
+### Tech Stack
 
-* **npm:** `npm install -g @beads/bd`
-* **Homebrew:** `brew install beads`
-* **Go:** `go install github.com/steveyegge/beads/cmd/bd@latest`
+- **TypeScript 5.x** (strict mode, ES modules)
+- **commander.js** — CLI framework
+- **tsup** — Bundler (single-file ESM output)
+- **vitest** — Test runner
+- **ESLint + Prettier** — Linting and formatting
 
-**Requirements:** Linux, FreeBSD, macOS, or Windows.
+### Branch Strategy
 
-## 🌐 Community Tools
+This project follows **GitFlow**:
 
-See [docs/COMMUNITY_TOOLS.md](docs/COMMUNITY_TOOLS.md) for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.
+- `master` — stable releases
+- `develop` — integration branch
+- `feature/*` — feature branches off `develop`
 
-## 📝 Documentation
+## License
 
-* [Installing](docs/INSTALLING.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot Setup](docs/COPILOT_INTEGRATION.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/PROTECTED_BRANCHES.md) | [Troubleshooting](docs/TROUBLESHOOTING.md) | [FAQ](docs/FAQ.md)
-* [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/steveyegge/beads)
+[MIT](LICENSE)

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command } from "commander";
+import { Command as Command9 } from "commander";
 
 // src/version.ts
 import { readFileSync } from "fs";
@@ -11,9 +11,996 @@ var __dirname = dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf-8"));
 var version = pkg.version;
 
+// src/commands/get-item.ts
+import { Command } from "commander";
+
+// src/services/azdo-client.ts
+var DEFAULT_FIELDS = [
+  "System.Title",
+  "System.State",
+  "System.WorkItemType",
+  "System.AssignedTo",
+  "System.Description",
+  "Microsoft.VSTS.Common.AcceptanceCriteria",
+  "Microsoft.VSTS.TCM.ReproSteps",
+  "System.AreaPath",
+  "System.IterationPath"
+];
+function authHeaders(pat) {
+  const token = Buffer.from(`:${pat}`).toString("base64");
+  return { Authorization: `Basic ${token}` };
+}
+async function fetchWithErrors(url, init) {
+  let response;
+  try {
+    response = await fetch(url, init);
+  } catch {
+    throw new Error("NETWORK_ERROR");
+  }
+  if (response.status === 401) throw new Error("AUTH_FAILED");
+  if (response.status === 403) throw new Error("PERMISSION_DENIED");
+  if (response.status === 404) throw new Error("NOT_FOUND");
+  return response;
+}
+function buildExtraFields(fields, requested) {
+  const result = {};
+  for (const name of requested) {
+    const val = fields[name];
+    if (val !== void 0 && val !== null) {
+      result[name] = String(val);
+    }
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+async function getWorkItem(context, id, pat, extraFields) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/${id}`
+  );
+  url.searchParams.set("api-version", "7.1");
+  if (extraFields && extraFields.length > 0) {
+    const allFields = [...DEFAULT_FIELDS, ...extraFields];
+    url.searchParams.set("fields", allFields.join(","));
+  }
+  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(pat) });
+  if (!response.ok) {
+    throw new Error(`HTTP_${response.status}`);
+  }
+  const data = await response.json();
+  const descriptionParts = [];
+  if (data.fields["System.Description"]) {
+    descriptionParts.push({ label: "Description", value: data.fields["System.Description"] });
+  }
+  if (data.fields["Microsoft.VSTS.Common.AcceptanceCriteria"]) {
+    descriptionParts.push({ label: "Acceptance Criteria", value: data.fields["Microsoft.VSTS.Common.AcceptanceCriteria"] });
+  }
+  if (data.fields["Microsoft.VSTS.TCM.ReproSteps"]) {
+    descriptionParts.push({ label: "Repro Steps", value: data.fields["Microsoft.VSTS.TCM.ReproSteps"] });
+  }
+  let combinedDescription = null;
+  if (descriptionParts.length === 1) {
+    combinedDescription = descriptionParts[0].value;
+  } else if (descriptionParts.length > 1) {
+    combinedDescription = descriptionParts.map((p) => `<h3>${p.label}</h3>${p.value}`).join("");
+  }
+  return {
+    id: data.id,
+    rev: data.rev,
+    title: data.fields["System.Title"],
+    state: data.fields["System.State"],
+    type: data.fields["System.WorkItemType"],
+    assignedTo: data.fields["System.AssignedTo"]?.displayName ?? null,
+    description: combinedDescription,
+    areaPath: data.fields["System.AreaPath"],
+    iterationPath: data.fields["System.IterationPath"],
+    url: data._links.html.href,
+    extraFields: extraFields && extraFields.length > 0 ? buildExtraFields(data.fields, extraFields) : null
+  };
+}
+async function getWorkItemFieldValue(context, id, pat, fieldName) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/${id}`
+  );
+  url.searchParams.set("api-version", "7.1");
+  url.searchParams.set("fields", fieldName);
+  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(pat) });
+  if (!response.ok) {
+    throw new Error(`HTTP_${response.status}`);
+  }
+  const data = await response.json();
+  const value = data.fields[fieldName];
+  if (value === void 0 || value === null || value === "") {
+    return null;
+  }
+  return typeof value === "object" ? JSON.stringify(value) : `${value}`;
+}
+async function updateWorkItem(context, id, pat, fieldName, operations) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/${id}`
+  );
+  url.searchParams.set("api-version", "7.1");
+  const response = await fetchWithErrors(url.toString(), {
+    method: "PATCH",
+    headers: {
+      ...authHeaders(pat),
+      "Content-Type": "application/json-patch+json"
+    },
+    body: JSON.stringify(operations)
+  });
+  if (response.status === 400) {
+    let serverMessage = "Unknown error";
+    try {
+      const body = await response.json();
+      if (body.message) serverMessage = body.message;
+    } catch {
+    }
+    throw new Error(`UPDATE_REJECTED: ${serverMessage}`);
+  }
+  if (!response.ok) {
+    throw new Error(`HTTP_${response.status}`);
+  }
+  const data = await response.json();
+  const lastOp = operations[operations.length - 1];
+  const fieldValue = lastOp.value ?? null;
+  return {
+    id: data.id,
+    rev: data.rev,
+    title: data.fields["System.Title"],
+    fieldName,
+    fieldValue
+  };
+}
+
+// src/services/auth.ts
+import { createInterface } from "readline";
+
+// src/services/credential-store.ts
+import { Entry } from "@napi-rs/keyring";
+var SERVICE = "azdo-cli";
+var ACCOUNT = "pat";
+async function getPat() {
+  try {
+    const entry = new Entry(SERVICE, ACCOUNT);
+    return entry.getPassword();
+  } catch {
+    return null;
+  }
+}
+async function storePat(pat) {
+  try {
+    const entry = new Entry(SERVICE, ACCOUNT);
+    entry.setPassword(pat);
+  } catch {
+  }
+}
+async function deletePat() {
+  try {
+    const entry = new Entry(SERVICE, ACCOUNT);
+    entry.deletePassword();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/services/auth.ts
+function normalizePat(rawPat) {
+  const trimmedPat = rawPat.trim();
+  return trimmedPat.length > 0 ? trimmedPat : null;
+}
+async function promptForPat() {
+  if (!process.stdin.isTTY) {
+    return null;
+  }
+  return new Promise((resolve2) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stderr
+    });
+    process.stderr.write("Enter your Azure DevOps PAT: ");
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    let pat = "";
+    const onData = (key) => {
+      const ch = key.toString("utf8");
+      if (ch === "") {
+        process.stdin.setRawMode(false);
+        process.stdin.removeListener("data", onData);
+        rl.close();
+        process.stderr.write("\n");
+        resolve2(null);
+      } else if (ch === "\r" || ch === "\n") {
+        process.stdin.setRawMode(false);
+        process.stdin.removeListener("data", onData);
+        rl.close();
+        process.stderr.write("\n");
+        resolve2(pat);
+      } else if (ch === "\x7F" || ch === "\b") {
+        if (pat.length > 0) {
+          pat = pat.slice(0, -1);
+          process.stderr.write("\b \b");
+        }
+      } else {
+        pat += ch;
+        process.stderr.write("*".repeat(ch.length));
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+async function resolvePat() {
+  const envPat = process.env.AZDO_PAT;
+  if (envPat) {
+    return { pat: envPat, source: "env" };
+  }
+  const storedPat = await getPat();
+  if (storedPat !== null) {
+    return { pat: storedPat, source: "credential-store" };
+  }
+  const promptedPat = await promptForPat();
+  if (promptedPat !== null) {
+    const normalizedPat = normalizePat(promptedPat);
+    if (normalizedPat !== null) {
+      await storePat(normalizedPat);
+      return { pat: normalizedPat, source: "prompt" };
+    }
+  }
+  throw new Error(
+    "Authentication cancelled. Set AZDO_PAT environment variable or run again to enter a PAT."
+  );
+}
+
+// src/services/git-remote.ts
+import { execSync } from "child_process";
+var patterns = [
+  // HTTPS (current): https://dev.azure.com/{org}/{project}/_git/{repo}
+  /^https?:\/\/dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/.+$/,
+  // HTTPS (legacy + DefaultCollection): https://{org}.visualstudio.com/DefaultCollection/{project}/_git/{repo}
+  /^https?:\/\/([^.]+)\.visualstudio\.com\/DefaultCollection\/([^/]+)\/_git\/.+$/,
+  // HTTPS (legacy): https://{org}.visualstudio.com/{project}/_git/{repo}
+  /^https?:\/\/([^.]+)\.visualstudio\.com\/([^/]+)\/_git\/.+$/,
+  // SSH (current): git@ssh.dev.azure.com:v3/{org}/{project}/{repo}
+  /^git@ssh\.dev\.azure\.com:v3\/([^/]+)\/([^/]+)\/.+$/,
+  // SSH (legacy): {org}@vs-ssh.visualstudio.com:v3/{org}/{project}/{repo}
+  /^[^@]+@vs-ssh\.visualstudio\.com:v3\/([^/]+)\/([^/]+)\/.+$/
+];
+function parseAzdoRemote(url) {
+  for (const pattern of patterns) {
+    const match = url.match(pattern);
+    if (match) {
+      const project = match[2];
+      if (/^DefaultCollection$/i.test(project)) {
+        return { org: match[1], project: "" };
+      }
+      return { org: match[1], project };
+    }
+  }
+  return null;
+}
+function detectAzdoContext() {
+  let remoteUrl;
+  try {
+    remoteUrl = execSync("git remote get-url origin", { encoding: "utf-8" }).trim();
+  } catch {
+    throw new Error("Not in a git repository. Provide --org and --project explicitly.");
+  }
+  const context = parseAzdoRemote(remoteUrl);
+  if (!context || !context.org && !context.project) {
+    throw new Error('Git remote "origin" is not an Azure DevOps URL. Provide --org and --project explicitly.');
+  }
+  return context;
+}
+
+// src/services/config-store.ts
+import fs from "fs";
+import path from "path";
+import os from "os";
+var SETTINGS = [
+  {
+    key: "org",
+    description: "Azure DevOps organization name",
+    type: "string",
+    example: "mycompany",
+    required: true
+  },
+  {
+    key: "project",
+    description: "Azure DevOps project name",
+    type: "string",
+    example: "MyProject",
+    required: true
+  },
+  {
+    key: "fields",
+    description: "Extra work item fields to include (comma-separated reference names)",
+    type: "string[]",
+    example: "System.Tags,Custom.Priority",
+    required: false
+  }
+];
+var VALID_KEYS = SETTINGS.map((s) => s.key);
+function getConfigPath() {
+  return path.join(os.homedir(), ".azdo", "config.json");
+}
+function loadConfig() {
+  const configPath = getConfigPath();
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw err;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    process.stderr.write(`Warning: Config file ${configPath} contains invalid JSON. Using defaults.
+`);
+    return {};
+  }
+}
+function saveConfig(config) {
+  const configPath = getConfigPath();
+  const dir = path.dirname(configPath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+function validateKey(key) {
+  if (!VALID_KEYS.includes(key)) {
+    throw new Error(`Unknown setting key "${key}". Valid keys: org, project, fields`);
+  }
+}
+function getConfigValue(key) {
+  validateKey(key);
+  const config = loadConfig();
+  return config[key];
+}
+function setConfigValue(key, value) {
+  validateKey(key);
+  const config = loadConfig();
+  if (value === "") {
+    delete config[key];
+  } else if (key === "fields") {
+    config.fields = value.split(",").map((s) => s.trim());
+  } else {
+    config[key] = value;
+  }
+  saveConfig(config);
+}
+function unsetConfigValue(key) {
+  validateKey(key);
+  const config = loadConfig();
+  delete config[key];
+  saveConfig(config);
+}
+
+// src/services/context.ts
+function resolveContext(options) {
+  if (options.org && options.project) {
+    return { org: options.org, project: options.project };
+  }
+  const config = loadConfig();
+  if (config.org && config.project) {
+    return { org: config.org, project: config.project };
+  }
+  let gitContext = null;
+  try {
+    gitContext = detectAzdoContext();
+  } catch {
+  }
+  const org = config.org || gitContext?.org;
+  const project = config.project || gitContext?.project;
+  if (org && project) {
+    return { org, project };
+  }
+  throw new Error(
+    'Could not determine org/project. Use --org and --project flags, work from an Azure DevOps git repo, or run "azdo config set org/project".'
+  );
+}
+
+// src/services/command-helpers.ts
+function parseWorkItemId(idStr) {
+  const id = Number.parseInt(idStr, 10);
+  if (!Number.isInteger(id) || id <= 0) {
+    process.stderr.write(
+      `Error: Work item ID must be a positive integer. Got: "${idStr}"
+`
+    );
+    process.exit(1);
+  }
+  return id;
+}
+function validateOrgProjectPair(options) {
+  const hasOrg = options.org !== void 0;
+  const hasProject = options.project !== void 0;
+  if (hasOrg !== hasProject) {
+    process.stderr.write(
+      "Error: --org and --project must both be provided, or both omitted.\n"
+    );
+    process.exit(1);
+  }
+}
+function handleCommandError(err, id, context, scope = "write") {
+  const error = err instanceof Error ? err : new Error(String(err));
+  const msg = error.message;
+  const scopeLabel = scope === "read" ? "Work Items (read)" : "Work Items (Read & Write)";
+  if (msg === "AUTH_FAILED") {
+    process.stderr.write(
+      `Error: Authentication failed. Check that your PAT is valid and has the "${scopeLabel}" scope.
+`
+    );
+  } else if (msg === "PERMISSION_DENIED") {
+    process.stderr.write(
+      `Error: Access denied. Your PAT may lack ${scope} permissions for project "${context?.project}".
+`
+    );
+  } else if (msg === "NOT_FOUND") {
+    process.stderr.write(
+      `Error: Work item ${id} not found in ${context?.org}/${context?.project}.
+`
+    );
+  } else if (msg === "NETWORK_ERROR") {
+    process.stderr.write(
+      "Error: Could not connect to Azure DevOps. Check your network connection.\n"
+    );
+  } else if (msg.startsWith("UPDATE_REJECTED:")) {
+    const serverMsg = msg.replace("UPDATE_REJECTED: ", "");
+    process.stderr.write(`Error: Update rejected: ${serverMsg}
+`);
+  } else {
+    process.stderr.write(`Error: ${msg}
+`);
+  }
+  process.exit(1);
+}
+
+// src/commands/get-item.ts
+function stripHtml(html) {
+  let text = html;
+  text = text.replace(/<h[1-6][^>]*>(.*?)<\/h[1-6]>/gi, "\n--- $1 ---\n");
+  text = text.replace(/<br\s*\/?>/gi, "\n");
+  text = text.replace(/<\/?(p|div)>/gi, "\n");
+  text = text.replace(/<li>/gi, "\n");
+  text = text.replace(/<[^>]*>/g, "");
+  text = text.replace(/&amp;/g, "&");
+  text = text.replace(/&lt;/g, "<");
+  text = text.replace(/&gt;/g, ">");
+  text = text.replace(/&quot;/g, '"');
+  text = text.replace(/&#39;/g, "'");
+  text = text.replace(/&nbsp;/g, " ");
+  text = text.replace(/\n{3,}/g, "\n\n");
+  return text.trim();
+}
+function formatWorkItem(workItem, short) {
+  const lines = [];
+  const label = (name) => name.padEnd(13);
+  lines.push(`${label("ID:")}${workItem.id}`);
+  lines.push(`${label("Type:")}${workItem.type}`);
+  lines.push(`${label("Title:")}${workItem.title}`);
+  lines.push(`${label("State:")}${workItem.state}`);
+  lines.push(`${label("Assigned To:")}${workItem.assignedTo ?? "Unassigned"}`);
+  if (!short) {
+    lines.push(`${label("Area:")}${workItem.areaPath}`);
+    lines.push(`${label("Iteration:")}${workItem.iterationPath}`);
+  }
+  lines.push(`${label("URL:")}${workItem.url}`);
+  if (workItem.extraFields) {
+    for (const [refName, value] of Object.entries(workItem.extraFields)) {
+      const fieldLabel = refName.includes(".") ? refName.split(".").pop() : refName;
+      lines.push(`${fieldLabel.padEnd(13)}${value}`);
+    }
+  }
+  lines.push("");
+  const descriptionText = workItem.description ? stripHtml(workItem.description) : "";
+  if (short) {
+    const descLines = descriptionText.split("\n").filter((l) => l.trim() !== "");
+    const firstThree = descLines.slice(0, 3);
+    const truncated = descLines.length > 3;
+    const descSummary = firstThree.join("\n") + (truncated ? "\n..." : "");
+    lines.push(`${label("Description:")}${descSummary}`);
+  } else {
+    lines.push("Description:");
+    lines.push(descriptionText);
+  }
+  return lines.join("\n");
+}
+function createGetItemCommand() {
+  const command = new Command("get-item");
+  command.description("Retrieve an Azure DevOps work item by ID").argument("<id>", "work item ID").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--short", "show abbreviated output").option("--fields <fields>", "comma-separated additional field reference names").action(
+    async (idStr, options) => {
+      const id = parseWorkItemId(idStr);
+      validateOrgProjectPair(options);
+      let context;
+      try {
+        context = resolveContext(options);
+        const credential = await resolvePat();
+        const fieldsList = options.fields ? options.fields.split(",").map((f) => f.trim()) : loadConfig().fields;
+        const workItem = await getWorkItem(context, id, credential.pat, fieldsList);
+        const output = formatWorkItem(workItem, options.short ?? false);
+        process.stdout.write(output + "\n");
+      } catch (err) {
+        handleCommandError(err, id, context, "read");
+      }
+    }
+  );
+  return command;
+}
+
+// src/commands/clear-pat.ts
+import { Command as Command2 } from "commander";
+function createClearPatCommand() {
+  const command = new Command2("clear-pat");
+  command.description("Remove the stored Azure DevOps PAT from the credential store").action(async () => {
+    const deleted = await deletePat();
+    if (deleted) {
+      process.stdout.write("PAT removed from credential store.\n");
+    } else {
+      process.stdout.write("No stored PAT found.\n");
+    }
+  });
+  return command;
+}
+
+// src/commands/config.ts
+import { Command as Command3 } from "commander";
+import { createInterface as createInterface2 } from "readline";
+function createConfigCommand() {
+  const config = new Command3("config");
+  config.description("Manage CLI settings");
+  const set = new Command3("set");
+  set.description("Set a configuration value").argument("<key>", "setting key (org, project, fields)").argument("<value>", "setting value").option("--json", "output in JSON format").action((key, value, options) => {
+    try {
+      setConfigValue(key, value);
+      if (options.json) {
+        const output = { key, value };
+        if (key === "fields") {
+          output.value = value.split(",").map((s) => s.trim());
+        }
+        process.stdout.write(JSON.stringify(output) + "\n");
+      } else {
+        process.stdout.write(`Set "${key}" to "${value}"
+`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Error: ${message}
+`);
+      process.exit(1);
+    }
+  });
+  const get = new Command3("get");
+  get.description("Get a configuration value").argument("<key>", "setting key (org, project, fields)").option("--json", "output in JSON format").action((key, options) => {
+    try {
+      const value = getConfigValue(key);
+      if (options.json) {
+        process.stdout.write(
+          JSON.stringify({ key, value: value ?? null }) + "\n"
+        );
+      } else if (value === void 0) {
+        process.stdout.write(`Setting "${key}" is not configured.
+`);
+      } else if (Array.isArray(value)) {
+        process.stdout.write(value.join(",") + "\n");
+      } else {
+        process.stdout.write(value + "\n");
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Error: ${message}
+`);
+      process.exit(1);
+    }
+  });
+  const list = new Command3("list");
+  list.description("List all configuration values").option("--json", "output in JSON format").action((options) => {
+    const cfg = loadConfig();
+    if (options.json) {
+      process.stdout.write(JSON.stringify(cfg) + "\n");
+    } else {
+      const keyWidth = 10;
+      const valueWidth = 30;
+      for (const setting of SETTINGS) {
+        const raw = cfg[setting.key];
+        const value = raw === void 0 ? "(not set)" : Array.isArray(raw) ? raw.join(",") : raw;
+        const marker = raw === void 0 && setting.required ? " *" : "";
+        process.stdout.write(
+          `${setting.key.padEnd(keyWidth)}${String(value).padEnd(valueWidth)}${setting.description}${marker}
+`
+        );
+      }
+      const hasUnset = SETTINGS.some(
+        (s) => s.required && cfg[s.key] === void 0
+      );
+      if (hasUnset) {
+        process.stdout.write(
+          '\n* = required but not configured. Run "azdo config wizard" to set up.\n'
+        );
+      }
+    }
+  });
+  const unset = new Command3("unset");
+  unset.description("Remove a configuration value").argument("<key>", "setting key (org, project, fields)").option("--json", "output in JSON format").action((key, options) => {
+    try {
+      unsetConfigValue(key);
+      if (options.json) {
+        process.stdout.write(JSON.stringify({ key, unset: true }) + "\n");
+      } else {
+        process.stdout.write(`Unset "${key}"
+`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Error: ${message}
+`);
+      process.exit(1);
+    }
+  });
+  const wizard = new Command3("wizard");
+  wizard.description("Interactive wizard to configure all settings").action(async () => {
+    if (!process.stdin.isTTY) {
+      process.stderr.write(
+        "Error: Wizard requires an interactive terminal.\n"
+      );
+      process.exit(1);
+    }
+    const cfg = loadConfig();
+    const rl = createInterface2({
+      input: process.stdin,
+      output: process.stderr
+    });
+    const ask = (prompt) => new Promise((resolve2) => rl.question(prompt, resolve2));
+    process.stderr.write("Azure DevOps CLI - Configuration Wizard\n");
+    process.stderr.write("=======================================\n\n");
+    for (const setting of SETTINGS) {
+      const current = cfg[setting.key];
+      const currentDisplay = current === void 0 ? "" : Array.isArray(current) ? current.join(",") : current;
+      const requiredTag = setting.required ? " (required)" : " (optional)";
+      process.stderr.write(`${setting.description}${requiredTag}
+`);
+      if (setting.example) {
+        process.stderr.write(`  Example: ${setting.example}
+`);
+      }
+      const defaultHint = currentDisplay ? ` [${currentDisplay}]` : "";
+      const answer = await ask(`  ${setting.key}${defaultHint}: `);
+      const trimmed = answer.trim();
+      if (trimmed) {
+        setConfigValue(setting.key, trimmed);
+        process.stderr.write(`  -> Set "${setting.key}" to "${trimmed}"
+
+`);
+      } else if (currentDisplay) {
+        process.stderr.write(`  -> Kept "${setting.key}" as "${currentDisplay}"
+
+`);
+      } else {
+        process.stderr.write(`  -> Skipped "${setting.key}"
+
+`);
+      }
+    }
+    rl.close();
+    process.stderr.write("Configuration complete!\n");
+  });
+  config.addCommand(set);
+  config.addCommand(get);
+  config.addCommand(list);
+  config.addCommand(unset);
+  config.addCommand(wizard);
+  return config;
+}
+
+// src/commands/set-state.ts
+import { Command as Command4 } from "commander";
+function createSetStateCommand() {
+  const command = new Command4("set-state");
+  command.description("Change the state of a work item").argument("<id>", "work item ID").argument("<state>", 'target state (e.g., "Active", "Closed")').option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output result as JSON").action(
+    async (idStr, state, options) => {
+      const id = parseWorkItemId(idStr);
+      validateOrgProjectPair(options);
+      let context;
+      try {
+        context = resolveContext(options);
+        const credential = await resolvePat();
+        const operations = [
+          { op: "add", path: "/fields/System.State", value: state }
+        ];
+        const result = await updateWorkItem(context, id, credential.pat, "System.State", operations);
+        if (options.json) {
+          process.stdout.write(
+            JSON.stringify({
+              id: result.id,
+              rev: result.rev,
+              title: result.title,
+              field: result.fieldName,
+              value: result.fieldValue
+            }) + "\n"
+          );
+        } else {
+          process.stdout.write(`Updated work item ${result.id}: State -> ${state}
+`);
+        }
+      } catch (err) {
+        handleCommandError(err, id, context, "write");
+      }
+    }
+  );
+  return command;
+}
+
+// src/commands/assign.ts
+import { Command as Command5 } from "commander";
+function createAssignCommand() {
+  const command = new Command5("assign");
+  command.description("Assign a work item to a user, or unassign it").argument("<id>", "work item ID").argument("[name]", "user display name or email").option("--unassign", "clear the Assigned To field").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output result as JSON").action(
+    async (idStr, name, options) => {
+      const id = parseWorkItemId(idStr);
+      if (!name && !options.unassign) {
+        process.stderr.write(
+          "Error: Either provide a user name or use --unassign.\n"
+        );
+        process.exit(1);
+      }
+      if (name && options.unassign) {
+        process.stderr.write(
+          "Error: Cannot provide both a user name and --unassign.\n"
+        );
+        process.exit(1);
+      }
+      validateOrgProjectPair(options);
+      let context;
+      try {
+        context = resolveContext(options);
+        const credential = await resolvePat();
+        const value = options.unassign ? "" : name;
+        const operations = [
+          { op: "add", path: "/fields/System.AssignedTo", value }
+        ];
+        const result = await updateWorkItem(context, id, credential.pat, "System.AssignedTo", operations);
+        if (options.json) {
+          process.stdout.write(
+            JSON.stringify({
+              id: result.id,
+              rev: result.rev,
+              title: result.title,
+              field: result.fieldName,
+              value: result.fieldValue
+            }) + "\n"
+          );
+        } else {
+          const displayValue = options.unassign ? "(unassigned)" : name;
+          process.stdout.write(`Updated work item ${result.id}: Assigned To -> ${displayValue}
+`);
+        }
+      } catch (err) {
+        handleCommandError(err, id, context, "write");
+      }
+    }
+  );
+  return command;
+}
+
+// src/commands/set-field.ts
+import { Command as Command6 } from "commander";
+function createSetFieldCommand() {
+  const command = new Command6("set-field");
+  command.description("Set any work item field by its reference name").argument("<id>", "work item ID").argument("<field>", "field reference name (e.g., System.Title)").argument("<value>", "new value for the field").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output result as JSON").action(
+    async (idStr, field, value, options) => {
+      const id = parseWorkItemId(idStr);
+      validateOrgProjectPair(options);
+      let context;
+      try {
+        context = resolveContext(options);
+        const credential = await resolvePat();
+        const operations = [
+          { op: "add", path: `/fields/${field}`, value }
+        ];
+        const result = await updateWorkItem(context, id, credential.pat, field, operations);
+        if (options.json) {
+          process.stdout.write(
+            JSON.stringify({
+              id: result.id,
+              rev: result.rev,
+              title: result.title,
+              field: result.fieldName,
+              value: result.fieldValue
+            }) + "\n"
+          );
+        } else {
+          process.stdout.write(`Updated work item ${result.id}: ${field} -> ${value}
+`);
+        }
+      } catch (err) {
+        handleCommandError(err, id, context, "write");
+      }
+    }
+  );
+  return command;
+}
+
+// src/commands/get-md-field.ts
+import { Command as Command7 } from "commander";
+
+// src/services/md-convert.ts
+import { NodeHtmlMarkdown } from "node-html-markdown";
+
+// src/services/html-detect.ts
+var HTML_TAG_REGEX = /<\/?([a-z][a-z0-9]*)\b/gi;
+var HTML_TAGS = /* @__PURE__ */ new Set([
+  "p",
+  "br",
+  "div",
+  "span",
+  "strong",
+  "em",
+  "b",
+  "i",
+  "u",
+  "a",
+  "ul",
+  "ol",
+  "li",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "table",
+  "tr",
+  "td",
+  "th",
+  "img",
+  "pre",
+  "code"
+]);
+function isHtml(content) {
+  let match;
+  HTML_TAG_REGEX.lastIndex = 0;
+  while ((match = HTML_TAG_REGEX.exec(content)) !== null) {
+    if (HTML_TAGS.has(match[1].toLowerCase())) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// src/services/md-convert.ts
+function htmlToMarkdown(html) {
+  return NodeHtmlMarkdown.translate(html);
+}
+function toMarkdown(content) {
+  if (isHtml(content)) {
+    return htmlToMarkdown(content);
+  }
+  return content;
+}
+
+// src/commands/get-md-field.ts
+function createGetMdFieldCommand() {
+  const command = new Command7("get-md-field");
+  command.description("Get a work item field value, converting HTML to markdown").argument("<id>", "work item ID").argument("<field>", "field reference name (e.g., System.Description)").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").action(
+    async (idStr, field, options) => {
+      const id = parseWorkItemId(idStr);
+      validateOrgProjectPair(options);
+      let context;
+      try {
+        context = resolveContext(options);
+        const credential = await resolvePat();
+        const value = await getWorkItemFieldValue(context, id, credential.pat, field);
+        if (value === null) {
+          process.stdout.write("\n");
+        } else {
+          process.stdout.write(toMarkdown(value) + "\n");
+        }
+      } catch (err) {
+        handleCommandError(err, id, context, "read");
+      }
+    }
+  );
+  return command;
+}
+
+// src/commands/set-md-field.ts
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { Command as Command8 } from "commander";
+function fail(message) {
+  process.stderr.write(`Error: ${message}
+`);
+  process.exit(1);
+}
+function resolveContent(inlineContent, options) {
+  if (inlineContent && options.file) {
+    fail("Cannot specify both inline content and --file.");
+  }
+  if (options.file) {
+    return readFileContent(options.file);
+  }
+  if (inlineContent) {
+    return inlineContent;
+  }
+  return null;
+}
+function readFileContent(filePath) {
+  if (!existsSync(filePath)) {
+    fail(`File not found: ${filePath}`);
+  }
+  try {
+    return readFileSync2(filePath, "utf-8");
+  } catch {
+    fail(`Cannot read file: ${filePath}`);
+  }
+}
+async function readStdinContent() {
+  if (process.stdin.isTTY) {
+    fail(
+      "No content provided. Pass markdown content as the third argument, use --file, or pipe via stdin."
+    );
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const stdinContent = Buffer.concat(chunks).toString("utf-8").trimEnd();
+  if (!stdinContent) {
+    fail(
+      "No content provided via stdin. Pipe markdown content or use inline content or --file."
+    );
+  }
+  return stdinContent;
+}
+function formatOutput(result, options, field) {
+  if (options.json) {
+    process.stdout.write(
+      JSON.stringify({
+        id: result.id,
+        rev: result.rev,
+        field: result.fieldName,
+        value: result.fieldValue
+      }) + "\n"
+    );
+  } else {
+    process.stdout.write(`Updated work item ${result.id}: ${field} set with markdown content
+`);
+  }
+}
+function createSetMdFieldCommand() {
+  const command = new Command8("set-md-field");
+  command.description("Set a work item field with markdown content").argument("<id>", "work item ID").argument("<field>", "field reference name (e.g., System.Description)").argument("[content]", "markdown content to set").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output result as JSON").option("--file <path>", "read markdown content from file").action(
+    async (idStr, field, inlineContent, options) => {
+      const id = parseWorkItemId(idStr);
+      validateOrgProjectPair(options);
+      const content = resolveContent(inlineContent, options) ?? await readStdinContent();
+      let context;
+      try {
+        context = resolveContext(options);
+        const credential = await resolvePat();
+        const operations = [
+          { op: "add", path: `/fields/${field}`, value: content },
+          { op: "add", path: `/multilineFieldsFormat/${field}`, value: "Markdown" }
+        ];
+        const result = await updateWorkItem(context, id, credential.pat, field, operations);
+        formatOutput(result, options, field);
+      } catch (err) {
+        handleCommandError(err, id, context, "write");
+      }
+    }
+  );
+  return command;
+}
+
 // src/index.ts
-var program = new Command();
+var program = new Command9();
 program.name("azdo").description("Azure DevOps CLI tool").version(version, "-v, --version");
+program.addCommand(createGetItemCommand());
+program.addCommand(createClearPatCommand());
+program.addCommand(createConfigCommand());
+program.addCommand(createSetStateCommand());
+program.addCommand(createAssignCommand());
+program.addCommand(createSetFieldCommand());
+program.addCommand(createGetMdFieldCommand());
+program.addCommand(createSetMdFieldCommand());
 program.showHelpAfterError();
 program.parse();
 if (process.argv.length <= 2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.2.0-develop.8",
+  "version": "0.2.0",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
     "format": "prettier --check src/",
-    "test": "vitest run"
+    "test": "npm run build && vitest run"
   },
   "repository": {
     "type": "git",
@@ -22,7 +22,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "commander": "^14.0.3"
+    "@napi-rs/keyring": "^1.2.0",
+    "commander": "^14.0.3",
+    "node-html-markdown": "^2.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",