azdo-cli 0.2.4 → 0.3.0

package/README.md

@@ -12,6 +12,7 @@ Azure DevOps CLI focused on work item read/write workflows.
 - Update work item state (`set-state`)
 - Assign and unassign work items (`assign`)
 - Set any work item field by reference name (`set-field`)
+- Create or update Tasks from markdown documents (`upsert`)
 - Read rich-text fields as markdown (`get-md-field`)
 - Set rich-text fields as markdown from inline text, file, or stdin (`set-md-field`)
 - Persist org/project/default fields in local config (`config`)
@@ -47,16 +48,20 @@ azdo get-item 12345
 
 # 3) Update state
 azdo set-state 12345 "Active"
+
+# 4) Create or update a Task from markdown
+azdo upsert --content $'---\nTitle: Improve markdown import UX\nState: New\n---'
 ```
 
 ## Command Cheat Sheet
 
 | Command | Purpose | Common Flags |
 | --- | --- | --- |
-| `azdo get-item <id>` | Read a work item | `--short`, `--fields`, `--org`, `--project` |
+| `azdo get-item <id>` | Read a work item | `--short`, `--fields`, `--markdown`, `--org`, `--project` |
 | `azdo set-state <id> <state>` | Change work item state | `--json`, `--org`, `--project` |
 | `azdo assign <id> [name]` | Assign or unassign owner | `--unassign`, `--json`, `--org`, `--project` |
 | `azdo set-field <id> <field> <value>` | Update any field | `--json`, `--org`, `--project` |
+| `azdo upsert [id]` | Create or update a Task from markdown | `--content`, `--file`, `--json`, `--org`, `--project` |
 | `azdo get-md-field <id> <field>` | Get field as markdown | `--org`, `--project` |
 | `azdo set-md-field <id> <field> [content]` | Set markdown field | `--file`, `--json`, `--org`, `--project` |
 | `azdo config <subcommand>` | Manage saved settings | `set`, `get`, `list`, `unset`, `wizard`, `--json` |
@@ -75,6 +80,12 @@ azdo get-item 12345 --short
 
 # Include extra fields for this call
 azdo get-item 12345 --fields "System.Tags,Microsoft.VSTS.Common.Priority"
+
+# Convert rich text fields to markdown
+azdo get-item 12345 --markdown
+
+# Disable markdown even if config is on
+azdo get-item 12345 --no-markdown
 ```
 
 ```bash
@@ -89,6 +100,14 @@ azdo assign 12345 --unassign
 azdo set-field 12345 System.Title "Updated title"
 ```
 
+### Markdown Display
+
+The `get-item` command can convert HTML rich-text fields to readable markdown. Resolution order:
+
+1. `--markdown` / `--no-markdown` flag (highest priority)
+2. Config setting: `azdo config set markdown true`
+3. Default: off (HTML stripped to plain text)
+
 ### Markdown Field Commands
 
 ```bash
@@ -105,6 +124,83 @@ azdo set-md-field 12345 System.Description --file ./description.md
 cat description.md | azdo set-md-field 12345 System.Description
 ```
 
+## azdo upsert
+
+`azdo upsert` accepts a single markdown task document and either creates a new Azure DevOps Task or updates an existing one. Omit `[id]` to create; pass `[id]` to update that work item in place.
+
+```bash
+# Create from inline content
+azdo upsert --content $'---\nTitle: Improve markdown import UX\nAssigned To: user@example.com\nState: New\n---'
+
+# Update from a file
+azdo upsert 12345 --file ./task-import.md
+
+# JSON output
+azdo upsert 12345 --content $'---\nSystem.Title: Improve markdown import UX\n---' --json
+```
+
+The command requires exactly one source flag:
+
+- `azdo upsert [id] --content <markdown>`
+- `azdo upsert [id] --file <path>`
+
+If `--file` succeeds, the source file is deleted after the Azure DevOps write completes. If parsing, validation, or the API call fails, the file is preserved. If deletion fails after a successful write, the command still succeeds and prints a warning.
+
+### Task Document Format
+
+The document starts with YAML front matter for scalar fields, followed by optional `##` heading sections for markdown rich-text fields.
+
+```md
+---
+Title: Improve markdown import UX
+Assigned To: user@example.com
+State: New
+Tags: cli; markdown
+Priority: null
+---
+
+## Description
+
+Implement a single-command task import flow.
+
+## Acceptance Criteria
+
+- Supports create when no ID is passed
+- Supports update when an ID is passed
+- Deletes imported files only after success
+```
+
+Supported friendly field names:
+
+- `Title`
+- `Assigned To` / `assignedTo`
+- `State`
+- `Description`
+- `Acceptance Criteria` / `acceptanceCriteria`
+- `Tags`
+- `Priority`
+
+Raw Azure DevOps reference names are also accepted anywhere a field name is expected, for example `System.Title` or `Microsoft.VSTS.Common.AcceptanceCriteria`.
+
+Clear semantics:
+
+- Scalar YAML fields with `null` or an empty value are treated as clears on update.
+- Rich-text heading sections with an empty body are treated as clears on update.
+- Omitted fields are untouched on update.
+
+`--json` output shape:
+
+```json
+{
+  "action": "created",
+  "id": 12345,
+  "fields": {
+    "System.Title": "Improve markdown import UX",
+    "System.Description": "Implement a single-command task import flow."
+  }
+}
+```
+
 ### Configuration
 
 ```bash
@@ -114,6 +210,9 @@ azdo config list
 # Interactive setup
 azdo config wizard
 
+# Enable markdown display for all get-item calls
+azdo config set markdown true
+
 # Set/get/unset values
 azdo config set fields "System.Tags,Custom.Priority"
 azdo config get fields

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 
 // src/version.ts
 import { readFileSync } from "fs";
@@ -42,6 +42,19 @@ async function fetchWithErrors(url, init) {
   if (response.status === 404) throw new Error("NOT_FOUND");
   return response;
 }
+async function readResponseMessage(response) {
+  try {
+    const body = await response.json();
+    if (typeof body.message === "string" && body.message.trim() !== "") {
+      return body.message.trim();
+    }
+  } catch {
+  }
+  return null;
+}
+function normalizeFieldList(fields) {
+  return Array.from(new Set(fields.map((f) => f.trim()).filter((f) => f.length > 0)));
+}
 function buildExtraFields(fields, requested) {
   const result = {};
   for (const name of requested) {
@@ -52,16 +65,44 @@ function buildExtraFields(fields, requested) {
   }
   return Object.keys(result).length > 0 ? result : null;
 }
+function writeHeaders(pat) {
+  return {
+    ...authHeaders(pat),
+    "Content-Type": "application/json-patch+json"
+  };
+}
+async function readWriteResponse(response, errorCode) {
+  if (response.status === 400) {
+    const serverMessage = await readResponseMessage(response) ?? "Unknown error";
+    throw new Error(`${errorCode}: ${serverMessage}`);
+  }
+  if (!response.ok) {
+    throw new Error(`HTTP_${response.status}`);
+  }
+  const data = await response.json();
+  return {
+    id: data.id,
+    rev: data.rev,
+    fields: data.fields
+  };
+}
 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];
+  const normalizedExtraFields = extraFields ? normalizeFieldList(extraFields) : [];
+  if (normalizedExtraFields.length > 0) {
+    const allFields = normalizeFieldList([...DEFAULT_FIELDS, ...normalizedExtraFields]);
     url.searchParams.set("fields", allFields.join(","));
   }
   const response = await fetchWithErrors(url.toString(), { headers: authHeaders(pat) });
+  if (response.status === 400) {
+    const serverMessage = await readResponseMessage(response);
+    if (serverMessage) {
+      throw new Error(`BAD_REQUEST: ${serverMessage}`);
+    }
+  }
   if (!response.ok) {
     throw new Error(`HTTP_${response.status}`);
   }
@@ -93,7 +134,7 @@ async function getWorkItem(context, id, pat, extraFields) {
     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
+    extraFields: normalizedExtraFields.length > 0 ? buildExtraFields(data.fields, normalizedExtraFields) : null
   };
 }
 async function getWorkItemFieldValue(context, id, pat, fieldName) {
@@ -103,6 +144,12 @@ async function getWorkItemFieldValue(context, id, pat, fieldName) {
   url.searchParams.set("api-version", "7.1");
   url.searchParams.set("fields", fieldName);
   const response = await fetchWithErrors(url.toString(), { headers: authHeaders(pat) });
+  if (response.status === 400) {
+    const serverMessage = await readResponseMessage(response);
+    if (serverMessage) {
+      throw new Error(`BAD_REQUEST: ${serverMessage}`);
+    }
+  }
   if (!response.ok) {
     throw new Error(`HTTP_${response.status}`);
   }
@@ -114,40 +161,41 @@ async function getWorkItemFieldValue(context, id, pat, fieldName) {
   return typeof value === "object" ? JSON.stringify(value) : `${value}`;
 }
 async function updateWorkItem(context, id, pat, fieldName, operations) {
+  const result = await applyWorkItemPatch(context, id, pat, operations);
+  const title = result.fields["System.Title"];
+  const lastOp = operations[operations.length - 1];
+  const fieldValue = lastOp.value ?? null;
+  return {
+    id: result.id,
+    rev: result.rev,
+    title: typeof title === "string" ? title : "",
+    fieldName,
+    fieldValue
+  };
+}
+async function createWorkItem(context, workItemType, pat, operations) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/$${encodeURIComponent(workItemType)}`
+  );
+  url.searchParams.set("api-version", "7.1");
+  const response = await fetchWithErrors(url.toString(), {
+    method: "POST",
+    headers: writeHeaders(pat),
+    body: JSON.stringify(operations)
+  });
+  return readWriteResponse(response, "CREATE_REJECTED");
+}
+async function applyWorkItemPatch(context, id, pat, 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"
-    },
+    headers: writeHeaders(pat),
     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
-  };
+  return readWriteResponse(response, "UPDATE_REJECTED");
 }
 
 // src/services/auth.ts
@@ -315,6 +363,13 @@ var SETTINGS = [
     type: "string[]",
     example: "System.Tags,Custom.Priority",
     required: false
+  },
+  {
+    key: "markdown",
+    description: "Convert rich text fields to markdown on display",
+    type: "boolean",
+    example: "true",
+    required: false
   }
 ];
 var VALID_KEYS = SETTINGS.map((s) => s.key);
@@ -348,7 +403,7 @@ function saveConfig(config) {
 }
 function validateKey(key) {
   if (!VALID_KEYS.includes(key)) {
-    throw new Error(`Unknown setting key "${key}". Valid keys: org, project, fields`);
+    throw new Error(`Unknown setting key "${key}". Valid keys: ${VALID_KEYS.join(", ")}`);
   }
 }
 function getConfigValue(key) {
@@ -361,6 +416,11 @@ function setConfigValue(key, value) {
   const config = loadConfig();
   if (value === "") {
     delete config[key];
+  } else if (key === "markdown") {
+    if (value !== "true" && value !== "false") {
+      throw new Error(`Invalid value "${value}" for markdown. Must be "true" or "false".`);
+    }
+    config.markdown = value === "true";
   } else if (key === "fields") {
     config.fields = value.split(",").map((s) => s.trim());
   } else {
@@ -399,6 +459,61 @@ function resolveContext(options) {
   );
 }
 
+// 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/services/command-helpers.ts
 function parseWorkItemId(idStr) {
   const id = Number.parseInt(idStr, 10);
@@ -421,7 +536,25 @@ function validateOrgProjectPair(options) {
     process.exit(1);
   }
 }
-function handleCommandError(err, id, context, scope = "write") {
+function validateSource(options) {
+  const hasContent = options.content !== void 0;
+  const hasFile = options.file !== void 0;
+  if (hasContent === hasFile) {
+    process.stderr.write("Error: provide exactly one of --content or --file\n");
+    process.exit(1);
+  }
+}
+function formatCreateError(err) {
+  const error = err instanceof Error ? err : new Error(String(err));
+  const message = error.message.startsWith("CREATE_REJECTED:") ? error.message.replace("CREATE_REJECTED:", "").trim() : error.message;
+  const requiredMatches = [...message.matchAll(/field ['"]([^'"]+)['"]/gi)];
+  if (requiredMatches.length > 0) {
+    const fields = Array.from(new Set(requiredMatches.map((match) => match[1])));
+    return `Create rejected: ${message} (fields: ${fields.join(", ")})`;
+  }
+  return `Create rejected: ${message}`;
+}
+function handleCommandError(err, id, context, scope = "write", exit = true) {
   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)";
@@ -444,6 +577,13 @@ function handleCommandError(err, id, context, scope = "write") {
     process.stderr.write(
       "Error: Could not connect to Azure DevOps. Check your network connection.\n"
     );
+  } else if (msg.startsWith("BAD_REQUEST:")) {
+    const serverMsg = msg.replace("BAD_REQUEST: ", "");
+    process.stderr.write(`Error: Request rejected: ${serverMsg}
+`);
+  } else if (msg.startsWith("CREATE_REJECTED:")) {
+    process.stderr.write(`Error: ${formatCreateError(error)}
+`);
   } else if (msg.startsWith("UPDATE_REJECTED:")) {
     const serverMsg = msg.replace("UPDATE_REJECTED: ", "");
     process.stderr.write(`Error: Update rejected: ${serverMsg}
@@ -452,10 +592,21 @@ function handleCommandError(err, id, context, scope = "write") {
     process.stderr.write(`Error: ${msg}
 `);
   }
-  process.exit(1);
+  if (exit) {
+    process.exit(1);
+  } else {
+    process.exitCode = 1;
+  }
 }
 
 // src/commands/get-item.ts
+function parseRequestedFields(raw) {
+  if (raw === void 0) return void 0;
+  const source = Array.isArray(raw) ? raw : [raw];
+  const tokens = source.flatMap((entry) => entry.split(/[,\s]+/)).map((field) => field.trim()).filter((field) => field.length > 0);
+  if (tokens.length === 0) return void 0;
+  return Array.from(new Set(tokens));
+}
 function stripHtml(html) {
   let text = html;
   text = text.replace(/<h[1-6][^>]*>(.*?)<\/h[1-6]>/gi, "\n--- $1 ---\n");
@@ -472,7 +623,24 @@ function stripHtml(html) {
   text = text.replace(/\n{3,}/g, "\n\n");
   return text.trim();
 }
-function formatWorkItem(workItem, short) {
+function convertRichText(html, markdown) {
+  if (!html) return "";
+  return markdown ? toMarkdown(html) : stripHtml(html);
+}
+function formatExtraFields(extraFields, markdown) {
+  return Object.entries(extraFields).map(([refName, value]) => {
+    const fieldLabel = refName.includes(".") ? refName.split(".").pop() : refName;
+    const displayValue = markdown ? toMarkdown(value) : value;
+    return `${fieldLabel.padEnd(13)}${displayValue}`;
+  });
+}
+function summarizeDescription(text, label) {
+  const descLines = text.split("\n").filter((l) => l.trim() !== "");
+  const firstThree = descLines.slice(0, 3);
+  const suffix = descLines.length > 3 ? "\n..." : "";
+  return [`${label("Description:")}${firstThree.join("\n")}${suffix}`];
+}
+function formatWorkItem(workItem, short, markdown = false) {
   const lines = [];
   const label = (name) => name.padEnd(13);
   lines.push(`${label("ID:")}${workItem.id}`);
@@ -486,19 +654,12 @@ function formatWorkItem(workItem, short) {
   }
   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(...formatExtraFields(workItem.extraFields, markdown));
   }
   lines.push("");
-  const descriptionText = workItem.description ? stripHtml(workItem.description) : "";
+  const descriptionText = convertRichText(workItem.description, markdown);
   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}`);
+    lines.push(...summarizeDescription(descriptionText, label));
   } else {
     lines.push("Description:");
     lines.push(descriptionText);
@@ -507,7 +668,7 @@ function formatWorkItem(workItem, short) {
 }
 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(
+  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").option("--markdown", "convert rich text fields to markdown").action(
     async (idStr, options) => {
       const id = parseWorkItemId(idStr);
       validateOrgProjectPair(options);
@@ -515,12 +676,13 @@ function createGetItemCommand() {
       try {
         context = resolveContext(options);
         const credential = await resolvePat();
-        const fieldsList = options.fields ? options.fields.split(",").map((f) => f.trim()) : loadConfig().fields;
+        const fieldsList = options.fields !== void 0 ? parseRequestedFields(options.fields) : parseRequestedFields(loadConfig().fields);
         const workItem = await getWorkItem(context, id, credential.pat, fieldsList);
-        const output = formatWorkItem(workItem, options.short ?? false);
+        const markdownEnabled = options.markdown ?? loadConfig().markdown ?? false;
+        const output = formatWorkItem(workItem, options.short ?? false, markdownEnabled);
         process.stdout.write(output + "\n");
       } catch (err) {
-        handleCommandError(err, id, context, "read");
+        handleCommandError(err, id, context, "read", false);
       }
     }
   );
@@ -821,63 +983,6 @@ function createSetFieldCommand() {
 
 // 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(
@@ -990,8 +1095,313 @@ function createSetMdFieldCommand() {
   return command;
 }
 
+// src/commands/upsert.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3, unlinkSync } from "fs";
+import { Command as Command9 } from "commander";
+
+// src/services/task-document.ts
+var FIELD_ALIASES = /* @__PURE__ */ new Map([
+  ["title", "System.Title"],
+  ["assignedto", "System.AssignedTo"],
+  ["assigned to", "System.AssignedTo"],
+  ["state", "System.State"],
+  ["description", "System.Description"],
+  ["acceptancecriteria", "Microsoft.VSTS.Common.AcceptanceCriteria"],
+  ["acceptance criteria", "Microsoft.VSTS.Common.AcceptanceCriteria"],
+  ["tags", "System.Tags"],
+  ["priority", "Microsoft.VSTS.Common.Priority"]
+]);
+var RICH_TEXT_FIELDS = /* @__PURE__ */ new Set([
+  "System.Description",
+  "Microsoft.VSTS.Common.AcceptanceCriteria"
+]);
+var REFERENCE_NAME_PATTERN = /^[A-Z][A-Za-z0-9]*(\.[A-Za-z0-9]+)+$/;
+function normalizeAlias(name) {
+  return name.trim().replaceAll(/\s+/g, " ").toLowerCase();
+}
+function parseScalarValue(rawValue, fieldName) {
+  if (rawValue === void 0) {
+    throw new Error(`Malformed YAML front matter: missing value for "${fieldName}"`);
+  }
+  const trimmed = rawValue.trim();
+  if (trimmed === "" || trimmed === "null" || trimmed === "~") {
+    return null;
+  }
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  if (/^[[{]|^[>|]-?$/.test(trimmed)) {
+    throw new Error(`Malformed YAML front matter: unsupported value for "${fieldName}"`);
+  }
+  return trimmed;
+}
+function parseFrontMatter(content) {
+  if (!content.startsWith("---")) {
+    return { frontMatter: "", remainder: content };
+  }
+  const frontMatterPattern = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+  const match = frontMatterPattern.exec(content);
+  if (!match) {
+    throw new Error('Malformed YAML front matter: missing closing "---"');
+  }
+  return {
+    frontMatter: match[1],
+    remainder: content.slice(match[0].length)
+  };
+}
+function assertKnownField(name, kind) {
+  const resolved = resolveFieldName(name);
+  if (!resolved) {
+    const prefix = kind === "rich-text" ? "Unknown rich-text field" : "Unknown field";
+    throw new Error(`${prefix}: ${name}`);
+  }
+  if (kind === "rich-text" && !RICH_TEXT_FIELDS.has(resolved)) {
+    throw new Error(`Unknown rich-text field: ${name}`);
+  }
+  return resolved;
+}
+function pushField(fields, seen, refName, value, kind) {
+  if (seen.has(refName)) {
+    throw new Error(`Duplicate field: ${refName}`);
+  }
+  seen.add(refName);
+  fields.push({
+    refName,
+    value,
+    op: value === null ? "clear" : "set",
+    kind
+  });
+}
+function parseScalarFields(frontMatter, fields, seen) {
+  if (frontMatter.trim() === "") {
+    return;
+  }
+  for (const rawLine of frontMatter.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "") {
+      continue;
+    }
+    const separatorIndex = rawLine.indexOf(":");
+    if (separatorIndex <= 0) {
+      throw new Error(`Malformed YAML front matter: ${rawLine.trim()}`);
+    }
+    const rawName = rawLine.slice(0, separatorIndex).trim();
+    const rawValue = rawLine.slice(separatorIndex + 1);
+    const refName = assertKnownField(rawName, "scalar");
+    const value = parseScalarValue(rawValue, rawName);
+    pushField(fields, seen, refName, value, "scalar");
+  }
+}
+function parseRichTextSections(content, fields, seen) {
+  const normalizedContent = content.replaceAll("\r\n", "\n");
+  const lines = normalizedContent.split("\n");
+  const headings = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.startsWith("##")) {
+      continue;
+    }
+    const headingBody = line.slice(2);
+    if (headingBody.trim() === "" || !headingBody.startsWith(" ") && !headingBody.startsWith("	")) {
+      continue;
+    }
+    headings.push({
+      lineIndex: index,
+      rawName: headingBody.trim()
+    });
+  }
+  if (headings.length === 0) {
+    return;
+  }
+  for (let index = 0; index < headings[0].lineIndex; index += 1) {
+    if (lines[index].trim() !== "") {
+      throw new Error("Unexpected content before the first markdown heading section");
+    }
+  }
+  for (let index = 0; index < headings.length; index += 1) {
+    const { lineIndex, rawName } = headings[index];
+    const refName = assertKnownField(rawName, "rich-text");
+    const bodyStart = lineIndex + 1;
+    const bodyEnd = index + 1 < headings.length ? headings[index + 1].lineIndex : lines.length;
+    const rawBody = lines.slice(bodyStart, bodyEnd).join("\n");
+    const value = rawBody.trim() === "" ? null : rawBody.trimEnd();
+    pushField(fields, seen, refName, value, "rich-text");
+  }
+}
+function resolveFieldName(name) {
+  const trimmed = name.trim();
+  if (trimmed === "") {
+    return null;
+  }
+  const alias = FIELD_ALIASES.get(normalizeAlias(trimmed));
+  if (alias) {
+    return alias;
+  }
+  return REFERENCE_NAME_PATTERN.test(trimmed) ? trimmed : null;
+}
+function parseTaskDocument(content) {
+  const { frontMatter, remainder } = parseFrontMatter(content);
+  const fields = [];
+  const seen = /* @__PURE__ */ new Set();
+  parseScalarFields(frontMatter, fields, seen);
+  parseRichTextSections(remainder, fields, seen);
+  return { fields };
+}
+
+// src/commands/upsert.ts
+function fail2(message) {
+  process.stderr.write(`Error: ${message}
+`);
+  process.exit(1);
+}
+function loadSourceContent(options) {
+  validateSource(options);
+  if (options.content !== void 0) {
+    return { content: options.content };
+  }
+  const filePath = options.file;
+  if (!existsSync2(filePath)) {
+    fail2(`File not found: ${filePath}`);
+  }
+  try {
+    return {
+      content: readFileSync3(filePath, "utf-8"),
+      sourceFile: filePath
+    };
+  } catch {
+    fail2(`Cannot read file: ${filePath}`);
+  }
+}
+function toPatchOperations(fields, action) {
+  const operations = [];
+  for (const field of fields) {
+    if (field.op === "clear") {
+      if (action === "updated") {
+        operations.push({ op: "remove", path: `/fields/${field.refName}` });
+      }
+      continue;
+    }
+    operations.push({ op: "add", path: `/fields/${field.refName}`, value: field.value ?? "" });
+    if (field.kind === "rich-text") {
+      operations.push({
+        op: "add",
+        path: `/multilineFieldsFormat/${field.refName}`,
+        value: "Markdown"
+      });
+    }
+  }
+  return operations;
+}
+function buildAppliedFields(fields) {
+  const applied = {};
+  for (const field of fields) {
+    applied[field.refName] = field.value;
+  }
+  return applied;
+}
+function ensureTitleForCreate(fields) {
+  const titleField = fields.find((field) => field.refName === "System.Title");
+  if (!titleField || titleField.op === "clear" || titleField.value === null || titleField.value.trim() === "") {
+    fail2("Title is required when creating a task.");
+  }
+}
+function writeSuccess(result, options) {
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result)}
+`);
+    return;
+  }
+  const verb = result.action === "created" ? "Created" : "Updated";
+  const fields = Object.keys(result.fields).join(", ");
+  const suffix = fields ? ` (${fields})` : "";
+  process.stdout.write(`${verb} task #${result.id}${suffix}
+`);
+}
+function cleanupSourceFile(sourceFile) {
+  if (!sourceFile) {
+    return;
+  }
+  try {
+    unlinkSync(sourceFile);
+  } catch {
+    process.stderr.write(`Warning: upsert succeeded but could not delete source file: ${sourceFile}
+`);
+  }
+}
+function buildUpsertResult(action, writeResult, fields) {
+  const appliedFields = buildAppliedFields(fields);
+  return {
+    action,
+    id: writeResult.id,
+    fields: appliedFields
+  };
+}
+function isUpdateWriteError(err) {
+  return err.message === "AUTH_FAILED" || err.message === "PERMISSION_DENIED" || err.message === "NOT_FOUND" || err.message === "NETWORK_ERROR" || err.message.startsWith("BAD_REQUEST:") || err.message.startsWith("UPDATE_REJECTED:");
+}
+function isCreateWriteError(err) {
+  return err.message === "AUTH_FAILED" || err.message === "PERMISSION_DENIED" || err.message === "NETWORK_ERROR" || err.message.startsWith("BAD_REQUEST:") || err.message.startsWith("HTTP_");
+}
+function handleUpsertError(err, id, context) {
+  if (!(err instanceof Error)) {
+    process.stderr.write(`Error: ${String(err)}
+`);
+    process.exit(1);
+  }
+  if (id === void 0 && err.message.startsWith("CREATE_REJECTED:")) {
+    process.stderr.write(`Error: ${formatCreateError(err)}
+`);
+    process.exit(1);
+  }
+  if (id !== void 0 && isUpdateWriteError(err)) {
+    handleCommandError(err, id, context, "write");
+    return;
+  }
+  if (id === void 0 && isCreateWriteError(err)) {
+    handleCommandError(err, 0, context, "write");
+    return;
+  }
+  process.stderr.write(`Error: ${err.message}
+`);
+  process.exit(1);
+}
+function createUpsertCommand() {
+  const command = new Command9("upsert");
+  command.description("Create or update a Task from a markdown document").argument("[id]", "work item ID to update; omit to create a new Task").option("--content <markdown>", "task document content").option("--file <path>", "read task document from file").option("--json", "output result as JSON").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").action(async (idStr, options) => {
+    validateOrgProjectPair(options);
+    const id = idStr === void 0 ? void 0 : parseWorkItemId(idStr);
+    const { content, sourceFile } = loadSourceContent(options);
+    let context;
+    try {
+      context = resolveContext(options);
+      const document = parseTaskDocument(content);
+      const action = id === void 0 ? "created" : "updated";
+      if (action === "created") {
+        ensureTitleForCreate(document.fields);
+      }
+      const operations = toPatchOperations(document.fields, action);
+      const credential = await resolvePat();
+      let writeResult;
+      if (action === "created") {
+        writeResult = await createWorkItem(context, "Task", credential.pat, operations);
+      } else {
+        if (id === void 0) {
+          fail2("Work item ID is required for updates.");
+        }
+        writeResult = await applyWorkItemPatch(context, id, credential.pat, operations);
+      }
+      const result = buildUpsertResult(action, writeResult, document.fields);
+      writeSuccess(result, options);
+      cleanupSourceFile(sourceFile);
+    } catch (err) {
+      handleUpsertError(err, id, context);
+    }
+  });
+  return command;
+}
+
 // src/index.ts
-var program = new Command9();
+var program = new Command10();
 program.name("azdo").description("Azure DevOps CLI tool").version(version, "-v, --version");
 program.addCommand(createGetItemCommand());
 program.addCommand(createClearPatCommand());
@@ -1001,6 +1411,7 @@ program.addCommand(createAssignCommand());
 program.addCommand(createSetFieldCommand());
 program.addCommand(createGetMdFieldCommand());
 program.addCommand(createSetMdFieldCommand());
+program.addCommand(createUpsertCommand());
 program.showHelpAfterError();
 program.parse();
 if (process.argv.length <= 2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {
@@ -28,12 +28,12 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.3.3",
-    "eslint": "^10.0.2",
+    "@types/node": "^25.5.0",
+    "eslint": "^10.1.0",
     "prettier": "^3.8.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1",
-    "vitest": "^4.0.18"
+    "typescript-eslint": "^8.57.2",
+    "vitest": "^4.1.2"
   }
 }